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.
- Phase 4 (HID) started: standard Xbox One report layout, HID report
descriptor, and GIP-to-report mapping implemented in `src/hid/` and unit
tested. Remaining: present the reports as a virtual device via a DriverKit
extension (needs a Developer ID with the DriverKit entitlement).
tested. Remaining: present the reports via the user-space
`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.
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/**
- Expose controller as macOS HID device so games work natively
- Options:
- **HID Proxy Driver (DriverKit)**: Maps USB device to virtual HID.
Minimal kernel code. Preferred approach.
- **IOHIDSystem user-space**: Create virtual HID device entirely in
user-space. May not work for all games.
- **Gamepad wrapper**: Lower-level, translate input events to HID reports.
- Presentation mechanism: `IOHIDUserDevice` (IOKit, user-space virtual HID
device API, available since macOS 10.15). No DriverKit needed: the app
creates one virtual device per controller with our report descriptor,
pushes input reports from GIP state, and receives output reports for
rumble relay.
- 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
report descriptor: done. `hid/hid_report.hpp` defines the 64-byte
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
`parse_output_report()`.
- Battery status reporting
- Remaining: present the reports as a virtual device (DriverKit extension).
Needs a Developer ID with the DriverKit entitlement to build and load.
- Remaining: implement the `IOHIDUserDevice` wrapper in `src/hid/`, wire it
into the app, verify on hardware with SIP disabled.
### Phase 5: macOS App (new)