feat: onboard profiles (0x8100) support for G-series mice

[Stanley5249]

Summary

Adds end-to-end support for HID++ 2.0 Onboard Profiles (feature 0x8100), the switch
gaming mice (G502 X LIGHTSPEED, G305, G602, …) use to decide whether they run host software
settings or their own flash-stored profiles. Until now 0x8100 was a name-only row in the
feature registry, so OpenLogi could neither report which mode a mouse was in nor let the
user choose one.

This is a read + mode-control slice: read the memory description, mode, active profile
and profile directory; switch host/onboard mode; select the active onboard profile. It
deliberately does not write flash (no profile editing — fn6–8 are out of scope).

The mode is volatile — a mouse left in host mode comes back onboard after a power cycle —
so the agent re-applies the per-device policy on every (re)connect.

Rewritten 2026-07-26. The original version of this description said DPI writes are
rejected while a mouse is in onboard mode, and justified part of the design with that.
Bench testing disproved it; the real cause was a concurrency bug, now fixed here. See
Corrections.

Changes

• hidpp: new feature/onboard_profiles module — getDescription, get/set onboard
  mode, get/set current profile, memoryRead, and directory parsing over sector 0.
  Offsets reverse-engineered against Solaar / libratbag and marked as such; strict wire
  validation (unknown mode/enabled bytes → UnsupportedResponse). No flash-write session.
• hid: IPC-facing ProfilesMode / ProfileEntry / OnboardProfilesInfo types and the
  read/apply verbs. apply_profiles_config skips writes the device already matches and
  tolerates transient post-mode-switch read-back failures (observed on hardware).
  Also: an exchange() lock serializing every device verb — see below.
• core: per-device [devices."…".onboard_profiles] config (mode, profile),
  config-file-only; Capabilities::onboard_profiles from a 0x8100 feature probe.
• ipc: set_onboard_profiles / read_onboard_profiles agent methods; the reconnect
  reapply. PROTOCOL_VERSION 10 → 11, wire-format goldens regenerated.
• gui: a "Profiles" tab (gated on Capabilities::onboard_profiles) — Settings source
  (OpenLogi settings / Onboard memory) and the active onboard-profile selector.
• cli: openlogi diag profiles — prints the state and runs a mode/profile round-trip
  (--read-only, --leave-onboard).

The agent never switches a device's mode uninvited

An unconfigured 0x8100 device is left in whatever mode it powered on in. The mouse
signals its active profile only by blinking an LED, so a host-mode switch the user did not
ask for discards the profile they picked on the device itself, with nothing on screen and
nothing on the device to explain it. The mode is written only after the user chooses one.

Concurrent HID++ verbs were cross-matching replies

HID++ correlates a reply to its request only by (device index, feature index, function, software id), and every verb here opens by resolving its feature with the same
0x0000 getFeature header at the channel's fixed software id. Two verbs in flight on one
device therefore match each other's replies. Bench-observed on a G502 X:

concurrent pair	result
set_profiles_mode ‖ set_dpi	DPI InvalidArgument, 3/3 — the DPI payload reaches 0x8100's index
set_dpi ‖ set_scroll_wheel_mode	0x2121 reported unsupported, though the feature table lists it
get_dpi ‖ get_onboard_profiles	UnsupportedResponse
get_dpi ‖ set_profiles_mode	Ok(0) — silently wrong, no error

Run sequentially, all of them succeed. An exchange() lock now spans each verb, taken in
with_route and in every *_on shared-channel fast path; all four cases pass after it.
This predates onboard profiles — the same fan-out existed in the reconnect reapply — but
0x8100 is what made it reproducible.

The reapply still runs the remaining volatile writes as a continuation of the
onboard-profiles apply, for a different reason than originally stated: activating a profile
reloads that profile's DPI out of flash, so a DPI write that raced ahead would be
discarded.

Testing

Hardware: G502 X LIGHTSPEED over a Lightspeed receiver, Windows.

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
cargo run -p openlogi -- diag profiles            # full read + round-trip
cargo run -p openlogi -- diag dpi                 # in both modes
cargo run -p openlogi-gui                          # Profiles tab, toggle + re-read

Verified on hardware:

• diag profiles reads the description (5 user + 2 ROM profiles, 11 buttons,
  16 × 255 B sectors), mode, active profile, and the directory; the strict 0/1 enabled
  parse holds on real flash. The unit fixture now carries this captured payload.
• Mode and active-profile round-trips succeed, across an agent restart honouring a GUI-set
  mode = onboard, profile = 2.
• setCurrentProfile is onboard-mode-only — host mode answers InvalidArgument. Host
  mode also reports active profile 0x0000, since it parks the flash profile.
• The mode is volatile: a device left in host mode returned to onboard, with sector
  0x0002 active again, after a power cycle.
• DPI writes are accepted in both modes — 1600 → 1650 → 1600 round-trips while
  onboard, while in host mode, and immediately after a mode write.
• The four concurrency cases in the table above, before and after the lock.
• ROM profiles are counted but not reachable on this device. The description reports 2,
  yet sector 0's directory terminates right after the 5 user entries (reading with the
  corrected profile_count + profile_count_oob bound still returns 5), and
  setCurrentProfile rejects 0x0101/0x0102/0x0103 with InvalidArgument. The
  directory bound was fixed anyway — it is wrong for the format, and a device that does
  list ROM entries would lose them — but is_rom_sector and the GUI's entry.is_rom()
  branch are dead paths on a G502 X, not proof they work.

macOS/Linux GUI build and i18n parity are CI's job — not built on macOS locally.

Corrections

Two claims in the first version of this PR were wrong, and are fixed in the code and the
docs rather than left standing:

1. "DPI writes are rejected while the mouse is onboard." They are not. Every
   InvalidArgument behind that claim came from the concurrency bug above — the DPI write
   was reaching 0x8100's feature index. The consent policy's stated cost ("configured DPI
   silently no-ops on a mouse sitting in onboard mode") therefore does not exist.
2. "On these devices OpenLogi's writes silently did nothing." Overstated. Onboard mode
   accepts host writes; what it does is reload the profile's own values from flash on the
   next profile switch, which is a persistence question, not a blocked write.

Known limitation — host mode is currently a downgrade

On a G502 X, the host mode this PR can enter leaves G7/G8 dead and the LED dark. That
is not the mode's fault: the DPI stage list, the lighting and the button assignments all
lived in the flash profile that host mode parks, and OpenLogi writes the mode byte and
nothing else. G HUB's host mode keeps all of it because it pushes a full configuration the
moment it takes the mode.

The feature table bounds how far this can be closed on this device: no 0x1b04 (no
HID++ button remapping — the OS hook is the only path) and no 0x807x/0x8081 lighting
at all, so nothing OpenLogi can currently send will light that LED. 0x8110 (button spy)
is the untested lead for host-side DPI staging.

Until that is closed, host mode stays opt-in and is never entered on the user's behalf —
which is what the consent policy above already does.

Notes

• Stacks on fix(hid): declare Win32_System_IO feature for windows-sys WriteFile #458 (Win32_System_IO for windows-sys) and feat(hid): recognise Lightspeed nano receivers (G-series, e.g. G305) #388 (Lightspeed receiver
  recognition) — both included here so the branch builds and the hardware test runs. Their
  commits carry identical patch-ids and drop out on rebase once those merge.
• Screenshots of the new Profiles tab below.

[greptile-apps]

Greptile Summary

This PR adds end-to-end HID++ 2.0 0x8100 OnboardProfiles support for G-series gaming mice (G502 X LIGHTSPEED, G305, G602, …): read the profile memory description, get/set the onboard/host mode, get/set the active profile sector, and parse the flash directory. It also fixes a pre-existing concurrency bug where concurrent HID++ verbs on one device cross-matched replies, by introducing a global exchange() mutex that serializes every verb.

• openlogi-hidpp: new OnboardProfilesFeature (0x8100) — wire parsing, getDescription, getOnboardMode/setOnboardMode, getCurrentProfile/setCurrentProfile, and memoryRead+directory parsing; strict validation (enabled ≠ 0/1 → UnsupportedResponse).
• openlogi-hid: apply_profiles_config / get_onboard_profiles / set_profiles_mode / set_active_profile; the global EXCHANGE Tokio mutex added to with_route and all *_on fast-path functions; reconnect reapply restructured so remaining writes run as a continuation after the onboard-profiles apply.
• openlogi-agent-core / openlogi-agent: set_onboard_profiles / read_onboard_profiles IPC verbs, PROTOCOL_VERSION bumped to 11, per-device config, Capabilities::onboard_profiles probed from feature table.
• GUI: "Profiles" tab with source pills and profile selector, lazy read, optimistic writes + confirming re-read; Lightspeed receiver (0xc53f, 0xc547) enumeration on the Unifying protocol path.

Confidence Score: 5/5

Safe to merge — the concurrency fix is correct, the ROM-profile directory fix from the previous review is applied, and the reconnect reapply sequencing is sound.

The exchange lock covers every code path that sends a HID++ packet (with_route, all *_on fast-path helpers, and the hires_wheel *_on variants) without introducing any re-entrancy hazard: *_on_channel helpers are always called with the lock already held and never try to acquire it themselves. The reconnect reapply continuation correctly sequences onboard-profiles before DPI/SmartShift. Directory parsing now passes total_profiles (user + OOB) so ROM entries are no longer silently dropped. Wire-format goldens are regenerated, the protocol version is bumped, and all four previously-failing concurrent-verb combinations are listed as verified on hardware.

Files Needing Attention: No files require special attention.

Important Files Changed

Filename	Overview
crates/openlogi-hidpp/src/feature/onboard_profiles/mod.rs	New 0x8100 OnboardProfilesFeature: wire calls for getDescription, get/set mode, get/set active profile, memoryRead, and directory parsing. Non-exhaustive OnboardMode handled conservatively. Directory read correctly passes total_profiles (user + ROM), fixing the previous ROM-profile omission.
crates/openlogi-hid/src/write.rs	Adds global EXCHANGE Tokio mutex and exchange() helper; with_route now acquires it before opening the channel, serializing all HID++ verbs on all shared-channel and route-open code paths.
crates/openlogi-hid/src/write/onboard_profiles.rs	New module: get_onboard_profiles, set_profiles_mode, set_active_profile, apply_profiles_config, and the shared apply_profiles_config_on_channel. Apply logic skips writes when device already matches, logs non-fatal read-back failures, and is correctly called with EXCHANGE held by every caller path.
crates/openlogi-agent-core/src/orchestrator.rs	reapply_volatile_settings restructured: remaining writes bundled into an after closure passed to apply_onboard_profiles_in_background, so they run strictly after the profiles apply.
crates/openlogi-agent-core/src/hardware.rs	Adds apply_onboard_profiles_in_background (with RunOnDrop ensuring after runs on panic/timeout), apply_onboard_profiles (IPC path), and read_onboard_profiles. Timeout wraps the entire apply.
crates/openlogi-gui/src/components/profiles_panel.rs	New Profiles tab: source pills and profile directory pills. Lazy read, optimistic write + confirming re-read, stale-route guard. keep_profile_for correctly handles the host-mode 0x0000 active profile.
crates/openlogi-gui/src/state.rs	Adds profiles_data and profiles_pending_confirm alongside the existing smartshift pattern. commit_onboard_profiles writes IPC + config + optimistic update + queues confirming re-read.
crates/openlogi-hid/src/route.rs	Adds LIGHTSPEED_PIDS (0xc53f, 0xc547) and speaks_unifying_protocol(); device_route_for now routes Lightspeed receivers via DeviceRoute::Unifying. Tests verify both PIDs produce Unifying routes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Device reconnect] --> B{onboard_profiles\nconfigured?}
    B -- No --> REST
    B -- Yes --> C[spawn OS thread with tokio rt]
    C --> D[acquire EXCHANGE lock]
    D --> E[open 0x8100 feature]
    E --> F[read current mode fn2]
    F --> G{current == target?}
    G -- yes --> H
    G -- no --> I[setOnboardMode fn1]
    I --> J[read-back mode\nnon-fatal on fail]
    J --> H
    H{Onboard AND\nprofile set?}
    H -- no --> K[release EXCHANGE lock]
    H -- yes --> L[getCurrentProfile fn4]
    L --> M{active == target?}
    M -- yes --> K
    M -- no --> N[setCurrentProfile fn3]
    N --> O[read-back profile\nnon-fatal on fail]
    O --> K
    K --> REST[after closure\nscroll+DPI+SmartShift\nown bg threads]

Loading

_{Reviews (3): Last reviewed commit: "fix(hid): bound the profile directory re..." | Re-trigger Greptile}