Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 65 additions & 2 deletions docs/BUTTON_MAPPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ buttons - diagram callout "D".

### Connected to the Wheel Base

When connected to the wheel base accessory port (sub-device 03), gears 1 to 7 and Reverse report on DirectInput button indices 12 to 19 (hardware-verified 2026-10-29). Index 20 is unused.
When connected to a wheel base accessory port, gears 1 to 7 and Reverse report on DirectInput button indices 12 to 19 (hardware-verified 2026-10-29). Index 20 is used by the Racing Adapter DB9 Reverse.

| Index | Button / Gear | evdev Code | Wire bitmask (Report 0x08) |
|---|---|---|---|
Expand All @@ -64,14 +64,77 @@ When connected to the wheel base accessory port (sub-device 03), gears 1 to 7 an
| 17 | RS H-Shifter: Gear 6 | `0x2c1` (`BTN_TRIGGER_HAPPY2`) | Byte 2 bit 5 (`0x20`) |
| 18 | RS H-Shifter: Gear 7 | `0x2c2` (`BTN_TRIGGER_HAPPY3`) | Byte 2 bit 6 (`0x40`) |
| 19 | RS H-Shifter: Reverse | `0x2c3` (`BTN_TRIGGER_HAPPY4`) | Byte 3 bit 0 (`0x01`) |
| 20 | Unused | `0x2c4` (`BTN_TRIGGER_HAPPY5`) | - |
| 20 | Racing Adapter DB9 Reverse | `0x2c4` (`BTN_TRIGGER_HAPPY5`) | Byte 3 bit 1 (`0x02`) |

### Connected Directly to PC via USB

When connected directly to the PC via USB (`046d:c26b Logitech RS H-Shifter`), it enumerates as an independent joystick reporting 8 digital buttons:
- Buttons 0 to 6 (`0x120`..`0x126`): 1st through 7th gear
- Button 7 (`0x127`): Reverse (R)

## RS Shifter & Handbrake (046d:c278)

Dual-mode sim accessory featuring a physical toggle switch between progressive analog handbrake mode and dual-direction sequential shifter mode.

### Connected to the Wheel Base

When connected to a direct-drive wheel base accessory port (RS50 / G PRO):
- **Handbrake Mode**: Reports as the wheel base's handbrake axis (progressive 0–100%).
- **Sequential Shifter Mode**: Shift Up (pull back) and Shift Down (push forward) are routed directly by base firmware to the wheel paddle button codes:
- Shift Up: Right Paddle (`0x124`, `BTN_TOP2`)
- Shift Down: Left Paddle (`0x125`, `BTN_PINKIE`)

### Connected Directly to PC via USB

When connected directly to the PC via USB-C (`046d:c278 Logitech RS Shifter & Handbrake`), it enumerates as a standalone joystick:
- **Handbrake Mode**: Progressive 10-bit analog axis:
- `ABS_Z`: Handbrake lever travel (`0` relaxed .. `1023` fully pulled).
- **Sequential Shifter Mode**: Two digital momentary buttons:
- Button 0 (`0x120`, `BTN_TRIGGER`): Shift Up (pull back)
- Button 1 (`0x121`, `BTN_THUMB`): Shift Down (push forward)

## Logitech G Racing Adapter (046d:c273)

USB adapter connecting legacy G29/G920/G923 3-pedal sets and 6+R DB9 Driving Force shifters.

### Pedals (12-bit Analog Axes)

Connected via the adapter's dedicated pedal port:
| Pedal | evdev Axis | Raw Range | Notes |
|-------|------------|-----------|-------|
| Throttle | `ABS_Y` | `0`..`4095` | Full travel 12-bit progressive |
| Brake | `ABS_Z` | `0`..`4095` | Full travel 12-bit progressive |
| Clutch | `ABS_RX` | `0`..`4095` | Full travel 12-bit progressive |

### DB9 Driving Force Shifter (Digital Buttons)

Connected via the adapter's DB9 shifter port when the adapter is plugged directly into the PC via USB:
| Gear | evdev Code | DirectInput Button |
|------|------------|--------------------|
| 1st Gear | `0x120` (`BTN_TRIGGER`) | Button 0 |
| 2nd Gear | `0x121` (`BTN_THUMB`) | Button 1 |
| 3rd Gear | `0x122` (`BTN_THUMB2`) | Button 2 |
| 4th Gear | `0x123` (`BTN_TOP`) | Button 3 |
| 5th Gear | `0x124` (`BTN_TOP2`) | Button 4 |
| 6th Gear | `0x125` (`BTN_PINKIE`) | Button 5 |
| Reverse (Push-down + 6th) | `0x126` (`BTN_BASE`) | Button 6 |

### Connected to the Wheel Base

When the Racing Adapter is plugged into an RS50 / G PRO wheel base USB port (`wheel_accessory` reports `Racing Adapter`):
- **Pedals**: Routed through the wheel base's standard pedal axes (`ABS_RX` Throttle, `ABS_RY` Brake, `ABS_RZ` Clutch).
- **DB9 Driving Force Shifter**: Routed through the wheel base's standard H-shifter button slots (`0x12c`..`0x12f` for 1st–4th, `0x2c0`..`0x2c1` for 5th–6th, and `0x2c4` (`BTN_TRIGGER_HAPPY5`) for Reverse, hardware-verified 2026-11-09). In Desktop mode (`profile 0`), the kernel driver automatically enables `0x8120` (`GAMING_ATTACHMENTS`) slot routing and `0x1BC0` (`SYNC`) when the Racing Adapter sub-device is detected.

## Pedals Connected to Wheel Base

When pedals (and optional RS Shifter & Handbrake) are connected to a wheel base's ports, the evdev axis assignment depends on the wheel model (matching `pedal_axes` in `logi_wheel_core::evtest` and `HIDPP_DD_PEDAL_BASE_AXIS` in `hid-logitech-hidpp.c`):
| Axis | RS50 / G PRO | G923 (PlayStation `0xc266`/`0xc267`) | G923 (Xbox `0xc26e`) |
|------|--------------|--------------------------------------|----------------------|
| Throttle | `ABS_RX` | `ABS_Z` | `ABS_Y` |
| Brake | `ABS_RY` | `ABS_RZ` | `ABS_Z` |
| Clutch | `ABS_RZ` | `ABS_Y` | `ABS_RZ` |
| Handbrake | `ABS_Z` | - | - |

## G923

The G923's own button layout, hardware-captured 2026-07-27 by a guided live
Expand Down
12 changes: 7 additions & 5 deletions docs/SYSFS_API.md
Original file line number Diff line number Diff line change
Expand Up @@ -990,13 +990,15 @@ Include this output in bug reports - firmware-dependent behaviour

### wheel_accessory
**Access**: Read-only
**Values**: accessory device name, or `none`
**Values**: comma-separated list of active accessory names (e.g. `RS Shifter & Handbrake, RS H-Shifter, Racing Adapter`), or `none`

Presence signal for the base's optional accessories: the **RS Shifter &
Handbrake** and the **RS H-Shifter**, which plug into the base's USB-A
ports. Reports the RS Shifter & Handbrake's own HID++ device name, or
`RS H-Shifter`, or `none` when neither is attached. With both attached it
names the RS Shifter & Handbrake. Unlike the pedal/handbrake attributes
Handbrake**, the **RS H-Shifter**, and the **Logitech Racing Adapter**, which
plug into the base's USB-A ports. Reports the attached accessory's name
(`RS Shifter & Handbrake`, `RS H-Shifter`, or `Racing Adapter`), a
comma-separated list when multiple accessories are attached (e.g.
`RS Shifter & Handbrake, RS H-Shifter` or `RS Shifter & Handbrake, Racing Adapter`),
or `none` when none is attached. Unlike the pedal/handbrake attributes
below, this never returns an error: it exists precisely so apps can check
for an accessory without inferring presence from another attribute's error
code.
Expand Down
Loading
Loading