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:
@@ -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)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user