GameSir home-LED agent-state feedback not achievable on macOS (config channel is XInput/Windows-only)

[stephenleo]

Summary

Agent-state color feedback currently works only on the DualSense (via driver.output in src/controller/output.ts / dualsense-driver.ts). This issue investigates extending state-color feedback — specifically the home LED — to GameSir controllers (G7 Pro, Cyclone 2), and documents why it is not achievable on macOS with the current architecture, plus the decoded protocol for whoever picks this up later.

Conclusion up front: the GameSir LED config channel only exists during a Windows XInput/Xbox-mode enumeration. macOS cannot complete that handshake, and openmicro talks to these pads over Bluetooth (which never carries the channel at all). So the home-LED color cannot be driven from openmicro as it stands, on any of the transports tested. Recommend keeping LED feedback DualSense-only.

What was tested (macOS, Apple Silicon)

Hardware: GameSir G7 Pro, GameSir Cyclone 2. Transports: Bluetooth, 2.4 GHz dongle, wired USB-C. Modes: XInput (green), Switch/NS (red), DS4 (blue).

Setup	Enumerates as	Vendor config interface (0xFFF0)?
G7 Pro — Bluetooth	5 standard HID usages	No
G7 Pro — wired USB-C	2 interfaces (gamepad + 0xFFF0)	Yes, but every command framing tried on it stalled / got no reply
Cyclone 2 — dongle, Switch mode	057E:2009 "Pro Controller"	No
Cyclone 2 — dongle, XInput	drops to white/idle, link won't hold	n/a (macOS has no XInput host)
Cyclone 2 — wired USB-C, XInput (green)	057E:2009 "Gamepad", 1 HID interface only	No

Cyclone 2 wired-XInput, full descriptor:

DEVICE vid=0x57e pid=0x2009 numConfigs=1
  iface 0 class 0x3 sub 0x0 proto 0x0 eps=2

Only the gamepad interface. No second (vendor) interface, hidden or otherwise.

Root cause

The GameSir vendor config interface (usage page 0xFFF0, reports 0x0F/0x10/0x12) is exposed only during a successful XInput/Xbox-mode enumeration, which is a Windows driver handshake. On macOS:

• Selecting XInput (green) and plugging in → the controller waits for a Windows XInput driver, never gets one, and falls back to a plain single-interface gamepad descriptor (here, a Nintendo-style 057E:2009) with no config channel.
• Switch/DS4 modes stay connected but expose no config interface.

So on macOS the config channel never appears in any mode.

Compounding this for openmicro specifically: the existing GameSir path talks to the pad over Bluetooth, and Bluetooth only ever carries the standard gamepad HID — the config channel is a wired/dongle + XInput-on-Windows artifact exclusively. There is no transport from openmicro (as architected) to the LED even if the framing were solved.

Decoded protocol (preserved for future work)

The Cyclone 2 protocol is fully open-source (reverse-engineered in NaokoAF/InFract, Cyclone2Notes.md). The home-LED command is known exactly:

• Transport: HID output report on the vendor interface, 0x0F report ID, 64-byte payload.
• Write-register: 0F 03 <profile> <addrHi> <addrLo> <len> <data...>
• Home LED lives in RGB profile 0x20, register 0x000E (Rgb1ColorHome), 3 bytes RGB.
• So the home-LED-to-RGB command is: 0F 03 20 00 0E 03 RR GG BB (padded to 64 bytes).
• Ack arrives as report 0x10 command 0x06. A heartbeat (0F F2) must be sent ~1/s to keep the input/command channel live.
• Open question (untested — no reachable channel on macOS): whether writing the RGB register applies live or needs a keyframe-select (0F 0D 01 XX) / profile reload to show.

The G7 Pro uses a different command set (gs_pc3, header shipped inside GameSir Connect): SetLightColorTest (id 11, {enable,r,g,b}), SetLightColorHSV (id 14), light names include HomeLight = 0. Its exact wire framing was not solved — it lives in a stripped C++ packet-builder in sapjoyuniapis*.dll and would need a Windows USB capture of GameSir Connect to confirm.

Recommendation

• Keep agent-state LED feedback DualSense-only — matches the current output.ts assumption; DualSense is the one pad here whose LED is reachable over the Bluetooth transport openmicro uses.
• If GameSir LED control is ever pursued, it's a separate Windows-side helper (Cyclone 2 protocol is fully decoded above; G7 Pro needs one USB capture), not a change inside openmicro — and it would still only work while the pad is wired to a Windows host, not over openmicro's Bluetooth link.

Filed from a hardware investigation session; happy to attach raw probe scripts if useful.