diff --git a/PLAN.md b/PLAN.md index 5dc2875..058ded4 100644 --- a/PLAN.md +++ b/PLAN.md @@ -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)