portersky/xone_macos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README with current project status

Browse Source 
Check off investigation items resolved on hardware (firmware load,
EFUSE, radio init, beacon, pairing, reconnect), align build commands
with AGENTS.md, add xone_cli and scripts to the layout, replace the
completed first-steps list with a current status section, and drop
em dashes per the documentation conventions.

Co-Authored-By: qwen3.8-27b@q3_k_xl: updated README with current status
This commit is contained in:
portersky
2026-08-29 14:21:18 +02:00
parent 418e177b5c
commit 51192023aa
1 changed files with 93 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+93 -81
View File
@@ -1,4 +1,4 @@
# Xbox Wireless Dongle — macOS Port
# Xbox Wireless Dongle: macOS Port
User-space macOS app for the Xbox Wireless Dongle (MediaTek MT76xx).
Ports the Linux kernel driver [`xone/`](../xone/) to macOS.
@@ -14,18 +14,22 @@ Swift is only supported by the **Ninja** and **Xcode** generators in CMake,
so configure with one of them explicitly:
```sh
cmake -S . -B build -G Ninja -DBUILD_TESTING=ON
cmake --build build
cmake -S . -B build -GNinja -DBUILD_TESTING=ON
ninja -C build
./build/xone_app
cmake --build build --target check # run the test suite
ninja -C build check # build and run the test suite
```
Layout (mirrors `../refix/`):
- `deps/` — CMake modules: `Platform.cmake`, `Flags.cmake`, `Sanitizers.cmake`, `FindUnity.cmake`
- `src/{usb,mt76,gip,auth,hid}` — C++ protocol stack (ported from `medusalix/xone`)
- `src/app/` — Swift app entry point + C ABI bridge (`include/app/xone_api.h`)
- `tests/` — Unity test suite (`BUILD_TESTING=ON`)
- `deps/`: CMake modules: `Platform.cmake`, `Flags.cmake`, `Sanitizers.cmake`,
`FindUnity.cmake`
- `src/{usb,mt76,gip,auth,hid}`: C++ protocol stack (ported from
`medusalix/xone`)
- `src/app/`: Swift app entry point + C ABI bridge (`include/app/xone_api.h`)
- `src/cli/`: C++ CLI (`xone_cli`) for manual protocol sequences
- `scripts/`: `download-firmware.sh` (port of the upstream firmware fetcher)
- `tests/`: Unity test suite (`BUILD_TESTING=ON`)
---
@@ -36,123 +40,124 @@ Strike through or check off as each is resolved.
### 1. IOKit USB Access
- [x] **IOUSBLib vs IOUSBFamily** — Resolved: the SDK exposes only the
- [x] **IOUSBLib vs IOUSBFamily**: Resolved: the SDK exposes only the
struct-based `IOUSBDeviceInterface` / `IOUSBInterfaceInterface` (v197/v190)
via `IOCreatePlugInInterfaceForService()` + `QueryInterface`. Implemented in
`src/usb/usb_transport.cpp`.
- [x] **USB device matching** — Class match on `IOUSBDevice` plus a user-space
- [x] **USB device matching**: Class match on `IOUSBDevice` plus a user-space
VID/PID filter on the `idVendor`/`idProduct` properties (numeric registry
matching proved unreliable). Verified with a physical dongle (PID 0x02E6).
- [x] **Interface claiming** — All interfaces are opened and pipes mapped by
- [x] **Interface claiming**: All interfaces are opened and pipes mapped by
endpoint number + direction (EP 0x04 IN/OUT, EP 0x05 IN). Verified: opens
cleanly with no driver conflict.
- [ ] **Async transfer latency** — `ReadPipeAsync` pump implemented (4
outstanding reads per IN pipe, resubmission in the completion handler).
Latency tuning deferred to Phase 3 firmware load.
- [x] **Device reconnect handling** — `kIOTerminatedNotification` with a PID
filter fires on unplug and chip re-enumeration. Reliability pending hardware.
- [x] **Async transfer latency**: Resolved: the `ReadPipeAsync` pump (4
outstanding reads per IN pipe, resubmission in the completion handler)
streams live controller input with no drops at game-report rates.
- [x] **Device reconnect handling**: Resolved: `kIOTerminatedNotification`
with a PID filter fires on unplug and chip re-enumeration. Verified
across firmware-load resets and repeated unplug/replug cycles.
### 2. Firmware Loading
- [ ] **Firmware binary availability** — Run `../xone/install/firmware.sh` (or
ported `scripts/download-firmware.sh`) to confirm the Windows Update CAB URLs
still work and firmware hashes match.
- [ ] **Firmware load sequence** — Trace the Linux `xone_mt76_load_firmware()`
flow: control request to enter firmware mode → bulk transfer in 0x3800-byte
chunks → MCU completion poll → chip reset. Map each step to IOKit equivalents.
- [ ] **Post-firmware reconnect** — After firmware loads, the chip resets and
re-enumerates. Verify the USB device reappears with the same VID/PID and can
be re-opened.
- [x] **Firmware binary availability**: Resolved: `scripts/download-firmware.sh`
(port of `../xone/install/firmware.sh`) fetches the Windows Update CAB
images and the hashes match the Linux driver. Images land in `firmware/`.
- [x] **Firmware load sequence**: Resolved: ported to `src/mt76/mt76.cpp`
(control request to firmware mode, bulk transfer in 0x3800-byte chunks,
MCU completion poll, chip reset). Verified on hardware: FCE shows the
firmware running after load.
- [x] **Post-firmware reconnect**: Resolved: the chip re-enumerates with the
same VID/PID; the app and CLI close, wait, and reopen the device. The
full sequence runs end-to-end.
### 3. MT76 Register Access
- [ ] **Vendor request format** — The Linux driver uses `usb_control_msg()` with
vendor requests (bRequest 0x84/0x86 for register R/W). Confirm the exact
`bmRequestType`, `bRequest`, `wValue`, `wIndex`, `wLength` values work via
`IOUSBDeviceInterface->DeviceRequest()`.
- [ ] **Register timing** — Some register writes require delays between them.
Test if `usleep()` in user-space provides sufficient precision, or if
`clock_nanosleep()` is needed.
- [ ] **EFUSE read** — Verify the EFUSE read sequence returns valid MAC address,
chip ID, and TX power calibration data on macOS.
- [x] **Vendor request format**: Resolved: the Linux values work unchanged via
`IOUSBDeviceInterface->DeviceRequest()` (bRequest 0x84/0x86 for register
R/W). All radio init traffic uses this path.
- [x] **Register timing**: Resolved: `usleep()` / `clock_nanosleep()` in
user-space are sufficient; radio init and channel evaluation complete
reliably.
- [x] **EFUSE read**: Resolved: the EFUSE sequence returns valid MAC address,
chip ID, and TX power calibration data on macOS (`xone_cli info`).
### 4. 802.11 Frame Handling
- [ ] **Beacon construction** — The Linux driver builds raw 802.11 beacon frames
with a Microsoft OUI (00:50:f2) information element. Verify the frame format
matches what the MT76 chip expects (may include chip-specific headers before
the 802.11 frame).
- [ ] **Frame encapsulation** — The MT76 chip wraps 802.11 frames in a
proprietary header. Reverse-engineer or confirm the header format from Linux
driver source (`xone_mt76_tx()` / `xone_mt76_rx()`).
- [ ] **QoS data frames** — Controller input/output uses 802.11 QoS data frames.
Verify the frame construction and AES-CCMP encryption/decryption flow.
- [x] **Beacon construction**: Resolved: beacons with the Microsoft OUI
(00:50:f2) information element transmit correctly, including the chip
header before the 802.11 frame. Controllers hear them and associate.
- [x] **Frame encapsulation**: Resolved: TX/RX chip headers handled per the
Linux driver (`send_wlan` / `process_wlan`). Association, pairing, and
encryption-enable management frames verified against hardware.
- [ ] **QoS data frames**: RX path verified: controller input QoS frames are
decrypted, fed to the GIP layer, and shown live in the app. Host to
controller TX (rumble, LED over the data path) is not implemented yet.
### 5. AES-CCMP Encryption
- [x] **Crypto backend choice** — CommonCrypto (SHA-256/HMAC), Security.framework
- [x] **Crypto backend choice**: CommonCrypto (SHA-256/HMAC), Security.framework
(RSA PKCS#1), and a self-contained P-256 ECDH (no public macOS C API for EC
key agreement). Implemented in `src/auth/crypto.cpp`.
- [x] **CCMP mode implementation** — Not needed on the host: AES-CCMP runs on the
- [x] **CCMP mode implementation**: Not needed on the host: AES-CCMP runs on the
MT76 chip; the host only installs keys via WCID registers
(`xone_mt76_set_client_key`).
- [x] **ECDH key exchange** — P-256 implemented and validated against
- [x] **ECDH key exchange**: P-256 implemented and validated against
OpenSSL-derived test vectors (`tests/test_crypto.cpp`).
### 6. Virtual HID Gamepad
- [ ] **HID Proxy Driver feasibility** — Research Apple's [HID Proxy
- [ ] **HID Proxy Driver feasibility**: Research Apple's [HID Proxy
Driver](https://developer.apple.com/documentation/coreaudio/hid_proxy_driver)
(DriverKit). Can we create a virtual Xbox controller that games recognize
natively?
- [ ] **IOHIDDevice user-space alternative** — Can we create a virtual HID
- [ ] **IOHIDDevice user-space alternative**: Can we create a virtual HID
device entirely in user-space? Test with `IOHIDManager` and see if games
(Steam, Game Center) recognize it.
- [ ] **HID report descriptor** — Write an Xbox 360/One-compatible HID report
- [ ] **HID report descriptor**: Write an Xbox 360/One-compatible HID report
descriptor. Test with existing Xbox controller (via Bluetooth) to capture the
exact report format macOS expects.
- [ ] **Force feedback** — Can the virtual HID device receive rumble commands
- [ ] **Force feedback**: Can the virtual HID device receive rumble commands
from games and relay them to the controller via GIP?
### 7. Core Audio (Headset Support)
- [ ] **Audio Unit setup** — Test creating an `AURenderCallback` /
- [ ] **Audio Unit setup**: Test creating an `AURenderCallback` /
`AUOutputUnit` for headset playback and `AURecordingCallback` / `AUInputUnit`
for mic input.
- [ ] **Latency requirements** — The GIP protocol sends audio in 8ms intervals.
- [ ] **Latency requirements**: The GIP protocol sends audio in 8ms intervals.
Can Core Audio maintain this latency without glitches?
- [ ] **Format negotiation** — The headset negotiates audio format (sample rate,
- [ ] **Format negotiation**: The headset negotiates audio format (sample rate,
channels) via GIP. Map GIP audio formats to Core Audio
`AudioStreamBasicDescription`.
### 8. Build System
- [ ] **CMake vs Xcode** — CMake is simpler for the C library portions, but
Xcode is needed for the macOS app bundle and any DriverKit extension. Decide
on primary build system.
- [ ] **Minimum macOS version** — Target 12.0 (Monterey) for modern
- [x] **CMake vs Xcode**: Resolved: CMake with the Ninja generator compiles
both the C++ stack and the Swift app (see Building). An Xcode project is
only needed later for a DriverKit extension, if Phase 4 goes that route.
- [ ] **Minimum macOS version**: Target 12.0 (Monterey) for modern
IOKit/DriverKit. Verify all APIs are available.
- [ ] **Code signing** — IOKit USB access may require specific entitlements
(`com.apple.kpi.iokit`, `com.apple.security.device.usb`). DriverKit requires
notarization. Plan for development vs distribution signing.
- [ ] **Code signing**: Development builds run unsigned on the local machine
with no entitlements needed for IOKit USB access. DriverKit
notarization and distribution signing deferred to the HID phase.
### 9. Regulatory / Legal
- [ ] **5GHz channel restrictions** — macOS enforces regulatory domain for 5GHz.
The dongle may try to use channels blocked in the current region. May need to
limit to 2.4GHz only or find a way to override.
- [ ] **Firmware license** — The firmware binaries are from Microsoft Windows
- [ ] **5GHz channel restrictions**: Channel evaluation picks a working
channel and pairing is verified on hardware; no regulatory failures seen
so far. Regional edge cases (blocked channels) remain untested.
- [ ] **Firmware license**: The firmware binaries are from Microsoft Windows
Update. Confirm they can be redistributed with the macOS port (the Linux
driver includes them with a disclaimer).
### 10. Testing Hardware
- [ ] **Dongle** — Xbox Wireless Dongle (PID 0x02FE preferred, 0x02E6 also
works)
- [ ] **Controller** — Xbox One or Series X|S controller (for pairing and input
testing)
- [ ] **Headset** — Xbox Wireless Headset (optional, for audio testing)
- [ ] **macOS machine** — Intel or Apple Silicon (test both if possible, IOKit
- [x] **Dongle**: Xbox Wireless Dongle (PID 0x02FE preferred, 0x02E6 also
works). In hand: PID 0x02E6 verified end-to-end.
- [x] **Controller**: Xbox One or Series X|S controller (for pairing and input
testing). In hand: pairing and live input verified.
- [ ] **Headset**: Xbox Wireless Headset (optional, for audio testing)
- [ ] **macOS machine**: Intel or Apple Silicon (test both if possible, IOKit
may differ)
---
@@ -166,7 +171,7 @@ Strike through or check off as each is resolved.
| `usb_submit_urb()` | `ReadPipeAsync()` + `CFRunLoopSource` | ✅ Done (reader thread) |
| `kzalloc` / `kfree` | `malloc` / `free` | ✅ Straightforward |
| `spin_lock_irqsave` | `std::mutex` / `std::condition_variable` | ✅ Done (`usb_transport.cpp`) |
| `msleep` / `mdelay` | `usleep()` / `clock_nanosleep()` | ☐ Test timing |
| `msleep` / `mdelay` | `usleep()` / `clock_nanosleep()` | ✅ Done (radio init, channel eval) |
| `crypto_shash_*` | CommonCrypto / Security.framework | ✅ Done (`auth/crypto.cpp`) |
| `input_register_device()` | HID Proxy Driver / IOHIDSystem | ☐ Investigate |
| `snd_pcm_*` | Core Audio (Audio Units) | ☐ Investigate |
@@ -177,14 +182,21 @@ Strike through or check off as each is resolved.
---
## First Steps on macOS
## Current Status
1. Plug in the dongle, run `system_profiler SPUSBDataType` — confirm it's
detected
2. Check `log show --predicate 'subsystem == "com.apple.iokit"'` — see if macOS
loads any driver
3. Open the device with `transport::probe()` and confirm endpoint enumeration
(EP 0x04 IN/OUT, EP 0x05 IN)
4. Try a vendor control request (register read) to verify USB communication
works
5. Attempt firmware load with the binary from `firmware/` directory
Working end-to-end on hardware:
- Dongle probe/open, async read pump, vendor register R/W
- Firmware download (`scripts/download-firmware.sh`) and load
- EFUSE read, radio init, channel evaluation, beacon TX
- Pairing mode, controller association, GIP handshake + auth
- Live controller input (buttons, sticks, triggers) in the Swift app
Not done yet: host to controller TX over the data path (rumble, LED),
virtual HID gamepad (Phase 4), headset audio (Phase 5).
`xone_cli` exercises the stack manually in a single dongle session:
```sh
./build/xone_cli info firmware firmware/xow_dongle.bin radio-init pair
```