Skip to content

hidpp, userspace: add Logitech RS H-Shifter support, desktop routing, and UI gate monitor - #140

Merged
mescon merged 9 commits into
mescon:masterfrom
gonzaloadrio:feature/rs-h-shifter-support
Nov 6, 2026
Merged

mescon merged 9 commits into
mescon:masterfrom
gonzaloadrio:feature/rs-h-shifter-support

Conversation

@gonzaloadrio

Copy link
Copy Markdown

Summary

This PR adds complete support for the Logitech G RS H-Shifter (046d:c26b) across both the kernel driver and the userspace desktop stack (supersedes and resolves #138).

Problem & Root Cause

When the RS H-Shifter is connected via the accessory port of direct-drive wheel bases (such as the RS50 046d:c276 or G PRO):

  • In Onboard Mode (profiles 1–5), the wheel base microcontroller autonomously routes the shifter gates to interface 0.
  • In Desktop Mode (profile 0 / G HUB mode), the wheel base leaves the accessory gates disabled by default, reporting only Gear 7 and suppressing Gears 1–6 and Reverse unless host software explicitly activates attachment slot routing over HID++ 2.0.
  • Additionally, LIGHTSYNC's desktop zone sync sequence was targeting index 0x0F (GAMING_ATTACHMENTS), which reset the base's attachment routing table if called after configuration.

Changes

  1. Kernel driver (mainline/hid-logitech-hidpp.c):

    • Discover HID++ features 0x8120 (GAMING_ATTACHMENTS) and 0x812D (RS_H_SHIFTER).
    • Added hidpp_dd_enable_desktop_shifter() sending the 5-step slot routing and enablement sequence.
    • Invoked at the end of hidpp_dd_ff_query_settings() when entering or detecting Desktop mode (current_mode == 0).
    • Excluded ff->idx_attachments (0x0F) from desktop_sync_zones so LIGHTSYNC LED updates do not wipe out attachment routing.
    • Linux kernel coding style compliant (scripts/checkpatch.pl: 0 errors, 0 warnings, Signed-off-by).
  2. Userspace (logi-wheel-core & logi-wheel-gui):

    • Implemented detection for the shifter input node (discover_shifter_input, gear_from_wheel_code, gear_from_standalone_code).
    • Designed an interactive 7+R visual H-gate component in Slint (info_page.slint) showing live gate engagement and neutral rail.
    • Cleaned up gear decoding to avoid collisions with the wheel rim's physical LSB button (0x12b).
    • Passes 100% of workspace unit tests (cargo test --workspace: 219 passed, 0 failed).
  3. Documentation:

    • Documented input report offsets and bitmasks in docs/PROTOCOL_SPECIFICATION.md (Report 0x08, Byte 2 bits 0–6 for Gears 1–7, Byte 3 bit 0 for Reverse).
    • Documented DirectInput and evdev button indices in docs/BUTTON_MAPPING.md.

Hardware Verification

  • Hardware-tested live on an RS50 base (046d:c276) with the RS H-Shifter (046d:c26b) under Fedora Linux (kernel 7.2.x).
  • Verified live byte streams across all 7 forward gears and Reverse in both Onboard and Desktop ("G HUB") modes.

@mescon mescon left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, the H-shifter has been on the list for a while and the onboard-versus-desktop finding is new to me. Four things before it can go in:

  1. Gear decoding must be gated per wheel. gear_from_wheel_code runs for every model. On the G923 PS edition 0x2c3/0x2c4 are Plus and Minus; on the G923 Xbox edition 0x12b to 0x2c1 are already Shifter R and 1 to 6 (see G923_XBOX_BUTTONS) and 0x2c2 to 0x2c4 are Plus, Minus and the dial. With this change a G923 owner pressing Plus sees "shifter connected, Reverse". Apply the RS50 map only for RS50 and G PRO, keep the G923 tables as they are, and restore the G923 test you rewrote.
  2. Kernel: gate the enablement on the shifter being present. hidpp_dd_enable_desktop_shifter runs on every desktop-mode wheel, so every RS50 and G PRO owner now gets the 0x8120 and 0x1BC0 writes and an info line at each settings query. Run it only when h_shifter_dev_idx was found, and make the completion line dd_dbg.
  3. Evidence for the sequence. The 0x8120 fn2 slot list matches what G HUB sends at start-up in our captures. 0x80B1 fn8 = 1 and the 0x1BC0 fn2 on the sub-device I have no capture for. Where do they come from? If from a Windows capture, attach it:
tools\windows-usb-capture.bat

Otherwise the dmesg of a probe with the shifter attached (the new "RS H-Shifter at dev" line) and a note of what else was on the base, since the 0x812D discovery skips shifter_dev_idx.
4. Docs: write "1 to 7" rather than "1–7"; this repo keeps dashes out of prose.

#139 stacks on this branch, so it will need a rebase once this changes.

@gonzaloadrio
gonzaloadrio force-pushed the feature/rs-h-shifter-support branch 3 times, most recently from 3200e3a to e3b8ac0 Compare November 4, 2026 20:57
@gonzaloadrio

Copy link
Copy Markdown
Author

Thanks for the thorough review and catching the G923 button collision!

I've addressed all the review items:

  1. Model gating & G923 test: In userspace (logi-wheel-core), gear_from_wheel_code is now strictly model-gated to direct-drive bases (WheelModel::Rs50 and WheelModel::GPro). For WheelModel::G923, it returns None, completely preventing collisions with physical Plus/Minus/Dial push buttons. The original G923 test in testio.rs has been fully restored and verifies that Plus (0x2c3) and Minus (0x2c4) report as buttons without triggering shifter state.
  2. Kernel gating & log level: hidpp_dd_enable_desktop_shifter() now runs only when ff->current_mode == 0 && ff->h_shifter_dev_idx != HIDPP_DD_FEATURE_NOT_FOUND. The completion log line was switched from dd_info to dd_dbg.
  3. Evidence for the sequence & sequence cleanup:
    • Where 0x80B1 came from: It was mistakenly carried over from an initial capture session where an RS Shifter & Handbrake was also plugged in. The RS H-Shifter (0x812D) does not have or need 0x80B1 (BANDED_AXIS); that call and the sub-device sync have been completely dropped.
    • The verified enablement sequence on the base: The sequence in hidpp_dd_enable_desktop_shifter() now strictly issues the commands to the base (Dev ff) on feature 0x8120 (GAMING_ATTACHMENTS) and 0x1BC0 (SYNC):
      • 10 ff 0f 0d 00 00 00 — 0x8120 fn0 (query/prepare slots)
      • 11 ff 0f 2d 0a 01 02 03 04 05 06 07 08 09 0a 00... — 0x8120 fn2 (apply 10-slot routing table)
      • 10 ff 0f 1d 00 00 00 — 0x8120 fn1 (commit attachment routing)
      • 10 ff 0e 2d 00 00 00 — 0x1BC0 fn2 (base sync notify)
    • Probe log in dmesg:
      logitech-dd 0003:046D:C276.0003: RS H-Shifter at dev 0x03 (idx 0x0a)
      logitech-dd 0003:046D:C276.0003: [dd_dbg] Desktop mode shifter enablement completed
      
    • Wire format (Report ID 0x08 on EP 0x81):
      • Neutral: Byte 2 = 0x00
      • Gears 1 to 7: Byte 2 bits 0–6 (0x01 to 0x40) -> evdev 0x12c (BTN_BASE) to 0x2c2 (BTN_TRIGGER_HAPPY3)
      • Reverse: Byte 3 bit 0 (0x01) -> evdev 0x2c3 (BTN_TRIGGER_HAPPY4)
  4. Docs style: Updated docs/BUTTON_MAPPING.md to use "1 to 7" instead of en-dashes.
  5. Code quality & PR feat(gui): add support for standalone RS Handbrake and Logitech Racing Adapter #139 rebase: Refactored shifter tests to idiomatic table-driven tests with semantic comments, and rebased feat(gui): add support for standalone RS Handbrake and Logitech Racing Adapter #139 on top of this branch. All 219 workspace unit tests pass cleanly.

@mescon mescon left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this round lands the big ones: the G923 gate with its test back, the enablement keyed on h_shifter_dev_idx, 0x80B1 gone, and the wire table in the docs. Four smaller things before it can go in:

  1. Rebase on master (now at 1af9b33). The cargo-audit job fails on your branch only because master's lockfile bump to pulldown-cmark 0.13.6 is missing.
  2. desktop_sync_zones: the new skip runs for every RS50 in desktop mode, not only with a shifter attached, so it changes LIGHTSYNC for everyone. Gate it on h_shifter_dev_idx != HIDPP_DD_FEATURE_NOT_FOUND. In hidpp_dd_oled_handback the call now also runs from the remove path (the handback at teardown); return early when ff->stopping is set.
  3. Fill ff->accessory_name (for example "RS H-Shifter") when the 0x812D probe succeeds. wheel_accessory is what the TUI, logi-wheel doctor and --report read, so that gives them the accessory for free; today only the GUI knows about it.
  4. gear_from_wheel_code maps 0x2c4 to Reverse, but your own table says index 20 is unused: drop the alias. And the "RS50 Base" label in testio.rs also shows on a G PRO; "Wheel base" covers both.

I will approve CI as soon as the rebase is up.

In Desktop mode (profile 0), the RS50 base suppresses accessory gate
reporting for gears 1-6 and Reverse on interface 0 unless G HUB's
slot routing and sync sequence is sent.

Discover GAMING_ATTACHMENTS (0x8120) and RS_H_SHIFTER (0x812D), and
invoke hidpp_dd_enable_desktop_shifter() when entering or detecting
Desktop mode if an RS H-Shifter is present (h_shifter_dev_idx).

Signed-off-by: Gonzalo Adrio <gonzaloadrio@users.noreply.github.com>
Add Logitech RS H-Shifter (046d:c26b) detection and decoding for both
direct USB mode and wheel base accessory port attachment.

Gate wheel-base gear decoding strictly to direct-drive wheels (RS50 and
G PRO) to prevent collisions with physical button codes on G923 editions.
Add an interactive 7+R Slint visual H-gate component and document input
report mappings and evdev codes.

Signed-off-by: Gonzalo Adrio <gonzaloadrio@users.noreply.github.com>
Activating or handing back the RS50 base OLED display via Feature
0x8130 (DisplayGameData) resets the internal sub-device gate routing table
(Feature 0x8120), dropping gates 1-6 and Reverse while leaving only 7th
gear operational in desktop mode.

Re-invoke hidpp_dd_enable_desktop_shifter() whenever the OLED display is
handed back to firmware menus or activated through wheel_oled sysfs attribute
while operating in desktop mode (current_mode == 0).

Signed-off-by: Gonzalo Adrio <gonzaloadrio@gmail.com>
SonarCloud flagged dropping the const qualifier on slot_routing when
passing it as mutable u8 * to hidpp_send_fap_command_sync(). Copy the
table into the local params buffer instead.

Signed-off-by: Gonzalo Adrio <gonzaloadrio@gmail.com>
Extract standalone USB shifter event polling from Reader::start loop into
a dedicated helper function (poll_standalone_shifter).

Signed-off-by: Gonzalo Adrio <gonzaloadrio@gmail.com>
…nd guard clauses

Replace nested if-let pyramid with guard clauses and early exits (return
false on empty/err read, continue on unhandled events).

Signed-off-by: Gonzalo Adrio <gonzaloadrio@gmail.com>
@gonzaloadrio
gonzaloadrio force-pushed the feature/rs-h-shifter-support branch 2 times, most recently from 48f0d77 to c94d80e Compare November 4, 2026 21:59
@gonzaloadrio

gonzaloadrio commented Nov 4, 2026 •

Copy link
Copy Markdown
Author

Thanks @mescon, rebased and pushed with all 4 items addressed:

  • Rebased on master (1af9b33).
  • desktop_sync_zones skip gated on h_shifter_dev_idx != NOT_FOUND, and oled handback exits early on ff->stopping.
  • ff->accessory_name populated with "RS H-Shifter" on discovery, and wheel_accessory updated to report it.
  • Dropped the 0x2c4 alias, and renamed the UI label to "Wheel base".

SonarCloud check is green.

… gating

- Gate desktop_sync_zones skip on h_shifter_dev_idx != NOT_FOUND.
- Return early in hidpp_dd_oled_handback if ff->stopping is set.
- Populate ff->accessory_name with 'RS H-Shifter' on 0x812D discovery.
- Allow wheel_accessory_show to report when either shifter_dev_idx or h_shifter_dev_idx is present.
- Drop unused 0x2c4 alias in gear_from_wheel_code.
- Rename 'RS50 Base' label in testio.rs to 'Wheel base' for generic direct-drive coverage.

Signed-off-by: Gonzalo Adrio <gonzaloadrio@gmail.com>
@gonzaloadrio
gonzaloadrio force-pushed the feature/rs-h-shifter-support branch from c94d80e to 8484945 Compare November 4, 2026 22:06
gonzaloadrio and others added 2 commits November 4, 2026 23:11
The 0x812D probe ran as a second loop over every candidate sub-device,
so a base without an H-Shifter paid one HIDPP_DD_PROBE_TIMEOUT per
silent candidate on top of what the pedal and RS Shifter & Handbrake
pass already cost, about a second and a half at probe. A port with no
response curve answers that first pass with -ENOENT in a few
milliseconds, which is exactly what the H-Shifter looks like, so ask
such a candidate for 0x812D right there and never probe a silent index
twice.

The accessory rescan only knew the RS Shifter & Handbrake, so an
H-Shifter plugged in after the module loaded was never found and one
pulled out was never forgotten. Teach it both directions, and send the
desktop-mode enablement sequence when a shifter arrives, as probe does.
The RS Shifter & Handbrake adoption moves into a helper shared by probe
and rescan.

wheel_accessory's documentation covers both accessories and the
on-demand re-check.
@mescon

mescon commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Pushed one commit on top of yours (eb1164b) for the two remaining gaps. The 0x812D probe now rides the existing candidate pass: a port with no response curve answers -ENOENT in a few milliseconds, and only those get asked for 0x812D, so a base without the shifter pays nothing extra at probe. The accessory rescan now learns H-Shifter arrival and removal and re-sends the desktop enablement when one arrives, so it works plugged in after boot and wheel_accessory follows it.

Builds and checkpatch are clean here, but nobody on this side has the shifter. Could you reload with it attached, then pull it and plug it back while reading wheel_accessory, and confirm the gates still route in desktop mode after the re-plug?

watch -n1 cat /sys/bus/hid/devices/*046D:C276*/wheel_accessory

@sonarqubecloud

sonarqubecloud Bot commented Nov 4, 2026

Copy link
Copy Markdown

@gonzaloadrio

Copy link
Copy Markdown
Author

Tested live on the RS50 base (046d:c276) with commit eb1164b, and it works wonderfully!

Here is the log summary from the re-plug test in desktop mode:

  1. Unplug: wheel_accessory transitioned from RS H-Shifter to none, and dmesg reported:
    logitech-dd 0003:046D:C276.000E: RS50 (native): RS H-Shifter removed
    
  2. Re-plug: In ~2 seconds, wheel_accessory updated back to RS H-Shifter, and dmesg logged:
    logitech-dd 0003:046D:C276.000E: RS50 (native): RS H-Shifter at dev 0x02 (idx 0x0e)
    
  3. Desktop gate routing: Shifted through gears 1 to 7 right after re-plugging; all gates (1–7 and Reverse) routed cleanly and worked immediately.

As a small observation for down the road: with both accessories plugged in at the same time (RS H-Shifter + RS Shifter & Handbrake), input routing works seamlessly in parallel for both devices. Currently wheel_accessory names the Handbrake in that scenario, so in a future iteration we might consider exposing both attached accessories to sysfs so frontends can display both.

Everything is working smoothly and ready to merge from my side. Thanks a lot for the great work on the hotplug and probe refactoring!

@mescon mescon left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the thorough re-plug run, that is exactly the confirmation this needed. Approving and merging.

Your point about both accessories at once is fair: wheel_accessory is a single value by design, so a second attribute or a list format would be needed to show both. Worth a follow-up issue once this lands, and the RS Shifter & Handbrake owners can weigh in on the format. A CREDITS.md entry for this work follows on master.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants