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

[Stanley5249]

Summary

Adds support for HID++ 2.0 Onboard Profiles (feature 0x8100), the flash profile memory G-series gaming mice use to decide whether they run host software settings or their own 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 and mode-control slice: read the memory description, mode, active profile and profile directory; switch between host and onboard mode; and select the active onboard profile. It deliberately does not write flash, so profile editing (functions 6 to 8) is out of scope.

The mode lives in device RAM, so a mouse left in host mode is back in onboard mode after a power cycle. The agent therefore re-applies a configured mode on every reconnect. A device with no configured mode is left in whatever mode it powered on in, and OpenLogi never switches it on the user's behalf.

Scope, and what still needs work

This PR is the wiring: the protocol wrapper, the I/O verbs, the config key, a panel to toggle the mode and pick a profile, and enough receiver support to reach these mice at all. It is not a finished onboard-profiles feature:

• Profile contents are untouched. Key bindings, DPI stages and report rate stored inside a profile are neither read nor written. Selecting a profile activates whatever the device already has in that slot.
• The UI is functional, not designed. The Profiles tab is a source toggle and a row of pills. It needs real design work before it is something to ship proudly.
• Flash writes are out of scope, so OpenLogi cannot create, edit or reset a profile.

Worth reviewing as the foundation, not as the finished surface.

Changes

• hidpp: new feature/onboard_profiles with getDescription, get/set onboard mode, get/set current profile, memoryRead, and directory parsing over sector 0. Offsets are reverse-engineered against Solaar and libratbag and marked as such; unknown mode and enabled bytes surface as UnsupportedResponse rather than silent fallbacks. The directory read is bounded by profile_count + profile_count_oob, so a device that lists its read-only profiles is not truncated. No flash-write session.
• hid: IPC-facing ProfilesMode / ProfileEntry / OnboardProfilesInfo and the read/apply verbs; apply_profiles_config skips writes the device already matches. Recognises Lightspeed receivers (0xc53f, 0xc547) so a G502 X LIGHTSPEED is reachable at all. Adds the exchange() lock described below.
• core: per-device [devices."…".onboard_profiles] (mode, profile), config-file only and now documented in docs/CONFIGURATION.md; Capabilities::onboard_profiles from a 0x8100 feature probe.
• ipc: set_onboard_profiles / read_onboard_profiles agent methods and the reconnect re-apply. PROTOCOL_VERSION 10 → 11, wire-format goldens regenerated.
• gui: a Profiles tab gated on Capabilities::onboard_profiles, with a settings source (OpenLogi settings / onboard memory) and the active-profile selector. The selector offers user slots only: a device's read-only profiles are factory templates a slot is reset from, and the firmware rejects setCurrentProfile on one, so offering them would be an action that cannot succeed. diag profiles still prints them, since showing raw device state is its job.
• cli: openlogi diag profiles prints the state and runs a mode/profile round-trip (--read-only, --leave-onboard).

Things worth a careful look

PROTOCOL_VERSION 10 → 11. ProfilesMode and ProfileEntry cross the agent↔GUI IPC, so their variant and field order are wire format.

The global lock is a stopgap, not the fix. send_v20 matches a reply to its request by comparing HID++ headers, and the channel is built with rotate_software_id: false, so two concurrent requests to one device carry byte-identical headers and can take each other's replies. Bench-observed on a G502 X: a DPI write racing a mode write fails InvalidArgument 3/3 with the DPI payload landing on 0x8100's feature index, and get_dpi racing a mode write returns Ok(0), silently wrong with no error. write::exchange() serializes verbs to stop it, but the root fix is HidppChannel::set_rotating_sw_id(true). The lock is global rather than per-device and is held across open_route_channel(), so it serializes enumeration for unrelated devices too, which is heavier than the problem warrants. Rotating the software id is left out of this PR deliberately: it changes the vendored channel for every device and every feature, so it wants the bench cases re-run on hardware rather than riding along here. Note also that gesture.rs::run_capture_session opens a channel outside the lock.

Lightspeed receivers route as DeviceRoute::Unifying. They speak the same HID++ 1.0 register protocol, so they are enumerated, routed and paired through the Unifying path, and only receiver_display_name tells them apart. A dedicated route variant would fork every match arm for what is currently a cosmetic difference, so it seems worth revisiting only if their pairing register semantics turn out to diverge.

Three new UI strings are English placeholders in all 19 non-English locales, for Crowdin to fill.

