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
26 changes: 26 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,32 @@ changes to the sysfs surface, minor versions add supported wheels or
new attributes, patch versions are bug fixes and documentation. Pre-1.0
the contract is "it works on RS50 and G Pro as listed here".

## Unreleased

**An RS Shifter & Handbrake is never dropped from `wheel_accessory`.** When
the accessory's name could not be read, the driver left it out of the list
and only its settings showed it was there. It is now listed under the fixed
name `RS Shifter & Handbrake` in that case.

**The apps no longer mistake another accessory for the Shifter & Handbrake.**
Since 0.43.0 the attribute lists every attached accessory. The apps took any
list that was not `none` as the Shifter & Handbrake, so an H-Shifter or a
Racing Adapter on its own switched the handbrake settings on. They now look
for the Shifter & Handbrake's own entry.

**Plain language, continued.** The per-game setup text in the apps and in
`docs/GAME_SETUP.md` is rewritten in short sentences. The per-axis view
toggles are now called "response", as in "Throttle response".

**Specification corrections.** The FFB strength encoding is `Nm × 8192 - 1`
in both places it appears. The LIGHTSYNC slot name is 9 characters, as the
wheel accepts, not 8 or 15. The interface summary says which interface
carries HID++ and which carries the force stream. The RS50's force packets
are 64-byte reports with ID `0x01`. The SDK symbol counts were recounted
against the DLL (75 exports, 58 of them `logi*`) and the current game build
(59 of 63 lookups resolved). The sysfs identity attributes have their own
section in the reference and the wiki.

## 0.43.0 - 2026-11-14

**The Logitech RS H-Shifter works on the RS50 and the G PRO.** Plug it into
Expand Down
4 changes: 2 additions & 2 deletions docs/DINPUT_ESCAPE.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Everything here was measured on an RS50 (`046d:c276`) in Assetto Corsa EVO on
|---|---|
| Our shim registers the SDK | fixed; it was broken from 0.27.1 to 0.34.x by a quoting bug |
| The game loads the SDK | yes, verified by signature and loaded |
| The game resolves the SDK API | yes, 56 of 59 symbols |
| The game resolves the SDK API | yes, 59 of the 63 symbols it looks up; the other 4 were never exported (counted 2026-11-14) |
| The SDK opens the wheel | yes, interface `mi_02`, the TrueForce interface |
| The SDK writes to the wheel | **yes**, on endpoint 3, once the range questions are answered locally (see 2026-08-12 below) |
| The game streams torque | **yes**, `logiTrueForceSetTorqueKF` at ~190/sec |
Expand Down Expand Up @@ -186,7 +186,7 @@ backend, and raw HID stops being a trade-off.
- **The missing viscosity API.** The game resolves
`logiTrueForceGetViscosity`, `GetViscosityMax` and `SetViscosity`, and all
three fail. This is not the blocker. `1_3_11` and `1_3_12` have identical
76-symbol export sets, and neither has them. So no shipped G HUB provides
75-symbol export sets, and neither has them. So no shipped G HUB provides
them, and Windows users are equally without. The game probes optionally.
- **A G HUB agent.** The SDK and the effect driver both enumerate HID
themselves. Neither references `LGHUB`, a pipe, or a socket to one.
Expand Down
6 changes: 3 additions & 3 deletions docs/GAME_SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,9 +149,9 @@ the app's Setup page afterwards.

## What each recipe means

