docs: phase 4 uses userspace IOHIDUserDevice, not DriverKit

macOS has a user-space virtual HID device API (IOHIDUserDevice,
available since 10.15). No DriverKit extension is needed: the app
creates one virtual device per controller with our report descriptor.

Development works with SIP disabled and no Apple account (verified on
macOS 15.7 that creation fails with SIP enabled; dji-fpv3 and
ControlLab document the SIP-disabled dev workflow). Distribution with
SIP enabled requires the com.apple.developer.hid.virtual.device
entitlement from a paid Developer Program membership.

Co-Authored-By: qwen3.8-27b@q3_k_xl: researched virtual HID options
This commit is contained in:
portersky
2026-08-29 15:49:30 +02:00
parent fafca4c265
commit 176a563400
+19 -10
View File
@@ -51,8 +51,10 @@ and exposes connected controllers as HID gamepads.
live input monitor, battery level, and a rumble test button. live input monitor, battery level, and a rumble test button.
- Phase 4 (HID) started: standard Xbox One report layout, HID report - Phase 4 (HID) started: standard Xbox One report layout, HID report
descriptor, and GIP-to-report mapping implemented in `src/hid/` and unit descriptor, and GIP-to-report mapping implemented in `src/hid/` and unit
tested. Remaining: present the reports as a virtual device via a DriverKit tested. Remaining: present the reports via the user-space
extension (needs a Developer ID with the DriverKit entitlement). `IOHIDUserDevice` API (no DriverKit needed; development requires SIP
disabled, distribution requires the `com.apple.developer.hid.virtual.device`
entitlement).
The dongle LED is driven at chip level for pairing and client lifecycle. The dongle LED is driven at chip level for pairing and client lifecycle.
Phase 3 is complete. Next: Phase 4 (virtual HID gamepad) and Phase 5 (app Phase 3 is complete. Next: Phase 4 (virtual HID gamepad) and Phase 5 (app
@@ -162,12 +164,19 @@ Extract the protocol logic from Linux kernel code into standalone C.
**src/hid/** **src/hid/**
- Expose controller as macOS HID device so games work natively - Expose controller as macOS HID device so games work natively
- Options: - Presentation mechanism: `IOHIDUserDevice` (IOKit, user-space virtual HID
- **HID Proxy Driver (DriverKit)**: Maps USB device to virtual HID. device API, available since macOS 10.15). No DriverKit needed: the app
Minimal kernel code. Preferred approach. creates one virtual device per controller with our report descriptor,
- **IOHIDSystem user-space**: Create virtual HID device entirely in pushes input reports from GIP state, and receives output reports for
user-space. May not work for all games. rumble relay.
- **Gamepad wrapper**: Lower-level, translate input events to HID reports. - Signing/entitlements:
- Development (SIP disabled): `IOHIDUserDeviceCreateWithProperties`
works without any Apple account. Verified on macOS 15.7: with SIP on,
creation fails; open-source projects (dji-fpv3, ControlLab) document
the SIP-disabled dev workflow.
- Distribution (SIP enabled): requires the
`com.apple.developer.hid.virtual.device` entitlement in a
provisioning profile (paid Apple Developer Program membership).
- Map Xbox controller buttons/sticks/triggers to standard Xbox One HID - Map Xbox controller buttons/sticks/triggers to standard Xbox One HID
report descriptor: done. `hid/hid_report.hpp` defines the 64-byte report descriptor: done. `hid/hid_report.hpp` defines the 64-byte
input/output report layout and the HID report descriptor; GIP state maps input/output report layout and the HID report descriptor; GIP state maps
@@ -176,8 +185,8 @@ Extract the protocol logic from Linux kernel code into standalone C.
(Phase 3); output-report parsing for the relay is implemented in (Phase 3); output-report parsing for the relay is implemented in
`parse_output_report()`. `parse_output_report()`.
- Battery status reporting - Battery status reporting
- Remaining: present the reports as a virtual device (DriverKit extension). - Remaining: implement the `IOHIDUserDevice` wrapper in `src/hid/`, wire it
Needs a Developer ID with the DriverKit entitlement to build and load. into the app, verify on hardware with SIP disabled.
### Phase 5: macOS App (new) ### Phase 5: macOS App (new)