The device renders as a silhouette. The pinned asset catalog has no G502 X or X-generation entry (#461), so the panel shows generic art and hotspots.

Testing

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

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo run -p openlogi -- diag profiles      # 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 read-only profiles, 11 buttons, 16 × 255 B sectors), the mode, the active profile and the directory. The strict 0/1 enabled parse holds on real flash, and the unit fixture carries this captured payload.
• Mode and active-profile round-trips succeed, including across an agent restart honouring a GUI-set mode = onboard, profile = 2.
• setCurrentProfile is onboard-mode only. Host mode answers InvalidArgument and reports the active profile as 0x0000, since it parks the flash profile.
• The mode is volatile: a device left in host mode came back onboard, with sector 0x0002 active, 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 concurrency pairs above, before and after the lock.

Not verified:

• Any device other than a G502 X LIGHTSPEED. Everything above generalises from one mouse.
• The read-only-profile paths. The G502 X reports 2 of them alongside its 5 user slots, yet the sector-0 directory terminates after the 5 user entries and setCurrentProfile rejects 0x0101 to 0x0103, so nothing here exercises them. A device that does list them would be the first real test.
• macOS and Linux GUI builds and i18n parity are CI's job; not built on macOS locally.

Notes

Depends on #388 (Lightspeed receiver recognition). Its commit is carried here so the branch builds and the hardware test runs; the patch-ids match, so it drops out on rebase once #388 merges.

Screenshots

Fixes #462

[greptile-apps]

Greptile Summary

This PR wires in read and mode-control support for HID++ 0x8100 OnboardProfiles, enabling OpenLogi to report a G-series mouse's mode, switch between host and onboard mode, and select the active user-profile slot. The protocol layer (openlogi-hidpp), I/O verbs (openlogi-hid), IPC DTOs and agent methods, GUI Profiles tab, diag profiles CLI command, and per-device config key (onboard_profiles) are all introduced together; protocol version advances from 23 to 24.

• The core read_profile_directory loop now correctly uses total_profile_count() (user + ROM) to bound reads, with parse_directory stopping at the terminator or the entry limit — addressing the concern raised in earlier review threads.
• The reconnect re-apply sequence applies the configured mode before DPI and wheel-mode writes, which is the correct ordering since a mode switch can shadow subsequent host-side writes.
• Two small hardening gaps: validate_user_profile accepts sector 0x0000 (the directory sector), which would produce a spurious write error on every reconnect for a hand-edited profile = 0 config; and read_profile_directory has no guard against attempting a memoryRead past sector_size - 16 for devices with many profiles in a small flash sector.

Confidence Score: 5/5

• Safe to merge as a foundation layer; the two gaps noted are hardening nits that do not affect any device tested and do not corrupt data.
• The change is a read-and-mode-control slice with no flash writes. The protocol implementation is well-tested (captured G502 X fixture, wire-format golden tests, round-trip unit tests). The reconnect re-apply and GUI optimistic-write paths both follow established patterns in the codebase. The two issues found — sector-0 passing validate_user_profile and the theoretical read_profile_directory overrun on exotic hardware — are quality nits that only surface under unusual conditions (manual config editing or non-existent hardware combinations) and fail loudly rather than silently.
• crates/openlogi-hid/src/write/onboard_profiles.rs and crates/openlogi-hidpp/src/feature/onboard_profiles.rs are worth a second look for the two hardening gaps; all other files are straightforward additions.

Important Files Changed

Filename	Overview
crates/openlogi-hidpp/src/feature/onboard_profiles.rs	New feature wrapper for HID++ 0x8100. Protocol is sound (reverse-engineered, cross-checked). One issue: the read_profile_directory loop does not guard against reading past sector_size - 16, which would fail on devices with many profiles in a small sector.
crates/openlogi-hid/src/write/onboard_profiles.rs	New I/O verbs: get/set mode, get/set profile, apply config with skip-if-matches optimisation. validate_user_profile does not reject sector 0 (the directory sector), so a hand-edited config with profile = 0 causes a spurious write error on every reconnect.
crates/openlogi-hidpp/src/feature/onboard_profiles/types.rs	Wire types and parse_directory. Terminator, enabled-byte validation, and max-entries bound are all handled correctly; the captured G502 X fixture test is a nice regression anchor.
crates/openlogi-core/src/hid/onboard_profiles.rs	IPC-facing DTOs (ProfilesMode, ProfileEntry, OnboardProfilesInfo). Wire-format comments and the is_rom_sector helper are clean; the #[must_use] annotation on the free function is a good touch.
crates/openlogi-core/src/config/settings.rs	New OnboardProfiles config enum using tagged TOML (mode = "host" / mode = "onboard"). deny_unknown_fields correctly prevents host {} from accepting a stray profile key; both shapes are covered by the new parse tests.
crates/openlogi-agent-core/src/orchestrator.rs	configured_onboard_profiles helper integrates cleanly into the re-apply pipeline; capability gate and the "unconfigured = unmanaged" contract are both correct and tested.
crates/openlogi-agent-core/src/hardware.rs	OnboardProfilesApply and its insertion into reapply_mouse_volatile_in_background look correct. Profiles are applied before DPI and wheel mode, which is the right order given mode switches can shadow subsequent writes.
crates/openlogi-desktop/src/features/profiles.rs	Profiles panel with lazy read, optimistic write, and post-write confirming re-read. ROM entries are correctly excluded from the selector. Index-based pill numbering is acknowledged as a placeholder; the selectable_profiles_exclude_disabled_and_rom_entries_without_renumbering test names the behaviour explicitly.
crates/openlogi-ipc/src/ipc.rs	Protocol version bump 23→24 with two new agent methods appended. Wire-format golden tests are regenerated and the new onboard_profile_types test pins the serde encoding.
crates/openlogi-cli/src/cmd/diag/profiles.rs	Diagnostic command with clean error propagation and a restore path that covers both the mode and the profile. The finish_with_restore helper avoids hiding operation errors under restore failures. The four unit tests cover the key round_trip_target cases well.
crates/openlogi-desktop/src/state/profiles.rs	Lazy-read cache and optimistic write update. The profiles_error_is_permanent gate (only FeatureUnsupported is permanent) is correct for a HID++ feature probe.
crates/openlogi-core/src/hid/error.rs	New InvalidProfileSector WriteError variant and two new HidppOperation variants, all appended last as required by the wire-format ordering contract.
crates/openlogi-agent/src/server.rs	set_onboard_profiles and read_onboard_profiles server-side handlers delegate correctly through DeviceOp::run, which provides the channel serialization described in the PR.

Sequence Diagram

sequenceDiagram
    participant Device as G-series Mouse
    participant Agent as openlogi-agent
    participant Orch as Orchestrator
    participant HW as hardware.rs
    participant HID as openlogi-hid
    participant GUI as openlogi-desktop

    Note over Agent,Device: Device (Re)connect
    Agent->>Orch: device appeared
    Orch->>Orch: configured_onboard_profiles()
    Orch->>HW: reapply_mouse_volatile_in_background(profiles, ...)
    HW->>HID: apply_profiles_config_on(mode, profile)
    HID->>Device: get_onboard_mode() [read current]
    Device-->>HID: Onboard / Host
    alt mode mismatch
        HID->>Device: set_onboard_mode(mode)
        HID->>Device: get_onboard_mode() [read-back]
    end
    alt Onboard mode + profile configured
        HID->>Device: get_current_profile()
        Device-->>HID: active sector
        alt profile mismatch
            HID->>Device: set_current_profile(sector)
        end
    end

    Note over GUI,Agent: GUI interaction
    GUI->>Agent: read_onboard_profiles(route)
    Agent->>HID: get_onboard_profiles_on(shared)
    HID->>Device: getProfilesDescription() [fn 0]
    HID->>Device: getOnboardMode() [fn 2]
    HID->>Device: getCurrentProfile() [fn 4]
    HID->>Device: "memoryRead(sector=0, offsets…) [fn 5, repeated]"
    Device-->>HID: 16-byte chunks → directory
    HID-->>Agent: OnboardProfilesInfo
    Agent-->>GUI: OnboardProfilesInfo

    GUI->>Agent: set_onboard_profiles(route, mode, profile)
    Agent->>HID: apply_profiles_config_on(mode, profile)
    HID->>Device: set_onboard_mode / set_current_profile
    Agent-->>GUI: Ok(())
    GUI->>Agent: read_onboard_profiles(route) [confirming re-read]

Loading

_{Reviews (14): Last reviewed commit: "fix(xtask): handle CRLF workflow continu..." | Re-trigger Greptile}

[davidbudnick]

@Stanley5249 Looks as you have issues, with your pipeline running for the following change, can you fix issues and re-push?

[Stanley5249]

@davidbudnick CI is green now, and I've updated the PR body. A few things could use a closer look: the protocol version bump, the translations, and the temporary global lock. Details on each are at the top. Thanks.

[davidbudnick]

@davidbudnick CI is green now, and I've updated the PR body. A few things could use a closer look: the protocol version bump, the translations, and the temporary global lock. Details on each are at the top. Thanks.

Perfect thanks for updating it, looks as you have a few merge conflicts which need to be resolved before a merge can take place.

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Start a greploop in Codex and it will work through the open comments and keep going until this PR reviews clean.

[Stanley5249]

@davidbudnick Done. Maybe close #388 as well, its commit is carried here with kiwimaker credited.

[albertorm95]

wow, this would be great!

[Stanley5249]

@albertorm95

Thanks! For now, it only lets you switch profile modes and pick an onboard profile. It’s still far from everything G Hub supports, but G Hub’s UX sucks!

[Stanley5249]

@davidbudnick, mind taking a look? Thanks.

[albertorm95]

@albertorm95

Thanks! For now, it only lets you switch profile modes and pick an onboard profile. It’s still far from everything G Hub supports, but G Hub’s UX sucks!

Looking forward on remapping the keys, let me know if there is a list of missing tasks so maybe I can support this

[Stanley5249]

@albertorm95 The main missing tasks are:

• Profile writing
• Key remapping
• DPI steps
• G-Shift
• Live state updates

Key remapping may be the easiest place to start. DPI steps and G-Shift need more design. There is also a sync issue: the app does not update after pressing DPI Shift or switching profiles until you reopen it.

The G502 X guide may help: https://www.logitech.com/assets/66193/3/g502-x-artanis-web-qsg.pdf

[davidbudnick]

@Stanley5249 Looks as you have quite a few actions failing, can you please update them?

[Stanley5249]

@davidbudnick Done.

[Stanley5249]

Thanks.