- **Install the shim.** Stage Logitech's signed SDK DLLs into the game's Proton prefix, from the app's Setup page or `tools/install-tf-shim.sh`. Install the TrueForce shim once, from the app's Setup page; launch options `logi-launch %command%` (it turns raw HID on, stages the proxy that answers the SDK's rotation question, without which the stock library stops steering and force on track, and everything else this game needs); turn Steam Input off. No engine-note texture merge here: ACC produces its own TrueForce audio, so the merge is not wired for it.
- **On a wheel with no SDK TrueForce.** Leave PROTON_ENABLE_HIDRAW unset: on this wheel it costs you force feedback. For haptics, turn this game on under Simulated TrueForce; logi-launch puts the telemetry relay in the game's prefix and starts the daemon for you, and that route is confirmed working on a G923. Steam Input off.
- **Launch via logi-ffb.** Launch options `logi-launch %command%` (it keeps raw HID off, runs the logi-ffb helper and puts the telemetry relay in the game's prefix for you); Steam Input off. Simulated TrueForce also needs the community rF2SharedMemoryMapPlugin installed in the game.
- **Install the shim.** Stage Logitech's signed SDK DLLs into the game's Proton prefix, from the app's Setup page or `tools/install-tf-shim.sh`. Install the TrueForce shim once, from the app's Setup page. Set the launch options to `logi-launch %command%`. logi-launch turns raw HID on. It stages the proxy that answers the SDK's rotation question. Without that proxy, the stock library stops steering and force on track. It also sets up everything else this game needs. Turn Steam Input off. There is no engine-note texture merge here. ACC produces its own TrueForce audio, so the merge is not wired for it.
- **On a wheel with no SDK TrueForce.** Leave PROTON_ENABLE_HIDRAW unset. On this wheel it costs you force feedback. For haptics, turn this game on under Simulated TrueForce. logi-launch puts the telemetry relay in the game's prefix. It also starts the daemon for you. That route is confirmed working on a G923. Turn Steam Input off.
- **Launch via logi-ffb.** Set the launch options to `logi-launch %command%`. logi-launch keeps raw HID off. It runs the logi-ffb helper. It puts the telemetry relay in the game's prefix for you. Turn Steam Input off. Simulated TrueForce also needs the community rF2SharedMemoryMapPlugin. Install that plugin in the game.
- **Nothing to do.** The wheel is an ordinary Linux force feedback device. The game drives it directly.

## Confidence
Expand Down
23 changes: 13 additions & 10 deletions docs/PROTOCOL_SPECIFICATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -475,14 +475,14 @@ All non-calibration commands use Short HID++ (`0x10`) with device index `0xFF`.
```
Set: 10 FF 16 2D [Value_Hi] [Value_Lo] 00
```
**Encoding**: Value = Nm × 8192 (range 1.0-8.0 Nm with 0.1 Nm steps)
**Encoding**: Value = Nm × 8192 - 1, rounded down (range 1.0-8.0 Nm with 0.1 Nm steps). This is the same formula as the compat-mode table in section 5.1.

| Value | Nm | Formula |
|-------|-----|---------|
| `0x1FFF` | 1.0 Nm | 1.0 × 8192 ≈ 8191 |
| `0x4FFF` | 2.5 Nm | 2.5 × 8192 ≈ 20479 |
| `0x7FFF` | 4.0 Nm | 4.0 × 8192 ≈ 32767 |
| `0xC998` | 6.3 Nm | 6.3 × 8192 ≈ 51608 |
| `0x1FFF` | 1.0 Nm | 1.0 × 8192 - 1 = 8191 |
| `0x4FFF` | 2.5 Nm | 2.5 × 8192 - 1 = 20479 |
| `0x7FFF` | 4.0 Nm | 4.0 × 8192 - 1 = 32767 |
| `0xC998` | 6.3 Nm | 6.3 × 8192 - 1 ≈ 51608 |
| `0xFFFF` | 8.0 Nm | Maximum torque |

**Driver Formula**: `value = (uint16_t)(nm * 8191.875)` or `value = nm * 0xFFFF / 8.0`
Expand Down Expand Up @@ -925,7 +925,7 @@ A few behaviors observed in compat mode look like driver problems. They are firm
- **Default steering angle is 90°**: the factory default angle in compat mode is 90°, not the wheel's 1080° hardware maximum. This is correct firmware behavior. To set it from Linux: first write `wheel_profile=0`, then write `wheel_range=<degrees>`. Or set it from the OLED by editing the active onboard profile.
- **LIGHTSYNC works in compat mode**: feature `0x807A` is advertised in compat at the same index that discovery picks up in native. `wheel_led_*` writes drive the LED strip end-to-end (verified 2026-04-29). An earlier draft of this document claimed otherwise. That claim was incorrect.

### 5.3 Sub-device Addressing (HID++ dev_idx 0x01 / 0x02 / 0x05)
### 5.3 Sub-device Addressing (HID++ dev_idx 0x01 to 0x05; the index is the port)

Cross-capture census (2026-07-02, all 62 captures): the wheel base sits at
dev_idx `0xff` (~100k packets each way). Besides it, three sub-devices
Expand Down Expand Up @@ -1210,7 +1210,7 @@ again.
| Feature | G920/G923 | RS50 |
|---------|-----------|------|
| FFB Method | HID++ Feature 0x8123 | Dedicated endpoint 0x03 |
| FFB Commands | Via HID++ FAP messages | Raw HID output reports (05 XX) |
| FFB Commands | Via HID++ FAP messages | Raw 64-byte output reports, report ID 0x01 (section 4) |
| Report ID | 0x11/0x12 | 0x01 (custom) |
| Sequence Field | 2 bytes | 1 byte |
| Max Rotation | 900° | 2700° |
Expand Down Expand Up @@ -1253,7 +1253,7 @@ queue-saturation failures). But a minimal 0x8123-fn2 force-target sender
remains an untested alternative transport. It could matter if the wheel's
FFB-filter smoothing turns out to apply only to that path.

**Interface initialization**: FFB must be initialized on Interface 1 (HID++), not Interface 0 (joystick). Interface 0 has no HID++ support.
**Interfaces**: HID++ lives on Interface 1. That is where feature `0x8123` and the settings (strength, range, filters) are written. The endpoint `0x03` force stream, and the session init that opens it (see `TRUEFORCE_PROTOCOL.md`), live on Interface 2. Interface 0 (joystick) carries neither and has no HID++ support.

---

Expand Down Expand Up @@ -1498,7 +1498,7 @@ Interpretation: May enumerate effect types or zone capabilities (appears to be z
│ │ │ │ │
│ │ │ │ └── LED count (10)
│ │ │ └───── Unknown (1)
│ │ └──────── Max name length (8 characters)
│ │ └──────── Max name length as advertised (8; the wheel accepts 9, see 9.6)
│ └─────────── Number of slots (5)
└────────────── Number of slots (5, duplicated)
```
Expand Down Expand Up @@ -1701,7 +1701,10 @@ Custom slots can have user-defined names (shown in G Hub UI).
12 FF [idx] 4C [slot] [len] [ASCII name, null-padded]...
```

Name is up to 15 ASCII characters. Default names: "CUSTOM 1" through "CUSTOM 5".
The wheel accepts a name of up to 9 ASCII characters and stores it in upper
case (hardware-verified 2026-07-16). fn0 advertises 8. A longer name is
refused by the wheel, which the driver reports as `EIO`. Default names:
"CUSTOM 1" through "CUSTOM 5".

### 9.7 Protocol Examples

Expand Down
7 changes: 4 additions & 3 deletions docs/SDK_ABI_NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,9 +126,10 @@ that added this section.

## Which SDK a game uses

Grep the game binary. Assetto Corsa Competizione resolves 56 symbols from
the TrueForce SDK, including all four rotation getters. It resolves none at
all from the legacy Steering Wheel SDK:
Grep the game binary. Assetto Corsa Competizione resolves 59 symbols from
the TrueForce SDK (57 `logi*` calls plus `dllOpen` and `dllClose`, counted
2026-11-14 on the current build), including all four rotation getters. It
resolves none at all from the legacy Steering Wheel SDK:

```bash
strings -n 6 AC2-Win64-Shipping.exe | grep -E "^(logi|Logi|dll)[A-Za-z]" | sort -u
Expand Down
6 changes: 4 additions & 2 deletions docs/SYSFS_API.md
Original file line number Diff line number Diff line change
Expand Up @@ -1000,6 +1000,8 @@ G PRO. Reports are welcome (issue tracker).**
echo 7 > wheel_rev_level
```

## Identity

### wheel_serial
**Access**: Read-only
**Values**: 12-character device serial
Expand Down Expand Up @@ -1032,8 +1034,8 @@ Presence signal for the base's optional accessories: the **RS Shifter &
Handbrake**, the **RS H-Shifter** and the **Logitech Racing Adapter**. They
plug into the base's USB-A ports. The attribute lists the attached
accessories by name, separated by commas, always in this order: the RS
Shifter & Handbrake (its own HID++ device name), `RS H-Shifter`, `Racing
Adapter`. It reads `none` when no accessory is attached. Unlike the
Shifter & Handbrake (its own HID++ device name, or `RS Shifter & Handbrake`
when that name could not be read), `RS H-Shifter`, `Racing Adapter`. It reads `none` when no accessory 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
4 changes: 2 additions & 2 deletions docs/TRUEFORCE_PROTOCOL.md
Original file line number Diff line number Diff line change
Expand Up @@ -496,7 +496,7 @@ Used for constant force values with extended precision.
| `userspace/libtrueforce/src/tf_init_data.h` | 68 canonical init packets, auto-generated from capture, sent twice at session bring-up |
| `userspace/libtrueforce/src/session.c` | `logitf_session_ensure()` opens the hidraw node and runs the two-pass init |
| `userspace/libtrueforce/src/stream.c` | 1000 Hz timerfd loop (`LOGITF_TF_PKT_HZ`), 13-slot rolling window, `logitf_stream_push_s16()` / `_clear()` / `_start/stop()` |
| `userspace/libtrueforce/include/trueforce.h` | Mirrors the 62 exports of `trueforce_sdk_x64.dll` (Windows SDK) so a Linux app can call the same API surface |
| `userspace/libtrueforce/include/trueforce.h` | Declares the 58 `logi*` functions that `trueforce_sdk_x64.dll` (Windows SDK 1.3.11, 75 exports in all) exports, so a Linux app can call the same API surface. The DLL's other 17 exports are `dllOpen`/`dllClose`, two COM registration stubs and 13 mangled C++ internals |

## Open Items

Expand Down Expand Up @@ -545,6 +545,6 @@ other call to Logitech's own library and answers only the rotation getters.
Signatures for those are in `docs/SDK_ABI_NOTES.md`, taken from the library's
machine code rather than from any header.

Assetto Corsa Competizione resolves 56 symbols from this SDK, including all
Assetto Corsa Competizione resolves 59 symbols from this SDK, including all
four rotation getters, and none at all from the older Steering Wheel SDK. So
for that title this is the right library to answer through.
19 changes: 9 additions & 10 deletions mainline/hid-logitech-hidpp.c
Original file line number Diff line number Diff line change
Expand Up @@ -8727,9 +8727,9 @@ static int hidpp_dd_read_device_name(struct hidpp_device *hidpp, u8 dev_idx,
* Read the RS Shifter & Handbrake accessory's own DeviceNameType (0x0005)
* name into ff->accessory_name, once the accessory has been confirmed at
* dev_idx (see hidpp_dd_discover_settings_features). Best-effort: any
* failure leaves accessory_name empty, which wheel_accessory_show reports
* as "none" - the same as a genuinely absent accessory, since without a
* name the sysfs attribute cannot usefully distinguish the two anyway.
* failure leaves accessory_name empty, and wheel_accessory_show then lists
* the accessory under the fixed name "RS Shifter & Handbrake" instead, so a
* confirmed accessory is never reported as absent.
*/
static void hidpp_dd_query_accessory_name(struct hidpp_dd_ff_data *ff, u8 dev_idx)
{
Expand Down Expand Up @@ -8768,10 +8768,9 @@ static void hidpp_dd_adopt_shifter_handbrake(struct hidpp_dd_ff_data *ff,
* 2026-10-29). Only called for a candidate already known to answer, so the
* normal transport timeout is fine: a silent index never gets this far.
*
* On a hit this records the feature index and, unless an accessory with a
* queried name already owns it, the wheel_accessory text. The caller
* publishes h_shifter_dev_idx itself, last, because that is what the
* readers gate on.
* On a hit this records the feature index. The caller publishes
* h_shifter_dev_idx itself, last, because that is what the readers gate
* on, and wheel_accessory_show derives its text from that index.
*/
static bool hidpp_dd_probe_h_shifter(struct hidpp_dd_ff_data *ff, u8 cand)
{
Expand Down Expand Up @@ -15356,14 +15355,14 @@ static ssize_t wheel_accessory_show(struct device *dev,
jiffies + HIDPP_DD_ACCESSORY_RESCAN_INTERVAL);
queue_work(ff->wq, &ff->accessory_rescan_work);
}
has_shifter = READ_ONCE(ff->shifter_dev_idx) != HIDPP_DD_FEATURE_NOT_FOUND &&
ff->accessory_name[0];
has_shifter = READ_ONCE(ff->shifter_dev_idx) != HIDPP_DD_FEATURE_NOT_FOUND;
has_h_shifter = READ_ONCE(ff->h_shifter_dev_idx) != HIDPP_DD_FEATURE_NOT_FOUND;
has_adapter = READ_ONCE(ff->adapter_dev_idx) != HIDPP_DD_FEATURE_NOT_FOUND;
if (!has_shifter && !has_h_shifter && !has_adapter)
return sysfs_emit(buf, "none\n");
if (has_shifter)
len += sysfs_emit_at(buf, len, "%s", ff->accessory_name);
len += sysfs_emit_at(buf, len, "%s", ff->accessory_name[0] ?
ff->accessory_name : "RS Shifter & Handbrake");
if (has_h_shifter)
len += sysfs_emit_at(buf, len, "%sRS H-Shifter", len ? ", " : "");
if (has_adapter)
Expand Down
52 changes: 44 additions & 8 deletions userspace/logi-wheel/crates/logi-wheel-core/src/device.rs
Original file line number Diff line number Diff line change
Expand Up @@ -822,28 +822,29 @@ impl<S: SysfsIo> Device<S> {
}
}

/// The RS Shifter & Handbrake's entry in `wheel_accessory`, or `None`
/// when the attribute is missing, unreadable, `none`, or lists only
/// other accessories. The driver lists every attached accessory,
/// comma-separated (`RS Shifter & Handbrake, RS H-Shifter, Racing
/// Adapter`), so the entry has to be picked out: an H-Shifter or a
/// Racing Adapter on its own must not light up the handbrake settings.
pub fn accessory_name(&self) -> Option<String> {
if !self.io.exists("wheel_accessory") {
return None;
}
let raw = self.io.read("wheel_accessory").ok()?;
let t = raw.trim();
if t.is_empty() || t == "none" {
return None;
}
Some(t.to_string())
shifter_handbrake_entry(&raw).map(str::to_string)
}

pub fn accessory_attached(&self) -> Option<bool> {
if !self.io.exists("wheel_accessory") {
return None;
}
let raw = self.io.read("wheel_accessory").ok()?;
let t = raw.trim();
if t.is_empty() {
if raw.trim().is_empty() {
return None;
}
Some(t != "none")
Some(shifter_handbrake_entry(&raw).is_some())
}

pub fn write(&self, attr: &str, v: &Value) -> Result<(), Error> {
Expand Down Expand Up @@ -914,6 +915,21 @@ impl<S: SysfsIo> Device<S> {
}
}

/// The RS Shifter & Handbrake's entry in a `wheel_accessory` value, which is
/// `none` or a comma-separated list of accessory names. The entry is whatever
/// is not one of the two fixed names the driver uses for the other
/// accessories: normally the device's own HID++ name, `RS Shifter &
/// Handbrake`, but the driver may report a firmware variant of it.
fn shifter_handbrake_entry(raw: &str) -> Option<&str> {
let t = raw.trim();
if t.is_empty() || t == "none" {
return None;
}
t.split(',')
.map(str::trim)
.find(|e| !e.is_empty() && *e != "RS H-Shifter" && *e != "Racing Adapter")
}

#[cfg(test)]
mod tests {
use super::*;
Expand Down Expand Up @@ -1093,6 +1109,26 @@ mod tests {
assert_eq!(d.read_supported("wheel_handbrake_curve").unwrap(), None);
}

#[test]
fn handbrake_settings_stay_hidden_when_only_other_accessories_are_attached() {
// Since the driver lists every attached accessory, an H-Shifter or a
// Racing Adapter alone must not count as the Shifter & Handbrake.
for list in ["RS H-Shifter", "Racing Adapter", "RS H-Shifter, Racing Adapter"] {
let d = dev_with_accessory(Some(list));
assert_eq!(d.accessory_attached(), Some(false), "{list}");
assert_eq!(d.accessory_name(), None, "{list}");
assert!(!d.available("wheel_handbrake_sensitivity"), "{list}");
}
}

#[test]
fn handbrake_settings_are_available_with_the_accessory_in_a_list() {
let d = dev_with_accessory(Some("RS Shifter & Handbrake, RS H-Shifter, Racing Adapter"));
assert_eq!(d.accessory_attached(), Some(true));
assert_eq!(d.accessory_name().as_deref(), Some("RS Shifter & Handbrake"));
assert!(d.available("wheel_handbrake_sensitivity"));
}

#[test]
fn handbrake_settings_are_available_with_the_accessory_attached() {
let d = dev_with_accessory(Some("RS Shifter & Handbrake"));
Expand Down
Loading
Loading