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