From e4802dd8fa950a8b331162d0a0749f5a6d7993c9 Mon Sep 17 00:00:00 2001 From: mescon <5875228+mescon@users.noreply.github.com> Date: Fri, 6 Nov 2026 19:17:18 +0100 Subject: [PATCH 1/3] docs: 0.43.0 release prep (changelog, credits, H-Shifter in README and matrix, USB enumeration troubleshooting) --- CHANGELOG.md | 34 ++++++++++++++++++++++++++++++++++ CREDITS.md | 9 ++++++++- README.md | 27 +++++++++++++++++++++++++-- docs/FEATURE_MATRIX.md | 5 +++-- 4 files changed, 70 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc6290f..1cc88b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,40 @@ 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". +## 0.43.0 - Unreleased + +**The Logitech RS H-Shifter works on the RS50 and the G PRO.** Plug it into +an accessory port on the wheel base. The driver finds it when the module +loads and when you plug it in later. The seven gates and reverse report as +buttons 12 to 19. In desktop mode, with no game running, the driver turns +on the base's routing for the shifter, so the gates also work on the +desktop. The Info page in logi-wheel shows the gate that is in, and whether +the shifter sits on the base or on its own USB cable. Written and tested on +real hardware by gonzaloadrio ([#140](../../pull/140)). + +**`wheel_accessory` now names the H-Shifter.** A read of the attribute +re-checks the accessory ports, so a shifter plugged in after boot shows up +on the next read. With an RS Shifter & Handbrake and an H-Shifter attached +at the same time, the attribute names the Shifter & Handbrake. Showing both +is tracked in [#144](../../issues/144). + +**Module load did not get slower.** The H-Shifter probe runs inside the one +accessory pass that already existed, so a wheel without accessories pays +nothing extra. + +**pulldown-cmark 0.13.6** clears advisory RUSTSEC-2026-0414 in the Rust +workspace ([#142](../../pull/142)). + +**Troubleshooting now covers a wheel that never enumerates.** A front-panel +USB port can fail the USB link before any driver runs. The kernel log shows +`disabled by hub (EMI?)` or `error -71`. A rear port fixes it +([#141](../../issues/141)). + +Thanks to gonzaloadrio for the shifter work and the hot-plug test runs, to +kangaro0 for the first power-up report that found the port problem, and to +fenixadam for the Windows captures in +[#134](../../issues/134) and [#135](../../issues/135). + ## 0.42.6 - 2026-10-22 **A kernel oops on the G923 PS edition when the wheel is unplugged or the diff --git a/CREDITS.md b/CREDITS.md index 42be322..9b3d621 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -33,7 +33,10 @@ until the last round. ([#83](../../issues/83)) is his too. And after weeks of a freeze that left nothing in any log, he disabled his iGPU to see the panic on screen and photographed it, which named the stale reply buffer fixed in 0.42.5 - ([#128](../../issues/128)). + ([#128](../../issues/128)). The Windows captures in + [#134](../../issues/134) and [#135](../../issues/135) then showed that the + wire traffic is the same on both systems, which put the pedal inversion + on the Windows side and closed a long thread with evidence. - **[DaveDos95](https://github.com/DaveDos95)** - RaceRoom on an RS50 under SteamOS ([#92](../../issues/92)): read the game's own profile file to rule out the first diagnosis, then produced the proxy logs that proved the real @@ -93,6 +96,10 @@ until the last round. ## Sustained bug reporting +- **[kangaro0](https://github.com/kangaro0)** - an RS50 that never showed + up on first power-up ([#141](../../issues/141)). The kernel log in that report + named the real cause, a front-panel USB port failing the link before any + driver ran, which is now a troubleshooting entry for everyone after him. - **[Ismael-Torresan](https://github.com/Ismael-Torresan)** - the only quantitative measurements the force engine has: a fixed push over a fixed travel, timed, for damper, friction and inertia on both the firmware's diff --git a/README.md b/README.md index 8510d22..68ca862 100644 --- a/README.md +++ b/README.md @@ -164,8 +164,8 @@ cancelable force tests. ## What works -Force feedback, TrueForce haptics, LEDs, pedals, the RS Shifter & Handbrake, and -the full set of G HUB wheel settings all work. The RS50 is the development +Force feedback, TrueForce haptics, LEDs, pedals, the RS Shifter & Handbrake, +the RS H-Shifter, and the full set of G HUB wheel settings all work. The RS50 is the development hardware and is verified directly; the G PRO runs the same code path and is expected to work, with a few items awaiting an owner's confirmation. @@ -181,6 +181,7 @@ to work ยท ๐ŸŸก needs a tester ยท `-` not applicable. | Rotation range (90 to 2700ยฐ), strength, damping, filters | โœ… | ๐ŸŸข | | Pedal response curves, sensitivity, deadzones, combined pedals | โœ… | ๐ŸŸข | | RS Shifter & Handbrake (shift, digital + analog handbrake) | โœ… | ๐ŸŸข | +| RS H-Shifter (7 gates + reverse, works on the desktop, hot-plug) | โœ… | ๐ŸŸข | | LIGHTSYNC RGB LEDs (slots, colors, direction; edits apply live) | โœ… (faceplate strip, see note) | ๐ŸŸก (rev lights) | | RPM rev-light display (level fill; drawn center-out by default - the strip's pattern comes from the wheel's stored display config, separate from the level itself) | โœ… | ๐ŸŸก | | Native texture merge + telemetry rev lights in AC EVO (relay triple -> logi-rpm-bridge -> wheel) | โœ… | ๐ŸŸข | @@ -627,6 +628,13 @@ handbrake curve is live while the two trigger points are not. ![logi-wheel-gui RS Shifter and Handbrake settings](docs/images/logi-wheel-accessory.png) +The **RS H-Shifter** works the same way. Plug it into an accessory port on +the base and its seven gates and reverse appear as buttons 12 to 19. The +driver also turns on the base's routing for it in desktop mode, so the gates +work outside a game. The Info / Testing page shows which gate is in. Plug +the shifter straight into the computer by USB instead and the page reads it +there too, with the mode shown next to the gate. + The Info / Testing page doubles as a live input tester (does this button reach the computer?), and the Setup page manages the game helpers: @@ -671,6 +679,21 @@ keeping hands clear during AC EVO map loads) are covered under logi-wheel --report ``` +### The wheel never shows up, or drops off the bus + +If the wheel is missing from `lsusb`, or appears and vanishes, read the +kernel log before you suspect the driver: + +```bash +sudo dmesg | grep -i usb | tail -n 30 +``` + +Lines like `disabled by hub (EMI?)`, `device descriptor read/64, error -71` +or `unable to enumerate USB device` mean the USB link itself failed. That +happens before any driver runs. The usual cause is a front-panel USB port or +a hub. Move the wheel to a port on the back of the computer, on the +mainboard, and power the wheel off and on ([#141](../../issues/141)). + ### No force feedback once the raw HID interface is on Some games drive force feedback the older Windows way, which needs a part of diff --git a/docs/FEATURE_MATRIX.md b/docs/FEATURE_MATRIX.md index 6f1f68a..5a1d34a 100644 --- a/docs/FEATURE_MATRIX.md +++ b/docs/FEATURE_MATRIX.md @@ -14,8 +14,9 @@ HID++ features (base): 8040=0A 807A=0B 807B=0C 80A4=0D 80D0=0E ... ## Read this before drawing conclusions from it **These are BASE-DEVICE answers.** HID++ sub-devices answer separately: the -RS Shifter & Handbrake reports at device index `0x04`, and its features -error out here rather than reporting themselves. `0x80B1 BANDED_AXIS` and +RS Shifter & Handbrake reports at device index `0x04`, the RS H-Shifter +(`0x812D RS_H_SHIFTER`) at the index of the port it is plugged into, and +their features error out here rather than reporting themselves. `0x80B1 BANDED_AXIS` and `0x812C WHEEL_CENTER_POSITION` show as absent on the RS50 below and the driver demonstrably uses both. Absence in this table means "not on the base device", not "not on the wheel". From cd65809207700d1072d490075908269100afbbca Mon Sep 17 00:00:00 2001 From: mescon <5875228+mescon@users.noreply.github.com> Date: Fri, 6 Nov 2026 19:38:19 +0100 Subject: [PATCH 2/3] docs: plain-language pass over the README and every document Short sentences, active voice, one idea per sentence, technical terms explained on first use, instructions as ordered steps. Reference documents (protocol spec, sysfs reference, TrueForce notes) keep every table, byte layout and code block unchanged; only the prose moved. Stale facts corrected against the driver source on the way: the effect loop and the TrueForce packet cadence are 1 kHz (the docs still said 500 and 250 Hz in places), LED effect modes 3 and 4 were swapped in the sysfs table, the G923 Xbox range_restore default is on, the OLED feature row in the matrix, the rev-light write cadence, the G Hub software id, and the open-item list in STATUS. docs/GAME_SETUP.md is regenerated from its generator. --- README.md | 873 ++++----- docs/BUTTON_MAPPING.md | 52 +- docs/DINPUT_ESCAPE.md | 275 +-- docs/FEATURE_MATRIX.md | 134 +- docs/GAME_SETUP.md | 118 +- docs/LAUNCH_OPTIONS.md | 496 ++--- docs/NATIVE_TF_TEXTURE_MERGE_DESIGN.md | 208 ++- docs/PROTOCOL_SPECIFICATION.md | 1597 +++++++++-------- docs/ROADMAP.md | 56 +- docs/SCS_PLUGIN.md | 92 +- docs/SDK_ABI_NOTES.md | 82 +- docs/SECURITY_ASSURANCE.md | 186 +- docs/SHARED_MEMORY_RELAY.md | 210 +-- docs/STATUS.md | 264 +-- docs/SYSFS_API.md | 1316 +++++++------- docs/TF_TEXTURE_RECIPE.md | 69 +- docs/TRUEFORCE_PROTOCOL.md | 284 +-- .../logi-wheel-core/tests/game_setup_doc.rs | 116 +- 18 files changed, 3355 insertions(+), 3073 deletions(-) diff --git a/README.md b/README.md index 68ca862..21b8ad9 100644 --- a/README.md +++ b/README.md @@ -16,87 +16,100 @@ [![Nix flake](https://github.com/mescon/logitech-trueforce-linux-driver/actions/workflows/nix.yml/badge.svg)](https://github.com/mescon/logitech-trueforce-linux-driver/actions/workflows/nix.yml) [![License: GPL-2.0](https://img.shields.io/badge/license-GPL--2.0-blue.svg)](https://github.com/mescon/logitech-trueforce-linux-driver/blob/master/COPYING) -A Linux kernel driver and userspace tools for three Logitech racing wheels: -the direct-drive **RS50** and **G PRO Racing Wheel**, and the gear-driven -**G923**. It brings force feedback, TrueForce haptics, a live RPM rev-light -display, LIGHTSYNC LED control, and G HUB-equivalent wheel settings to Linux, -including in Proton/Wine sims. +This is a Linux kernel driver, plus userspace tools, for three Logitech +racing wheels: the direct-drive **RS50** and **G PRO Racing Wheel**, and the +gear-driven **G923**. The kernel driver is the part of Linux that talks to +the hardware. The userspace tools are normal programs that run on top of it. +Together they give you force feedback, TrueForce haptics, a live RPM +rev-light display, LIGHTSYNC LED control, and every wheel setting G HUB +offers. That includes sims running under Proton (Steam's layer for running +Windows games on Linux) and Wine (the project Proton is built on). **This is the first TrueForce implementation on Linux.** TrueForce is -Logitech's high-frequency haptic layer - engine note, road surface and tyre -texture felt through the rim, on top of ordinary force feedback - and until -this project it did not exist here at all. It arrives two ways: - -- **Native**, in sims that support Logitech's SDK. The steering force is the - game's own signal, carried to the wheel unchanged. The engine texture on - top is synthesised by the driver stack from the game's live telemetry - - which is how TrueForce texture works on every platform: on Windows too, - the game supplies force and telemetry and the driver stack supplies the - texture. This driver replicates that architecture in the kernel. +Logitech's high-frequency haptic layer. It is the engine note, road surface +and tyre texture you feel through the rim, on top of ordinary force feedback. +Before this project it did not exist on Linux at all. It arrives two ways: + +- **Native**, in sims that support Logitech's SDK (the software kit Logitech + gives game developers). The steering force is the game's own signal, + carried to the wheel unchanged. The driver stack synthesises the engine + texture on top from the game's live telemetry (the car data a game sends + out: RPM, speed, and so on). That is how TrueForce texture works on every + platform. On Windows too, the game supplies force and telemetry, and the + driver stack supplies the texture. This driver does the same job in the + kernel. - **Simulated**, in everything else. Where a game has no TrueForce, - `logi-tf-sim` synthesises it from that game's live telemetry - engine RPM, - speed, surface - so wheels still get texture in titles that never shipped - support for it. + `logi-tf-sim` synthesises it from that game's live telemetry: engine RPM, + speed, surface. So your wheel still gets texture in titles that never + shipped support for it. -The **G923** matters as much here as the direct-drive wheels. It is the only -Linux driver that gives it TrueForce, and the only one that gives the -PlayStation edition force feedback at all - that edition had none on Linux -before this. See [G923 support](#g923-support). +The **G923** matters as much here as the direct-drive wheels. This is the +only Linux driver that gives it TrueForce. It is also the only one that gives +the PlayStation edition any force feedback at all. That edition had none on +Linux before this. See [G923 support](#g923-support). > The older **G920** is already served by the in-tree `hid-logitech-hidpp` -> driver and does not need this one. +> driver (the one that ships inside the kernel itself). It does not need +> this one. ## Getting started -Four steps, whichever of these wheels you own. +Five steps, whichever of these wheels you own. -**1. Install it.** One command on most distributions: find yours in +**1. Install it.** One command on most distributions. Find yours in [Install](#install) below. -**2. Plug the wheel in and open Logi Wheel.** `logi-wheel-gui` for the desktop -app, `logi-wheel` for the terminal one. It finds the wheel and shows every -setting that wheel supports. +**2. Plug the wheel in and open Logi Wheel.** Run `logi-wheel-gui` for the +desktop app, or `logi-wheel` for the terminal one. It finds the wheel and +shows every setting that wheel supports. -**3. Set your games up from its Setup page.** It lists the sims it found -across Steam, Lutris and Heroic, and each row has the buttons for that game: +**3. Set your games up from its Setup page.** The page lists the sims it +found across Steam, Lutris and Heroic. Each row has the buttons for that game: - **Install relay** puts the telemetry relay into that game's Proton folder. - This is what feeds simulated TrueForce and the rev lights in sims that keep - their telemetry in shared memory (the Assetto Corsa family, iRacing, - RaceRoom, rFactor 2, Le Mans Ultimate). + The relay is what feeds simulated TrueForce and the rev lights in sims that + keep their telemetry in shared memory (a block of memory the game lets other + programs read). That is the Assetto Corsa family, iRacing, RaceRoom, + rFactor 2 and Le Mans Ultimate. - **Install TrueForce files** puts Logitech's own TrueForce files into that - game's Proton folder, for sims with TrueForce built in (Assetto Corsa - Competizione, Assetto Corsa EVO) on a **direct-drive wheel**. This needs a + game's Proton folder. Use it for sims with TrueForce built in (Assetto Corsa + Competizione, Assetto Corsa EVO) on a **direct-drive wheel**. It needs a one-time copy first; see below. A G923 does not use this route and can skip it, because that wheel does not answer Logitech's SDK. - **With these files installed, this is the configuration to want**: the - game's own force reaches the wheel unchanged, with the engine texture - synthesised from its live telemetry - the same division of labour the - Windows driver stack uses, done here in the kernel. - - **Without them, do not switch the raw HID interface on.** Reaching that - interface is what lets Logitech's SDK deliver TrueForce, and switching it - on replaces the ordinary path force feedback arrives by. The raw interface - offers no force feedback of its own, so with it on and the files missing - you get neither. `logi-launch` will not make that trade: it leaves the raw - interface alone until the files are there, so force feedback keeps working - and you get simulated TrueForce meanwhile. - -> **The one-time copy: Logitech's TrueForce files.** They cannot be -> redistributed, so you supply them from a Windows G HUB installation. Copy -> the whole `Logi` folder to `~/.local/share/logitech-trueforce/sdk`, keeping -> its own layout, so you end up with: + **With these files installed, this is the setup you want.** The game's own + force reaches the wheel unchanged. The driver synthesises the engine + texture from the game's live telemetry. That is the same division of labour + the Windows driver stack uses, done here in the kernel. + + **Without them, do not switch the raw HID interface on.** HID is the USB + protocol for input devices. The raw HID interface gives a game direct + access to the wheel's USB reports. Logitech's SDK needs that access to + deliver TrueForce. But switching it on also replaces the normal path force + feedback arrives by. The raw interface offers no force feedback of its own. + So with it on and the files missing, you get neither. `logi-launch` will + not make that trade. It leaves the raw interface alone until the files are + there, so force feedback keeps working and you get simulated TrueForce + meanwhile. + +> **The one-time copy: Logitech's TrueForce files.** Nobody may redistribute +> them, so you supply them yourself from a Windows G HUB installation. > -> ``` -> ~/.local/share/logitech-trueforce/sdk/Logi/Trueforce//trueforce_sdk_x64.dll -> ~/.local/share/logitech-trueforce/sdk/Logi/wheel_sdk//logi_steering_wheel_x64.dll -> ``` +> 1. Find the `Logi` folder in a Windows G HUB installation. +> 2. Copy the whole folder to `~/.local/share/logitech-trueforce/sdk`. Keep +> its own layout, so you end up with: > -> Whatever version numbers your G HUB shipped are the right ones. The Setup -> page's **TrueForce files** section shows the folder it is reading and says -> whether it found them, so you can check before installing to a game. To keep -> them somewhere else, set the folder there. +> ``` +> ~/.local/share/logitech-trueforce/sdk/Logi/Trueforce//trueforce_sdk_x64.dll +> ~/.local/share/logitech-trueforce/sdk/Logi/wheel_sdk//logi_steering_wheel_x64.dll +> ``` +> +> 3. Open the Setup page's **TrueForce files** section. It shows the folder +> it is reading and says whether it found the files. Check that before you +> install them to a game. +> +> Whatever version numbers your G HUB shipped are the right ones. To keep the +> files somewhere else, set the folder on that page. **4. Put one launch option on each sim.** In Steam: Properties, General, Launch Options. @@ -105,22 +118,24 @@ Launch Options. logi-launch %command% ``` -That line is the same for every game and every wheel, and for most people it -is the only setup step. `logi-launch` works out what this game needs on the -wheel you have plugged in, and does it: force feedback for older DirectInput -sims, the game's own TrueForce where it supports it, simulated TrueForce and -live rev lights everywhere else. For native-SDK sims like AC EVO it also -arranges the in-kernel texture merge and the telemetry rev-light chain: the -SDK proxy relays the game's live rpm, first-shift-light rpm and redline, -and `logi-rpm-bridge` feeds them to the wheel as engine texture -(`wheel_texture_rpm`) and rev-light levels (`wheel_rev_level`). -Logi Wheel's Setup page shows what it will do -for each of your games, which differs by wheel. Full detail in +That line is the same for every game and every wheel. For most people it is +the only setup step. `logi-launch` works out what this game needs on the +wheel you have plugged in, and does it. Older DirectInput sims get force +feedback (DirectInput is the older Windows game-controller interface). Sims +with their own TrueForce get that. Everything else gets simulated TrueForce +and live rev lights. For native-SDK sims like AC EVO it also sets up +the in-kernel texture merge and the telemetry rev-light chain. The SDK proxy +(a helper the game loads next to Logitech's SDK) relays the game's live rpm, +first-shift-light rpm and redline. `logi-rpm-bridge` then feeds them to the +wheel as engine texture (`wheel_texture_rpm`) and rev-light levels +(`wheel_rev_level`). Logi Wheel's Setup page shows what it will do for each +of your games. That differs by wheel. Full detail in [docs/LAUNCH_OPTIONS.md](docs/LAUNCH_OPTIONS.md). -One thing it cannot do for you: **turn Steam Input off** for the game -(Properties, Controller, "Disable Steam Input"). Left on, it hides the wheel -behind a virtual gamepad and force feedback never arrives. +**5. Turn Steam Input off for the game.** In Steam: Properties, Controller, +"Disable Steam Input". This is the one thing `logi-launch` cannot do for +you. Left on, Steam Input hides the wheel behind a virtual gamepad, and force +feedback never arrives. ### Which wheel do I have? @@ -130,44 +145,47 @@ lsusb | grep -i 046d | Product id | Wheel | What you get | |---|---|---| -| `c275`, `c276` | RS50 (both editions) | Everything: force feedback, the game's own TrueForce and simulated TrueForce, rev lights, every setting. The Xbox edition plugs in as `c275` and is switched to `c276` automatically, after which it is the same wheel to everything here. Needs `usb_modeswitch` installed. | -| `c272` | RS50 in compatibility mode, **or** a G PRO (Xbox/PC) | Same as above. The two share this id; Logi Wheel names which one it found. | +| `c275`, `c276` | RS50 (both editions) | Everything: force feedback, the game's own TrueForce and simulated TrueForce, rev lights, every setting. The Xbox edition plugs in as `c275`. The driver switches it to `c276` automatically. After that it is the same wheel to everything here. Needs `usb_modeswitch` installed. | +| `c272` | RS50 in compatibility mode, **or** a G PRO (Xbox/PC) | Same as above. The two share this id. Logi Wheel names which one it found. | | `c268` | G PRO Racing Wheel (PS/PC) | Same as above. | | `c266`, `c267` | G923 PlayStation edition | Force feedback (no other Linux driver gives this wheel any), simulated TrueForce, rev lights, and the core settings. | -| `c26d`, `c26e` | G923 Xbox edition | Force feedback and TrueForce, both confirmed on a real unit. Rev lights are implemented and awaiting an owner's confirmation in a game. Needs `usb_modeswitch` installed; see [G923 support](#g923-support). | +| `c26d`, `c26e` | G923 Xbox edition | Force feedback and TrueForce, both confirmed on a real unit. Rev lights are implemented and await an owner's confirmation in a game. Needs `usb_modeswitch` installed; see [G923 support](#g923-support). | A wheel that plugs in as `c267`, `c26d` or `c275` is switched to its PC mode -automatically, so a different id after plugging in is expected, not a fault. -The two Xbox editions need `usb_modeswitch` installed for that, and -`sudo logi-wheel-modeswitch` does it by hand on a system without systemd. +automatically. So a different id after plugging in is expected, not a fault. +The two Xbox editions need `usb_modeswitch` (the tool that flips a USB +device between its modes) installed for that switch. On a system without +systemd, `sudo logi-wheel-modeswitch` does the switch by hand. -If nothing above matches, this driver is not for your wheel. The **G920** is -already handled by the kernel's own `hid-logitech-hidpp`, and the older -G25/G27/G29 by `hid-logitech-hidpp` and `hid-lg4ff`. +If nothing above matches, this driver is not for your wheel. The kernel's +own `hid-logitech-hidpp` already handles the **G920**. `hid-logitech-hidpp` +and `hid-lg4ff` handle the older G25/G27/G29. ## Logi Wheel -**Logi Wheel** is how you drive all of this. It is this project's answer to G -HUB: every setting your wheel supports, in one place. Wheels differ in what -they offer, and a few settings only apply in one of the wheel's modes, so -anything unavailable is greyed out with a note saying why. It runs as a -desktop app (`logi-wheel-gui`) or in a terminal (`logi-wheel`), and both are +**Logi Wheel** is how you drive all of this. It is this project's answer to +G HUB: every setting your wheel supports, in one place. Wheels differ in what +they offer. A few settings only apply in one of the wheel's modes. So +anything unavailable is greyed out, with a note saying why. It runs as a +desktop app (`logi-wheel-gui`) or in a terminal (`logi-wheel`). Both are built from the same core, so they behave identically. ![Logi Wheel](docs/images/logi-wheel.png) -Beyond the settings, it has a G HUB-style curve editor for the pedals, a -LIGHTSYNC editor whose changes reach the wheel as you make them, a Setup page -that finds your sims across Steam, Lutris and Heroic and turns the per-game -TrueForce helpers on and off, and an Info / Testing page with live input and -cancelable force tests. +It does more than settings. There is a G HUB-style curve editor for the +pedals. There is a LIGHTSYNC editor whose changes reach the wheel as you make +them. The Setup page finds your sims across Steam, Lutris and Heroic and +turns the per-game TrueForce helpers on and off. The Info / Testing page +shows live input and runs force tests you can cancel. ## What works Force feedback, TrueForce haptics, LEDs, pedals, the RS Shifter & Handbrake, -the RS H-Shifter, and the full set of G HUB wheel settings all work. The RS50 is the development -hardware and is verified directly; the G PRO runs the same code path and is -expected to work, with a few items awaiting an owner's confirmation. +the RS H-Shifter, and the full set of G HUB wheel settings all work. Force +feedback goes through evdev, the Linux input event interface, so games see a +standard wheel. The RS50 is the development hardware, so it is verified +directly. The G PRO runs the same code path and is expected to work. A few +items there await an owner's confirmation. **Legend:** โœ… verified on hardware ยท ๐ŸŸข shares the verified code path, expected to work ยท ๐ŸŸก needs a tester ยท `-` not applicable. @@ -185,133 +203,136 @@ to work ยท ๐ŸŸก needs a tester ยท `-` not applicable. | LIGHTSYNC RGB LEDs (slots, colors, direction; edits apply live) | โœ… (faceplate strip, see note) | ๐ŸŸก (rev lights) | | RPM rev-light display (level fill; drawn center-out by default - the strip's pattern comes from the wheel's stored display config, separate from the level itself) | โœ… | ๐ŸŸก | | Native texture merge + telemetry rev lights in AC EVO (relay triple -> logi-rpm-bridge -> wheel) | โœ… | ๐ŸŸข | - -> **If the strip stays dark, check which onboard profile is active.** The -> wheel stores five, and a profile can keep the strip off entirely. Every -> LED write still reports success on such a profile, so the driver looks -> broken when the wheel is simply doing what that profile says. The four -> built-in sweeps also play a colour pattern held in the wheel's own -> firmware, which it never reports, so the app previews their motion but -> not their colours; pick a custom slot to choose colours yourself. | Simulated TrueForce from game telemetry (`logi-tf-sim`) | โœ… (sweep-verified) | ๐ŸŸข | | Centre calibration, mode / profile switching, computer-side profiles | โœ… | ๐ŸŸข | +> **If the strip stays dark, check which onboard profile is active.** The +> wheel stores five. A profile can keep the strip off entirely. Every LED +> write still reports success on such a profile, so the driver looks broken +> when the wheel is simply doing what that profile says. The four built-in +> sweeps also play a colour pattern held in the wheel's own firmware. The +> wheel never reports that pattern, so the app previews their motion but not +> their colours. Pick a custom slot to choose colours yourself. + USB IDs covered: RS50 (`046d:c276` native for both the PlayStation and the Xbox edition, `046d:c272` compatibility mode), G PRO Racing Wheel (`046d:c272` Xbox/PC, `046d:c268` PS/PC), and the G923 -(`046d:c266`/`c267` PlayStation edition, `046d:c26d`/`c26e` Xbox edition - +(`046d:c266`/`c267` PlayStation edition, `046d:c26d`/`c26e` Xbox edition, see [G923 support](#g923-support)). ## What's included Everything below is built from this repository: -- **The kernel driver** (`hid-logitech-dd`) makes the wheel work: games get - standard Linux force feedback, and every wheel setting appears under - `/sys/.../wheel_*`. Your other Logitech devices stay on their usual drivers. - It drives the G923 too, through a separate force-feedback engine suited to - that wheel (see [G923 support](#g923-support)). +- **The kernel driver** (`hid-logitech-dd`) makes the wheel work. Games get + standard Linux force feedback. Every wheel setting appears under + `/sys/.../wheel_*`, in sysfs, the kernel's settings file tree. Your other + Logitech devices stay on their usual drivers. It drives the G923 too, + through a separate force-feedback engine suited to that wheel (see + [G923 support](#g923-support)). - **Logi Wheel**, described [above](#logi-wheel), is the app you configure the - wheel with. `logi-wheel-gui` is the desktop version, with a LIGHTSYNC editor - whose per-slot colors and animation direction reach the wheel immediately, - computer-side profile presets, a Setup page for your sims, and an Info / - Testing page with a rotating wheel diagram, button and pedal readouts and - cancelable force tests. `logi-wheel` is the terminal version: the same - settings and the same G HUB-style curve editor, so you never have to `echo` - values into sysfs by hand. + wheel with. `logi-wheel-gui` is the desktop version. Its LIGHTSYNC editor + sends per-slot colors and animation direction to the wheel immediately. It + also has computer-side profile presets, a Setup page for your sims, and an + Info / Testing page with a rotating wheel diagram, button and pedal readouts + and cancelable force tests. `logi-wheel` is the terminal version. It has + the same settings and the same G HUB-style curve editor, so you never have + to `echo` values into sysfs by hand. - **logi-ffb** restores force feedback in DirectInput sims under Wine/Proton (Le Mans Ultimate, for example). One launch option and it works: see [Force feedback in games](#force-feedback-in-games). - **logi-tf-sim** gives you TrueForce engine haptics and a live RPM rev-light - display in games with no native TrueForce, using the game's own UDP - telemetry. Supported games are auto-detected (DiRT Rally 2.0 and the classic - Codemasters format, Automobilista 2 / Project CARS 2, F1, BeamNG.drive and - EA Sports WRC); enable and tune it per game from the Setup page. + display in games with no native TrueForce. It uses the game's own UDP + telemetry (car data the game sends out over the network). It auto-detects + the supported games (DiRT Rally 2.0 and the classic Codemasters format, + Automobilista 2 / Project CARS 2, F1, BeamNG.drive and EA Sports WRC). + Enable and tune it per game from the Setup page. -- **libtrueforce** lets native Linux apps drive TrueForce without Wine: a C - library reimplementing Logitech's TrueForce SDK. Optional; not needed for - the Proton recipe. +- **libtrueforce** lets native Linux apps drive TrueForce without Wine. It is + a C library that reimplements Logitech's TrueForce SDK. Optional; the + Proton recipe does not need it. The distribution packages install the driver plus the `logi-wheel`, -`logi-wheel-gui`, `logi-ffb` and `logi-tf-sim` tools, the TrueForce shim -installer, and the helpers games load themselves: the SDK proxy, the -telemetry relay and the truck-sim plugin. The intent is that installing a -package leaves you needing only Logitech's own DLLs, which cannot be -redistributed. `libtrueforce` has its own build under -`userspace/libtrueforce/`. +`logi-wheel-gui`, `logi-ffb` and `logi-tf-sim` tools. They also install the +TrueForce shim installer (the shim puts Logitech's TrueForce files into a +game's Proton folder) and the helpers games load themselves: the SDK proxy, +the telemetry relay and the truck-sim plugin. The idea is simple. After you install a +package, the only thing you still need is Logitech's own DLLs (Windows +library files), which cannot be redistributed. `libtrueforce` has its own +build under `userspace/libtrueforce/`. ## G923 support The G923 gets something no other Linux driver offers: **force feedback and -TrueForce on the same wheel**. TrueForce has never been available for it on -Linux before, and the PlayStation edition had no force feedback at all - the +TrueForce on the same wheel**. TrueForce was never available for it on Linux +before. The PlayStation edition had no force feedback at all, because the in-tree drivers do not cover it. -It is gear-driven and speaks an older Logitech protocol, so internally it -takes a different path than the RS50 and G PRO above, but the result is the +It is gear-driven and speaks an older Logitech protocol. So inside the driver +it takes a different path from the RS50 and G PRO above. The result is the same: real forces in games, engine haptics through the rim, working rev lights, and the settings app. -Both editions are verified on hardware. The Xbox edition was confirmed by an -owner in issue #27, on a wheel none of the maintainers own (see +Both editions are verified on hardware. An owner confirmed the Xbox edition +in issue #27, on a wheel none of the maintainers own (see [CREDITS.md](CREDITS.md)). **PlayStation edition** (`046d:c266`/`c267`) is fully supported and verified on hardware: -- **Force feedback** in games. Launch options `logi-launch %command%` work - here too: the wrapper detects the classic wheel and applies its plan (raw - HID stays off, the telemetry engine note comes on where the game supports - it). Doing it by hand instead: just turn Steam Input off, and never set - `PROTON_ENABLE_HIDRAW` for this wheel, it is meant for the direct-drive - wheels and it disables the G923's force feedback. +- **Force feedback** in games. The launch option `logi-launch %command%` + works here too. The wrapper detects the classic wheel and applies its plan: + raw HID stays off, and the telemetry engine note comes on where the game + supports it. To do it by hand instead, just turn Steam Input off. Never set + `PROTON_ENABLE_HIDRAW` for this wheel. That variable is meant for the + direct-drive wheels, and it disables the G923's force feedback. - **TrueForce** engine haptics through `logi-tf-sim`, driven by game telemetry. - Logitech's own SDK cannot deliver TrueForce here (it hands the haptics to - G HUB, which does not exist on Linux), so this driver streams them itself. -- **Rev lights**, driven from telemetry or controllable as ordinary Linux LEDs. - The packaged udev rules cover their brightness files, so a normal user can - drive them. -- **Pedals the right way round.** This wheel sends all three pedals inverted - (255 released, 0 fully pressed), and HID has no way to mark an axis as - inverted, so every layer passes that on and a game reads every pedal as - fully applied at rest. The driver turns them the right way up. Raw HID is - untouched, since a Wine or Proton game reading the wheel that way expects + Logitech's own SDK cannot deliver TrueForce here. It hands the haptics to + G HUB, which does not exist on Linux. So this driver streams them itself. +- **Rev lights**, driven from telemetry, or controllable as ordinary Linux + LEDs. The packaged udev rules (udev is the service that sets device + permissions) cover their brightness files, so a normal user can drive them. +- **Pedals the right way round.** This wheel sends all three pedals inverted: + 255 released, 0 fully pressed. HID has no way to mark an axis as inverted. + So every layer passes that on, and a game reads every pedal as fully + applied at rest. The driver turns them the right way up. Raw HID is + untouched, because a Wine or Proton game reading the wheel that way expects the Windows convention. - **Settings**: rotation range, force strength, autocenter and combined pedals, through `logi-wheel` or Oversteer. Since 0.29.0 that engine note also covers **Assetto Corsa Competizione and -Assetto Corsa EVO**, which is new. Those two have real TrueForce of their own, -but it travels through a Logitech SDK the G923 does not answer, so it never -reached the wheel. Their telemetry is read from the game's shared memory -instead and synthesized into an engine note (see +Assetto Corsa EVO**, which is new. Those two have real TrueForce of their +own. But it travels through a Logitech SDK the G923 does not answer, so it +never reached the wheel. Instead, their telemetry is read from the game's +shared memory and synthesized into an engine note (see [docs/SHARED_MEMORY_RELAY.md](docs/SHARED_MEMORY_RELAY.md)). Confirmed on a -c266: stationary in the pit box with the engine revving, the wheel buzzes, -which force feedback alone cannot do. +c266: stationary in the pit box with the engine revving, the wheel buzzes. +Force feedback alone cannot do that. **Xbox edition** (`046d:c26e`) has **force feedback and TrueForce**, both confirmed on a real unit, and **rev lights**. Neither the forces nor the haptics existed for this wheel on Linux before this project. -The rev lights follow RPM in a game, confirmed by an owner in Assetto -Corsa EVO. With Logitech's TrueForce files in a game's prefix, -`logi-launch %command%` puts this edition on the same route as a -direct-drive wheel: the game's own force and TrueForce over raw HID, and -the simulated daemon for the rev lights and screen only. The strip -exposes the same five `::RPM1`..`::RPM5` LED devices -the PlayStation edition does, so anything that drives those works here -unchanged. Two owners found that this wheel gives force feedback and -simulated TrueForce together on the driver's own force engine -(`g923_xbox_dd_engine=1`, raw HID off); the [G923 wiki +The rev lights follow RPM in a game. An owner confirmed that in Assetto +Corsa EVO. With Logitech's TrueForce files in a game's prefix (the private +Windows-style folder Proton keeps for each game), `logi-launch %command%` +puts this edition on the same route as a direct-drive wheel. The game's own +force and TrueForce travel over raw HID. The simulated daemon (the +background service) does the rev lights and screen only. The strip exposes the same five +`::RPM1`..`::RPM5` LED devices the PlayStation edition does. So anything +that drives those works here unchanged. Two owners found that this wheel +gives force feedback and simulated TrueForce together on the driver's own +force engine (`g923_xbox_dd_engine=1`, raw HID off). The [G923 wiki page](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/G923) has that recipe. -This edition ships in a console-only mode that Linux cannot use, and has to +This edition ships in a console-only mode that Linux cannot use. It has to be switched into PC mode. The packages handle it: a udev rule does the switch -on plug-in, using `usb_modeswitch`, which comes in as a recommended +on plug-in, using `usb_modeswitch`. That tool comes in as a recommended dependency on Debian, Ubuntu, Fedora and openSUSE. **On Arch it is an optional dependency**, so install it yourself there: @@ -319,162 +340,173 @@ optional dependency**, so install it yourself there: sudo pacman -S usb_modeswitch ``` -The RS50 Xbox edition (`046d:c275`) is handled by the same rule and the same -helper. `sudo logi-wheel-modeswitch` switches either wheel by hand, which is -the answer on a system without systemd. +The RS50 Xbox edition (`046d:c275`) uses the same rule and the same helper. +`sudo logi-wheel-modeswitch` switches either wheel by hand. That is the +answer on a system without systemd. If the wheel never leaves console mode, the out-of-tree `xone` driver has probably claimed it first. One known limitation: some sims lock the steering to 90 degrees (45 each way). That is not the wheel or this driver. Logitech's TrueForce SDK asks -G HUB for your wheel's rotation over a local pipe, nothing answers that under -Proton, and the game falls back to 90, which is the minimum of the wheel's -legal range. The troubleshooting section below has the workaround, and the -shim that aims to remove the need for one. Tracked in #27. - -Two notes for the curious: the wheel plugs in as `c267` (PlayStation) or `c26d` -(Xbox) and the driver switches it to its PC mode automatically, and the G923's -sysfs settings use the classic Oversteer-compatible names rather than the -`wheel_*` names the direct-drive wheels use. The +G HUB for your wheel's rotation over a local pipe. Nothing answers that under +Proton, so the game falls back to 90, the minimum of the wheel's legal range. +The [Troubleshooting](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Troubleshooting) wiki page has the workaround, and the shim that +aims to remove the need for one. Tracked in #27. + +Two notes for the curious. The wheel plugs in as `c267` (PlayStation) or +`c26d` (Xbox), and the driver switches it to its PC mode automatically. The +G923's sysfs settings use the classic Oversteer-compatible names rather than +the `wheel_*` names the direct-drive wheels use. The [wiki](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/G923) has the details, including the LED devices and the driver-precedence rule. ## Install -Pick your distribution. The full step-by-step is on the +Pick your distribution in the table. The full step-by-step is on the [**Installation**](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Installation) -wiki page, and the one-time TrueForce SDK setup is on +wiki page. The one-time TrueForce SDK setup is on [**Force feedback in games**](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Force-Feedback-in-Games). +Most packages use DKMS, which rebuilds the driver module for each new kernel. | Distribution | Install | |---|---| -| Arch, CachyOS, Manjaro | `paru -S logi-wheel-gui` (AUR, or your AUR helper; pulls `logi-wheel` and the driver. Headless box: `paru -S logi-wheel`). Or the [signed binary repo](#arch-linux-binary-repository) below, which does not depend on the AUR being reachable. | +| Arch, CachyOS, Manjaro | `paru -S logi-wheel-gui` (from the AUR, the Arch User Repository, with paru or your own AUR helper; pulls `logi-wheel` and the driver. Headless box: `paru -S logi-wheel`). Or use the [signed binary repo](#arch-linux-binary-repository) below, which does not depend on the AUR being reachable. | | Debian, Ubuntu, Mint, Pop!_OS | download the `.deb`s from [Releases](https://github.com/mescon/logitech-trueforce-linux-driver/releases), then `sudo apt install ./logitech-trueforce-dkms_*.deb ./logi-wheel_*.deb ./logi-wheel-gui_*.deb` (skip the gui one on a headless box) | -| Fedora, Nobara | COPR akmod: `sudo dnf copr enable mescon/logitech-trueforce && sudo dnf install akmod-logitech-trueforce logi-wheel-gui` (headless box: `logi-wheel` instead of `logi-wheel-gui`) | -| openSUSE | OBS repo `home:mescon` (see the [Installation](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Installation) page) | +| Fedora, Nobara | COPR (Fedora's community package service) akmod: `sudo dnf copr enable mescon/logitech-trueforce && sudo dnf install akmod-logitech-trueforce logi-wheel-gui` (headless box: `logi-wheel` instead of `logi-wheel-gui`) | +| openSUSE | OBS (openSUSE's build service) repo `home:mescon` (see the [Installation](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Installation) page) | | NixOS | add this repo as a flake input, import `nixosModules.default`, and set `hardware.logitech-trueforce.enable = true;` That builds the module against your own kernel and installs the tools, the udev rules and the helpers. Full snippet on the [Installation](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Installation) page. | -| From source (any distro) | `git clone` this repo, then `sudo ./tools/setup.sh`: DKMS build, udev rules, the helper scripts, and the apps themselves (`logi-wheel`, `logi-ffb`, `logi-tf-sim`, and the window when it can be built). Needs `cargo`, and stops before touching anything if it is missing, because an app left over from an older build next to a new module is a fault, not an install (`--without-apps` skips them on purpose). Every app and the module carry the same build stamp, shown by `--version`; `./tools/setup.sh doctor` fails when they were not built from the same source. The window also needs `pkg-config` and the fontconfig headers: `libfontconfig-dev` on Debian/Ubuntu, `fontconfig-devel` on Fedora, `fontconfig` on Arch; without them everything else still installs. | +| From source (any distro) | `git clone` this repo, then `sudo ./tools/setup.sh`. That does the DKMS build, the udev rules, the helper scripts, and the apps themselves (`logi-wheel`, `logi-ffb`, `logi-tf-sim`, and the window when it can be built). It needs `cargo`, and stops before touching anything if it is missing: an app left over from an older build next to a new module is a fault, not an install (`--without-apps` skips them on purpose). Every app and the module carry the same build stamp, shown by `--version`. `./tools/setup.sh doctor` fails when they were not built from the same source. The window also needs `pkg-config` and the fontconfig headers: `libfontconfig-dev` on Debian/Ubuntu, `fontconfig-devel` on Fedora, `fontconfig` on Arch. Without them everything else still installs. | + +Then: -The AUR and Debian packages are DKMS-based and rebuild automatically on kernel -upgrades; the NixOS module builds against whichever kernel your configuration -selects and is rebuilt with the system. After installing, plug in the wheel and check `dmesg` for a line naming -your wheel model. The packages install a udev rule, so settings are writable -right away, no group membership needed. +1. Run the install command for your distribution. +2. Plug in the wheel. +3. Check `dmesg` for a line naming your wheel model. + +The AUR and Debian packages are DKMS-based, so they rebuild automatically on +kernel upgrades. The NixOS module builds against whichever kernel your +configuration selects, and is rebuilt with the system. The packages install +a udev rule, so settings are writable right away. No group membership needed. ### Arch Linux binary repository -The AUR is the normal route, and when it is up nothing here is needed. It has -had extended outages during which no Arch user could get anything newer than -whatever was last pushed, so every release also publishes a signed pacman -repository as release assets. It is served by GitHub, so it works whenever +The AUR is the normal route. When it is up, nothing here is needed. But it +has had long outages. During those, no Arch user could get anything newer +than whatever was last pushed. So every release also publishes a signed +pacman repository as release assets. GitHub serves it, so it works whenever GitHub does. -Import the signing key, then add the repository: +1. Import the signing key and sign it locally: -```bash -curl -fsSL -O https://github.com/mescon/logitech-trueforce-linux-driver/releases/latest/download/logitech-trueforce-signing-key.asc -sudo pacman-key --add logitech-trueforce-signing-key.asc -sudo pacman-key --lsign-key 4B5BDD7802723B289FA934CACD77C00A443B9E79 -``` + ```bash + curl -fsSL -O https://github.com/mescon/logitech-trueforce-linux-driver/releases/latest/download/logitech-trueforce-signing-key.asc + sudo pacman-key --add logitech-trueforce-signing-key.asc + sudo pacman-key --lsign-key 4B5BDD7802723B289FA934CACD77C00A443B9E79 + ``` -Check the fingerprint printed by `--lsign-key` matches the one above before -signing it. The full fingerprint rather than a short id, because short ids can -be collided and this is a key you are telling your package manager to trust. -It signs nothing but this repository's packages. + Before you confirm the signing, check that the fingerprint `--lsign-key` + prints matches the one in that command. We use the full fingerprint + rather than a short id, because short ids can be collided, and this is a + key you are telling your package manager to trust. It signs nothing but + this repository's packages. -The key is served from the release rather than a keyserver so that installing -depends on nothing beyond GitHub. If you would rather use a keyserver, -`sudo pacman-key --recv-keys 4B5BDD7802723B289FA934CACD77C00A443B9E79 ---keyserver keyserver.ubuntu.com` works once it has propagated. +2. Add the repository at the end of `/etc/pacman.conf`: -```ini -# /etc/pacman.conf, at the end -[logitech-trueforce] -Server = https://github.com/mescon/logitech-trueforce-linux-driver/releases/latest/download -``` + ```ini + # /etc/pacman.conf, at the end + [logitech-trueforce] + Server = https://github.com/mescon/logitech-trueforce-linux-driver/releases/latest/download + ``` -```bash -sudo pacman -Sy logi-wheel-gui # headless box: logi-wheel -``` +3. Install: + + ```bash + sudo pacman -Sy logi-wheel-gui # headless box: logi-wheel + ``` + +The key is served from the release rather than a keyserver, so that +installing depends on nothing beyond GitHub. If you would rather use a +keyserver, `sudo pacman-key --recv-keys 4B5BDD7802723B289FA934CACD77C00A443B9E79 --keyserver keyserver.ubuntu.com` +works once it has propagated. Updates then arrive through `pacman -Syu` like anything else. `latest/download` always resolves to the newest release, so the `Server` line never needs changing. -The packages are the same ones the AUR recipe builds, from the same tag, built -and signed in public CI. If you would rather not add a third-party repository, -the individual `.pkg.tar.zst` files are attached to every release and install -with `sudo pacman -U `. +The packages are the same ones the AUR recipe builds, from the same tag, +built and signed in public CI. If you would rather not add a third-party +repository, the individual `.pkg.tar.zst` files are attached to every +release. They install with `sudo pacman -U `. -**On a Steam Deck this repository is the route**, not the AUR: SteamOS ships +**On a Steam Deck this repository is the route**, not the AUR. SteamOS ships libraries without the files needed to compile against them, so an AUR build -fails before it reaches anything of ours. It also has a read-only root -filesystem, and a SteamOS update replaces it, so the install has to be -repeated afterwards. The wiki's +fails before it reaches anything of ours. SteamOS also has a read-only root +filesystem, and a SteamOS update replaces it, so you have to repeat the +install afterwards. The wiki's [SteamOS section](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Installation#steamos-steam-deck) has the full sequence, including the kernel headers the module needs. ## Force feedback in games **`logi-launch %command%` already does everything in this section.** It is -covered here because knowing what it does makes it possible to check it, and -because some people would rather set things up themselves. +covered here so you can check what it does, and because some people would +rather set things up themselves. -The recipe is per game **and per wheel**: the same title needs opposite -settings on an RS50 and a G923, which is why one launch option that works it +The recipe is per game **and per wheel**. The same title needs opposite +settings on an RS50 and a G923. That is why one launch option that works it out beats a line copied from someone else's post. Every game and wheel this -project knows about is in **[docs/GAME_SETUP.md](docs/GAME_SETUP.md)**, +project knows about is in **[docs/GAME_SETUP.md](docs/GAME_SETUP.md)**. It is generated from the same registry the app uses, so the two cannot disagree. -- **Native and most Proton sims:** force feedback works out of the box; games see - a standard Linux wheel. No setup beyond binding controls in game. +- **Native and most Proton sims:** force feedback works out of the box. Games + see a standard Linux wheel. No setup beyond binding controls in game. - **TrueForce haptics** (the high-frequency texture layer, on top of normal - FFB) in SDK-aware sims: stage Logitech's signed SDK DLLs into the game's - Proton prefix (the app's Setup page, or `tools/install-tf-shim.sh`), and - launch with `logi-launch %command%`, which turns raw HID on for the - wheels that want it and stages the proxy that answers the SDK's rotation - question. Leave `PROTON_ENABLE_HIDRAW` to the launcher: with Logitech's - stock library alone the game's steering and force feedback stop on - track, and the launcher refuses to set it in that state. The - DLLs are the one part nobody can automate, because Logitech's files cannot - be redistributed. The one-time recipe is on the + FFB) in SDK-aware sims. Stage Logitech's signed SDK DLLs into the game's + Proton prefix, from the app's Setup page or with `tools/install-tf-shim.sh`. + Then launch with `logi-launch %command%`. It turns raw HID on for the + wheels that want it, and stages the proxy that answers the SDK's rotation + question. Leave `PROTON_ENABLE_HIDRAW` to the launcher. With Logitech's + stock library alone, the game's steering and force feedback stop on track, + and the launcher refuses to set it in that state. The DLLs are the one + part nobody can automate, because Logitech's files cannot be + redistributed. The one-time recipe is on the [Force feedback in games](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Force-Feedback-in-Games) wiki page. Verified end to end on **Assetto Corsa Competizione** and **Assetto Corsa EVO**. **On a G923 the recipe is different, not absent.** That wheel does not - answer the TrueForce SDK, so `PROTON_ENABLE_HIDRAW` must stay unset: there - it does not add TrueForce, it takes away the force feedback you already - had. For haptics, turn the game on under Simulated TrueForce instead: - `logi-tf-sim` synthesizes an engine note from the game's own telemetry, - confirmed working on a G923 in ACC and AC EVO. The shim's `--proxy` - option does not help in those two: both check the library's signature - and refuse the unsigned proxy, so it carries nothing there. See + answer the TrueForce SDK, so `PROTON_ENABLE_HIDRAW` must stay unset. There + it does not add TrueForce; it takes away the force feedback you already + had. For haptics, turn the game on under Simulated TrueForce instead. + `logi-tf-sim` synthesizes an engine note from the game's own telemetry. + That is confirmed working on a G923 in ACC and AC EVO. The shim's `--proxy` + option does not help in those two. Both check the library's signature and + refuse the unsigned proxy, so it carries nothing there. See [G923 support](#g923-support). **Where the SDK files go.** Copy the `Logi` folder out of a Windows G HUB - install into `~/.local/share/logitech-trueforce/sdk`, keeping its own - layout, so you end up with: + install into `~/.local/share/logitech-trueforce/sdk`. Keep its own layout, + so you end up with: ``` ~/.local/share/logitech-trueforce/sdk/Logi/Trueforce//trueforce_sdk_x64.dll ~/.local/share/logitech-trueforce/sdk/Logi/wheel_sdk//logi_steering_wheel_x64.dll ``` - Whatever version numbers your G HUB shipped are the right ones; nothing + Whatever version numbers your G HUB shipped are the right ones. Nothing here assumes a particular pair. To keep them somewhere else, set `LOGITECH_TRUEFORCE_SDK_DIR` to that directory, or pass `--sdk-dir` to the installer, or set the folder on the app's Setup page. `setup.sh doctor` - prints the directory it checked, so if it disagrees with you, that line - tells you where it looked. + prints the directory it checked. If it disagrees with you, that line tells + you where it looked. **Side effects to know about.** With `PROTON_ENABLE_HIDRAW` set, some games - read the wheel's raw HID reports instead of the normal Linux input layer, - and the two use opposite conventions for a control at rest. Nothing is - wrong with the wheel or the driver, and all of it goes away if you unset - the variable. + read the wheel's raw HID reports instead of the normal Linux input layer. + The two use opposite conventions for a control at rest. Nothing is wrong + with the wheel or the driver. All of it goes away if you unset the + variable. - **Pedals read the other way up**: resting registers as fully pressed. Turn on the game's own "invert axis" option for the affected pedals. @@ -483,7 +515,7 @@ generated from the same registry the app uses, so the two cannot disagree. that makes menus impossible to navigate. Rebinding in the game usually clears it. Reported on Assetto Corsa EVO under GE-Proton9-27. - If either makes a game unusable and you would rather have force feedback + If either makes a game unusable, and you would rather have force feedback than the game's own TrueForce, tell the wrapper so for that game in `~/.config/logi-wheel/games.conf`: @@ -492,13 +524,13 @@ generated from the same registry the app uses, so the two cannot disagree. ``` - **DirectInput sims** (Le Mans Ultimate, for example): `logi-launch` routes - these through `logi-ffb` for you. By hand it is `logi-ffb - %command%` in the game's Steam launch options. It presents a virtual wheel - the game can drive force feedback on and passes the forces through to the - real one; do not set `PROTON_ENABLE_HIDRAW` yourself, `logi-ffb` handles it. - The game sees a "logi-ffb Virtual Wheel" (its own name and IDs, not the real + these through `logi-ffb` for you. By hand it is `logi-ffb %command%` in + the game's Steam launch options. `logi-ffb` presents a virtual wheel the + game can drive force feedback on, and passes the forces through to the real + one. Do not set `PROTON_ENABLE_HIDRAW` yourself; `logi-ffb` handles it. The + game sees a "logi-ffb Virtual Wheel" (its own name and IDs, not the real wheel's), so it may need a one-time manual binding. Hardware-validated, but - still waiting on an in-game tester; if you run such a sim, reports are very + still waiting on an in-game tester. If you run such a sim, reports are very welcome. **The one line to put in a game's launch options** is: @@ -508,140 +540,142 @@ logi-launch %command% ``` That is the whole setup for most people. It works out what the game needs on -the wheel you actually have and applies it: the raw-HID setting only where -that wheel wants it, the `logi-ffb` proxy for DirectInput games, the -simulated-TrueForce daemon, and the telemetry relay inside the game's Proton -prefix for the sims that need one. Games with their own TrueForce keep it and -get nothing layered on top. It knows 29 titles by their Steam appid, and you -can teach it others. Full details, including how to add a game yourself, are -in [docs/LAUNCH_OPTIONS.md](docs/LAUNCH_OPTIONS.md). - -- **Simulated TrueForce** for games without native support: enable the game in - Setup's "Simulated TrueForce" panel and switch on the game's own UDP - telemetry setting. `logi-tf-sim` then plays engine haptics from live RPM and - throttle, and drives the rev LEDs to match. Intensity and felt rev rate - (pitch) are tunable, and a built-in test sweep (the app asks before running - it) lets you feel the effect without launching a game. The sweep refuses, - and names what has the wheel, if a game or the daemon is already streaming - to it: the wheel's TrueForce endpoint takes one writer at a time, and two - at once buzz rather than blend. - Hardware-verified with those test sweeps; in-game reports welcome. +the wheel you actually have, and applies it. That means the raw-HID setting +only where that wheel wants it, and the `logi-ffb` proxy for DirectInput +games. It also means the simulated-TrueForce daemon, and the telemetry relay +inside the game's Proton prefix for the sims that need one. Games with their own TrueForce keep it and +get nothing layered on top. It knows 29 titles by their Steam appid (Steam's +number for a game), and you can teach it others. Full details, including how +to add a game yourself, are in [docs/LAUNCH_OPTIONS.md](docs/LAUNCH_OPTIONS.md). + +- **Simulated TrueForce** for games without native support. Enable the game + in Setup's "Simulated TrueForce" panel, and switch on the game's own UDP + telemetry setting. `logi-tf-sim` then plays engine haptics from live RPM + and throttle, and drives the rev LEDs to match. Intensity and felt rev rate + (pitch) are tunable. A built-in test sweep lets you feel the effect without + launching a game; the app asks before running it. The sweep refuses, and + names what has the wheel, if a game or the daemon is already streaming to + it. The wheel's TrueForce endpoint takes one writer at a time, and two at + once buzz rather than blend. Hardware-verified with those test sweeps; + in-game reports welcome. Two kinds of game need a helper before they can feed it. **`sudo ./tools/setup.sh` installs both for you**, into every Proton prefix and - into both truck sims, and the settings app can install the relay per game - from its Setup page, so there is normally nothing to fetch or copy. They - are also packaged and downloadable if you would rather place them - yourself: + into both truck sims. The settings app can also install the relay per game + from its Setup page. So there is normally nothing to fetch or copy. They + are also packaged and downloadable if you would rather place them yourself. Euro Truck Simulator 2 and American Truck Simulator use a native Linux - plugin ([docs/SCS_PLUGIN.md](docs/SCS_PLUGIN.md)); iRacing, RaceRoom, the + plugin ([docs/SCS_PLUGIN.md](docs/SCS_PLUGIN.md)). iRacing, RaceRoom, the Assetto Corsa family, rFactor 2 and Le Mans Ultimate publish to shared - memory that a small in-prefix relay forwards + memory, and a small in-prefix relay forwards it ([docs/SHARED_MEMORY_RELAY.md](docs/SHARED_MEMORY_RELAY.md)). The Assetto - Corsa family's decoders were confirmed against running games; the others - are written against published layouts but nobody has driven them yet, - which is why those titles carry the provisional marker in the table. + Corsa family's decoders were confirmed against running games. The others + are written against published layouts, but nobody has driven them yet. + That is why those titles carry the provisional marker in the table. Beyond the engine note there is a **haptic effects layer**: both limiters, gear shifts, the ABS pump, traction loss, surface texture, impacts and DRS. - Tune it in Setup, under "Simulated TrueForce": in the GUI, "Extra effects" - then "Adjust individual levels"; in the terminal app, `x` toggles the layer + Tune it in Setup, under "Simulated TrueForce". In the GUI: "Extra effects", + then "Adjust individual levels". In the terminal app: `x` toggles the layer and `l` lists it, with `[` `]` to pick a layer and `v` to set its level. - How much of it you feel depends on what your game's telemetry carries, and - each slider tells you which games feed it. Only the engine note and the rev + How much of it you feel depends on what your game's telemetry carries. Each + slider tells you which games feed it. Only the engine note and the rev limiter work in every supported game. The gear, the pedals and the ABS and - traction lamps come from OutGauge, which among these games means - BeamNG.drive, so the pit limiter, gear shifts, ABS and traction are silent - elsewhere. Surface texture, airborne, impacts and DRS have no source - at all yet: the effects are written, the missing piece is a decoder field. + traction lamps come from OutGauge (a telemetry format), which among these + games means BeamNG.drive. So the pit limiter, gear shifts, ABS and traction + are silent elsewhere. Surface texture, airborne, impacts and DRS have no + source at all yet. The effects are written; the missing piece is a decoder + field. All of this applies only to games you switched simulated TrueForce on for. Games with built-in TrueForce (ACC, Assetto Corsa EVO) normally get their - effects from the game itself and are not affected by any of it. **The G923 - is the exception**, and the reason simulated TrueForce covers those two - titles at all: their TrueForce goes through a Logitech SDK that wheel does - not answer, so on a G923 it never arrives, and a synthesized engine note is - the difference between haptics and silence. On a direct-drive wheel, keep - using the shim and leave these switches alone. + effects from the game itself. None of this affects them. **The G923 is the + exception**, and the reason simulated TrueForce covers those two titles at + all. Their TrueForce goes through a Logitech SDK that wheel does not + answer, so on a G923 it never arrives. A synthesized engine note is the + difference between haptics and silence. On a direct-drive wheel, keep using + the shim and leave these switches alone. The same settings live in `tf-sim.conf` as `effects=0/1` and `effect_=0-100`, where `` is one of `engine`, `rev_limiter`, `pit_limiter`, `gear_shift`, `abs`, `traction_loss`, `road_bumps`, `airborne`, `collision`, `drs`. `effect_airborne` is a depth rather than a level: it sets how far the road is quieted with the wheels off the ground. - Only the engine layer is hardware-validated so far, so if something feels - wrong, turn that one layer down and please say so in an issue. + Only the engine layer is hardware-validated so far. If something feels + wrong, turn that one layer down, and please say so in an issue. The base's screen can show the car while a session runs, from the same - telemetry as the rev lights: turn on the screen switch on the Setup page - (`screen=1` in `tf-sim.conf`) and it shows the gear and the speed by - default. The template (`screen.template`) is any `wheel_oled` frame with - `{gear}`, `{speed}`, `{speed_mph}`, `{rpm}` and the gauge values - `{rpm_pct}`, `{throttle_pct}`, `{brake_pct}` filled in, so - `J|Lap {gear}|{speed}|{rpm}|km/h` is four rows of text and `G|{gear}|{speed}` - is the gear-and-speed screen. The screen goes back to the wheel's own menu - when the session ends. It works in the lights-only mode too, so a strength - of zero gives rev lights and a dashboard with no haptics at all. Direct-drive - wheels only; the G923 has no screen. + telemetry as the rev lights. Turn on the screen switch on the Setup page + (`screen=1` in `tf-sim.conf`). It shows the gear and the speed by default. + The template (`screen.template`) is any `wheel_oled` frame with `{gear}`, + `{speed}`, `{speed_mph}`, `{rpm}` and the gauge values `{rpm_pct}`, + `{throttle_pct}`, `{brake_pct}` filled in. So + `J|Lap {gear}|{speed}|{rpm}|km/h` is four rows of text, and + `G|{gear}|{speed}` is the gear-and-speed screen. The screen goes back to + the wheel's own menu when the session ends. It works in the lights-only + mode too, so a strength of zero gives rev lights and a dashboard with no + haptics at all. Direct-drive wheels only; the G923 has no screen. The easiest way to set all of this is the screen editor on either app's - lights page ("Choose what to show..."): a preview and a list of - ready-made screens, from gear and speed to gauges and messages of your - own. "Show now" puts one on the screen, "Use during games" makes it the - dashboard, and the design behind any preset is open for changes. + lights page ("Choose what to show..."). It has a preview and a list of + ready-made screens, from gear and speed to gauges and messages of your own. + "Show now" puts one on the screen. "Use during games" makes it the + dashboard. The design behind any preset is open for changes. With a G923 and a direct-drive wheel plugged in together, say which one - simulated TrueForce should drive: the Setup page has a picker, or set - `wheel=dd` or `wheel=g923` in `tf-sim.conf`. Left on `auto` it takes a G923 - whenever it finds one, so the direct-drive wheel would never get it. + simulated TrueForce should drive. The Setup page has a picker, or set + `wheel=dd` or `wheel=g923` in `tf-sim.conf`. Left on `auto`, it takes a + G923 whenever it finds one, so the direct-drive wheel would never get it. ## Configuring the wheel -Run **logi-wheel-gui** (or **logi-wheel** in a terminal) and edit settings live: -rotation range, force-feedback strength and filters, TrueForce level, LIGHTSYNC -LEDs, profiles, and per-pedal / steering response curves through a G HUB-style -curve editor. +Run **logi-wheel-gui** (or **logi-wheel** in a terminal) and edit settings +live: rotation range, force-feedback strength and filters, TrueForce level, +LIGHTSYNC LEDs, profiles, and per-pedal / steering response curves through a +G HUB-style curve editor. ![logi-wheel-gui curve editor](docs/images/logi-wheel-curve-editor.png) **More than one wheel plugged in?** Both apps manage all of them. The window -puts a button for each next to the title; the terminal app switches with `w`. -The settings you see, the values you write and the tests all belong to the -wheel currently picked, and wheels of the same model are numbered so you can +puts a button for each next to the title. The terminal app switches with +`w`. The settings you see, the values you write and the tests all belong to +the wheel currently picked. Wheels of the same model are numbered so you can tell them apart. Nothing is shared between them: each wheel keeps its own settings on its own hardware. Games are scoped the same way. `logi-launch` resolves one wheel when it starts (`--wheel` picks it on a mixed rig) and hands that choice to -everything it runs, so the engine texture, the rev lights and the force -feedback all go to the wheel you are playing, and quitting the game undoes -only what that session armed on it. Another session on the other wheel is -left alone. +everything it runs. So the engine texture, the rev lights and the force +feedback all go to the wheel you are playing. Quitting the game undoes only +what that session armed on it. Another session on the other wheel is left +alone. The **RS Shifter & Handbrake** is supported too. Plug it into the wheel base -and its settings appear on their own; unplug it and they go away again. The +and its settings appear on their own. Unplug it and they go away again. The app also reads the physical three-position switch on its base and greys out -whatever does not apply: below it is in analog-handbrake mode, so the +whatever does not apply. Below, it is in analog-handbrake mode, so the handbrake curve is live while the two trigger points are not. ![logi-wheel-gui RS Shifter and Handbrake settings](docs/images/logi-wheel-accessory.png) The **RS H-Shifter** works the same way. Plug it into an accessory port on -the base and its seven gates and reverse appear as buttons 12 to 19. The +the base, and its seven gates and reverse appear as buttons 12 to 19. The driver also turns on the base's routing for it in desktop mode, so the gates work outside a game. The Info / Testing page shows which gate is in. Plug -the shifter straight into the computer by USB instead and the page reads it +the shifter straight into the computer by USB instead, and the page reads it there too, with the mode shown next to the gate. The Info / Testing page doubles as a live input tester (does this button -reach the computer?), and the Setup page manages the game helpers: +reach the computer?). The Setup page manages the game helpers: ![logi-wheel-gui Info / Testing](docs/images/logi-wheel-info-testing.png) ![logi-wheel-gui Setup](docs/images/logi-wheel-setup.png) +To build the apps yourself: + ```bash cd userspace/logi-wheel && cargo build --release ./target/release/logi-wheel-gui # desktop app; ./target/release/logi-wheel for the TUI @@ -649,27 +683,27 @@ cd userspace/logi-wheel && cargo build --release **logi-wheel is the recommended way to configure these wheels**: it covers every setting. Everything it sets is also a plain sysfs attribute under -`/sys/class/hidraw/hidrawX/device/wheel_*`, so you can script it directly; the -complete reference is [**docs/SYSFS_API.md**](docs/SYSFS_API.md). If you +`/sys/class/hidraw/hidrawX/device/wheel_*`, so you can script it directly. +The complete reference is [**docs/SYSFS_API.md**](docs/SYSFS_API.md). If you already run [Oversteer](https://github.com/berarma/oversteer) across a -collection of Logitech wheels, it recognizes the basics here too, since the -attribute names it expects are exposed as well. +collection of Logitech wheels, it recognizes the basics here too, because +the attribute names it expects are exposed as well. ## Verified game support -**Assetto Corsa Competizione** and **Assetto Corsa EVO** run under Proton with -steering, force feedback and TrueForce at once on a direct-drive wheel. Put -`logi-launch %command%` in the launch options and turn Steam Input off; it -applies the rest. Most other sims work out -of the box with standard force feedback, or need `logi-ffb` in their launch -options; the full per-game table, and which needs what, is in -[docs/GAME_SETUP.md](docs/GAME_SETUP.md) and on the +**Assetto Corsa Competizione** and **Assetto Corsa EVO** run under Proton +with steering, force feedback and TrueForce at once on a direct-drive wheel. +Put `logi-launch %command%` in the launch options and turn Steam Input off. +It applies the rest. Most other sims work out of the box with standard force +feedback, or need `logi-ffb` in their launch options. The full per-game +table, and which needs what, is in [docs/GAME_SETUP.md](docs/GAME_SETUP.md) +and on the [Force feedback in games](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Force-Feedback-in-Games) wiki page. -A couple of game-side behaviors (rotation-range reset at session start, and -keeping hands clear during AC EVO map loads) are covered under -[Troubleshooting](#troubleshooting) below. +Two game-side behaviors (rotation-range reset at session start, and keeping +hands clear during AC EVO map loads) are covered on the +[Troubleshooting](https://github.com/mescon/logitech-trueforce-linux-driver/wiki/Troubleshooting) wiki page. ## Troubleshooting @@ -691,25 +725,27 @@ sudo dmesg | grep -i usb | tail -n 30 Lines like `disabled by hub (EMI?)`, `device descriptor read/64, error -71` or `unable to enumerate USB device` mean the USB link itself failed. That happens before any driver runs. The usual cause is a front-panel USB port or -a hub. Move the wheel to a port on the back of the computer, on the -mainboard, and power the wheel off and on ([#141](../../issues/141)). +a hub ([#141](../../issues/141)). To fix it: + +1. Move the wheel to a port on the back of the computer, on the mainboard. +2. Power the wheel off and on. ### No force feedback once the raw HID interface is on -Some games drive force feedback the older Windows way, which needs a part of +Some games drive force feedback the older Windows way. That needs a part of the HID protocol these wheels do not implement. On the raw HID interface -those games have nowhere to send force, so force feedback goes silent while +those games have nowhere to send force. So force feedback goes silent while everything else keeps working. -**There is no fix for this yet.** The driver has a `inject_pid` option that -adds the missing part, and it does deliver force feedback, but it also breaks -steering and pedals on these wheels, so it is off and should stay off. The -reason is structural: these wheels send their input reports without a report -id, and the added part declares several, after which the kernel expects an id -on every report and misreads the ones the wheel is sending correctly. Making -it usable needs the driver to rewrite incoming reports too. +**There is no fix for this yet.** The driver has an `inject_pid` option that +adds the missing part. It does deliver force feedback, but it also breaks +steering and pedals on these wheels. So it is off and should stay off. The +reason is structural. These wheels send their input reports without a report +id. The added part declares several ids. After that, the kernel expects an +id on every report and misreads the ones the wheel is sending correctly. +Making it usable needs the driver to rewrite incoming reports too. -What works today is to leave the raw interface off for that game, which +What works today is to leave the raw interface off for that game. That keeps force feedback and loses the game's own TrueForce. In `~/.config/logi-wheel/games.conf`: @@ -721,30 +757,31 @@ keeps force feedback and loses the game's own TrueForce. In ## Documentation The [**project wiki**](https://github.com/mescon/logitech-trueforce-linux-driver/wiki) -is the friendliest place to start: a **Users** section (install, force feedback -in games, configuring the wheel, simulated TrueForce, troubleshooting) and a -**Developers** section (architecture, the sysfs API, the protocol -specification, libtrueforce, and the internals of `logi-ffb` and the -simulated-TrueForce daemon). +is the friendliest place to start. It has a **Users** section (install, force +feedback in games, configuring the wheel, simulated TrueForce, +troubleshooting) and a **Developers** section (architecture, the sysfs API, +the protocol specification, libtrueforce, and the internals of `logi-ffb` +and the simulated-TrueForce daemon). The `wheel_*` attribute reference for scripting, -[**docs/SYSFS_API.md**](docs/SYSFS_API.md), ships in the repo so it always +[**docs/SYSFS_API.md**](docs/SYSFS_API.md), ships in the repo, so it always matches your installed version. The protocol and button-mapping references -live under [`docs/`](docs/) as well, including -[**docs/FEATURE_MATRIX.md**](docs/FEATURE_MATRIX.md), what each wheel -reports it can do against what this driver uses, and -[**docs/STATUS.md**](docs/STATUS.md), which says plainly which claims here -are measured, which are argued from the code, and which are neither, along -with the problems we know about and have not fixed. +live under [`docs/`](docs/) as well. Two of them are worth knowing. +[**docs/FEATURE_MATRIX.md**](docs/FEATURE_MATRIX.md) lists what each wheel +reports it can do against what this driver uses. +[**docs/STATUS.md**](docs/STATUS.md) says plainly which claims here are +measured, which are argued from the code, and which are neither, along with +the problems we know about and have not fixed. ## Verifying a release Assets on a [release](https://github.com/mescon/logitech-trueforce-linux-driver/releases) -are signed with the project's GnuPG key, fingerprint -`4B5B DD78 0272 3B28 9FA9 34CA CD77 C00A 443B 9E79`, whose public half is +are signed with the project's GnuPG key (GnuPG is the standard open-source +signing tool). Its fingerprint is +`4B5B DD78 0272 3B28 9FA9 34CA CD77 C00A 443B 9E79`. Its public half is attached to each release as `logitech-trueforce-signing-key.asc`. Up to 0.41.0 that covers the Arch packages and the repository database, which -pacman verifies once the key is trusted; from 0.42.0 every asset has a +pacman verifies once the key is trusted. From 0.42.0 every asset has a detached `.sig`. To check one by hand: ```bash @@ -753,15 +790,16 @@ gpg --fingerprint 4B5BDD7802723B289FA934CACD77C00A443B9E79 # must match the li gpg --verify logi-wheel-0.41.0-1-x86_64.pkg.tar.zst.sig logi-wheel-0.41.0-1-x86_64.pkg.tar.zst ``` -A release is from this project when it verifies against that key; a change +A release is from this project when it verifies against that key. A change of key would be announced here and in the release notes. -From 0.42.0 each release also carries a CycloneDX SBOM per binary and a -SLSA provenance statement, `release-assets.intoto.jsonl`, listing every -asset by SHA-256 and signed through Sigstore by the release workflow itself. -[slsa-verifier](https://github.com/slsa-framework/slsa-verifier) checks that -an asset is the one the workflow published, from this repository, at that -tag: +From 0.42.0 each release also carries a CycloneDX SBOM per binary (a +software bill of materials: the list of what went into it) and a SLSA +provenance statement, `release-assets.intoto.jsonl`. The statement lists +every asset by SHA-256, and the release workflow itself signs it through +Sigstore. [slsa-verifier](https://github.com/slsa-framework/slsa-verifier) +checks that an asset is the one the workflow published, from this +repository, at that tag: ```bash slsa-verifier verify-artifact logi-wheel_0.42.0-1_amd64.deb \ @@ -770,7 +808,7 @@ slsa-verifier verify-artifact logi-wheel_0.42.0-1_amd64.deb \ --source-tag v0.42.0 ``` -Only the latest release is supported; see [SECURITY.md](SECURITY.md) for +Only the latest release is supported. See [SECURITY.md](SECURITY.md) for the policy and the reporting process. ## Project documents @@ -790,21 +828,21 @@ the policy and the reporting process. ## Contributing -Contributions are welcome: code, testing on hardware this project cannot reach -(a real G PRO, a DirectInput sim with `logi-ffb`), and USB captures of wheel -variants that are not yet fully supported. The kernel driver is a fork of -[JacKeTUs/hid-logitech-hidpp](https://github.com/JacKeTUs/hid-logitech-hidpp); -changes that apply to other Logitech devices are worth contributing upstream too. -Open an issue with your kernel version, distribution, and relevant `dmesg` output; -`tools/setup.sh report` prints all of that in one block. - -Most of the project can be checked without a wheel. The Rust workspace has its -own tests (`cargo test --workspace` in `userspace/logi-wheel`), and the parts -of the kernel driver that are pure arithmetic, the force maths and the texture -synthesis, are header-only files with userspace harnesses under -[`tests/`](tests/README.md) that build with nothing but a C compiler. CI runs -all of it on every push. Changes that add functionality come with tests for -it, in the same change. What needs hardware is listed in +Contributions are welcome: code, testing on hardware this project cannot +reach (a real G PRO, a DirectInput sim with `logi-ffb`), and USB captures of +wheel variants that are not yet fully supported. The kernel driver is a fork +of [JacKeTUs/hid-logitech-hidpp](https://github.com/JacKeTUs/hid-logitech-hidpp). +Changes that apply to other Logitech devices are worth contributing upstream +too. Open an issue with your kernel version, distribution, and relevant +`dmesg` output. `tools/setup.sh report` prints all of that in one block. + +Most of the project can be checked without a wheel. The Rust workspace has +its own tests (`cargo test --workspace` in `userspace/logi-wheel`). The parts +of the kernel driver that are pure arithmetic, the force maths and the +texture synthesis, are header-only files. They have userspace harnesses +under [`tests/`](tests/README.md) that build with nothing but a C compiler. +CI runs all of it on every push. Changes that add functionality come with +tests for it, in the same change. What needs hardware is listed in [docs/STATUS.md](docs/STATUS.md). ## License @@ -815,30 +853,31 @@ it, in the same change. What needs hardware is listed in Linux apps may link it while changes to the library itself stay open. Logitech's TrueForce SDK DLLs are not part of this project and are not -redistributed here; you supply them from your own G HUB installation. +redistributed here. You supply them from your own G HUB installation. ## Protocol and SDK notes What this project has worked out about the hardware and Logitech's own -software, kept current as things are proven or disproven: +software. Kept current as things are proven or disproven: -- [**docs/PROTOCOL_SPECIFICATION.md**](docs/PROTOCOL_SPECIFICATION.md) - the - wheel's HID++ surface: features, settings, LEDs, force feedback. -- [**docs/TRUEFORCE_PROTOCOL.md**](docs/TRUEFORCE_PROTOCOL.md) - the haptic +- [**docs/PROTOCOL_SPECIFICATION.md**](docs/PROTOCOL_SPECIFICATION.md): the + wheel's HID++ surface (HID++ is Logitech's extension of HID): features, + settings, LEDs, force feedback. +- [**docs/TRUEFORCE_PROTOCOL.md**](docs/TRUEFORCE_PROTOCOL.md): the haptic stream, the operating-range packet, and why a sim under Proton is told the wheel turns 90 degrees. -- [**docs/SDK_ABI_NOTES.md**](docs/SDK_ABI_NOTES.md) - how to call Logitech's - SDK correctly, taken from its machine code, with what is verified and what - is still assumed marked as such. -- [**docs/SYSFS_API.md**](docs/SYSFS_API.md) - every attribute this driver +- [**docs/SDK_ABI_NOTES.md**](docs/SDK_ABI_NOTES.md): how to call Logitech's + SDK correctly, taken from its machine code. What is verified and what is + still assumed are marked as such. +- [**docs/SYSFS_API.md**](docs/SYSFS_API.md): every attribute this driver exposes. ## Acknowledgments Most of what this driver knows about the hardware came from people who tested wheels the maintainers do not own and reported what happened. They -are credited individually in **[CREDITS.md](CREDITS.md)**, which is where -the work that never shows up in a commit log is recorded. +are credited individually in **[CREDITS.md](CREDITS.md)**. That is where the +work that never shows up in a commit log is recorded. The projects this one is built on: diff --git a/docs/BUTTON_MAPPING.md b/docs/BUTTON_MAPPING.md index 43ff7f6..9b619e8 100644 --- a/docs/BUTTON_MAPPING.md +++ b/docs/BUTTON_MAPPING.md @@ -1,21 +1,22 @@ # Button Mapping -The physical controls on the RS50 / G PRO wheel and hub, and the joystick button -index each one reports. Buttons use sequential indices matching Windows -DirectInput, so bindings stay consistent across platforms. +This page lists the physical controls on the RS50 / G PRO wheel and hub. It +gives the joystick button index each one reports. Buttons use sequential +indices that match Windows DirectInput (the Windows game-input interface). +So bindings stay the same across platforms. This is the reference for binding controls in a game. The wire-level bitmask (which report bit encodes which button) is in [PROTOCOL_SPECIFICATION.md](PROTOCOL_SPECIFICATION.md). The G923 has its own -table below: it reports its own classic button layout straight from its HID -descriptor, not the RS50/G PRO one. +table below. It reports its own classic button layout straight from its HID +descriptor (the device's own list of its controls), not the RS50/G PRO one. ![RS50 button layout](images/rs-wheel-hub-button-layout.png) The **Index** column is the joystick button number games show when binding (sequential, matching Windows DirectInput). The **Diagram #** column is the -numbered callout box in the layout image above - the two numbering systems -are unrelated, so a button's index and its diagram number usually differ. +numbered callout box in the layout image above. The two numbering systems +are unrelated. So a button's index and its diagram number usually differ. | Index | Button | Diagram # | |-------|--------|-----------| @@ -41,18 +42,20 @@ are unrelated, so a button's index and its diagram number usually differ. | 28 | GL | 13 | | 29 | GR | 7 | -GL and GR are their own buttons, not aliases of the shifter paddles -(hardware-verified 2026-07-20 by guided capture: evdev 0x2cc / 0x2cd, -sequential after G1). +GL and GR are their own buttons, not aliases of the shifter paddles. This +was hardware-verified on 2026-07-20 by guided capture: evdev 0x2cc / 0x2cd, +sequential after G1. evdev is the Linux input event interface. The D-pad reports as a hat switch (`ABS_HAT0X` / `ABS_HAT0Y`), not as four -buttons - diagram callout "D". +buttons. It is diagram callout "D". ## RS H-Shifter (046d:c26b) ### 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 you connect the shifter 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. | Index | Button / Gear | evdev Code | Wire bitmask (Report 0x08) | |---|---|---|---| @@ -68,18 +71,21 @@ When connected to the wheel base accessory port (sub-device 03), gears 1 to 7 an ### 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: +When you connect the shifter directly to the PC via USB +(`046d:c26b Logitech RS H-Shifter`), it enumerates as an independent +joystick. It reports 8 digital buttons: - Buttons 0 to 6 (`0x120`..`0x126`): 1st through 7th gear - Button 7 (`0x127`): Reverse (R) ## G923 -The G923's own button layout, hardware-captured 2026-07-27 by a guided live -capture (every physical button pressed in turn, its joystick index -recorded) on a PS-edition unit (PID 0xc266). It reports the same sequential -DirectInput indexing as the RS50/G PRO above, but a different set of -buttons: no G1/GL/GR, and only one dial (right hand; the G923 has no left -encoder at all). +This is the G923's own button layout. It was hardware-captured on +2026-07-27 by a guided live capture on a PS-edition unit (PID 0xc266, the +USB product id). Every physical button was pressed in turn, and its +joystick index recorded. The G923 reports the same sequential DirectInput +indexing as the RS50/G PRO above, but a different set of buttons. It has no +G1/GL/GR. It has only one dial (right hand); the G923 has no left encoder +at all. | Index | Button | |-------|--------| @@ -102,9 +108,9 @@ encoder at all). | 23 | Dial Push | | 24 | PS | -Indices 12 to 18 are gaps in the HID descriptor (unused). Indices 19-20 -(Plus/Minus) are real buttons on the G923, unlike the RS50/G PRO, which -have no buttons there at all. +Indices 12 to 18 are gaps in the HID descriptor (unused). Indices 19 to 20 +(Plus/Minus) are real buttons on the G923. The RS50/G PRO have no buttons +there at all. The D-pad reports as a hat switch (`ABS_HAT0X` / `ABS_HAT0Y`), not as four -buttons, same as the RS50/G PRO. +buttons, the same as the RS50/G PRO. diff --git a/docs/DINPUT_ESCAPE.md b/docs/DINPUT_ESCAPE.md index dfbe5d3..d692aa8 100644 --- a/docs/DINPUT_ESCAPE.md +++ b/docs/DINPUT_ESCAPE.md @@ -1,8 +1,10 @@ # Native force feedback and TrueForce under Proton: what is actually in the way Neither force feedback nor TrueForce reaches a direct-drive wheel from a -Logitech SDK title under Proton. The wheel, the driver and the SDK are all -healthy; something in the handshake between the game and the SDK is not. +Logitech SDK title under Proton. TrueForce is Logitech's high-rate haptic +channel. Proton is the Wine-based Windows compatibility layer in Steam. The +wheel, the driver and the SDK are all healthy. Something in the handshake +between the game and the SDK is not. > **This has worked before, and that constrains every theory here.** > `docs/TRUEFORCE_PROTOCOL.md` records AC EVO driving an RS50 in **native** @@ -30,33 +32,34 @@ Everything here was measured on an RS50 (`046d:c276`) in Assetto Corsa EVO on | The game streams torque | **yes**, `logiTrueForceSetTorqueKF` at ~190/sec | | What still fails | the wheel oscillates: the force loop is not held open (#57) | -> The first capture in this document showed zero output transfers and was +> The first capture in this document showed zero output transfers. It was > taken with a parked car and nobody touching the wheel, which is exactly > when a correct stream carries zeros. Later captures while driving show the > stream running. Do not read the early rows as evidence of a dead link. ## Three faults, stacked -Each of these hid the one below it, which is why this took so long to see. +Each of these hid the one below it. That is why this took so long to see. 1. **Our registered SDK path was unopenable.** A quoting change in 0.27.1 - halved every backslash in the CLSID's value, so the path named a file that - did not exist and the SDK never loaded. Fixed; the installer now derives - the path from one source and verifies it resolves to a real file. + halved every backslash in the CLSID's value. So the path named a file that + did not exist, and the SDK never loaded. Fixed. The installer now derives + the path from one source and verifies that it resolves to a real file. 2. **An unsigned SDK can never load.** The game reads the DLL path from the CLSID's default value and calls `WinVerifyTrust` before loading it. Our `--proxy` build is refused before its first instruction. This is a hard - ceiling on replacing that DLL and explains several dead ends recorded + ceiling on replacing that DLL. It explains several dead ends recorded against issue #27 as protocol problems. 3. **Logitech's own operating-range getters break the wheel's HID++ channel.** - Answering them locally is what lets the TrueForce stream start at all; - measured below. With that done the stream runs and the remaining problem - is the wheel running away for want of a force session (#57). + Answering them locally is what lets the TrueForce stream start at all. + This is measured below. With that done the stream runs. The remaining + problem is the wheel running away for want of a force session (#57). ## What the game sends, and what it is not -The game calls `IDirectInputDevice8::Escape` at 187 calls per second with a -20-byte payload: +The game calls `IDirectInputDevice8::Escape` at 187 calls per second. Escape +is DirectInput's vendor pass-through call (DirectInput is the older Windows +force-feedback interface). Each call carries a 20-byte payload: | Offset | Size | Meaning | |---|---|---| @@ -66,18 +69,18 @@ The game calls `IDirectInputDevice8::Escape` at 187 calls per second with a | 12 | 4 | **float: first-shift-light rpm** (established 2026-08-14, verified against the in-game dash; per-car, live in every packet) | | 16 | 4 | **float: redline** (established 2026-08-14, dash-verified; per-car, live in every packet) | -RPM was established, not guessed: with the car **stationary**, four rev cycles -and a held fifth pull reproduced exactly that pattern in the live field, and -nothing else in a stationary car varies that way. +RPM was established, not guessed. With the car **stationary**, four rev cycles +and a held fifth pull reproduced exactly that pattern in the live field. +Nothing else in a stationary car varies that way. **This is the game's engine state, not the SDK's haptic output.** The game sends it even when the SDK has never loaded (3012 calls in a run where the -CLSID path was still broken), so it is an input to the Logitech stack rather -than a product of it. Do not mistake it for TrueForce: what the SDK generates -has never been observed leaving it. +CLSID path was still broken). So it is an input to the Logitech stack, not a +product of it. Do not mistake it for TrueForce. What the SDK generates has +never been observed leaving it. -Wine returns `DI_OK` for every one of these while doing nothing, so the sender -has no way to know they went nowhere. +Wine returns `DI_OK` for every one of these while it does nothing. So the +sender has no way to know they went nowhere. ## The component that is missing @@ -86,15 +89,15 @@ G HUB installs `Logitech\Direct Input Force Feedback\\`: - `hidpp_forcefeedback_x64.dll` for the HID++ wheels - `jerry_forcefeedback_x64.dll` for the classic wheels -`hidpp_forcefeedback_x64.dll` is a COM in-process server implementing +`hidpp_forcefeedback_x64.dll` is a COM in-process server. It implements **`IDirectInputEffectDriver`** (its RTTI carries `.?AUIDirectInputEffectDriver@@`). On Windows, DirectInput finds it through System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Joystick\OEM\VID_046D&PID_xxxx\OEMForceFeedback and routes **force-feedback effects and `Escape`** to it. It opens the wheel -itself via `SETUPAPI`/`CFGMGR32` and `CreateFile`, importing no `HID.DLL` and -referencing no G HUB agent, so it needs no background service. +itself via `SETUPAPI`/`CFGMGR32` and `CreateFile`. It imports no `HID.DLL` +and references no G HUB agent, so it needs no background service. `DllRegisterServer` registers two CLSIDs: @@ -112,7 +115,7 @@ The device ids in `hidpp_forcefeedback_x64.dll` are VID_046D&PID_C262, C268, C26E, C272 -**`C276` is absent**, and appears nowhere in that package. `C272` is the +**`C276` is absent**, and it appears nowhere in that package. `C272` is the RS50's *compatibility* mode. So even on Windows, this driver has nothing to say about an RS50 in native mode. @@ -124,32 +127,32 @@ Registered into a prefix with `regsvr32` and probed directly (Wine 11.14): GetVersions -> 0x00000000 firmware/hardware/driver = 0x010003e7 DeviceID(external=0) -> crash: movups (%rbx),%xmm0 with rbx = 0 -So the driver loads and answers under Wine. `DeviceID` dereferences null, -which is consistent with its "no supported device found" path being unhandled: -the only wheel attached was a `c276`, which it does not recognise. Adding the -`OEMForceFeedback` registry entries for `C276` and `C272` did not change it, -which suggests the device filter is an internal PID list rather than the -registry. +So the driver loads and answers under Wine. `DeviceID` dereferences null. +That is consistent with its "no supported device found" path being +unhandled: the only wheel attached was a `c276`, which it does not recognise. +Adding the `OEMForceFeedback` registry entries for `C276` and `C272` did not +change it. That suggests the device filter is an internal PID list rather +than the registry. ## Where the OEM driver does and does not fit Given the 2026-07-08 evidence above, this driver is **not** required for -TrueForce: the SDK reached the wheel directly then, and can again. Its +TrueForce. The SDK reached the wheel directly then, and it can again. Its relevance is narrower and still real: -- It is how **force feedback** works on Windows for these wheels, which is +- It is how **force feedback** works on Windows for these wheels. That is the half that currently dies under `PROTON_ENABLE_HIDRAW`. If it can be driven under Wine, force feedback stops depending on Proton's evdev - backend and the hidraw trade-off disappears. + backend, and the hidraw trade-off disappears. - It consumes the `Escape` engine-state stream on Windows. The "so it is also where rev lights would come from" conclusion this line once drew is - **superseded** (2026-08-14): the dinput8-escape proxy now relays the + **superseded** (2026-08-14). The dinput8-escape proxy now relays the Escape telemetry triple (live rpm, first-shift-light rpm, redline) over - the LTFR datagram, and `logi-rpm-bridge` drives the rev strip through - `wheel_rev_level` - rev lights work with no OEM driver in the path. + the LTFR datagram. `logi-rpm-bridge` drives the rev strip through + `wheel_rev_level`. Rev lights work with no OEM driver in the path. -It is not the explanation for the SDK going quiet, and treating it as one -would be chasing the wrong thing. +It is not the explanation for the SDK going quiet. Treating it as one would +be chasing the wrong thing. ## What follows @@ -158,12 +161,12 @@ Two things have to be true at once, and only one of them is ours: 1. **The wheel must present an id the driver knows.** For an RS50 that means compatibility mode (`c272`) rather than native (`c276`). Untested. 2. **Something must route effects and `Escape` to the driver**, because Wine - does not. That can be done from `tools/dinput8-escape-proxy.cpp`, which is - already in the call path, is not signature-checked, and already wraps every - `IDirectInputDevice8`. + does not. That can be done from `tools/dinput8-escape-proxy.cpp`. It is + already in the call path, it is not signature-checked, and it already + wraps every `IDirectInputDevice8`. If both hold, the result is native force feedback and native TrueForce from -Logitech's own driver, which is the outcome worth having. +Logitech's own driver. That is the outcome worth having. ### Why this would also fix force feedback, not just TrueForce @@ -175,20 +178,20 @@ Force feedback currently depends on which backend Proton picked: | not set | dead | works, via Proton's synthesised evdev device | With the OEM driver in the path, force feedback comes from Logitech's driver -over HID++ rather than from a PID collection, so it no longer needs the evdev +over HID++ rather than from a PID collection. So it no longer needs the evdev backend, and raw HID stops being a trade-off. ## Things that look like causes and are not - **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 - them and Windows users are equally without. The game probes optionally. + `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 + 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. + themselves. Neither references `LGHUB`, a pipe, or a socket to one. - **Device permissions.** The wheel's `/dev/hidraw*` nodes carry a `uaccess` - ACL and open read/write as the desktop user; `winebus` holds all three open + ACL and open read/write as the desktop user. `winebus` holds all three open while a game runs. - **The SDK not finding the wheel.** It opens `mi_02`, the correct interface. @@ -213,18 +216,19 @@ The game is not refusing to drive the wheel. In order, it: It never calls `dllClose` or `logiWheelClose`, so it does not give up. **`SetTorqueKF`, not `SetTorqueTF`.** Watching only the `SetTorqueTF*` family -showed zeros for hours and produced the wrong conclusion that the game sends +showed zeros for hours. That produced the wrong conclusion that the game sends nothing. The KF family is a full channel with its own gain, maximum torque, reconstruction filter and clear. ### Answering the operating-range questions is load-bearing -Separate launches, toggled with `LOGI_RANGE_FIX`. Honestly stated: this is -a strong correlation, not a controlled single-variable experiment. The wheel -carries state across game restarts (a disturbed session left it misbehaving -into the next run at least once), so session hysteresis is a confound. -Fix off was bad in two of two launches; fix on was good in two of three, -with the bad one immediately following a deliberately torn-down stream: +These were separate launches, toggled with `LOGI_RANGE_FIX`. Honestly +stated: this is a strong correlation, not a controlled single-variable +experiment. The wheel carries state across game restarts (a disturbed +session left it misbehaving into the next run at least once), so session +hysteresis is a confound. Fix off was bad in two of two launches. Fix on was +good in two of three, and the bad one immediately followed a deliberately +torn-down stream: | | answered by us | answered by the SDK | |---|---|---| @@ -234,34 +238,34 @@ with the bad one immediately following a deliberately torn-down stream: | wheel input reports on ep1 | 9918 | **0** | | the game | normal | stutters, car will not move | -With Logitech's own implementations in the path the TrueForce stream never -starts and the wheel stops reporting input altogether. There are **no** control -transfers in either case, so this is not slow HID++ queries: those functions -take the wheel's HID++ channel out of service. +With Logitech's own implementations in the path, the TrueForce stream never +starts and the wheel stops reporting input altogether. There are **no** +control transfers in either case, so this is not slow HID++ queries. Those +functions take the wheel's HID++ channel out of service. This is the same function family `tools/tf-range-proxy.c` was written against -for issue #27's 90 degree clamp, which now looks like the same root cause seen +for issue #27's 90 degree clamp. That now looks like the same root cause seen from a different angle. ### Reading the captures: two traps -Two measurement artefacts ran through this investigation and should be -remembered before trusting any single capture: +Two measurement artefacts ran through this investigation. Remember them +before trusting any single capture: - **The wheel only sends input reports on change.** A parked rim produces - zero ep1 traffic, so "no input reports" alone never proves a wedged wheel - (this is already recorded in the project's test notes, and was still - misread twice today). -- The physical rim was watched over a webcam during the runaway and really + zero ep1 traffic. So "no input reports" alone never proves a wedged wheel. + (This is already recorded in the project's test notes, and it was still + misread twice today.) +- The physical rim was watched over a webcam during the runaway. It really was rotating violently, so that event was real force, not a graphic - artefact. The caveat that survives is narrower: in-game wheel motion and - physical rim motion are separate observables, and a frozen or off-centre - input axis can make the in-game wheel look wild while the rim sits still, - so captures should say which one they mean. + artefact. The caveat that survives is narrower. In-game wheel motion and + physical rim motion are separate observables. A frozen or off-centre + input axis can make the in-game wheel look wild while the rim sits still. + So captures should say which one they mean. ## 2026-08-12 evening: the transport works; the SDK is the only thing not using it -A power cycle reset the wheel, and every "no effects" symptom that followed +A power cycle reset the wheel. Every "no effects" symptom that followed is one finding: **Logitech's SDK does not emit the TrueForce stream under Proton on a clean wheel.** Measured across a full A/B: @@ -271,32 +275,32 @@ Proton on a clean wheel.** Measured across a full A/B: | current, tonight | 0 | 0 | 193 | | v0.24.0 baseline, tonight | 11980 | 0 | 22k | -The kernel module is not the variable: v0.24.0 restored input reporting but +The kernel module is not the variable. v0.24.0 restored input reporting but still produced no ep3 stream. The game's handshake is byte-identical to the -working morning run - dllOpen, SetForceMode(1) accepted, KF streaming at -~190/sec - yet the SDK writes nothing to endpoint 3. +working morning run (dllOpen, SetForceMode(1) accepted, KF streaming at +~190/sec), yet the SDK writes nothing to endpoint 3. -**This morning's 11745-packet stream was almost certainly ours**, from the -FF_CONSTANT keepalive session, which triggers the driver's own 68-packet TF -init and streaming. Not the SDK's. The SDK has not been observed emitting -the stream in any clean test. +**This morning's 11745-packet stream was almost certainly ours.** It came +from the FF_CONSTANT keepalive session, which triggers the driver's own +68-packet TF init and streaming. It was not the SDK's. The SDK has not been +observed emitting the stream in any clean test. **Our TF transport, by contrast, works on the fresh wheel.** `logi-tf-sim --sweep` with no game running produced a correct session on ep3: init, START, 2879 type-0x01 audio-sample packets at ~2 kHz with real varying content, -STOP. Confirmed by feel - the owner felt the sweep. +STOP. Confirmed by feel: the owner felt the sweep. So the fix does not route through Logitech's SDK at all. The game's KF torque -(190/sec, cleanly intercepted by the dinput8 proxy) is the SDK's *input*, and -our TF channel is the transport the SDK would have used. Path: game -> KF -torque -> proxy -> driver TF channel -> wheel. No Logitech binary in the force -path, so no dependency on one that will not run correctly here. The forces are -the game's own; only the interpolation from ~190 Hz to 2 kHz is ours (the SDK -uses GetReconstructionFilterKF for the same step), which is the one thing that -is close rather than provably bit-identical. +(190/sec, cleanly intercepted by the dinput8 proxy) is the SDK's *input*. Our +TF channel is the transport the SDK would have used. Path: game -> KF +torque -> proxy -> driver TF channel -> wheel. No Logitech binary is in the +force path, so there is no dependency on one that will not run correctly +here. The forces are the game's own. Only the interpolation from ~190 Hz to +2 kHz is ours (the SDK uses GetReconstructionFilterKF for the same step). +That is the one thing that is close rather than provably bit-identical. ### Superseded: the runaway theory -The runaway below was real but is now understood as the range-clamp war plus +The runaway below was real. It is now understood as the range-clamp war plus an uncontrolled force session, not the core blocker. Kept for the record. ### It is not usable yet: the wheel runs away @@ -305,28 +309,28 @@ With the range questions answered, the 2 kHz stream carries real content and the rim moves through roughly full travel. That is **not** a working force feedback reading. `logi-tf-sim`'s `ffb_keepalive` documents this exact failure for issue #57: streaming to a direct-drive wheel with no force session open -drives it into its stops and oscillates there. Confirmed by feel report: the -wheel swings violently. +drives it into its stops, and it oscillates there. Confirmed by feel report: +the wheel swings violently. -Holding a zero-level `FF_CONSTANT` open does stabilise it, and starts the 2 kHz -stream on its own, but it also stops the `0x0c` traffic that carries the game's -own values: a zero constant appears to cancel the game's torque. +Holding a zero-level `FF_CONSTANT` open does stabilise it, and it starts the +2 kHz stream on its own. But it also stops the `0x0c` traffic that carries +the game's own values. A zero constant appears to cancel the game's torque. So the open question is how to keep a direct-drive wheel's force loop alive -without zeroing what the game is sending. Doing it in the driver when it sees a -TrueForce stream on the vendor interface would cover a game as well as our own -daemon, and is a better depth for it than a userspace effect. +without zeroing what the game is sending. Doing it in the driver, when it +sees a TrueForce stream on the vendor interface, would cover a game as well +as our own daemon. That is a better depth for it than a userspace effect. ## 2026-08-12 late: NATIVE FFB WORKS, and the texture is decoded from Windows captures **Native base force feedback through Logitech's real SDK works under Proton.** -Verified by feel and by wire: after a wheel power cycle, with the dinput8 +Verified by feel and by wire. After a wheel power cycle, with the dinput8 proxy answering the four operating-range getters, the SDK streams type-0x01 packets at 2 kHz with the game's live force in `cur` (11883 packets/6 s, sane values, felt correct). The steering-ratio problem was the SDK's -session-init clamp to 90 degrees: the quiesce patch had removed the -auto-heal, so it stuck. The quiesce is reverted (a single heal holds; the -SDK clamps once and does not fight), and the range poll now runs every 3 s +session-init clamp to 90 degrees. The quiesce patch had removed the +auto-heal, so the clamp stuck. The quiesce is reverted (a single heal holds; +the SDK clamps once and does not fight). The range poll now runs every 3 s, so the heal lands within seconds of track load. ## 2026-08-13: shipped - the texture is a kernel splice, and the OEM path is closed @@ -335,22 +339,22 @@ Two things this document was open on are now settled. **The base FFB recipe above is productized, not a manual step anymore.** `logi-launch %command%` stages the range-answering proxy itself for Assetto -Corsa EVO on a direct-drive wheel: it copies `dinput8-escape.dll` into the -game's install directory and sets `WINEDLLOVERRIDES=dinput8=n,b`, tearing +Corsa EVO on a direct-drive wheel. It copies `dinput8-escape.dll` into the +game's install directory and sets `WINEDLLOVERRIDES=dinput8=n,b`. It tears both down again on exit. The power cycle this document found necessary for a -clean SDK session is still the user's to do; nothing here changes that. +clean SDK session is still the user's to do. Nothing here changes that. **The engine-note texture is a kernel splice into the SDK's own stream, and -it is hardware-validated.** Rather than chase the SDK into sending texture it -was never observed sending on any OS, the driver now inserts synthesised -samples into the type-0x01 packets it is already relaying, the same point -G HUB merges at on Windows. Measured on the RS50 (module `9C1B5855`, -2026-08-13): +it is hardware-validated.** The SDK was never observed sending texture on +any OS, so there was no point chasing it into sending some. Instead the +driver now inserts synthesised samples into the type-0x01 packets it is +already relaying, the same point G HUB merges at on Windows. Measured on the +RS50 (module `9C1B5855`, 2026-08-13): - merge off is byte-identical passthrough: 7847 packets, every one `byte10=00`, `cur=0x8000`; -- merge on with no RPM fed is untouched, proving the stale/zero gate on real - hardware, not just in the unit tests; +- merge on with no RPM fed is untouched, which proves the stale/zero gate on + real hardware, not just in the unit tests; - merge on with 6000 rpm fed splices every packet at the 4 kHz sample budget, `cur` bit-identical in every packet, sample rms 523.2 counts against the 524-count capture-fit target (0.2% off), and the dominant frequency exactly @@ -359,7 +363,7 @@ G HUB merges at on Windows. Measured on the RS50 (module `9C1B5855`, auto-heal restores 900 in under 2 s with no manual write, logged as `restored range to 900 after SDK push (attempt 1/3)`; - killing the RPM feed lets the texture die out inside the 200 ms staleness - window, rather than droning on stale data. + window, rather than drone on stale data. `logi-launch %command%` arms this automatically for Assetto Corsa EVO on a direct-drive wheel: proxy staged, `logi-rpm-bridge` started, the merge turned @@ -367,44 +371,45 @@ on, all torn down again when the game exits. **The OEM driver / compat-mode path is a dead end, not an unfinished lead.** `hidpp_forcefeedback_x64.dll`'s device id list never contains `C276`, the -RS50's native mode, on Windows either, so there was never a version of this +RS50's native mode, on Windows either. So there was never a version of this where that driver had something to say about this wheel's native identity. More to the point, the texture it would have carried is not a wire format to -reverse: on Windows it is G HUB synthesising it from the game's RPM on the +reverse. On Windows it is G HUB synthesising it from the game's RPM on the host and merging it into the SDK stream, the same operation this feature now -does in the kernel. There was no captured protocol to complete; the destination -was always synthesis, and the driver now does that synthesis itself. +does in the kernel. There was no captured protocol to complete. The +destination was always synthesis, and the driver now does that synthesis +itself. **2026-08-14**: the merge was re-validated against the LIVE Logitech SDK -stream rather than a replay - 11,217 of 11,219 real stream packets spliced, +stream rather than a replay: 11,217 of 11,219 real stream packets spliced, sample rms 411.2 against the 411 capture-fit target, spectrum peak exactly at the fed firing frequency, and the SDK's own `cur` bytes byte-identical -throughout. Two bugs surfaced during the same pass and are fixed: the +throughout. Two bugs surfaced during the same pass, and both are fixed. The 90-degree auto-restore's original decode read the range push at the wrong -bytes (8-11 instead of the real 6-9, see `docs/TRUEFORCE_PROTOCOL.md`), so it -ignored every real push from a live session while a synthetic test built -against the same wrong offset kept passing - fixed and unit-tested against -the captured frames; and a pre-existing rmmod NULL-deref in the interface-2 -close path was found (`hid_hw_close` on a `hid_device` that had already lost -its driver binding), with teardown now validating the binding under -`device_lock` before touching it. +bytes (8-11 instead of the real 6-9, see `docs/TRUEFORCE_PROTOCOL.md`). So it +ignored every real push from a live session, while a synthetic test built +against the same wrong offset kept passing. That is fixed and unit-tested +against the captured frames. A pre-existing rmmod NULL-deref in the +interface-2 close path was also found (`hid_hw_close` on a `hid_device` that +had already lost its driver binding). Teardown now validates the binding +under `device_lock` before it touches it. ### 2026-09-12: the SDK announces its range through an escape Assetto Corsa EVO on a G923 Xbox edition, proxy log. The game resolves the -SDK's range setters by name and never calls them, and changing the -in-game steering lock produces no SDK call and no escape: on this route the -game's lock goes nowhere at all. What does appear is a DirectInput escape, -command 5, sent by the SDK itself right after the proxy sets the operating -range through the setter: a 20-byte block, no answer expected -(`cbOutBuffer` 0), bytes 0-3 the block size, bytes 4-7 the value 1, bytes +SDK's range setters by name and never calls them. Changing the in-game +steering lock produces no SDK call and no escape. On this route the game's +lock goes nowhere at all. What does appear is a DirectInput escape, command +5, sent by the SDK itself right after the proxy sets the operating range +through the setter. It is a 20-byte block with no answer expected +(`cbOutBuffer` 0): bytes 0-3 the block size, bytes 4-7 the value 1, bytes 8-11 varying (they resemble the low half of the SDK handle), the last eight bytes the range as a little-endian double (900.0). Escapes of the same form -at start-up carry 0.0 and 39.99999, other properties; command 5 with +at start-up carry 0.0 and 39.99999, other properties. Command 5 with `cbOutBuffer` 8 is a getter. On Windows that escape is how Logitech's -driver learns the range the SDK was given and sets the wheel; under Wine +driver learns the range the SDK was given and sets the wheel. Under Wine it is dropped. The proxy now applies a command-5 set whose value lies within the range a lock can take (90 to 2700 degrees) to the wheel's sysfs -range, and to nothing else: the first build also called the SDK's setter -from inside the escape, the SDK answered with another escape, and the game +range, and to nothing else. The first build also called the SDK's setter +from inside the escape. The SDK answered with another escape, and the game sat on a black screen in that loop. `LOGI_STEER_LOCK=0` switches it off. diff --git a/docs/FEATURE_MATRIX.md b/docs/FEATURE_MATRIX.md index 5a1d34a..55e8e4f 100644 --- a/docs/FEATURE_MATRIX.md +++ b/docs/FEATURE_MATRIX.md @@ -1,11 +1,13 @@ # HID++ feature matrix -What each wheel reports, against what this driver uses. Enumerated on -hardware 2026-08-08 by asking `ROOT.GetFeature` for every gaming feature in -Logitech's published HID++ 2.0 registry (mirrored in Solaar's -`hidpp20_constants.py`), rather than by reading captures. +HID++ is Logitech's configuration protocol over USB. This page lists what +each wheel reports, against what this driver uses. The list was made on +hardware on 2026-08-08. The method: ask `ROOT.GetFeature` for every gaming +feature in Logitech's published HID++ 2.0 registry (mirrored in Solaar's +`hidpp20_constants.py`). It was not read from captures. -The driver logs its own line of this at probe: +The driver logs its own line of this at probe (the first set-up of the +device): ``` HID++ features (base): 8040=0A 807A=0B 807B=0C 80A4=0D 80D0=0E ... @@ -13,16 +15,17 @@ HID++ features (base): 8040=0A 807A=0B 807B=0C 80A4=0D 80D0=0E ... ## Read this before drawing conclusions from it -**These are BASE-DEVICE answers.** HID++ sub-devices answer separately: the -RS Shifter & Handbrake reports at device index `0x04`, the RS H-Shifter -(`0x812D RS_H_SHIFTER`) at the index of the port it is plugged into, and -their features error out here rather than reporting themselves. `0x80B1 BANDED_AXIS` and -`0x812C WHEEL_CENTER_POSITION` show as absent on the RS50 below and the -driver demonstrably uses both. Absence in this table means "not on the base -device", not "not on the wheel". - -The G923 column is more trustworthy: it answers a clean "not supported" -rather than erroring, because its classic force-feedback path leaves HID++ +**These are BASE-DEVICE answers.** HID++ sub-devices answer separately. +The RS Shifter & Handbrake reports at device index `0x04`. The RS +H-Shifter (`0x812D RS_H_SHIFTER`) reports at the index of the port it is +plugged into. Their features error out here instead of reporting +themselves. `0x80B1 BANDED_AXIS` and `0x812C WHEEL_CENTER_POSITION` show +as absent on the RS50 below, and the driver demonstrably uses both. +Absence in this table means "not on the base device". It does not mean +"not on the wheel". + +The G923 column is more trustworthy. It answers a clean "not supported" +instead of erroring, because its classic force-feedback path leaves HID++ alone. ## The matrix @@ -38,7 +41,7 @@ alone. | `0x8120` GAMING_ATTACHMENTS | 0x0F | **0x0F** | **no** | | `0x8123` FORCE_FEEDBACK | 0x10 | - | yes | | `0x8127` DUAL_CLUTCH | 0x11 | **0x10** | **no** | -| `0x8130` DISPLAY_GAME_DATA | 0x12 | - | **no** | +| `0x8130` DISPLAY_GAME_DATA | 0x12 | - | **yes** (`wheel_oled`) | | `0x8132` AXIS_MAPPING | 0x13 | - | **no** | | `0x8133` GLOBAL_DAMPING | 0x14 | - | yes | | `0x8134` BRAKE_FORCE | 0x15 | - | yes | @@ -48,76 +51,77 @@ alone. | `0x8139` TRUE_FORCE | 0x19 | - | yes | | `0x8140` FFB_FILTER | 0x1A | - | yes | -The G923 reporting neither `FORCE_FEEDBACK` nor `TRUE_FORCE` confirms -independently what captures already showed: the PlayStation edition drives +The G923 reports neither `FORCE_FEEDBACK` nor `TRUE_FORCE`. This confirms +on its own what captures already showed: the PlayStation edition drives force through the classic path, not the 0x8123/0x8139 family. ## The gaps, and what each would actually take -Not filed as issues because none is a small fix, and saying so is more +These are not filed as issues. None is a small fix, and saying so is more useful than a ticket that implies otherwise. -**`0x80A3` on the G923.** The two wheels use different response-curve pages: -the RS50 has `0x80A4`, the G923 has the legacy `0x80A3`. So +**`0x80A3` on the G923.** The two wheels use different response-curve +pages. The RS50 has `0x80A4`. The G923 has the legacy `0x80A3`. So `wheel_response_curve` is structurally unreachable on a G923. This is not a page fallback away from working. The G923 exposes **no** -`wheel_*` attributes at all: it takes the classic path, which has no -settings surface, no feature discovery and no sysfs group. Reaching `0x80A3` -means building that path for this wheel and decoding a page whose function -layout is undocumented. Feature work, not a bug fix. +`wheel_*` attributes at all. It takes the classic path, which has no +settings surface, no feature discovery and no sysfs group. sysfs is the +kernel's settings file tree under `/sys`. Reaching `0x80A3` means building +that path for this wheel. It also means decoding a page whose function +layout is undocumented. That is feature work, not a bug fix. **`0x8127` DUAL_CLUTCH, present on both wheels.** A clutch bite point is a -real thing to want and nothing here offers one. The page's functions are now -known, from a third-party listen on a G923 Xbox edition rather than a G HUB -capture (@fsfarmscaper, [#97](../../issues/97)): the wheel configures the -bite point and the paddle from button combinations on the wheel itself, -`fn2` reads the result back, and every change arrives as an unsolicited -event on the feature index. Writes are acknowledged and change nothing, so -the host's whole job here is to read. See PROTOCOL_SPECIFICATION.md 12.6. -Not implemented yet: the natural form is a read-only attribute plus the -event, and it needs a wheel with a dual clutch to verify against, which no -wheel here has. - -**`0x8120` GAMING_ATTACHMENTS, present on both.** Plausibly the accessory -reporting this driver currently infers by scanning sub-device indices, which -is known awkward (index is a physical port, not a device type). Same -blocker: no function layout. +real thing to want, and nothing here offers one. The page's functions are +now known. They came from a third-party listen on a G923 Xbox edition, not +from a G HUB capture (@fsfarmscaper, [#97](../../issues/97)). G HUB is +Logitech's Windows software. The wheel configures the bite point and the +paddle from button combinations on the wheel itself. `fn2` reads the +result back. Every change arrives as an unsolicited event on the feature +index. Writes are acknowledged and change nothing. So the host's whole job +here is to read. See PROTOCOL_SPECIFICATION.md 12.6. It is not implemented +yet. The natural form is a read-only attribute plus the event. It needs a +wheel with a dual clutch to verify against, and no wheel here has one. + +**`0x8120` GAMING_ATTACHMENTS, present on both.** This is plausibly the +accessory reporting the driver currently infers by scanning sub-device +indices. That scan is known to be awkward: an index is a physical port, +not a device type. The blocker is the same: no function layout. **`0x8130` DISPLAY_GAME_DATA, RS50 only. NOT unknown**, and an earlier -version of this file wrongly said it was. It is the RS50's Dynamic OLED, and +version of this file wrongly said it was. It is the RS50's Dynamic OLED. `PROTOCOL_SPECIFICATION.md` 12.3 has it largely decoded from issue #20: fn0 layout count, fn1 layout descriptor, fn2 clear pending, fn3 set layout/data, ten layouts A-J, a typed firmware renderer rather than a -framebuffer, reached at interface 1 endpoint 0 by SET_REPORT. Reached on -hardware by a third party with static text and live iRacing telemetry, and -since then first-hand on an RS50. Implemented: `wheel_oled` and -`wheel_oled_layouts` in sysfs, a dashboard in `logi-tf-sim` and an editor -with presets in both apps. What is still open is the risk below, which is -the same one the rev lights carry. - -**`0x8132` AXIS_MAPPING, RS50 only.** Unknown, and it would duplicate +framebuffer, reached at interface 1 endpoint 0 by SET_REPORT. A third +party reached it on hardware with static text and live iRacing telemetry. +Since then it has been reached first-hand on an RS50. Implemented: +`wheel_oled` and `wheel_oled_layouts` in sysfs, a dashboard in +`logi-tf-sim`, and an editor with presets in both apps. What is still open +is the risk below. It is the same risk the rev lights carry. + +**`0x8132` AXIS_MAPPING, RS50 only.** Unknown. It would also duplicate something already done host-side. ## Before writing to any of these: a live-force hazard -`PROTOCOL_SPECIFICATION.md` 12.5 records, from two independent third -parties, that **while force is present on the HID++ endpoint a non-force -write to that endpoint cuts the force.** Regardless of sender, size or -pacing; a 60 ms floor fixed nothing. Rev-light writes on `0x807A` during a -game's force were the original case. +`PROTOCOL_SPECIFICATION.md` 12.5 records this, from two independent third +parties: **while force is present on the HID++ endpoint, a non-force write +to that endpoint cuts the force.** This holds regardless of sender, size +or pacing. A 60 ms floor fixed nothing. Rev-light writes on `0x807A` +during a game's force were the original case. -That is a constraint on every feature in the "not implemented" list, because -each would be exactly such a write. It also bears directly on issue #27: the -G923 Xbox edition is the only wheel here whose force rides HID++, so driving -its rev lights over `0x807A` may cost force feedback while the lights update -even if the feature is present. Finding the feature is therefore necessary -and not sufficient. +That is a constraint on every feature in the "not implemented" list, +because each would be exactly such a write. It also bears directly on +issue #27. The G923 Xbox edition is the only wheel here whose force rides +HID++. So driving its rev lights over `0x807A` may cost force feedback +while the lights update, even if the feature is present. Finding the +feature is therefore necessary and not sufficient. -The enumeration this file records is safe on that count: it runs once at +The feature scan this file records is safe on that count. It runs once at probe, before any force exists. -All four want the same thing before code: a capture of G HUB exercising the -control. That is the routine this project has used for every other page it -implements, and there is no shortcut that does not amount to guessing at a -wheel's firmware. +All four want the same thing before code: a capture of G HUB exercising +the control. That is the routine this project has used for every other +page it implements. There is no shortcut that does not amount to guessing +at a wheel's firmware. diff --git a/docs/GAME_SETUP.md b/docs/GAME_SETUP.md index be66d35..cff39f5 100644 --- a/docs/GAME_SETUP.md +++ b/docs/GAME_SETUP.md @@ -1,50 +1,65 @@ # Game setup, per game and per wheel -**Generated file. Do not edit.** It is rendered from the -compatibility registry in -`userspace/logi-wheel/crates/logi-wheel-core/src/games.rs` by -`tests/game_setup_doc.rs`, which fails if this file drifts from it. -The settings app resolves your own installed games against that same -registry, so what you read here is what the app will tell you. - -**Most people need none of this.** `logi-launch %command%` in a -game's Steam launch options works the whole recipe out for the game -being launched and the wheel attached, and applies it: the raw-HID -setting only where that wheel wants it, the logi-ffb proxy for the -DirectInput games, the telemetry daemon, and the relay inside the -game's prefix for the sims that need one. A game with its own -TrueForce keeps it, and nothing is layered on top. See +**Generated file. Do not edit.** The compatibility registry in +`userspace/logi-wheel/crates/logi-wheel-core/src/games.rs` is the +source. `tests/game_setup_doc.rs` renders this file from it. The test +fails if this file drifts from the registry. The settings app checks +your own installed games against that same registry. So what you +read here is what the app will tell you. + +**Most people need none of this.** Put `logi-launch %command%` in a +game's Steam launch options. Launch options are the command Steam +runs to start a game. `logi-launch` works out the whole recipe for +the game and the attached wheel, and applies it. It sets the raw-HID +setting only where that wheel wants it. (Raw HID gives a game direct +access to the wheel's USB reports.) It starts the logi-ffb proxy for +the DirectInput games. (DirectInput is the older Windows +force-feedback interface. The proxy is a virtual wheel that forwards +force to the real one.) It starts the telemetry daemon. (Telemetry +is the live data a game publishes about the car: rpm, gear, speed.) +It puts the relay inside the game's prefix for the sims that need +one. (The prefix is the private Windows folder that Proton, Steam's +layer for running Windows games, makes for each game.) A game with +its own TrueForce keeps it. Nothing is layered on top. See LAUNCH_OPTIONS.md. -**This table is for doing it by hand**, or for working out what went -wrong. Read on for why the answer differs per wheel. +**This table is for doing it by hand**, or for finding out what went +wrong. Read on to see why the answer differs per wheel. What a game needs depends on the wheel as well as the game. The -direct-drive wheels answer Logitech's TrueForce SDK, so a sim with -built-in TrueForce reaches them through the staged SDK DLLs, and -`PROTON_ENABLE_HIDRAW=1` is what lets it. +direct-drive wheels answer Logitech's TrueForce SDK. (The SDK is +Logitech's library that a game loads to send TrueForce haptics.) A +sim with built-in TrueForce reaches them through the staged SDK +DLLs. `PROTON_ENABLE_HIDRAW` is what lets it, and `logi-launch` sets it +scoped to the wheel, never the bare `1`. The G923 does not answer that SDK. Setting the variable there does -not add TrueForce, it diverts the game to raw HID reports the wheel -cannot drive force feedback through, so it costs you the force +not add TrueForce. It diverts the game to raw HID reports. The wheel +cannot drive force feedback through those. So it costs you the force feedback you already had. Leave it unset. -That wheel is still capable of haptics in those games, by a -different route: `logi-tf-sim` synthesizes an engine note from the -game's own telemetry, read out of its shared memory by a small relay -(`docs/SHARED_MEMORY_RELAY.md`). Confirmed working on a G923 in -Assetto Corsa Competizione and EVO. +That wheel can still have haptics in those games, by a different +route. `logi-tf-sim` synthesizes an engine note from the game's own +telemetry. A small relay reads that telemetry out of the game's +shared memory (`docs/SHARED_MEMORY_RELAY.md`). This is confirmed +working on a G923 in Assetto Corsa Competizione and EVO. The shim's `--proxy` option is not a second route in these games. -Both check the library's signature before loading it and refuse the -unsigned proxy, so it carries nothing, and on a wheel that uses -Logitech's library it costs the game that library's force feedback -too. `./tools/setup.sh doctor` flags a prefix that has it. +(The shim is the set of Logitech SDK files staged into a game's +prefix.) Both games check the library's signature before they load +it. They refuse the unsigned proxy, so it carries nothing. On a wheel +that uses Logitech's library, it also costs the game that library's +force feedback. `./tools/setup.sh doctor` flags a prefix that has +it. -Launch options go in Steam under the game's Properties. Paste them -exactly, `%command%` included: it is the placeholder Steam replaces -with the game itself, so without it the line replaces the game -instead of wrapping it. +To set launch options: + +1. In Steam, open the game's Properties. +2. Paste the line into Launch Options, exactly, `%command%` +included. + +`%command%` is the placeholder Steam replaces with the game itself. +Without it, the line replaces the game instead of wrapping it. ## Recipes @@ -81,31 +96,32 @@ instead of wrapping it. | TOCA Race Driver 3 | Proton | Native FFB | Nothing to do | Nothing to do | | Wreckfest | Proton | Native FFB | Nothing to do | Nothing to do | -Rows marked `*` are not confirmed on this driver yet: expected or -documented rather than tested end to end. +Rows marked `*` are not confirmed on this driver yet. They are +expected or documented, not tested end to end. ## Simulated TrueForce Games with no TrueForce of their own can still have engine haptics -and rev lights, synthesized by `logi-tf-sim` from whatever telemetry -the game publishes. This works on every supported wheel, including -the G923: it is ordinary force feedback driven from telemetry, not -the SDK. - -How the telemetry reaches the daemon depends on the game. Most -broadcast it over UDP and only need that switched on in their own -settings. Euro Truck Simulator 2 and American Truck Simulator use a -plugin instead (`docs/SCS_PLUGIN.md`), and iRacing publishes to -shared memory that a small in-prefix relay forwards -(`docs/SHARED_MEMORY_RELAY.md`). Either way, enable the game in the -app's Setup page afterwards. +and rev lights. `logi-tf-sim` synthesizes them from whatever +telemetry the game publishes. This works on every supported wheel, +including the G923. It is ordinary force feedback driven from +telemetry, not the SDK. + +How the telemetry reaches the daemon depends on the game. Most games +broadcast it over UDP. (UDP is a simple network protocol. The game +sends packets to a port.) Those games only need that switched on in +their own settings. Euro Truck Simulator 2 and American Truck +Simulator use a plugin instead (`docs/SCS_PLUGIN.md`). iRacing +publishes to shared memory, and a small in-prefix relay forwards it +(`docs/SHARED_MEMORY_RELAY.md`). In every case, enable the game in +the app's Setup page afterwards. | Game | Simulated TrueForce | |---|---| | American Truck Simulator | supported today | | Assetto Corsa (original) | supported today | -| Assetto Corsa Competizione | the game's own TrueForce is the route to use; on a direct-drive wheel the helper never adds haptics of its own, and where it runs beside the game it drives the rev lights and the screen only; simulated haptics are the fallback for a wheel that cannot receive the real thing | -| Assetto Corsa EVO (early access) | the game's own TrueForce is the route to use; on a direct-drive wheel the helper never adds haptics of its own, and where it runs beside the game it drives the rev lights and the screen only; simulated haptics are the fallback for a wheel that cannot receive the real thing | +| Assetto Corsa Competizione | use the game's own TrueForce; on a direct-drive wheel the helper adds no haptics of its own, and where it runs beside the game it drives only the rev lights and the screen; simulated haptics are the fallback for a wheel that cannot receive the real thing | +| Assetto Corsa EVO (early access) | use the game's own TrueForce; on a direct-drive wheel the helper adds no haptics of its own, and where it runs beside the game it drives only the rev lights and the screen; simulated haptics are the fallback for a wheel that cannot receive the real thing | | Assetto Corsa Rally (early access) | no usable telemetry | | Automobilista 2 | supported today | | BeamNG.drive | supported today | @@ -136,7 +152,7 @@ app's Setup page afterwards. - **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. -- **Nothing to do.** The wheel is an ordinary Linux force feedback device and the game drives it directly. +- **Nothing to do.** The wheel is an ordinary Linux force feedback device. The game drives it directly. ## Confidence diff --git a/docs/LAUNCH_OPTIONS.md b/docs/LAUNCH_OPTIONS.md index 5b12e6a..dc73802 100644 --- a/docs/LAUNCH_OPTIONS.md +++ b/docs/LAUNCH_OPTIONS.md @@ -1,39 +1,57 @@ # Steam launch options, and what each one is for -Everything this project asks you to put in a game's launch options, in one -place. Right-click the game in Steam, **Properties**, **Launch Options**. +This page lists everything this project asks you to put in a game's launch +options. Launch options are the command Steam runs to start a game. To find +them: -`%command%` is the placeholder Steam replaces with the real command that -starts the game. Type it exactly, including the percent signs. Anything to -the left of it runs first; the game itself is what `%command%` becomes. +1. Right-click the game in Steam. +2. Open **Properties**. +3. Open **Launch Options**. + +`%command%` is a placeholder. Steam replaces it with the real command that +starts the game. Type it exactly, with the percent signs. Anything to the +left of it runs first. The game itself is what `%command%` becomes. ## The short version -Put this in every racing game's launch options and stop thinking about it: +Put this in every racing game's launch options, then stop thinking about it: ``` logi-launch %command% ``` It works out what that game needs on the wheel you have attached, and does -it: sets `PROTON_ENABLE_HIDRAW` only where that wheel wants it, launches -through `logi-ffb` for the DirectInput games, starts `logi-tf-sim`, and -starts the telemetry relay inside the game's Proton prefix for the sims that -need one. A game that needs none of it starts none of it, so leaving the -line in place costs nothing. +it: + +- It sets `PROTON_ENABLE_HIDRAW` only where that wheel wants it. (Proton is + Steam's layer for running Windows games. This variable gives the game raw + access to the wheel's USB reports.) +- It launches through `logi-ffb` for the DirectInput games. (DirectInput is + the older Windows force-feedback interface. `logi-ffb` is the proxy, a + virtual wheel that forwards force to the real one.) +- It starts `logi-tf-sim`, the daemon that turns telemetry into haptics. + (Telemetry is the live data a game publishes about the car.) +- It starts the telemetry relay inside the game's Proton prefix for the sims + that need one. (The prefix is the private Windows folder Proton makes for + each game.) + +A game that needs none of this gets none of it. So leaving the line in place +costs nothing. It knows 29 titles by their Steam appid. A game it does not know still gets -the daemon, which is all the UDP-telemetry games need, and you can describe -it yourself (see [Teaching it a new game](#teaching-it-a-new-game)). +the daemon. That is all the UDP-telemetry games need. (UDP is a simple +network protocol. The game sends packets to a port.) You can also describe +the game yourself (see [Teaching it a new game](#teaching-it-a-new-game)). **It will not put simulated TrueForce on a game that has its own.** On a direct-drive wheel, Assetto Corsa Competizione and Assetto Corsa EVO get -their real TrueForce through the shim and nothing is layered on top. On a -G923, where that cannot arrive, the same titles get the simulated kind +their real TrueForce through the shim. (The shim is the set of Logitech SDK +files staged into the game's prefix.) Nothing is layered on top. On a G923, +where real TrueForce cannot arrive, the same titles get the simulated kind instead. -The rest of this page is what `logi-launch` is doing on your behalf, for -when you want to do it by hand or understand what went wrong. +The rest of this page explains what `logi-launch` does on your behalf. Read +it when you want to do the work by hand, or to understand what went wrong. ## What `logi-launch` actually does @@ -41,70 +59,71 @@ In order, when you start a game with it: **1. It asks the app what this game needs.** `logi-wheel --launch-plan ` answers from the compatibility registry, for the wheel currently -attached. Steam already provides the appid in the environment, so nothing -has to be configured. The registry is the same one behind the app's Setup -page: the wrapper decides nothing itself, because a second copy of that -logic in shell is a second copy to drift. - -**2. It sets `PROTON_ENABLE_HIDRAW` only if that wheel wants it here**, and -scoped to that wheel (`0x046D/0xC276`) rather than the bare `1`, which -Proton reads as every HID device on the machine. -Games with their own TrueForce need the raw HID interface to reach the -wheel, and the SDK only delivers it to a direct-drive wheel. On a G923 the -same setting **removes** force feedback, so it is never set speculatively: -no wheel, or two different kinds and none named, means it is withheld and -the log says why. +attached. Steam already provides the appid in the environment, so you +configure nothing. The registry is the same one behind the app's Setup page. +The wrapper decides nothing itself. A second copy of that logic in shell +would be a second copy to drift. + +**2. It sets `PROTON_ENABLE_HIDRAW` only if that wheel wants it here.** It +scopes the value to that wheel (`0x046D/0xC276`), not the bare `1`. Proton +reads a bare `1` as every HID device on the machine. Games with their own +TrueForce need the raw HID interface to reach the wheel. The SDK only +delivers TrueForce to a direct-drive wheel. On a G923 the same setting +**removes** force feedback. So it is never set on a guess. With no wheel, or +with two different kinds and none named, it is withheld, and the log says +why. **3. It chains through `logi-ffb` for DirectInput games.** Le Mans Ultimate, -rFactor 2, iRacing and RaceRoom drive force feedback the old Windows way, -which needs the proxy in front of the game. `logi-launch` execs it rather -than asking you to add a second wrapper. +rFactor 2, iRacing and RaceRoom drive force feedback the old Windows way. +That needs the proxy in front of the game. `logi-launch` execs it for you. +You do not add a second wrapper. **4. It starts `logi-tf-sim` if the game needs it.** The daemon turns a -game's telemetry into TrueForce haptics and rev-light levels. It is left -running afterwards, because it idles when nothing is streaming. If a wheel -was named, the daemon is aimed at that same wheel, so the game and the -haptics cannot end up on different ones. +game's telemetry into TrueForce haptics and rev-light levels. It stays +running afterwards, because it idles when nothing is streaming. If you named +a wheel, the daemon is aimed at that same wheel. So the game and the haptics +cannot end up on different wheels. It is **not** started for a game whose own TrueForce already reaches your -wheel. On a direct-drive wheel, Assetto Corsa Competizione and Assetto -Corsa EVO get the real thing through the shim, and the simulated kind on -top of it would be two engine notes at once. On a G923, where the real one -cannot arrive, those same titles do get it. +wheel. On a direct-drive wheel, Assetto Corsa Competizione and Assetto Corsa +EVO get the real thing through the shim. The simulated kind on top would be +two engine notes at once. On a G923, where the real one cannot arrive, those +same titles do get it. **5. It starts the game.** **6. Once the game has the prefix, it starts `logi-tf-relay` inside it.** -Only for the sims that publish telemetry to Windows shared memory rather -than over the network. This step is last for a reason, and the reason is -not obvious: Proton takes the prefix exclusively when it launches, running -`wineserver -w` and waiting for any existing wineserver to exit. A helper -started **before** the game stops the game from starting at all. So the -wrapper launches the game first and waits for the game's own wineserver to -appear before attaching anything. - -The relay is run with the wine build the prefix itself belongs to, read -from its `config_info`. The distribution's `wine` is a different build, and -pointing it at a Proton-made prefix triggers prefix initialisation, prompts -to install wine-mono, and can convert the prefix. If that build cannot be -found, the relay is skipped rather than run the wrong way. +This is only for the sims that publish telemetry to Windows shared memory +instead of over the network. This step is last for a reason, and the reason +is not obvious. Proton takes the prefix exclusively when it launches. It runs +`wineserver -w` and waits for any existing wineserver to exit. (wineserver is +the background process that runs a Wine prefix.) A helper started **before** +the game stops the game from starting at all. So the wrapper launches the +game first. Then it waits for the game's own wineserver to appear before it +attaches anything. + +The relay runs with the wine build the prefix belongs to, read from the +prefix's `config_info`. The distribution's `wine` is a different build. +Pointing it at a Proton-made prefix triggers prefix initialisation, prompts +to install wine-mono, and can convert the prefix. If the right build cannot +be found, the relay is skipped. It is never run the wrong way. ### What it never does -- Set `PROTON_ENABLE_HIDRAW` on a guess. Wrong here silently costs a G923 - owner their force feedback, and nothing in the game would explain it. +- Set `PROTON_ENABLE_HIDRAW` on a guess. A wrong guess silently costs a G923 + owner their force feedback. Nothing in the game would explain it. - Put simulated TrueForce on a game that already has its own on your wheel. -- Start anything for a game that needs nothing, so leaving the line in - every game's launch options costs nothing. +- Start anything for a game that needs nothing. So leaving the line in every + game's launch options costs nothing. - Offer advice for a title that does not run on Linux at all. ### Seeing what it decided -Everything it does is logged to `/tmp/logi-launch.log`, starting with the -plan it resolved: +Everything it does is logged to `/tmp/logi-launch.log`. The log starts with +the plan it resolved. -Assetto Corsa EVO on a direct-drive wheel, where the game's own TrueForce -is the route and nothing is simulated: +Assetto Corsa EVO on a direct-drive wheel. The game's own TrueForce is the +route, and nothing is simulated: ``` [logi-launch] plan: wheel=direct-drive game=Assetto Corsa EVO (early access) hidraw=0x046D/0xC276 ffb=native relay=none tfsim=0 @@ -112,8 +131,8 @@ is the route and nothing is simulated: [logi-launch] no in-prefix relay needed for this game ``` -The same game on a G923, where it cannot be, so the simulated kind and its -relay are used instead: +The same game on a G923. Real TrueForce cannot arrive there, so the +simulated kind and its relay are used instead: ``` [logi-launch] plan: wheel=classic game=Assetto Corsa EVO (early access) hidraw=unset ffb=native relay=ac-evo tfsim=1 @@ -121,7 +140,7 @@ relay are used instead: [logi-launch] starting c:\logi-tf-relay.exe --game ac-evo in .../compatdata/3058630/pfx ``` -Note there is no `PROTON_ENABLE_HIDRAW` in the second one. That is the +Note that the second one has no `PROTON_ENABLE_HIDRAW`. That is the difference that costs a G923 owner their force feedback if it is guessed. If something did not happen, that file says which step declined and why. @@ -131,93 +150,97 @@ If something did not happen, that file says which step declined and why. | Option | What it does | When you want it | |---|---|---| | `logi-launch %command%` | Works out everything below for this game and this wheel, and applies it | **Every racing game.** It is the only line most people need | -| `PROTON_ENABLE_HIDRAW=0x046D/0xC276 %command%` | Lets the game talk to the wheel's raw HID interface, which is how Logitech's SDK delivers TrueForce | Set by `logi-launch`, scoped to your wheel. By hand: a **direct-drive wheel** (RS50, G PRO) in a game with its own TrueForce (ACC, Assetto Corsa EVO), with the TrueForce files installed. Use your own product id, not `0xC276`. One known cost: on one CachyOS machine every Proton build tried (Valve's hotfix branch, GE-Proton 11) paid a constant frame-time penalty in AC EVO with the wheel exposed this way, moving or not, while the same wheel on `proton-cachyos` here does not; the cost is in Proton's raw HID layer, and empty launch options give full force feedback without TrueForce (issue #74) | +| `PROTON_ENABLE_HIDRAW=0x046D/0xC276 %command%` | Lets the game talk to the wheel's raw HID interface. That is how Logitech's SDK delivers TrueForce | Set by `logi-launch`, scoped to your wheel. By hand: a **direct-drive wheel** (RS50, G PRO) in a game with its own TrueForce (ACC, Assetto Corsa EVO), with the TrueForce files installed. Use your own product id, not `0xC276`. One known cost: on one CachyOS machine, every Proton build tried (Valve's hotfix branch, GE-Proton 11) paid a constant frame-time penalty in AC EVO with the wheel exposed this way, moving or not. The same wheel on `proton-cachyos` there does not. The cost is in Proton's raw HID layer. Empty launch options give full force feedback without TrueForce (issue #74) | | *(no `PROTON_ENABLE_HIDRAW` at all)* | The wheel stays an ordinary Linux force-feedback device | By hand on a **G923**, always. This row is about that one variable, not about `logi-launch`, which every wheel wants | | `logi-ffb %command%` | Presents a virtual wheel that speaks the older DirectInput force-feedback protocol, and forwards it to your real wheel | Applied by `logi-launch`. By hand: games that only do DirectInput FFB (Le Mans Ultimate, rFactor 2, iRacing, RaceRoom), on **any** wheel including a G923 | -The bottom three rows describe what `logi-launch` does for you. You only type -them yourself if you would rather not use it. +The bottom three rows describe what `logi-launch` does for you. You only +type them yourself if you would rather not use it. -`gamemoderun` is not ours. It is from `gamemode` and composes fine with all -of the above. +`gamemoderun` is not ours. It comes from `gamemode`. It composes fine with +all of the above. ## Combining them -Order is: **environment variables first, then wrappers, then `%command%`.** -Each wrapper runs the next one along, so they chain left to right. +The order is: **environment variables first, then wrappers, then +`%command%`.** Each wrapper runs the next one along, so they chain left to +right. -`logi-launch` composes with things that are not ours. Assetto Corsa EVO, with -gamemode and the graphics settings that title wants: +`logi-launch` composes with things that are not ours. Here is Assetto Corsa +EVO with gamemode and the graphics settings that title wants: ``` PROTON_ENABLE_NVAPI=1 VKD3D_CONFIG=descriptor_heap gamemoderun logi-launch %command% ``` That line is the same on an RS50 and on a G923. Do not add -`PROTON_ENABLE_HIDRAW` to it: `logi-launch` sets that itself on the wheels -that want it, and setting it yourself is how it ends up on a G923, where it +`PROTON_ENABLE_HIDRAW` to it. `logi-launch` sets that itself on the wheels +that want it. Setting it yourself is how it ends up on a G923, where it costs that wheel its force feedback. ### With the TrueForce files it is an upgrade; without them it is a loss **With them**, this is the configuration to want. The game's own TrueForce -reaches the wheel: the haptics its developers authored, rather than the +reaches the wheel. Those are the haptics its developers authored, not the engine note `logi-tf-sim` synthesises from telemetry. That is a real -difference, and it is the reason this setting exists. +difference. It is the reason this setting exists. **Without them**, it is a pure loss. Turning it on makes Proton hand the game -the raw HID device instead of the one backed by the Linux input layer, and -**this wheel's raw descriptor carries no force-feedback protocol at all**. -Logitech's SDK is what fills that gap, and the SDK is what those files are. -So on a prefix without them you lose force feedback and gain nothing. - -`logi-launch` checks the prefix and declines rather than make that trade, -saying so in the log, and falls back to simulated TrueForce so the wheel is -not left with nothing. That is issue #60, where it read as "logi-launch gives -me no FFB". - -The corollary is worth stating plainly: **for Assetto Corsa Competizione and -Assetto Corsa EVO on a direct-drive wheel, Logitech's files are what carry -force feedback**, not only TrueForce. They are optional only in the sense -that you can leave the raw interface off and keep the ordinary path. - -One thing this does **not** change: force feedback itself is never simulated -by this project. `logi-tf-sim` synthesises TrueForce and nothing else, so the +the raw HID device instead of the one backed by the Linux input layer. +**This wheel's raw descriptor carries no force-feedback protocol at all.** +Logitech's SDK fills that gap, and the SDK is what those files are. So on a +prefix without them, you lose force feedback and gain nothing. + +`logi-launch` checks the prefix. It declines rather than make that trade, +says so in the log, and falls back to simulated TrueForce. So the wheel is +not left with nothing. That is issue #60, where it read as "logi-launch +gives me no FFB". + +The corollary is worth stating plainly. **For Assetto Corsa Competizione and +Assetto Corsa EVO on a direct-drive wheel, Logitech's files carry force +feedback**, not only TrueForce. They are optional only in one sense: you can +leave the raw interface off and keep the ordinary path. + +One thing this does **not** change: this project never simulates force +feedback itself. `logi-tf-sim` synthesises TrueForce and nothing else. The forces you feel through the evdev path are the game's own, exactly as its -developers wrote them. What the raw interface changes is which route those -forces travel, and whether the game's TrueForce can travel at all. No -measurement here says the SDK route feels better than the evdev one; the -gain that is established is native TrueForce over simulated. +developers wrote them. (evdev is the Linux input layer that games normally +use for a wheel.) The raw interface changes which route those forces travel. +It also decides whether the game's TrueForce can travel at all. No +measurement here says the SDK route feels better than the evdev one. The +established gain is native TrueForce over simulated. ### The engine buzz, and a stale variable to remove -Real TrueForce through the SDK carries the game's steering forces but not the -fine engine-note texture. On Windows that texture is G HUB's own addition, -synthesised from the game's RPM and merged into the same stream, not -something the game sends itself. Since 2026-08-13 the driver does the same -merge, and `logi-launch` wires all of it up for you: for Assetto Corsa EVO on -a direct-drive wheel, plain `logi-launch %command%` stages the proxy DLL, -starts `logi-rpm-bridge`, and turns on the merge, tearing both down again +Real TrueForce through the SDK carries the game's steering forces, but not +the fine engine-note texture. On Windows that texture is G HUB's own +addition. G HUB synthesises it from the game's RPM and merges it into the +same stream. The game does not send it itself. Since 2026-08-13 the driver +does the same merge, and `logi-launch` wires all of it up for you. For +Assetto Corsa EVO on a direct-drive wheel, plain `logi-launch %command%` +stages the proxy DLL, starts `logi-rpm-bridge`, and turns on the merge. (The +proxy DLL is a stand-in `dinput8` library placed in the game's directory. It +relays what the game's SDK does with the wheel.) It tears both down again when the game exits. The same telemetry lights the rev strip: the proxy relays the game's live rpm, first-shift-light rpm and redline, and -`logi-rpm-bridge` drives `wheel_rev_level` with them. Nothing else to add, -and nothing to type differently from any other title. +`logi-rpm-bridge` drives `wheel_rev_level` with them. There is nothing else +to add. You type nothing different from any other title. **IMPORTANT: remove `LOGI_ESCAPE_RELAY=0` if it is sitting in a game's launch options from an older manual recipe.** That variable turns the dinput8 proxy -into capture-only, so it stops relaying the RPM the texture merge needs, and -the wheel goes back to force with no buzz for no reason that shows up -anywhere. `logi-launch` never sets it, and the relay must stay on. +into capture-only. It then stops relaying the RPM the texture merge needs. +The wheel goes back to force with no buzz, and nothing shows the reason +anywhere. `logi-launch` never sets it. The relay must stay on. ### Why it names your wheel rather than saying `1` Proton matches this variable as a **substring** against each device's own `0xVID/0xPID` (`dlls/winebus.sys/main.c`). The bare value `1` short-circuits -that test and returns true for **every HID device on the machine**, so your +that test. It returns true for **every HID device on the machine**. So your keyboard, headset and any other controller are handed to the game as raw HID -alongside the wheel. Naming the wheel is what the pattern form is for, and -what `logi-launch` now does. Reported as issue #60, where `1` cost an RS50 -owner their force feedback in Assetto Corsa EVO. +alongside the wheel. Naming the wheel is what the pattern form is for. That +is what `logi-launch` now does. This was reported as issue #60, where `1` +cost an RS50 owner their force feedback in Assetto Corsa EVO. Le Mans Ultimate, on any wheel: @@ -238,46 +261,46 @@ PROTON_ENABLE_NVAPI=1 VKD3D_CONFIG=descriptor_heap gamemoderun %command% logi-ffb %command% # Le Mans Ultimate, either wheel ``` -The first two differ by one variable, and that variable is the difference -between TrueForce on one wheel and no force feedback at all on the other. -Doing this by hand means getting it right per game and per wheel, every time. -You also start `logi-tf-sim` yourself, and install the relay per game from the +The first two lines differ by one variable. That variable is the difference +between TrueForce on one wheel and no force feedback at all on the other. By +hand, you must get it right per game and per wheel, every time. You also +start `logi-tf-sim` yourself. You also install the relay per game from the app's Setup page. ## Why the relay has to run inside the prefix Some sims never send telemetry over the network. The Assetto Corsa family (including EVO), iRacing, RaceRoom, rFactor 2 and Le Mans Ultimate publish -into a named Windows shared-memory section instead. Assetto Corsa EVO has no -UDP output at all: its binary carries a `SharedMemoryPhysicsWriter` and -`CreateFileMappingA`, and every socket in it belongs to the multiplayer -stack. - -Nothing on the Linux side can read that section, and nothing on another -machine can either. Reading it needs a Windows process inside the same -Proton prefix. That is what `logi-tf-relay` is, and it is how a remote -SimHub, a buttkicker or a phone dashboard can be fed from a game running -here. - -**The catch is ordering, and it is worth understanding before you fight it.** -Proton takes the prefix exclusively when it launches: it runs `wineserver -w` +into a named Windows shared-memory section instead. (A shared-memory section +is a block of memory one Windows program publishes and another reads.) +Assetto Corsa EVO has no UDP output at all. Its binary carries a +`SharedMemoryPhysicsWriter` and `CreateFileMappingA`. Every socket in it +belongs to the multiplayer stack. + +Nothing on the Linux side can read that section. Nothing on another machine +can either. Reading it needs a Windows process inside the same Proton prefix. +That is what `logi-tf-relay` is. It is also how a remote SimHub, a buttkicker +or a phone dashboard can be fed from a game running here. + +**The catch is ordering. It is worth understanding before you fight it.** +Proton takes the prefix exclusively when it launches. It runs `wineserver -w` and waits for any existing wineserver to exit first. So a helper started -before the game stops the game from starting at all, and one started by hand -afterwards is a step you have to remember every session. +before the game stops the game from starting at all. A helper started by +hand afterwards is a step you must remember every session. -`logi-launch` runs the game immediately and starts the helper afterwards, +`logi-launch` runs the game immediately. It starts the helper afterwards, once the game's own wineserver exists. It also runs the helper with the **same wine build the game is using**, read from the prefix's `config_info`. -That matters: the distribution's own `wine` is a different build, and -pointing it at a Proton-made prefix triggers prefix initialisation, prompts -to install wine-mono, and can convert the prefix. `logi-launch` refuses to +That matters. The distribution's own `wine` is a different build. Pointing +it at a Proton-made prefix triggers prefix initialisation, prompts to +install wine-mono, and can convert the prefix. `logi-launch` refuses to attach at all rather than do that. ### You should not have to configure it -With nothing set, `logi-launch` runs **this project's own `logi-tf-relay`** -and works out which game it is from the appid Steam already provides. So -for simulated TrueForce the whole setup is: +With nothing set, `logi-launch` runs **this project's own `logi-tf-relay`**. +It works out which game it is from the appid Steam already provides. So for +simulated TrueForce the whole setup is: ``` logi-launch %command% @@ -285,12 +308,14 @@ logi-launch %command% It knows the seven titles that publish to shared memory (iRacing, RaceRoom, Assetto Corsa, Competizione, EVO, rFactor 2, Le Mans Ultimate). For any -other game it starts nothing and simply launches it, so leaving it in the +other game it starts nothing and simply launches it. So leaving it in the launch options of a game that does not need it costs nothing. -If the relay is not in that game's prefix yet it says so in the log and -launches the game anyway, rather than failing silently. Install it from the -app's Setup page, **Install relay**. +If the relay is not in that game's prefix yet, the log says so, and the game +launches anyway. It does not fail silently. To install the relay: + +1. Open the app's Setup page. +2. Choose **Install relay**. ### Running something else instead @@ -304,23 +329,23 @@ app's Setup page, **Install relay**. | `LOGI_LAUNCH_TF_SIM` | `1` | `0` leaves the `logi-tf-sim` daemon alone, for running it yourself | | `LOGI_LAUNCH_LOG` | `/tmp/logi-launch.log` | Where it writes what it did | | `LOGI_REV_MODE` | full bar | `shift` makes `logi-rpm-bridge` map the rev strip to the dash band: dark below the car's first shift light, level 1 exactly there, 10 at the limiter. The default lights LED 1 as soon as rpm > 0 and all 10 at the limiter | -| `LOGI_FFB_DEVICE` | the wheel `--wheel` resolved | Which evdev node `logi-ffb` drives (`eventN` or a full path). `logi-launch` sets it from the wheel it set the session up for; set it yourself only to override that | -| `LOGI_TF_CAPTURE` | worked out from the wheels attached | `1` makes the TrueForce SDK shim relay the game's own TrueForce to `logi-tf-sim`, `0` stops it. Only a G923 wants it: on a direct-drive wheel Logitech's library streams those samples itself, and a second writer on the wheel's one-packet-per-millisecond endpoint takes turns with it rather than sharing, which buzzes. `logi-launch` sets it from `--wheel` when you name one, and forces it to `0` whenever it grants raw HID, since the SDK's own stream reaches the wheel then | -| `LOGI_TF_REARM` | `0` | **Experimental.** `1` makes `logi-launch` re-arm the TrueForce session before the game starts (the stop/start pair plus the 68-packet init, twice, from `tools/tf-init.bin`), for recovering from a previous session that died without teardown. Off by default pending hardware validation; a power cycle of the base remains the proven recovery | -| `LOGI_RANGE_PUSH` | `1` | The escape proxy tells Logitech's SDK the wheel's real rotation range once, right after the game selects the force mode. On the G923 Xbox edition the SDK renders the endstops itself at the edges of the range it believes, and it never learns the real one on that wheel, so without this the rim hits a wall of full torque a few tens of degrees off centre and the game's force is lost under it (#91). `0` leaves the SDK's own belief alone | -| `LOGI_STEER_LOCK` | `1` | The escape proxy applies to the wheel the range Logitech's SDK announces. Whenever the SDK's operating range is set, it tells the driver through a DirectInput escape; on Windows that is how the wheel follows a game's steering lock, under Wine the escape is dropped. The proxy writes that range to the wheel's sysfs range instead (#91). `0` leaves the wheel's range to the driver alone | -| `LOGI_ESCAPE_LOG` | `1` | The escape proxy staged into a game writes what the title's TrueForce SDK did to `dinput8-escape.log` beside itself. `0` switches that off. On by default because it is the one record that exists when a report comes in; since 0.39.2 its cost is a buffered write, flushed at most twice a second. | - -`LOGI_LAUNCH_EXE` replaces the relay, so simulated TrueForce and the rev -lights lose their telemetry. That is the right choice only when you want +| `LOGI_FFB_DEVICE` | the wheel `--wheel` resolved | Which evdev node `logi-ffb` drives (`eventN` or a full path). `logi-launch` sets it from the wheel it set the session up for. Set it yourself only to override that | +| `LOGI_TF_CAPTURE` | worked out from the wheels attached | `1` makes the TrueForce SDK shim relay the game's own TrueForce to `logi-tf-sim`. `0` stops it. Only a G923 wants it. On a direct-drive wheel Logitech's library streams those samples itself. A second writer on the wheel's one-packet-per-millisecond endpoint takes turns with it rather than sharing, which buzzes. `logi-launch` sets it from `--wheel` when you name one. It forces it to `0` whenever it grants raw HID, since the SDK's own stream reaches the wheel then | +| `LOGI_TF_REARM` | `0` | **Experimental.** `1` makes `logi-launch` re-arm the TrueForce session before the game starts (the stop/start pair plus the 68-packet init, twice, from `tools/tf-init.bin`). Use it to recover from a previous session that died without teardown. Off by default pending hardware validation. A power cycle of the base remains the proven recovery | +| `LOGI_RANGE_PUSH` | `1` | The escape proxy tells Logitech's SDK the wheel's real rotation range once, right after the game selects the force mode. On the G923 Xbox edition the SDK renders the endstops itself, at the edges of the range it believes, and it never learns the real one on that wheel. Without this, the rim hits a wall of full torque a few tens of degrees off centre, and the game's force is lost under it (#91). `0` leaves the SDK's own belief alone | +| `LOGI_STEER_LOCK` | `1` | The escape proxy applies to the wheel the range Logitech's SDK announces. Whenever the SDK's operating range is set, it tells the driver through a DirectInput escape. On Windows that is how the wheel follows a game's steering lock. Under Wine the escape is dropped. The proxy writes that range to the wheel's sysfs range instead (#91). `0` leaves the wheel's range to the driver alone | +| `LOGI_ESCAPE_LOG` | `1` | The escape proxy staged into a game writes what the title's TrueForce SDK did to `dinput8-escape.log` beside itself. `0` switches that off. It is on by default because it is the one record that exists when a report comes in. Since 0.39.2 its cost is a buffered write, flushed at most twice a second. | + +`LOGI_LAUNCH_EXE` replaces the relay. Simulated TrueForce and the rev lights +then lose their telemetry. That is the right choice only when you want nothing driven on this machine. ### Running your own helpers inside the prefix `LOGI_LAUNCH_HELPERS` starts extra Windows programs inside the game's prefix, alongside whatever the plan already decided. Our relay is one such -program; there is nothing special about it, and anything else that has to -run beside the game can go the same way. +program. There is nothing special about it. Anything else that has to run +beside the game can go the same way. ``` LOGI_LAUNCH_HELPERS='c:\sim-teleport.exe source' logi-launch %command% @@ -337,66 +362,69 @@ LOGI_LAUNCH_HELPERS='c:\sim-teleport.exe source; c:\dash-bridge.exe --port 8080' The sims that matter here publish telemetry into a **named Windows shared-memory section**: the Assetto Corsa family including EVO, iRacing, RaceRoom, rFactor 2 and Le Mans Ultimate. That section exists inside the -Wine prefix and nowhere else. No Linux process can open it, and neither can -a program on another machine. Reading it takes a Windows process in the same -prefix, which is the whole reason this mechanism exists. +Wine prefix and nowhere else. No Linux process can open it. Neither can a +program on another machine. Reading it takes a Windows process in the same +prefix. That is the whole reason this mechanism exists. Games that broadcast telemetry over **UDP** instead (Automobilista 2, the F1 titles, the Codemasters rally games, BeamNG) need none of this. Point the -game's own telemetry setting at `127.0.0.1` and read it from Linux directly. +game's own telemetry setting at `127.0.0.1`. Then read it from Linux +directly. #### Getting a program in there -Copy the `.exe` into the prefix's `drive_c`, which is where `c:\name.exe` -resolves to: +Two steps: + +1. Copy the `.exe` into the prefix's `drive_c`. That is where `c:\name.exe` + resolves to. +2. Name it in `LOGI_LAUNCH_HELPERS` as `c:\yourhelper.exe`. + +The copy, for step 1: ``` cp yourhelper.exe ~/.steam/steam/steamapps/compatdata//pfx/drive_c/ ``` -Then name it in `LOGI_LAUNCH_HELPERS` as `c:\yourhelper.exe`. - #### What logi-launch handles for you -The hard part is not starting the program, it is starting it at the right -moment, and this is the reason to go through the wrapper rather than -launching it yourself: +The hard part is not starting the program. It is starting it at the right +moment. This is the reason to go through the wrapper rather than launch it +yourself: -- **Order.** Proton takes the prefix exclusively at launch: it runs +- **Order.** Proton takes the prefix exclusively at launch. It runs `wineserver -w` and waits for any existing wineserver to exit first. Start - a helper first and **the game does not start at all**, it sits waiting for - your helper to quit. `logi-launch` execs the game immediately and starts + a helper first and **the game does not start at all**. It sits waiting for + your helper to quit. `logi-launch` execs the game immediately. It starts helpers afterwards, once the game's own wineserver exists. - **The right wine.** Helpers run with the same Proton build the game is using, read from the prefix's `config_info`. The distribution's `wine` is - a different build against a Proton-made prefix: it prompts to install + a different build. Against a Proton-made prefix it prompts to install wine-mono and can convert the prefix. -- **Settling.** It waits `LOGI_LAUNCH_SETTLE` seconds (15 by default) so the - game has created its sections before the first probe. +- **Settling.** It waits `LOGI_LAUNCH_SETTLE` seconds (15 by default). That + gives the game time to create its sections before the first probe. #### What suits this, and what does not Good candidates are programs that **attach to a running game**: telemetry readers, bridges to a dashboard or a second PC, bass-shaker feeders, logging -tools. Several reading the same telemetry is fine, and not a conflict: a +tools. Several reading the same telemetry is fine. It is not a conflict. A Windows shared-memory section takes any number of readers. It does not suit anything that must run **before** the game, such as a -launcher, a patcher, or a mod manager. Those need the prefix to themselves, -which is the exact situation this design avoids. +launcher, a patcher, or a mod manager. Those need the prefix to themselves. +That is the exact situation this design avoids. #### Limits worth knowing -- The program name is whatever precedes the first space, so it cannot itself - contain one. In `drive_c` the path is `c:\name.exe` and the question does +- The program name is whatever precedes the first space, so it cannot + contain one. In `drive_c` the path is `c:\name.exe`, and the question does not arise. -- Each helper gets its own wine process, and they are all started together - rather than one after another. A helper that never exits does not hold up - the next one. +- Each helper gets its own wine process. They all start together, not one + after another. A helper that never exits does not hold up the next one. - Helpers stop when the game does, because Proton tears the prefix down on - exit. That is observed rather than promised: a helper of your own that - survives it would keep a wineserver alive and delay the next launch. If a - game refuses to start, check for a stray `wineserver` first. + exit. That is observed, not promised. A helper of your own that survives + it would keep a wineserver alive and delay the next launch. If a game + refuses to start, check for a stray `wineserver` first. - Output goes to `/tmp/logi-launch.log`, with `WINEDEBUG=-all` unless you set `WINEDEBUG` yourself. @@ -406,32 +434,33 @@ See [SHARED_MEMORY_RELAY.md](SHARED_MEMORY_RELAY.md) for the relay itself. `sim-teleport` ([upstream](https://github.com/t-hovestadt/sim-teleport)) is a third-party tool, not part of this project. Its **source** half runs on the -gaming PC and its **target** half on the SimHub PC, where it recreates the -game's shared-memory sections locally so SimHub reads the real layout and -identifies the game correctly, rather than being fed a re-encoded -approximation. +gaming PC. Its **target** half runs on the SimHub PC. There it recreates the +game's shared-memory sections locally. So SimHub reads the real layout and +identifies the game correctly, instead of a re-encoded approximation. + +Its source half runs correctly under Proton. This was confirmed on +2026-08-09 with Assetto Corsa EVO, which it detected from the menu via +`Local\acevo_pmf_physics`. To use it: -Its source half runs correctly under Proton: confirmed on 2026-08-09 with -Assetto Corsa EVO, which it detected from the menu via -`Local\acevo_pmf_physics`. Put `sim-teleport.exe` in the prefix's `drive_c`, -then add it to the helpers: +1. Put `sim-teleport.exe` in the prefix's `drive_c`. +2. Add it to the helpers: ``` LOGI_LAUNCH_HELPERS='c:\sim-teleport.exe source' logi-launch %command% ``` Use `LOGI_LAUNCH_HELPERS` and not `LOGI_LAUNCH_EXE` here. The second one -replaces our relay, which leaves SimHub fed on the other machine and the rev +replaces our relay. That leaves SimHub fed on the other machine, and the rev lights and simulated TrueForce dark on this one. Feeding SimHub and driving -the wheel are not alternatives, and both bridges can read the same telemetry -at once. +the wheel are not alternatives. Both bridges can read the same telemetry at +once. Its own documentation warns that the **target** half must never run on the -gaming PC, because it creates shared-memory sections using the game's own -names. Only the source half belongs here. +gaming PC. It creates shared-memory sections using the game's own names. +Only the source half belongs here. None of this touches force feedback or TrueForce. A telemetry helper only -reads; the native FFB and SDK TrueForce paths are unaffected. +reads. The native FFB and SDK TrueForce paths are unaffected. ## Seeing every game's recipe @@ -439,19 +468,20 @@ reads; the native FFB and SDK TrueForce paths are unaffected. logi-wheel --launch-plan --list ``` -prints all 30 titles the registry knows, with the name to pass to `--game`, -the Steam appid, and what each one resolves to **on the wheel you have -attached**. The same command with an appid instead of `--list` shows one -game's answer, which is what `logi-launch` itself asks for. +This prints all 30 titles the registry knows. For each, it shows the name to +pass to `--game`, the Steam appid, and what the title resolves to **on the +wheel you have attached**. The same command with an appid instead of +`--list` shows one game's answer. That is what `logi-launch` itself asks +for. Titles that do not run on Linux at all (the Forza games, Gran Turismo 7) say -so and get no recipe, rather than advice nobody can test. +so and get no recipe. Advice nobody can test is not offered. ## Naming a game it does not recognise -An appid identifies a Steam title, but not every install has one: a game -added as a non-Steam shortcut gets an id Steam makes up locally, a copy -bought elsewhere has none, and a delisted game may not resolve. Name it +An appid identifies a Steam title, but not every install has one. A game +added as a non-Steam shortcut gets an id Steam makes up locally. A copy +bought elsewhere has none. A delisted game may not resolve. Name the game instead: ``` @@ -459,15 +489,15 @@ logi-launch --game dirt-4 %command% ``` Names come from `--launch-plan --list`. A partial name works if it is -unambiguous; `--game dirt` refuses and lists the candidates rather than -choosing between DiRT 4 and DiRT Rally 2.0. +unambiguous. `--game dirt` refuses and lists the candidates, rather than +choose between DiRT 4 and DiRT Rally 2.0. ## Two wheels at once `logi-launch` works out what to set from the wheel you have attached. With -two of them, and of different kinds, it stops guessing: the game picks which -wheel it uses in its own settings and never tells us, so there is nothing to -detect. Getting it wrong is not a small mistake either, because +two wheels of different kinds, it stops guessing. The game picks which wheel +it uses in its own settings and never tells us. So there is nothing to +detect. Getting it wrong is not a small mistake either. `PROTON_ENABLE_HIDRAW` on a G923 costs that wheel its force feedback. So on a mixed rig it applies what is safe, says what it withheld, and waits @@ -479,18 +509,18 @@ logi-launch --wheel g923 %command% # the G923 logi-launch --wheel xbox %command% # the G923 Xbox edition, on the SDK route ``` -That choice also aims `logi-tf-sim` at the same wheel, so the game and the -haptics cannot end up on different ones. If the daemon was already running -from an earlier session it keeps whatever wheel it was started with, and -the log says so rather than letting the flag look honoured. +That choice also aims `logi-tf-sim` at the same wheel. So the game and the +haptics cannot end up on different wheels. If the daemon was already running +from an earlier session, it keeps whatever wheel it was started with. The +log says so, rather than let the flag look honoured. **Everything else this script starts is aimed there too.** One wheel is -resolved at the top of the run and handed to the rest: `logi-rpm-bridge` +resolved at the top of the run and handed to the rest. `logi-rpm-bridge` gets that wheel's `wheel_texture_rpm` (and so its rev strip, the attribute -next door), `logi-ffb` gets that wheel's force-feedback event node through -`LOGI_FFB_DEVICE`, the texture merge is switched on at that wheel's -`wheel_tf_merge`, and the TrueForce teardown sent after the game exits goes -to that wheel's raw interface. The log names the directory it settled on: +next door). `logi-ffb` gets that wheel's force-feedback event node through +`LOGI_FFB_DEVICE`. The texture merge is switched on at that wheel's +`wheel_tf_merge`. The TrueForce teardown sent after the game exits goes to +that wheel's raw interface. The log names the directory it settled on: ``` [logi-launch] acting on the wheel at /sys/bus/hid/devices/0003:046D:C276.0003 @@ -498,8 +528,8 @@ to that wheel's raw interface. The log names the directory it settled on: ``` Before this, the merge was switched on for **every** direct-drive wheel -attached and switched off again on every one at exit, and the teardown took -whichever raw node sorted first: quitting one game could reach into a +attached, and switched off again on every one at exit. The teardown took +whichever raw node sorted first. Quitting one game could reach into a session running on the other wheel. The exit path now undoes exactly the attribute this run wrote, and nothing else. @@ -518,25 +548,25 @@ override what it decides, write a line in 1234567 ffb=proxy tfsim=0 ``` -The appid is the number in the game's Steam store URL, and the same number -as its folder under `steamapps/compatdata`. Your line wins for the keys it -states; a key it leaves out keeps the built-in answer's value, so a line -written for an older release does not quietly turn off pieces added since -(an old `hidraw=1` line, for example, keeps the kernel texture merge the -built-in plan asks for). To force something off, state it: `texture=none`, +The appid is the number in the game's Steam store URL. It is also the name +of its folder under `steamapps/compatdata`. Your line wins for the keys it +states. A key it leaves out keeps the built-in answer's value. So a line +written for an older release does not quietly turn off pieces added since. +(An old `hidraw=1` line, for example, keeps the kernel texture merge the +built-in plan asks for.) To force something off, state it: `texture=none`, `tfsim=0`. | setting | values | meaning | |---|---|---| -| `hidraw` | `0`, or a wheel id like `0x046D/0xC276` | what to set `PROTON_ENABLE_HIDRAW` to. `0` turns the raw interface off for this game, which is how you keep force feedback when the raw path spoils a game's input. A bare `1` still works and means every HID device, which is rarely what you want | +| `hidraw` | `0`, or a wheel id like `0x046D/0xC276` | what to set `PROTON_ENABLE_HIDRAW` to. `0` turns the raw interface off for this game. That is how you keep force feedback when the raw path spoils a game's input. A bare `1` still works and means every HID device, which is rarely what you want | | `ffb` | `proxy` | launch through `logi-ffb`, for games that drive force feedback the DirectInput way | | `relay` | `acc`, `ac-evo`, `assetto`, `iracing`, `raceroom`, `rf2`, `lmu`, `none` | which decoder the in-prefix telemetry relay should use | -| `tfsim` | `1`, `0` | run `logi-tf-sim`. Set `0` for a game whose own TrueForce already reaches your wheel. Asking for it alongside `texture=merge` is a combination only a hand-written line can produce, and it works: the two read the same telemetry port, so whichever holds it forwards to the other and both are fed (see "One socket gets the datagrams, every reader gets the telemetry" in [SHARED_MEMORY_RELAY.md](SHARED_MEMORY_RELAY.md)) | -| `texture` | `merge`, `none` | mix the driver's engine-note texture into the game's own TrueForce on the wheel. `merge` makes `logi-launch` stage the dinput8 escape proxy into the game's directory, start `logi-rpm-bridge` and switch `wheel_tf_merge` on, undoing all of it when the game exits. The same chain also lights the rev strip from the game's own telemetry: the proxy relays live rpm, first-shift-light rpm and redline, and `logi-rpm-bridge` drives `wheel_rev_level` with them (full bar by default, `LOGI_REV_MODE=shift` for the dash band). Only does anything for a direct-drive wheel in an SDK title with the TrueForce files installed | -| `revleds` | `bar`, `shift` | how `logi-rpm-bridge` maps the rev strip while `texture=merge` drives it: `bar` (the default) lights LED 1 as soon as the engine turns and all 10 at the limiter, `shift` is the dash band (dark below the car's first shift light, level 1 exactly there). The apps persist this choice in `~/.config/logi-wheel/launch.conf` and it shows on a merge title's Setup card; a games.conf line overrides it per game like any other key | +| `tfsim` | `1`, `0` | run `logi-tf-sim`. Set `0` for a game whose own TrueForce already reaches your wheel. Asking for it alongside `texture=merge` is a combination only a hand-written line can produce, and it works: the two read the same telemetry port, so whichever holds it forwards to the other, and both are fed (see "One socket gets the datagrams, every reader gets the telemetry" in [SHARED_MEMORY_RELAY.md](SHARED_MEMORY_RELAY.md)) | +| `texture` | `merge`, `none` | mix the driver's engine-note texture into the game's own TrueForce on the wheel. `merge` makes `logi-launch` stage the dinput8 escape proxy into the game's directory, start `logi-rpm-bridge` and switch `wheel_tf_merge` on. It undoes all of it when the game exits. The same chain also lights the rev strip from the game's own telemetry: the proxy relays live rpm, first-shift-light rpm and redline, and `logi-rpm-bridge` drives `wheel_rev_level` with them (full bar by default, `LOGI_REV_MODE=shift` for the dash band). It only does anything for a direct-drive wheel in an SDK title with the TrueForce files installed | +| `revleds` | `bar`, `shift` | how `logi-rpm-bridge` maps the rev strip while `texture=merge` drives it. `bar` (the default) lights LED 1 as soon as the engine turns and all 10 at the limiter. `shift` is the dash band (dark below the car's first shift light, level 1 exactly there). The apps persist this choice in `~/.config/logi-wheel/launch.conf`, and it shows on a merge title's Setup card. A games.conf line overrides it per game like any other key | A line that works for you is also exactly the report needed to add the game -properly, so please open an issue with it. +properly. Please open an issue with it. ## What it needs installed diff --git a/docs/NATIVE_TF_TEXTURE_MERGE_DESIGN.md b/docs/NATIVE_TF_TEXTURE_MERGE_DESIGN.md index adc5adc..89ed40e 100644 --- a/docs/NATIVE_TF_TEXTURE_MERGE_DESIGN.md +++ b/docs/NATIVE_TF_TEXTURE_MERGE_DESIGN.md @@ -5,83 +5,85 @@ ## Status update: implemented -Everything below shipped as designed, with two deltas found during review and -one framing question that came up more than once and was settled explicitly. +Everything below shipped as designed. Review found two deltas. One framing +question came up more than once, and it was settled explicitly. **Delta 1: the merge state lives in a devm shim, not on `ff` directly.** The design below describes `ff->tm`/`ff->tm_lock`. Review hardening moved -that state onto its own `struct hidpp_dd_texmerge_shim`, devm-allocated -against interface 2's device and reached through `ff->tm_shim` (which -may be `NULL` across teardown), with the shim's own spinlock serializing -every read and write against the classifier - not just against other sysfs -writers, since the classifier reads the whole struct on every packet on the -ll_driver hot path. +that state onto its own `struct hidpp_dd_texmerge_shim`. The shim is +devm-allocated against interface 2's device and reached through +`ff->tm_shim` (which may be `NULL` across teardown). The shim's own spinlock +serializes every read and write against the classifier, not just against +other sysfs writers. This matters because the classifier reads the whole +struct on every packet on the ll_driver hot path. **Delta 2: the oscillator gained a Nyquist harmonic guard.** In the harmonic loop, any harmonic whose frequency would reach 0.45 of the sample -rate is skipped rather than accumulated, so high RPM cannot fold a harmonic +rate is skipped rather than accumulated. So high RPM cannot fold a harmonic back down into the audible band as aliasing. The phase accumulator still advances underneath a skipped harmonic, so it re-enters cleanly in range without a phase jump. **Framing: the synthesis-fitted-to-capture approach was raised and approved -explicitly, not assumed.** The game supplies no texture at all - every SDK +explicitly, not assumed.** The game supplies no texture at all: every SDK packet from AC EVO carries `byte10=0`. On Windows the buzz is not something -sent over the wire and decoded; it is G HUB inventing it from the game's RPM -on the host and merging it into the same stream. There was accordingly no -protocol to reverse-engineer for the texture itself, only a pattern to fit -(`docs/TF_TEXTURE_RECIPE.md`, from the Windows capture). That this project -should do the same synthesis, in the kernel, rather than keep hunting for a -wire format that does not exist, was confirmed before implementation started -rather than discovered as a fallback partway through. +sent over the wire and decoded. G HUB invents it from the game's RPM on the +host and merges it into the same stream. So there was no protocol to +reverse-engineer for the texture itself, only a pattern to fit +(`docs/TF_TEXTURE_RECIPE.md`, from the Windows capture). This project does +the same synthesis, in the kernel, rather than keep hunting for a wire format +that does not exist. That choice was confirmed before implementation started. +It was not discovered as a fallback partway through. **Delta 3: validated against the live SDK stream, two overnight fixes (2026-08-14).** The merge was re-validated against the LIVE Logitech SDK -stream rather than a replay - 11,217 of 11,219 real stream packets spliced, +stream rather than a replay: 11,217 of 11,219 real stream packets spliced, sample rms 411.2 against the 411 capture-fit target, spectrum peak exactly at the fed firing frequency, SDK `cur` bytes byte-identical throughout. Two -fixes came out of the same pass: the type-`0x0e` range-push decode was +fixes came out of the same pass. The type-`0x0e` range-push decode was corrected to the true wire layout (bytes 6-9, not 8-11) after capture -analysis, and teardown was hardened with `device_lock` validation after a +analysis. Teardown was hardened with `device_lock` validation after a pre-existing close-path oops (`hid_hw_close` on an unbound `hid_device`) was found during rmmod testing. **Delta 4: the splicer stamps `pkt[11] = 0x0d` (2026-08-14).** The design below said to leave `pkt[11]` untouched. That was the one-byte gate between -"wire-perfect stream" and "texture actually felt": bytes 10 and 11 are a +"wire-perfect stream" and "texture actually felt". Bytes 10 and 11 are a demux pair (`byte10 != 0` always pairs with `byte11 = 0x0d` in Windows -captures; no-sample packets carry `0x00 0x00`), and the wheel silently +captures; no-sample packets carry `0x00 0x00`). The wheel silently discards the whole sample window of a `byte10 != 0` + `byte11 = 0x00` -packet while still honouring its cur bytes. The splicer now stamps `0x0d` -whenever it adds samples (commit `9b15131`); the merge is felt working on -hardware. See `docs/TRUEFORCE_PROTOCOL.md`, stream layout invariants. +packet while it still honours the packet's cur bytes. The splicer now stamps +`0x0d` whenever it adds samples (commit `9b15131`). The merge is felt working +on hardware. See `docs/TRUEFORCE_PROTOCOL.md`, stream layout invariants. ## Goal Add fine engine-texture haptics (the "buzz") to native TrueForce games under -Proton by having the kernel driver splice synthesized texture samples into the -Logitech SDK's own ep3 stream, leaving the SDK's base force bit-identical. This -mirrors how Windows G HUB merges texture into the same stream. +Proton. TrueForce is Logitech's high-rate haptic channel. The kernel driver +splices synthesized texture samples into the Logitech SDK's own ep3 stream +(USB endpoint 3, the TrueForce output channel). The SDK's base force stays +bit-identical. This mirrors how Windows G HUB merges texture into the same +stream. ## Background: what is already proven -Native base force feedback for the SDK path works and was hardware-verified on +Native base force feedback for the SDK path works. It was hardware-verified on 2026-08-13 (see memory `native-ffb-reproduced-2026-08-13`): -- The Logitech SDK (`trueforce_sdk_x64.dll`), running in the game under Wine, +- The Logitech SDK (`trueforce_sdk_x64.dll`) runs in the game under Wine. It streams the base force on USB interface 2, endpoint 0x03, as 64-byte - type-0x01 packets. The base force lives in `cur` (bytes 6-9). It writes these - by writing to `/dev/hidraw7` (the interface-2 hidraw node); the kernel routes - them to the USB interrupt-OUT endpoint. + type-0x01 packets. The base force lives in `cur` (bytes 6-9). The SDK + writes these to `/dev/hidraw7` (the interface-2 hidraw node). The kernel + routes them to the USB interrupt-OUT endpoint. - The game (AC EVO) provides base force but **no** texture: every SDK packet - has `byte10 = 0` (zero audio samples). The rev test confirms it - directional - force on curbs/walls, no buzz when revving. -- On Windows the buzz is synthesized by G HUB from the game's engine RPM and - injected into this same stream as a **separate** source. The game itself + has `byte10 = 0` (zero audio samples). The rev test confirms it. There is + directional force on curbs and walls, and no buzz when revving. +- On Windows, G HUB synthesizes the buzz from the game's engine RPM and + injects it into this same stream as a **separate** source. The game itself never calls the SDK's `SetTorqueTF*` functions on either OS. -- Injecting texture through the game's own SDK session (`SetTorqueTFfloat`) does - **not** work: the game never opens the SDK's TF channel, so the SDK drops the - samples (verified: `byte10` stays 0 on the wire). +- Injecting texture through the game's own SDK session (`SetTorqueTFfloat`) + does **not** work. The game never opens the SDK's TF channel, so the SDK + drops the samples (verified: `byte10` stays 0 on the wire). Conclusion: the correct merge point is the ep3 stream itself, in the kernel, exactly where G HUB merges on Windows. @@ -94,7 +96,7 @@ All the mechanics already exist in `mainline/hid-logitech-hidpp.c`: `hid_ll_driver` on interface 0 to intercept userspace output writes (`hidpp_dd_pid_ll_output_report` / `hidpp_dd_pid_ll_raw_request`, installed by `hidpp_dd_pid_install`, gated `if (ifnum != 0) return 0;`). `.raw_event` only - sees input; the ll_driver override is the correct hook for output. We + sees input. The ll_driver override is the correct hook for output. We replicate this pattern on interface 2's `ff->ff_hdev`. - **The packet builder exists.** `hidpp_dd_tf_queue_stream` already writes the exact type-0x01 layout: `pkt[0]=0x01`, `pkt[4]=0x01` (stream cmd), @@ -102,55 +104,59 @@ All the mechanics already exist in `mainline/hid-logitech-hidpp.c`: `pkt[11]=0x0d`, then 13 window slots of u16 (bytes 12+, each duplicated). We reuse this layout knowledge for the splice. - **Interface-2 handle is held.** `ff->ff_hdev` is cached from - `usb_get_intfdata(iface2)` and kept open; existing `READ_ONCE`/`WRITE_ONCE` + `usb_get_intfdata(iface2)` and kept open. The existing `READ_ONCE`/`WRITE_ONCE` guards handle the remove-race. - **RPM out of the game is solved.** The dinput8 proxy relays the game's Escape telemetry as a UDP datagram (`LTFR`) to `127.0.0.1:20780` at ~62 Hz into the userspace daemon. Since 2026-08-14 the datagram is **32 bytes**: the 28-byte version-2 layout (`rpm`+`max_rpm` among its fields) plus an - appended f32 LE first-shift-light rpm at offset 28, append-only so old - consumers keep reading the first 28 bytes (see + appended f32 LE first-shift-light rpm at offset 28. It is append-only, so + old consumers keep reading the first 28 bytes (see `docs/SHARED_MEMORY_RELAY.md`). ## Scope -**In scope:** the native-merge path only - splice RPM-synthesized texture into +**In scope:** the native-merge path only. Splice RPM-synthesized texture into the SDK's existing ep3 stream for native-TF games. **Out of scope (untouched):** the existing `wheel_texture_route` (`kf`/`tf`) -simulated-TF path, which serves a *different* class of games (non-SDK / evdev -force-feedback titles, where the driver owns the stream and texture comes from -uploaded evdev effects). Native-merge is a separate mechanism with a different -stream owner (the SDK) and a different texture source (the RPM oscillator). The -two are mutually exclusive per game and never both active. Native-merge is NOT -a third value of `texture_route`. +simulated-TF path. That path serves a *different* class of games (non-SDK / +evdev force-feedback titles, where the driver owns the stream and texture +comes from uploaded evdev effects). Native-merge is a separate mechanism. It +has a different stream owner (the SDK) and a different texture source (the +RPM oscillator). The two are mutually exclusive per game and never both +active. Native-merge is NOT a third value of `texture_route`. ## Architecture Four units, each independently testable: -1. **Interceptor** - an `hid_ll_driver` override on `ff->ff_hdev` that inspects - every outgoing packet and, when the merge is active, hands stream packets to - the splicer before forwarding to the real `output_report`. -2. **Splicer** - a pure function: given an outgoing 64-byte packet and a block - of texture samples, preserve `cur`/`seq`, set `byte10` and the window slots, - return the modified packet. -3. **Oscillator** - a pure, fixed-point engine-note generator: given RPM and the - tuning parameters, produce the next block of offset-binary u16 samples, +1. **Interceptor**: an `hid_ll_driver` override on `ff->ff_hdev`. It inspects + every outgoing packet. When the merge is active, it hands stream packets to + the splicer before it forwards them to the real `output_report`. +2. **Splicer**: a pure function. Given an outgoing 64-byte packet and a block + of texture samples, it preserves `cur`/`seq`, sets `byte10` and the window + slots, and returns the modified packet. +3. **Oscillator**: a pure, fixed-point engine-note generator. Given RPM and the + tuning parameters, it produces the next block of offset-binary u16 samples, phase-continuous across calls. -4. **RPM feed** - a sysfs input the userspace daemon writes, plus a freshness +4. **RPM feed**: a sysfs input the userspace daemon writes, plus a freshness timestamp. ### Unit 1: Interceptor -Install the ll_driver override on `ff->ff_hdev` **once**, at the same point the -driver sets up interface 2 (where `ff->ff_hdev` becomes valid and is opened), -mirroring `hidpp_dd_pid_install` but for `ifnum == 2`. Save the real -`ll_driver`, swap in a copy whose `output_report` (and `raw_request`, for the -SET_REPORT fallback path the SDK may use) point at our wrapper. Restore the real -`ll_driver` on teardown, reusing the interface-0 pattern's ordering and guards. +Install the ll_driver override on `ff->ff_hdev` **once**. Do it at the same +point where the driver sets up interface 2 (where `ff->ff_hdev` becomes valid +and is opened). This mirrors `hidpp_dd_pid_install` but for `ifnum == 2`. -The wrapper is a **pure pass-through by default**. It splices only when all of: +1. Save the real `ll_driver`. +2. Swap in a copy whose `output_report` (and `raw_request`, for the + SET_REPORT fallback path the SDK may use) point at our wrapper. +3. Restore the real `ll_driver` on teardown. Reuse the interface-0 pattern's + ordering and guards. + +The wrapper is a **pure pass-through by default**. It splices only when all of +these hold: - `wheel_tf_merge` (sysfs, default 0) is 1, - the packet is report-id 0x01 and `pkt[4] == 0x01` (stream) and @@ -158,56 +164,57 @@ The wrapper is a **pure pass-through by default**. It splices only when all of: - RPM is fresh (written within a staleness window, ~200 ms) and above an idle threshold. -Otherwise it forwards the packet unchanged. With the feature off or no RPM -being fed, ep3 is byte-identical to today: zero regression risk, and the base -FFB path is untouched. +Otherwise it forwards the packet unchanged. With the feature off, or with no +RPM fed, ep3 is byte-identical to today. There is zero regression risk, and +the base FFB path is untouched. ### Unit 2: Splicer `splice(pkt[64], samples[], count)`: - Assert/require `pkt[0]==0x01 && pkt[4]==0x01`. - Leave bytes 0-9 (`cur` + `seq` + header) untouched. -- Set `pkt[10]` = new-sample count, stamp `pkt[11] = 0x0d` (see Delta 4: the - wheel discards the window of a sample-carrying packet without it), and - write the window slots (bytes 12+) using +- Set `pkt[10]` = new-sample count. Stamp `pkt[11] = 0x0d` (see Delta 4: the + wheel discards the window of a sample-carrying packet without it). Write + the window slots (bytes 12+) using the same duplicated-u16 layout as `hidpp_dd_tf_queue_stream`. -- Sample count and window semantics **match the existing builder** so the +- Sample count and window semantics **match the existing builder**, so the wheel's stream engine sees a well-formed stream. -Pure and unit-testable: assert `cur` bytes are identical before/after; assert a -known sample block lands in the expected slots. +The splicer is pure and unit-testable. Assert that the `cur` bytes are +identical before and after. Assert that a known sample block lands in the +expected slots. ### Unit 3: Oscillator Fixed-point, no kernel floating point (sine lookup table + integer phase accumulators). Per call, produce the next `count` samples: -- **fundamental** `f0 = RPM/60 * (cylinders/2)` (4-stroke firing frequency); - `cylinders` is a sysfs param (default 4 since commit `90a7489`; the design - originally said 8, but higher counts push the firing frequency above what - a direct-drive rim can express - excursion falls as 1/f^2 - so 4 feels - right and the knob is a feel setting). +- **fundamental** `f0 = RPM/60 * (cylinders/2)` (4-stroke firing frequency). + `cylinders` is a sysfs param (default 4 since commit `90a7489`). The design + originally said 8. Higher counts push the firing frequency above what a + direct-drive rim can express (excursion falls as 1/f^2), so 4 feels right + and the knob is a feel setting. - **harmonic stack** h1..h5 with gains interpolated by RPM and an amplitude curve, seeded from `docs/TF_TEXTURE_RECIPE.md` (which fits the Windows - capture). Values there are a starting point; the sysfs knobs make them + capture). Values there are a starting point. The sysfs knobs make them tunable live. -- **phase-continuous** accumulators carried across calls so the waveform is +- **phase-continuous** accumulators carried across calls, so the waveform is seamless packet-to-packet. - output: signed sample -> offset-binary u16 (same conversion class as `hidpp_dd_force_to_offset_binary`), clamped. Tuning knobs, all sysfs, live, no rebuild: `wheel_texture_intensity` (overall -amplitude), `wheel_texture_cylinders`, and the harmonic-gain profile. These are -what make matching the Windows feel a fast feel-adjust-feel loop. +amplitude), `wheel_texture_cylinders`, and the harmonic-gain profile. These +make matching the Windows feel a fast feel-adjust-feel loop. ### Unit 4: RPM feed - New sysfs `wheel_texture_rpm`: write `rpm` (and `max_rpm` for limiter feel). - The store records the value and a timestamp; a stale value (older than the - staleness window) disables splicing so a dead feed cannot leave a droning + The store records the value and a timestamp. A stale value (older than the + staleness window) disables splicing, so a dead feed cannot leave a droning wheel. -- The userspace daemon that already receives the proxy's UDP relay is extended - to write this sysfs at ~62 Hz. No new transport; reuses the existing chain +- The userspace daemon already receives the proxy's UDP relay. It is extended + to write this sysfs at ~62 Hz. No new transport. It reuses the existing chain (proxy Escape hook -> UDP 127.0.0.1:20780 -> daemon -> sysfs). ## Data flow @@ -226,16 +233,16 @@ game engine RPM ## Error handling and safety -- **Default off.** `wheel_tf_merge=0`; the hook is inert pass-through. -- **Stale-RPM guard.** No fresh RPM -> no splice, so a crashed daemon or closed +- **Default off.** `wheel_tf_merge=0`. The hook is inert pass-through. +- **Stale-RPM guard.** No fresh RPM -> no splice. A crashed daemon or closed game leaves the wheel smooth, never droning. - **Never clobber.** Packets with `byte10 != 0` (a future SDK/game that streams its own texture) pass through untouched. -- **cur is sacred.** The splicer never writes bytes 6-9; the base force stays - exactly what the SDK computed. This is the core invariant and a test asserts +- **cur is sacred.** The splicer never writes bytes 6-9. The base force stays + exactly what the SDK computed. This is the core invariant, and a test asserts it. -- **Teardown.** ll_driver restore on interface-2 remove reuses the interface-0 - pattern's ordering and the existing `ff_hdev` TOCTOU guards. +- **Teardown.** The ll_driver restore on interface-2 remove reuses the + interface-0 pattern's ordering and the existing `ff_hdev` TOCTOU guards. - **Idle threshold.** Below an RPM floor, no texture (a stationary idling engine should be near-silent, matching Windows). @@ -249,10 +256,13 @@ game engine RPM silence below idle; clamping at high intensity. - RPM sysfs parse + staleness logic. - classifier: only report-0x01 type-0x01 `byte10==0` packets are eligible. -- **Hardware validation (rev test):** with merge on and RPM fed, capture ep3; - assert `byte10 > 0` appears and scales with RPM, assert `cur` bytes match a - passthrough baseline, and confirm the user feels engine buzz that tracks revs. - With merge off, assert ep3 is byte-identical to baseline. +- **Hardware validation (rev test):** + 1. Turn the merge on and feed RPM. + 2. Capture ep3. + 3. Assert `byte10 > 0` appears and scales with RPM. + 4. Assert `cur` bytes match a passthrough baseline. + 5. Confirm the user feels engine buzz that tracks revs. + 6. Turn the merge off and assert ep3 is byte-identical to baseline. ## Rollout diff --git a/docs/PROTOCOL_SPECIFICATION.md b/docs/PROTOCOL_SPECIFICATION.md index f2a0ede..36a90d1 100644 --- a/docs/PROTOCOL_SPECIFICATION.md +++ b/docs/PROTOCOL_SPECIFICATION.md @@ -5,7 +5,7 @@ **Author**: Verified from USB capture analysis **Status**: Protocol reference for Linux driver development -This document was originally RS50-only. Most of what it describes now applies to the Logitech G Pro Racing Wheel (`046d:c272` Xbox/PC, `046d:c268` PS/PC) as well. G Pro-only or RS50-only differences are called out inline. +This document started as an RS50-only reference. Most of it now also applies to the Logitech G Pro Racing Wheel (`046d:c272` Xbox/PC, `046d:c268` PS/PC). Where the G Pro or the RS50 differs, the text says so at that point. --- @@ -30,13 +30,13 @@ This document was originally RS50-only. Most of what it describes now applies to | Product ID | `0xC272` (Xbox/PC), `0xC268` (PS/PC) | | Device Name | Logitech G Pro Racing Wheel | -G Pro exposes additional HID++ sub-devices (indices 0x01, 0x02, 0x05 over the shared interface 1), whereas the RS50 is a single-device base. Centre calibration (section 5, page 0x812C) lives on sub-device 0x05 and is only exercised by the driver on the G Pro. +The G Pro exposes additional HID++ sub-devices. HID++ is Logitech's configuration protocol, carried over USB. A sub-device is a unit inside the wheel that HID++ addresses with its own device index. The G Pro sub-devices are at indices 0x01, 0x02 and 0x05, all over the shared interface 1. The RS50 is a single-device base. Centre calibration (section 5, page 0x812C) lives on sub-device 0x05. The driver only uses it on the G Pro. --- ## 2. USB Interface Structure -The RS50 presents **3 HID interfaces** to the host: +The RS50 presents **3 HID interfaces** to the host. A HID interface is one logical USB device for input or output. Each interface has endpoints, the USB pipes the wheel exposes: ### Interface 0 - Game Controller (Joystick) | Property | Value | @@ -61,7 +61,7 @@ The RS50 presents **3 HID interfaces** to the host: | Endpoint OUT | `0x03 OUT` (Interrupt, 64 bytes) | | Purpose | Real-time force feedback | -**Important**: FFB uses dedicated endpoint `0x03 OUT`, NOT the HID++ protocol. +**Important**: force feedback (FFB, the motor force the wheel plays back) uses the dedicated endpoint `0x03 OUT`. It does NOT use the HID++ protocol. --- @@ -128,16 +128,17 @@ Button state is encoded in bytes 0-3 of the input report. ### D-pad Encoding (Byte 0 low nibble, bits 0-3) - standard HID hat -Byte 0's low nibble (`byte0 & 0x0F`) is a **standard HID Hat Switch** -(Usage `0x39`). The interface-0 report descriptor declares it as logical -`0-7` over physical `0-315` degrees with a null state, which by HID -convention means value `0` = Up and each step is `45` degrees clockwise. +The low nibble of byte 0 (`byte0 & 0x0F`) is a **standard HID Hat Switch** +(Usage `0x39`). The report descriptor is the HID table that declares the +layout of each report. The interface-0 descriptor declares the hat as +logical `0-7` over physical `0-315` degrees, with a null state. By HID +convention, value `0` = Up, and each step is `45` degrees clockwise. Values `8-15` are the null (centered / released) state. The high nibble (bits 4-7) holds the A/X/B/Y buttons listed in the Byte 0 table above. -Because this is a standard hat switch, the kernel's native HID input -mapping decodes it to `ABS_HAT0X`/`ABS_HAT0Y`; the driver does **no** -custom D-pad decoding. +This is a standard hat switch, so the kernel's native HID input mapping +decodes it to `ABS_HAT0X`/`ABS_HAT0Y`. The driver does **no** custom D-pad +decoding. | Hat value | Direction | Angle | |-----------|-----------|-------| @@ -151,8 +152,8 @@ custom D-pad decoding. | `7` | Up-Left | 315 deg | | `8-15` | Released (null state) | - | -**Detection**: the hat value is `byte0 & 0x0F`; `0-7` are directions and -`8-15` are released (so "released" is also detectable as `byte0 & 0x08`). +**Detection**: the hat value is `byte0 & 0x0F`. Values `0-7` are directions. +Values `8-15` are released, so "released" is also detectable as `byte0 & 0x08`. **Example (no buttons pressed):** - Idle / released: `08 00 00 00` @@ -164,11 +165,11 @@ custom D-pad decoding. > An earlier revision of this section documented a hand-rolled byte-0 > decode with a non-standard direction table (e.g. value `0x02` = Left, -> `0x06` = Down). That decode lived in the driver, mapped several -> directions wrongly - it reported physical Left as Down - and was removed +> `0x06` = Down). That decode lived in the driver. It mapped several +> directions wrongly: it reported physical Left as Down. It was removed > in favour of the kernel's native hat mapping (issue #22). The table -> above is the standard HID hat encoding the report descriptor actually -> declares, confirmed against the live wheel after the fix. +> above is the standard HID hat encoding that the report descriptor +> declares. It was confirmed against the live wheel after the fix. ### Wheel Position Encoding @@ -208,14 +209,17 @@ Brake partial (0x4847): > **Endpoint 0x03 carries one 64-byte type-0x01 packet family, not two > separate protocols.** Byte 10 (the "new samples this packet" count) -> demultiplexes it: `0` is a pure constant-force ("KF") update -> documented here, and `4` is a unified force+audio ("TF") packet whose -> bytes 12-63 carry a rolling haptic sample window on top of the same -> force field. **[`TRUEFORCE_PROTOCOL.md`](TRUEFORCE_PROTOCOL.md) is the +> tells the two uses apart. `0` is a pure constant-force ("KF") update, +> documented here. `4` is a unified force+audio ("TF", TrueForce) packet. +> TrueForce is Logitech's haptic feature: it plays audio-like vibration +> samples through the motor. In a TF packet, bytes 12-63 carry a rolling +> haptic sample window on top of the same force field. +> **[`TRUEFORCE_PROTOCOL.md`](TRUEFORCE_PROTOCOL.md) is the > authoritative reference for the full framing** (window layout, init > sequence, type-0x0e range, type-0x02 responses). This section covers -> only the constant-force subset the kernel driver's steering path -> emits, plus the encoding and refresh command shared by both. +> only the constant-force subset that the kernel driver's steering path +> emits. It also covers the encoding and the refresh command that both +> uses share. ### Constant-Force Report (64 bytes, byte 10 = 0) - VERIFIED @@ -235,10 +239,10 @@ Offset Size Type Description ``` Bytes 6-9 are the wheel's motor torque target ("cur" in TrueForce -terms) and are honoured whether or not the packet also carries audio, -so a constant-force packet is a TF stream packet with an empty sample -window. **CRITICAL**: the sequence counter is a **single byte** that -wraps at 255 (unlike the two-byte HID++ sequence). +terms). The wheel honours them whether or not the packet also carries +audio. So a constant-force packet is a TF stream packet with an empty +sample window. **CRITICAL**: the sequence counter is a **single byte**. +It wraps at 255 (unlike the two-byte HID++ sequence). ### Force Value Encoding (Offset Binary) @@ -257,7 +261,7 @@ uint16_t offset_binary = (int16_t)signed_value + 0x8000; ### FFB Enable/Refresh Command (64 bytes) -Sent periodically during gameplay (approximately every 30-60 seconds): +Seen periodically during gameplay, approximately every 30-60 seconds (but see the correction below): ``` Offset Size Description @@ -272,12 +276,13 @@ Offset Size Description Example: `05 07 00 00 00 00 00 FF FF 00 00 00 00 ...` > **CORRECTION (capture re-analysis):** this `05 07` packet is NOT a wheel -> command. In every capture the `05 07 .. FF FF` packets are 32-byte -> DualShock-4 lightbar/rumble output reports to a *game controller* that was -> plugged in at capture time - the `FF FF` is the DS4 lightbar colour, not an -> FFB value. G HUB never sends `05 07` to the wheel, and the wheel's FFB -> endpoint is silent at idle. Host-alive is carried entirely by the type-0x01 -> force stream. The driver no longer sends this packet. +> command. In every capture, the `05 07 .. FF FF` packets are 32-byte +> DualShock-4 lightbar/rumble output reports. They went to a *game +> controller* that was plugged in at capture time. The `FF FF` is the DS4 +> lightbar colour, not an FFB value. G HUB (Logitech's Windows +> configuration software) never sends `05 07` to the wheel. The wheel's FFB +> endpoint is silent at idle. The type-0x01 force stream carries the whole +> host-alive signal. The driver no longer sends this packet. ### Example FFB Commands @@ -294,33 +299,33 @@ Maximum force RIGHT, sequence 0x01: ### Observed Behavior -- Force update rate: games stream **1000 Hz** (observed in every gameplay - capture: ACC on RS50, ACC/BeamNG on G PRO - median inter-packet gap - ~1.0 ms); the kernel driver's own force stream matches that at 1000 Hz - since 0.30.0. Before that it was a jiffies timer whose nominal 500 Hz was - really 333 Hz, because a self-rearming jiffies timer never gets the period - it asks for -- Sequence counter increments with each command (one shared counter across - all interface-2 packet types on the wire) -- Force value and duplicate must always match -- `05 07` is NOT sent to the wheel (see the correction above - it is a - DualShock-4 packet); there is no idle FFB keepalive +- Force update rate: games stream at **1000 Hz**. This was observed in every + gameplay capture (ACC on RS50, ACC/BeamNG on G PRO), with a median + inter-packet gap of ~1.0 ms. The kernel driver's own force stream matches + that at 1000 Hz since 0.30.0. Before that, it was a jiffies timer (a timer + that counts kernel ticks). Its nominal 500 Hz was really 333 Hz, because a + self-rearming jiffies timer never gets the period it asks for +- The sequence counter increments with each command. One shared counter + covers all interface-2 packet types on the wire +- The force value and its duplicate must always match +- `05 07` is NOT sent to the wheel (see the correction above: it is a + DualShock-4 packet). There is no idle FFB keepalive --- ## 5. HID++ Protocol (Interface 1) -The RS50 uses the HID++ 2.0-family protocol for configuration, -reporting protocol number 4. Decoding IRoot `GetProtocolVersion` (fn1) -per Logitech's official x0000 spec, the capture traffic -`10ff001d 0000 39` -> `12ff001d 04 02 39` (`2026-01-26_ghub_startup`) -reads: byte 0 `protocolNum` = 4, byte 1 `targetSw` = 0x02 (bit 1 = -"Logitech Gaming Software is the intended target SW"), byte 2 = echoed -pingData. Officially this is NOT a major.minor version - "4.2" is the -Linux kernel driver's de-facto major.minor reading of the same two -bytes, kept elsewhere in this document for consistency with kernel -terminology. G Hub uses this call with random pingData as a liveness -ping throughout every session. +The RS50 uses the HID++ 2.0-family protocol for configuration. It reports +protocol number 4. IRoot is the root feature (feature 0x0000), and its +function 1 (fn1) is `GetProtocolVersion`. Decoded per Logitech's official +x0000 spec, the capture traffic `10ff001d 0000 39` -> `12ff001d 04 02 39` +(`2026-01-26_ghub_startup`) reads as follows. Byte 0 `protocolNum` = 4. +Byte 1 `targetSw` = 0x02 (bit 1 = "Logitech Gaming Software is the +intended target SW"). Byte 2 = echoed pingData. Officially this is NOT a +major.minor version. "4.2" is the Linux kernel driver's de-facto +major.minor reading of the same two bytes. This document keeps "4.2" +elsewhere for consistency with kernel terminology. G Hub uses this call +with random pingData as a liveness ping throughout every session. ### Message Formats @@ -353,18 +358,18 @@ Bytes 4-63: Parameters ### โš ๏ธ CRITICAL: RS50 HID++ Report ID Behavior -**The RS50 has non-standard HID++ report handling:** +**The RS50 has non-standard HID++ report handling.** A report ID is the first byte of a HID report; it names the report format: 1. **G Hub sends SHORT reports (0x10)** for all commands, NOT long reports (0x11) 2. **RS50 ALWAYS responds with VERY LONG reports (0x12)** regardless of the input report type 3. Responses are 64 bytes even for simple queries -This is different from other Logitech HID++ devices which typically respond with the same report type they receive - but it IS officially specified: Logitech's HID vendor-collection usages document defines report ID 0x12 as the "very long" HID++ report (64 bytes, usage page 0xFF43), and the vendor collection usage's high byte is a capability bitmask (bit 0 = short 0x10/7B, bit 1 = long 0x11/20B, bit 2 = very-long 0x12/64B), so a device advertising usage 0x07NN supports all three. A driver can therefore detect very-long support from the report descriptor instead of assuming it. (An earlier revision of this section called 0x12 an undocumented firmware extension; the cpg-docs 2.0 draft indeed only defines 0x10/0x11, but the vendor-usages document covers it.) Note the exception in section 5.3: SUB-DEVICE responses (dev_idx 0x01/0x02/0x05) arrive as 0x11, not 0x12. +Other Logitech HID++ devices typically respond with the same report type they receive. The RS50 behaviour is different, but it IS officially specified. Logitech's HID vendor-collection usages document defines report ID 0x12 as the "very long" HID++ report (64 bytes, usage page 0xFF43). The high byte of the vendor collection usage is a capability bitmask: bit 0 = short 0x10/7B, bit 1 = long 0x11/20B, bit 2 = very-long 0x12/64B. So a device that advertises usage 0x07NN supports all three. A driver can therefore detect very-long support from the report descriptor instead of assuming it. (An earlier revision of this section called 0x12 an undocumented firmware extension. The cpg-docs 2.0 draft indeed only defines 0x10/0x11, but the vendor-usages document covers 0x12.) Note the exception in section 5.3: SUB-DEVICE responses (dev_idx 0x01/0x02/0x05) arrive as 0x11, not 0x12. **Implication for drivers:** -- When sending 0x10 (short) or 0x11 (long), expect response on 0x12 (very long) +- When you send 0x10 (short) or 0x11 (long), expect the response on 0x12 (very long) - The kernel driver must handle this asymmetric report ID behavior -- Feature discovery and settings queries work correctly when using 0x10 requests +- Feature discovery and settings queries work correctly with 0x10 requests **Verified via USB capture (2026-01-28):** ``` @@ -374,7 +379,7 @@ Device โ†’ Host: 12 ff 00 0b 18 00 00... (VERY LONG: feature at index 0x18) ### HID++ Communication Method -Commands are sent via **USB Control Transfer (SET_REPORT)** to endpoint 0, NOT via interrupt OUT. +The host sends commands via **USB Control Transfer (SET_REPORT)** to endpoint 0, NOT via interrupt OUT. SET_REPORT is the standard HID request that writes a report over the control pipe. Responses arrive via **Interrupt IN** on endpoint 0x82. ``` @@ -384,6 +389,8 @@ Device โ†’ Host: Interrupt IN (endpoint 0x82) ### Complete Feature Table (Verified) +The wheel assigns each HID++ feature a feature index. That is the slot number the host puts in byte 2 of every request. The feature ID is the fixed 16-bit page number of the feature; the index can change between firmware versions. + | Index | Feature ID | Name | G Hub Setting | |-------|------------|------|---------------| | 0x00 | `0x0000` | IRoot | Feature discovery | @@ -411,38 +418,41 @@ Device โ†’ Host: Interrupt IN (endpoint 0x82) **DeviceInfo identity readout (live-verified 2026-07-02).** Feature `0x0003` fn0 getDeviceInfo returns `[entityCnt][unitId x4][transport -x2][modelId...][capabilities @ byte 14]`; capabilities bit 0 gates fn2 -`getDeviceSerialNumber`, which returns the real 12-character ASCII -serial (verified identical to the USB `iSerial`). fn1 +x2][modelId...][capabilities @ byte 14]`. Capabilities bit 0 gates fn2 +`getDeviceSerialNumber`. That function returns the real 12-character +ASCII serial (verified identical to the USB `iSerial`). fn1 `getFwInfo(entity)` returns `[type][name x3 ASCII][BCD number][BCD -rev][BE16 BCD build][active][trPid]...`; the wheel base has 3 entities -(type 1 bootloader "BL2", type 0 active main FW "U1 65.03.B0038", type -2 hardware) and the motor unit at sub-device `0x05` carries its own -DeviceInfo whose type-0 entity is the servo firmware ("SC -02.01.B0042"). Querying past the last entity returns a standard -InvalidArgument error frame. The driver reads all of this once at init -(`serial ..., base FW ..., motor FW ...` in dmesg, prefixed with the model tag) and exposes -`wheel_serial` / `wheel_firmware` in sysfs. +rev][BE16 BCD build][active][trPid]...`. The wheel base has 3 entities: +type 1 bootloader "BL2", type 0 active main FW "U1 65.03.B0038", and +type 2 hardware. The motor unit at sub-device `0x05` carries its own +DeviceInfo. Its type-0 entity is the servo firmware ("SC 02.01.B0042"). +A query past the last entity returns a standard InvalidArgument error +frame. The driver reads all of this once at init (`serial ..., base FW +..., motor FW ...` in dmesg, prefixed with the model tag). It exposes +`wheel_serial` / `wheel_firmware` in sysfs. Sysfs is the Linux +attribute file system under `/sys`, where the driver publishes its +settings. **Feature-type flags** (per Logitech's official x0000/x0001 specs, which define the full byte): bit 7 `obsl` (obsolete), bit 6 `hidden`, bit 5 `eng` (engineering), bit 4 `manuf_deact` (manufacturing-deactivatable), bit 3 `compl_deact` (compliance-deactivatable), bits 2-0 reserved. Every feature the Linux -driver touches (0x8040, 0x807A/B, 0x80A4, 0x8133-0x8140, and the -dev-0x05 calibration cluster 0x812B/0x812C) advertises flags 0x00 = -public. The undocumented catalog entries not listed above decode as: -0x40 = hidden; 0x60 = hidden + engineering; 0x70 = hidden + -engineering + manufacturing-deactivatable - features deliberately not -exposed to normal software. A useful signal that the driver's surface -sits entirely on Logitech's public feature set. (IFeatureSet -`getFeatureID` also returns a featureVersion byte the catalog dumps in -this section do not record; versions gate function availability, e.g. -x8040 gained its illumination on/off functions in v1.) +driver touches advertises flags 0x00 = public. That set is 0x8040, +0x807A/B, 0x80A4, 0x8133-0x8140, and the dev-0x05 calibration cluster +0x812B/0x812C. The undocumented catalog entries not listed above decode +as: 0x40 = hidden; 0x60 = hidden + engineering; 0x70 = hidden + +engineering + manufacturing-deactivatable. Those are features that +Logitech deliberately does not expose to normal software. This is a +useful signal: the driver's surface sits entirely on Logitech's public +feature set. (IFeatureSet `getFeatureID` also returns a featureVersion +byte. The catalog dumps in this section do not record it. Versions gate +function availability, e.g. x8040 gained its illumination on/off +functions in v1.) ### Setting Commands (All Verified) -Each setting feature exposes a handful of HID++ functions. The encoding in byte 3 of the short report is `(function_number << 4) | SW_ID`. In the G Hub captures this analysis is derived from, SW_ID is `0xD` across the board; the Linux driver uses SW_ID `0x0a` (it must not use `0x01` - the pedal sub-device's MCU silently drops sw-id `0x01`), so the same SET appears on the wire as e.g. `0x2a` rather than `0x2d`. GET semantics are *mostly* `fn=0` queries capabilities/limits and `fn=1` reads current value - **but damping is an exception: its current value is read with `fn=0`; `fn=1` is the SETTER and an empty-payload `fn=1` sets damping to 0.** The SET function number also varies **per feature and per wheel**. Do not assume all settings use `fn=2`: damping and TRUEFORCE each have their own SET fn, and the two wheels agree on the exceptions. +Each setting feature exposes a handful of HID++ functions. Byte 3 of the short report encodes `(function_number << 4) | SW_ID`. SW_ID is the software ID, a nibble that tags which client sent a request. In the G Hub captures behind this analysis, SW_ID is `0xD` across the board. The Linux driver uses SW_ID `0x0a`. It must not use `0x01`: the pedal sub-device's MCU (its microcontroller) silently drops sw-id `0x01`. So the same SET appears on the wire as e.g. `0x2a` rather than `0x2d`. GET semantics are *mostly* as follows: `fn=0` queries capabilities/limits, and `fn=1` reads the current value. **Damping is an exception: its current value is read with `fn=0`. `fn=1` is the SETTER, and an empty-payload `fn=1` sets damping to 0.** The SET function number also varies **per feature and per wheel**. Do not assume all settings use `fn=2`. Damping and TRUEFORCE each have their own SET fn. The two wheels agree on the exceptions. | Feature | Page | GET caps | GET value | SET (RS50 + G Pro) | |---------|------|----------|-----------|--------------------| @@ -455,9 +465,9 @@ Each setting feature exposes a handful of HID++ functions. The encoding in byte | TRUEFORCE | 0x8139 | `fn=0` | `fn=1` | **`fn=3`** (`0x3D`) | | Centre calibration | 0x812C | - | - | **`fn=3`** (`0x3D`) on sub-device 0x05 (RS50 + G Pro, both verified) | -[1] Damping reuses `fn=1` for both GET-value and SET; the device disambiguates by payload length (empty on GET, 3 bytes on SET). +[1] Damping reuses `fn=1` for both GET-value and SET. The device tells them apart by payload length (empty on GET, 3 bytes on SET). -The driver uses the same SET fn numbers for both wheels (`hidpp_dd_ff_data::fn_set_*` defaulted for RS50, overridden where G Pro differs). In practice the two wheels agreed on every SET fn we've captured so far. +The driver uses the same SET fn numbers for both wheels (`hidpp_dd_ff_data::fn_set_*` defaulted for RS50, overridden where G Pro differs). In practice, the two wheels agreed on every SET fn captured so far. All non-calibration commands use Short HID++ (`0x10`) with device index `0xFF`. @@ -499,7 +509,7 @@ Set: 10 FF 1A 2D [Flags] 00 [Level] | 0 | `0x01` | User explicitly set this level right now (slider move) | | 2 | `0x04` | Auto filter mode enabled | -The four values observed across RS50 and G Pro captures (`auto_ffb_filter`, `ffb_filter_sweep`, and the 2026-04-18 G Pro run) are `0x00`, `0x01`, `0x04`, `0x05`. Any combination of the two bits is legal: +Four values were observed across the RS50 and G Pro captures (`auto_ffb_filter`, `ffb_filter_sweep`, and the 2026-04-18 G Pro run): `0x00`, `0x01`, `0x04`, `0x05`. Any combination of the two bits is legal: | Flags | Interpretation | |-------|----------------| @@ -508,7 +518,7 @@ The four values observed across RS50 and G Pro captures (`auto_ffb_filter`, `ffb | `0x04` | Auto ON, level held (auto-toggle path) | | `0x05` | Auto ON, user just set the level | -The driver splits this across two sysfs writes: `wheel_ffb_filter` always sets bit 0 and OR's bit 2 from the current auto state; `wheel_ffb_filter_auto` writes bare `0x00`/`0x04` to mirror G Hub's auto-toggle behaviour. See commits `63999d8` (decode) and `8ab5fc4` (driver simplification). +The driver splits this across two sysfs writes. `wheel_ffb_filter` always sets bit 0, and it ORs in bit 2 from the current auto state. `wheel_ffb_filter_auto` writes bare `0x00`/`0x04` to mirror G Hub's auto-toggle behaviour. See commits `63999d8` (decode) and `8ab5fc4` (driver simplification). **Filter Level (Byte 6):** 1-15 @@ -542,10 +552,11 @@ Set: 10 FF 18 2D [Degrees_Hi] [Degrees_Lo] 00 **Range**: 90ยฐ to 2700ยฐ in 10ยฐ increments -> The 90ยฐ minimum is not a curiosity. When Logitech's TrueForce SDK cannot -> reach G HUB, which is its normal state under Proton, a game asking how far -> the wheel turns receives this floor rather than the real range, and clamps -> its steering to 45ยฐ each way. See `docs/TRUEFORCE_PROTOCOL.md`, "The SDK's +> The 90ยฐ minimum is not a curiosity. Under Proton (the Wine-based layer that +> runs Windows games on Linux), Logitech's TrueForce SDK normally cannot +> reach G HUB. In that state, a game that asks how far the wheel turns +> receives this floor rather than the real range. The game then clamps its +> steering to 45ยฐ each way. See `docs/TRUEFORCE_PROTOCOL.md`, "The SDK's > own IPC, and where 90 degrees comes from". #### TRUEFORCE (Feature 0x8139, Index 0x19) @@ -581,10 +592,11 @@ Set: 10 FF 15 2D [Value_Hi] [Value_Lo] 00 > **CORRECTION (capture re-analysis + hardware):** the steering "Sensitivity" > slider does NOT write feature 0x8040. `0x8040` is LED BrightnessControl only. > G HUB's Sensitivity is a full 64-point `0x80A4` AxisResponseCurve upload on -> the steering axis (a cubic Bezier (0,0)->(1,1) with control points -> P1=(1-s, s), P2=(s, 1-s) for s=slider/100; 50 = identity = revert to the -> built-in curve). The `0x8040` "Set" shown below only changes LED brightness. -> The driver's `wheel_sensitivity` now uploads the 0x80A4 curve accordingly. +> the steering axis. The curve is a cubic Bezier from (0,0) to (1,1), with +> control points P1=(1-s, s) and P2=(s, 1-s), where s=slider/100. A slider +> value of 50 is the identity, which reverts to the built-in curve. The +> `0x8040` "Set" shown below only changes LED brightness. The driver's +> `wheel_sensitivity` now uploads the 0x80A4 curve accordingly. The 0x8040 write shown here changes LED brightness (both modes): ``` @@ -618,8 +630,8 @@ Set: 10 FF 0A 2D 00 [Value] 00 > โš ๏ธ **Note**: This is the simplified "quick effect" command. For full per-LED RGB > control with custom colors, see **Section 9: LIGHTSYNC RGB LED Control**. -The feature index is discovered dynamically via `hidpp_root_get_feature(0x807A)`. -Typical index: `0x0B` or `0x0C` depending on firmware. +The driver discovers the feature index at run time via `hidpp_root_get_feature(0x807A)`. +Typical index: `0x0B` or `0x0C`, depending on firmware. ``` Set: 10 FF [idx] 3C [Effect] 00 00 @@ -632,7 +644,7 @@ Set: 10 FF [idx] 3C [Effect] 00 00 | `0x04` | Leftโ†’Right | | `0x05`-`0x09` | CUSTOM 1-5 (renders custom slot `effect - 5`) | -The value only STAGES the effect; the strip repaints on the following +The value only STAGES the effect. The strip repaints on the following zero-parameter fn6 commit (see section 9.3.2). #### Profile/Mode Switch (Feature 0x8137, Index 0x17) @@ -675,13 +687,14 @@ Switch to Onboard 3: 10 FF 17 2D 03 00 00 #### Onboard Profile Authoring There is no block-write/upload protocol for an onboard slot's contents. -Confirmed by a full USB capture of G Hub's onboard settings page -(`dev/captures/2026-07-14_profile_save.pcapng`, 342 HID++ frames) plus a -read-only live cross-check against a connected RS50: **a slot is authored -by activating it (the Set Mode/Profile call above) and then sending the -same per-setting SET commands every other view uses.** The wheel persists -each value to the active slot's own storage immediately; there is no -separate commit/save call afterwards. +An onboard slot is one of the five settings profiles the wheel stores on +itself. This was confirmed by a full USB capture of G Hub's onboard +settings page (`dev/captures/2026-07-14_profile_save.pcapng`, 342 HID++ +frames), plus a read-only live cross-check against a connected RS50. +**To author a slot, first activate it (the Set Mode/Profile call above). +Then send the same per-setting SET commands that every other view uses.** +The wheel persists each value to the active slot's own storage +immediately. There is no separate commit/save call afterwards. **Select-then-set model:** ``` @@ -690,48 +703,49 @@ separate commit/save call afterwards. 3. Set: 10 FF 16 2A [strength] 00 wheel_strength's normal SET, FFBStrength 4. ... any other setting's normal SET ``` -Each SET is answered by the same unsolicited broadcast event the driver -already consumes when running live in that mode; there is no additional -frame that means "saved" or "committed". Reading a setting back always -reports the ACTIVE slot's stored value: switching to a different slot and -back shows the values it was last written with, confirming the writes -land in that slot's own storage, not a shared/desktop-only location. +The wheel answers each SET with the same unsolicited broadcast event that +the driver already consumes when running live in that mode. There is no +additional frame that means "saved" or "committed". A read-back of a +setting always reports the ACTIVE slot's stored value. Switch to a +different slot and back, and the read shows the values that slot was last +written with. This confirms that the writes land in that slot's own +storage, not in a shared/desktop-only location. **What a slot stores** (per-slot, confirmed by the capture and the live cross-check): rotation range (`0x8138`), FFB strength (`0x8136`), TrueForce intensity (`0x8139`), damping (`0x8133`), the FFB filter pair (`0x8140`), brake force (`0x8134`, onboard-mode-only on the wheel itself), -LED effect + brightness, and the slot's own name (`0x8137` fn3/fn4). NOT -slot content: the steering sensitivity curve (G Hub actively reverts axis -0 to linear at the start of every onboard settings burst - the Sensitivity -slider is a desktop-only concept), combined-pedals, and the pedal/ -handbrake response curves (a desktop-only software shaping layer; ignored -by the pedal MCU in native PC mode). - -**Slot-0/name edge case:** `0x8137` fn3 (get slot name) against slot -argument `0x00` (the desktop state) returns an empty name rather than an -error - desktop has no onboard name to report, which is expected, not a -fault. +LED effect + brightness, and the slot's own name (`0x8137` fn3/fn4). Three +things are NOT slot content. The first is the steering sensitivity curve: +G Hub actively reverts axis 0 to linear at the start of every onboard +settings burst, and the Sensitivity slider is a desktop-only concept. The +second is combined-pedals. The third is the pedal/handbrake response +curves, a desktop-only software curve layer that the pedal MCU ignores in +native PC mode. + +**Slot-0/name edge case:** `0x8137` fn3 (get slot name) with slot argument +`0x00` (the desktop state) returns an empty name rather than an error. +Desktop has no onboard name to report. This is expected, not a fault. **Feature indices pinned this session** (request/response pairing against -a live G Hub startup capture; previously missing from the table below): -index `0x11` = `0x8127` (DualClutch; its fn2 result reads back identical -across every slot because it is the wheel's own bite-point state, not part -of a slot's content, see 12.6; this driver has never needed to send it), -`0x12` = `0x8130` (DisplayGameData, the Dynamic OLED's transport; -see 12.3), `0x13` = `0x8132` (undecoded; not touched by any sysfs -attribute). - -**Application-level implementation:** see `docs/SYSFS_API.md`'s "Editing -an onboard slot" section for how logi-wheel's userspace turns this wire -model into a guarded "select a slot, edit its values, optionally revert" -flow - the kernel driver itself needs no new attributes for any of it, -since authoring a slot is just writing the existing per-setting attrs +a live G Hub startup capture; previously missing from the table above). +Index `0x11` = `0x8127` (DualClutch, see 12.6). Its fn2 result reads back +identical across every slot, because it is the wheel's own bite-point +state and not part of a slot's content. This driver has never needed to +send it. Index `0x12` = `0x8130` (DisplayGameData, the Dynamic OLED's +transport; see 12.3). Index `0x13` = `0x8132` (undecoded; not touched by +any sysfs attribute). + +**Application-level implementation:** see the "Editing an onboard slot" +section of `docs/SYSFS_API.md`. It describes how logi-wheel's userspace +turns this wire model into a guarded "select a slot, edit its values, +optionally revert" flow. The kernel driver itself needs no new attributes +for any of it. To author a slot, you write the existing per-setting attrs while `wheel_profile` names that slot. #### Centre Calibration (Feature 0x812C, sub-device 0x05) -Both RS50 and G Pro expose centre calibration on sub-device `0x05`, not the root (`0xFF`). The feature index must be discovered by querying page `0x812C` on device index `0x05` and the resulting SET must also go to device index `0x05`. The index differs per wheel; RS50 captures show index `0x0f`, G Pro varies. +Both the RS50 and the G Pro expose centre calibration on sub-device `0x05`, not on the root (`0xFF`). To find the feature index, query page `0x812C` on device index `0x05`. The resulting SET must also go to device index `0x05`. The index differs per wheel: RS50 captures show index `0x0f`, and the G Pro varies. G Hub's calibrate button is a three-step exchange: @@ -745,33 +759,33 @@ Set: 10 05 [idx] 3D [Pos_Hi] [Pos_Lo] 00 host -> device: fn=3 SET centre - Bytes 4-5: absolute encoder position (big-endian u16) to adopt as the new centre - Byte 6: reserved, `0x00` -Two sysfs attributes drive this (see `docs/SYSFS_API.md`): `wheel_calibrate` is the raw SET primitive - the game or userspace tool samples the current wheel position from evdev and passes it verbatim as the new centre; `wheel_calibrate_here` performs the fn=1 GET then the fn=3 SET internally, adopting the wheel's current physical position in one write. Verified on RS50 from `2026-04-22_re_calibrate.pcapng` and on G Pro from `2026-04-18_calibrate.pcapng`. +Two sysfs attributes drive this (see `docs/SYSFS_API.md`). `wheel_calibrate` is the raw SET primitive. The game or userspace tool samples the current wheel position from evdev (the Linux input event interface) and passes it verbatim as the new centre. `wheel_calibrate_here` performs the fn=1 GET and then the fn=3 SET internally. It adopts the wheel's current physical position in one write. Verified on the RS50 from `2026-04-22_re_calibrate.pcapng` and on the G Pro from `2026-04-18_calibrate.pcapng`. ### 5.1 G PRO PID Feature Set (RS50-in-compat-mode and real G PRO) -The G PRO Racing Wheel for Xbox/PC (`046d:c272`) and PS/PC (`046d:c268`) PIDs cover two physically distinct cases: +The G PRO Racing Wheel PIDs (product IDs) for Xbox/PC (`046d:c272`) and PS/PC (`046d:c268`) cover two physically distinct cases: - **Real G PRO Racing Wheel.** Direct-drive wheel. iProduct string is "Logitech PRO Racing Wheel". - **RS50 in "G PRO compatibility" mode.** RS50 hardware re-enumerated as the same VID/PID via the wheel's OLED menu. iProduct string is "Logitech RS50 Base for PlayStation/PC". -Both wheels are direct-drive and run the same modern firmware architecture. They share the same HID++ 4.2 feature catalog at the same indices and the same dedicated 64-byte FFB endpoint on interface 2. The driver gives both `HIDPP_QUIRK_DD_FFB` from the id-table (no iProduct-string sniff), so both go through the `hidpp_dd_ff_*` code path rather than the inherited G920 HID++ FFB path. This is what makes basic FFB, TrueForce streaming, and the wheel-config sysfs surface all work on a real G PRO without the queue-saturation / "Failed to send command" failures the G920 path inherits from the older gear-driven generation (issue #8). +Both wheels are direct-drive. Both run the same modern firmware architecture. They share the same HID++ 4.2 feature catalog at the same indices. They also share the same dedicated 64-byte FFB endpoint on interface 2. The driver gives both `HIDPP_QUIRK_DD_FFB` from the id-table (no iProduct-string sniff). So both go through the `hidpp_dd_ff_*` code path rather than the inherited G920 HID++ FFB path. This is what makes basic FFB, TrueForce streaming, and the wheel-config sysfs surface all work on a real G PRO. It avoids the queue-saturation / "Failed to send command" failures that the G920 path inherits from the older gear-driven generation (issue #8). Catalog note (corrected 2026-07-02 after a full IFeatureSet cross-capture comparison): the RS50's compat-mode device-0xff feature catalog is -**byte-identical to its native catalog** (the full index 0x04-0x25 table +**byte-identical to its native catalog**. The full index 0x04-0x25 table matches between `2026-01-26_ghub_startup` and -`2026-04-26_compat_ghub_init`). Only the **real G PRO's** catalog differs -- same canonical feature IDs, shifted to different indices (e.g. what -sits at index 0x0d on the RS50 is at 0x0b on the G Pro). An earlier -revision of this section described the compat catalog as "reduced"; -that was wrong. What remains true operationally: `ROOT.GetFeature()` +`2026-04-26_compat_ghub_init`. Only the **real G PRO's** catalog differs. +It has the same canonical feature IDs, shifted to different indices (e.g. +what sits at index 0x0d on the RS50 is at 0x0b on the G Pro). An earlier +revision of this section described the compat catalog as "reduced". That +was wrong. One thing remains true operationally: `ROOT.GetFeature()` lookups did not reliably return the expected indices on the G PRO PID in -early bring-up, so the driver still tries native-mode IDs first and then +early bring-up. So the driver still tries native-mode IDs first, and then the `HIDPP_DD_COMPAT_*` fallback indices (range / strength / trueforce / damping / FFB filter / profile-mode switch / LIGHTSYNC / centre calibration all wired). -A different feature set, observed only in compat mode, controls live host-pushed wheel settings. All commands below are short HID++ reports (`0x10`) sent on the corded device index `0xff` with sw_id `d`. +A different feature set, observed only in compat mode, controls live host-pushed wheel settings. All commands below are short HID++ reports (`0x10`). They are sent on the corded device index `0xff` with sw_id `d`. | Feature ID (best-guess) | Index | Fn | Purpose | Params | |---|---|---|---|---| @@ -781,24 +795,24 @@ A different feature set, observed only in compat mode, controls live host-pushed | `0x8133` | 0x14 | 1 | Set wheel damping | `[value_hi, value_lo, 0x00]` (16-bit BE 0..0xFFFF; 0..100% scale) | | `0x8140` | 0x1A | 2 | Set FFB filter level | `[0x00, 0x00, level]` (level 1..15) | -The fallback indices in the table are what GHUB uses on a 2026-04-26 firmware revision. The driver tries `ROOT.GetFeature()` first so a future firmware that reorders the table still works; if that returns an unknown index, the hardcoded fallback is used. +The fallback indices in the table are what GHUB uses on a 2026-04-26 firmware revision. The driver tries `ROOT.GetFeature()` first, so a future firmware that reorders the table still works. If that returns an unknown index, the driver uses the hardcoded fallback. -**Mode switching in compat mode**: feature `0x8137` (advertised at index `0x17` in compat, the same canonical "Profile" feature ID as in native) carries the mode switch: +**Mode switching in compat mode**: feature `0x8137` carries the mode switch. In compat it is advertised at index `0x17`, the same canonical "Profile" feature ID as in native: -- `fn=1` with no parameters reads `[profile, mode, ...]`: `params[0]` is the profile index (0 = desktop, 1..5 = onboard slot), `params[1]` a mode flag. (An earlier revision of this section misread the response as `[mode_class, slot]`; that was disproven live 2026-07-02 - a decode built on it reported "profile 1" while the wheel's OLED sat on slot 2.) +- `fn=1` with no parameters reads `[profile, mode, ...]`. `params[0]` is the profile index (0 = desktop, 1..5 = onboard slot). `params[1]` is a mode flag. (An earlier revision of this section misread the response as `[mode_class, slot]`. That was disproven live 2026-07-02: a decode built on it reported "profile 1" while the wheel's OLED sat on slot 2.) - `fn=2` with `[0x00, 0x00, 0x00]` switches the wheel into desktop mode. Subsequent live host SETs (range, strength, trueforce, damping, filter) take effect on the motor immediately. Verified end-to-end on 2026-04-26 against the live wheel. -- `fn=2` with `[slot, 0x00, 0x00]` selects onboard slot 1..5 - the same plain-index encoding as native, confirmed live 2026-07-02 (OLED landed on the correct slot name, sysfs read-back matched, and the slot's stored range applied). This is also what G Hub's own packets send (`10ff172d 03` in the compat profile-sweep captures). -- `fn=3` with `[slot]` returns the slot's user-assigned profile NAME: `[slot][length][ASCII name]` (e.g. `12ff173c 01 04 "RACE"`). Exposed as the `wheel_profile_names` sysfs attribute; verified against the wheel's OLED profile list. +- `fn=2` with `[slot, 0x00, 0x00]` selects onboard slot 1..5. This is the same plain-index encoding as native, confirmed live 2026-07-02 (the OLED landed on the correct slot name, the sysfs read-back matched, and the slot's stored range applied). This is also what G Hub's own packets send (`10ff172d 03` in the compat profile-sweep captures). +- `fn=3` with `[slot]` returns the slot's user-assigned profile NAME: `[slot][length][ASCII name]` (e.g. `12ff173c 01 04 "RACE"`). Exposed as the `wheel_profile_names` sysfs attribute. Verified against the wheel's OLED profile list. -The wheel boots in onboard mode by default. The OLED menu cycles between onboard profile slots only; it does not expose a desktop indicator separately, but the slot name displayed reflects the active state. +The wheel boots in onboard mode by default. The OLED menu cycles between onboard profile slots only. It does not show a separate desktop indicator, but the slot name on display reflects the active state. -An earlier draft of this document and the driver shipped with a "force_desktop_mode" helper that sent `10ff1a2d 00 00 0b` to feature `0x8140`; the dedicated filter-only capture (`dev/captures/2026-04-26_compat_range_filter_only_desktop.pcapng`) proved that command actually sets the FFB filter level to `0x0b` (= 11), not switching modes. The helper was removed and replaced with the discovery above. +An earlier draft of this document and the driver shipped with a "force_desktop_mode" helper. It sent `10ff1a2d 00 00 0b` to feature `0x8140`. The dedicated filter-only capture (`dev/captures/2026-04-26_compat_range_filter_only_desktop.pcapng`) proved that this command sets the FFB filter level to `0x0b` (= 11). It does not switch modes. The helper was removed and replaced with the discovery above. **Format notes**: -- Damping uses `fn=1` (other settings use `fn=2` or `fn=3`); this matches the native RS50 convention where damping is also `fn=1`. -- FFB filter wire format in compat mode is simpler than native: bytes 0-1 are zero, byte 2 carries the 1..15 level. There is no `flags` byte and no observable auto-mode encoding from compat-mode captures, so the driver leaves `wheel_ffb_filter_auto` as `-EOPNOTSUPP` in compat. -- Onboard mode silently ignores live host-pushed SETs. Compat-mode sysfs writes only take physical effect on the motor while the wheel is in desktop mode; the wheel boots in onboard, so write `0` to `wheel_profile` first to switch into desktop. +- Damping uses `fn=1` (other settings use `fn=2` or `fn=3`). This matches the native RS50 convention, where damping is also `fn=1`. +- The FFB filter wire format in compat mode is simpler than native: bytes 0-1 are zero, and byte 2 carries the 1..15 level. There is no `flags` byte. Compat-mode captures show no auto-mode encoding, so the driver leaves `wheel_ffb_filter_auto` as `-EOPNOTSUPP` in compat. +- Onboard mode silently ignores live host-pushed SETs. Compat-mode sysfs writes only take physical effect on the motor while the wheel is in desktop mode. The wheel boots in onboard mode. So write `0` to `wheel_profile` first to switch into desktop. **Previously-unknown features, resolved 2026-07-02** (full cross-capture analysis; index-to-ID mapping derived from IFeatureSet fn1 pairing in @@ -806,115 +820,119 @@ analysis; index-to-ID mapping derived from IFeatureSet fn1 pairing in - **Feature `0x80A4` (AxisResponseCurve; index `0x0d` on RS50 native AND compat, `0x0b` on the real G Pro; also present on pedal sub-device - `0x02`).** Per-axis 64-point response-curve store, NOT a torque LUT. - `fn0` caps returns `[axes=7][3][3]` on the wheel base (`[3][3][3][1]` - on the pedal unit); `fn1 [axis]` returns `[axis][00 01 00][HID usage] - [bit width 0x10][loaded_points u16][max_points u16 = 0x0040]`; an - upload is `fn3 [axis]` (open; empty param = axis 0 / steering), - 22x `fn4 [n][(in,out) u16-BE x n]` chunks (n <= 3; 64 monotonic points - from `(0,0)` to `(0xFFFF,0xFFFF)`), then `fn5` commit (echoes - `[axis][00][0040]`); `fn6 [axis]` reverts an axis to the built-in - curve. This is what G Hub's **Sensitivity** slider uploads for the - steering axis, exposed as `wheel_response_curve`; the wheel applies it - to the steering axis it reports to the PC. - - The same feature applies curves on three axis groups, each of which the - driver drives: + `0x02`).** This is a per-axis 64-point response-curve store, NOT a + torque LUT. `fn0` caps returns `[axes=7][3][3]` on the wheel base + (`[3][3][3][1]` on the pedal unit). `fn1 [axis]` returns + `[axis][00 01 00][HID usage][bit width 0x10][loaded_points u16] + [max_points u16 = 0x0040]`. An upload has three steps: + 1. `fn3 [axis]` opens the upload (empty param = axis 0 / steering). + 2. 22x `fn4 [n][(in,out) u16-BE x n]` chunks carry the points (n <= 3; + 64 monotonic points from `(0,0)` to `(0xFFFF,0xFFFF)`). + 3. `fn5` commits (echoes `[axis][00][0040]`). + + `fn6 [axis]` reverts an axis to the built-in curve. This is what + G Hub's **Sensitivity** slider uploads for the steering axis. The driver + exposes it as `wheel_response_curve`. The wheel applies it to the + steering axis it reports to the PC. + + The same feature applies curves on three axis groups. The driver drives + each of them: - **Steering** (base dev `0xff`, axis 0): `wheel_response_curve` and `wheel_sensitivity`. - **Pedals** (base dev `0xff`, axes **1/2/3** = throttle/brake/clutch): `wheel_{throttle,brake,clutch}_{curve,sensitivity,deadzone}`. **On the BASE, not the pedal MCU.** The pedal sub-device exposes its own - `0x80A4` store and will accept a 64-point upload, reporting it back as - loaded - but it never applies it to the axis it reports to the PC. The + `0x80A4` store. It accepts a 64-point upload and reports it back as + loaded. But it never applies it to the axis it reports to the PC. The curve that actually bends a pedal lives on the base, one axis up from - the pedal index. Hardware-proven 2026-07-28 with a step curve (output - plateaus `0x2000`/`0xE000`, which an applied curve makes the band between - unreachable): + the pedal index. This was hardware-proven 2026-07-28 with a step curve. + Its output plateaus are `0x2000`/`0xE000`, so an applied curve makes + the band between them unreachable: | destination | result | |---|---| | pedal MCU | readback said 64/64 points, axis swept straight through the forbidden band | | base axis 1 | axis snapped to exactly `0x2000` with the pedals untouched | - Each mapping was then confirmed individually, nothing touched: base axis 1 - moves only `ABS_RX` (throttle), axis 2 only `ABS_RY` (brake), axis 3 only - `ABS_RZ` (clutch). G Hub writes its throttle curve to base axis 1 as well - (capture, same date), so this is also the path the wheel is designed - around. - - Earlier revisions of this document said the pedal MCU applied its curve - and that the base's pedal axes were inert. Both were wrong, and the driver - was built on them - every pedal curve, sensitivity and deadzone was - silently doing nothing until it was retargeted. Note the trap: `fn1` - readback reports what a sub-device has STORED, which is not the same as - what it APPLIES, and only the latter can be seen on evdev. + Each mapping was then confirmed on its own, with nothing else touched. + Base axis 1 moves only `ABS_RX` (throttle). Axis 2 moves only `ABS_RY` + (brake). Axis 3 moves only `ABS_RZ` (clutch). G Hub writes its throttle + curve to base axis 1 as well (capture, same date). So this is also the + path the wheel is designed around. + + Earlier revisions of this document said the pedal MCU applied its curve. + They also said the base's pedal axes were inert. Both were wrong, and + the driver was built on them. Every pedal curve, sensitivity and + deadzone was silently doing nothing until it was retargeted. Note the + trap: `fn1` readback reports what a sub-device has STORED. That is not + the same as what it APPLIES. Only the latter can be seen on evdev. - **Analog handbrake** (base dev `0xff`, axis 4, HID usage 0x32 = Z, evdev `ABS_Z`): `wheel_handbrake_curve` and `wheel_handbrake_sensitivity`. A measurement note: the wheel emits no HID reports while an axis is held - still, so an upload does not change the reported axis until it next moves; - read the point count back with `fn1` for a motion-free check. - Unknowns: the second `03` in caps, pedal-unit - `fn9 [axis]` (called on every G Hub init; possibly axis refresh), and - whether curves persist across power cycles. + still. So an upload does not change the reported axis until it next + moves. For a motion-free check, read the point count back with `fn1`. + Unknowns: the second `03` in caps, pedal-unit `fn9 [axis]` (called on + every G Hub init; possibly axis refresh), and whether curves persist + across power cycles. - **Feature `0x80D0` (combined pedals; on the wheel base dev `0xff`).** A - boolean: `fn1` sets it (`10 ff 1a 01` on / `...00` off), `fn0` reads it - back. When on, the wheel merges the throttle and brake into a single centred - axis for legacy games. Exposed as `wheel_combined_pedals` (desktop mode only). - The same feature also emits the profile-change broadcast events the driver - consumes, so its index is shared. + boolean. `fn1` sets it (`10 ff 1a 01` on / `...00` off). `fn0` + reads it back. When on, the wheel merges the throttle and brake into a + single centred axis for legacy games. Exposed as `wheel_combined_pedals` + (desktop mode only). The same feature also emits the profile-change + broadcast events that the driver consumes, so its index is shared. - **Feature `0x1BC0` (REPORT_HID_USAGE; index `0x09` on RS50, `0x07` on - G Pro).** On every config apply, G Hub sends `fn2` (empty) followed by - LONG `fn1` writes of `01 0009 00XX` with XX iterating `{0x0d..0x12, - 0x15}` on the RS50 PID and `{0x0d..0x13, 0x15}` on the G PRO PID - - byte-identical across wheels, so XX is not a feature index. Given the - registered feature name, the likely reading is "enable reporting of - Button-page (usage page 0x0009) usages 13..21"; the effect on the HID - interface was never isolated in captures. Optional: every SET works - without it, and the Linux driver omits it with no observed downside. - Naming sources: Solaar's feature registry and openlogi.org both list - `0x1BC0` as REPORT_HID_USAGE / "report HID usage pages to host" - (corroborating the payload reading); cvuchener/hidpp's older table - calls it "Persistent remappable action", but that is settled - definitively by Logitech's own spec set, which contains - `x1c00_persistentremappableaction` and no 0x1BC0 document - - PersistentRemappableAction is `0x1C00`, and `0x1BC0` = - ReportHidUsages stands. No public source documents 0x1BC0's - functions; the fn map above (from captures) is the best available. + G Pro).** On every config apply, G Hub sends `fn2` (empty). It then + sends LONG `fn1` writes of `01 0009 00XX`. XX iterates `{0x0d..0x12, + 0x15}` on the RS50 PID and `{0x0d..0x13, 0x15}` on the G PRO PID. The + writes are byte-identical across wheels, so XX is not a feature index. + Given the registered feature name, the likely reading is "enable + reporting of Button-page (usage page 0x0009) usages 13..21". The effect + on the HID interface was never isolated in captures. It is optional: + every SET works without it, and the Linux driver omits it with no + observed downside. Naming sources: Solaar's feature registry and + openlogi.org both list `0x1BC0` as REPORT_HID_USAGE / "report HID usage + pages to host", which corroborates the payload reading. The older table + in cvuchener/hidpp calls it "Persistent remappable action". Logitech's + own spec set settles that definitively: it contains + `x1c00_persistentremappableaction` and no 0x1BC0 document. + PersistentRemappableAction is `0x1C00`, and `0x1BC0` = ReportHidUsages + stands. No public source documents the functions of 0x1BC0. The fn map + above (from captures) is the best available. - **Compat index `0x15` = `0x8134` Brake Force - mystery closed.** The - compat catalog is identical to native (see above), so index 0x15 is - the already-documented Brake Force feature. The previously mysterious + compat catalog is identical to native (see above). So index 0x15 is the + already-documented Brake Force feature. The previously mysterious `10ff152a XXXX` pushes during "unrelated" slider sweeps are the G Hub - Brake Force slider (u16 BE, 0..0xFFFF = 0..100%), e.g. `028f / 4ccc / - 7fff / ffff` in `compat_range_other_sliders_desktop`, each answered by - broadcast `12ff1500 XXXX` - wire-identical to the native - `2026-01-26_brake_force_sweep`. The sw_id byte carries no protocol - meaning: G Hub runs parallel client sessions on sw_ids `a`..`e` (plus - `f` for DFU checks) and the wheel broadcasts with sw_id 0. Note these - captures show brake-force writes accepted in DESKTOP mode too, so the - native section's "onboard mode only" restriction deserves a re-check. -- Mode-change broadcasts: when the wheel transitions between onboard profiles (via the OLED) or between onboard and desktop modes (when Windows G Hub takes / releases control), the wheel may emit an unsolicited notification on EP 0x82. Not yet captured or consumed. + Brake Force slider (u16 BE, 0..0xFFFF = 0..100%). Examples are `028f / + 4ccc / 7fff / ffff` in `compat_range_other_sliders_desktop`. The wheel + answers each with broadcast `12ff1500 XXXX`. This is wire-identical to + the native `2026-01-26_brake_force_sweep`. The sw_id byte carries no + protocol meaning. G Hub runs parallel client sessions on sw_ids `a`..`e` + (plus `f` for DFU checks), and the wheel broadcasts with sw_id 0. Note + that these captures show brake-force writes accepted in DESKTOP mode + too. So the native section's "onboard mode only" restriction deserves a + re-check. +- Mode-change broadcasts: the wheel may emit an unsolicited notification on EP 0x82 when it transitions between onboard profiles (via the OLED), or between onboard and desktop modes (when Windows G Hub takes / releases control). Not yet captured or consumed. **Evidence**: `dev/captures/2026-04-26_compat_ghub_init.pcapng` (full GHUB bring-up enumeration); `..._compat_range_ghub_slider_{desktop,onboard}.pcapng` (steering angle 90โ†’1080ยฐ); `..._compat_range_strength_slider_{desktop,onboard}.pcapng` (FFB strength 0โ†’100%); `..._compat_range_damping_only_desktop.pcapng` (isolated damping sweep, source for the 0x14/fn=1 wiring); `..._compat_range_filter_only_desktop.pcapng` (isolated filter sweep, source for the 0x1a/fn=2 wiring and proof that "force_desktop_mode" was actually the filter setter). ### 5.2 Compatibility Mode Behavior That Is NOT a Driver Bug -A few behaviors observed in compat mode look like driver problems but are firmware-side defaults verified to match Windows GHUB on the same wheel firmware. Listed here so future readers do not re-investigate them: +A few behaviors observed in compat mode look like driver problems. They are firmware-side defaults, verified to match Windows GHUB on the same wheel firmware. They are listed here so future readers do not re-investigate them: -- **Default centering spring**: in compat mode the wheel applies its own self-centering spring whenever it is in onboard mode and no game / host-side FFB is actively writing. This is the same on Windows with GHUB running. There is no known host command to disable it; users see it as "the wheel won't stop pushing back to center" when nothing is talking to the wheel. -- **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. Set it from Linux via `wheel_profile=0` then `wheel_range=`, or from the OLED by editing the active onboard profile. -- **LIGHTSYNC works in compat mode**: feature `0x807A` is advertised in compat at the same index discovery picks up in native, and `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. +- **Default centering spring**: in compat mode, the wheel applies its own self-centering spring whenever it is in onboard mode and no game / host-side FFB is actively writing. This is the same on Windows with GHUB running. There is no known host command to disable it. Users see it as "the wheel won't stop pushing back to center" when nothing is talking to the wheel. +- **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=`. 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) -Cross-capture census (2026-07-02, all 62 captures): besides the wheel -base at dev_idx `0xff` (~100k packets each way), three sub-devices carry -real HID++ traffic on BOTH the RS50 and the real G Pro - dev `0x01` -(~390 packets each way), dev `0x02` (~560), dev `0x05` (~420). No other -sub-index appears. Each has its own feature catalog, enumerated by G Hub -on every init: +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 +carry real HID++ traffic on BOTH the RS50 and the real G Pro: dev `0x01` +(~390 packets each way), dev `0x02` (~560), and dev `0x05` (~420). No +other sub-index appears. Each has its own feature catalog. G Hub +enumerates each catalog on every init: - **dev `0x01`** - display / rim module: `0x8091` (per-key/LED matrix), `0x18A2`, `0x9315`. @@ -925,48 +943,48 @@ on every init: modular pedals should target this dev_idx. - **dev `0x05`** - motor / base unit: `0x8128`, `0x8129`, `0x812B`, **`0x812C` centre calibration**, `0x92D1`. The whole 0x812x - calibration cluster lives here; live calibrate traffic confirmed on + calibration cluster lives here. Live calibrate traffic is confirmed on both wheels (`2026-04-22_re_calibrate` on RS50: `10050f1a` read - position -> `10050f3a` write centre; same pattern at index 0x0c on the + position -> `10050f3a` write centre; same pattern at index 0x0c in the G Pro contributor captures). The driver's `wheel_calibrate*` already targets this dev_idx. - **dev `0x04` - RS Shifter & Handbrake accessory** (hardware-verified - 2026-07-28, RS50 only; not part of the 2026-07-02 census because the - accessory was not attached during it). An optional accessory in the - base's USB-A port, not a separate USB device: only a HID++ sub-device - plus fields already reserved in the base's interface-0 input report - (evdev `BTN_TOP2`/`BTN_PINKIE`/`BTN_THUMB2`/`ABS_Z`, section 5.1's - input mapping table). IFeatureSet at idx `0x01`, count 18 (HID++ - 4.2). Names: `0x0005` reports **"RS Shifter & Handbrake"**, device - type byte `0x1a` (not in any known registry); `0x0007` - DeviceFriendlyName reports **"RS Handbrake & Shifter"** (reversed word - order) and is accessory-only, absent on every other sub-device. - `0x0003` DeviceInformation: 3 entities, own serial-number capability - bit set, main firmware "MPO 13.00.B0013" on its own SecureDFU - (`0x00C3`). Full feature list: core `0x0001`, `0x0003`, `0x0005`, - `0x0007`, `0x00C3`; unknown/engineering `0x1602`, `0x1802` - (DeviceReset, do not call), `0x1807` (likely + 2026-07-28, RS50 only). It is not part of the 2026-07-02 census, + because the accessory was not attached during it. It is an optional + accessory in the base's USB-A port, not a separate USB device. It is + only a HID++ sub-device plus fields already reserved in the base's + interface-0 input report (evdev `BTN_TOP2`/`BTN_PINKIE`/`BTN_THUMB2`/ + `ABS_Z`, section 5.1's input mapping table). IFeatureSet is at idx + `0x01`, count 18 (HID++ 4.2). Names: `0x0005` reports **"RS Shifter & + Handbrake"**, device type byte `0x1a` (not in any known registry). + `0x0007` DeviceFriendlyName reports **"RS Handbrake & Shifter"** + (reversed word order). `0x0007` is accessory-only and absent on every + other sub-device. `0x0003` DeviceInformation: 3 entities, own + serial-number capability bit set, main firmware "MPO 13.00.B0013" on + its own SecureDFU (`0x00C3`). Full feature list: core `0x0001`, + `0x0003`, `0x0005`, `0x0007`, `0x00C3`; unknown/engineering `0x1602`, + `0x1802` (DeviceReset, do not call), `0x1807` (likely ConfigurableProperties), `0x180B`, `0x18B1`, `0x1BC0` ReportHidUsages, `0x1E00` EnableHiddenFeatures (disabled), `0x1E02` ManageDeactivatableFeatures, `0x1EB0`, `0x9315`; and three public, - non-core, non-DFU features that are exactly the surface a "3 sliders + - mode" G HUB accessory page needs: + non-core, non-DFU features. Those three are exactly the surface a + "3 sliders + mode" G HUB accessory page needs: - **`0x80A4` AxisResponseCurve** - the accessory's own store, 1 axis - (HID usage `0x32` = Z, same usage as the base's handbrake axis 4), - 0/64 points loaded (built-in linear response active). Same fn0/fn1 - wire layout as every other `0x80A4` store (section 5.1); the driver - uses this axis count to identify the accessory during discovery - (`HIDPP_DD_SHIFTER_AXIS_COUNT`). + (HID usage `0x32` = Z, the same usage as the base's handbrake axis 4), + 0/64 points loaded (built-in linear response active). It has the same + fn0/fn1 wire layout as every other `0x80A4` store (section 5.1). The + driver uses this axis count to identify the accessory during + discovery (`HIDPP_DD_SHIFTER_AXIS_COUNT`). - **`0x80B1` BANDED_AXIS** - unique to this sub-device across the - whole wheel (verified absent on `0xff`/`0x01`/`0x03`/`0x05`), so the + whole wheel (verified absent on `0xff`/`0x01`/`0x03`/`0x05`). So the driver uses `Root.getFeature(0x80B1)` as the accessory confirmation - test. Name is first-party (Solaar commit b9e0cf8, sourced from LGHUB - itself; listed in Solaar's "racing peripherals" group). + test. The name is first-party (Solaar commit b9e0cf8, sourced from + LGHUB itself; listed in Solaar's "racing peripherals" group). **Decoded 2026-07-28** from G Hub captures. This is the actuation-point store behind the Shift Sensitivity and Handbrake Actuation sliders. - A band is addressed by `[group][band]`, and carries a signed 32-bit + A band is addressed by `[group][band]`. It carries a signed 32-bit position on the lever's travel: | fn | direction | params | meaning | @@ -976,11 +994,13 @@ on every init: | `fn2 [group][band]` | read | | `[group][band][value s32-LE]` | | `fn3 [group][band][value s32-LE]` | write | | set the band | - Group 0 is the sequential shifter and holds **two** bands, one per shift - direction; group 1 is the digital handbrake and holds **one**. Asking for - a band that does not exist (e.g. `(1,1)`) returns error `0x2a`. + Group 0 is the sequential shifter. It holds **two** bands, one per shift + direction. Group 1 is the digital handbrake. It holds **one** band. A + request for a band that does not exist (e.g. `(1,1)`) returns error + `0x2a`. - G Hub's scales, both linear in the 1-100 its UI accepts (it refuses 0): + G Hub's scales are both linear in the 1-100 range its UI accepts (it + refuses 0): - **shift**: `+/- pct * 0.008` of full scale, written to BOTH of group 0's bands, symmetric about centre. The slider therefore spans 80% of the @@ -989,22 +1009,22 @@ on every init: band 0. **G Hub overflows here.** The handbrake scale exceeds 16 bits above about - 69%, and G Hub truncates: it writes 75% as `5312` rather than `70848` - - a point far SHORTER than 50%. That wraparound is what makes a captured - sweep look non-monotonic and undecodable until you spot it. The wheel - itself accepts the full 32-bit value (`-94464` stored and read back - verbatim), so this driver writes the true value and stays monotonic; - above ~69% our behaviour and G Hub's will not agree. - - The firmware validates nothing - it stored `+/-2000000000` without - complaint - so there is no range to discover by probing, and a bad value + 69%, and G Hub truncates. It writes 75% as `5312` rather than `70848`, + a point far SHORTER than 50%. That wraparound makes a captured sweep + look non-monotonic and undecodable until you spot it. The wheel itself + accepts the full 32-bit value (`-94464` stored and read back verbatim). + So this driver writes the true value and stays monotonic. Above ~69%, + our behaviour and G Hub's will not agree. + + The firmware validates nothing. It stored `+/-2000000000` without + complaint. So there is no range to discover by probing, and a bad value is not rejected. - **`0x1B30` DEVICE_MODE** - also unique to this sub-device. Same first-party naming source as `0x80B1`. - **Decoded 2026-07-28**: it reports the physical mode switch's current - position. `fn2` (no params) returns the mode in its first byte; `fn0` - returns a static `1a 03 01` on this firmware and is NOT the mode. + **Decoded 2026-07-28**: it reports the current position of the physical + mode switch. `fn2` (no params) returns the mode in its first byte. + `fn0` returns a static `1a 03 01` on this firmware and is NOT the mode. `fn1` and `fn3` return errors. | value | switch position | @@ -1013,51 +1033,50 @@ on every init: | `2` | digital handbrake (MIDDLE) | | `1` | analog handbrake (RIGHT) | - Note the ordering: middle and right are **2 and 1**, not 1 and 2. It + Note the ordering: middle and right are **2 and 1**, not 1 and 2. This was measured by moving the switch through all three positions while - watching `fn2`, precisely because assuming left-to-right numbering is - the obvious guess and would have been wrong. + watching `fn2`. Left-to-right numbering is the obvious guess, and it + would have been wrong. A caution for anyone probing this feature: match a reply on the - function/sw byte as well as the feature index. Matching on the feature - index alone hands an `fn2` reply back as the answer to an `fn0` request, - which is what first made `fn0` look like it was changing with the - switch. + function/sw byte as well as the feature index. A match on the feature + index alone hands an `fn2` reply back as the answer to an `fn0` + request. That is what first made `fn0` look like it was changing with + the switch. - The driver discovers this sub-device, resolves the three feature - indices, exposes presence via `wheel_accessory`, and drives `0x80B1` + The driver discovers this sub-device and resolves the three feature + indices. It exposes presence via `wheel_accessory`. It drives `0x80B1` through `wheel_shift_actuation` and `wheel_handbrake_actuation`. `0x1B30` is read through `wheel_accessory_mode`. See `docs/SYSFS_API.md`. - The accessory's own `0x80A4` store is deliberately NOT used: G Hub writes - the handbrake curve there, but on this hardware a curve written to the - accessory has no observable effect, while the same curve on base axis 4 - bends `ABS_Z` immediately (both tested 2026-07-28 with the unit confirmed - in analog-handbrake mode). So `wheel_handbrake_curve` targets the base. + The accessory's own `0x80A4` store is deliberately NOT used. G Hub writes + the handbrake curve there. But on this hardware, a curve written to the + accessory has no observable effect. The same curve on base axis 4 bends + `ABS_Z` immediately. Both were tested 2026-07-28 with the unit confirmed + in analog-handbrake mode. So `wheel_handbrake_curve` targets the base. "G Hub writes somewhere else" and "our target is wrong" are different - claims, and only the second justifies a change. + claims. Only the second justifies a change. **A sub-device index belongs to a physical port, not to a device type.** -The base has two USB-A ports, and the SAME accessory reports at dev `0x04` -on the accessory port and at dev `0x03` on the pedals' port -(hardware-verified 2026-07-28: with the pedals unplugged and the accessory -in their port, `0x03` was the accessory and no 3-axis sub-device existed at -all). On this wheel the pedal MCU answers at `0x03` whether or not the +The base has two USB-A ports. The SAME accessory reports at dev `0x04` on +the accessory port and at dev `0x03` on the pedals' port. This was +hardware-verified 2026-07-28: with the pedals unplugged and the accessory +in their port, `0x03` was the accessory, and no 3-axis sub-device existed +at all. On this wheel, the pedal MCU answers at `0x03` whether or not the accessory is attached. The index is the physical port, not the device type. -Two consequences, both enforced in the driver: never key on an index to -identify a device, and never skip an index because another device was once -found there - a rescan optimisation that skipped the pedals' index made the -accessory permanently undiscoverable on the second port. The -driver never hardcodes a sub-device index for either device: it probes -a small candidate list (`0x02, 0x03, 0x01, 0x04, 0x05, 0x06`) and -classifies whatever answers by feature content (axis count for -`0x80A4`, then `0x80B1` confirmation for the accessory), in a single -pass shared by both discoveries. A future firmware or attach order could -place either device at any of these indices, or move the pedal MCU -somewhere the current candidate list does not cover - if that ever -happens, the fix is to extend the candidate list, not to special-case an -index. +Two consequences follow, and the driver enforces both. Never key on an +index to identify a device. Never skip an index because another device was +once found there: a rescan optimisation that skipped the pedals' index made +the accessory permanently undiscoverable on the second port. The driver +never hardcodes a sub-device index for either device. It probes a small +candidate list (`0x02, 0x03, 0x01, 0x04, 0x05, 0x06`). It then classifies +whatever answers by feature content (axis count for `0x80A4`, then +`0x80B1` confirmation for the accessory). It does this in a single pass +shared by both discoveries. A future firmware or attach order could place +either device at any of these indices. It could also move the pedal MCU +somewhere the current candidate list does not cover. If that ever happens, +the fix is to extend the candidate list, not to special-case an index. Two driver-relevant quirks: @@ -1065,17 +1084,17 @@ Two driver-relevant quirks: the wheel base uses for its responses. - **Feature ID `0x0009`** (unregistered; index `0x08` on RS50, `0x06` on G Pro, at dev `0xff`) looks like the sub-device topology/presence - feature: G Hub calls its `fn2` (empty) and the wheel answers with a - burst of unsolicited events `12ff0800 [unit][flags] 14` for units - 01/02 (flags 0xf0), 03/04 (0x60), 05 (0xc0) - likely how G Hub learns - which dev_idx values exist. Units 3-4 are announced but never - addressed via HID++ in any capture. - -To enumerate a sub-device's catalog on a live wheel from Linux (no -Windows capture round-trip needed), the `hidpp-list-features` tool from -cvuchener/hidpp works over hidraw and takes a `--device-index` option - -useful for verifying the dev `0x02` pedal-base map on contributors' G -Pro hardware. + feature. G Hub calls its `fn2` (empty). The wheel answers with a burst + of unsolicited events `12ff0800 [unit][flags] 14` for units 01/02 + (flags 0xf0), 03/04 (0x60), 05 (0xc0). This is likely how G Hub learns + which dev_idx values exist. Units 3-4 are announced but never addressed + via HID++ in any capture. + +You can enumerate a sub-device's catalog on a live wheel from Linux, with +no Windows capture round-trip. The `hidpp-list-features` tool from +cvuchener/hidpp works over hidraw (the raw HID device node) and takes a +`--device-index` option. This is useful for verifying the dev `0x02` +pedal-base map on contributors' G Pro hardware. --- @@ -1088,14 +1107,14 @@ Recommended initialization order: 3. **Feature Discovery** - Use IRoot (index 0x00) to find feature indices 4. **Read Settings** - Query current rotation, FFB gain 5. **Start FFB Loop** - Begin sending force commands (the driver runs a - fixed 1 kHz timer). It is an hrtimer, programmed against the clock - hardware, so the period is the one asked for and `CONFIG_HZ` does not - enter into it. It was a jiffies timer until 0.30.0, which could not - deliver this rate: the timer wheel never fires a timer early, so a - callback re-arming itself for the next jiffy always landed on the one - after, giving 2 ms where HZ is 1000 and 8 ms where HZ is 250. The - nominal 500 Hz of earlier releases was really 333 Hz for the same - reason + fixed 1 kHz timer). It is an hrtimer, a high-resolution timer + programmed against the clock hardware. So the period is the one asked + for, and `CONFIG_HZ` does not enter into it. Until 0.30.0 it was a + jiffies timer, which could not deliver this rate. The timer wheel never + fires a timer early. So a callback that re-arms itself for the next + jiffy always landed on the one after. That gave 2 ms where HZ is 1000 + and 8 ms where HZ is 250. The nominal 500 Hz of earlier releases was + really 333 Hz for the same reason --- @@ -1106,11 +1125,18 @@ Recommended initialization order: 1. **Multi-Interface Device**: Claim interface 2 for FFB, interface 0 for input 2. **FFB via hid_hw_output_report()**: Send 64-byte reports to interface 2 3. **Workqueue**: FFB must be sent from process context -4. **Full software effect pipeline**: The wheel firmware only understands raw constant forces on endpoint 0x03, but the driver emulates the complete Linux FFB effect set on top of it (FF_CONSTANT, FF_RAMP, FF_PERIODIC with SINE/SQUARE/TRIANGLE/SAW_UP/SAW_DOWN, and the four condition effects FF_SPRING, FF_DAMPER, FF_FRICTION, FF_INERTIA). Condition effects read the live wheel state (position from interface-0 byte 4-5, with velocity and acceleration derived at the timer tick) and apply the standard Linux `ff_condition_effect` formula; waveform and envelope semantics match `Documentation/input/ff.rst`. +4. **Full software effect pipeline**: The wheel firmware only understands raw constant forces on endpoint 0x03. The driver emulates the complete Linux FFB effect set on top of it (FF_CONSTANT, FF_RAMP, FF_PERIODIC with SINE/SQUARE/TRIANGLE/SAW_UP/SAW_DOWN, and the four condition effects FF_SPRING, FF_DAMPER, FF_FRICTION, FF_INERTIA). Condition effects read the live wheel state: position from interface-0 byte 4-5, with velocity and acceleration derived at the timer tick. They apply the standard Linux `ff_condition_effect` formula. Waveform and envelope semantics match `Documentation/input/ff.rst`. ### Timer-Based Force Updates -The driver uses a 500Hz timer to send continuous force commands while any effect is active. The RS50 requires continuous commands to maintain force (unlike some wheels that hold state). Each tick walks the active-effect slots, sums each effect's instantaneous contribution, applies `FF_GAIN`, and sends a single net force value. The timer keeps running whenever any effect is playing, even if the current net force happens to be zero (a SPRING at exact centre or a DAMPER with a stationary wheel) so condition effects produce force the moment the wheel moves. +The driver uses a 1 kHz timer (one tick per millisecond, since 0.30.0) to send continuous force commands while any effect is active. The RS50 requires continuous commands to maintain force (unlike some wheels that hold state). Each tick does four things in order: + +1. Walk the active-effect slots. +2. Sum each effect's instantaneous contribution. +3. Apply `FF_GAIN`. +4. Send a single net force value. + +The timer keeps running whenever any effect is playing. It runs even if the current net force happens to be zero (a SPRING at exact centre, or a DAMPER with a stationary wheel). So condition effects produce force the moment the wheel moves. ### Settings Query on Init @@ -1153,32 +1179,32 @@ static u16 rs50_force_to_offset_binary(s32 force) ### Linux Sysfs Interface -The driver exposes all runtime settings (FFB, rotation range, LIGHTSYNC, -onboard profiles, pedal curves and deadzones, Oversteer compatibility -shims, optional HID++ debug shell) as sysfs attributes under -`/sys/class/hidraw/hidrawX/device/`. +The driver exposes all runtime settings as sysfs attributes under +`/sys/class/hidraw/hidrawX/device/`. These cover FFB, rotation range, +LIGHTSYNC, onboard profiles, pedal curves and deadzones, Oversteer +compatibility shims, and the optional HID++ debug shell. -The authoritative reference for the full attribute surface (types, -ranges, read/write semantics, availability per wheel, onboard vs desktop -mode differences) is [`SYSFS_API.md`](SYSFS_API.md). This spec does not -re-enumerate it. +[`SYSFS_API.md`](SYSFS_API.md) is the authoritative reference for the full +attribute surface (types, ranges, read/write semantics, availability per +wheel, onboard vs desktop mode differences). This spec does not list it +again. --- ## 8. Differences from G920/G923 -> This section describes the G920 and the G923 Xbox edition, both of which -> use the HID++ 0x8123 path below. The G923 PlayStation edition (`c266`/ -> `c267`) is a different case: this driver now supports it directly via a -> ported classic force-feedback engine (plain HID output reports, the same -> wire format as G29/G920's in-kernel `hid-logitech` driver) - neither -> 0x8123 nor the RS50/G PRO TrueForce-stream path documented below drives -> its force feedback. The PS G923 does still carry the same interface-2 -> TrueForce stream transport as the DD wheels (confirmed by TF4ALL's -> Windows captures, issue #20, and on hardware 2026-07-26): the driver -> exposes that interface as a hidraw node and `logi-tf-sim` streams -> simulated TrueForce over it. See the G923 section in the README and -> CHANGELOG, and the coverage note in +> This section describes the G920 and the G923 Xbox edition. Both use the +> HID++ 0x8123 path below. The G923 PlayStation edition (`c266`/`c267`) is +> a different case. This driver now supports it directly via a ported +> classic force-feedback engine. That engine uses plain HID output reports, +> the same wire format as the G29/G920's in-kernel `hid-logitech` driver. +> Neither 0x8123 nor the RS50/G PRO TrueForce-stream path documented below +> drives its force feedback. The PS G923 does still carry the same +> interface-2 TrueForce stream transport as the DD (direct-drive) wheels. +> This was confirmed by TF4ALL's Windows captures (issue #20) and on +> hardware 2026-07-26. The driver exposes that interface as a hidraw node, +> and `logi-tf-sim` streams simulated TrueForce over it. See the G923 +> section in the README and CHANGELOG, and the coverage note in > [`TRUEFORCE_PROTOCOL.md`](TRUEFORCE_PROTOCOL.md). | Feature | G920/G923 | RS50 | @@ -1194,37 +1220,38 @@ re-enumerate it. ### Architecture Note -The RS50/G PRO expose **two independent force transports**, and which one a -host uses is a choice, not a hardware constraint (established 2026-07-04 by -the TF4ALL project's Windows-side kernel-filter captures, cross-checked -against our catalog): +The RS50/G PRO expose **two independent force transports**. Which one a +host uses is a choice, not a hardware constraint. This was established +2026-07-04 by the TF4ALL project's Windows-side kernel-filter captures, +cross-checked against our catalog: - **HID++ Feature 0x8123 fn2** - the path Logitech's own Windows runtime - uses for normal game FFB on these wheels too, not just on G920/G923: - report 0x11/0x12, device index 0xff, the wheel's 0x8123 feature *index* - (native RS50 catalog: 0x10; G-PRO-PID catalog: 0x0e), function 2, signed - int16 BE motor target at payload offset 10-11, sent at the game's rate - (~140-333 Hz observed). Set-and-hold: the wheel maintains the last - commanded force indefinitely with no keepalive. + uses for normal game FFB on these wheels too, not just on G920/G923. It + uses report 0x11/0x12, device index 0xff, the wheel's 0x8123 feature + *index* (native RS50 catalog: 0x10; G-PRO-PID catalog: 0x0e), and + function 2. The payload carries a signed int16 BE motor target at offset + 10-11. It is sent at the game's rate (~140-333 Hz observed). It is + set-and-hold: the wheel maintains the last commanded force indefinitely, + with no keepalive. - **Dedicated endpoint 0x03 on Interface 2** (raw report-0x01 packets) - - the TrueForce session channel, used by SDK-native games (AC EVO, ACC) - and by this Linux driver for ALL force output. While a TrueForce session - is active, bytes 6-9 of the stream packet ("cur") are the motor torque - target and OVERRIDE the 0x8123 path; the 13-slot window plays additively - on top as audio. A packet with zero new samples (byte 10 = 0) is a pure - force command - this driver's classic "KF" packet. + the TrueForce session channel. SDK-native games (AC EVO, ACC) use it, + and this Linux driver uses it for ALL force output. While a TrueForce + session is active, bytes 6-9 of the stream packet ("cur") are the motor + torque target. They OVERRIDE the 0x8123 path. The 13-slot window plays + additively on top as audio. A packet with zero new samples (byte 10 = 0) + is a pure force command. That is this driver's classic "KF" packet. The G920/G923 comparison above therefore describes *defaults*, not -capabilities: the G920/G923 has only 0x8123, while the DD wheels have both -and privilege the endpoint stream. +capabilities. The G920/G923 has only 0x8123. The DD wheels have both and +privilege the endpoint stream. **Driver implication**: this driver uses the endpoint path exclusively -(`HIDPP_QUIRK_DD_FFB` / `hidpp_dd_ff_*`), which needs the 1 kHz refresh -semantics below; the G920 `hidpp_ff_*` 0x8123 code path with its slot-based -effect engine still cannot be reused as-is (the issue #8 queue-saturation -failures), but a minimal 0x8123-fn2 force-target sender remains an untested -alternative transport - potentially relevant if the wheel's FFB-filter -smoothing turns out to apply only to that path. +(`HIDPP_QUIRK_DD_FFB` / `hidpp_dd_ff_*`). That path needs the 1 kHz +refresh semantics below. The G920 `hidpp_ff_*` 0x8123 code path, with its +slot-based effect engine, still cannot be reused as-is (the issue #8 +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. @@ -1233,76 +1260,75 @@ smoothing turns out to apply only to that path. ## 9. LIGHTSYNC RGB LED Control (Feature 0x807A) The RS50 has a horizontal strip of **10 individually addressable RGB LEDs** -across the upper section of the faceplate, used as an engine-RPM / shift -indicator. The LIGHTSYNC feature provides per-LED colour control plus a -direction setting for the built-in sweep effects. - -> **This section describes RS50 rim hardware only** (in both native and -> compat enumeration - the rim does not change with the PID). The **real -> G PRO rim** uses the same 0x807A feature page for a completely different, -> LEVEL-based rev-light protocol with no per-LED RGB. The direct-drive -> rev path, decoded from G HUB's own live captures (2026-08-14): at -> attach time the host performs **discovery reads only** - SHORT fn0, -> fn1, fn2, fn0, once - and then the level stream is a bare repeated -> pair: SHORT fn2 GET_STATE + LONG fn6 with params -> `00 01 00 0a 00 LEVEL` (level 0-10). **No arming exists on this -> path**: fn3, fn4 and fn7 are NEVER used, and from the onboard -> power-on state the strip renders bare fn2+fn6 levels exactly -> (hardware-proven; the earlier "must be fn3-armed or it refuses every -> level" belief is disproven). Colours, direction and scaling belong to -> the wheel's onboard profile. Exposed by this driver as -> `wheel_rev_level`, with the RGB attributes hidden on real G PROs. -> Caution from the TF4ALL project's original decode: bursting these +across the upper section of the faceplate. It serves as an engine-RPM / +shift indicator. The LIGHTSYNC feature provides per-LED colour control. It +also provides a direction setting for the built-in sweep effects. + +> **This section describes RS50 rim hardware only.** This holds in both +> native and compat enumeration: the rim does not change with the PID. +> The **real G PRO rim** uses the same 0x807A feature page for a +> completely different, LEVEL-based rev-light protocol with no per-LED +> RGB. The direct-drive rev path was decoded from G HUB's own live +> captures (2026-08-14). At attach time, the host performs **discovery +> reads only**: SHORT fn0, fn1, fn2, fn0, once. After that, the level +> stream is a bare repeated pair: SHORT fn2 GET_STATE + LONG fn6 with +> params `00 01 00 0a 00 LEVEL` (level 0-10). **No arming exists on this +> path**: fn3, fn4 and fn7 are NEVER used. From the onboard power-on +> state, the strip renders bare fn2+fn6 levels exactly. This is +> hardware-proven. The earlier belief, "must be fn3-armed or it refuses +> every level", is disproven. Colours, direction and scaling belong to +> the wheel's onboard profile. This driver exposes the level as +> `wheel_rev_level`, and it hides the RGB attributes on real G PROs. +> A caution from the TF4ALL project's original decode: a burst of these > writes starves the wheel's shared HID++ command processor and cuts FFB -> out on the Windows FFB path, so level writes are paced. The ~160 ms -> figure quoted from that source is wrong: a first-party G HUB capture +> out on the Windows FFB path. So level writes are paced. The ~160 ms +> figure quoted from that source is wrong. A first-party G HUB capture > (issue #20, iRacing) measures ~16.5 ms per pair, about 60 Hz. The driver > enforces a ~10 ms floor. > > **G923 editions only: the display has to be switched on before it > accepts a level** (hardware-verified 2026-08-11, both G923 editions). -> On those wheels `fn2` reports the live effect, and a wheel answering -> **0** is displaying nothing: in that state every `fn6` level is -> refused with HID++ error 5, `LogitechInternal`, until an -> `fn3 param 0x02` starts the display, after which the identical level -> is accepted. This is a G923 quirk, not part of the direct-drive -> path: the DD wheels need no enable call (see above), and the G923 -> editions keep their own separate arming code in the driver. `fn3` is -> not a boolean switch either way: values 1-4 and 6-9 are the built-in -> sweeps and the owner's custom slots, which a careless `fn3` would -> overwrite. +> On those wheels, `fn2` reports the live effect. A wheel that answers +> **0** is displaying nothing. In that state, every `fn6` level is +> refused with HID++ error 5, `LogitechInternal`. An `fn3 param 0x02` +> starts the display. After that, the identical level is accepted. This +> is a G923 quirk, not part of the direct-drive path. The DD wheels need +> no enable call (see above). The G923 editions keep their own separate +> arming code in the driver. `fn3` is not a boolean switch either way. +> Values 1-4 and 6-9 are the built-in sweeps and the owner's custom +> slots. A careless `fn3` would overwrite them. > > **`fn0` reports the strip length** in its second parameter: `0x0a` on the > direct-drive wheels, `0x05` on a G923. The level is a fraction of that -> length, so a wheel told the wrong length shows the wrong fill. +> length. So a wheel told the wrong length shows the wrong fill. > > **RS50 accepts the same level command (hardware-verified 2026-07-20, > re-verified with the bare fn2+fn6 form 2026-08-14):** writes to -> `wheel_rev_level` visibly drive the RS50's 10-LED strip too - -> 0 = all dark, 10 = all lit, intermediate values a partial fill. The -> display renders **center-out by default**, so the 10-LED strip shows +> `wheel_rev_level` visibly drive the RS50's 10-LED strip too. 0 = all +> dark, 10 = all lit, and intermediate values give a partial fill. The +> display renders **center-out by default**. So the 10-LED strip shows > 5 mirrored visual steps across a 0-10 level sweep. The display -> pattern is a separate concern from the level protocol: the level says -> how much of the bar is lit, the wheel's stored display config +> pattern is a separate concern from the level protocol. The level says +> how much of the bar is lit. The wheel's stored display config > (colours, direction) says how that amount is drawn. Reconfiguring the > pattern mid-session via `0x807B` is NOT part of G HUB's mid-session -> vocabulary and is untested during live TrueForce sessions, so it must -> not be assumed safe there. The arm-semantics question this note once -> deferred to a future capture is settled: there ARE no arm semantics on -> the direct-drive path (see the attach-time discovery reads above). A -> written level holds until the next level write; writing -> `wheel_led_effect` restores the idle pattern. +> vocabulary. It is untested during live TrueForce sessions, so it must +> not be assumed safe there. This note once deferred the arm-semantics +> question to a future capture. That question is settled: there ARE no +> arm semantics on the direct-drive path (see the attach-time discovery +> reads above). A written level holds until the next level write. A +> write to `wheel_led_effect` restores the idle pattern. > > **Historical: the old arm burst stomped the active effect > (hardware-verified 2026-07-20).** When the driver still sent an arm -> burst, its "fn3 param 0x02" was a plain SET_EFFECT that force-switched -> the wheel to effect 2 (Outside-In), so the driver had to re-assert the +> burst, its "fn3 param 0x02" was a plain SET_EFFECT. It force-switched +> the wheel to effect 2 (Outside-In). So the driver had to re-assert the > pre-arm effect afterwards. The burst is gone from the direct-drive -> path (2026-08-14, see above) - and had to go: sent during a native -> TrueForce SDK session it killed the session at init and killed wheel -> input mid-session, while the bare fn2+fn6 form coexists with a live -> session (see section 12.5). This paragraph is kept only to explain -> older captures and driver versions. +> path (2026-08-14, see above), and it had to go. Sent during a native +> TrueForce SDK session, it killed the session at init and killed wheel +> input mid-session. The bare fn2+fn6 form coexists with a live session +> (see section 12.5). This paragraph is kept only to explain older +> captures and driver versions. ### 9.1 Physical LED Layout @@ -1311,12 +1337,12 @@ direction setting for the built-in sweep effects. ``` LEDs are numbered 1-10, left to right across the faceplate strip. -The protocol uses **reversed order** - see section 9.4. +The protocol uses **reversed order**. See section 9.4. ### 9.2 Feature Discovery -The LIGHTSYNC feature uses Page ID `0x807A`. The actual feature index varies by device/firmware -and must be discovered at runtime: +The LIGHTSYNC feature uses Page ID `0x807A`. The actual feature index varies by device/firmware. +You must discover it at runtime: ``` Query: 10 FF 00 0X 80 7A 00 (ROOT.getFeatureIndex for page 0x807A) @@ -1372,7 +1398,7 @@ Byte Field Description ### 9.3.2 Detailed Function Reference (Empirical - 2026-01-30) Both LIGHTSYNC features (0x807A and 0x807B) share a similar function numbering scheme. -The following tables document what we've observed from driver testing and G Hub captures. +The following tables document what was observed from driver testing and G Hub captures. **HID++ Function Code Encoding:** The function byte encodes: `(function_number << 4) | SW_ID` @@ -1393,8 +1419,8 @@ The function byte encodes: `(function_number << 4) | SW_ID` | 7 | 0x7C | ENABLE | `00 00 00` | - | Refreshes LED display | | 8+ | 0x8C+ | - | - | ERROR 7 | Not supported | -> **Note**: fn4 and fn5 are context-dependent - they succeed during LED configuration -> but return error 5 (ERR_COUNT) at other times. Possibly related to config mode state. +> **Note**: fn4 and fn5 are context-dependent. They succeed during LED configuration +> but return error 5 (ERR_COUNT) at other times. This is possibly related to config mode state. **fn0 Response Breakdown:** ``` @@ -1441,16 +1467,16 @@ Interpretation: May enumerate effect types or zone capabilities (appears to be z | 0x08 | CUSTOM 4 (renders custom slot 3) | the slot's name | | 0x09 | CUSTOM 5 (renders custom slot 4) | the slot's name | -> **Effect values 5-9 ARE the five custom slots** - there is no separate -> "activate slot" command; selecting a slot IS selecting its effect -> number, staged by fn3 and repainted by the zero-parameter fn6 commit. -> Decoded from `2026-01-30_desktop_led_colors.pcapng` (every G Hub -> dropdown switch to CUSTOM N sends fn3 `[0x04 + N]` and reads back slot -> `N - 1`'s config and name: frames 219/339/715 and 279/525/775) and -> hardware-confirmed live (fn3 `0x08` + fn6 repainted the strip to -> slot 3). Earlier revisions misread 0x05 as a lone "Static/Custom" mode -> and called 6-9 unlabeled. Corollary: fn2 GET_STATE returns the selected -> custom slot as `effect - 5` when the value is >= 5. +> **Effect values 5-9 ARE the five custom slots.** There is no separate +> "activate slot" command. Selecting a slot IS selecting its effect +> number. fn3 stages it, and the zero-parameter fn6 commit repaints it. +> This was decoded from `2026-01-30_desktop_led_colors.pcapng`: every +> G Hub dropdown switch to CUSTOM N sends fn3 `[0x04 + N]` and reads back +> the config and name of slot `N - 1` (frames 219/339/715 and +> 279/525/775). It was hardware-confirmed live (fn3 `0x08` + fn6 repainted +> the strip to slot 3). Earlier revisions misread 0x05 as a lone +> "Static/Custom" mode and called 6-9 unlabeled. Corollary: fn2 GET_STATE +> returns the selected custom slot as `effect - 5` when the value is >= 5. #### Feature 0x0C (Page 0x807B) - RGB Zone Config @@ -1464,7 +1490,7 @@ Interpretation: May enumerate effect types or zone capabilities (appears to be z | 5+ | 0x5C+ | - | - | ERROR 7 | Not supported | > **IMPORTANT**: fn6/fn7 do NOT exist on feature 0x0C! They only work on 0x0B. -> Sending fn6/fn7 to 0x0C returns HID++ error 7 (ERR_INVALID_FUNCTION_ID). +> If you send fn6/fn7 to 0x0C, the wheel returns HID++ error 7 (ERR_INVALID_FUNCTION_ID). **fn0 Response Breakdown:** ``` @@ -1489,7 +1515,7 @@ Slot 2: 02 03 ff 00 00 ff 00 00 ff 00 00 ff 00 00 ff 00 (red pattern) Slot 3: 03 03 00 00 ff ff ff 00 00 00 ff ff ff 00 00 00 (blue/yellow pattern) Slot 4: 04 04 00 ff 00 00 ff 00 ff 00 00 ff 00 00 ff 00 (type=4, green/cyan) ``` -Note: Response shows first ~4-5 LEDs in 16-byte SHORT response. Full RGB data requires VERY_LONG report. +Note: the 16-byte SHORT response shows only the first ~4-5 LEDs. Full RGB data requires the VERY_LONG report. **fn3 Response (GET_NAME) - Returns slot name:** ``` @@ -1527,9 +1553,8 @@ When G Hub starts with wheel already on, it queries feature 0x0B: > **Correction (2026-08-14)**: current G HUB captures show **neither > fn4 nor fn7 on the rev-light path**. The attach-time reads on that > path are fn0, fn1, fn2, fn0, and nothing else (see the section 9 -> intro). The listing above is kept as recorded from its own capture; -> treat fn4/fn7 as belonging to the RGB slot-upload flow, not to rev -> levels. +> intro). The listing above is kept as recorded from its own capture. +> Treat fn4/fn7 as part of the RGB slot-upload flow, not of rev levels. #### G Hub Color Change Sequence (from lightsync_custom_save.pcapng) @@ -1545,9 +1570,9 @@ When user applies new custom colors: 8. 10 FF 0B 7C 00 00 00 - Enable/refresh display (feature 0x0B fn7) ``` -(Earlier versions of this section had the pre-config / commit / enable -steps listed against feature 0x0C; they actually live on 0x0B. The -summary table at the end of this section was already correct.) +(Earlier versions of this section listed the pre-config / commit / enable +steps against feature 0x0C. They actually live on 0x0B. The summary table +at the end of this section was already correct.) #### Key Discovery: First Update Works, Subsequent Updates Don't @@ -1555,9 +1580,9 @@ Testing revealed that: 1. **First color change after driver init**: LEDs display correctly 2. **Second and subsequent changes**: HID++ commands succeed but LEDs don't update -This suggests the device has internal state that gets "consumed" on the first update. -G Hub may reset this state via the init sequence (fn0โ†’fn1โ†’fn2โ†’fn4โ†’fn7) before each change, -or there's a cold-start initialization we haven't captured yet. +This suggests the device has internal state that the first update "consumes". +G Hub may reset this state via the init sequence (fn0โ†’fn1โ†’fn2โ†’fn4โ†’fn7) before each change. +Or there is a cold-start initialization that has not been captured yet. ### 9.4 Set RGB Zone Config (Function 0x2C) - VERIFIED @@ -1587,8 +1612,8 @@ Byte Field Description ``` > โš ๏ธ **CRITICAL: LED Order is REVERSED!** -> Protocol sends LED10 first (bytes 6-8) and LED1 last (bytes 33-35). -> Driver code must reverse user-facing LED1-10 to protocol order LED10-1. +> The protocol sends LED10 first (bytes 6-8) and LED1 last (bytes 33-35). +> Driver code must reverse the user-facing order LED1-10 to the protocol order LED10-1. **Slot Index Values:** | Value | G Hub Name | @@ -1605,11 +1630,11 @@ Byte 5 carries a **1-based wire value (1-4)**, NOT the driver's 0-3 `HIDPP_DD_LIGHTSYNC_DIR_*` enum. `dev/captures/2026-07-19_lightsync_direction.pcapng` contains only device-to-host GET (fn1) echoes of the state G Hub had already applied for -each direction - no host-to-device 0x0C SET frames were captured. The wire -values below were derived from those GET echoes (GET/SET symmetry: a Get -Zone Config response carries the same byte 5 a Set would have sent), -corroborated by the old driver's `direction + 2` encoding being accepted by -the firmware for 2/3/4 and NAKed for the out-of-range 5: +each direction. No host-to-device 0x0C SET frames were captured. The wire +values below were derived from those GET echoes. This relies on GET/SET +symmetry: a Get Zone Config response carries the same byte 5 a Set would +have sent. The old driver's `direction + 2` encoding corroborates it: the +firmware accepted 2/3/4 and NAKed the out-of-range 5: | Wire (byte 5) | Effect | G Hub Swedish | G Hub English | Driver enum | |---------------|--------|---------------|---------------|-------------| @@ -1619,21 +1644,20 @@ the firmware for 2/3/4 and NAKed for the out-of-range 5: | `0x04` | Right to Left sweep | Hร–GER TILL Vร„NSTER | Right to Left | 1 | **Hardware-verified 2026-07-20** (RS50, live rev-fill sweeps): all four -driver-enum directions were watched on the physical strip and match the -table above exactly - enum 0 fills left to right, 1 right to left, 2 from +driver-enum directions were watched on the physical strip. They match the +table above exactly. Enum 0 fills left to right, 1 right to left, 2 from the centre outward, 3 from the edges inward. The verification used the rev-level fill (0x807A fn2+fn6, see the rev-light note at the top of -section 9), which follows the SELECTED slot's stored -direction, so the same test confirmed both the wire mapping and the -fill/direction coupling. The 0x807A effect-select values are a separate -encoding entirely (1-4 = built-in animations, 5-9 = the custom slots; -see 9.3.2). +section 9). That fill follows the SELECTED slot's stored direction. So the +same test confirmed both the wire mapping and the fill/direction coupling. +The 0x807A effect-select values are a separate encoding entirely (1-4 = +built-in animations, 5-9 = the custom slots; see 9.3.2). > **Historical bug:** an earlier driver encoded byte 5 as `enum + 2` -> (L->R=2, R->L=3, IO=4, **OI=5**). That both mislabelled the sweeps (its -> "Left to Right" actually sent Outside-In's value) and sent `5` for -> Outside-In, which is out of the device's 1-4 range - the firmware NAKs it -> and the write surfaces as `-EIO`. The driver now maps enum<->wire +> (L->R=2, R->L=3, IO=4, **OI=5**). That mislabelled the sweeps: its +> "Left to Right" actually sent Outside-In's value. It also sent `5` for +> Outside-In, which is out of the device's 1-4 range. The firmware NAKs +> it, and the write surfaces as `-EIO`. The driver now maps enum<->wire > explicitly via `hidpp_dd_lightsync_dir_to_wire()` / > `hidpp_dd_lightsync_wire_to_dir()`. @@ -1716,10 +1740,10 @@ Response (device returns current config): ### 9.8 LED Mirroring Based on Direction -For the two **symmetric** directions - **Inside-Out** (driver enum 2, wire -`0x01`) and **Outside-In** (driver enum 3, wire `0x02`) - G Hub collapses the -10 LEDs into **5 mirrored pairs**, so the colours are a palindrome about the -strip's centre: +Two directions are **symmetric**: **Inside-Out** (driver enum 2, wire +`0x01`) and **Outside-In** (driver enum 3, wire `0x02`). For those, G Hub +collapses the 10 LEDs into **5 mirrored pairs**. So the colours are a +palindrome about the strip's centre: - LED1 โ†” LED10 (outermost pair) - LED2 โ†” LED9 @@ -1728,13 +1752,14 @@ strip's centre: - LED5 โ†” LED6 (innermost pair) Painting one LED sets its mirror to the same colour (G Hub draws a bracket -linking the pair). Confirmed 2026-07-19 from G Hub screenshots. The two sweep -directions (Left-to-Right, Right-to-Left) leave all 10 LEDs independent. +that links the pair). Confirmed 2026-07-19 from G Hub screenshots. The two +sweep directions (Left-to-Right, Right-to-Left) leave all 10 LEDs +independent. -This is application behaviour, not protocol-level enforcement - the wire -format still carries all 10 colours - but a UI that mirrors these directions -(as G Hub and `logi-wheel` do) must send a palindrome so the animation looks -right. The `wheel_led_colors` sysfs attribute always takes 10 colours. +This is application behaviour, not protocol-level enforcement. The wire +format still carries all 10 colours. But a UI that mirrors these directions +(as G Hub and `logi-wheel` do) must send a palindrome, so the animation +looks right. The `wheel_led_colors` sysfs attribute always takes 10 colours. ### 9.9 Linux Driver Implementation @@ -1774,42 +1799,43 @@ cat wheel_led_colors ### 9.10 Official Lineage: x8070 ColorLedEffects / x8071 RGBEffects -LIGHTSYNC 0x807A/0x807B has no public documentation, but Logitech's +LIGHTSYNC 0x807A/0x807B has no public documentation. But Logitech's published x8070 (ColorLedEffects) and x8071 (RGBEffects) specs are its -clear conceptual ancestors. The packet layouts do NOT carry over -(function numbering, effect ID enumerations, and the RS50's 64-byte -very-long RGB frames are all different), but four concepts map -directly and reframe open questions in this section: +clear conceptual ancestors. The packet layouts do NOT carry over. +Function numbering, effect ID enumerations, and the RS50's 64-byte +very-long RGB frames are all different. But four concepts map directly. +They reframe open questions in this section: - **SW/FW ownership arbitration.** x8070 fn8 `setSwControl` ("SW takes control of the color and the effect") and x8071 fn5 `manageSwControl` ("disables all FW RGB clusters handling") are the - official concept behind 0x807A's fn6 (pre-config) + fn7 (enable) - being required before LED writes work. It also reframes the "First - Update Works, Subsequent Updates Don't" mystery of 9.3.2: if fn6 is - an ownership grab the firmware later reclaims, re-arbitrating before - every update - exactly what G Hub's per-change sequence does - is - the officially expected pattern, not a workaround. + official concept behind 0x807A's fn6 (pre-config) + fn7 (enable). + Those two are required before LED writes work. This also reframes the + "First Update Works, Subsequent Updates Don't" mystery of 9.3.2. If + fn6 is an ownership grab that the firmware later reclaims, then + re-arbitrating before every update is the officially expected + pattern, not a workaround. That is exactly what G Hub's per-change + sequence does. - **Custom slots.** 0x807B's 5 named slots correspond to x8071's effect 12 "Custom Onboard Stored" ("stored and played frame by frame at/from a memory chunk in the device", with a "several slots" - capability bit and per-slot state/defaults/UUID/name metadata) - - promoted from getInfo-multiplexing into a dedicated feature. + capability bit and per-slot state/defaults/UUID/name metadata). They + were promoted from getInfo-multiplexing into a dedicated feature. - **Direction vocabulary.** The RS50's directions 0-3 (L-to-R, R-to-L, inside-out, outside-in) match the official Color Wave direction - semantics (horizontal, reverse-horizontal, center-out, center-in), - differently encoded. + semantics (horizontal, reverse-horizontal, center-out, center-in). + They are encoded differently. - **The 9.3.2 fn1 response `00 02 01 03 04 05 06 07 08 09`**, previously labeled "zone IDs?", is byte 0 = zone/cluster index and - bytes 1..9 = the list of supported effect IDs - CONFIRMED live - 2026-07-02 by re-reading fn1 on the wheel. Effect IDs 1..9 exist: - 1-4 are the built-in animations and 5-9 are the five custom slots - (0x05 = CUSTOM 1 .. 0x09 = CUSTOM 5, decoded 2026-07-20); the - G Hub effect-change broadcasts carrying 6 and 9 were slot switches. - -x8071's `rgbClusterChangedEvent` DOES have a 0x807A equivalent, -confirmed across seven captures and now consumed by the driver: -`12ff00 ` (sw_id 0) fires on every effect change with + bytes 1..9 = the list of supported effect IDs. This was CONFIRMED live + 2026-07-02 by re-reading fn1 on the wheel. Effect IDs 1..9 exist. + 1-4 are the built-in animations. 5-9 are the five custom slots + (0x05 = CUSTOM 1 .. 0x09 = CUSTOM 5, decoded 2026-07-20). The + G Hub effect-change broadcasts that carried 6 and 9 were slot switches. + +x8071's `rgbClusterChangedEvent` DOES have a 0x807A equivalent. It was +confirmed across seven captures, and the driver now consumes it. +`12ff00 ` (sw_id 0) fires on every effect change, with the new effect ID as the single payload byte. The driver updates its led_effect cache and notifies wheel_led_effect pollers. @@ -1823,8 +1849,8 @@ led_effect cache and notifies wheel_led_effect pollers. ### 9.12 LIGHTSYNC Command Sequence -LIGHTSYNC requires a **specific 5-step sequence** using **both features** (0x0B and 0x0C). -fn6 (pre-config) and fn6/fn7 (commit/enable) must go to feature 0x0B, while RGB data goes to feature 0x0C. +LIGHTSYNC requires a **specific 5-step sequence** that uses **both features** (0x0B and 0x0C). +fn6 (pre-config) and fn6/fn7 (commit/enable) must go to feature 0x0B. RGB data goes to feature 0x0C. #### Command Sequence @@ -1839,16 +1865,16 @@ Step Feature Function Purpose Parameters ``` **Important Notes:** -- Step 1's effect value is `0x05 + slot` (see 9.3.2): selecting a custom +- Step 1's effect value is `0x05 + slot` (see 9.3.2). Selecting a custom slot IS selecting its effect number. There is NO separate "activate - slot" command - the `10 FF 0C 3C [slot]` frame earlier revisions listed - here as an "Activate slot" step is 0x807B fn3 GET_NAME, a pure read - (G Hub issues it as a read-back after switching; the driver's old - "activate" call did nothing). + slot" command. Earlier revisions listed the `10 FF 0C 3C [slot]` frame + here as an "Activate slot" step. That frame is 0x807B fn3 GET_NAME, a + pure read. G Hub issues it as a read-back after switching. The driver's + old "activate" call did nothing. - params[1] in the RGB config (byte 5) IS the animation direction, as a 1-4 wire value (see 9.4.1): 1=Inside-Out, 2=Outside-In, 3=L->R, 4=R->L. An - earlier note here claimed it "must be 0x03, not direction" - that was from - before the direction encoding was decoded and is incorrect. + earlier note here claimed it "must be 0x03, not direction". That note + predates the decoding of the direction encoding, and it is incorrect. - fn6/fn7 only work on feature 0x0B (0x807A), not on 0x0C (0x807B) #### Two-Feature Architecture @@ -1873,7 +1899,7 @@ Scoping note (2026-08-14, verified against the current driver): this fn7, and this whole sequence, belong to the **RGB slot path only** (`hidpp_dd_lightsync_enable()` at probe and the slot-upload flow below). The rev-light level path sends no fn7, no fn4 and no fn3 at -any point: its only traffic is the attach-time discovery reads and +any point. Its only traffic is the attach-time discovery reads and the bare fn2+fn6 level pair (see the section 9 intro). #### Color Change Sequence (runs for each update) @@ -1897,28 +1923,28 @@ All sysfs attributes (`wheel_led_colors`, `wheel_led_slot`, etc.) trigger this f The following features exist but are not yet implemented in the driver: -1. **In-game slot activation** - Can games trigger LED slot changes via HID++ or only via sysfs? -2. **Firmware update feature** - Standard HID++ devices often have a DFU feature (0x00C0 or similar). **DO NOT PROBE WRITE FUNCTIONS** on unknown features to avoid corrupting firmware. +1. **In-game slot activation** - Can games trigger LED slot changes via HID++, or only via sysfs? +2. **Firmware update feature** - Standard HID++ devices often have a DFU (device firmware update) feature (0x00C0 or similar). **DO NOT PROBE WRITE FUNCTIONS** on unknown features. A write could corrupt the firmware. -(Onboard profile / mode switching is implemented via feature 0x8137 - see -Section 5 - and exposed as the `wheel_profile` / `wheel_mode` attributes.) +(Onboard profile / mode switching is implemented via feature 0x8137 (see +Section 5). It is exposed as the `wheel_profile` / `wheel_mode` attributes.) > **SAFETY WARNING**: Some HID++ features may be related to firmware updates or critical -> device configuration. Always use GET (read-only) functions when probing unknown features. +> device configuration. Always use GET (read-only) functions when you probe unknown features. > Never blindly send SET commands to uncharacterized features. ### Note on Autocenter / Centering Spring The `autocenter` sysfs attribute (and the evdev `FF_AUTOCENTER` upload) drives a real driver-side centring spring. The driver stores the -magnitude, and its 1 kHz effect timer sums a position-fed centring force -on top of the game's own effects while the value is nonzero (firm within -roughly the central eighth of travel). A game that writes autocenter 0 -disables it for its session. - -The spring is computed host-side from the motor: these direct-drive -wheels have no separate hardware autocenter setting (G Hub exposes none), -and unlike belt/gear-driven wheels they produce centring force through the +magnitude. While the value is nonzero, its 1 kHz effect timer sums a +position-fed centring force on top of the game's own effects. The spring +is firm within roughly the central eighth of travel. A game that writes +autocenter 0 disables it for its session. + +The spring is computed host-side from the motor. These direct-drive +wheels have no separate hardware autocenter setting (G Hub exposes none). +Unlike belt/gear-driven wheels, they produce centring force through the motor directly. The same attribute backs Oversteer's autocenter control. --- @@ -1962,32 +1988,32 @@ Where `HH LL` is the 16-bit Page ID (e.g., 0x8138 for rotation range). ### Software ID (SW_ID) Behavior -The HID++ protocol uses a Software ID (SW_ID) in the lower nibble of the function byte to correlate requests with responses. G Hub uses SW_ID `0xB` (11), while the Linux driver uses SW_ID `0x0a` (it must not use `0x01`: the pedal sub-device silently drops requests carrying sw-id `0x01`). +The HID++ protocol uses a Software ID (SW_ID) in the lower nibble of the function byte. It correlates requests with responses. G Hub uses SW_ID `0xD` (13). The Linux driver uses SW_ID `0x0a`. It must not use `0x01`: the pedal sub-device silently drops requests that carry sw-id `0x01`. **Observed RS50 behavior:** - G Hub sends: `10 ff 00 0b 81 38 00` (function 0, SW_ID 11) - RS50 responds: `12 ff 00 0c 18 00 00...` (function 0, SW_ID echoed as 12?) -The RS50 appears to echo the SW_ID in responses, though some HID++ 2.0 devices may leave it as 0. The driver should handle both cases by comparing only the function index (upper nibble) when SW_ID is 0. +The RS50 appears to echo the SW_ID in responses. Some HID++ 2.0 devices may leave it as 0. The driver should handle both cases. When SW_ID is 0, compare only the function index (upper nibble). Official semantics (Logitech HID++ 2.0 draft specification, 2012-06-04) -confirm the observed behavior: the firmware must copy the software -identifier into the response but does not otherwise use it, and SW_ID 0 +confirm the observed behavior. The firmware must copy the software +identifier into the response, but it does not otherwise use it. SW_ID 0 is reserved ("do not use - allows to distinguish a notification from a -response"). This matches the capture census exactly: every unsolicited -packet - the `12ff1500 XXXX`-style settings broadcasts, profile and -rotation events - carries SW_ID 0 (officially "broadcast events"), -while responses echo the requester's SW_ID (G Hub runs parallel client -sessions on SW_IDs `a`..`e`, plus `f` for DFU checks; the Linux driver -is `1`). The same spec also states all request parameters must be -repeated in the response, which explains the echoed values in e.g. +response"). This matches the capture census exactly. Every unsolicited +packet carries SW_ID 0 (officially "broadcast events"). That includes the +`12ff1500 XXXX`-style settings broadcasts and the profile and rotation +events. Responses echo the requester's SW_ID. G Hub runs parallel client +sessions on SW_IDs `a`..`e`, plus `f` for DFU checks. The Linux driver +is `1`. The same spec also states that the response must repeat all +request parameters. That explains the echoed values in e.g. `10ff182d 0438` -> `12ff182d 0438`. ### HID++ Error Packets -Errors arrive as a response with feature index `0xFF` in byte 2, -followed by the failing feature index, the failing fn|sw byte, and an -error code (per the official 2.0 draft): 0 NoError, 1 Unknown, +Errors arrive as a response with feature index `0xFF` in byte 2. Next +come the failing feature index, the failing fn|sw byte, and an error +code (per the official 2.0 draft): 0 NoError, 1 Unknown, 2 InvalidArgument, 3 OutOfRange, 4 HWError, 5 "Logitech internal", 6 InvalidFeatureIndex, 7 InvalidFunctionId, 8 Busy, 9 Unsupported. The wheel uses this standard mechanism, including in very-long frames. @@ -2001,7 +2027,7 @@ Decoded examples from the captures: ### Alternative: FeatureSet Enumeration -Instead of querying ROOT.getFeatureIndex for each PAGE ID, G Hub uses FeatureSet (index 0x01) to enumerate all features: +G Hub does not query ROOT.getFeatureIndex for each PAGE ID. Instead, it uses FeatureSet (index 0x01) to enumerate all features: ``` Query FeatureSet.getFeatureID(index): @@ -2010,7 +2036,7 @@ Response: 12 ff 01 1X [pageID_hi] [pageID_lo] [type] ... ``` -This returns the PAGE ID at each index. G Hub queries indices 0x00 through ~0x1F to build the complete feature map. This is more efficient than individual ROOT queries because: +This returns the PAGE ID at each index. G Hub queries indices 0x00 through ~0x1F to build the complete feature map. This is more efficient than individual ROOT queries, because: 1. Single function call per index (vs. searching for each PAGE) 2. Discovers all features, including unknown/undocumented ones 3. Faster overall enumeration @@ -2018,28 +2044,28 @@ This returns the PAGE ID at each index. G Hub queries indices 0x00 through ~0x1F ### 12.3 Dynamic OLED (Feature 0x8130, DisplayGameData) > **Not the rev lights.** This wheel has two separate light-emitting -> surfaces, and they share nothing: +> surfaces. They share nothing: > > | | Where | Feature | Driver support | > |---|---|---|---| > | **Dynamic OLED** | the screen on the wheel **base** | `0x8130` (this section) | none | > | **Rev-light strip** | the 10 LEDs across the **rim** | `0x807A` (12.4, section 9) | `wheel_rev_level`, `wheel_led_*` | > -> The OLED is the same panel that shows the profile and settings menu -> referred to elsewhere in this document as "the wheel's OLED menu"; -> "Dynamic" is the role it plays when a game feeds it, not a second -> display. The rev strip is what `logi-tf-sim` drives from telemetry, and -> what the pit-limiter flash in 12.4 alternates. Nothing in this section -> reaches the strip, and nothing in 12.4 reaches the OLED. +> The OLED is the same panel that shows the profile and settings menu. +> Elsewhere in this document, that menu is called "the wheel's OLED menu". +> "Dynamic" is the role the panel plays when a game feeds it, not a second +> display. The rev strip is what `logi-tf-sim` drives from telemetry. It +> is also what the pit-limiter flash in 12.4 alternates. Nothing in this +> section reaches the strip, and nothing in 12.4 reaches the OLED. **Status: confirmed on hardware by a third party, not by this driver.** The driver neither sends nor exposes anything here. This section records what is -known so the next person does not start from the enumeration table again. +known, so the next person does not start from the enumeration table again. -The RS50's Dynamic OLED is driven through HID++ feature `0x8130`, which -enumerates at index `0x12` on this wheel. Reported by @PeposCJ in issue #20 -(2026-07-28), who reached the panel over that feature and displayed both -static text and live iRacing telemetry on it. +The RS50's Dynamic OLED is driven through HID++ feature `0x8130`. It +enumerates at index `0x12` on this wheel. @PeposCJ reported this in +issue #20 (2026-07-28). They reached the panel over that feature and +displayed both static text and live iRacing telemetry on it. **Functions** (@PeposCJ, 2026-07-30, RS50 hardware): @@ -2051,9 +2077,9 @@ static text and live iRacing telemetry on it. | 3 | set layout / data | The wheel reports **10 layouts, A to J**. Static and repeated writes are -both hardware-confirmed (@PeposCJ). Every layout's descriptor, read -first-hand from an RS50 here (2026-09-02, read-only fn1 sweep, feature at -index `0x12`, confirmed as `0x8130` through IFeatureSet): +both hardware-confirmed (@PeposCJ). The descriptor of every layout was +read first-hand from an RS50 here (2026-09-02, read-only fn1 sweep, +feature at index `0x12`, confirmed as `0x8130` through IFeatureSet): | index | layout | text fields (widths) | |---|---|---| @@ -2068,23 +2094,25 @@ index `0x12`, confirmed as `0x8130` through IFeatureSet): | 8 | I | 19, 10, 19, 10 | | 9 | J | 19, 10, 19, 10 | -fn0 answered `0x0a`, ten, matching. A G PRO fn1 sweep (@Mhytee, 2026-08-06) -matches this table on all ten layouts, counts and widths identical. +fn0 answered `0x0a`, ten, which matches. A G PRO fn1 sweep (@Mhytee, +2026-08-06) matches this table on all ten layouts. Counts and widths are +identical. -**fn3, validated on hardware** (@Mhytee on a G PRO, layouts F to J driven -since 2026-08-06 and shipped in TF4ALL; A to E from @PeposCJ's working -writer and gallery record; both sources corroborate each other's numbers -wherever they overlap. Posted in issue #75, 2026-09-02). Every setter is -the 64-byte VERY_LONG report, layout byte first: +**fn3, validated on hardware.** @Mhytee drove layouts F to J on a G PRO +from 2026-08-06, and they shipped in TF4ALL. Layouts A to E come from +@PeposCJ's working writer and gallery record. Both sources corroborate +each other's numbers wherever they overlap. Posted in issue #75, +2026-09-02. Every setter is the 64-byte VERY_LONG report, layout byte +first: ``` 12 ff 3 ``` -Text is ASCII, left aligned, fixed width, packed back to back; spaces are -content; zero padding after the last field is fine. Firmware behaviour on -non-printable bytes is uncharacterised (TF4ALL clamps to space). Payload -offsets count the report ID as byte 0: +Text is ASCII, left aligned, fixed width, and packed back to back. Spaces +are content. Zero padding after the last field is fine. Firmware behaviour +on non-printable bytes is uncharacterised (TF4ALL clamps to space). +Payload offsets count the report ID as byte 0: | layout | payload | |---|---| @@ -2099,145 +2127,148 @@ offsets count the report ID as byte 0: | I (8) | bytes 5-23, 24-33, 34-52, 53-62 = 19/10/19/10; rows 2 and 4 larger, right-aligned | | J (9) | same offsets as I; every row centred | -The gauge's unfilled remainder is a diagonal-stripe background that the -fill replaces left to right. G is the classic gear-and-speed screen: a -very large one-character slot, a firmware-drawn separator, a medium -three-character value; F is its mirror. Those two carry the panel's +The gauge's unfilled remainder is a diagonal-stripe background. The fill +replaces it left to right. G is the classic gear-and-speed screen: a very +large one-character slot, a firmware-drawn separator, and a medium +three-character value. F is its mirror. Those two carry the panel's largest font (37 px), which exists nowhere else. **Two traps in "build frames from the descriptor".** fn1's capability -bytes describe text fields only: D and E also take two normalised value -bytes, and those come *first* in the payload, so a writer that starts +bytes describe text fields only. D and E also take two normalised value +bytes, and those come *first* in the payload. So a writer that starts text at byte 5 with the descriptor's widths corrupts D's gauge with the label's first two characters. And the descriptor lists fields left to -right *as drawn*, not in payload order; E is the one layout where the two -differ. Descriptor widths are trustworthy, descriptor order is not, and -D/E need their value bytes prepended. +right *as drawn*, not in payload order. E is the one layout where the two +differ. Descriptor widths are trustworthy. Descriptor order is not. D/E +need their value bytes prepended. -**I versus J** have identical descriptors and different rendering: I -right-aligns its two large rows, J centres every row. Only a write tells +**I versus J** have identical descriptors and different rendering. I +right-aligns its two large rows. J centres every row. Only a write tells them apart. **Two-zone rule.** The wide large rows (H's lower row, I's large rows) -draw the first character pinned to the left edge and the remainder -right-aligned: "112%" draws "1" left and "12%" right with a gap, on a -correctly described single field. Spaces steer it: a leading space skips -the left zone for a clean right-aligned value, trailing spaces pull it -back, character-exact. Used deliberately that is a one-character value -left and a longer one right on one row. In F and G padding moves nothing. -No large-font layout centres, so J's 18 px rows are the largest centred -text the panel produces. - -**The panel does not hold a frame.** When the host goes quiet the -firmware drops the Dynamic surface back to the wheel's own menu; the +draw the first character pinned to the left edge. They draw the remainder +right-aligned. So "112%" draws "1" left and "12%" right with a gap, on a +correctly described single field. Spaces steer it. A leading space skips +the left zone, which gives a clean right-aligned value. Trailing spaces +pull it back, character-exact. Used deliberately, that gives a +one-character value left and a longer one right on one row. In F and G, +padding moves nothing. No large-font layout centres. So J's 18 px rows are +the largest centred text the panel produces. + +**The panel does not hold a frame.** When the host goes quiet, the +firmware drops the Dynamic surface back to the wheel's own menu. The timeout is under two seconds (a 2 s refresh visibly flickered back to the -menu between frames). An unchanged frame must still be resent; TF4ALL -resends at 50 Hz and the panel is stable. A driver therefore needs a -refresh tick, not only write coalescing. **fn2 is the immediate handback**: -without it the wheel reclaims its screen only after that timeout. +menu between frames). An unchanged frame must still be resent. TF4ALL +resends at 50 Hz, and the panel is stable. A driver therefore needs a +refresh tick, not only write coalescing. **fn2 is the immediate handback.** +Without it, the wheel reclaims its screen only after that timeout. **The feature ends at fn3.** fn4 through fn15 answer HID++ error `0x07` -INVALID_FUNCTION_ID on a G PRO; there is no claim-the-display call. +INVALID_FUNCTION_ID on a G PRO. There is no claim-the-display call. **Verified here, first-hand** (RS50, base firmware U1 65.04.B0039, -2026-09-03, watched): the fn3 frame above is accepted at the dynamically -resolved index; layout J drew four rows, the second and fourth larger, all -centred; layout G drew the very large gear digit with the three-character -value beside it; layout H drew `112%` on its lower row as `1` pinned left -and `12%` right with a gap, which is the two-zone rule; and fn2 returned -the wheel's own menu immediately each time. Held at 20 Hz for the viewing, -and stable at that rate. - -A cheaper first-hand probe than a watched write: fill bytes 5..63 with -distinct printable characters (a ruler frame) and the panel labels its -own offsets, one frame per layout. A full-width ruler masks the two-zone -rule, which needed a short real value such as "112%" to expose. +2026-09-03, watched). The fn3 frame above is accepted at the dynamically +resolved index. Layout J drew four rows, the second and fourth larger, all +centred. Layout G drew the very large gear digit with the three-character +value beside it. Layout H drew `112%` on its lower row as `1` pinned left +and `12%` right with a gap, which is the two-zone rule. fn2 returned the +wheel's own menu immediately each time. The frames were held at 20 Hz for +the viewing, and the panel was stable at that rate. + +There is a cheaper first-hand probe than a watched write. Fill bytes +5..63 with distinct printable characters (a ruler frame). The panel then +labels its own offsets, one frame per layout. A full-width ruler masks the +two-zone rule. That rule needed a short real value such as "112%" to +expose. Still unknown, at both ends: the 12.5 mechanism, the exact hold timeout, firmware behaviour on non-printable bytes, and features 0x18A2, 0x18B1 and 0x9315. -**fn1 is self-describing** (@WnDTech's tester, RS50 hardware, 2026-08-15): -requesting the descriptor for layout index 9 answers +**fn1 is self-describing** (@WnDTech's tester, RS50 hardware, 2026-08-15). +A request for the descriptor of layout index 9 answers ``` 12 FF 12 1A 09 0A 13 0A 13 0A 00 ... ``` -payload `[requested layout index][one-based layout ID][four capability -bytes]`. So `09` is the index asked for, `0A` is layout ID 10 (layout J), -and `13 0A 13 0A` are the four field widths 19 / 10 / 19 / 10. A client -can build frames from the descriptor instead of hardcoding per-layout -widths. +with payload `[requested layout index][one-based layout ID][four +capability bytes]`. So `09` is the index asked for. `0A` is layout ID 10 +(layout J). `13 0A 13 0A` are the four field widths 19 / 10 / 19 / 10. A +client can build frames from the descriptor instead of hardcoding +per-layout widths. -The apparent fifth capacity entry was the layout ID being read as a -width: decoded by @PeposCJ from the RS50's own firmware handler and -confirmed against the same readback (issue #20, 2026-08-31). There are -four text fields, not five. The fn3 frame byte order was then validated -on an RS50 here (2026-09-02): the per-layout table above is what the -panel drew, including the two traps and the two-zone rule. +The apparent fifth capacity entry was the layout ID, read as a width. +@PeposCJ decoded this from the RS50's own firmware handler and confirmed +it against the same readback (issue #20, 2026-08-31). There are four text +fields, not five. The fn3 frame byte order was then validated on an RS50 +here (2026-09-02). The per-layout table above is what the panel drew, +including the two traps and the two-zone rule. **Read that run's "collision retry" carefully.** 0x8130 appeared at index -0x12 only on a second attempt, which looks like the wheel handing out a -colliding index and is more likely to be a mismatched answer. A Root -getFeature response does not echo the feature ID it was asked about, so -every such query looks identical on the wire, and a late answer to one -query is indistinguishable from the answer to the next. @PeposCJ reports -that exact failure being reproduced elsewhere, an OLED discovery answer -latched as the rev-light index. Resolve the index dynamically, never -assume it, and treat a discovery answer as suspect unless the request it -belongs to is still the one outstanding. +0x12 only on a second attempt. That looks like the wheel handing out a +colliding index. It is more likely a mismatched answer. A Root getFeature +response does not echo the feature ID it was asked about. So every such +query looks identical on the wire. A late answer to one query cannot be +told apart from the answer to the next. @PeposCJ reports that exact +failure reproduced elsewhere: an OLED discovery answer latched as the +rev-light index. Resolve the index dynamically. Never assume it. Treat a +discovery answer as suspect unless the request it belongs to is still the +one outstanding. **It is a typed renderer, not a framebuffer.** The firmware holds a 128x64 -monochrome buffer, but no `0x8130` command accepts framebuffer bytes, +monochrome buffer. But no `0x8130` command accepts framebuffer bytes, coordinates, pixels or partial regions. Each layout exposes bounded text -fields and normalised values, and the firmware draws them: +fields and normalised values. The firmware draws them: ``` host -> typed Layout A-J data -> firmware renderer -> framebuffer -> OLED ``` So a driver-side interface for this would be a small set of typed fields per -layout, not a bitmap surface. That rules out the character-device interface a -framebuffer would have implied. +layout, not a bitmap surface. That rules out the character-device interface +that a framebuffer would have implied. -**Transport: interface 1, endpoint 0, HID SET_REPORT.** Deliberately not -Logitech's DirectInput Escape path. That path reaches the panel, but its +**Transport: interface 1, endpoint 0, HID SET_REPORT.** This is deliberately +not Logitech's DirectInput Escape path. That path reaches the panel. But its exclusive Acquire/Unacquire lifecycle emits `RESET_ALL`, -`SET_GLOBAL_GAINS(0xFFFF)`, `RESET_ALL` on `0x8123`, which killed iRacing's +`SET_GLOBAL_GAINS(0xFFFF)`, `RESET_ALL` on `0x8123`. That killed iRacing's shift LEDs and centre feel until the game rebuilt its wheel state. Do not use it. **Safety: not settled, and the caveat is sharper than it looks.** See 12.5. -Coexistence has been observed but only in the one case where the endpoint -happens to be quiet: iRacing has native TrueForce, so it carries steering -force in `cur` on the TrueForce stream and never writes force to HID++. Five -writes at 1 Hz rendered and acknowledged while TrueForce ran at ~1000 -submissions/sec, with no observable disturbance, car stationary in the pits. -That is not evidence that OLED writes are safe in a title that does write -force to HID++, and 12.5 gives reason to expect they are not. +Coexistence has been observed, but only in the one case where the endpoint +happens to be quiet. iRacing has native TrueForce. So it carries steering +force in `cur` on the TrueForce stream, and it never writes force to HID++. +Five writes at 1 Hz rendered and were acknowledged while TrueForce ran at +~1000 submissions/sec. There was no observable disturbance, with the car +stationary in the pits. That is not evidence that OLED writes are safe in a +title that does write force to HID++. 12.5 gives reason to expect they are +not. **Related undecoded candidates.** An earlier round of enumeration flagged `0x18A2`, `0x18B1` and `0x9315` as the interesting unknowns on `dev_idx -0x01`. The OLED turned out not to be any of them, so they remain unexplained +0x01`. The OLED turned out not to be any of them. So they remain unexplained rather than ruled out. ### 12.4 Rev-light stream: attach-time discovery reads, acknowledgements and flashing This section is entirely about the **rim's 10-LED rev strip**, feature -`0x807A`. It has nothing to do with the base's OLED screen (12.3): the two -are different hardware on different features, and no command here reaches -the display. +`0x807A`. It has nothing to do with the base's OLED screen (12.3). The two +are different hardware on different features. No command here reaches the +display. -From four first-party G Hub/iRacing captures contributed by @PeposCJ in -issue #20 (2026-07-27). These settled three questions and found one bug. +The source is four first-party G Hub/iRacing captures that @PeposCJ +contributed in issue #20 (2026-07-27). They settled three questions and +found one bug. -**Attach-time discovery reads** (this used to be called an "arm sequence"; -2026-08-14 hardware work settled that nothing here arms anything - they are -plain reads, done once at wheel attach, and the strip renders bare fn2+fn6 -levels from the onboard power-on state without them). After `0x807A` -resolves to its runtime index, G Hub sends fn0, fn1, fn2, then fn0 again, -and only then begins the fn2 + fn6 stream: +**Attach-time discovery reads.** This used to be called an "arm sequence". +Hardware work on 2026-08-14 settled that nothing here arms anything. They +are plain reads, done once at wheel attach. The strip renders bare fn2+fn6 +levels from the onboard power-on state without them. After `0x807A` +resolves to its runtime index, G Hub sends fn0, fn1, fn2, then fn0 again. +Only then does it begin the fn2 + fn6 stream: ``` 10 ff 00 0c 80 7a 00 -> 12 ff 00 0c 0b 00 00 resolve 0x807A to index 0x0B @@ -2248,71 +2279,74 @@ and only then begins the fn2 + fn6 stream: 11 ff 0b 6c ... then the fn2 + fn6 stream ``` -This driver used to send an extra `fn3` with parameter 2 that G Hub never -sends. `fn3` is SET_EFFECT, so it switched the wheel to effect 2 and -destroyed whatever LIGHTSYNC effect the user had configured, which the -driver then papered over by snapshotting and restoring the lighting. Both -the stray write and its workaround were removed in v0.21.0 (`75090ad`). The -sequence above is the first-party evidence that settled it; the `fn3` came +This driver used to send an extra `fn3` with parameter 2. G Hub never +sends it. `fn3` is SET_EFFECT, so it switched the wheel to effect 2. That +destroyed whatever LIGHTSYNC effect the user had configured. The driver +then papered over it by snapshotting and restoring the lighting. Both the +stray write and its workaround were removed in v0.21.0 (`75090ad`). The +sequence above is the first-party evidence that settled it. The `fn3` came from a third-party capture. **Acknowledgements.** Every write draws a `0x12` response. Over 301 short -plus 301 long writes the pattern held without exception: `0x10` fn2 answered -in ~2.49 ms median, then ~0.15 ms later `0x11` fn6 answered in ~2.85 ms -median. Consistent with flow control rather than fire-and-forget. +plus 301 long writes, the pattern held without exception. `0x10` fn2 was +answered in ~2.49 ms median. Then, ~0.15 ms later, `0x11` fn6 was answered +in ~2.85 ms median. This is consistent with flow control rather than +fire-and-forget. -**Redline.** Only `LL = 0..10` is ever used. At redline the stream simply -keeps sending `LL = 10` at ~60 Hz. There is no value above `0x0A`, and no -separate flash command or alternate function. +**Redline.** Only `LL = 0..10` is ever used. At redline, the stream simply +keeps sending `LL = 10` at ~60 Hz. There is no value above `0x0A`. There is +no separate flash command or alternate function. **Pit-limiter flash.** iRacing's full-strip flash is not a device effect at -all: it is `LL = 10` and `LL = 0` alternating at ~416.7 ms, about 1.2 Hz, +all. It is `LL = 10` and `LL = 0` alternating at ~416.7 ms, about 1.2 Hz, over the same fn2/fn6 pair. A telemetry feeder can therefore reproduce it -without any new protocol support, which is why it lives in `logi-tf-sim` +without any new protocol support. That is why it lives in `logi-tf-sim` rather than the driver. -Reproduced on an RS50 on 2026-07-29, from synthetic OutGauge packets rather -than a game: 28 transitions across 12 seconds, strictly `10` and `0`, mean -gap 418 ms against the captured 417 ms. The rev level the same RPM would -otherwise show (`5`, held steady throughout a control run) never appeared, -confirming the limiter overrides the rev display entirely rather than -blending with it. So a Windows behaviour was reproduced on Linux to within -measurement noise from the capture alone, with no vendor documentation. +It was reproduced on an RS50 on 2026-07-29, from synthetic OutGauge packets +rather than a game: 28 transitions across 12 seconds, strictly `10` and +`0`, mean gap 418 ms against the captured 417 ms. The rev level that the +same RPM would otherwise show (`5`, held steady throughout a control run) +never appeared. This confirms that the limiter overrides the rev display +entirely rather than blending with it. So a Windows behaviour was +reproduced on Linux to within measurement noise, from the capture alone, +with no vendor documentation. ### 12.5 HID++ endpoint contention: a non-force write cuts live force -Third-party finding (@Mhytee / TF4ALL, 2026-07-30, corroborated by -@PeposCJ's independent OLED captures in issue #20). Observation, not -mechanism: nobody has established why. +This is a third-party finding (@Mhytee / TF4ALL, 2026-07-30). @PeposCJ's +independent OLED captures in issue #20 corroborate it. It is an +observation, not a mechanism. Nobody has established why. **While any force is present on the HID++ endpoint, a write to that endpoint -which is not force appears to cut the force.** Regardless of who sends it, -how small it is, or how gently it is paced. Rev-light writes on `0x807A` -during a game's DirectInput force were the original case, on Windows with a -G PRO. Pacing was tuned down to a 60 ms floor and fixed nothing. +which is not force appears to cut the force.** This holds regardless of who +sends it, how small it is, or how gently it is paced. The original case was +rev-light writes on `0x807A` during a game's DirectInput force, on Windows +with a G PRO. Pacing was tuned down to a 60 ms floor and fixed nothing. Two things it is *not*: - **Not a multiple-writers problem.** Two independent programs writing the - endpoint at once disturbed nothing, and one program doing both force and + endpoint at once disturbed nothing. One program doing both force and LEDs still dropped out. - **Not solved by cadence.** See above. -The only configuration where it stops is force carried on the TrueForce -stream with the HID++ endpoint kept completely force-free. +It stops in only one configuration: force carried on the TrueForce stream, +with the HID++ endpoint kept completely force-free. **"Ignored is not the same as absent."** This is the part that took longest -to see, and the part most likely to mislead a reading of a capture. While the -TrueForce stream carries force, the wheel obeys `cur` and appears to ignore -force sent to HID++, so the endpoint looks free. It is not: the game's writes -are still on the wire and still break things until they actually stop. +to see. It is also the part most likely to mislead a reading of a capture. +While the TrueForce stream carries force, the wheel obeys `cur`. It appears +to ignore force sent to HID++, so the endpoint looks free. It is not. The +game's writes are still on the wire, and they still break things until they +actually stop. -So a quiet-looking endpoint proves only that the current title has native -TrueForce and never writes force there. +So a quiet-looking endpoint proves only one thing: the current title has +native TrueForce and never writes force there. **Unexplained counter-evidence.** In a capture of Logitech's own stack, `0x8123` force pairs interleave with `0x807A` rev-light updates as close as -37 ms apart with no measurable degradation: +37 ms apart, with no measurable degradation: ``` FFB inter-packet gaps near an LED write : median 3.00 ms p99 15 ms max 107 ms @@ -2322,37 +2356,37 @@ FFB inter-packet gaps away from LED writes : median 3.01 ms p99 240 ms max 969 No third party has reproduced that. Whatever Logitech does to make them coexist is not known. -**What this means for this driver.** Mostly nothing today, and that is worth -stating explicitly so it is not mistaken for a latent bug: +**What this means for this driver.** Mostly nothing today. That is worth +stating explicitly, so it is not mistaken for a latent bug: - **Direct-drive wheels are not exposed to THIS interference class.** Their - force rides endpoint `0x03`, not HID++, so `wheel_led_*` and the rev-level - writes never compete with force on the same endpoint. Games cannot put - force there either: force reaches the wheel through this driver, which - sends it to `0x03`. They turned out to have an interference class of - their own, though (hardware, 2026-08-14): while a **native TrueForce SDK - session** is live, the driver's old rev-LED form - arm burst plus - per-level fn3 - killed the session at init and killed wheel input - mid-session. The fix was making the driver speak exactly what G HUB - speaks: bare fn2+fn6 levels, no arming (commit `9d4b68a`). In that form, - base FFB + TrueForce texture + telemetry LEDs are hardware-validated - running together. + force rides endpoint `0x03`, not HID++. So `wheel_led_*` and the + rev-level writes never compete with force on the same endpoint. Games + cannot put force there either. Force reaches the wheel through this + driver, which sends it to `0x03`. They turned out to have an + interference class of their own, though (hardware, 2026-08-14). While a + **native TrueForce SDK session** is live, the driver's old rev-LED form + (arm burst plus per-level fn3) killed the session at init. It also + killed wheel input mid-session. The fix was to make the driver speak + exactly what G HUB speaks: bare fn2+fn6 levels, no arming (commit + `9d4b68a`). In that form, base FFB + TrueForce texture + telemetry LEDs + are hardware-validated running together. - **The PlayStation G923 is not exposed.** Its force is the classic engine's - plain HID output reports, and its rev LEDs are `led_classdev` entries - driven by the same engine. Neither is HID++. -- **The G923 Xbox edition is the one wheel where this could bite**, because - its force genuinely does ride HID++ `0x8123`. It has `0x807A` in its - feature map, so rev lights are *technically* reachable. Today this driver - exposes no LED surface for it at all: the `led_classdev` entries come from - the classic engine it does not use, and `wheel_led_*` belongs to the - direct-drive path it does not use either. + plain HID output reports. Its rev LEDs are `led_classdev` entries driven + by the same engine. Neither is HID++. +- **The G923 Xbox edition is the one wheel where this could bite.** Its + force genuinely does ride HID++ `0x8123`. It has `0x807A` in its feature + map, so rev lights are *technically* reachable. Today this driver + exposes no LED surface for it at all. The `led_classdev` entries come + from the classic engine, which it does not use. `wheel_led_*` belongs to + the direct-drive path, which it does not use either. ### 0x807A rev level: the 4th parameter is a denominator (hardware-measured) -Measured on an RS50 on 2026-08-10, with the strip switched to Left-to-Right -so a fill reads as a count from one end rather than closing in from both -(Outside-In makes the two cases below look nearly identical, which cost one -inconclusive round): +Measured on an RS50 on 2026-08-10. The strip was switched to Left-to-Right, +so a fill reads as a count from one end rather than closing in from both. +(Outside-In makes the two cases below look nearly identical. That cost one +inconclusive round.) | count | level | LEDs lit | |---|---|---| @@ -2361,50 +2395,50 @@ inconclusive round): | **5** | **5** | **10** | The third row settles it. If the level were a raw LED count, `5` would light -five. It lights the whole strip, so the level is a fraction of the count: -the 4th parameter is the denominator, and the wheel scales the fill to its +five. It lights the whole strip. So the level is a fraction of the count. +The 4th parameter is the denominator, and the wheel scales the fill to its own strip. **But the two wheels do not treat a wrong denominator the same.** The RS50 -accepts `0a` and `05` and lights for both. The G923 Xbox edition lit nothing -at all for `0a` across five framings (issue #27), while Windows drives it +accepts `0a` and `05`, and it lights for both. The G923 Xbox edition lit +nothing at all for `0a` across five framings (issue #27). Windows drives it with `05`, which is that wheel's real LED count. So on the RS50 the value -only scales the fill, and on the Xbox G923 it appears to be validated. That -asymmetry is unexplained and worth remembering: do not conclude from the +only scales the fill. On the Xbox G923 it appears to be validated. That +asymmetry is unexplained and worth remembering. Do not conclude from the RS50's tolerance that the field is cosmetic. -The rule either way is the same, and it is what Windows does: send the -wheel's actual LED count, ten for the direct-drive wheels and five for a +The rule either way is the same, and it is what Windows does. Send the +wheel's actual LED count: ten for the direct-drive wheels, and five for a G923. **Superseded 2026-08-10 by a capture of that wheel (issue #27).** Its rev -lights are driven over `0x807A` after all, with `fn2`+`fn6` pairs, and the -reason ours never lit is a single parameter: the level command states the -strip length, and the G923 has **five** LEDs where the direct-drive wheels -have ten. This project sent `0a` to every wheel. The same capture shows that -wheel's force arriving on the `0xFFFD` stream rather than HID++, so the +lights are driven over `0x807A` after all, with `fn2`+`fn6` pairs. The +reason ours never lit is a single parameter. The level command states the +strip length. The G923 has **five** LEDs where the direct-drive wheels have +ten. This project sent `0a` to every wheel. The same capture shows that +wheel's force arriving on the `0xFFFD` stream rather than HID++. So the endpoint-contention argument below does not apply to its rev lights. **Consequence for future work:** adding rev-light support to the G923 Xbox -edition is not a matter of wiring up `0x807A`. On that wheel it would be -writing non-force to the same endpoint its force arrives on, which is exactly -the configuration described above. It would need force moved off HID++ first, -or evidence that this wheel behaves differently from the G PRO the finding -came from. +edition is not a matter of wiring up `0x807A`. On that wheel, it would mean +writing non-force to the same endpoint its force arrives on. That is exactly +the configuration described above. It would need force moved off HID++ +first. Or it would need evidence that this wheel behaves differently from +the G PRO the finding came from. ### 12.6 Dual clutch (Feature 0x8127, DualClutch) -Decoded by @fsfarmscaper on a G923 Xbox edition (`046d:c26e`, firmware -139.2.50, feature index `0x11`) by listening on the feature index while a +@fsfarmscaper decoded this on a G923 Xbox edition (`046d:c26e`, firmware +139.2.50, feature index `0x11`). They listened on the feature index while a person worked the wheel, with G HUB not running ([#97](../../issues/97), -logs attached there). Not verified by this driver, which has no wheel with a -dual clutch to hand. One wheel, one firmware: the page is also reported on -the RS50 and the PS G923 and nothing below has been checked on either. +logs attached there). This driver has not verified it: no wheel with a dual +clutch is to hand. One wheel, one firmware. The page is also reported on the +RS50 and the PS G923, and nothing below has been checked on either. **The host only reads.** The wheel configures the feature from on-wheel button combinations and reports the result. Writes to `fn2` and `fn3` are -acknowledged and change nothing (28 across two sessions), so on this page an -acknowledged write is not an applied one. **The setting persists**: after +acknowledged and change nothing (28 across two sessions). So on this page, +an acknowledged write is not an applied one. **The setting persists.** After mains and USB were both pulled for ten seconds, `fn2` read back the saved paddle and bite point unchanged (run 4). @@ -2423,41 +2457,42 @@ with the same fields plus a mode byte: 12 ff 11 00 | 00 ``` -`mode` is `02` while in setting mode and `00` on exit and save. Byte 5 -(`n`) is mostly `01`, with `00` in the second of a pair when the wheel sends -two frames ten milliseconds apart (the Reset below, the first pair on -entering setting mode); not identified. The wheel also sends one such -report, mode `00` with the saved values, a few seconds after the HID++ -handle opens (runs 2 and 4), so a host that listens from connect learns the -state without asking. - -**Reset** (both paddles plus X) is not a full clear: it disables the feature -and returns the bite point to 100 but keeps the paddle assignment, `01 01 50` -becoming `00 01 64` (run 5, two events ten milliseconds apart). Runs 2 -and 3 both show the entry into setting mode itself: `01 ff 64 00 01 01`, -paddle `ff` (unassigned) and bite point back at 100 with mode `01`, a few -seconds before the first mode-`02` event. The simplest reading is that -entering setup resets both fields for the session, mode `01` being the -entry state; the link is by timing only, since the moment of entry was not -marked in the log. The saved value itself survives (run 4 above); it is -the next setup entry that starts over from 100. Whether `fn2` byte 1 `00` -can also mean "unassigned" (the entry event carries `ff`) is not -separated. - -**On the wheel** (all without host involvement): hold both paddles plus LSB -and RSB for about two seconds to enter setup (rev LEDs blue, slow flash); -press LSB or RSB to assign the paddle (LEDs flash red); clutch and -accelerator down, then `+` or `-` to move the bite point, one event per -press, 100 is the ceiling; Select (dial centre) exits and saves (LEDs flash -green to blue); both paddles plus X resets (all rev LEDs on, then off in -sequence). `0x807A` `fn2` and `fn7` were unchanged throughout, so the page -does not touch the rev-light state. +`mode` is `02` while in setting mode, and `00` on exit and save. Byte 5 +(`n`) is mostly `01`. It is `00` in the second of a pair when the wheel +sends two frames ten milliseconds apart (the Reset below, and the first +pair on entering setting mode). It is not identified. The wheel also sends +one such report a few seconds after the HID++ handle opens, with mode `00` +and the saved values (runs 2 and 4). So a host that listens from connect +learns the state without asking. + +**Reset** (both paddles plus X) is not a full clear. It disables the feature +and returns the bite point to 100, but it keeps the paddle assignment: +`01 01 50` becomes `00 01 64` (run 5, two events ten milliseconds apart). +Runs 2 and 3 both show the entry into setting mode itself: `01 ff 64 00 01 +01`, paddle `ff` (unassigned) and bite point back at 100, with mode `01`, a +few seconds before the first mode-`02` event. The simplest reading is that +entering setup resets both fields for the session, with mode `01` as the +entry state. The link is by timing only, since the moment of entry was not +marked in the log. The saved value itself survives (run 4 above). It is the +next setup entry that starts over from 100. Whether `fn2` byte 1 `00` can +also mean "unassigned" (the entry event carries `ff`) is not separated. + +**On the wheel** (all without host involvement): + +1. Hold both paddles plus LSB and RSB for about two seconds to enter setup (rev LEDs blue, slow flash). +2. Press LSB or RSB to assign the paddle (LEDs flash red). +3. Press the clutch and accelerator down, then press `+` or `-` to move the bite point. There is one event per press. 100 is the ceiling. +4. Press Select (dial centre) to exit and save (LEDs flash green to blue). +5. To reset, press both paddles plus X (all rev LEDs on, then off in sequence). + +`0x807A` `fn2` and `fn7` were unchanged throughout. So the page does not +touch the rev-light state. **Method, worth reusing.** Two sessions of writing to the page produced -nothing; one session of listening for unsolicited reports while someone -performed the real on-device action, diffing the registers before and -after, produced the layout above. Other pages that look inert may yield to -the same approach. +nothing. One session of listening for unsolicited reports, while someone +performed the real on-device action, produced the layout above. The +registers were diffed before and after. Other pages that look inert may +yield to the same approach. --- diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 8772870..98a3af1 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,44 +1,50 @@ # Roadmap -Where the project is going, in the order it intends to get there. Dates are -deliberately absent: the work is driven by what owners of the hardware can -test, and that is not on a schedule. The current state of every wheel and -every game is in [STATUS.md](STATUS.md); this page is about what changes. +This page lists where the project goes next, in order. It gives no dates. +Owners of the hardware drive the work by what they can test, and that is +not on a schedule. [STATUS.md](STATUS.md) gives the current state of every +wheel and every game. This page is about what changes. ## Toward 1.0 1.0 means the RS50, the G PRO and both G923 editions work as this project -documents them, on the distributions it packages for, without steps the -documentation does not mention. What still stands between here and there: - -1. **G PRO force feedback and TrueForce verified on the wire.** The - configuration protocol is confirmed; the force stream has only been - inferred from RS50 captures. One owner's capture closes this (#8). +documents them. They must work on the distributions the project packages +for. They must need no steps the documentation does not mention. These +items still stand in the way: + +1. **G PRO force feedback and TrueForce verified on the wire.** TrueForce + is Logitech's high-rate haptic stream, which adds texture to the force. + The configuration protocol is confirmed. The force stream is only + inferred from RS50 captures (recordings of USB traffic). One owner's + capture closes this item (#8). 2. **G923 Xbox edition parity with Windows.** The SDK route works end to - end as of 0.41.0; whether every TrueForce effect the Windows stack - renders reaches the wheel is open, and the comparison capture is the - instrument (#83). + end as of 0.41.0. The SDK is Logitech's library that a game loads to + talk to the wheel. We do not know if every TrueForce effect the Windows + stack renders reaches the wheel. A comparison capture is the instrument + (#83). 3. **The force engine's condition effects calibrated by measurement**, not - by feel, against the firmware's own rendering, using the timed-travel - method an owner established (#87). + by feel. The reference is the firmware's own rendering. The method is + the timed-travel method an owner established (#87). 4. **A second maintainer.** The project's bus factor is one. See [GOVERNANCE.md](../GOVERNANCE.md) for how that changes. ## Next -- **Test coverage measured in CI** and reported, so the number in the - documentation is a fact rather than an estimate, and the parts that need - hardware are named as such. +- **Test coverage measured in CI** and reported. CI is the automated check + that runs on every change. Then the number in the documentation is a + fact, not an estimate, and the parts that need hardware are named as + such. - **The three Windows binaries built by the packages rather than - committed**, once every packaging channel can build them offline; until - then they are byte-verified against their source in CI. + committed.** This waits until every packaging channel can build them + offline. Until then, CI verifies them byte for byte against their source. - **The unused wheel features** (`DUAL_CLUTCH`, `GAMING_ATTACHMENTS`, - `AXIS_MAPPING`), each of which needs a capture of Logitech's software - using it before it can be driven safely alongside live force. + `AXIS_MAPPING`). Each needs a capture of Logitech's software using it. + Only then can the driver use it safely next to live force. - **AC Rally telemetry**, once the game publishes any. ## Not planned -- Support for wheels outside Logitech's HID++ TrueForce family; the - in-tree drivers and new-lg4ff cover the older ones. -- A graphical installer; the packages and `tools/setup.sh` are the install. +- Support for wheels outside Logitech's HID++ TrueForce family. HID++ is + Logitech's configuration protocol over USB. The in-tree drivers and + new-lg4ff cover the older wheels. +- A graphical installer. The packages and `tools/setup.sh` are the install. diff --git a/docs/SCS_PLUGIN.md b/docs/SCS_PLUGIN.md index c272096..dc517b8 100644 --- a/docs/SCS_PLUGIN.md +++ b/docs/SCS_PLUGIN.md @@ -1,37 +1,53 @@ # Simulated TrueForce in Euro Truck Simulator 2 and American Truck Simulator -These two publish telemetry through their own plugin interface rather than -over UDP, so `logi-tf-sim` cannot see them the way it sees Automobilista 2 or -DiRT Rally. `logi-tf-scs` is a small plugin that runs inside the game and -forwards engine speed, throttle and gear to the daemon, which then drives the -wheel exactly as it does for the UDP titles. +These two games publish telemetry through their own plugin interface, not +over UDP. (Telemetry is the live data a game publishes about the vehicle. UDP +is a simple network protocol. The game sends packets to a port.) So +`logi-tf-sim`, the daemon that turns telemetry into haptics, cannot see them +the way it sees Automobilista 2 or DiRT Rally. `logi-tf-scs` is a small +plugin that runs inside the game. It forwards engine speed, throttle and gear +to the daemon. The daemon then drives the wheel exactly as it does for the +UDP titles. It is a native Linux plugin. No Wine, no Proton, nothing to cross-compile. +(Proton is Steam's layer for running Windows games. Wine is the project it is +built on.) ## Install -**`sudo ./tools/setup.sh` installs it into both games for you**, creating the -`plugins` directory they look for but do not ship. If you have run that, -skip to "Check it is working". +**`sudo ./tools/setup.sh` installs it into both games for you.** It also +creates the `plugins` directory the games look for but do not ship. If you +have run that, skip to "Check it is working". -If you installed from a package (Debian, Arch, Fedora, openSUSE), the master -copy is at: +Otherwise, get the plugin file first. Pick one of these: + +- If you installed from a package (Debian, Arch, Fedora, openSUSE), the + master copy is at: ``` /usr/share/logitech-trueforce/liblogi_tf_scs.so ``` -Otherwise download `liblogi_tf_scs-.so` from the -[latest release](https://github.com/mescon/logitech-trueforce-linux-driver/releases/latest) -and rename it to `liblogi_tf_scs.so`, or build it yourself: +- Or download `liblogi_tf_scs-.so` from the + [latest release](https://github.com/mescon/logitech-trueforce-linux-driver/releases/latest) + and rename it to `liblogi_tf_scs.so`. +- Or build it yourself: ```bash cargo build --release -p logi-tf-scs ``` -Then drop it into the game's plugin directory. +Then install it: + +1. Create the game's `plugins` directory. The game only looks for it; it does + not ship one. +2. Copy the file into that directory. +3. Turn the game on in the app's Setup page, under Simulated TrueForce. This + is the same switch every other supported title uses. Euro Truck + Simulator 2 and American Truck Simulator have separate switches and + separate intensities. -Euro Truck Simulator 2: +Steps 1 and 2 for Euro Truck Simulator 2: ```bash mkdir -p ~/.steam/steam/steamapps/common/"Euro Truck Simulator 2"/bin/linux_x64/plugins @@ -39,7 +55,7 @@ cp userspace/logi-wheel/target/release/liblogi_tf_scs.so \ ~/.steam/steam/steamapps/common/"Euro Truck Simulator 2"/bin/linux_x64/plugins/ ``` -American Truck Simulator: +Steps 1 and 2 for American Truck Simulator: ```bash mkdir -p ~/.steam/steam/steamapps/common/"American Truck Simulator"/bin/linux_x64/plugins @@ -47,24 +63,23 @@ cp userspace/logi-wheel/target/release/liblogi_tf_scs.so \ ~/.steam/steam/steamapps/common/"American Truck Simulator"/bin/linux_x64/plugins/ ``` -Create the `plugins` directory if it is not there; the game only looks for -it, it does not ship one. If your Steam library lives on another drive, -`./tools/setup.sh doctor` prints the library roots it found. - -Then turn the game on in the app's Setup page, under Simulated TrueForce, the -same switch every other supported title uses. Euro Truck Simulator 2 and -American Truck Simulator have separate switches and separate intensities. +If your Steam library lives on another drive, `./tools/setup.sh doctor` +prints the library roots it found. ## Check it is working -The game logs its plugins at startup. With a session loaded: +The game logs its plugins at startup. + +1. Load a session in the game. +2. Search the log: ```bash grep -i "logi-tf-scs" ~/.local/share/"Euro Truck Simulator 2"/game.log.txt ``` -A line mentioning `logi-tf-scs` means the game loaded it. If the wheel is -still quiet after that, the daemon is the next place to look: +A line that mentions `logi-tf-scs` means the game loaded it. + +3. If the wheel is still quiet after that, check the daemon: ```bash logi-tf-sim --status @@ -72,16 +87,16 @@ logi-tf-sim --status ## What it sends, and what it does not -Engine rpm, the engine's redline, throttle position and selected gear. That -is what the engine-note synthesizer needs and nothing more. +It sends engine rpm, the engine's redline, throttle position and selected +gear. That is what the engine-note synthesizer needs, and nothing more. It does not send position, speed, damage, cargo, navigation or anything else -the SCS telemetry interface exposes, and it does not read anything back from -the game. It opens one UDP socket to `127.0.0.1` and writes to it. +the SCS telemetry interface exposes. It does not read anything back from the +game. It opens one UDP socket to `127.0.0.1` and writes to it. -If `logi-tf-sim` is not running, the packets go nowhere and the game is -unaffected. Every callback is wrapped so that a fault in the plugin cannot -take the game down with it. +If `logi-tf-sim` is not running, the packets go nowhere, and the game is +unaffected. Every callback is wrapped, so a fault in the plugin cannot take +the game down with it. ## Port @@ -94,8 +109,9 @@ LOGI_TF_SIM_RELAY_PORT=20999 steam steam://rungameid/227300 ## Status -The plugin is written against the official SCS SDK 1.14 headers, with every -struct layout pinned by tests, but it has **not yet been confirmed in a -running game**. That is why the compatibility table marks these two titles -provisional. If you run either of them, a note on the issue tracker saying -whether the engine note appeared is the thing that moves them to verified. +The plugin is written against the official SCS SDK 1.14 headers. Tests pin +every struct layout. But it has **not yet been confirmed in a running +game**. That is why the compatibility table marks these two titles +provisional. If you run either of them, please leave a note on the issue +tracker. Say whether the engine note appeared. That is what moves them to +verified. diff --git a/docs/SDK_ABI_NOTES.md b/docs/SDK_ABI_NOTES.md index 4ade20b..3fe7868 100644 --- a/docs/SDK_ABI_NOTES.md +++ b/docs/SDK_ABI_NOTES.md @@ -1,20 +1,23 @@ # TrueForce SDK: verified ABI notes -Companion to `TRUEFORCE_PROTOCOL.md`, which covers the wire protocol to the -wheel and why the SDK reports 90 degrees under Proton. This one is about -calling the SDK itself. +Companion to `TRUEFORCE_PROTOCOL.md`. That document covers the wire protocol +to the wheel and why the SDK reports 90 degrees under Proton. This one is +about calling the SDK itself. The ABI is the binary calling convention a +library exposes: which registers carry which arguments, and what comes back. -What the shipped `trueforce_sdk_x64.dll` actually expects, taken from its own -machine code rather than from any header. +These notes record what the shipped `trueforce_sdk_x64.dll` actually expects. +They come from its own machine code, not from any header. **Read this before adding to `libtrueforce` or the proxy.** The header in -`userspace/libtrueforce/include/trueforce.h` is not authoritative: three of -its signatures disagree with the DLL, and one of those disagreements is -enough to stop `tools/tf-range-proxy.c` working at all (issue #27). +`userspace/libtrueforce/include/trueforce.h` is not authoritative. Three of +its signatures disagree with the DLL. One of those disagreements is enough to +stop `tools/tf-range-proxy.c` working at all (issue #27). ## How to check a signature -Find the RVA in `sdk/trueforce_1_3_11/exports_x64.txt`, then: +1. Find the RVA (relative virtual address, the function's offset from the + image base) in `sdk/trueforce_1_3_11/exports_x64.txt`. +2. Disassemble the first bytes of the function: ```bash D=sdk/trueforce_1_3_11/trueforce_sdk_x64.dll @@ -23,8 +26,8 @@ x86_64-w64-mingw32-objdump -d "$D" --start-address="$A" \ --stop-address="$(python3 -c "print(hex(int('$A',16)+0x40))")" ``` -Windows x64 passes integer and pointer arguments in RCX, RDX, R8, R9, and -floating point in XMM0-3 by position. So: +Windows x64 passes integer and pointer arguments in RCX, RDX, R8, R9. It +passes floating point in XMM0-3 by position. So: - a `test %rcx,%rcx` followed by a `mov $0x80000001,%eax` return means the first argument is a pointer that must not be null @@ -34,9 +37,9 @@ floating point in XMM0-3 by position. So: `0x80000001` is the library's own bad-parameter status. Success is 0. -Calling one of these cold to see what it does will not work: they dereference -internal state that only exists after the SDK has been opened, and crash on a -null context. Verified by trying it. +Calling one of these cold to see what it does will not work. They dereference +internal state that only exists after the SDK has been opened, and they crash +on a null context. This was verified by trying it. ## Verified @@ -51,15 +54,15 @@ null context. Verified by trying it. ### Why bounds means the settable limits -Worth writing down, because the other reading is plausible and was in this -tree for a while. Five things agree: +This is worth writing down. The other reading is plausible, and it was in +this tree for a while. Five things agree: - the name: bounds *of the operating range*, and the operating range is a single total-degrees number, which Logitech's own documentation states (`LogiGetOperatingRange` "fills the range parameter with the current controller operating range") - the library's own strings, `ANGULAR_RANGE_MIN` and `ANGULAR_RANGE_MAX` -- `docs/PROTOCOL_SPECIFICATION.md`: settable range is 90 to 2700 in 10 +- `docs/PROTOCOL_SPECIFICATION.md`: the settable range is 90 to 2700 in 10 degree steps, and 90 being the minimum is exactly why a failed lookup produces a 90 degree wheel - the function reads its answer from the device through a vtable rather than @@ -68,13 +71,13 @@ tree for a while. Five things agree: ACC and the SDK pair the getter with a setter The competing reading, `-range/2 .. +range/2`, rested on `450.0` appearing -four times in the binary. Those are all in `.text`: coincidental bytes inside -instructions, not double constants, which would live in `.rdata`. There is no -evidence for it at all. +four times in the binary. Those are all in `.text`. They are coincidental +bytes inside instructions, not double constants, which would live in +`.rdata`. There is no evidence for it at all. The legacy Steering Wheel SDK is a different library with different -conventions, and its equivalent writes an `int`, not a `double`: +conventions. Its equivalent writes an `int`, not a `double`: | Function | Signature | |---|---| @@ -82,10 +85,11 @@ conventions, and its equivalent writes an `int`, not a `double`: ## Audit of `libtrueforce`, 2026-08-05 -All 54 declarations checked against the real library's prologues. **Seventeen -are wrong**, and they fail the same way: the real library reports through an -out parameter and returns a status, while the header declares a value return -and no out parameter. Nothing written against the real SDK can call these. +All 54 declarations were checked against the real library's prologues. +**Seventeen are wrong**, and they fail the same way. The real library reports +through an out parameter and returns a status. The header declares a value +return and no out parameter. Nothing written against the real SDK can call +these. ``` bool logiTrueForceAvailable(int) bool logiTrueForceIsPaused(int) @@ -101,35 +105,35 @@ double logiTrueForceGetMaxPeakTorqueKF(int) int logiWheelGetVersion(int index, ...) -- first argument is a pointer ``` -Each should become `int f(..., T *out)` returning 0 or `0x80000001`, the signature -already applied to the rotation getters. The setters, which pass values in -rather than out, check out clean: `logiTrueForceSetGainTF(int, double)` and -the `SetTorqueTF*` family match. +Each should become `int f(..., T *out)` returning 0 or `0x80000001`. That is +the signature already applied to the rotation getters. The setters pass +values in rather than out, and they check out clean: +`logiTrueForceSetGainTF(int, double)` and the `SetTorqueTF*` family match. -This is an ABI break for `libtrueforce`, and deliberately not rushed in -alongside a release. It costs nothing to defer, because no caller written +This is an ABI break for `libtrueforce`. It is deliberately not rushed in +alongside a release. Deferring it costs nothing, because no caller written against the real SDK could ever have linked against the current signature. -Reproduce with the method above, or the throwaway script in the commit that -added this section. +Reproduce with the method above, or with the throwaway script in the commit +that added this section. ## Not established - Whether the out parameter of each getter above is a `double`, an `int` or a - `bool`. The status-return signature is certain; the width is not, and the safe - way to settle each is the write instruction in the body rather than the + `bool`. The status-return signature is certain. The width is not. The safe + way to settle each one is the write instruction in the body, not the prologue. ## Which SDK a game uses Grep the game binary. Assetto Corsa Competizione resolves 56 symbols from -the TrueForce SDK, including all four rotation getters, and none at all from -the legacy Steering Wheel SDK: +the TrueForce SDK, 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 ``` It also looks up four symbols the library has never exported (`dllVersion` -and three viscosity calls). Those lookups fail on Windows too, so a proxy -should match the real library exactly rather than inventing them. +and three viscosity calls). Those lookups fail on Windows too. A proxy should +match the real library exactly rather than invent them. diff --git a/docs/SECURITY_ASSURANCE.md b/docs/SECURITY_ASSURANCE.md index b107066..76ca640 100644 --- a/docs/SECURITY_ASSURANCE.md +++ b/docs/SECURITY_ASSURANCE.md @@ -1,29 +1,37 @@ # Security assurance -What this software is exposed to, what it does about it, and why the -maintainer believes that is enough. This is the assurance case the -project's security work is measured against; the reporting process is in -[../SECURITY.md](../SECURITY.md), and the rules for people and credentials +This page says what this software is exposed to, what it does about it, +and why the maintainer believes that is enough. It is the assurance case +the project's security work is measured against. The reporting process is +in [../SECURITY.md](../SECURITY.md). The rules for people and credentials are in [../GOVERNANCE.md](../GOVERNANCE.md). ## What runs where - **hid-logitech-dd**, a kernel module. It binds the wheel's USB HID - interfaces, parses every report the wheel sends, sends HID++ commands and - the TrueForce stream, and exposes settings through sysfs. It runs with - kernel privilege. + interfaces (HID is the USB class for input devices). It parses every + report the wheel sends. It sends HID++ commands (HID++ is Logitech's + configuration protocol over USB) and the TrueForce stream (Logitech's + high-rate haptic stream). It exposes settings through sysfs, the + kernel's settings file tree under `/sys`. It runs with kernel privilege. - **logi-wheel, logi-wheel-gui**, settings apps. They read and write sysfs - attributes and read `/dev/hidraw` for diagnostics. They run as the user. -- **logi-tf-sim**, the telemetry daemon. It listens on UDP ports on the - loopback interface for game telemetry, synthesises haptics, and writes - them to the wheel through hidraw or the kernel's sysfs. It runs as the - user. -- **logi-ffb**, the DirectInput proxy. It creates a virtual HID device - through `/dev/uhid`, receives force-feedback reports from a Wine process, - and replays them on the real wheel's evdev node. It runs as the user. + attributes. They read `/dev/hidraw` (raw access to the USB HID device) + for diagnostics. They run as the user. +- **logi-tf-sim**, the telemetry daemon (a background service). It listens + for game telemetry on UDP ports on the loopback interface (network + traffic that never leaves the machine). It synthesises haptics from that + telemetry. It writes them to the wheel through hidraw or the kernel's + sysfs. It runs as the user. +- **logi-ffb**, the DirectInput proxy. DirectInput is the Windows + game-input interface. The proxy creates a virtual HID device through + `/dev/uhid`. It receives force-feedback reports from a Wine process + (Wine runs Windows programs on Linux). It replays them on the real + wheel's evdev node (evdev is the Linux input event interface). It runs + as the user. - **logi-launch** and the Windows helpers it stages into a game's prefix - (the escape proxy, the telemetry relay). They run inside the game's Wine - process, with the game's own privileges. + (the escape proxy, the telemetry relay). A prefix is a game's private + Wine environment. They run inside the game's Wine process, with the + game's own privileges. ## Attack surface and threat model @@ -31,109 +39,117 @@ Who could attack, through what, and what the consequence would be. | Source | Reaches | Worst plausible outcome | What stands in the way | |---|---|---|---| -| **A malicious or faulty USB device** presenting Logitech's ids | The kernel module's report parsers and HID++ reply handling | Kernel memory corruption; a crash | Every report is length-checked before a field is read; feature indexes are resolved from the device's own tables and bounds-checked; replies are matched to requests by sequence and validated; the driver is built under the kernel's `-Wall`, checked by sparse, smatch and CodeQL, and its lifetime-sensitive paths are exercised under a KASAN, lockdep and kmemleak kernel in the development VM. Physical access to the USB port is required. | -| **A game, or anything else on the machine, sending UDP telemetry** to the daemon's loopback ports | The telemetry decoders and the relay datagram parser | A daemon crash (loss of haptics) or, at worst, wrong forces | The daemon only binds loopback; every decoder validates length, magic and version before reading a field, rejects samples with no usable engine data, and is fuzzed with cargo-fuzz; forces are clamped by the wheel's strength setting and the kernel's limits, and the wheel's own firmware saturates torque. | -| **A Wine process** writing force-feedback reports to the virtual wheel | The PID report decoder in logi-ffb | A proxy crash (loss of force) or wrong forces | The decoder validates report ids, lengths and block indexes and is fuzzed; effects are translated into the kernel's own force-feedback interface, which bounds them; the proxy runs as the user, with no more access than the game itself has. | -| **A game's prefix** where the Windows helpers run | The escape proxy and relay, and through them the wheel's sysfs range | Wrong rotation range; a stalled game | The helpers only read the game's shared memory and write telemetry to loopback; the one write they perform on the wheel (the rotation range the SDK announces) is bounds-checked to the range a wheel accepts, and can be switched off. | -| **Another local user** | The wheel's sysfs attributes, which the udev rule makes world-writable | Changed settings; a changed rotation range while someone is driving | Accepted risk, stated here: the attributes are world-writable so that settings apps and games work without root, and a machine with a racing wheel attached is assumed to be single-user. No attribute grants any privilege beyond the wheel itself. | -| **A dependency or a build tool** | Everything | Compromised releases | Dependencies are pinned by `Cargo.lock`, updated by Dependabot, checked by `cargo audit` on every push and weekly; GitHub Actions are pinned to commit hashes; workflow tokens are read-only by default; releases are signed, carry SLSA provenance for every asset, and the signing key's fingerprint is published. | -| **The maintainer's accounts and secrets** | Releases and channels | Compromised releases | Two-factor authentication is required for write access; secrets live only in GitHub Actions and are rotated on any suspicion; the rules are in GOVERNANCE.md. | - -The critical code paths, in order of consequence, are the kernel module's -report parsing (kernel privilege), the daemon's writes to the wheel (physical -force), and the release pipeline (everyone's machine). Each has a specific -mitigation above rather than a general one. +| **A malicious or faulty USB device** presenting Logitech's ids | The kernel module's report parsers and HID++ reply handling | Kernel memory corruption; a crash | Every report is length-checked before a field is read. Feature indexes are resolved from the device's own tables and bounds-checked. Replies are matched to requests by sequence and validated. The driver is built under the kernel's `-Wall`. It is checked by sparse, smatch and CodeQL (static analysers, which find bugs without running the code). Its lifetime-sensitive paths run under a KASAN, lockdep and kmemleak kernel (memory-error, lock-order and memory-leak detectors) in the development VM. Physical access to the USB port is required. | +| **A game, or anything else on the machine, sending UDP telemetry** to the daemon's loopback ports | The telemetry decoders and the relay datagram parser | A daemon crash (loss of haptics) or, at worst, wrong forces | The daemon only binds loopback. Every decoder validates length, magic and version before reading a field. It rejects samples with no usable engine data. It is fuzzed with cargo-fuzz (fed random input to find crashes). Forces are clamped by the wheel's strength setting and the kernel's limits. The wheel's own firmware saturates torque. | +| **A Wine process** writing force-feedback reports to the virtual wheel | The PID report decoder in logi-ffb | A proxy crash (loss of force) or wrong forces | The decoder validates report ids, lengths and block indexes. It is fuzzed. Effects are translated into the kernel's own force-feedback interface, which bounds them. The proxy runs as the user, with no more access than the game itself has. | +| **A game's prefix** where the Windows helpers run | The escape proxy and relay, and through them the wheel's sysfs range | Wrong rotation range; a stalled game | The helpers only read the game's shared memory and write telemetry to loopback. They perform one write on the wheel: the rotation range the SDK announces (the SDK is Logitech's library that a game loads to talk to the wheel). That write is bounds-checked to the range a wheel accepts, and can be switched off. | +| **Another local user** | The wheel's sysfs attributes, which the udev rule (a Linux device-manager rule) makes world-writable | Changed settings; a changed rotation range while someone is driving | Accepted risk, stated here. The attributes are world-writable so that settings apps and games work without root. A machine with a racing wheel attached is assumed to be single-user. No attribute grants any privilege beyond the wheel itself. | +| **A dependency or a build tool** | Everything | Compromised releases | Dependencies are pinned by `Cargo.lock`, updated by Dependabot, and checked by `cargo audit` on every push and weekly. GitHub Actions are pinned to commit hashes. Workflow tokens are read-only by default. Releases are signed and carry SLSA provenance for every asset (a signed record of how a release was built). The signing key's fingerprint is published. | +| **The maintainer's accounts and secrets** | Releases and channels | Compromised releases | Two-factor authentication is required for write access. Secrets live only in GitHub Actions and are rotated on any suspicion. The rules are in GOVERNANCE.md. | + +The critical code paths, in order of consequence, are: the kernel module's +report parsing (kernel privilege), the daemon's writes to the wheel +(physical force), and the release pipeline (everyone's machine). Each has +a specific mitigation above, not a general one. ## Secure design principles the project follows -- **Least privilege.** Only the kernel module runs privileged, and only it - touches the device directly; everything else runs as the user, through +- **Least privilege.** Only the kernel module runs privileged. Only it + touches the device directly. Everything else runs as the user, through interfaces the kernel bounds. Workflow tokens are read-only unless a job says otherwise. - **Validate at the boundary.** Every byte from a device, a socket or a HID - node passes a parser that checks length and structure before any field - is used, and those parsers are the fuzz targets. -- **Fail closed on force.** When the driver cannot tell what a wheel is - doing (unreadable range, a lost session, a device that stops answering) - it stops sending force rather than guessing, and says so in dmesg. + node passes a parser. The parser checks length and structure before any + field is used. Those parsers are the fuzz targets. +- **Fail closed on force.** Sometimes the driver cannot tell what a wheel + is doing (unreadable range, a lost session, a device that stops + answering). Then it stops sending force instead of guessing, and says so + in dmesg (the kernel log). - **One writer per stream.** Two processes writing the TrueForce stream - corrupt each other's output; the daemon takes a lease, and steps aside + corrupt each other's output. So the daemon takes a lease. It steps aside when a game's own SDK has the wheel. Most of the 0.4x series was about enforcing this. - **Nothing hidden in the build.** The kernel module and the apps carry - the same git stamp; the installer refuses to leave an app that does not - match the module; the three committed Windows binaries are byte-verified - against their source in CI. + the same git stamp. The installer refuses to leave an app that does not + match the module. CI (the automated checks on every change) verifies + the three committed Windows binaries byte for byte against their source. ## Dependencies and software composition -How dependencies are chosen, obtained and tracked (this is the policy the -Baseline criteria ask for): +How dependencies are chosen, obtained and tracked. This is the policy the +Baseline criteria ask for. - **Selection.** A Rust dependency is added only with a reason in the - change that adds it, must be GPL-2.0-compatible, and must be maintained. - The kernel module has no dependencies beyond the kernel. + change that adds it. It must be GPL-2.0-compatible. It must be + maintained. The kernel module has no dependencies beyond the kernel. - **Obtaining.** Dependencies come from crates.io through cargo, pinned in - `userspace/logi-wheel/Cargo.lock`; distribution packages build from that + `userspace/logi-wheel/Cargo.lock`. Distribution packages build from that lock with `--locked`. GitHub Actions are pinned to full commit hashes. - **Tracking.** Dependabot opens weekly update pull requests for cargo and - for Actions; `cargo audit` runs on every push and weekly against the - RustSec advisory database and fails the workflow on an advisory. + for Actions. `cargo audit` runs on every push and weekly against the + RustSec advisory database. It fails the workflow on an advisory. - **Remediation thresholds.** A vulnerability advisory in a dependency is - fixed, by updating or replacing the crate, before the next release, and - within 14 days for anything rated high or critical; a license problem is - fixed before the next release. Advisories that do not affect the project - (for example maintenance notices about crates that carry no - vulnerability) are recorded twice, with the reason each time: in the VEX - document at [../security/openvex.json](../security/openvex.json) for - people, and in `userspace/logi-wheel/osv-scanner.toml` for scanners - (osv-scanner reads that file from the lock file's directory, and so does - the OpenSSF Scorecard, which runs it). Every scanner entry carries an - expiry date, so an accepted advisory is reported again when it lapses and - has to be reviewed again. Both files are reviewed at each release. No - release is cut with an unrecorded advisory outstanding. + fixed before the next release, by updating or replacing the crate. + Anything rated high or critical is fixed within 14 days. A license + problem is fixed before the next release. Some advisories do not affect + the project (for example maintenance notices about crates that carry no + vulnerability). Those are recorded twice, with the reason each time. For + people, in the VEX document at + [../security/openvex.json](../security/openvex.json) (VEX, a record of + which advisories do not apply and why). For scanners, in + `userspace/logi-wheel/osv-scanner.toml`. osv-scanner reads that file + from the lock file's directory, and so does the OpenSSF Scorecard, which + runs it. Every scanner entry carries an expiry date. So an accepted + advisory is reported again when it lapses, and has to be reviewed again. + Both files are reviewed at each release. No release is cut with an + unrecorded advisory outstanding. - **Static analysis findings.** A CodeQL or clippy finding of a security - weakness blocks the change that introduced it: clippy failures fail CI, - and CodeQL alerts are triaged within 14 days and fixed before the next - release or dismissed with a written reason on the alert. + weakness blocks the change that introduced it. clippy failures fail CI. + CodeQL alerts are triaged within 14 days. Each is fixed before the next + release, or dismissed with a written reason on the alert. ## Software bill of materials Every release from 0.42.0 onward attaches a CycloneDX SBOM for each Rust -binary (the settings apps, the daemon, the proxy and the Windows relay), -generated by the release pipeline from the locked dependency graph. The -kernel module has no third-party components; its bill of materials is the -module source itself, which the packages ship. +binary (the settings apps, the daemon, the proxy and the Windows relay). +An SBOM is a list of every software component in a release. The release +pipeline generates it from the locked dependency graph. The kernel module +has no third-party components. Its bill of materials is the module source +itself, which the packages ship. ## Verifying a release -Release assets are signed with the project's GnuPG key, fingerprint -`4B5B DD78 0272 3B28 9FA9 34CA CD77 C00A 443B 9E79`, published with each -release as `logitech-trueforce-signing-key.asc`: the Arch packages and -repository database up to 0.41.0, every asset from 0.42.0. The README's -"Verifying a release" says how to check one: pacman does it once the key -is trusted; for any other asset, `gpg --verify .sig ` after -importing the key and checking the fingerprint. The identity behind a -release is that key: a release signed by any other key is not from this -project until the README says the key has changed. +Release assets are signed with the project's GnuPG key. Its fingerprint is +`4B5B DD78 0272 3B28 9FA9 34CA CD77 C00A 443B 9E79`. The key is published +with each release as `logitech-trueforce-signing-key.asc`. Signed: the +Arch packages and repository database up to 0.41.0, and every asset from +0.42.0. The README's "Verifying a release" says how to check one. pacman +does it once the key is trusted. For any other asset: + +1. Import the key. +2. Check its fingerprint against the one above. +3. Run `gpg --verify .sig `. + +The identity behind a release is that key. A release signed by any other +key is not from this project, until the README says the key has changed. From 0.42.0 each release also carries a SLSA build provenance statement -(`release-assets.intoto.jsonl`) produced by the SLSA generic generator: -the release workflow hashes every attached asset and the generator signs -the list keylessly through Sigstore, recording the repository, the tag and -the workflow that published them. `slsa-verifier` checks an asset against -it, as the README shows. The GnuPG signature says who signed; the +(`release-assets.intoto.jsonl`). The SLSA generic generator produces it. +The release workflow hashes every attached asset. The generator signs the +list keylessly through Sigstore. The statement records the repository, the +tag and the workflow that published them. `slsa-verifier` checks an asset +against it, as the README shows. The GnuPG signature says who signed. The provenance says what built it and from which commit. ## Support and end of support -The latest release is the supported one and receives security fixes; a +The latest release is the supported one and receives security fixes. A release stops receiving them the moment a newer release exists. There are no maintenance branches. SECURITY.md carries the same statement. ## What this case does not cover -Physical safety of a direct-drive wheel is a hardware matter the software -can only bound, not remove; the rules for testing with hands on the rim are -in STATUS.md. A compromised kernel or a root-level attacker on the machine -is out of scope, as it is for any driver. +Physical safety of a direct-drive wheel is a hardware matter. The software +can only bound it, not remove it. The rules for testing with hands on the +rim are in STATUS.md. A compromised kernel or a root-level attacker on the +machine is out of scope, as it is for any driver. diff --git a/docs/SHARED_MEMORY_RELAY.md b/docs/SHARED_MEMORY_RELAY.md index affad24..9ede9e8 100644 --- a/docs/SHARED_MEMORY_RELAY.md +++ b/docs/SHARED_MEMORY_RELAY.md @@ -1,14 +1,15 @@ # Simulated TrueForce for sims that publish to shared memory -Most sims broadcast telemetry over UDP, which `logi-tf-sim` reads directly. -A few do not: iRacing, RaceRoom, the Assetto Corsa family, rFactor 2 -and Le Mans Ultimate publish into a named Windows shared-memory section that -only the game's own SDK reads. Nothing on the Linux side can see it. +Most sims broadcast telemetry over UDP, and `logi-tf-sim` reads that +directly. A few do not. iRacing, RaceRoom, the Assetto Corsa family, rFactor 2 +and Le Mans Ultimate publish into a named Windows shared-memory section. +Shared memory is a memory region two programs read and write together. Only +the game's own SDK reads that section. Nothing on the Linux side can see it. -`logi-tf-relay` is a small Windows executable that runs inside the game's -Proton prefix, reads that section with the ordinary Win32 API (which Wine -implements), and forwards engine speed, redline, throttle and gear to the -daemon over localhost UDP. +`logi-tf-relay` is a small Windows executable. It runs inside the game's +Proton prefix (the per-game Wine environment Steam creates). It reads that +section with the ordinary Win32 API, which Wine implements. It then forwards +engine speed, redline, throttle and gear to the daemon over localhost UDP. ## What works today @@ -22,74 +23,74 @@ daemon over localhost UDP. | rFactor 2 | Decoder written. Unconfirmed against a live session. | | Le Mans Ultimate | Decoder written. Unconfirmed against a live session. | -What separates these is not difficulty, it is whether the layout can be +What separates these is not difficulty. It is whether the layout can be trusted without a capture. Each earned that trust a different way. **iRacing's telemetry is self-describing.** The section starts with a small -header pointing at a table of variable descriptors, each carrying a -variable's name next to its offset and type, so the decoder looks up `RPM`, -`Throttle` and `Gear` by name at runtime. Nothing about where those values -live is guessed. +header. The header points at a table of variable descriptors. Each descriptor +carries a variable's name next to its offset and type. So the decoder looks up +`RPM`, `Throttle` and `Gear` by name at runtime. Nothing about where those +values live is guessed. **RaceRoom's layout is published by the people who write it.** KW Studios -ship `r3e.h` at `github.com/sector3studios/r3e-api`, in the public domain, -and they own both ends of the interface with no plugin in between. The struct -is byte-packed, so no compiler can disagree about where a field sits, and it -opens with a major version number the decoder checks before reading anything -else. +ship `r3e.h` at `github.com/sector3studios/r3e-api`, in the public domain. +They own both ends of the interface, with no plugin in between. The struct +is byte-packed, so no compiler can disagree about where a field sits. It +opens with a major version number, and the decoder checks that number before +it reads anything else. **Assetto Corsa only needs the head of its struct.** Kunos have appended -fields to the physics block for a decade, but appending does not move what -came before, and throttle, gear and rpm have been in its first 32 bytes since -1.0. The redline comes from a second block where the offset is less obviously -safe, so the decoder verifies that block's layout in-band before trusting it. -Competizione publishes the same section names and the same layout, byte for -byte through every field used, so it is read by the same decoder. - -EVO is the one that changed. Kunos renamed every section and took the car -spec sheet out of the static block, so the redline the older two read there -does not exist. Its replacement, `currentMaxRpm`, sits in the physics block -and is republished every tick. That leaves EVO with one section and no layout -guard, so the check is the value itself: a redline is a distinctive number, -and a wrong offset in a physics block lands on a temperature, a pressure or a -pedal, none of which comes near one. +fields to the physics block for a decade. Appending does not move what came +before, and throttle, gear and rpm have been in its first 32 bytes since 1.0. +The redline comes from a second block, where the offset is less obviously +safe. So the decoder verifies that block's layout in-band before it trusts +it. Competizione publishes the same section names and the same layout, byte +for byte through every field used. The same decoder reads it. + +EVO is the one that changed. Kunos renamed every section. They also took the +car spec sheet out of the static block, so the redline the older two read +there does not exist. Its replacement, `currentMaxRpm`, sits in the physics +block and is republished every tick. That leaves EVO with one section and no +layout guard. So the check is the value itself. A redline is a distinctive +number. A wrong offset in a physics block lands on a temperature, a pressure +or a pedal, and none of those comes near one. Confirmed on a live session on 2026-08-06: `acevo_pmf_physics` opened while -`acpmf_physics` stayed absent, which is itself evidence the rename is real, -and offset 588 read 6200 next to an engine turning 4662 in first gear. A -number that plausible, that consistent with its neighbours, is not a -temperature read by accident. +`acpmf_physics` stayed absent. That is itself evidence the rename is real. +Offset 588 read 6200 next to an engine turning 4662 in first gear. A number +that plausible, and that consistent with its neighbours, is not a temperature +read by accident. **rFactor 2 and Le Mans Ultimate say whether a read was good.** Their layout -comes from a community plugin rather than a vendor, which is why they were +comes from a community plugin rather than a vendor. That is why they were written last: the struct depends on which fork and build the user installed. -What makes them decodable anyway is that the format carries its own -consistency state. Each buffer is preceded by a pair of counters the plugin -bumps before and after writing, so a read that caught a write in progress is -detectable and gets dropped. And the player's car is found by matching a slot -id between two independently written buffers, which a misaligned read fails -rather than passes with plausible numbers. +They are decodable anyway, because the format carries its own consistency +state. Each buffer is preceded by a pair of counters. The plugin bumps them +before and after writing, so a read that caught a write in progress is +detectable and gets dropped. The player's car is found by matching a slot id +between two independently written buffers. A misaligned read fails that +match rather than passing with plausible numbers. Assetto Corsa Competizione was confirmed end to end on 2026-08-06, on a -G923. Both sections opened; the physics head read a coherent live car; the -static block's UTF-16 guard passed on real bytes; and `maxRpm` at offset 412 +G923. Both sections opened. The physics head read a coherent live car. The +static block's UTF-16 guard passed on real bytes. `maxRpm` at offset 412 read 8650, a genuine GT3 redline rather than plausible garbage. Then the whole chain was run: game shared memory, relay wire format, daemon, synth, wheel. With the car **stationary in the pit box** and the engine revving, the wheel produced an engine note. That is the test worth repeating, -because force feedback cannot fake it: a parked car generates no tyre or -suspension force, so anything felt while stationary came from telemetry. Same -offsets confirm Assetto Corsa, which shares this layout. +because force feedback cannot fake it. A parked car generates no tyre or +suspension force, so anything felt while stationary came from telemetry. The +same offsets confirm Assetto Corsa, which shares this layout. The rest have not been run against a live game. Every read in them is bounds -checked and range gated, and each drops a sample it cannot vouch for rather -than sending a wrong number, but that is a design argument, not evidence. +checked and range gated. Each drops a sample it cannot vouch for rather than +send a wrong number. But that is a design argument, not evidence. ## Get it **You normally do not have to place this yourself.** `sudo ./tools/setup.sh` -puts it in every Proton prefix, and the settings app has an "Install relay" +puts it in every Proton prefix. The settings app has an "Install relay" button on each game that needs one (in the terminal app, `h` on the selected game). It lands at the prefix's drive root, which makes the in-prefix path `C:\logi-tf-relay.exe`. @@ -102,7 +103,7 @@ copy is at: ``` It is a Windows executable, so it lives in the shared data directory rather -than in `bin`: you do not run it directly, you run it inside a game's Proton +than in `bin`. You do not run it directly. You run it inside a game's Proton prefix. It ships prebuilt because no distro builder has a Rust Windows target, the same reason `tf-range-proxy.dll` is prebuilt. @@ -118,7 +119,7 @@ tools/build-relay.sh ``` If `cargo` comes from your distribution rather than rustup, put rustup's -first: a system cargo usually has only the host target, and the failure is +first. A system cargo usually has only the host target, and the failure is an unhelpful "can't find crate for `core`". ```bash @@ -127,16 +128,16 @@ export PATH="$HOME/.cargo/bin:$PATH" Do not try to satisfy it by unpacking an upstream `rust-std` into the system `/usr/lib/rustlib`. A precompiled std has to come from the exact rustc build -that will use it, and a distribution's patched rustc is not that build; the +that will use it. A distribution's patched rustc is not that build. The result is E0514, "found crate `core` compiled by an incompatible version of rustc". -That uses the `relay-dist` cargo profile, which is what keeps the committed +The build uses the `relay-dist` cargo profile, which keeps the committed binary small, and writes `tools/logi-tf-relay.exe`. Refresh it that way -rather than by hand: CI runs `tools/build-relay.sh --check` and fails if the +rather than by hand. CI runs `tools/build-relay.sh --check` and fails if the committed binary is older than the sources it was built from, so a packaged -relay cannot silently lag the code. The build needs a MinGW linker, no -Windows machine and no Wine. +relay cannot silently lag the code. The build needs a MinGW linker. It needs +no Windows machine and no Wine. ## Run it @@ -153,20 +154,20 @@ running. The prefix is named after the game's Steam appid: | rFactor 2 | `rf2` | 365960 | `rF2SharedMemoryMapPlugin` | | Le Mans Ultimate | `lmu` | 2399420 | `rF2SharedMemoryMapPlugin` | -The easy way is to let the game start it, by putting this in the game's +The easy way is to let the game start it. Put this in the game's Steam launch options: ``` logi-launch %command% ``` -That starts the relay inside the prefix once the game is up, and works out +That starts the relay inside the prefix once the game is up. It works out which game it is from the appid, so there is nothing else to set. See [LAUNCH_OPTIONS.md](LAUNCH_OPTIONS.md). **Starting it by hand is fiddlier than it looks, and the obvious command is -a trap.** `WINEPREFIX=... wine ...` uses your distribution's wine, which is -a different build from the one Proton made the prefix with: it runs prefix +a trap.** `WINEPREFIX=... wine ...` uses your distribution's wine. That is +a different build from the one Proton made the prefix with. It runs prefix initialisation, prompts to install wine-mono, and can convert the prefix. Use the prefix's own wine instead, and only while the game is already running, because Proton waits for any existing wineserver to exit before it @@ -183,15 +184,15 @@ what it finds to `logi-tf-sim`, which must also be running. Then turn the game on in the app's Setup page under Simulated TrueForce. **Competizione and EVO are special cases.** Both have real TrueForce of -their own, and on a direct-drive wheel that is the route to use: install the +their own. On a direct-drive wheel that is the route to use: install the shim and skip the relay entirely. The relay is here for the G923, which -cannot receive the SDK's TrueForce at all, so a synthesized engine note is -the difference between haptics and silence rather than a second-best. +cannot receive the SDK's TrueForce at all. For that wheel a synthesized +engine note is the difference between haptics and silence, not a second-best. -None of these needs anything switched on inside the game: unlike the UDP +None of these needs anything switched on inside the game. Unlike the UDP titles, the shared memory is always published. rFactor 2 and Le Mans Ultimate do need the community `rF2SharedMemoryMapPlugin` in the game's `Plugins` -directory, though, or the game publishes nothing at all. +directory, though. Without it the game publishes nothing at all. If your Steam library is on another drive, `./tools/setup.sh doctor` prints the roots it found. @@ -204,8 +205,9 @@ LOGI_TF_SIM_RELAY_PORT=20999 wine logi-tf-relay.exe --game iracing ## Capture a fixture -Every decoder here is written against a published layout, and none has yet -been confirmed against a running game. If one of them stays silent, or sends +Every decoder here is written against a published layout. Only the RaceRoom, +Assetto Corsa Competizione and AC EVO ones are confirmed against a running +game (see the table at the top). If one of the others stays silent, or sends something obviously wrong, a dump is what turns that into a fix. With the game running and a session actually **live** (sitting in the menus @@ -216,32 +218,32 @@ WINEPREFIX= \ wine logi-tf-relay.exe --game lmu --dump lmu-dump.bin ``` -Attach `lmu-dump.bin` to an issue, saying which game and which build. The -dump is what a decoder gets re-tested against, so a real one settles a +Attach `lmu-dump.bin` to an issue. Say which game and which build. The +dump is what a decoder gets re-tested against. A real one settles a question that no amount of reading headers can. The dump contains vehicle telemetry for the session that was running. It -carries no account details, no keys and no personal data, but it does reflect +carries no account details, no keys and no personal data. It does reflect what you were driving at that moment. ## The relay datagram is a generic RPM contract -Everything above describes the producers this project ships, but the port +Everything above describes the producers this project ships. But the port is a contract, not a private channel: **any** telemetry producer that emits the LTFR datagram to `127.0.0.1:20780` plugs into the same consumers. That includes `logi-rpm-bridge`, which forwards `rpm max_rpm` into the driver's -`wheel_texture_rpm` sysfs attribute and therefore feeds the native -TrueForce texture merge - so a homegrown bridge for an unlisted sim gets -the on-wheel engine texture for its title as soon as the game's recipe -grants `texture=merge` (the registry in -`userspace/logi-wheel/crates/logi-wheel-core/src/games.rs`; today only -AC EVO, because grants ride hardware evidence). +`wheel_texture_rpm` sysfs attribute. That feeds the native TrueForce texture +merge. So a homegrown bridge for an unlisted sim gets the on-wheel engine +texture for its title as soon as the game's recipe grants `texture=merge`. +The recipe registry is in +`userspace/logi-wheel/crates/logi-wheel-core/src/games.rs`. Today only +AC EVO has the grant, because grants ride hardware evidence. **One socket gets the datagrams, every reader gets the telemetry.** The -port takes any number of producers, but a unicast datagram is delivered to -exactly one socket, whatever options the listeners set (`SO_REUSEADDR` only -lets both bind while the kernel still picks one winner; `SO_REUSEPORT` -load-balances, which splits a stream rather than duplicating it). The +port takes any number of producers. But a unicast datagram is delivered to +exactly one socket, whatever options the listeners set. `SO_REUSEADDR` only +lets both bind while the kernel still picks one winner. `SO_REUSEPORT` +load-balances, which splits a stream rather than duplicating it. The kernel will not deliver to both, so the readers do it themselves: - Whoever binds 20780 is the **hub**. It forwards every datagram it @@ -249,27 +251,27 @@ kernel will not deliver to both, so the readers do it themselves: 20783 and 20784. (20781 is skipped: that is the captured-TrueForce port, where a copy of engine telemetry would be read as finished haptics.) - Whoever finds 20780 taken reads the first free fan-out port instead, and - is fed by the hub. It says so at startup, naming both ports, because a + is fed by the hub. It says so at startup, naming both ports. Otherwise a program listening on 20782 with nothing configured to say so would read as a misconfiguration in a bug report. - A follower keeps trying to take 20780, about every two seconds. When the - hub exits, the survivor is promoted, so telemetry aimed where every - producer sends it keeps arriving and the next program to start finds a + hub exits, the survivor is promoted. So telemetry aimed where every + producer sends it keeps arriving, and the next program to start finds a working hub. -Forwarding only ever goes upward, from 20780 to the fan-out ports, so no +Forwarding only ever goes upward, from 20780 to the fan-out ports. So no arrangement of these programs can make a datagram circulate. Nothing needs to be stopped, and no port needs moving, for `logi-rpm-bridge` and `logi-tf-sim` to run at the same time. `LOGI_RPM_PORT` and the daemon's `port.relay` still move the whole block (the fan-out is derived from -whatever the relay port is), which is what a third-party producer on a +whatever the relay port is). That is what a third-party producer on a different port wants. The rules are implemented twice, in `logi_wheel_core::relay::RelayListener` and in `tools/logi-rpm-bridge.c`, because the two readers are written in different languages. A change to one belongs in the other. -`logi-rpm-bridge` is also the rev-light feeder: besides +`logi-rpm-bridge` is also the rev-light feeder. Besides `wheel_texture_rpm`, it drives `wheel_rev_level` from the same datagrams. The default mapping is a full rev bar (LED 1 as soon as rpm > 0, all 10 at the limiter; works for 28-byte senders too). `LOGI_REV_MODE=shift` @@ -277,27 +279,27 @@ selects the dash band instead: dark below the first-shift-light rpm, level 1 exactly there, 10 at the limiter (needs the 32-byte form below). `LOGI_REV_SYSFS` overrides the LED target attribute and `LOGI_RPM_PORT` the UDP port. The strip darkens on telemetry loss (1 s) and on bridge -exit. The strip has one feeder per session: `logi-tf-sim` drives it from +exit. The strip has one feeder per session. `logi-tf-sim` drives it from telemetry too, so while a bridge is running the daemon leaves the rev -display alone (it says so in its log) rather than writing a second mapping +display alone (it says so in its log) rather than write a second mapping over the top of it. -**Which wheel it writes to.** Left alone the bridge finds a wheel itself, -which is right with one attached and a coin toss with two: its rev target +**Which wheel it writes to.** Left alone, the bridge finds a wheel itself. +That is right with one attached and a coin toss with two. Its rev target is the neighbour of the texture attribute, so an unscoped bridge can feed one wheel's texture and light the other one's strip. `logi-launch` therefore passes `LOGI_RPM_SYSFS=/wheel_texture_rpm` for the wheel it -resolved for the session, and the rev target is taken from the same +resolved for the session. The rev target is taken from the same directory unless `LOGI_REV_SYSFS` says otherwise. If a write fails with the errors that mean the device moved (`ENOENT`, `ENODEV`), the bridge resolves -again rather than writing into a stale path for the rest of the session, so +again rather than write into a stale path for the rest of the session. So a wheel that is replugged mid-game is picked up without restarting anything. -The wire format, LTFR version 2 (40 bytes since 2026-09-05, 32 since -2026-08-14, little-endian, append-only - the first 28 bytes are the -original version-2 layout, the version byte is unchanged, and old consumers -keep reading just what they know; the authoritative copy lives in -`logi-wheel-core`'s `relay.rs`): +The wire format is LTFR version 2. It is 40 bytes since 2026-09-05, and was +32 since 2026-08-14. It is little-endian and append-only: the first 28 bytes +are the original version-2 layout, the version byte is unchanged, and old +consumers keep reading just what they know. The authoritative copy lives in +`logi-wheel-core`'s `relay.rs`: | offset | field | type | notes | |---|---|---|---| @@ -313,7 +315,7 @@ keep reading just what they know; the authoritative copy lives in | 32 | speed | f32 LE | car speed, m/s; 0 = the sender cannot tell (appended 2026-09-05, for the base's screen) | | 36 | brake | f32 LE | 0.0-1.0; 0 = the sender cannot tell (appended with speed) | -Send at roughly 60 Hz; consumers rate-limit on their side, and +Send at roughly 60 Hz. Consumers rate-limit on their side, and `logi-rpm-bridge` drops packets whose rpm is not in `[0, 30000)`. Fields a producer cannot supply are zero, which the format defines as "the sender cannot tell". @@ -321,10 +323,10 @@ cannot tell". ## Troubleshooting **"not readable yet"** repeated: the relay is running but the game is not -publishing. Check the game is actually in a session, and for rFactor 2 and Le -Mans Ultimate that the shared-memory plugin is installed. +publishing. Check that the game is actually in a session. For rFactor 2 and +Le Mans Ultimate, check that the shared-memory plugin is installed. -**Nothing happens although the relay says it is streaming**: check +**Nothing happens although the relay says it is streaming**: check that `logi-tf-sim` is running, that the game is switched on in the Setup page, and that both agree on the port. diff --git a/docs/STATUS.md b/docs/STATUS.md index f2a4ae8..c1d1349 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,11 +1,12 @@ # Where this driver is, and what it still cannot do -A companion to [FEATURE_MATRIX.md](FEATURE_MATRIX.md), which says what the -wheels report; this one says what has been done with that, and what has not. +This page is a companion to [FEATURE_MATRIX.md](FEATURE_MATRIX.md). That +page says what the wheels report. This one says what has been done with +that, and what has not. -The point of it is that the honest answer to "does this work?" is different -for each wheel and each claim, and a reader deserves to know which parts are -measured, which are argued, and which are hoped. +The honest answer to "does this work?" differs for each wheel and each +claim. A reader deserves to know which parts are measured, which are +argued, and which are hoped. ## Wheels @@ -16,67 +17,72 @@ measured, which are argued, and which are hoped. | G923 PS (`c266`/`c267`) | yes, classic path | simulated only | **none** | yes, classic command | | G923 Xbox (`c26e`) | yes, HID++ 0x8123 by default; this driver's own engine with `g923_xbox_dd_engine=1` | the game's own with the SDK files present, else simulated; both with force | **none** | yes, follows revs on the engine (#72) | -The Xbox editions of the RS50 (`c275`) and the G923 (`c26d`) boot speaking -the console's own protocol, with no HID++ interface to bind. Both are -switched to their PC id automatically on every plug-in, which needs -`usb_modeswitch` installed; `sudo logi-wheel-modeswitch` does it by hand. -After the switch each is the wheel in its row above. +The Xbox editions of the RS50 (`c275`) and the G923 (`c26d`) start up +speaking the console's own protocol. In that mode they have no HID++ +interface to bind. HID++ is Logitech's configuration protocol over USB. +The driver switches both wheels to their PC id on every plug-in. This +needs `usb_modeswitch` installed. `sudo logi-wheel-modeswitch` does the +switch by hand. After the switch, each wheel is the wheel in its row above. The G923 Xbox edition is the one wheel here whose force this driver does -not compute. Its effects are downloaded into the wheel's own firmware over -HID++ 0x8123 and summed there, so nothing in the kernel knows the force -being produced, and a TrueForce stream, whose torque field takes the -motor, can only carry a zero. `logi-tf-sim` therefore refuses that wheel -rather than silencing it (#72), and its own `g923.stream_without_ffb_mirror` -streams anyway for anyone who wants the haptics and not the force. - -The way to have both is `g923_xbox_dd_engine=1`, which moves that wheel -onto the engine the direct-drive wheels use, summing the effects here and -carrying force and texture in one packet. Off by default, and now measured -on the hardware by its owner (issue #72, 2026-09-02): force is linear in -the commanded level above a static-friction floor of about 3.6% of full -scale, and the engine's gain matches the firmware path to within the -measurement's own noise, so the scaling needed no change. Under it the -condition effects are fed the steering position as of this release (the -axis is located by usage in the report descriptor rather than at the -RS50's offset), and all four conditions were measured alive on a real -unit in September 2026 (#72: spring returns to centre, damper, friction -and inertia each slow a fixed push by a distinct, repeatable factor); the -rev lights stay on their own LED device, which speaks the command that -wheel obeys rather than the direct-drive one. Two owners found that this -engine with raw HID off is the setup that gives force and simulated -TrueForce together on that wheel (#72, #84); 0.40.1 taught it the wheel's -real range and strength, its own strength scaling, the firmware centring -spring, and the 2 ms position reports its velocity estimate had aliased -against (#82, #85, #86). - -That wheel can also wedge after a stalled motor: HID++ commands fail, -as a mix of timeouts and fast submit errors, while init has already -reported success and steering still works. Reloading the driver or -replugging the wheel recovers it, measured by its owner against an -eight-minute control (#72); an earlier claim that only a power cycle did -was withdrawn. The driver notices a run of transport failures and says -so, once, in dmesg, with that recovery, and declares recovery only after -a run of answers. A wedged wheel can also answer with HID++ errors rather -than silence (traced in #72: every effect download refused as an invalid -argument), and since 0.40.1 those no longer count as a healthy answer. - -Whether force feedback comes up at all on that wheel depends on its HID++ -answering while this driver is still in probe. A fix that keeps waiting -instead of giving up lives on `g923-xbox-ffb-retry`, unmerged for the same -reason (#52). - -Two things about the RS50's light strip that are not faults. It only -displays on some onboard profiles: a profile can keep it dark, and writes -still succeed there. And the four built-in sweeps render a palette held in -the wheel's firmware, which no function in `0x807A`/`0x807B` reports and -which G HUB never reads either, so their colours cannot be previewed or -copied. - -The G923 exposes no `wheel_*` attributes at all. That is not an oversight: -it takes the classic force-feedback path, which has no settings surface, no -feature discovery and no sysfs group to hang them on. Its response curves -would also need `0x80A3`, a page this driver does not implement, because the +not compute. The driver downloads its effects into the wheel's own +firmware over HID++ 0x8123. The firmware sums them there. So nothing in +the kernel knows the force the wheel produces. TrueForce is Logitech's +high-rate haptic stream, and its torque field takes the motor. On this +wheel that field can only carry a zero. `logi-tf-sim` therefore refuses +that wheel instead of silencing it (#72). Its own +`g923.stream_without_ffb_mirror` streams anyway, for anyone who wants the +haptics and not the force. + +`g923_xbox_dd_engine=1` is the way to have both. It moves that wheel onto +the engine the direct-drive wheels use. That engine sums the effects here +and carries force and texture in one packet. It is off by default. Its +owner has now measured it on the hardware (issue #72, 2026-09-02). Force +is linear in the commanded level above a static-friction floor of about +3.6% of full scale. The engine's gain matches the firmware path to within +the measurement's own noise. So the scaling needed no change. As of this +release, the condition effects under it get the steering position. The +driver finds the axis by usage in the report descriptor, not at the RS50's +offset. All four conditions were measured alive on a real unit in +September 2026 (#72). Spring returns to centre. Damper, friction and +inertia each slow a fixed push by a distinct, repeatable factor. The rev +lights stay on their own LED device. That device speaks the command this +wheel obeys, not the direct-drive one. Two owners found that this engine +with raw HID off gives force and simulated TrueForce together on that +wheel (#72, #84). 0.40.1 taught the engine the wheel's real range and +strength, its own strength scaling, the firmware centring spring, and the +2 ms position reports. Its velocity estimate had aliased against those +reports (#82, #85, #86). + +That wheel can also wedge after a stalled motor. HID++ commands then fail, +as a mix of timeouts and fast submit errors. Init has already reported +success, and steering still works. Reloading the driver or replugging the +wheel recovers it. Its owner measured this against an eight-minute control +(#72). An earlier claim that only a power cycle recovered it was +withdrawn. The driver notices a run of transport failures. It says so once +in dmesg (the kernel log), with that recovery. It declares recovery only +after a run of answers. A wedged wheel can also answer with HID++ errors +instead of silence. #72 traced this: every effect download was refused as +an invalid argument. Since 0.40.1 those errors no longer count as a +healthy answer. + +Whether force feedback comes up at all on that wheel depends on one thing. +Its HID++ must answer while this driver is still in probe (the first +set-up of the device). A fix that keeps waiting instead of giving up lives +on `g923-xbox-ffb-retry`. It is unmerged for the same reason (#52). + +Two things about the RS50's light strip are not faults. First, it only +displays on some onboard profiles. A profile can keep it dark, and writes +still succeed there. Second, the four built-in sweeps render a palette +held in the wheel's firmware. No function in `0x807A`/`0x807B` reports +that palette. G HUB (Logitech's Windows software) never reads it either. +So their colours cannot be previewed or copied. + +The G923 exposes no `wheel_*` attributes at all. That is not an oversight. +It takes the classic force-feedback path. That path has no settings +surface, no feature discovery and no sysfs group to hang them on. sysfs is +the kernel's settings file tree under `/sys`. Its response curves would +also need `0x80A3`, a page this driver does not implement. The direct-drive wheels use `0x80A4` instead. ## What is measured, what is argued @@ -84,98 +90,100 @@ direct-drive wheels use `0x80A4` instead. Everything here has been tested somehow. The distinction that matters is how. -**Measured on hardware.** The 4 kHz stream rate on both transports (1000 -packets/sec sustained, no drops, matching Logitech's stated 1 ms interval). -The direct-drive stability fix (steering-axis travel 1258-1703 degrees -before, 204-488 after). The rev-rate default (899 degrees of travel at 25 -against 611 at 35). Which rev-light command each wheel obeys. Which HID++ -features each wheel has. - -The RS50's light strip, end to end: `wheel_rev_level` fills it -proportionally, and custom colours follow what is written across count, -position, global colour, half-and-half and per-LED alternation. The wire -traffic for the rev display matches a G HUB capture from the same model -byte for byte, including the transport (control SET_REPORT). The driver -sends the bare fn2+fn6 level pair and no setup packet, because the arm form -proves fatal to a live native TrueForce session (see -`PROTOCOL_SPECIFICATION.md` section 9). - -The kernel effect tick, on an RS50 with a kprobe on the timer callback: -1000.2 Hz on bare metal, median period 1.000 ms, p99 1.003 ms, no tick -over 1.5 ms. Under a steering force and a TrueForce stream together, 990 -packets/sec with every one accepted at its full 64 bytes and no submission -errors. That leaves no headroom: the wheel is full-speed USB with a -`bInterval=1` interrupt OUT endpoint, which is exactly 1000 packets per -second, so a feature wanting a second packet per tick has to displace one -rather than join it. This is why exactly one program streams to the wheel -at a time, and why the driver stands aside when userspace takes the stream -(`docs/TRUEFORCE_PROTOCOL.md`, "One writer at a time"). +**Measured on hardware.** The 4 kHz sample rate on both transports (1000 +packets per second with four samples each, sustained, no drops, matching +Logitech's stated 1 ms interval). +The direct-drive stability fix (steering-axis travel 1258 to 1703 degrees +before, 204 to 488 after). The rev-rate default (899 degrees of travel at +25 against 611 at 35). Which rev-light command each wheel obeys. Which +HID++ features each wheel has. + +The RS50's light strip, end to end. `wheel_rev_level` fills it in +proportion. Custom colours follow what is written, across count, position, +global colour, half-and-half and per-LED alternation. The wire traffic for +the rev display matches a G HUB capture from the same model byte for byte, +including the transport (control SET_REPORT). The driver sends the bare +fn2+fn6 level pair and no setup packet. The arm form proves fatal to a +live native TrueForce session (see `PROTOCOL_SPECIFICATION.md` section 9). + +The kernel effect tick, on an RS50 with a kprobe (a kernel trace point) on +the timer callback: 1000.2 Hz on bare metal, median period 1.000 ms, p99 +1.003 ms, no tick over 1.5 ms. Under a steering force and a TrueForce +stream together: 990 packets/sec, every one accepted at its full 64 bytes, +no submission errors. That leaves no headroom. The wheel is full-speed USB +with a `bInterval=1` interrupt OUT endpoint. That is exactly 1000 packets +per second. So a feature that wants a second packet per tick has to +displace one, not join it. This is why exactly one program streams to the +wheel at a time. It is also why the driver stands aside when userspace +takes the stream (`docs/TRUEFORCE_PROTOCOL.md`, "One writer at a time"). Telemetry latency through the simulated-TrueForce path, measured off the -wire after fifteen seconds of continuous streaming: a change in engine speed -starts coming out of the wheel 15 ms later and has fully taken over the note -by 90 ms. - -The driver is validated on a KASAN, lockdep, RCU-proving and -timer-object-debugging kernel with the wheel attached: no splats across -probe, repeated bind and unbind, erase-while-playing, arm and disarm churn, -twelve concurrent effects, attribute reads racing an unbind, module unload -during an active stream, or hot-unplug during an active stream. Memory is -flat across all of it. +wire after fifteen seconds of continuous streaming: a change in engine +speed starts to come out of the wheel 15 ms later. It has fully taken over +the note by 90 ms. + +The driver is validated on a debug kernel with the wheel attached. That +kernel runs KASAN (a memory-error detector), lockdep (a lock-order +checker), RCU proving and timer-object debugging. No splats (kernel error +reports) appeared across probe, repeated bind and unbind, +erase-while-playing, arm and disarm churn, twelve concurrent effects, +attribute reads racing an unbind, module unload during an active stream, +or hot-unplug during an active stream. Memory is flat across all of it. **Argued from the code, not exercised.** The rev-limiter dwell fix is -unit-tested against a simulated clock but its end-to-end timing has never -been trustworthily measured, because the bench instrument for it has six -stages between cause and observation. The `hrtimer_init` compatibility path -for kernels older than 6.15 compiles but has not run, because no such kernel +unit-tested against a simulated clock. Its end-to-end timing has never +been measured in a trustworthy way. The bench instrument for it has six +stages between cause and observation. The `hrtimer_init` compatibility +path for kernels older than 6.15 compiles but has not run. No such kernel was available. **Not confirmed at all.** Whether Assetto Corsa Competizione populates -`wheelLoad`, which decides whether the airborne flag ever fires. The +`wheelLoad`. That decides whether the airborne flag ever fires. The airborne haptic layer's gain, which has never been heard. `LOGI_TF_REARM`, -the experimental pre-launch re-arm for a wheel whose session latched, which +the experimental pre-launch re-arm for a wheel whose session latched. It is off by default until it is validated on hardware. ## Known problems -**The force-feedback keepalive is best-effort.** If the wheel's evdev node -cannot be opened, a direct-drive wheel can still drive itself into its stops -while TrueForce streams. The self-test refuses to run in that state; the -daemon carries on. +**The force-feedback keepalive is best-effort.** evdev is the Linux input +event interface. If the wheel's evdev node cannot be opened, a +direct-drive wheel can still drive itself into its stops while TrueForce +streams. The self-test refuses to run in that state. The daemon carries +on. **Low-frequency haptic layers move the wheel rather than buzzing it.** The -pit limiter is 10 Hz, ABS 15 Hz, the rev limiter 25 Hz, and excursion for a -given torque goes roughly as 1/f^2. Their gains were chosen as torque levels -while what is felt is excursion. Deliberately not "fixed" with a frequency -curve: see the reasoning in `effects.rs`, which is that the wheel is -normally held and a hand already damps exactly those frequencies. +pit limiter is 10 Hz, ABS 15 Hz, the rev limiter 25 Hz. Excursion for a +given torque goes roughly as 1/f^2. Their gains were chosen as torque +levels, but what you feel is excursion. This is deliberately not "fixed" +with a frequency curve. `effects.rs` gives the reasoning: the wheel is +normally held, and a hand already damps exactly those frequencies. -**The KF/TF crossover admits texture the wheel can follow.** Anything at or -above 20 Hz routes to the texture channel, and 20-40 Hz is where these -wheels still track the waveform. Flagged rather than moved, because -changing it changes which effects route where. +**The KF/TF crossover admits texture the wheel can follow.** Anything at +or above 20 Hz routes to the texture channel. 20 to 40 Hz is where these +wheels still track the waveform. This is flagged rather than moved, +because changing it changes which effects route where. **A session that dies without its teardown latches the wheel.** The next -TrueForce session opens fine and never streams. Power-cycling the base +TrueForce session opens fine and never streams. A power cycle of the base clears it. **Three features the wheels have and this driver does not use.** `DUAL_CLUTCH`, `GAMING_ATTACHMENTS` and `AXIS_MAPPING`. (`DISPLAY_GAME_DATA`, the base OLED, is driven through `wheel_oled` as of this release.) -Each needs a capture of G HUB exercising the control, and each would be a -non-force write to the HID++ endpoint, which specification 12.5 says cuts -live force. +Each needs a capture of G HUB exercising the control. Each would be a +non-force write to the HID++ endpoint, and specification 12.5 says such a +write cuts live force. ## Waiting on other people - **#27**, Xbox G923 rev lights. The driver reports which features that - wheel has; no owner has run it. Even a positive answer is not sufficient, - because that wheel's force rides HID++ and 12.5 applies. + wheel has. No owner has run it. Even a positive answer is not + sufficient, because that wheel's force rides HID++ and 12.5 applies. - **#52**, Xbox G923 force feedback coming up reliably, on the branch named above. -- **#72**, whether that wheel can be driven by this driver's own engine, - which is what would give it force feedback and TrueForce together. -- **#8**, a G PRO capture, which is what would let the real-G-PRO rev-light +- **#87**, whether this driver's own engine can drive that wheel in every + game. That is what would give it force feedback and TrueForce together. +- **#8**, a G PRO capture. That is what would let the real-G-PRO rev-light work start. - **#20** and **#62**, an OLED descriptor readback (`0x8130` fn1) offered by a Windows implementation. diff --git a/docs/SYSFS_API.md b/docs/SYSFS_API.md index e2ee9ee..3975117 100644 --- a/docs/SYSFS_API.md +++ b/docs/SYSFS_API.md @@ -8,22 +8,26 @@ **Applies to**: the `hid-logitech-dd` driver in this repository. -Most of the attributes documented here are shared between the RS50 and G Pro (the two wheels share the settings code path). Attributes that are currently G Pro-only or RS50-only are called out inline. +This document lists the driver's sysfs attributes. Sysfs is the kernel's settings file tree under `/sys`. Each attribute is a small file. You read a file to get a value and write to it to set one. -The **G923 is different**: none of the `wheel_*` attributes below exist on it. Its classic force-feedback engine has its own, smaller attribute set (`range`, `gain`, `autocenter`, `combine_pedals`, `ffb_output`) plus rev-LED devices under `/sys/class/leds/`; see [G923 Attributes](#g923-attributes-playstation-edition-c266c267) below. +The RS50 and the G Pro share most of the attributes here, because the two wheels share the settings code path. Where an attribute is G Pro-only or RS50-only, the text says so. + +The **G923 is different**. None of the `wheel_*` attributes below exist on it. Its classic force-feedback engine has its own, smaller attribute set: `range`, `gain`, `autocenter`, `combine_pedals` and `ffb_output`. It also has rev-LED devices under `/sys/class/leds/`. See [G923 Attributes](#g923-attributes-playstation-edition-c266c267) below. --- ## Overview -The driver exposes wheel configuration through sysfs attributes located at: +The driver puts the wheel settings in sysfs attributes under this directory: ``` /sys/bus/hid/devices// ``` -Where `` is typically `0003:046D:C276.XXXX` (RS50), `0003:046D:C272.XXXX` (G Pro Xbox/PC), or `0003:046D:C268.XXXX` (G Pro PS/PC). +`` is typically `0003:046D:C276.XXXX` (RS50), `0003:046D:C272.XXXX` (G Pro Xbox/PC), or `0003:046D:C268.XXXX` (G Pro PS/PC). + +The driver talks to the wheel with HID++, Logitech's configuration protocol over USB. Each HID++ setting lives in a feature, named by a hex id such as `0x8137`. A feature has numbered functions, written `fn` in this document. -To find your device path: +To find your device path, run one of these commands: ```bash find /sys/bus/hid/devices -name "*046D*C276*" 2>/dev/null # RS50 find /sys/bus/hid/devices -name "*046D*C27[28]*" 2>/dev/null # G Pro (c272 or c268) @@ -37,10 +41,10 @@ find /sys/bus/hid/devices -name "*046D*C27[28]*" 2>/dev/null # G Pro (c272 or c2 **Access**: Read/Write **Values**: `desktop`, `onboard` -Controls the operating mode of the wheel base. +Selects the operating mode of the wheel base. -- **Desktop mode** (profile 0): Settings controlled by host software. Sensitivity available. -- **Onboard mode** (profiles 1-5): Settings stored in wheel profiles. Brake force available. +- **Desktop mode** (profile 0): The host software controls the settings. Sensitivity is available. +- **Onboard mode** (profiles 1-5): The wheel stores the settings in its profiles. Brake force is available. ```bash # Read current mode @@ -58,7 +62,7 @@ echo "desktop" > wheel_mode **Access**: Read/Write **Values**: `0` (desktop), `1-5` (onboard profiles) -Controls the active profile. Profile 0 is desktop mode; profiles 1-5 are onboard profiles. +Selects the active profile. Profile 0 is desktop mode. Profiles 1-5 are onboard profiles. ```bash # Read current profile @@ -74,17 +78,13 @@ echo 0 > wheel_profile ### Editing an onboard slot -There is no separate "write a whole profile" attribute or protocol. A slot -is authored by making it active (write `wheel_profile`) and then writing -the same per-setting attrs everything else on this page uses - -`wheel_range`, `wheel_strength`, `wheel_trueforce`, `wheel_damping`, -`wheel_ffb_filter`/`wheel_ffb_filter_auto`, `wheel_brake_force`, -`wheel_led_effect`/`wheel_led_brightness`, and `wheel_profile_names` for -the slot's own name. The wheel persists each write to the active slot's -own storage **immediately**, exactly like every other write on this page; -there is no commit/save step afterwards. See -`docs/PROTOCOL_SPECIFICATION.md`'s "Onboard Profile Authoring" section for -the wire-level evidence. +There is no separate "write a whole profile" attribute or protocol. To edit a slot: + +1. Make the slot active: write its number to `wheel_profile`. +2. Write the per-setting attributes that the rest of this page uses: `wheel_range`, `wheel_strength`, `wheel_trueforce`, `wheel_damping`, `wheel_ffb_filter`/`wheel_ffb_filter_auto`, `wheel_brake_force`, `wheel_led_effect`/`wheel_led_brightness`. +3. Write the slot's own name with `wheel_profile_names`. + +The wheel saves each write to the active slot's own storage **immediately**. This is the same as every other write on this page. There is no commit or save step afterwards. See the "Onboard Profile Authoring" section of `docs/PROTOCOL_SPECIFICATION.md` for the wire-level evidence. ```bash # Author slot 3: activate it, then set its values one at a time. @@ -94,27 +94,28 @@ echo 80 > wheel_strength echo "3:RACE NITE" > wheel_profile_names ``` -Two things follow directly from "immediate write, no commit step": +Two things follow from "immediate write, no commit step": -- **Activating a slot changes the wheel's live feel right away.** The - moment `wheel_profile` lands on a slot, the motor runs whatever - strength/damping/range that slot already has stored, before you write +- **Activating a slot changes the wheel's live feel right away.** As soon + as `wheel_profile` lands on a slot, the motor runs the strength, damping + and range that the slot already has stored. This happens before you write anything else. Never do this while driving. - **A half-finished edit cannot be rolled back on the wire.** If a script - or tool is interrupted partway through authoring a slot, whatever was - written so far stays written; there is nothing to "cancel". A caller - that wants an undo path has to read every value it is about to touch - *before* writing anything, so it has something to write back if it needs - to revert. `logi-wheel`'s GUI/TUI "Edit onboard slot" flow does exactly - this (snapshot on entry, an explicit Revert action that replays it); see - `logi_wheel_core::onboard` in the userspace crate for the reusable - implementation. - -Also worth knowing when scripting this: the wheel can be switched to a -different slot from its own OLED menu at any time, including in the -middle of a multi-attribute edit like the one above. Re-read `wheel_profile` -before trusting that a write landed on the slot you intended, rather than -assuming nothing changed underneath you. + or tool stops partway through a slot edit, everything written so far + stays written. There is nothing to "cancel". A caller that wants an undo + path must read every value it is about to touch *before* it writes + anything. It then has something to write back if it needs to revert. + The "Edit onboard slot" flow in the `logi-wheel` GUI and TUI does exactly + this: it takes a snapshot on entry, and an explicit Revert action replays + it. See `logi_wheel_core::onboard` in the userspace crate for the + reusable implementation. + +One more thing matters when you script this. The wheel can switch to a +different slot from its own OLED menu at any time. (The OLED is the small +display on the wheel base.) This can happen in the middle of a +multi-attribute edit like the one above. Re-read `wheel_profile` before +you trust that a write landed on the slot you intended. Do not assume +nothing changed underneath you. --- @@ -123,8 +124,8 @@ assuming nothing changed underneath you. ### wheel_profile_names **Access**: Read/Write -The five onboard slots' names, queried live from the wheel. Use this to -know which slot number `wheel_profile` should get. +The names of the five onboard slots, read live from the wheel. Use this +to find the slot number to write to `wheel_profile`. ```bash cat wheel_profile_names @@ -135,20 +136,21 @@ cat wheel_profile_names # 5: PROFILE 5 ``` -Writing renames one slot, as `:` (feature `0x8137` fn4). The -wheel persists the name to its own NVM on the write; there is no separate -save step. +A write renames one slot. The format is `:` (feature `0x8137` +fn4). The wheel saves the name to its own NVM (non-volatile memory, the +wheel's permanent storage) on the write. There is no separate save step. ```bash # Rename slot 3 echo "3:RACE" > wheel_profile_names ``` -Slot is 1-5. On an RS50 the name may be up to **9 characters** (the same -length as its stock `PROFILE 3`), may contain spaces, and is stored -**uppercased** - `echo "3:Race"` reads back as `3: RACE`. A longer name is -refused by the wheel itself and surfaces as `-EIO`; a bad slot, an empty -name, or one over the 14-byte HID++ payload gives `-EINVAL`. +The slot is 1-5. On an RS50 the name may be up to **9 characters**, the +same length as its stock `PROFILE 3`. It may contain spaces. The wheel +stores it **uppercased**: `echo "3:Race"` reads back as `3: RACE`. The +wheel itself refuses a longer name, and the write returns `-EIO`. A bad +slot, an empty name, or a name over the 14-byte HID++ payload gives +`-EINVAL`. ### wheel_range **Access**: Read/Write @@ -165,83 +167,100 @@ cat wheel_range echo 540 > wheel_range ``` -On the G923 Xbox edition under `g923_xbox_dd_engine=1` the range is read -from and written to the wheel's classic force-feedback feature (0x8123), -the same one the default path uses, and is clamped to `180` to `900`: it -is a gear-driven wheel. The attribute reports what the wheel answered at -probe, not a direct-drive default. - -This governs the ordinary DirectInput/evdev axis and the soft endstop. It -does **not** constrain the axis Logitech's TrueForce SDK exposes over raw -HID: that path always presents the wheel's full mechanical range (2700 on -the RS50), whatever this is set to. So in a game running with TrueForce -(raw HID on), set the game's steer lock / rotation to the wheel's maximum -and let the game apply each car's own ratio, which is the usual direct-drive -setup; matching this value in the game is only correct on the non-TrueForce -path. - -On the G PRO PID (`046d:c272` / `046d:c268`) - both real G PRO and -RS50-in-compat - the standard HID++ range feature is not advertised -at the index the native code expects; the driver falls back to -feature `0x8138` (index 0x18, fn 2) captured from G Hub. See -`docs/PROTOCOL_SPECIFICATION.md` section 5.1. The fallback -write only takes effect while the wheel is in desktop mode; the -wheel boots in onboard mode, so write `0` to `wheel_profile` first -to enter desktop mode and have subsequent range writes take effect -on the motor. - -**External-change detection**: some game launches (observed with -Assetto Corsa EVO under Proton) reset the wheel's physical range to -90 degrees without any HID++ notification. The driver re-reads the -true range from the wheel every 20 seconds (paused while force -feedback is actively playing, so the synchronous query can never -stall the force stream; it catches up within one interval of the -effects stopping); if it changed externally, -the reported `wheel_range` value is updated to the real one, the -change is logged in dmesg (`rotation range changed externally`), and -`poll()`ers on the attribute are notified via `sysfs_notify()`. -When the external value is exactly 90 (the known SDK session-init -pathology - see `wheel_range_restore` below), the driver also -restores the previous range automatically. +On the G923 Xbox edition under `g923_xbox_dd_engine=1`, the driver reads +and writes the range through the wheel's classic force-feedback feature +(0x8123). The default path uses the same feature. The range is clamped to +`180` to `900`, because it is a gear-driven wheel. The attribute reports +what the wheel answered at probe, not a direct-drive default. (Probe is the +moment the driver first binds to the wheel.) + +This range governs the ordinary DirectInput/evdev axis and the soft +endstop. (DirectInput is the Windows game input API. Evdev is the Linux +input event interface.) It does **not** limit the axis that Logitech's +TrueForce SDK sees over raw HID. (TrueForce is Logitech's audio-driven +haptic channel. The SDK is the software kit games use to drive it. Raw +HID, or hidraw, is direct device access that bypasses the input layer.) +That path always presents the wheel's full mechanical range, 2700 on the +RS50, whatever this attribute is set to. So in a game that runs with TrueForce (raw HID +on), set the game's steer lock or rotation to the wheel's maximum. Then +let the game apply each car's own ratio. That is the usual direct-drive +setup. Matching this value in the game is only correct on the +non-TrueForce path. + +On the G PRO PID (`046d:c272` / `046d:c268`), the standard HID++ range +feature is not advertised at the index the native code expects. This +applies both to a real G PRO and to an RS50 in compat mode. (Compat mode +is when the RS50 enumerates with the G PRO's product id.) The driver falls +back to feature `0x8138` (index 0x18, fn 2), captured from G Hub. (G Hub +is Logitech's Windows configuration app.) See +`docs/PROTOCOL_SPECIFICATION.md` section 5.1. The fallback write only +takes effect while the wheel is in desktop mode. The wheel boots in +onboard mode. So write `0` to `wheel_profile` first to enter desktop mode. +Range writes after that take effect on the motor. + +**External-change detection**: some game launches reset the wheel's +physical range to 90 degrees without any HID++ notification. This was +observed with Assetto Corsa EVO under Proton. (Proton is Valve's +Wine-based layer that runs Windows games on Linux.) The driver re-reads +the true range from the wheel every 20 seconds. It pauses this while force +feedback is actively playing, so the synchronous query can never stall the +force stream. It catches up within one interval after the effects stop. +If the range changed externally, the driver does three things: + +1. It updates the reported `wheel_range` value to the real one. +2. It logs the change in dmesg, the kernel log (`rotation range changed externally`). +3. It wakes any program that waits on the attribute with `poll()`, via `sysfs_notify()`. + +When the external value is exactly 90, the driver also restores the +previous range automatically. The value 90 is the known SDK session-init +problem; see `wheel_range_restore` below. ### wheel_range_restore **Access**: Read/Write **Values**: `0` or `1` **Default**: `1` -Automatic recovery from the launch-time 90-degree reset. Root cause -(usbmon-verified): some games' SDK sessions push an operating range -of 90 degrees once at session start via a TrueForce interface-2 -packet, invisible to HID++. With this enabled, the driver restores -the pre-reset range automatically. Verified end-to-end against a -faithful reproduction of the game traffic: detection to restore in -under 100 ms once the poll samples the change. - -Safety gates, each earned from a real incident: -- fires only for an EXTERNAL silent change landing exactly on 90; - any other externally-set value (a game applying its configured - steering lock: 540, 850, ...) is respected as legitimate intent; -- desktop mode only, and never an automatic mode switch; -- the wheel must be stationary (two encoder reads 50 ms apart); - restores only ever widen the range, which cannot snap the wheel; -- at most 3 restores per session, then the driver logs and yields - (`an external writer keeps changing the rotation range`); -- an explicit `wheel_range` write supersedes any pending restore - and resets the strike counter. - -`0` = detect-and-report only: the -change is still logged and `wheel_range` stays honest, but recovery -is manual (`wheel_profile=0` then `wheel_range=` once FFB -is idle). The same opt-out also governs the push-triggered one-shot -restore performed when the interceptor sees the SDK's type-`0x0e` -range push directly (`docs/TRUEFORCE_PROTOCOL.md`): `0` means -detect-only for both mechanisms, not just the poll-based one. - -Both mechanisms act only on a push of exactly 90 degrees, the value the -SDK sends when nothing answered its rotation question. Any other pushed -value is a game applying its own steering lock through an SDK that was -answered (the launcher's proxy does that), and it is left in place so the -game's setting moves the wheel as it does on Windows. +Automatic recovery from the launch-time 90-degree reset. The root cause +is verified with usbmon, the kernel's USB traffic capture. Some games' +SDK sessions push an operating range of 90 degrees once at session start. +They send it as a TrueForce interface-2 packet, which HID++ cannot see. +With this attribute enabled, the driver restores the pre-reset range +automatically. This is verified end-to-end against a faithful +reproduction of the game traffic. Detection to restore takes under 100 ms +once the poll samples the change. + +Safety gates, each one earned from a real incident: +- The restore fires only for an EXTERNAL silent change that lands + exactly on 90. The driver respects any other externally-set value as + legitimate intent, for example a game applying its configured steering + lock (540, 850, ...). +- It works in desktop mode only. It never switches the mode automatically. +- The wheel must be stationary (two encoder reads 50 ms apart). The + encoder is the sensor that measures the wheel's position. A restore + only ever widens the range, which cannot snap the wheel. +- The driver does at most 3 restores per session. Then it logs + `an external writer keeps changing the rotation range` and yields. +- An explicit `wheel_range` write supersedes any pending restore and + resets the strike counter. + +`0` = detect-and-report only. The driver still logs the change, and +`wheel_range` stays honest. Recovery is manual. To recover by hand: + +1. Wait until FFB (force feedback) is idle. +2. Write `0` to `wheel_profile`. +3. Write the degrees you want to `wheel_range`. + +The same opt-out also governs the push-triggered one-shot restore. The +driver performs that restore when the interceptor sees the SDK's +type-`0x0e` range push directly (`docs/TRUEFORCE_PROTOCOL.md`). So `0` +means detect-only for both mechanisms, not just the poll-based one. + +Both mechanisms act only on a push of exactly 90 degrees. That is the +value the SDK sends when nothing answered its rotation question. Any other +pushed value is a game applying its own steering lock through an SDK that +was answered (the launcher's proxy does that). The driver leaves such a +value in place. The game's setting then moves the wheel as it does on +Windows. ### wheel_strength **Access**: Read/Write @@ -249,9 +268,9 @@ game's setting moves the wheel as it does on Windows. Sets the force feedback strength. -**Internal encoding**: The driver converts percentage to a 16-bit value where: +**Internal encoding**: The driver converts the percentage to a 16-bit value: - 0% = 0x0000 -- 100% = 0xFFFF (corresponds to 8.0 Nm max torque) +- 100% = 0xFFFF (this is the 8.0 Nm maximum torque) ```bash # Read current strength @@ -266,9 +285,9 @@ echo 50 > wheel_strength **Access**: Read/Write **Values**: `0` to `100` (percentage) -Sets the wheel damping (resistance when turning). +Sets the wheel damping, the resistance you feel when you turn the wheel. -**Internal encoding**: The driver scales the 0-100 percentage to a 16-bit big-endian value (`value = percentage * 65535 / 100`) and writes it to page `0x8133` with SET fn=1. See `docs/PROTOCOL_SPECIFICATION.md` section 5. +**Internal encoding**: The driver scales the 0-100 percentage to a 16-bit big-endian value (`value = percentage * 65535 / 100`). It writes the value to page `0x8133` with SET fn=1. See `docs/PROTOCOL_SPECIFICATION.md` section 5. ```bash # Read current damping @@ -282,7 +301,7 @@ echo 25 > wheel_damping **Access**: Read/Write **Values**: `0` to `100` (percentage) -Sets the TRUEFORCE bass shaker intensity. +Sets the TRUEFORCE bass shaker intensity. This is the strength of the vibration the wheel plays from TrueForce audio. ```bash # Read current TRUEFORCE level @@ -300,9 +319,9 @@ echo 0 > wheel_trueforce **Values**: `0` to `100` (percentage) **Mode Restriction**: **Onboard mode only** -Sets the brake pedal force threshold (load cell sensitivity). +Sets the brake pedal force threshold. This is the sensitivity of the load cell, the pressure sensor in the brake pedal. -**Note**: Returns `-EPERM` (Permission denied) in desktop mode. +**Note**: A write returns `-EPERM` (Permission denied) in desktop mode. ```bash # Set brake force to 75% (must be in onboard mode) @@ -315,21 +334,24 @@ echo 75 > wheel_brake_force **Values**: `0` to `100` (percentage) **Mode Restriction**: Writes only accepted in **desktop mode**; reads always succeed. -Bends the steering response curve via feature `0x80A4` -(AxisResponseCurve): a 64-point cubic Bezier from (0,0) to (1,1) with -control points P1=(1-s, s), P2=(s, 1-s) for s = value/100. Values below -`50` soften the response near centre; values above `50` sharpen it. `50` -is the identity curve, so the driver reverts to the wheel's built-in -curve (as G Hub does) rather than uploading a flat line. - -This is unrelated to LED brightness. Feature `0x8040` (behind -`wheel_led_brightness`) is brightness only; sensitivity and brightness are -fully independent. - -Reads return the last value written, defaulting to `50`. The wheel has no -read-back for the slider, so this is a write-through cache. Writes in -onboard mode fail with `-EPERM`; if the wheel does not expose the -response-curve feature, writes return `-EOPNOTSUPP`. +Bends the steering response curve through feature `0x80A4` +(AxisResponseCurve). A response curve maps the wheel's real position to +the position it reports. The curve is a 64-point cubic Bezier from (0,0) +to (1,1). (A Bezier is a smooth curve defined by control points.) The +control points are P1=(1-s, s) and P2=(s, 1-s), where s = value/100. +Values below `50` soften the response near centre. Values above `50` +sharpen it. `50` is the identity curve. For `50` the driver reverts to +the wheel's built-in curve, as G Hub does, instead of uploading a flat +line. + +This is unrelated to LED brightness. Feature `0x8040`, behind +`wheel_led_brightness`, is brightness only. Sensitivity and brightness +are fully independent. + +A read returns the last value written. The default is `50`. The wheel has +no read-back for the slider, so this is a write-through cache. A write in +onboard mode fails with `-EPERM`. If the wheel does not expose the +response-curve feature, a write returns `-EOPNOTSUPP`. ```bash # Sharpen the centre response (must be in desktop mode) @@ -341,9 +363,9 @@ echo 65 > wheel_sensitivity **Access**: Read/Write **Values**: `1` to `15` (filter level) -Sets the force feedback smoothing/filtering level. G Hub's labels are roughly Minimum (1), Low (7), Medium (11), Maximum (15). +Sets the force feedback smoothing (filter) level. G Hub's labels are roughly Minimum (1), Low (7), Medium (11), Maximum (15). -Values outside `1..15` are clamped to that range. +The driver clamps values outside `1..15` to that range. ```bash # Read current filter level @@ -357,9 +379,9 @@ echo 11 > wheel_ffb_filter **Access**: Read/Write **Values**: `0` (manual), `1` (auto) -Enables automatic FFB filter adjustment based on game output. +Enables automatic FFB filter adjustment based on the game's output. -The driver splits the two on-wire meanings of the filter flag byte across two sysfs writes: writing to `wheel_ffb_filter` stamps the "user set this level right now" bit, writing here toggles only the "auto mode" bit. See `docs/PROTOCOL_SPECIFICATION.md` section 5 (FFB Filter) for the bitfield decode. +The filter flag byte on the wire has two meanings. The driver splits them across two sysfs writes. A write to `wheel_ffb_filter` stamps the "user set this level right now" bit. A write here toggles only the "auto mode" bit. See `docs/PROTOCOL_SPECIFICATION.md` section 5 (FFB Filter) for the bitfield decode. ```bash # Enable auto filter @@ -371,15 +393,17 @@ echo 0 > wheel_ffb_filter_auto ### wheel_ffb_game_gain -Read-only. The force-feedback strength the running game has asked for, as -a percentage, which is `FF_GAIN` arriving through evdev when a game's own -force-feedback slider moves. 100 until a game lowers it. +Read-only. The force-feedback strength the running game has asked for, +as a percentage. This is the `FF_GAIN` value that arrives through evdev +when a game's own force-feedback slider moves. It is 100 until a game +lowers it. -Not a setting, and not the wheel's own strength: this is the game's, and -it is published so that everything the wheel does on that game's behalf -can follow it. `logi-tf-sim` scales its synthesized haptics by this, so a -title with no TrueForce of its own still obeys the slider a driver -reaches for (`follow_game_gain` in `tf-sim.conf` turns that off). +This is not a setting, and it is not the wheel's own strength. It is the +game's value. The driver publishes it so that everything the wheel does on +that game's behalf can follow it. `logi-tf-sim` scales its synthesized +haptics by this value. So a title with no TrueForce of its own still obeys +the slider a driver reaches for. `follow_game_gain` in `tf-sim.conf` turns +that off. ```bash cat "$H/wheel_ffb_game_gain" # 100 with nothing running @@ -390,45 +414,46 @@ cat "$H/wheel_ffb_game_gain" # 100 with nothing running **Values**: `0` or `1` **Default**: `1` -Controls whether the driver inverts the sign of every `FF_CONSTANT` -level before sending it to the wheel. This single toggle is what makes -the driver's FFB feel right under both Wine/Proton games and native -Linux apps - the two paths disagree on sign by one flip somewhere in -Wine's DirectInput-to-evdev translation layer, and the driver can't -tell them apart at runtime. +Selects whether the driver inverts the sign of every `FF_CONSTANT` +level before it sends the level to the wheel. (`FF_CONSTANT` is the evdev +constant-force effect type.) This single toggle makes the driver's FFB +feel right under both Wine/Proton games and native Linux apps. The two +paths disagree on sign by one flip somewhere in Wine's +DirectInput-to-evdev translation layer. The driver cannot tell them apart +at runtime. - `1` (default) - invert. Correct for Wine/Proton running Windows games (Assetto Corsa Competizione, etc.). If `FF_CONSTANT` feels like centring forces push the wheel *away* from centre instead of back toward it, the toggle is at the wrong setting. - `0` - pass-through. Correct for native Linux evdev apps that - upload effects with the convention documented in - `Documentation/input/ff.rst` (direction=0x4000 east, positive - level = rightward force). `fftest`, `ffcfstress`, and direct - EVIOCSFF uploads from custom tools are in this category. + upload effects with the convention in `Documentation/input/ff.rst` + (direction=0x4000 east, positive level = rightward force). + `fftest`, `ffcfstress`, and direct EVIOCSFF uploads from custom + tools are in this category. -Only affects `FF_CONSTANT`. All other effect types (`FF_SPRING`, +This only affects `FF_CONSTANT`. All other effect types (`FF_SPRING`, `FF_DAMPER`, `FF_FRICTION`, `FF_INERTIA`, `FF_RAMP`, `FF_PERIODIC`, `FF_RUMBLE`) feel identical at either toggle value. -**Caveat for reverse driving**: the inversion is unconditional - it -does not look at the wheel's velocity or the car's gear. In sims that -correctly model the self-aligning torque flipping sign at negative -longitudinal velocity (most modern racing sims do), the chain is -"sim physics-inverts for reverse โ†’ Wine inverts again โ†’ driver inverts -again", which lands as physics-correct destabilising FFB the user -feels as the wheel actively pushing away from centre when reversing. -That is the real-car behaviour and not a driver bug, but it can feel -violent compared to a wheel without TF / direct-drive force. Lowering -`wheel_strength` is the only knob from the driver side; switching the -sign toggle off would make forward driving feel wrong without fixing -the reverse case. - -A contributor cross-checked this on Windows (issue #8, AC EVO and AC): -the FFB "gets pretty violent in reverse" there too, with the same wheel +**Caveat for reverse driving**: the inversion is unconditional. It does +not look at the wheel's velocity or the car's gear. Most modern racing +sims correctly model the self-aligning torque flipping sign at negative +longitudinal velocity. In those sims the chain is: the sim physics +inverts for reverse, then Wine inverts again, then the driver inverts +again. The result is physics-correct destabilising FFB. The user feels +it as the wheel actively pushing away from centre when reversing. That is +the real-car behaviour and not a driver bug. But it can feel violent +compared to a wheel without TF / direct-drive force. Lowering +`wheel_strength` is the only knob on the driver side. Switching the sign +toggle off would make forward driving feel wrong without fixing the +reverse case. + +A contributor cross-checked this on Windows (issue #8, AC EVO and AC). +The FFB "gets pretty violent in reverse" there too, with the same wheel and game settings. So the strong reverse force is the sim's physics -surfacing through the wheel, identical to the Windows G Hub path, not a -sign error or double-inversion on our side. +surfacing through the wheel. It is identical to the Windows G Hub path. +It is not a sign error or a double inversion on our side. ```bash # Playing Wine/Proton racing games: leave default @@ -438,9 +463,9 @@ cat wheel_ffb_constant_sign # -> 1 echo 0 | sudo tee wheel_ffb_constant_sign ``` -The inversion is confirmed empirically on Assetto Corsa Competizione with this -wheel; a test harness in `tests/ff_matrix_test.c` cross-checks each toggle value -against native evdev expectations. +The inversion is confirmed by testing on Assetto Corsa Competizione with +this wheel. A test harness in `tests/ff_matrix_test.c` cross-checks each +toggle value against native evdev expectations. ### wheel_spring_damping **Access**: Read/Write @@ -448,19 +473,20 @@ against native evdev expectations. **Default**: `25` **Availability**: all direct-drive wheels (RS50 native/compat and real G PRO - every family PID runs the same `hidpp_dd_ff_*` FFB path). -Synthetic damping applied to emulated `FF_SPRING` effects, as a -percentage of a `FF_DAMPER` running the spring's own coefficient. - -The driver emulates condition effects host-side: it samples the wheel -position and pushes the computed force back over USB. That loop -latency on a low-friction direct-drive motor makes a stiff, undamped -game-uploaded spring ring - a growing back-and-forth oscillation that -ends with the wheel's over-torque failsafe cutting power (observed -live with Assetto Corsa EVO's map-load centring spring). Real wheels -damp the spring inside the firmware servo loop; this knob restores -that behaviour. `0` disables it. The damping -scales with the spring's own coefficient, so stiff springs get -proportionally stronger damping. +Synthetic damping that the driver applies to emulated `FF_SPRING` +effects. It is a percentage of a `FF_DAMPER` that runs at the spring's +own coefficient. + +The driver emulates condition effects on the host side. It samples the +wheel position and pushes the computed force back over USB. That loop +has latency. On a low-friction direct-drive motor, the latency makes a +stiff, undamped spring from a game ring. The ring is a growing +back-and-forth oscillation. It ends when the wheel's over-torque +failsafe cuts power. This was observed live with Assetto Corsa EVO's +map-load centring spring. Real wheels damp the spring inside the +firmware servo loop. This knob restores that behaviour. `0` disables it. +The damping scales with the spring's own coefficient, so stiff springs +get proportionally stronger damping. ```bash cat wheel_spring_damping # -> 25 @@ -473,52 +499,52 @@ echo 40 > wheel_spring_damping **Default**: `tf` **Availability**: all direct-drive wheels (RS50 native/compat and real G PRO - every family PID runs the same `hidpp_dd_ff_*` FFB path). -Selects where vibration-class effects - `FF_RUMBLE` and periodic -effects at 20 Hz or faster (period <= 50 ms) - are actuated: +Selects where the driver plays vibration-class effects. These are +`FF_RUMBLE` and periodic effects at 20 Hz or faster (period <= 50 ms). - `tf` (default) - the driver streams them on the wheel's TrueForce - audio-haptic channel (interface 2, ~1 kHz sample rate), the same - physical path the Windows SDK uses for texture. Steering-shaping + audio-haptic channel (interface 2, ~1 kHz sample rate). This is the + same physical path the Windows SDK uses for texture. Steering effects (`FF_CONSTANT`, conditions, slow periodics) stay on the - force channel, so rumble does not modulate the steering axis. - This matches the Windows KF/TF split; the "gritty/notchy steering + force channel. So rumble does not modulate the steering axis. + This matches the Windows KF/TF split. The "gritty/notchy steering under rumble" reported in issue #8 is the `kf` behaviour. -- `kf` - legacy: everything is summed into the single steering - force. Kept as a fallback and for A/B comparison. +- `kf` - legacy. The driver sums everything into the single steering + force. It is kept as a fallback and for A/B comparison. -The TrueForce session is brought up lazily: the first time a +The driver brings up the TrueForce session lazily. The first time a texture-class effect actually plays, the driver replays the captured -68-packet init sequence twice (G Hub behaviour) and then streams -unified packets at 500 Hz while texture effects are active - each -packet carries the steering-force sum in its preamble and four -texture-audio window slots (2 kHz slot rate), the same layout AC EVO -streams (dmesg: `TrueForce texture channel ready`). Wheels that never see texture -effects never see TF traffic. If the init fails, texture effects -fall back to the steering channel - degraded feel, never lost - and -the driver retries on a later texture playback (up to 3 attempts per -session, logged in dmesg). - -An effect's channel is decided when its playback starts and held for -the whole play cycle, so re-parametrising a playing effect across the -20 Hz crossover (or the session init completing mid-play) never yanks -a live effect between channels. Playbacks started before the session -is ready ride the steering channel for their duration; the next -playback moves to the TF stream. - -Texture amplitude respects `FF_GAIN` and `wheel_strength` (the wheel -firmware scales steering forces by the strength setting itself but -plays TF samples at face value, so the driver applies strength to -texture in software for consistency), and is additionally capped at -half of full scale: above roughly 0.5-0.7 FS the wheel's DSP crosses -from vibration into pulling the steering axis, so the cap keeps a -synthetic full-scale rumble from hijacking steering torque. Real -games stream texture far below the cap. - -Note for SDK games (ACC, AC EVO with the TrueForce shim): those -stream TrueForce themselves via hidraw and normally do not send -evdev rumble at the same time, so the two streams do not meet. If a -game somehow does both, set `kf` to keep the wheel's TF input to a -single writer. +68-packet init sequence twice. This is G Hub behaviour. It then streams +unified packets at 1 kHz while texture effects are active. Each packet +carries the steering-force sum in its preamble and four texture-audio +window slots (2 kHz slot rate). This is the same layout AC EVO streams. +The kernel log shows `TrueForce texture channel ready`. A wheel that +never sees texture effects never sees TF traffic. If the init fails, +texture effects fall back to the steering channel. The feel is degraded, +never lost. The driver retries on a later texture playback, up to 3 +attempts per session, and logs each attempt in dmesg. + +The driver decides an effect's channel when its playback starts. It holds +that channel for the whole play cycle. So re-parametrising a playing +effect across the 20 Hz crossover never yanks a live effect between +channels. The same is true when the session init completes mid-play. +Playbacks that start before the session is ready ride the steering +channel for their duration. The next playback moves to the TF stream. + +Texture amplitude respects `FF_GAIN` and `wheel_strength`. The wheel +firmware scales steering forces by the strength setting itself, but it +plays TF samples at face value. So the driver applies strength to texture +in software for consistency. The amplitude is also capped at half of +full scale. Above roughly 0.5-0.7 FS the wheel's DSP (its signal +processor) crosses from vibration into pulling the steering axis. The +cap keeps a synthetic full-scale rumble from hijacking steering torque. +Real games stream texture far below the cap. + +Note for SDK games (ACC, AC EVO with the TrueForce shim): those games +stream TrueForce themselves via hidraw. They normally do not send evdev +rumble at the same time, so the two streams do not meet. If a game +somehow does both, set `kf`. That keeps the wheel's TF input to a single +writer. ```bash cat wheel_texture_route # -> tf @@ -529,16 +555,17 @@ echo kf > wheel_texture_route # A/B back to the legacy mixing **Access**: Read/Write **Values**: `0` or `1` **Default**: `0` -**Availability**: all direct-drive wheels (RS50 native/compat and real G PRO - every family PID runs the same `hidpp_dd_ff_*` FFB path). Backed by the native texture-merge interceptor on interface 2: if it is not installed (interface 2 not yet bound, or already torn down), reads back `0` and writes fail with `-ENODEV`. - -Master switch for the native texture merge. When `1`, outgoing SDK -stream packets on interface 2 that carry no audio samples get engine -texture spliced in (synthesised from `wheel_texture_rpm`, fitted to -the Windows capture in `docs/TF_TEXTURE_RECIPE.md`). The base force -bytes are never modified. With no fresh RPM (200 ms staleness window) -or below 300 rpm the stream passes through untouched. Turning it off -also zeroes the internal sample-debt counter, so re-enabling starts -clean rather than bursting queued samples. +**Availability**: all direct-drive wheels (RS50 native/compat and real G PRO - every family PID runs the same `hidpp_dd_ff_*` FFB path). Backed by the native texture-merge interceptor on interface 2. If the interceptor is not installed (interface 2 not yet bound, or already torn down), reads give `0` and writes fail with `-ENODEV`. + +Master switch for the native texture merge. When `1`, the driver splices +engine texture into outgoing SDK stream packets on interface 2 that +carry no audio samples. The texture is synthesised from +`wheel_texture_rpm` and fitted to the Windows capture in +`docs/TF_TEXTURE_RECIPE.md`. The driver never modifies the base force +bytes. With no fresh RPM (200 ms staleness window), or below 300 rpm, +the stream passes through untouched. Turning the switch off also zeroes +the internal sample-debt counter. So re-enabling starts clean instead of +bursting queued samples. ```bash cat wheel_tf_merge # -> 0 @@ -551,22 +578,21 @@ echo 1 > wheel_tf_merge **Default**: `0 0 0` **Availability**: same as `wheel_tf_merge`, including the NULL-shim fallback (reads back `0 0 0`, writes fail with `-ENODEV`). -Live engine RPM feed for the texture merge. Normally written by -logi-rpm-bridge at roughly 60 Hz from the game's telemetry relay; -writable by hand for bench tests. `age_ms` on read is how long ago the -value was last written, and is what `wheel_tf_merge` checks against -its 200 ms staleness window. - -Besides writing `rpm max_rpm` here, logi-rpm-bridge also drives -`wheel_rev_level` from the same telemetry. The default mapping is a -full rev bar: LED 1 lights as soon as rpm > 0 and all 10 are lit at -the limiter (works for legacy 28-byte relay senders too). -`LOGI_REV_MODE=shift` selects the dash band instead: dark below the -first-shift-light rpm, level 1 exactly there, 10 at the limiter (needs -the 32-byte relay form that carries the first-shift-light rpm). -`LOGI_REV_SYSFS` overrides the LED target attribute and -`LOGI_RPM_PORT` the UDP port. The strip darkens on telemetry loss -(1 s) and on bridge exit. +Live engine RPM feed for the texture merge. Normally logi-rpm-bridge +writes it at roughly 60 Hz from the game's telemetry relay. You can also +write it by hand for bench tests. `age_ms` on read is how long ago the +value was last written. `wheel_tf_merge` checks this age against its +200 ms staleness window. + +logi-rpm-bridge also drives `wheel_rev_level` from the same telemetry. +The default mapping is a full rev bar: LED 1 lights as soon as rpm > 0, +and all 10 are lit at the limiter. This works for legacy 28-byte relay +senders too. `LOGI_REV_MODE=shift` selects the dash band instead: dark +below the first-shift-light rpm, level 1 exactly there, 10 at the +limiter. The dash band needs the 32-byte relay form that carries the +first-shift-light rpm. `LOGI_REV_SYSFS` overrides the LED target +attribute. `LOGI_RPM_PORT` overrides the UDP port. The strip darkens on +telemetry loss (1 s) and on bridge exit. ```bash cat wheel_texture_rpm # -> 6500 14000 12 @@ -580,7 +606,7 @@ echo "6500 14000" > wheel_texture_rpm **Availability**: same as `wheel_tf_merge`, including the NULL-shim fallback (reads back `0`, writes fail with `-ENODEV`). Texture amplitude as a percentage of the capture fit. `0` silences -the texture, `200` doubles it. +the texture. `200` doubles it. ```bash cat wheel_texture_intensity # -> 100 @@ -593,11 +619,11 @@ echo 150 > wheel_texture_intensity **Default**: `4` **Availability**: same as `wheel_tf_merge`, including the NULL-shim fallback (reads back `0`, writes fail with `-ENODEV`). -Cylinder count for the firing-frequency model driving the texture -synthesis (`f0 = rpm/60 * cylinders/2`). Treat it as a feel knob, not -a realism setting: rim excursion falls as 1/f^2, so higher counts push -the firing frequency across the rev range above what a direct-drive -rim can physically express, and the texture fades out of reach. +Cylinder count for the firing-frequency model that drives the texture +synthesis (`f0 = rpm/60 * cylinders/2`). Treat it as a feel knob, not a +realism setting. Rim excursion falls as 1/f^2. So higher counts push the +firing frequency, across the rev range, above what a direct-drive rim can +physically express. The texture then fades out of reach. ```bash cat wheel_texture_cylinders # -> 4 @@ -609,17 +635,19 @@ echo 6 > wheel_texture_cylinders **Values**: `0` to `65535` (raw encoder position) **Availability**: RS50 and G Pro. Returns `-EOPNOTSUPP` if the wheel does not expose page `0x812C` on sub-device `0x05` (no known variant lacks it, but the driver does not assume). -Low-level primitive: writes the given raw 16-bit encoder value to adopt -as the new centre. The driver sends `10 05 3D 00` to -HID++ sub-device `0x05`, feature page `0x812C` (see -`docs/PROTOCOL_SPECIFICATION.md` section 5 for the wire format). -Verified on RS50 from `2026-04-22_re_calibrate.pcapng`. +Low-level primitive. It writes the given raw 16-bit encoder value, which +the wheel adopts as the new centre. The driver sends +`10 05 3D 00` to HID++ sub-device `0x05`, feature page +`0x812C`. (A sub-device is a HID++ address for one part of the wheel, +such as the motor unit.) See `docs/PROTOCOL_SPECIFICATION.md` section 5 +for the wire format. Verified on RS50 from +`2026-04-22_re_calibrate.pcapng`. -Use this only if you already have the raw encoder value you want to -make the centre (e.g., you read it via a HID++ GET yourself, or you -want to seed a specific reference value). For the common case ("make -the wheel's current physical position the new centre") use -`wheel_calibrate_here` below, which does the GET+SET internally. +Use this only if you already have the raw encoder value you want as the +centre. For example, you read it via a HID++ GET yourself, or you want +to seed a specific reference value. For the common case, "make the +wheel's current physical position the new centre", use +`wheel_calibrate_here` below. It does the GET+SET internally. ```bash # Low-level: you already have the raw encoder number you want. @@ -632,28 +660,30 @@ echo 32768 > wheel_calibrate **Availability**: same as `wheel_calibrate` One-shot "use the wheel's current physical position as the new centre". -The driver issues fn=1 GET to read the current raw encoder value, then -fn=3 SET with that value. Mirrors what G Hub does when the user clicks -Calibrate on Windows. Hold the wheel at the desired centre (typically -true centre), then write to this attribute. +The driver issues fn=1 GET to read the current raw encoder value. It +then issues fn=3 SET with that value. This mirrors what G Hub does when +the user clicks Calibrate on Windows. To use it: + +1. Hold the wheel at the centre you want (typically true centre). +2. Write to this attribute. ```bash # Hold the wheel at true physical centre, then: echo 1 > wheel_calibrate_here ``` -No state is stored in the driver; the wheel's firmware persists the new -centre across power cycles (same as G Hub on Windows). +The driver stores no state. The wheel's firmware keeps the new centre +across power cycles, the same as G Hub on Windows. --- ## LIGHTSYNC LED Control -The RS50 has 10 RGB LEDs in a horizontal strip across the upper faceplate (an engine-RPM / shift indicator). The driver provides per-slot configuration with 5 custom slots (0-4). +The RS50 has 10 RGB LEDs in a horizontal strip across the upper faceplate. (RGB means each LED mixes red, green and blue, so it can show any colour.) The strip is an engine-RPM / shift indicator. The driver provides per-slot configuration with 5 custom slots (0-4). -> **Per-model availability**: the `wheel_led_*` LIGHTSYNC attributes exist on the RS50 in both native and G-PRO-compat enumeration (the RS50's faceplate LED-strip hardware doesn't change with the PID; verified live 2026-04-29). On a **real G PRO Racing Wheel** they are hidden: that rim has level-based rev lights with no per-LED RGB, exposed as `wheel_rev_level` instead (see its entry below). +> **Per-model availability**: the `wheel_led_*` LIGHTSYNC attributes exist on the RS50 in both native and G-PRO-compat enumeration. The RS50's faceplate LED-strip hardware does not change with the PID (the USB product id). Verified live 2026-04-29. On a **real G PRO Racing Wheel** they are hidden. That rim has level-based rev lights with no per-LED RGB. The driver exposes them as `wheel_rev_level` instead (see its entry below). > -> **G PRO PID (`046d:c272` / `046d:c268`)**: covers both real G PRO Racing Wheel and RS50-in-G-PRO-compat-mode. Both run through the same `hidpp_dd_ff_*` code path and expose the same wheel-config surface; the LED attributes differ per rim (see the per-model note above - the driver tells the two apart by USB product string). On the RS50 in compat mode, LIGHTSYNC works the same way as native - feature `0x807A` is advertised at the same index discovery picks up in native, and `wheel_led_*` writes drive the LED strip end-to-end (verified against the live wheel 2026-04-29). Wheel-config attributes that work via fallback feature paths (see `docs/PROTOCOL_SPECIFICATION.md` section 5.1): `wheel_range`, `wheel_strength`, `wheel_trueforce`, `wheel_damping`, `wheel_ffb_filter`, `wheel_profile` (write `0` to enter desktop mode), and `wheel_calibrate`. The remaining attributes (`wheel_brake_force`, `wheel_ffb_filter_auto`, `wheel_sensitivity`) are unsupported by this firmware: once their mode gating is satisfied the store returns `-EOPNOTSUPP` (note `wheel_brake_force` still returns `-EPERM` in desktop mode and `wheel_sensitivity` in onboard mode before that check). For those, configure via the wheel's OLED menu or via Windows G Hub on a Windows host. +> **G PRO PID (`046d:c272` / `046d:c268`)**: covers both the real G PRO Racing Wheel and the RS50 in G PRO compat mode. Both run through the same `hidpp_dd_ff_*` code path and expose the same wheel-config attributes. The LED attributes differ per rim (see the per-model note above). The driver tells the two apart by the USB product string. On the RS50 in compat mode, LIGHTSYNC works the same way as native. Feature `0x807A` is advertised at the same index that discovery picks up in native, and `wheel_led_*` writes drive the LED strip end-to-end (verified against the live wheel 2026-04-29). These wheel-config attributes work via fallback feature paths (see `docs/PROTOCOL_SPECIFICATION.md` section 5.1): `wheel_range`, `wheel_strength`, `wheel_trueforce`, `wheel_damping`, `wheel_ffb_filter`, `wheel_profile` (write `0` to enter desktop mode), and `wheel_calibrate`. This firmware does not support the remaining attributes (`wheel_brake_force`, `wheel_ffb_filter_auto`, `wheel_sensitivity`). Once their mode gating is satisfied, the store returns `-EOPNOTSUPP`. Note that `wheel_brake_force` still returns `-EPERM` in desktop mode, and `wheel_sensitivity` in onboard mode, before that check. For those settings, use the wheel's OLED menu or G Hub on a Windows host. ### LED Control Workflow @@ -662,18 +692,18 @@ The RS50 has 10 RGB LEDs in a horizontal strip across the upper faceplate (an en 3. **Set colors**: `echo "FF0000 FF0000 ... (10 colors)" > wheel_led_colors` 4. **Apply changes**: `echo 1 > wheel_led_apply` -Alternatively, use built-in effects via `wheel_led_effect`. +Or use the built-in effects through `wheel_led_effect`. ### wheel_led_slot **Access**: Read/Write **Values**: `0` to `4` (custom slot index) Selects the active custom LED slot and renders it on the strip. On the -wire a custom slot IS effect value `5 + slot` (see `wheel_led_effect`), -so writing this attribute is equivalent to writing effect `5 + slot`: -the driver applies the slot's stored config and switches the strip to it -(hardware-verified working, both directions, 2026-07-20). The slot-scoped -attributes (`wheel_led_slot_name`, `wheel_led_colors`, +wire, a custom slot IS effect value `5 + slot` (see `wheel_led_effect`). +So a write to this attribute equals a write of effect `5 + slot`. The +driver applies the slot's stored config and switches the strip to it. +This is hardware-verified in both directions, 2026-07-20. The +slot-scoped attributes (`wheel_led_slot_name`, `wheel_led_colors`, `wheel_led_direction`, `wheel_led_slot_brightness`) target the slot selected here. @@ -686,7 +716,7 @@ echo 2 > wheel_led_slot **Access**: Read/Write **Values**: String (max 8 characters) -Gets or sets the name of the currently selected LED slot. Names are stored on the device. +Gets or sets the name of the currently selected LED slot. The device stores the names. ```bash # Read current slot name @@ -701,7 +731,7 @@ echo "Racing" > wheel_led_slot_name **Access**: Read/Write **Values**: `0` to `100` (percentage) -Gets or sets the brightness for the currently selected slot. Each slot can have its own brightness level, which is applied when the slot is activated via `wheel_led_apply`. +Gets or sets the brightness for the currently selected slot. Each slot can have its own brightness level. The wheel applies it when you activate the slot with `wheel_led_apply`. ```bash # Read current slot brightness @@ -712,7 +742,7 @@ cat wheel_led_slot_brightness echo 50 > wheel_led_slot_brightness ``` -**Note**: This is per-slot brightness. Use `wheel_led_brightness` to set global brightness without changing slot settings. +**Note**: This is per-slot brightness. Use `wheel_led_brightness` to set the global brightness without changing slot settings. ### wheel_led_direction **Access**: Read/Write @@ -724,9 +754,9 @@ Sets the LED animation direction for the current slot: - `2` = Inside Out (center outward) - `3` = Outside In (edges inward) -On the wire the `0x807B` config carries a 1-4 value; the driver translates -between this 0-3 enum and the device's 1-4 encoding internally (see -PROTOCOL_SPECIFICATION.md section 9.4.1). +On the wire, the `0x807B` config carries a 1-4 value. The driver +translates between this 0-3 enum and the device's 1-4 encoding +internally (see PROTOCOL_SPECIFICATION.md section 9.4.1). ```bash # Set direction to Right-to-Left @@ -737,7 +767,7 @@ echo 1 > wheel_led_direction **Access**: Read/Write **Format**: 10 space-separated hex RGB values (`RRGGBB`) -Sets all 10 LED colors for the current slot. LED1 is leftmost. +Sets all 10 LED colors for the current slot. LED1 is the leftmost LED. ```bash # Set all LEDs to red @@ -762,46 +792,46 @@ Sets the global LED brightness. echo 50 > wheel_led_brightness ``` -Brightness changed from the wheel itself (OLED menu) is tracked: the -driver consumes the official x8040 `brightnessChangeEvent` broadcast, -updates this attribute's value, and notifies `poll()`ers on -`wheel_led_brightness`. It does not touch `wheel_sensitivity`: the two -were once thought to alias in desktop mode, that was disproved on -hardware, and the driver's own handler carries a note saying the read -here must never touch sensitivity. The two are fully independent, as -stated above. +The driver tracks brightness changes made from the wheel itself (OLED +menu). It consumes the official x8040 `brightnessChangeEvent` broadcast, +updates this attribute's value, and wakes `poll()` waiters on +`wheel_led_brightness`. It does not touch `wheel_sensitivity`. The two +were once thought to alias in desktop mode. That was disproved on +hardware. The driver's own handler carries a note that the read here +must never touch sensitivity. The two are fully independent, as stated +above. ### wheel_led_effect **Access**: Read/Write **Values**: `1` to `9` -Selects the LED animation mode. Values match feature 0x807A fn3 on +Selects the LED animation mode. The values match feature 0x807A fn3 on the wire: | Value | Effect | |---|---| | `1` | Inside to out | | `2` | Outside to in | -| `3` | Right to left | -| `4` | Left to right | +| `3` | Left to right | +| `4` | Right to left | | `5`-`9` | The five custom slots: `5` = CUSTOM 1 .. `9` = CUSTOM 5 | -Values `5`-`9` ARE the custom slots (decoded 2026-07-20): there is no -separate slot-activate command, selecting a slot is selecting its -effect number. Writing `5` renders the ACTIVE slot - the driver -re-applies `wheel_led_slot`'s stored RGB and sends `5 + slot` on the -wire, so through this attribute `5` always means "custom mode with the -currently selected slot". Writing `6`-`9` selects that specific slot's -image directly without moving `wheel_led_slot`; prefer `wheel_led_slot` -(or `5`) so the slot-scoped attributes keep targeting the rendered -slot. Writes for the animated modes (1-4) just switch the effect and -leave the cached colors untouched. Writes outside `1..9` are clamped -to the nearest end of the range. - -Effect changed from outside the driver (G Hub-style tools, or the -wheel itself) is tracked: the driver consumes the LIGHTSYNC -effect-change broadcast, updates this attribute, and notifies -`poll()`ers. +Values `5`-`9` ARE the custom slots (decoded 2026-07-20). There is no +separate slot-activate command. Selecting a slot is selecting its +effect number. A write of `5` renders the ACTIVE slot. The driver +re-applies the stored RGB of `wheel_led_slot` and sends `5 + slot` on +the wire. So through this attribute, `5` always means "custom mode with +the currently selected slot". A write of `6`-`9` selects that specific +slot's image directly, without moving `wheel_led_slot`. Prefer +`wheel_led_slot` (or `5`), so the slot-scoped attributes keep targeting +the rendered slot. A write of an animated mode (1-4) just switches the +effect and leaves the cached colors untouched. The driver clamps a write +outside `1..9` to the nearest end of the range. + +The driver tracks effect changes made from outside the driver, by G +Hub-style tools or by the wheel itself. It consumes the LIGHTSYNC +effect-change broadcast, updates this attribute, and wakes `poll()` +waiters. ```bash # Render the active custom slot @@ -819,13 +849,14 @@ echo 3 > wheel_led_effect **Availability**: wheels with feature `0x8130` (the RS50 and G PRO base OLED); reads `unsupported` elsewhere Puts a frame on the base's Dynamic OLED, or hands the screen back. Write -`||...`, where the layout is a letter `A` to `J` (or -`0` to `9`) and the fields follow in **payload order**, which for layouts D -and E is not the order the screen draws them. `wheel_oled_layouts` lists -what each layout takes. Text fields are space-padded to their width and -must not exceed it (`EMSGSIZE`); number fields take `0` to `255`; more -fields than the layout has is `E2BIG`. Fewer leaves the rest blank. Write -`off` to hand the screen back to the wheel's own menu immediately. +`||...`. The layout is a letter `A` to `J` (or `0` +to `9`). The fields follow in **payload order**. For layouts D and E, +payload order is not the order the screen draws them. `wheel_oled_layouts` +lists what each layout takes. The driver pads text fields with spaces to +their width. A text field must not exceed its width (`EMSGSIZE`). Number +fields take `0` to `255`. More fields than the layout has is `E2BIG`. +Fewer fields leaves the rest blank. Write `off` to hand the screen back to +the wheel's own menu immediately. | layout | fields, in write order | draws | |---|---|---| @@ -840,16 +871,16 @@ fields than the layout has is `E2BIG`. Fewer leaves the rest blank. Write | I | text(19), text(10), text(19), text(10) | four rows, 2 and 4 larger, right-aligned | | J | same as I | four rows, every row centred | -The panel does not hold a frame: the firmware returns to its own menu -after under two seconds of silence, so the driver resends the current -frame every 50 ms for as long as one is up. Reading back gives the last -write, or `off`. Two renderer rules worth knowing, both watched on an -RS50: a value on a wide large row (H's lower row, I's large rows) draws its -first character pinned left and the rest right-aligned, so `112%` shows as -`1` and `12%` with a gap, and a leading space gives a clean right-aligned -value instead; and no large-font layout centres, so J's rows are the -largest centred text the panel has. Full protocol in -`PROTOCOL_SPECIFICATION.md` 12.3. +The panel does not hold a frame. The firmware returns to its own menu +after under two seconds of silence. So the driver resends the current +frame every 50 ms for as long as one is up. A read gives the last write, +or `off`. Two renderer rules are worth knowing. Both were watched on an +RS50. First, a value on a wide large row (H's lower row, I's large rows) +draws its first character pinned left and the rest right-aligned. So +`112%` shows as `1` and `12%` with a gap. A leading space gives a clean +right-aligned value instead. Second, no large-font layout centres. So +J's rows are the largest centred text the panel has. The full protocol +is in `PROTOCOL_SPECIFICATION.md` 12.3. ```bash echo 'G|3|142' > wheel_oled # gear and speed @@ -857,20 +888,21 @@ echo 'J|Lap 12|1:42.7|Best|1:41.9' > wheel_oled echo off > wheel_oled ``` -These are non-force writes to the HID++ endpoint during play, the same -class as the rev lights, which have run alongside force and texture on -these wheels since 0.35.0. On a title that pushes DirectInput force to -HID++ next to its own TrueForce stream they can cut that force (12.5); -the rev lights carry the identical caveat. +These are non-force writes to the HID++ endpoint during play. They are +the same class as the rev lights, which have run alongside force and +texture on these wheels since 0.35.0. On a title that pushes DirectInput +force to HID++ next to its own TrueForce stream, they can cut that force +(12.5). The rev lights carry the identical caveat. ### wheel_oled_layouts **Access**: Read-only **Availability**: as `wheel_oled` -One line per layout the wheel reports: index, letter, the field kinds in -write order, then the text widths as the wheel's own descriptor lists them, -which is drawn order. E is the one layout where that differs from write -order (its 3-character field is written first and drawn on the right). On +One line per layout the wheel reports. Each line has the index, the +letter, the field kinds in write order, and then the text widths. The +widths are listed as the wheel's own descriptor lists them, which is +drawn order. E is the one layout where drawn order differs from write +order. Its 3-character field is written first and drawn on the right. On an RS50: ``` @@ -890,12 +922,13 @@ an RS50: **Access**: Read/Write **Availability**: all direct-drive wheels (feature `0x80A4`) -The steering axis's 64-point response curve - the store behind G Hub's -**Sensitivity** slider. Write `reset` to revert to the built-in -(linear) curve, or 2-64 whitespace-separated `in:out` pairs (decimal -0-65535, strictly increasing `in`, non-decreasing `out`, starting at -`0:0` and ending at `65535:65535`). Fewer than 64 pairs are resampled -by linear interpolation to the 64 points the wheel stores. +The steering axis's 64-point response curve. This is the store behind +G Hub's **Sensitivity** slider. Write `reset` to revert to the built-in +(linear) curve. Or write 2-64 whitespace-separated `in:out` pairs. The +values are decimal 0-65535. `in` must strictly increase. `out` must not +decrease. The pairs must start at `0:0` and end at `65535:65535`. If you +write fewer than 64 pairs, the driver resamples them by linear +interpolation to the 64 points the wheel stores. ```bash # Soften the centre (slower response near straight-ahead) @@ -908,14 +941,15 @@ cat wheel_response_curve # 64/64 points loaded (0 = built-in curve) ``` -The wheel applies this curve to the steering axis it reports to the PC (base -`0x80A4` axis 0, the same `wheel_sensitivity` uploads its slider curve to). -`wheel_sensitivity` and `wheel_response_curve` both write that one axis-0 curve, -so the last one written wins. The axis does not change until the wheel next -moves: it sends no HID reports while held still, so an upload appears to do -nothing until you nudge the wheel; `cat wheel_response_curve` reads the point -count back from the wheel and is the honest check. Use `reset` if steering feels -wrong after an upload. Whether curves persist across power cycles is untested. +The wheel applies this curve to the steering axis it reports to the PC. +That is base `0x80A4` axis 0, the same axis `wheel_sensitivity` uploads +its slider curve to. `wheel_sensitivity` and `wheel_response_curve` both +write that one axis-0 curve. So the last one written wins. The axis does +not change until the wheel next moves. The wheel sends no HID reports +while held still. So an upload appears to do nothing until you nudge the +wheel. `cat wheel_response_curve` reads the point count back from the +wheel and is the honest check. Use `reset` if steering feels wrong after +an upload. Whether curves persist across power cycles is untested. ### wheel_rev_level **Access**: Read/Write @@ -923,42 +957,43 @@ wrong after an upload. Whether curves persist across power cycles is untested. **Availability**: real G PRO rim AND the RS50's LIGHTSYNC strip (hardware-verified 2026-07-20, re-verified with the current wire form 2026-08-14). On the RS50 the display renders **center-out by -default**, so a 10-LED strip shows 5 mirrored visual steps across a +default**. So a 10-LED strip shows 5 mirrored visual steps across a 0-10 level sweep. The display pattern is a separate concern from the -level protocol: the level write says how much of the bar is lit, the +level protocol. The level write says how much of the bar is lit. The wheel's stored display config says how that amount is drawn. Reconfiguring the pattern mid-session (feature `0x807B`) is NOT part -of G HUB's own mid-session vocabulary and is untested during live +of G HUB's own mid-session vocabulary. It is untested during live TrueForce sessions, so do not assume it is safe there. A written -level holds until the next write; write `wheel_led_effect` to restore +level holds until the next write. Write `wheel_led_effect` to restore the normal idle pattern. Rev-light level for the G PRO rim. The G PRO's rim lights are -level-based: the host commands how many LEDs are lit (0-10) and the -wheel's onboard profile owns colours, direction and scaling. Protocol -decoded from G HUB captures (see -`docs/PROTOCOL_SPECIFICATION.md` section 9). No arming is needed: -from the onboard power-on state the strip renders bare levels exactly -(hardware-proven 2026-08-14; the earlier "the first write arms the -feature" belief is disproven, and the driver's direct-drive path sends -no arm burst). Writes return immediately: the driver coalesces them and -flushes only the newest level at a ~10 ms floor, comfortably above -G HUB's own measured ~60 Hz rev-light rate (faster -bursts would starve the wheel's shared HID++ command processor), so a +level-based. The host commands how many LEDs are lit (0-10). The +wheel's onboard profile owns colours, direction and scaling. The +protocol was decoded from G HUB captures (see +`docs/PROTOCOL_SPECIFICATION.md` section 9). No arming is needed. From +the onboard power-on state, the strip renders bare levels exactly +(hardware-proven 2026-08-14). The earlier belief that "the first write +arms the feature" is disproven. The driver's direct-drive path sends no +arm burst. Writes return immediately. The driver coalesces them and +flushes only the newest level, at a ~10 ms floor. That floor is +comfortably above G HUB's own measured ~60 Hz rev-light rate. Faster +bursts would starve the wheel's shared HID++ command processor. So a fast telemetry feeder always shows the latest value with no queueing -lag. The -wheel holds a level for a while but reverts eventually - a telemetry -feeder should refresh at ~1 Hz or faster (natural for rev-light use). +lag. The wheel holds a level for a while but reverts eventually. A +telemetry feeder should refresh at ~1 Hz or faster, which is natural +for rev-light use. -Level writes coexist safely with a live native TrueForce SDK session -since the driver moved to the bare fn2+fn6 wire form: base FFB + -TrueForce texture + telemetry-driven levels are hardware-validated -running together (2026-08-14). The old arm-burst form did NOT coexist: -it killed the SDK session at init and killed wheel input mid-session. +Level writes coexist safely with a live native TrueForce SDK session. +This has been true since the driver moved to the bare fn2+fn6 wire +form. Base FFB + TrueForce texture + telemetry-driven levels are +hardware-validated running together (2026-08-14). The old arm-burst +form did NOT coexist. It killed the SDK session at init and killed wheel +input mid-session. **Status: hardware-validated on the RS50 (2026-07-20, live 0-10-0 sweep -demos; fill semantics per the note above); not yet validated on a real -G PRO - reports welcome (issue tracker).** +demos; fill semantics per the note above). Not yet validated on a real +G PRO. Reports are welcome (issue tracker).** ```bash # Light 7 of 10 rev LEDs @@ -969,15 +1004,16 @@ echo 7 > wheel_rev_level **Access**: Read-only **Values**: 12-character device serial -The wheel's real serial number, read from HID++ DeviceInfo (feature -0x0003 fn2) at init. Matches the USB `iSerial` descriptor. +The wheel's real serial number. The driver reads it from HID++ +DeviceInfo (feature 0x0003 fn2) at init. It matches the USB `iSerial` +descriptor. ### wheel_firmware **Access**: Read-only -Firmware versions read from DeviceInfo at init: the wheel base's -active main firmware and the motor unit's servo firmware (from -sub-device 0x05's own DeviceInfo). +Firmware versions, read from DeviceInfo at init. The first is the wheel +base's active main firmware. The second is the motor unit's servo +firmware, from sub-device 0x05's own DeviceInfo. ```bash cat wheel_firmware @@ -985,7 +1021,7 @@ cat wheel_firmware # motor: SC 02.01.B0042 ``` -Include this output in bug reports - firmware-dependent behaviour +Include this output in bug reports. Firmware-dependent behaviour (feature index drift, settings quirks) is tracked against it. ### wheel_accessory @@ -993,26 +1029,26 @@ Include this output in bug reports - firmware-dependent behaviour **Values**: accessory device name, 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 -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. - -Both accessories are found at probe time and re-checked on demand: a read -queues a presence re-check in the background, so an accessory plugged in or -pulled after the module loaded shows up within a few reads. An RS H-Shifter -that arrives this way in desktop mode gets its gate routing enabled at the -same time, as it would have at probe. +Handbrake** and the **RS H-Shifter**. They plug into the base's USB-A +ports. The attribute 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 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. + +The driver finds both accessories at probe time and re-checks on demand. +A read queues a presence re-check in the background. So an accessory +plugged in or pulled after the module loaded shows up within a few reads. +An RS H-Shifter that arrives this way in desktop mode gets its gate +routing enabled at the same time, as it would have at probe. ```bash cat wheel_accessory # RS Shifter & Handbrake ``` -All three of the accessory's G HUB settings are now exposed: +The driver exposes all three of the accessory's G HUB settings: | G HUB slider | sysfs attribute | |---|---| @@ -1020,10 +1056,11 @@ All three of the accessory's G HUB settings are now exposed: | Handbrake Actuation | `wheel_handbrake_actuation` | | Handbrake Sensitivity | `wheel_handbrake_sensitivity` (+ `wheel_handbrake_curve`) | -The first two are trigger POINTS on the lever's travel and are named +The first two are trigger POINTS on the lever's travel. They are named `_actuation` for that reason, even though G HUB calls the shifter one -"sensitivity": in this driver a `*_sensitivity` attribute means one of an -axis's response-shaping generators, which these are not. +"sensitivity". In this driver, a `*_sensitivity` attribute means a +generator that applies a response curve to an axis. These two are not +that. ### wheel_led_apply **Access**: Write-only @@ -1042,50 +1079,57 @@ echo 1 > wheel_led_apply ### wheel_reset **Access**: Write-only (`1`) -Re-enumerates the wheel over USB from inside the driver, the software -equivalent of unplugging and replugging it. Logitech's TrueForce SDK can -leave the wheel's engine latched after a session that ended without its -teardown (a hard-killed or crashed game): the next SDK session opens but -never streams, and the wheel's steering and force go dead on track. A power -cycle clears it; so does this, and `logi-launch` writes it before a -TrueForce session so the ritual is unnecessary (`LOGI_TF_RESET=0` opts out). +Re-enumerates the wheel over USB from inside the driver. This is the +software equivalent of unplugging and replugging it. Logitech's TrueForce +SDK can leave the wheel's engine latched after a session that ended +without its teardown, for example a hard-killed or crashed game. The next +SDK session then opens but never streams. The wheel's steering and force +go dead on track. A power cycle clears it. So does this attribute. +`logi-launch` writes it before a TrueForce session, so the ritual is +unnecessary (`LOGI_TF_RESET=0` opts out). ```bash echo 1 > wheel_reset # the wheel drops off the bus and comes back in ~2 s ``` -The reset is queued to a workqueue, so the write returns immediately and the -driver re-probes cleanly; the hid ids change across it. USB wheels only. -## Pedal Configuration - -Pedal shaping is a 64-point `0x80A4` response curve, the same mechanism as -the steering `wheel_response_curve`, applied on the **wheel base** at axes -1/2/3 (throttle/brake/clutch). - -Not on the pedal unit. The pedal MCU has its own `0x80A4` store and will -accept an upload, reporting it back as loaded, but never applies it to the -axis it reports to the PC. Anything written there is silently inert. This -was proven on an RS50 (2026-07-28) with a step curve, which makes the band -between its two output plateaus unreachable if it is applied: loaded on the -pedal MCU the axis swept straight through that band, while the same curve on -base axis 1 pinned the axis to the plateau exactly, with the pedals -untouched. +The driver queues the reset to a workqueue, a kernel background job +queue. So the write returns immediately, and the driver re-probes +cleanly. The hid ids change across the reset. USB wheels only. -These attributes still require a pedal unit to be present: the base has -axes 1/2/3 regardless, but shaping an axis nothing drives is pointless, so -they return `EOPNOTSUPP` when no pedal unit answered discovery. +## Pedal Configuration -Each pedal `

` in {`throttle`, `brake`, `clutch`} exposes three attributes. -**They all write the single curve the axis holds, so the last write wins.** The -`_curve` attribute always reads back the wheel's true loaded-point count. +A pedal curve is a 64-point `0x80A4` response curve. It is the same +mechanism as the steering `wheel_response_curve`. The driver applies it on +the **wheel base** at axes 1/2/3 (throttle/brake/clutch). + +It is not applied on the pedal unit. The pedal MCU (the pedal unit's own +microcontroller) has its own `0x80A4` store. It accepts an upload and +reports it back as loaded. But it never applies the curve to the axis it +reports to the PC. Anything written there is silently inert. This was +proven on an RS50 (2026-07-28) with a step curve. A step curve makes the +band between its two output plateaus unreachable if it is applied. Loaded +on the pedal MCU, the axis swept straight through that band. The same +curve on base axis 1 pinned the axis to the plateau exactly, with the +pedals untouched. + +These attributes still require a pedal unit to be present. The base has +axes 1/2/3 regardless. But a curve on an axis that nothing drives is +pointless. So they return `EOPNOTSUPP` when no pedal unit answered +discovery. + +Each pedal `

` in {`throttle`, `brake`, `clutch`} exposes three +attributes. **They all write the single curve the axis holds, so the last +write wins.** The `_curve` attribute always reads back the wheel's true +loaded-point count. ### wheel_<p>_curve **Access**: Read/Write -The raw 64-point curve, identical in format to `wheel_response_curve`: write -`reset` for the built-in linear curve, or 2-64 whitespace-separated `in:out` -pairs (0-65535, strictly increasing `in`, non-decreasing `out`, starting `0:0` -and ending `65535:65535`; fewer than 64 pairs are resampled). Reads back +The raw 64-point curve. The format is identical to `wheel_response_curve`. +Write `reset` for the built-in linear curve. Or write 2-64 +whitespace-separated `in:out` pairs (0-65535, strictly increasing `in`, +non-decreasing `out`, starting `0:0` and ending `65535:65535`). The driver +resamples fewer than 64 pairs. A read gives `"/ points loaded"`. ```bash @@ -1099,10 +1143,11 @@ cat wheel_throttle_curve # e.g. "64/64 points loaded (0 = built-in curve)" **Access**: Read/Write, **Values**: `0`-`100` (`50` = linear) G HUB's simple sensitivity slider. Values above 50 make the pedal more -responsive early in its travel, below 50 less; `50` reverts to the built-in -linear curve. Generates the same symmetric-Bezier curve G HUB uploads. The -wheel stores only the resulting curve, so this reads back the last written -slider value, not a device query. +responsive early in its travel. Values below 50 make it less responsive. +`50` reverts to the built-in linear curve. The driver generates the same +symmetric-Bezier curve G HUB uploads. The wheel stores only the resulting +curve. So this reads back the last written slider value, not a device +query. ```bash echo 70 > wheel_brake_sensitivity @@ -1111,30 +1156,32 @@ echo 70 > wheel_brake_sensitivity ### wheel_<p>_deadzone **Access**: Read/Write, **Values**: `" "` percent -Dead travel at each end: output holds 0 until the pedal passes `lower`%, and -reaches full by `(100 - upper)`%. `lower + upper` must be at most 99. `"0 0"` -reverts to the built-in curve. Reads back the last written pair. +Dead travel at each end. The output holds 0 until the pedal passes +`lower`%. It reaches full by `(100 - upper)`%. `lower + upper` must be at +most 99. `"0 0"` reverts to the built-in curve. A read gives the last +written pair. ```bash # 8% dead at the bottom, 5% saturation at the top of the clutch echo "8 5" > wheel_clutch_deadzone ``` -> Because sensitivity, deadzone and the raw curve all write the one hardware -> curve per axis, use one of them at a time per pedal. To combine a deadzone -> with a custom curve, author the whole thing as a single `_curve` upload (this -> is what the logi-wheel editor does). +> Sensitivity, deadzone and the raw curve all write the one hardware curve +> per axis. So use one of them at a time per pedal. To combine a deadzone +> with a custom curve, write the whole thing as a single `_curve` upload. +> This is what the logi-wheel editor does. ### wheel_combined_pedals **Access**: Read/Write, **Values**: `0` (separate) / `1` (combined) **Mode**: desktop only -G HUB's "combined pedals" toggle (feature `0x80D0`). When on, the wheel merges -the throttle and brake into a single centred axis for legacy games that expect -one pedal axis: released = centre, one pedal drives it up, the other down. The -brake's own axis goes silent. Off for any modern sim. Verified on an RS50: with -it on, `ABS_RX` re-centres to ~32768 and `ABS_RY` (the separate brake axis) -stops reporting. +G HUB's "combined pedals" toggle (feature `0x80D0`). When on, the wheel +merges the throttle and brake into a single centred axis. This is for +legacy games that expect one pedal axis. Released = centre. One pedal +drives the axis up, the other down. The brake's own axis goes silent. Keep +it off for any modern sim. Verified on an RS50: with it on, `ABS_RX` +re-centres to ~32768, and `ABS_RY` (the separate brake axis) stops +reporting. ```bash echo 1 > wheel_combined_pedals # merge (legacy games) @@ -1146,11 +1193,11 @@ cat wheel_combined_pedals # 0 or 1 **Access**: Read-only **Values**: `shifter`, `digital-handbrake`, `analog-handbrake` -Which of its three jobs the **RS Shifter & Handbrake** is currently doing, -read live from feature `0x1B30` on the accessory. The unit has a physical -three-position switch and only one mode is active at a time, so most of its -settings apply to only one of them. Returns `EOPNOTSUPP` when no accessory is -attached. +Which of its three jobs the **RS Shifter & Handbrake** is currently doing. +The driver reads it live from feature `0x1B30` on the accessory. The unit +has a physical three-position switch. Only one mode is active at a time. +So most of its settings apply to only one of them. A read returns +`EOPNOTSUPP` when no accessory is attached. ```bash cat wheel_accessory_mode @@ -1158,56 +1205,59 @@ cat wheel_accessory_mode ``` The desktop and terminal apps use this to grey out the settings that belong -to a different mode and say which mode each needs. The greying is -presentation only: the attributes below stay writable in every mode, because -their values persist across a mode change and setting one up before flipping -the switch is a reasonable thing to do. +to a different mode. They also say which mode each setting needs. The +greying is presentation only. The attributes below stay writable in every +mode. Their values persist across a mode change. So setting one up before +you flip the switch is a reasonable thing to do. -An unrecognised value reads as `unknown (N)`, and the apps treat that as +An unrecognised value reads as `unknown (N)`. The apps treat that as "cannot tell" and hide nothing. ### wheel_shift_actuation / wheel_handbrake_actuation **Access**: Read/Write **Values**: `1`-`100` (G HUB's own range; it refuses `0`) -The **RS Shifter & Handbrake**'s two trigger points, on feature `0x80B1` -(BANDED_AXIS) on the accessory itself. Both return `EOPNOTSUPP` when no -accessory is attached. +The two trigger points of the **RS Shifter & Handbrake**. They live on +feature `0x80B1` (BANDED_AXIS) on the accessory itself. Both return +`EOPNOTSUPP` when no accessory is attached. -- `wheel_shift_actuation` - how far the sequential shifter must be pushed - before a shift registers. Writes both of the shifter's bands, one per - direction, symmetric about centre. G HUB calls this "Shift Sensitivity"; - it is a trigger point, not response shaping, hence the name here. -- `wheel_handbrake_actuation` - how far the handbrake must be pulled before - the digital handbrake button (`BTN_THUMB2`) fires. Applies in - digital-handbrake mode; the analog mode uses the handbrake curve instead. +- `wheel_shift_actuation` - how far you must push the sequential shifter + before a shift registers. A write sets both of the shifter's bands, one + per direction, symmetric about centre. G HUB calls this "Shift + Sensitivity". It is a trigger point, not a response curve, hence the + name here. +- `wheel_handbrake_actuation` - how far you must pull the handbrake before + the digital handbrake button (`BTN_THUMB2`) fires. It applies in + digital-handbrake mode. The analog mode uses the handbrake curve + instead. ```bash echo 30 > wheel_shift_actuation # shift triggers early echo 70 > wheel_handbrake_actuation # handbrake fires late in the pull ``` -Neither is mode-gated: unlike G HUB's UI, which will not let these be -changed in onboard mode, the wire accepts them in either mode (tested). +Neither is mode-gated. G HUB's UI will not let you change these in onboard +mode. But the wire accepts them in either mode (tested). **A deliberate difference from G HUB.** The handbrake scale overflows 16 -bits above about 69%, and G HUB truncates there - it writes 75% as a point -*shorter* than 50%. The wheel accepts the full value, so this driver writes -the true one and stays monotonic across the whole 1-100 range. Above ~69%, -values set here and values set in G HUB will not correspond. +bits above about 69%. G HUB truncates there: it writes 75% as a point +*shorter* than 50%. The wheel accepts the full value. So this driver +writes the true one and stays monotonic across the whole 1-100 range. +Above ~69%, values set here and values set in G HUB will not correspond. ### wheel_handbrake_curve / wheel_handbrake_sensitivity -Response-curve shaping for the **RS Shifter & Handbrake** in analog handbrake -mode. The handbrake drives a base axis (`0x80A4` axis 4, evdev `ABS_Z`), and the -driver bends it with the same mechanism as the pedals, verified on an RS50. +The response curve for the **RS Shifter & Handbrake** in analog handbrake +mode. The handbrake drives a base axis (`0x80A4` axis 4, evdev `ABS_Z`). +The driver bends it with the same mechanism as the pedals. Verified on an +RS50. - `wheel_handbrake_curve` - raw `in:out` points or `reset`, like `wheel_response_curve`. - `wheel_handbrake_sensitivity` - the 0-100 G HUB slider (50 = linear). -Both write the one curve the axis holds; last write wins. The handbrake *input* -itself needs no configuration: connected to the wheel base, it works out of the -box as `ABS_Z`. These attributes only bend it. +Both write the one curve the axis holds. The last write wins. The +handbrake *input* itself needs no configuration. Connected to the wheel +base, it works out of the box as `ABS_Z`. These attributes only bend it. ```bash echo 70 > wheel_handbrake_sensitivity @@ -1217,8 +1267,8 @@ echo reset > wheel_handbrake_curve ### RS Shifter & Handbrake input mapping -The accessory rides the wheel's existing report, so its inputs reach evdev with -no driver change. By its mode switch: +The accessory rides the wheel's existing report. So its inputs reach evdev +with no driver change. By its mode switch: | Mode | Action | evdev | |------|--------|-------| @@ -1227,114 +1277,120 @@ no driver change. By its mode switch: | Digital handbrake | pull past point | `BTN_THUMB2` (face button) | | Analog handbrake | pull | `ABS_Z` axis | -Use `wheel_accessory` (above) to check whether the accessory is attached, and -`wheel_accessory_mode` for which of its three jobs it is currently doing. All -three of its G HUB settings are implemented: `wheel_shift_actuation`, -`wheel_handbrake_actuation` and `wheel_handbrake_sensitivity` (with -`wheel_handbrake_curve`). +Use `wheel_accessory` (above) to check whether the accessory is attached. +Use `wheel_accessory_mode` to see which of its three jobs it is currently +doing. All three of its G HUB settings are implemented: +`wheel_shift_actuation`, `wheel_handbrake_actuation` and +`wheel_handbrake_sensitivity` (with `wheel_handbrake_curve`). --- ## Compatibility Attributes -These attributes provide compatibility with existing wheel management tools (e.g., Oversteer). -The sysfs filenames use standard Oversteer names (without the `wheel_` prefix). +These attributes provide compatibility with existing wheel management tools, for example Oversteer, a Linux wheel configuration tool. +The sysfs filenames use the standard Oversteer names, without the `wheel_` prefix. -**Note:** These aliases are created for every direct-drive wheel this driver -binds (RS50 and G PRO). They exist so Oversteer, which looks for the new-lg4ff -attribute names, can drive the wheel; the same settings are also available -under their `wheel_*` names documented above. On the **G923** the classic names -are not aliases but the primary (and only) attributes, with classic semantics -and scales - see the next section. +**Note:** The driver creates these aliases for every direct-drive wheel it +binds (RS50 and G PRO). Oversteer looks for the new-lg4ff attribute names. +(new-lg4ff is the community driver for classic Logitech wheels.) The +aliases exist so Oversteer can drive the wheel. The same settings are also +available under their `wheel_*` names documented above. On the **G923** +the classic names are not aliases. They are the primary (and only) +attributes, with classic semantics and scales. See the next section. -These attributes follow the de-facto Linux wheel convention (the -new-lg4ff attribute names and scales) that Oversteer and similar tools -speak. Conformance was verified 2026-07-03 by driving every getter and -setter through Oversteer's own code against the live wheel. Note the -scales differ from the `wheel_*` attributes: tools expect raw device -units here, not percent. +These attributes follow the de-facto Linux wheel convention that Oversteer +and similar tools speak: the new-lg4ff attribute names and scales. +Conformance was verified 2026-07-03 by driving every getter and setter +through Oversteer's own code against the live wheel. Note that the scales +differ from the `wheel_*` attributes. Tools expect raw device units here, +not percent. ### range **Access**: Read/Write **Values**: `90` to `2700` (degrees) -Same functionality as `wheel_range` (degrees on both). +The same function as `wheel_range`. Both use degrees. ### gain **Access**: Read/Write **Values**: `0` to `65535` (raw; the FF_GAIN scale) -Drives the same wheel strength setting as `wheel_strength`, but the -file speaks the raw 0-65535 scale tools expect (Oversteer shows it as -percent in its UI). `wheel_strength` keeps its human-friendly 0-100 -percent scale; the two stay in sync. +Drives the same wheel strength setting as `wheel_strength`. But this file +speaks the raw 0-65535 scale that tools expect. Oversteer shows it as +percent in its UI. `wheel_strength` keeps its human-friendly 0-100 percent +scale. The two stay in sync. ### autocenter **Access**: Read/Write **Values**: `0` to `65535` (raw; the FF_AUTOCENTER scale) -A real, driver-emulated centring spring: while -nonzero, the wheel pulls itself toward centre with a damped spring -computed in the 500 Hz effect loop - firm within roughly the central -eighth of the axis, like hardware autocenter on other wheels. Also -reachable through the standard evdev `FF_AUTOCENTER` control, which -means games that write autocenter 0 before taking over force feedback -correctly disable it for their session. Useful for desk-driving -without a game, or as idle centring. +A real, driver-emulated centring spring. While nonzero, the wheel pulls +itself toward centre with a damped spring. The driver computes the spring +in the 1 kHz effect loop. The spring is firm within roughly the central +eighth of the axis, like hardware autocenter on other wheels. It is also +reachable through the standard evdev `FF_AUTOCENTER` control. So a game +that writes autocenter 0 before it takes over force feedback correctly +disables it for its session. Useful for desk-driving without a game, or +as idle centring. ### spring_level / damper_level / friction_level / inertia_level **Access**: Read/Write **Values**: `0` to `400` (percent), default `100` Global output scales for the emulated `FF_SPRING` / `FF_DAMPER` / -`FF_FRICTION` / `FF_INERTIA` effect classes, matching the new-lg4ff -semantics: 100 = effects play as the game commanded, lower values tame -that effect class across all games, 0 mutes it. `damper_level` scales -DAMPER effects from games; the wheel's own firmware damping is +`FF_FRICTION` / `FF_INERTIA` effect classes. They match the new-lg4ff +semantics. 100 = effects play as the game commanded. Lower values tame +that effect class across all games. 0 mutes it. `damper_level` scales +DAMPER effects from games. The wheel's own firmware damping is `wheel_damping`. -new-lg4ff stops at 100. This engine accepts up to 400 because its gains sit -below what the wheels' firmware renders for the same effect, by amounts that -differ per wheel: a G923 Xbox edition owner measured the engine's damper at -0.61 of the firmware's ([#87](../../issues/87)), and a G PRO owner runs -2.25x damper and 4x spring against theirs ([#89](../../issues/89)). Until -those measurements settle the defaults, the levels are how to try them: +new-lg4ff stops at 100. This engine accepts up to 400. Its gains sit +below what the wheels' firmware renders for the same effect, by amounts +that differ per wheel. A G923 Xbox edition owner measured the engine's +damper at 0.61 of the firmware's ([#87](../../issues/87)). A G PRO owner +runs 2.25x damper and 4x spring against theirs ([#89](../../issues/89)). +Until those measurements settle the defaults, the levels are how to try +them: ```bash echo 225 > damper_level # the G PRO numbers from #89 echo 400 > spring_level ``` -The summed force is clamped to the motor's range after every effect is -added, so a large level saturates instead of wrapping. `inertia_level` has -no new-lg4ff counterpart; the engine's inertia estimate is band-limited -(a 50 ms one-pole on the velocity), so a steady acceleration reads as -itself and the encoder's quantisation no longer arrives as grain. +The driver clamps the summed force to the motor's range after it adds +every effect. So a large level saturates instead of wrapping. +`inertia_level` has no new-lg4ff counterpart. The engine's inertia +estimate is band-limited (a 50 ms one-pole on the velocity). So a steady +acceleration reads as itself, and the encoder's quantisation no longer +arrives as grain. --- ## G923 Attributes (PlayStation edition, c266/c267) -The G923 PlayStation edition runs a classic force-feedback engine ported from -berarma's new-lg4ff, not the direct-drive `hidpp_dd_ff_*` path, so it exposes -the classic lg4ff attribute names as its primary attributes (Oversteer speaks -them natively). None of the `wheel_*` attributes above exist on this wheel. -The attributes live on the wheel's interface-0 HID device: +The G923 PlayStation edition runs a classic force-feedback engine ported +from berarma's new-lg4ff. It does not use the direct-drive `hidpp_dd_ff_*` +path. So it exposes the classic lg4ff attribute names as its primary +attributes. Oversteer speaks them natively. None of the `wheel_*` +attributes above exist on this wheel. The attributes live on the wheel's +interface-0 HID device: ```bash find /sys/bus/hid/devices -name "*046D*C266*" 2>/dev/null # G923 PS (after mode switch) ``` -The wheel enumerates as `046d:c267` in PlayStation mode; the driver switches it -to classic mode (`046d:c266`) automatically, so `c266` is the device you -configure. All attributes are hardware-verified on a c266 except where noted. +The wheel enumerates as `046d:c267` in PlayStation mode. The driver +switches it to classic mode (`046d:c266`) automatically. So `c266` is the +device you configure. All attributes are hardware-verified on a c266 +except where noted. ### range **Access**: Read/Write **Values**: `40` to `900` (degrees) -Steering rotation range. Writing `0` selects the maximum (900). Out-of-range -values are ignored (the write succeeds but changes nothing). +Steering rotation range. A write of `0` selects the maximum (900). The +driver ignores out-of-range values. The write succeeds but changes +nothing. ```bash echo 540 > range @@ -1345,8 +1401,8 @@ echo 540 > range **Values**: `0` to `65535` **Default**: `65535` -Master gain applied to all effects the classic engine plays, multiplied with -the per-application `FF_GAIN` from evdev. +Master gain for all effects the classic engine plays. The engine +multiplies it with the per-application `FF_GAIN` from evdev. ### autocenter **Access**: Read/Write @@ -1354,55 +1410,56 @@ the per-application `FF_GAIN` from evdev. **Default**: `0` Hardware autocenter spring. Writes go through the same `FF_AUTOCENTER` -callback games use, so a game that disables autocenter before taking over -force feedback behaves correctly. +callback that games use. So a game that disables autocenter before it +takes over force feedback behaves correctly. ### combine_pedals **Access**: Read/Write **Values**: `0`, `1`, `2` -Merges two pedals into one centred axis for legacy games, by rewriting the -wheel's input report in the driver: +Merges two pedals into one centred axis for legacy games. The driver does +this by rewriting the wheel's input report: - `0` - separate pedals (default) - `1` - throttle and brake combined into the throttle axis - `2` - throttle and clutch combined into the throttle axis -Values above `2` are clamped to `2`. +The driver clamps values above `2` to `2`. ### ffb_output **Access**: Read-only **Values**: roughly `-32768` to `32767` (`0` = no force) -The classic engine's current net force output (post-gain), updated once per -effect-loop tick. `logi-tf-sim` polls this to mirror live force feedback into -the G923's TrueForce stream while simulated TrueForce is running (an active -stream makes the wheel follow the stream's force field instead of the classic -path, so the mirror is what keeps force feedback alive during streaming). +The classic engine's current net force output, after gain. The engine +updates it once per effect-loop tick. `logi-tf-sim` polls this to mirror +live force feedback into the G923's TrueForce stream while simulated +TrueForce is running. An active stream makes the wheel follow the stream's +force field instead of the classic path. So the mirror is what keeps force +feedback alive during streaming. ### Rev LEDs -The five rev-light pairs are standard Linux LED class devices, one per -mirrored pair, outermost first: +The five rev-light pairs are standard Linux LED class devices. There is +one device per mirrored pair, outermost first: ``` /sys/class/leds/::RPM1 .. ::RPM5 # e.g. /sys/class/leds/0003:046D:C266.0005::RPM1/brightness ``` -Write `1`/`0` to each `brightness` file to switch a pair on or off. Any LED -tool (or a telemetry feeder) that speaks the standard `leds` class works. This -is the classic G29-family LED command under the hood, not the DD wheels' -HID++ feature, so `wheel_rev_level` does not exist here. +Write `1`/`0` to each `brightness` file to switch a pair on or off. Any +LED tool (or a telemetry feeder) that speaks the standard `leds` class +works. Under the hood this is the classic G29-family LED command, not the +DD wheels' HID++ feature. So `wheel_rev_level` does not exist here. ### Xbox edition (c26e) -The G923 Xbox edition routes through the driver's HID++ 0x8123 (G920-style) -force-feedback path instead of the classic engine, so it exposes `range` -(clamped to `180`-`900`) and `range_restore`, and none of the classic -engine's `gain`/`autocenter`/`combine_pedals` or its rev-LED devices. -Force feedback and TrueForce are both hardware-confirmed on this edition -(issue #27, 2026-07-30). +The G923 Xbox edition routes through the driver's HID++ 0x8123 +(G920-style) force-feedback path instead of the classic engine. So it +exposes `range` (clamped to `180`-`900`) and `range_restore`. It exposes +none of the classic engine's `gain`/`autocenter`/`combine_pedals`, and +none of its rev-LED devices. Force feedback and TrueForce are both +hardware-confirmed on this edition (issue #27, 2026-07-30). #### range_restore @@ -1410,39 +1467,41 @@ Force feedback and TrueForce are both hardware-confirmed on this edition **Default**: `1`, on (matching `wheel_range_restore` on the direct-drive wheels) -Put the rotation range back when a game moves it. - -A game reaching the Logitech SDK directly (which on Linux means -`PROTON_ENABLE_HIDRAW=1`) pushes its own configured steering rotation at the -wheel as a TrueForce type-`0x0e` packet. That bypasses the HID++ range -feature entirely, so nothing is notified, and a title configured for 90 -degrees silently locks the wheel to 90 with a soft stop there. The SDK sends -it once at session start, so putting the range back sticks for that session. - -On this edition specifically, that push does not appear to reach the wheel: -an owner's rim keeps its full travel in ACC's config screen while the limit -shows up only on track, which means the game is clamping its own steering -rather than the wheel being reconfigured (see `docs/TRUEFORCE_PROTOCOL.md`). -So this is expected to find nothing to do there. It is on regardless, -because the cost of watching is a read every two seconds and the cost of not -watching is an unusable wheel for anyone whose game does write the range. - -While on, the driver re-reads the range the wheel is actually -enforcing every two seconds and re-applies the configured one if a game has -moved it. It gives up after three restores and logs once, so a program that -genuinely wants a different range wins rather than being fought forever; -writing `1` again forgives that count. - -**Why it defaults to off.** Enabling it means the driver writes a range while -a game holds the wheel. On the direct-drive wheels, doing that at the wrong -moment desynchronised the centre violently, which is why their equivalent -checks the rim is still and near centre first, using an encoder read this -wheel does not offer. The check here reads the reported steering axis -instead and refuses to write unless the rim is within 3% of centre, which is -believed equivalent but has not been proven on this hardware. Turn it on -deliberately, and watch the wheel the first time. - -Doing it by hand is a complete alternative, since the push is one-shot: +Puts the rotation range back when a game moves it. + +A game that reaches the Logitech SDK directly pushes its own configured +steering rotation at the wheel. On Linux, direct SDK access means +`PROTON_ENABLE_HIDRAW=1`. The push is a TrueForce type-`0x0e` packet. It +bypasses the HID++ range feature entirely, so nothing is notified. A +title configured for 90 degrees silently locks the wheel to 90, with a +soft stop there. The SDK sends the push once at session start. So putting +the range back sticks for that session. + +On this edition specifically, that push does not appear to reach the +wheel. An owner's rim keeps its full travel in ACC's config screen. The +limit shows up only on track. That means the game is clamping its own +steering, and the wheel is not being reconfigured (see +`docs/TRUEFORCE_PROTOCOL.md`). So this attribute is expected to find +nothing to do there. It is on regardless. The cost of watching is a read +every two seconds. The cost of not watching is an unusable wheel for +anyone whose game does write the range. + +While on, the driver re-reads the range the wheel is actually enforcing +every two seconds. If a game has moved it, the driver re-applies the +configured one. It gives up after three restores and logs once. So a +program that genuinely wants a different range wins, instead of being +fought forever. A write of `1` again forgives that count. + +**The risk.** The driver writes a range while a game holds the wheel. On the direct-drive wheels, doing that at the +wrong moment desynchronised the centre violently. That is why their +equivalent first checks that the rim is still and near centre. It uses an +encoder read that this wheel does not offer. The check here reads the +reported steering axis instead. It refuses to write unless the rim is +within 3% of centre. This is believed equivalent, but it has not been +proven on this hardware. Watch the wheel the first time it fires. Write +`0` to turn it off if the centre moves. + +Doing it by hand is a complete alternative, because the push is one-shot: ```bash # after the game has started and taken the wheel @@ -1457,7 +1516,7 @@ echo 900 > /sys/class/hidraw/hidrawN/device/range **Access**: Read/Write, mode 0600 (root only) **Availability**: Only present when the module is built with `CONFIG_HID_LOGITECH_HIDPP_DEBUG` (e.g. `make DEBUG=1`). Absent from default builds. -Raw HID++ command shell for protocol bring-up. Write `feature fn [params...]` (hex), read the last command's response. +Raw HID++ command shell for protocol bring-up. Write `feature fn [params...]` in hex. Read the last command's response. ```bash # Send fn 0x5c to feature 0x0b with three zero params @@ -1527,28 +1586,29 @@ fi ## Module parameters -Set at load time (`modprobe hid-logitech-dd stream_yield=N`) or, where the -mode allows, live under `/sys/module/hid_logitech_dd/parameters/`. All of -them default to the right thing; each exists so a behaviour that was -introduced to fix something can be turned off again if it ever misbehaves -on hardware nobody here has. +Set a parameter at load time (`modprobe hid-logitech-dd stream_yield=N`). +Or, where the mode allows, set it live under +`/sys/module/hid_logitech_dd/parameters/`. All of them default to the +right thing. Each exists so a behaviour that was introduced to fix +something can be turned off again. That matters if it ever misbehaves on +hardware nobody here has. | Parameter | Default | What it does | |---|---|---| -| `stream_yield` | `Y` | Stay off the TrueForce stream while another process is writing it. The endpoint carries one packet per millisecond, so two streamers halve each other and square-modulate the motor at 500 Hz (see the one-writer section of TRUEFORCE_PROTOCOL.md). While yielding, the driver still applies its own force by writing it into the owner's packet, but only when an effect is actually running here, so a game's own force is never overwritten. `N` restores the old behaviour of streaming regardless. | -| `kf_idle_gate` | `Y` | Stop the 1 kHz zero-force keepalive after 500 ms of exact-zero force, which is what keeps an idle wheel silent instead of holding a stream open. `N` streams always. | -| `g923_pedal_invert` | `Y` | Report the G923's pedals the way round Linux expects, 0 released and full scale pressed. The wheel sends all three inverted (255 released, 0 fully pressed), on every id it has, both editions included, and nothing in HID marks an axis as inverted so no layer corrects it by itself. Applied at the input layer only: raw HID stays exactly as the wheel sent it, because a Wine or Proton game reading the wheel over raw HID expects the Windows convention. `N` passes the axes through as sent, for anyone who already inverted them inside their games. Does not apply to the direct-drive wheels, which report these axes the normal way up, nor while `combine_pedals` is on, because that mode merges throttle and brake into one bidirectional axis where inverting would swap them. | -| `g923_xbox_dd_engine` | `N` | Experimental, and load-time only. Drives the G923 Xbox edition's force feedback from this driver's own engine instead of downloading the effects into the wheel's firmware over HID++ 0x8123. The reason to want it is simulated TrueForce: the firmware sums the effects itself, so the driver never knows the force being produced, and a TrueForce stream, whose torque field takes the motor, can only carry a zero. That is why `logi-tf-sim` refuses that wheel by default. With this engine the force is summed here and goes into the stream with the texture, the way it does on the direct-drive wheels, and the daemon streams without an override. Untested on hardware: nobody working on this owns that wheel. Its rev lights are unaffected and stay on their own LED device; the direct-drive `wheel_rev_level` that appears with this parameter does nothing on this wheel, which speaks the other rev-light dialect. Condition effects (spring, damper, friction, inertia) stay silent until the wheel's steering position reaches this engine, which needs that edition's report layout and is not done. | -| `inject_pid` | `0` (off) | Appends a PID force-feedback collection to interface 0's report descriptor. **Leave it off**: the injected collection declares report ids this wheel does not use, so its input reports are then misparsed and steering and pedals stop working. It was briefly a default in 0.34.0 and that is exactly what happened (#59, #63). `1` is a dry run, `2` actuates. | +| `stream_yield` | `Y` | Stay off the TrueForce stream while another process is writing it. The endpoint carries one packet per millisecond. So two streamers halve each other and square-modulate the motor at 500 Hz (see the one-writer section of TRUEFORCE_PROTOCOL.md). While yielding, the driver still applies its own force by writing it into the owner's packet. It does this only when an effect is actually running here, so a game's own force is never overwritten. `N` restores the old behaviour of streaming regardless. | +| `kf_idle_gate` | `Y` | Stop the 1 kHz zero-force keepalive after 500 ms of exact-zero force. This keeps an idle wheel silent instead of holding a stream open. `N` streams always. | +| `g923_pedal_invert` | `Y` | Report the G923's pedals the way round Linux expects: 0 released and full scale pressed. The wheel sends all three inverted (255 released, 0 fully pressed). It does this on every id it has, both editions included. Nothing in HID marks an axis as inverted, so no layer corrects it by itself. The driver applies this at the input layer only. Raw HID stays exactly as the wheel sent it, because a Wine or Proton game that reads the wheel over raw HID expects the Windows convention. `N` passes the axes through as sent, for anyone who already inverted them inside their games. It does not apply to the direct-drive wheels, which report these axes the normal way up. It also does not apply while `combine_pedals` is on. That mode merges throttle and brake into one bidirectional axis, where inverting would swap them. | +| `g923_xbox_dd_engine` | `N` | Experimental, and load-time only. Drives the G923 Xbox edition's force feedback from this driver's own engine. The default downloads the effects into the wheel's firmware over HID++ 0x8123 instead. The reason to want it is simulated TrueForce. The firmware sums the effects itself, so the driver never knows the force being produced. A TrueForce stream, whose torque field takes the motor, can then only carry a zero. That is why `logi-tf-sim` refuses that wheel by default. With this engine, the driver sums the force here and puts it into the stream with the texture, the way it does on the direct-drive wheels. The daemon then streams without an override. Untested on hardware: nobody working on this owns that wheel. Its rev lights are unaffected and stay on their own LED device. The direct-drive `wheel_rev_level` that appears with this parameter does nothing on this wheel, which speaks the other rev-light dialect. Condition effects (spring, damper, friction, inertia) stay silent until the wheel's steering position reaches this engine. That needs that edition's report layout and is not done. | +| `inject_pid` | `0` (off) | Appends a PID force-feedback collection to interface 0's report descriptor. (PID is the USB HID force-feedback class.) **Leave it off.** The injected collection declares report ids this wheel does not use. The wheel's input reports are then misparsed, and steering and pedals stop working. It was briefly a default in 0.34.0, and that is exactly what happened (#59, #63). `1` is a dry run. `2` actuates. | -`disable_tap_to_click` also exists, inherited from the in-tree driver this -one forked: it concerns a K400 touchpad and nothing about a wheel. +`disable_tap_to_click` also exists. It is inherited from the in-tree driver +this one forked. It concerns a K400 touchpad and nothing about a wheel. --- ## Protocol Details -For developers interested in the HID++ protocol details, see: +For the HID++ protocol details, see: - `PROTOCOL_SPECIFICATION.md` - Full protocol documentation - `dev/docs/CAPTURE_ANALYSIS_*.md` - USB capture analysis diff --git a/docs/TF_TEXTURE_RECIPE.md b/docs/TF_TEXTURE_RECIPE.md index 4520d78..019ab58 100644 --- a/docs/TF_TEXTURE_RECIPE.md +++ b/docs/TF_TEXTURE_RECIPE.md @@ -1,32 +1,37 @@ # Logitech's real TrueForce texture, extracted from Windows captures Source: `dev/captures/rs50_acc_2026-04-21/2026-04-21_trueforce_ace.pcapng` -(AC EVO on Windows, RS50, G HUB present). 119,028 stream packets, 250,140 -audio samples at ~3983 Hz, analysed 2026-08-12. Parsing: type-0x01 packets, -new samples = last `byte[10]` slots of the 13-slot window at bytes 12+4i, -u16 LE offset-binary. +(AC EVO on Windows, RS50, G HUB present). The capture holds 119,028 stream +packets and 250,140 audio samples at ~3983 Hz. It was analysed on 2026-08-12. +TrueForce is Logitech's high-rate haptic channel. Its texture is the fine +engine buzz the wheel plays on top of the base force. Parsing: type-0x01 +packets, new samples = last `byte[10]` slots of the 13-slot window at bytes +12+4i, u16 LE offset-binary. ## What Windows sends that Proton does not -On Windows the ep3 stream carries BOTH the base force (`cur`, 1 kHz) and +On Windows the ep3 stream (USB endpoint 3, the TrueForce output channel) +carries two things. It carries the base force (`cur`, 1 kHz). It also carries real audio texture (`byte[10]=4` in 62,535 of 119,028 packets). Under Proton -the SDK's stream carries `cur` only, `byte[10]=0` always. The missing texture -is the audio slots. +(the Wine-based Windows compatibility layer in Steam) the SDK's stream carries +`cur` only, and `byte[10]=0` always. The missing texture is the audio slots. **Who injects it (corrected 2026-08-13):** the injector is **G HUB the running -process**, synthesising the engine note from the game's Escape RPM and merging -it into ep3. It is NOT Logitech's OEM DirectInput driver -(`hidpp_forcefeedback_x64.dll`): this capture is on `c276` (native mode), and +process**. G HUB synthesises the engine note from the game's Escape RPM +(engine speed the game passes through a DirectInput call) and merges it into +ep3. It is NOT Logitech's OEM DirectInput driver +(`hidpp_forcefeedback_x64.dll`). This capture is on `c276` (native mode), and that driver does not claim c276 at all (only c262/c268/c26e/c272; it null-derefs on c276). The game itself calls `SetTorqueTF*` zero times. So the -texture is G HUB's synthesis, and there is no G HUB on Linux and no -non-synthesised signal to obtain - reproducing it means synthesising like G HUB -and fitting to this capture. The compat-mode(c272)/OEM-driver path is a dead -end for AC EVO texture (and c272 needs a physical wheel-OLED switch). +texture is G HUB's synthesis. There is no G HUB on Linux and no +non-synthesised signal to obtain. To reproduce it, synthesise like G HUB and +fit the result to this capture. The compat-mode(c272)/OEM-driver path is a +dead end for AC EVO texture (and c272 needs a physical wheel-OLED switch). ## The texture recipe (the tuning table) -An engine-firing-frequency harmonic stack, amplitude subtle: +The texture is a harmonic stack on the engine firing frequency, at a subtle +amplitude: | f0 (firing freq) | h2/h1 | h3/h1 | h4/h1 | h5/h1 | |---|---|---|---|---| @@ -36,18 +41,18 @@ An engine-firing-frequency harmonic stack, amplitude subtle: | 290-360 Hz | 0.28 | 0.33 | 0.08 | 0.07 | - Amplitude: rms ~ 72 + 1.13 * f0 counts, i.e. **0.7% of fullscale at low - revs rising to ~1.5% at high revs**. Occasional transients to ~2.3%. + revs rising to ~1.5% at high revs**. Occasional transients reach ~2.3%. - Harmonic falloff is much steeper than logi-tf-sim's current - `HARMONIC_GAINS [1.0, 0.5, 0.25]`: the real h2 is ~0.2-0.3 and h3 + `HARMONIC_GAINS [1.0, 0.5, 0.25]`. The real h2 is ~0.2-0.3 and h3 is ~0.1-0.33 (h3 RISES with revs). Our synth is too bright and too loud - relative to the real thing unless intensity is well below 100. + next to the real thing unless intensity is well below 100. - At idle the fundamental may be suppressed (peaks at 2x/3x/4x of ~56.5 Hz - for a ~850 rpm V8); at mid/high revs the fundamental dominates. + for a ~850 rpm V8). At mid/high revs the fundamental dominates. ### Rigorous re-measurement 2026-08-13 (2048-pt windowed FFT, FS=3983 Hz) -251,299 samples reconstructed; overall rms **1.48% FS**, 88% non-zero. -Fundamental (firing freq) ranges 41-385 Hz. Median harmonic ratios and +251,299 samples were reconstructed. Overall rms is **1.48% FS**, 88% non-zero. +The fundamental (firing freq) ranges 41-385 Hz. Median harmonic ratios and amplitude, binned by f0: | f0 band (Hz) | rms (%FS) | h2/h1 | h3/h1 | h4/h1 | h5/h1 | @@ -58,28 +63,28 @@ amplitude, binned by f0: | 240-290 | 1.27 | 0.23 | 0.13 | 0.08 | 0.07 | | 290-360 | 1.61 | 0.27 | 0.25 | 0.07 | 0.05 | -Confirms the earlier table: h2 rises ~0.11->0.27 and h3 ~0.08->0.25 with revs, -amplitude climbs ~0.5%->1.6% FS. The idle band's high ratios reflect the +This confirms the earlier table. h2 rises ~0.11->0.27 and h3 ~0.08->0.25 with +revs. Amplitude climbs ~0.5%->1.6% FS. The idle band's high ratios reflect the suppressed fundamental (energy sits at 2x/3x). Extraction: `/tmp/tex_samples.txt` from the awk+numpy pipeline in the 2026-08-13 session. BeamNG on Windows (`g_pro_tf_2026-04-19/2026-04-19_trueforce_beamng.pcapng`) -carries 46,883 sample-packets and can cross-check the model on a second +carries 46,883 sample-packets. It can cross-check the model on a second title. ## Where to inject under Proton (resolved: kernel-side merge) -The SDK owns the ep3 stream (single writer) and fills only `cur`. Options -considered: +The SDK owns the ep3 stream (single writer) and fills only `cur`. Two options +were considered: 1. **Kernel-side merge**: the stream passes through the kernel (hidraw - write path); rewrite passing type-0x01 packets to add synth samples + - count, exactly where Windows merges them. Base force stays bit-identical - SDK output; texture is ours, tuned from this recipe, fed RPM via - `wheel_texture_rpm`, written by `logi-rpm-bridge` from the proxy's - telemetry relay. + write path). Rewrite passing type-0x01 packets to add synth samples and + a count, exactly where Windows merges them. The base force stays + bit-identical SDK output. The texture is ours, tuned from this recipe. + It gets RPM via `wheel_texture_rpm`, which `logi-rpm-bridge` writes from + the proxy's telemetry relay. 2. **Own the stream**: drop the SDK, forward KF through libtrueforce and - mix texture in userspace. Simpler layering, but replaces the SDK's + mix texture in userspace. This is simpler layering. It replaces the SDK's bit-identical cur with our reconstruction. **Resolved**: option 1 was implemented and hardware-validated (2026-08-14, diff --git a/docs/TRUEFORCE_PROTOCOL.md b/docs/TRUEFORCE_PROTOCOL.md index d9a97d6..4bf3b55 100644 --- a/docs/TRUEFORCE_PROTOCOL.md +++ b/docs/TRUEFORCE_PROTOCOL.md @@ -2,16 +2,16 @@ > **Status**: the kernel driver leaves interface 2's hidraw node open for userspace. Two userspace paths consume that node: > -> - **Proton sims (verified working)**: `tools/install-tf-shim.sh` copies Logitech's own Authenticode-signed SDK DLLs (`trueforce_sdk_x64.dll`, `logi_steering_wheel_x64.dll`) into each Wine prefix and registers the CLSIDs. The unmodified DLLs run inside Wine and write to the wheel via Wine's HID stack, which reaches our kernel driver. No shim, no IAT hooks, no certificate spoofing. End-to-end verified against **Assetto Corsa Competizione** and **Assetto Corsa EVO** under Proton on RS50 in **both modes**: G PRO compatibility mode (`046d:c272`, 2026-04-26 / 2026-04-29) and **native mode** (`046d:c276`, AC EVO, 2026-07-08). The native run was usbmon-confirmed: Wine's HID backend opened interface 2 on the native PID and the SDK streamed ~2 kHz of type-0x01 packets (239k OUT over ~120 s) on ep 0x03. The SDK DLLs open and drive the wheel identically at either PID, so compat mode is not required for TrueForce. -> - **Native Linux apps**: `userspace/libtrueforce/` is a native C reimplementation of the same protocol described below. Useful for Linux apps that want to drive TrueForce directly (telemetry-driven haptic generators, custom test rigs, etc.). +> - **Proton sims (verified working)**: `tools/install-tf-shim.sh` copies Logitech's own Authenticode-signed SDK DLLs (`trueforce_sdk_x64.dll`, `logi_steering_wheel_x64.dll`) into each Wine prefix and registers the CLSIDs. The unmodified DLLs run inside Wine. They write to the wheel via Wine's HID stack, which reaches our kernel driver. No shim, no IAT hooks, no certificate spoofing. This is end-to-end verified against **Assetto Corsa Competizione** and **Assetto Corsa EVO** under Proton on RS50 in **both modes**: G PRO compatibility mode (`046d:c272`, 2026-04-26 / 2026-04-29) and **native mode** (`046d:c276`, AC EVO, 2026-07-08). The native run was usbmon-confirmed. Wine's HID backend opened interface 2 on the native PID, and the SDK streamed ~2 kHz of type-0x01 packets (239k OUT over ~120 s) on ep 0x03. The SDK DLLs open and drive the wheel identically at either PID, so compat mode is not required for TrueForce. +> - **Native Linux apps**: `userspace/libtrueforce/` is a native C reimplementation of the same protocol described below. It is useful for Linux apps that want to drive TrueForce directly (telemetry-driven haptic generators, custom test rigs, etc.). > -> Originally reverse-engineered from [issue #5](https://github.com/mescon/logitech-trueforce-linux-driver/issues/5) captures (BeamNG.drive + G Pro, contributed by [@SandSeppel](https://github.com/SandSeppel)) and re-verified 2026-04-21 against an RS50 + ACC capture on the same host. The two wheels use byte-for-byte identical init and streaming packets. +> The protocol was originally reverse-engineered from [issue #5](https://github.com/mescon/logitech-trueforce-linux-driver/issues/5) captures (BeamNG.drive + G Pro, contributed by [@SandSeppel](https://github.com/SandSeppel)). It was re-verified 2026-04-21 against an RS50 + ACC capture on the same host. The two wheels use byte-for-byte identical init and streaming packets. ## Overview -TRUEFORCE is a high-frequency audio-haptic stream that supplements traditional PID force feedback. Rather than low-rate constant-force updates (~50-100 Hz via HID SET_REPORT), TRUEFORCE sends a ~1000 Hz audio waveform directly to the wheel's DSP, which drives the motor with much higher fidelity. +TRUEFORCE is Logitech's high-rate haptic channel. It is a high-frequency audio-haptic stream that supplements traditional PID force feedback (PID is the USB HID "physical interface device" class for classic force-feedback effects). Classic force feedback sends low-rate constant-force updates (~50-100 Hz via HID SET_REPORT). TRUEFORCE instead sends a ~1000 Hz audio waveform directly to the wheel's DSP (digital signal processor), which drives the motor with much higher fidelity. -The protocol runs entirely on **USB Interface 2** (endpoints `0x03 OUT` / `0x83 IN`), which the kernel driver delegates to hidraw. No HID++ feature activation is required; userspace opens the hidraw node for interface 2 and starts writing. +The protocol runs entirely on **USB Interface 2** (endpoints `0x03 OUT` / `0x83 IN`). The kernel driver delegates that interface to hidraw (the raw HID device node). No HID++ feature activation is required. Userspace opens the hidraw node for interface 2 and starts writing. ## Wheel Coverage @@ -28,14 +28,15 @@ The 68-packet init sequence is identical across the RS50 and G Pro, byte-for-byt **The G923 Xbox edition (`c26e`) carries it too, confirmed 2026-08-10** from a Windows capture of that wheel under Automobilista 2 (issue #27). Over roughly 40 seconds it received **17597** type-0x01 stream packets on its `0xFFFD` -interface, against **24** HID++ `0x8123` commands which are setup only -(`RESET_ALL`, gains, effect create/play). The stream matches the documented -layout byte for byte: byte[5] a rolling sequence, bytes[6-9] `cur` duplicated, -byte[10] the new-sample count, `00 80 00 80 00` at idle and `04` samples while -driving. So its force arrives on the stream, not over HID++, and simulated -TrueForce should be able to drive that wheel the same way it drives a `c266`. +interface. In the same time it received **24** HID++ `0x8123` commands, which +are setup only (`RESET_ALL`, gains, effect create/play). The stream matches +the documented layout byte for byte: byte[5] a rolling sequence, bytes[6-9] +`cur` duplicated, byte[10] the new-sample count, `00 80 00 80 00` at idle and +`04` samples while driving. So its force arrives on the stream, not over +HID++. Simulated TrueForce should be able to drive that wheel the same way it +drives a `c266`. -The gear-driven **G923** carries the same interface-2 transport and stream protocol (first established by the TF4ALL project's Windows captures, issue #20; hardware-confirmed on a c266 by `logi-tf-sim`'s synthetic sweep). One G923-specific caveat: while a type-0x01 stream runs, the wheel's motor follows the stream's `cur` field and stops reacting to its classic interface-0 force-feedback commands, so a G923 streamer must mirror the live FFB into `cur` for the stream's duration - `logi-tf-sim` reads the kernel driver's `ffb_output` sysfs attribute for exactly this (see `SYSFS_API.md`). Feel under real game telemetry is not yet verified on the G923. +The gear-driven **G923** carries the same interface-2 transport and stream protocol. The TF4ALL project's Windows captures first established this (issue #20). `logi-tf-sim`'s synthetic sweep then hardware-confirmed it on a c266. One G923-specific caveat: while a type-0x01 stream runs, the wheel's motor follows the stream's `cur` field and stops reacting to its classic interface-0 force-feedback commands. So a G923 streamer must mirror the live FFB into `cur` for the stream's duration. `logi-tf-sim` reads the kernel driver's `ffb_output` sysfs attribute for exactly this (see `SYSFS_API.md`). Feel under real game telemetry is not yet verified on the G923. ## Traffic Characterisation @@ -45,7 +46,7 @@ The gear-driven **G923** carries the same interface-2 transport and stream proto | PID constant force updates (intf 1) | ongoing | small, init only | | Endpoint `0x03` packet rate | idle | 1000 Hz, all senders: libtrueforce, the kernel's unified stream, and games (AC EVO already used 1000; 250-500 seen in older captures). 1000 is both Logitech's stated 1 ms TRUEFORCE interval and the USB interrupt-endpoint ceiling. | | Samples per packet (new) | N/A | 4 new + 9 history = 13-slot rolling window | -| Effective audio sample rate | N/A | ~1000 Hz (250 pkt/s * 4 new samples) | +| Effective audio sample rate | N/A | ~4 kHz (1000 pkt/s * 4 new samples) | When TRUEFORCE is active, traditional PID FFB is used only for initial setup and occasional parameter changes. The high-frequency force data moves entirely to the audio stream. @@ -68,7 +69,7 @@ byte[5]: SEQUENCE Rolling u8 counter (0x00-0xFF wrap), shared acros byte[6..]: PAYLOAD Type-specific ``` -The sequence counter is rewritten at send time from a session-local counter. Each pass through the init sequence restarts the counter at 1; after init the stream continues from where init left off. +The sequence counter is rewritten at send time from a session-local counter. Each pass through the init sequence restarts the counter at 1. After init, the stream continues from where init left off. ## Command Types (Host -> Device, endpoint 0x03) @@ -86,7 +87,7 @@ The sequence counter is rewritten at send time from a session-local counter. Eac ## Initialisation Sequence (sent twice) -G Hub sends a 68-packet init sequence, then sends the **same 68 packets a second time** (sequence counter reset to 1 at the start of each pass) before the main per-sample stream begins. The init must be sent twice: a single pass is unreliable on cold boot. Both the 2026-04-19 G Pro + BeamNG and 2026-04-21 RS50 + ACC captures show the duplicate pass. +G Hub sends a 68-packet init sequence. It then sends the **same 68 packets a second time** (sequence counter reset to 1 at the start of each pass) before the main per-sample stream begins. The init must be sent twice. A single pass is unreliable on cold boot. Both the 2026-04-19 G Pro + BeamNG and 2026-04-21 RS50 + ACC captures show the duplicate pass. The 68 packets are stored verbatim in `userspace/libtrueforce/src/tf_init_data.h`. Breakdown: @@ -107,10 +108,10 @@ The 68 packets are stored verbatim in `userspace/libtrueforce/src/tf_init_data.h Key type-0x05 parameter values, for reference. **Note:** the committed init we replay (`userspace/libtrueforce/src/tf_init_data.h`) sends every type-0x05 packet with a **zero** value payload (only the index byte -varies), and TrueForce still works end-to-end, so these specific values +varies). TrueForce still works end-to-end, so these specific values are not required for basic operation. The table below records the -non-zero values decoded from G Hub's own init capture, kept as a guide to -what each index means: +non-zero values decoded from G Hub's own init capture. It is kept as a guide +to what each index means: | Index | Value | Likely meaning | |-------|-------|----------------| @@ -131,11 +132,11 @@ what each index means: ## Device Replies During Set-up (endpoint `0x83` -> host) -Read from a Windows capture of G HUB and iRacing on an RS50 (2026-07-27), -which carries both directions of interface 2 through a complete session -start; the mid-stream captures elsewhere in this project only show the -`0x01`/`0x02` pair. Header `01 00 00 00` stripped, bytes after the payload -zero. +These replies were read from a Windows capture of G HUB and iRacing on an +RS50 (2026-07-27). That capture carries both directions of interface 2 +through a complete session start. The mid-stream captures elsewhere in this +project only show the `0x01`/`0x02` pair. The header `01 00 00 00` is +stripped, and the bytes after the payload are zero. | Host sends | Wheel answers | |---|---| @@ -160,10 +161,10 @@ OUT 04 43 00 IN 02 43 ca bf 03 00 80 00 80 b4 30 1e 0a 13 00 00 80 00 00 OUT 03 44 00 IN 02 43 ca bf 03 00 80 00 80 52 38 1e 0a 81 00 00 80 00 00 80 07 00 00 1d 95 00 00 1d 95 91 ``` -Each `0x05` reply arrived about 2 ms after its question, and G HUB waited -for it before sending the next, so a host that expects the wheel to answer -every parameter (a PlayStation 5 does, per [#131](../../issues/131)) is -expecting exactly this. +Each `0x05` reply arrived about 2 ms after its question. G HUB waited for it +before sending the next. So a host that expects the wheel to answer every +parameter (a PlayStation 5 does, per [#131](../../issues/131)) is expecting +exactly this. ## Audio Data Stream (Type `0x01`) @@ -185,47 +186,47 @@ byte[60-63]: window[12] **Layout invariants observed across captures and replicated in `src/stream.c`:** - The 13-slot rolling window holds the most recent samples, oldest at `window[0]`, newest at `window[12]`. -- Each packet advances the window by **as many samples as byte 10 declares**; that many fall off the front. G Hub sends 4 almost always and 5 in some captures, so the field is a count and not a constant. `libtrueforce` sends 4 in the steady state, fewer when a drain came up short, and up to 12 (`LOGITF_TF_CATCHUP_MAX`) on a packet making up a coalesced timer expiry. 13 is the ceiling the window can express. -- Every u16 sample is duplicated (L and R channels). The wheel is single-motor, the stereo duplication is ceremonial. +- Each packet advances the window by **as many samples as byte 10 declares**. That many fall off the front. G Hub sends 4 almost always and 5 in some captures, so the field is a count and not a constant. `libtrueforce` sends 4 in the steady state, fewer when a drain came up short, and up to 12 (`LOGITF_TF_CATCHUP_MAX`) on a packet making up a coalesced timer expiry. 13 is the ceiling the window can express. +- Every u16 sample is duplicated (L and R channels). The wheel is single-motor. The stereo duplication is ceremonial. - Values are unsigned 16-bit little-endian, offset binary (centre `0x8000`, `0x0000` = full left, `0xFFFF` = full right). - The preamble at bytes 6-9 ("cur") is the **motor torque target**, duplicated as - two u16 LE. While a TrueForce session is active the wheel steers by cur and - the window plays additively on top as audio; cur OVERRIDES the HID++ 0x8123 + two u16 LE. While a TrueForce session is active the wheel steers by cur. The + window plays additively on top as audio. cur OVERRIDES the HID++ 0x8123 force path. In G Hub/SDK captures cur usually tracks the newest window - sample only because the games stream their FFB there. AC EVO carries its - game force in cur; the independent audio in the window of the same packet - is NOT the game's - AC EVO never calls the SDK's texture entry points - (`SetTorqueTF`/`SetStreamTF`, never even probes `GetTorqueTFRateBounds`), - so the window content in Windows captures is the driver stack's own - synthesis, fed by the game's Escape telemetry and serialized into the - same stream as the game's SDK force (which is why the sequence counter - is continuous). The kernel driver's texture merge replicates that - architecture. (cur semantics from the TF4ALL project's Windows captures; - synthesis attribution established 2026-08-14.) + sample, but only because the games stream their FFB there. AC EVO carries + its game force in cur. The independent audio in the window of the same + packet is NOT the game's. AC EVO never calls the SDK's texture entry points + (`SetTorqueTF`/`SetStreamTF`, and it never even probes + `GetTorqueTFRateBounds`). So the window content in Windows captures is the + driver stack's own synthesis. It is fed by the game's Escape telemetry and + serialized into the same stream as the game's SDK force (which is why the + sequence counter is continuous). The kernel driver's texture merge + replicates that architecture. (cur semantics come from the TF4ALL project's + Windows captures; the synthesis attribution was established 2026-08-14.) - Bytes 10 and 11 are a **demux pair, not independent constants** - (hardware-proven 2026-08-14): every sample-carrying packet pairs - `byte10 != 0` with `byte11 = 0x0d`, and every no-new-samples packet + (hardware-proven 2026-08-14). Every sample-carrying packet pairs + `byte10 != 0` with `byte11 = 0x0d`. Every no-new-samples packet (menu keepalive, plain force) pairs `byte10 = 0x00` with `byte11 = 0x00`. The combination `byte10 = 0x04` + `byte11 = 0x00` - never occurs in Windows captures, and the wheel **silently discards - the whole sample window** of such a packet while still honouring its - cur bytes - a wire-perfect texture stream that renders nothing. Any + never occurs in Windows captures. The wheel **silently discards + the whole sample window** of such a packet while it still honours the + packet's cur bytes: a wire-perfect texture stream that renders nothing. Any producer that adds samples to a packet must also stamp `0x0d`. -Packet cadence in libtrueforce is 1000 Hz (4 new samples * 1000 Hz = 4000 sample/s effective); the kernel driver's unified stream runs at the same 1000 Hz (4 kHz slot rate, 4 kHz unique content), driven by an hrtimer because a self-rearming jiffies timer cannot hold this rate. Games vary: ACC captures show 250-500 pkt/s, AC EVO up to ~1000 pkt/s (4 kHz audio) per TF4ALL measurements - the wheel accepts the whole range. If userspace can't keep up the thread holds the window for `LOGITF_TF_STARVE_HOLD_TICKS` and then flushes it toward centre while the held force unwinds (Windows does something similar under input starvation). If userspace overruns the transport, `logitf_stream_push_s16()` drops the OLDEST queued samples to hold the backlog to `LOGITF_TF_MAX_PENDING_MS` of audio, counting and reporting them; it does not block. +Packet cadence in libtrueforce is 1000 Hz (4 new samples * 1000 Hz = 4000 sample/s effective). The kernel driver's unified stream runs at the same 1000 Hz (4 kHz slot rate, 4 kHz unique content). An hrtimer drives it, because a self-rearming jiffies timer cannot hold this rate. Games vary: ACC captures show 250-500 pkt/s, and AC EVO up to ~1000 pkt/s (4 kHz audio) per TF4ALL measurements. The wheel accepts the whole range. If userspace cannot keep up, the thread holds the window for `LOGITF_TF_STARVE_HOLD_TICKS` and then flushes it toward centre while the held force unwinds (Windows does something similar under input starvation). If userspace overruns the transport, `logitf_stream_push_s16()` drops the OLDEST queued samples to hold the backlog to `LOGITF_TF_MAX_PENDING_MS` of audio. It counts and reports the dropped samples. It does not block. ## One writer at a time (measured 2026-08-17) **The stream has exactly one owner, and the endpoint enforces it whether the software agrees or not.** Endpoint `0x03` is an interrupt OUT with a -1 ms interval, so it carries one packet per millisecond in total, not -one per writer. Two programs each streaming at 1 kHz therefore do not -share it, they take turns on it: each gets every other frame. +1 ms interval. So it carries one packet per millisecond in total, not +one per writer. Two programs that each stream at 1 kHz therefore do not +share it. They take turns on it: each gets every other frame. What that does to the wheel is worse than halving a rate. Bytes 6-9 are a level, not an event: the wheel holds the last value it was given. So with two writers the torque target alternates between their two values -every millisecond, which is a 500 Hz square wave on the motor. Measured +every millisecond. That is a 500 Hz square wave on the motor. Measured on an RS50 with the kernel driver and a userspace producer both streaming: @@ -237,32 +238,32 @@ streaming: | 450-500 Hz content in the torque field | dominant | none | (The one-writer column is the finished state. Making the driver yield -took the rate from 1934/s to 3635/s on its own; the remaining gap was a -producer discarding coalesced timer expirations, and closing that +took the rate from 1934/s to 3635/s on its own. The remaining gap was a +producer discarding coalesced timer expirations. Closing that reached 3860/s against a 4000/s clock.) -Audibly this is a fixed buzz that does NOT move with the engine note, at -exactly 500.00 Hz with a strong third harmonic and almost no second: the -odd-harmonic signature of a level stepping every 2 ms rather than a +Audibly this is a fixed buzz that does NOT move with the engine note. It +sits at exactly 500.00 Hz with a strong third harmonic and almost no second. +That is the odd-harmonic signature of a level stepping every 2 ms, not a resonance (issue #59). The samples also play at half rate, an octave low. Consequences for anyone implementing this protocol: - **Take the stream, do not join it.** Before streaming, establish that - nothing else is: on Linux the kernel driver yields automatically (it + nothing else is. On Linux the kernel driver yields automatically (it detects a userspace writer on interface 2 and stops sending its own - packets), but two userspace programs must arbitrate between + packets). Two userspace programs must arbitrate between themselves. - **The torque field belongs to whoever owns the stream.** When the - driver yields it does not go silent: if it has force of its own to - apply it writes that force into bytes 6-9 of the owner's packet on - the way past, so one packet carries the owner's samples and the + driver yields it does not go silent. If it has force of its own to + apply, it writes that force into bytes 6-9 of the owner's packet on + the way past. So one packet carries the owner's samples and the driver's force. It leaves those bytes alone when it has no effect running, because a native SDK session puts the GAME's force there and overwriting it would replace force feedback with dead centre. - **A silent endpoint is the normal idle state.** With nothing streaming - there is no traffic at all on `0x03`; G HUB holds no idle session + there is no traffic at all on `0x03`. G HUB holds no idle session open, and neither should anything else (see the whine notes in the session-state section). @@ -281,10 +282,10 @@ byte[6-9]: f32 LE Operating range, degrees Evidence: -- The canonical init's packet 50 carries `2700.0` - exactly the +- The canonical init's packet 50 carries `2700.0`. That is exactly the wheel's maximum range, not a plausible sample rate. - AC EVO's SDK session init appends a second `0x0e` with `90.0` - (`01000000 0e 0000b442`), and the wheel's physical range + (`01000000 0e 0000b442`). The wheel's physical range flips 900 -> 90 in the same 20-second window with ZERO HID++ traffic on interface 1 (confirmed: the only interface-1 range packets in the entire capture are the Linux driver's own polls, @@ -294,80 +295,80 @@ Evidence: `2700.0` = `01 00 00 00 0e 32 00 c0 28 45` (2026-08-14 usbmon, AC EVO session init). -A session init sends **multiple** `0x0e` pushes, not one: the +A session init sends **multiple** `0x0e` pushes, not one. The 2026-08-14 capture shows `2700.0`, then `90.0`, then `2700.0` again in -the same init, which reads as the SDK negotiating its bounds around +the same init. That reads as the SDK negotiating its bounds around the clamp rather than writing the final value once. Consumers of this packet (the kernel driver's decode, any replay tooling) must not -assume a single push per session and must track the latest value seen, +assume a single push per session. They must track the latest value seen, not the first. -This is `logiWheelSetOperatingRange*()` on the wire, and it explains +This is `logiWheelSetOperatingRange*()` on the wire. It explains why the launch-time range reset never produced a HID++ broadcast: it does not go through the HID++ range feature at all. Games push their -configured steering rotation here at session start; a game whose +configured steering rotation here at session start. A game whose rotation setting is 90 (or defaulted) locks the wheel to 90 degrees. -The kernel driver's 20 s range poll detects the change and, by -default, restores the pre-reset range automatically (the -`wheel_range_restore` sysfs attribute; verified end-to-end with a +The kernel driver's 20 s range poll detects the change. By +default it restores the pre-reset range automatically (the +`wheel_range_restore` sysfs attribute). This is verified end-to-end with a detection-to-restore latency of ~60 ms against a faithful replay of -the game traffic). Re-applying a range via HID++ sticks - the SDK +the game traffic. Re-applying a range via HID++ sticks, because the SDK write is one-shot at session init. -Two firmware behaviours discovered while reproducing this +Two firmware behaviours were discovered while reproducing this (2026-07-03, live wheel): - **Type-`0x0e` is session-scoped, and the scope is the started stream, not the init** (sharpened 2026-08-14, live wheel + felt - stops): a `0x0e` push is ignored on an idle interface AND after the - init sequence alone - the canonical init's own `2700.0` pushes are + stops). A `0x0e` push is ignored on an idle interface AND after the + init sequence alone. The canonical init's own `2700.0` pushes are no-ops because they precede the `0x03` START. The range write only takes effect between `0x03` START and `0x04` STOP. A mid-stream push applies immediately (900 -> 90 clamp felt at the rim; the wheel broadcasts the change over HID++). - **Idle revert**: if a TF session goes quiet (no stream packets, - roughly a minute) the firmware reverts the session's range change + roughly a minute), the firmware reverts the session's range change on its own and broadcasts the restored value over HID++. A running - game keeps its session alive, which is why real launch-time resets + game keeps its session alive. That is why real launch-time resets persist. ### Session state and the force-mode latch Hardware-proven across many sessions: `logiWheelSetForceMode(1)` -latches in the wheel itself, not just in the SDK, and stays latched +latches in the wheel itself, not just in the SDK. It stays latched until a REAL power cycle. A USB reset is not enough, because the base -has its own PSU independent of the USB bus. Consequences, both +has its own PSU independent of the USB bus. Two consequences, both observed on real hardware: - A second SDK session started without a power cycle comes up with a dead haptic thread: status `0x80000008`, no ep3 OUT stream at all. - A hard-killed session (game terminated rather than closed cleanly) - leaves the wheel's stream engine running on its own: the wheel keeps + leaves the wheel's stream engine running on its own. The wheel keeps streaming ep `0x83` IN reports at 2 kHz indefinitely, with nothing on the host consuming them, until the base is power-cycled. Refinement (2026-08-14): after a session dies without its teardown reaching the wheel (hard kill, crash), the next session's -`logiWheelSetForceMode(1)` **returns success** yet there is zero ep3 -traffic **in both directions** - and a healthy session also carries a +`logiWheelSetForceMode(1)` **returns success**, yet there is zero ep3 +traffic **in both directions**. A healthy session also carries a ~1 kHz ep3 IN status stream, so its absence is the diagnostic, not just missing OUT packets. Power-cycling the base before launch recovers it. Running `logi-tf-init` between sessions is untested/inconclusive as a recovery. An experimental pre-launch re-arm exists: `LOGI_TF_REARM=1` makes `logi-launch` send the `0x04`+`0x03` pair and then the 68-packet init twice from `tools/tf-init.bin` before -the game starts; it is off by default pending hardware validation. +the game starts. It is off by default pending hardware validation. Anyone reproducing SDK captures or writing session teardown code needs to power-cycle the base between sessions, not just close and reopen the handle. **LED / HID++ traffic during a live session** (hardware, 2026-08-14): -the driver's old rev-LED form - an arm burst plus per-level fn3 -activation - was fatal to a native TrueForce SDK session: sent at init -it killed the session, sent mid-session it killed wheel input. The +the driver's old rev-LED form (an arm burst plus per-level fn3 +activation) was fatal to a native TrueForce SDK session. Sent at init +it killed the session. Sent mid-session it killed wheel input. The current form (bare SHORT fn2 GET_STATE + LONG fn6 level, nothing else) -coexists cleanly: base FFB + TrueForce texture + telemetry-driven rev +coexists cleanly. Base FFB + TrueForce texture + telemetry-driven rev LEDs are hardware-validated running together. See `PROTOCOL_SPECIFICATION.md` section 9 for the rev-LED wire protocol. @@ -379,27 +380,31 @@ LEDs are hardware-validated running together. See | G923 Xbox (`c26e`) | **no**, see below | | G923 PlayStation (`c266`) | **no**, tested on hardware | -The Xbox edition is disproved on hardware: in ACC's own config screen the -rim turns its full 900 degrees and the input bar tracks the whole way, with -the limit appearing only on track. A real operating-range change would +The Xbox edition is disproved on hardware. In ACC's own config screen the +rim turns its full 900 degrees and the input bar tracks the whole way. The +limit appears only on track. A real operating-range change would soft-stop the rim everywhere, menus included. So the wheel is never -reconfigured on that edition; the game clamps its own steering because it believes the wheel has -90 degrees of travel, which it gets from the TrueForce SDK falling back to -the minimum of the legal range when it cannot reach G HUB. Nothing on the -wheel is wrong, so there is nothing for a range restore to put back. - -The PlayStation edition was tested directly: a live TrueForce session was -established (full init sequence sent, silent stream running, confirmed by the -daemon's own `stream start`), a type-`0x0e` carrying `90.0` was pushed on the -`0xFFFD` transport, and the rim then turned its full travel with no early soft -stop. Repeated with the session up rather than idle, since the first attempt -made exactly the mistake the session-scoping note above describes, and a bare -push on an idle interface is a no-op on every wheel including the RS50. +reconfigured on that edition. The game clamps its own steering because it +believes the wheel has 90 degrees of travel. It gets that belief from the +TrueForce SDK, which falls back to the minimum of the legal range when it +cannot reach G HUB. Nothing on the wheel is wrong, so there is nothing for a +range restore to put back. + +The PlayStation edition was tested directly: + +1. A live TrueForce session was established (full init sequence sent, + silent stream running, confirmed by the daemon's own `stream start`). +2. A type-`0x0e` carrying `90.0` was pushed on the `0xFFFD` transport. +3. The rim then turned its full travel with no early soft stop. + +This was repeated with the session up rather than idle. The first attempt +made exactly the mistake the session-scoping note above describes: a bare +push on an idle interface is a no-op on every wheel, including the RS50. That bounds the operating-range restore work to the wheels whose force rides HID++: the direct-drive wheels, which already heal it, and the G923 Xbox edition, which has `range_restore` (see `docs/SYSFS_API.md`). The PlayStation -edition's classic engine exposes no range readback at all, so it is fortunate +edition's classic engine exposes no range readback at all. So it is fortunate rather than incidental that it needs none. AC EVO's init also differs from the canonical G Hub init in two more @@ -423,40 +428,40 @@ byte[33-63]: zeros ``` **Bytes 6-7 are not a motor load reading.** They were guessed to be current -or temperature, which would have made them the only route this project has to -answering "how hard is it safe to drive this motor". Tested on an RS50 -(2026-08-08) with `tests/motorlog`, which drives a known amplitude and then -pushes exact silence while still sampling, because current collapses with the -force and temperature decays over tens of seconds: +or temperature. That would have made them the only route this project has to +answering "how hard is it safe to drive this motor". They were tested on an +RS50 (2026-08-08) with `tests/motorlog`. That tool drives a known amplitude +and then pushes exact silence while it keeps sampling, because current +collapses with the force and temperature decays over tens of seconds: - The value slides steadily downward at the same rate whether the wheel is - being driven hard or sitting silent, which neither hypothesis allows. + being driven hard or sitting silent. Neither hypothesis allows that. - It wraps through zero to 0xFFFF and then goes flat exactly when the status - byte changes 3 -> 2, so it is tied to stream state rather than to load. + byte changes 3 -> 2. So it is tied to stream state rather than to load. - Across amplitudes 0.05, 0.30 and 0.60 its range overlaps almost completely - (min 1105 to max 62794 at the *lowest* amplitude), so per-amplitude + (min 1105 to max 62794 at the *lowest* amplitude). So per-amplitude statistics are dominated by the wrapping. -Counter-like, and still undecoded. What matters for anyone arriving with the -same idea: there is currently **no known telemetry from these wheels that -reports motor load, current or temperature**, so amplitude limits have to be -argued from what the motor is commanded to do, not measured from what it -reports. +It is counter-like, and still undecoded. What matters for anyone arriving +with the same idea: there is currently **no known telemetry from these wheels +that reports motor load, current or temperature**. So amplitude limits have +to be argued from what the motor is commanded to do, not measured from what +it reports. -Responses arrive at the same cadence as the host's packet rate, giving real-time wheel-position feedback for synchronisation. libtrueforce's stream thread consumes them while a stream is active and exposes the latest snapshot via the Linux-native `logitf_get_stream_feedback()` API (wheel position, device counter, and the still-undecoded motor/status fields); the kernel driver ignores them. +Responses arrive at the same cadence as the host's packet rate. That gives real-time wheel-position feedback for synchronisation. libtrueforce's stream thread consumes them while a stream is active. It exposes the latest snapshot via the Linux-native `logitf_get_stream_feedback()` API (wheel position, device counter, and the still-undecoded motor/status fields). The kernel driver ignores them. ## PID FFB Commands (report `0x10`/`0x11`, for reference) -Classic PID-style FFB is addressed by HID report ID (`0x10`/`0x11`), -distinct from TRUEFORCE's report ID `0x01`; the wheel firmware -demultiplexes the two by report ID and they coexist (verified by playing +Classic PID-style FFB is addressed by HID report ID (`0x10`/`0x11`). That is +distinct from TRUEFORCE's report ID `0x01`. The wheel firmware +demultiplexes the two by report ID, and they coexist (verified by playing a sine on TRUEFORCE while holding a constant-torque KF effect). Note on interfaces: on the G920-class HID++ path these PID reports are -addressed to interface 1, but the **RS50 has no FFB OUT endpoint on +addressed to interface 1. But the **RS50 has no FFB OUT endpoint on interface 1**. The Linux driver actuates the RS50's constant force by writing to **interface 2 endpoint `0x03`** (the dedicated `hidpp_dd_ff_*` -path), the same interface TRUEFORCE uses; the two are still separated by +path), the same interface TRUEFORCE uses. The two are still separated by report ID. See [`PROTOCOL_SPECIFICATION.md`](PROTOCOL_SPECIFICATION.md) section 4 for the constant-force (KF) subset of these same ep-0x03 packets and the wider HID++ / device reference. @@ -490,24 +495,25 @@ 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` | 250 Hz timerfd loop, 13-slot rolling window, `logitf_stream_push_s16()` / `_clear()` / `_start/stop()` | +| `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 | ## Open Items -- libtrueforce consumes type-`0x02` device responses while a stream is active and exposes them via `logitf_get_stream_feedback()` (2026-07-02). The motor field (bytes 6-7), status byte (8), and byte 17 checksum-like field are still undecoded; correlating the motor field against commanded torque on a live wheel would pin it down. -- ~~The constant flag word at byte 11 (`0x0d`) is passed through verbatim; its exact meaning is still not decoded.~~ **Resolved 2026-08-14**: byte 11 is the sample-window valid flag, one half of the byte10/byte11 demux pair (see the stream layout invariants above); the wheel discards the window of any packet that carries samples without it. Value `0x05` has been seen instead of `0x04` in byte 10 in some captures, corresponding to 5 new samples; libtrueforce sent the 4-new-samples variant exclusively until it began declaring the real count (4 in the steady state, fewer on a short drain, up to 12 when catching up a coalesced timer expiry). +- libtrueforce consumes type-`0x02` device responses while a stream is active and exposes them via `logitf_get_stream_feedback()` (2026-07-02). The motor field (bytes 6-7), status byte (8), and byte 17 checksum-like field are still undecoded. Correlating the motor field against commanded torque on a live wheel would pin it down. +- ~~The constant flag word at byte 11 (`0x0d`) is passed through verbatim; its exact meaning is still not decoded.~~ **Resolved 2026-08-14**: byte 11 is the sample-window valid flag, one half of the byte10/byte11 demux pair (see the stream layout invariants above). The wheel discards the window of any packet that carries samples without it. Value `0x05` has been seen instead of `0x04` in byte 10 in some captures, corresponding to 5 new samples. libtrueforce sent the 4-new-samples variant exclusively until it began declaring the real count (4 in the steady state, fewer on a short drain, up to 12 when catching up a coalesced timer expiry). - Per-title parameter variation (are the 48 init floats game-specific or universal?) is unconfirmed. So far the same data produces audible TRUEFORCE across BeamNG and ACC. ## The SDK's own IPC, and where 90 degrees comes from The type-`0x0e` section above explains how a range reaches the wheel. This -explains why the number is so often 90, which was open for a long time and is -now settled. +section explains why the number is so often 90. That was open for a long +time and is now settled. -`trueforce_sdk_x64.dll` contains a local IPC layer, `logi::local_connection`, -with a client, a server, and the pipe name `logi.trueforce.connect` compiled +`trueforce_sdk_x64.dll` contains a local IPC layer (inter-process +communication, how two programs on one machine talk), `logi::local_connection`. +It has a client, a server, and the pipe name `logi.trueforce.connect` compiled in. On Windows the peer is G HUB. Under Proton nothing serves that pipe. From a reporter's Wine log, repeating for as long as the game runs: @@ -516,29 +522,29 @@ CreateFileW L"\\.\pipe\logi.trueforce.connect" ... creation 3 CreateFileW Unable to create file ... (status c0000034) ``` -`creation 3` is OPEN_EXISTING and `c0000034` is STATUS_OBJECT_NAME_NOT_FOUND, -so the SDK is the client, nothing answers, and it retries forever, which +`creation 3` is OPEN_EXISTING and `c0000034` is STATUS_OBJECT_NAME_NOT_FOUND. +So the SDK is the client, nothing answers, and it retries forever. That matches the library's own string `Client failed to connect: polling again in %ld ms`. -With no peer, a game asking how far the wheel turns gets 90: not a value -anybody chose but the minimum of the legal 90-2700 range, which is why the +With no peer, a game asking how far the wheel turns gets 90. Nobody chose +that value. It is the minimum of the legal 90-2700 range, which is why the symptom is always exactly 45 degrees each way. **Answering that pipe ourselves is not possible.** On connect the SDK calls -`GetNamedPipeServerProcessId`, resolves the server to an executable with -`K32GetModuleFileNameExA`, runs `WinVerifyTrust` on it and reads the signer +`GetNamedPipeServerProcessId`. It resolves the server to an executable with +`K32GetModuleFileNameExA`. It runs `WinVerifyTrust` on it and reads the signer with `CertGetNameStringW`. The string `Logitech Inc` is compiled in. A probe serving that pipe is dropped in about a millisecond, in both message and byte -mode, which is what a rejected peer looks like rather than a rejected framing. +mode. That is what a rejected peer looks like, not a rejected framing. What is possible is answering the question the SDK cannot. A game loads the SDK through a CLSID this project's shim installer writes, so the library it -loads is ours to choose: see `tools/tf-range-proxy.c`, which forwards every +loads is ours to choose. See `tools/tf-range-proxy.c`, which forwards every 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 -four rotation getters, and none at all from the older Steering Wheel SDK, so +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. diff --git a/userspace/logi-wheel/crates/logi-wheel-core/tests/game_setup_doc.rs b/userspace/logi-wheel/crates/logi-wheel-core/tests/game_setup_doc.rs index f26c7d4..87feca8 100644 --- a/userspace/logi-wheel/crates/logi-wheel-core/tests/game_setup_doc.rs +++ b/userspace/logi-wheel/crates/logi-wheel-core/tests/game_setup_doc.rs @@ -78,50 +78,63 @@ fn render() -> String { let mut out = String::new(); out.push_str("# Game setup, per game and per wheel\n\n"); out.push_str( - "**Generated file. Do not edit.** It is rendered from the\n\ - compatibility registry in\n\ - `userspace/logi-wheel/crates/logi-wheel-core/src/games.rs` by\n\ - `tests/game_setup_doc.rs`, which fails if this file drifts from it.\n\ - The settings app resolves your own installed games against that same\n\ - registry, so what you read here is what the app will tell you.\n\n", + "**Generated file. Do not edit.** The compatibility registry in\n\ + `userspace/logi-wheel/crates/logi-wheel-core/src/games.rs` is the\n\ + source. `tests/game_setup_doc.rs` renders this file from it. The test\n\ + fails if this file drifts from the registry. The settings app checks\n\ + your own installed games against that same registry. So what you\n\ + read here is what the app will tell you.\n\n", ); out.push_str( - "**Most people need none of this.** `logi-launch %command%` in a\n\ - game's Steam launch options works the whole recipe out for the game\n\ - being launched and the wheel attached, and applies it: the raw-HID\n\ - setting only where that wheel wants it, the logi-ffb proxy for the\n\ - DirectInput games, the telemetry daemon, and the relay inside the\n\ - game's prefix for the sims that need one. A game with its own\n\ - TrueForce keeps it, and nothing is layered on top. See\n\ + "**Most people need none of this.** Put `logi-launch %command%` in a\n\ + game's Steam launch options. Launch options are the command Steam\n\ + runs to start a game. `logi-launch` works out the whole recipe for\n\ + the game and the attached wheel, and applies it. It sets the raw-HID\n\ + setting only where that wheel wants it. (Raw HID gives a game direct\n\ + access to the wheel's USB reports.) It starts the logi-ffb proxy for\n\ + the DirectInput games. (DirectInput is the older Windows\n\ + force-feedback interface. The proxy is a virtual wheel that forwards\n\ + force to the real one.) It starts the telemetry daemon. (Telemetry\n\ + is the live data a game publishes about the car: rpm, gear, speed.)\n\ + It puts the relay inside the game's prefix for the sims that need\n\ + one. (The prefix is the private Windows folder that Proton, Steam's\n\ + layer for running Windows games, makes for each game.) A game with\n\ + its own TrueForce keeps it. Nothing is layered on top. See\n\ LAUNCH_OPTIONS.md.\n\n\ - **This table is for doing it by hand**, or for working out what went\n\ - wrong. Read on for why the answer differs per wheel.\n\n", + **This table is for doing it by hand**, or for finding out what went\n\ + wrong. Read on to see why the answer differs per wheel.\n\n", ); out.push_str( "What a game needs depends on the wheel as well as the game. The\n\ - direct-drive wheels answer Logitech's TrueForce SDK, so a sim with\n\ - built-in TrueForce reaches them through the staged SDK DLLs, and\n\ - `PROTON_ENABLE_HIDRAW=1` is what lets it.\n\n\ + direct-drive wheels answer Logitech's TrueForce SDK. (The SDK is\n\ + Logitech's library that a game loads to send TrueForce haptics.) A\n\ + sim with built-in TrueForce reaches them through the staged SDK\n\ + DLLs. `PROTON_ENABLE_HIDRAW` is what lets it, and `logi-launch` sets it\n\ + scoped to the wheel, never the bare `1`.\n\n\ The G923 does not answer that SDK. Setting the variable there does\n\ - not add TrueForce, it diverts the game to raw HID reports the wheel\n\ - cannot drive force feedback through, so it costs you the force\n\ + not add TrueForce. It diverts the game to raw HID reports. The wheel\n\ + cannot drive force feedback through those. So it costs you the force\n\ feedback you already had. Leave it unset.\n\n\ - That wheel is still capable of haptics in those games, by a\n\ - different route: `logi-tf-sim` synthesizes an engine note from the\n\ - game's own telemetry, read out of its shared memory by a small relay\n\ - (`docs/SHARED_MEMORY_RELAY.md`). Confirmed working on a G923 in\n\ - Assetto Corsa Competizione and EVO.\n\n\ + That wheel can still have haptics in those games, by a different\n\ + route. `logi-tf-sim` synthesizes an engine note from the game's own\n\ + telemetry. A small relay reads that telemetry out of the game's\n\ + shared memory (`docs/SHARED_MEMORY_RELAY.md`). This is confirmed\n\ + working on a G923 in Assetto Corsa Competizione and EVO.\n\n\ The shim's `--proxy` option is not a second route in these games.\n\ - Both check the library's signature before loading it and refuse the\n\ - unsigned proxy, so it carries nothing, and on a wheel that uses\n\ - Logitech's library it costs the game that library's force feedback\n\ - too. `./tools/setup.sh doctor` flags a prefix that has it.\n\n", + (The shim is the set of Logitech SDK files staged into a game's\n\ + prefix.) Both games check the library's signature before they load\n\ + it. They refuse the unsigned proxy, so it carries nothing. On a wheel\n\ + that uses Logitech's library, it also costs the game that library's\n\ + force feedback. `./tools/setup.sh doctor` flags a prefix that has\n\ + it.\n\n", ); out.push_str( - "Launch options go in Steam under the game's Properties. Paste them\n\ - exactly, `%command%` included: it is the placeholder Steam replaces\n\ - with the game itself, so without it the line replaces the game\n\ - instead of wrapping it.\n\n", + "To set launch options:\n\n\ + 1. In Steam, open the game's Properties.\n\ + 2. Paste the line into Launch Options, exactly, `%command%`\n\ + included.\n\n\ + `%command%` is the placeholder Steam replaces with the game itself.\n\ + Without it, the line replaces the game instead of wrapping it.\n\n", ); out.push_str("## Recipes\n\n"); @@ -149,24 +162,25 @@ fn render() -> String { out.push_str(" |\n"); } out.push_str( - "\nRows marked `*` are not confirmed on this driver yet: expected or\n\ - documented rather than tested end to end.\n\n", + "\nRows marked `*` are not confirmed on this driver yet. They are\n\ + expected or documented, not tested end to end.\n\n", ); out.push_str("## Simulated TrueForce\n\n"); out.push_str( "Games with no TrueForce of their own can still have engine haptics\n\ - and rev lights, synthesized by `logi-tf-sim` from whatever telemetry\n\ - the game publishes. This works on every supported wheel, including\n\ - the G923: it is ordinary force feedback driven from telemetry, not\n\ - the SDK.\n\n\ - How the telemetry reaches the daemon depends on the game. Most\n\ - broadcast it over UDP and only need that switched on in their own\n\ - settings. Euro Truck Simulator 2 and American Truck Simulator use a\n\ - plugin instead (`docs/SCS_PLUGIN.md`), and iRacing publishes to\n\ - shared memory that a small in-prefix relay forwards\n\ - (`docs/SHARED_MEMORY_RELAY.md`). Either way, enable the game in the\n\ - app's Setup page afterwards.\n\n", + and rev lights. `logi-tf-sim` synthesizes them from whatever\n\ + telemetry the game publishes. This works on every supported wheel,\n\ + including the G923. It is ordinary force feedback driven from\n\ + telemetry, not the SDK.\n\n\ + How the telemetry reaches the daemon depends on the game. Most games\n\ + broadcast it over UDP. (UDP is a simple network protocol. The game\n\ + sends packets to a port.) Those games only need that switched on in\n\ + their own settings. Euro Truck Simulator 2 and American Truck\n\ + Simulator use a plugin instead (`docs/SCS_PLUGIN.md`). iRacing\n\ + publishes to shared memory, and a small in-prefix relay forwards it\n\ + (`docs/SHARED_MEMORY_RELAY.md`). In every case, enable the game in\n\ + the app's Setup page afterwards.\n\n", ); out.push_str("| Game | Simulated TrueForce |\n|---|---|\n"); for g in games::sorted_by_name().iter().filter(|g| g.linux != Linux::Unsupported) { @@ -179,10 +193,10 @@ fn render() -> String { // something. It does not. Simulated TrueForce is the fallback // for the wheels that cannot receive the real thing. SimTf::LiveNow(_) if g.ffb == Ffb::TrueForceShim => { - "the game's own TrueForce is the route to use; on a direct-drive wheel the helper \ - never adds haptics of its own, and where it runs beside the game it drives the \ - rev lights and the screen only; simulated haptics are the fallback for a wheel \ - that cannot receive the real thing" + "use the game's own TrueForce; on a direct-drive wheel the helper adds no \ + haptics of its own, and where it runs beside the game it drives only the rev \ + lights and the screen; simulated haptics are the fallback for a wheel that \ + cannot receive the real thing" } SimTf::LiveNow(_) => "supported today", SimTf::PossibleWithParser => "possible, needs a telemetry parser first", @@ -211,7 +225,7 @@ fn render() -> String { )); out.push_str( "- **Nothing to do.** The wheel is an ordinary Linux force feedback \ - device and the game drives it directly.\n", + device. The game drives it directly.\n", ); out.push_str("\n## Confidence\n\n"); From e174d0081310a1a7f31136ac7adeb805e96009d8 Mon Sep 17 00:00:00 2001 From: mescon <5875228+mescon@users.noreply.github.com> Date: Mon, 9 Nov 2026 23:16:59 +0100 Subject: [PATCH 3/3] docs: 0.43.0 release notes for the Racing Adapter and the accessory list Add the 0.43.0 changelog items for #139: the Racing Adapter on the base, the standalone RS Shifter & Handbrake and adapter on the Test page, and wheel_accessory listing every attached accessory (closes #144). Correct the H-Shifter button range to 12 to 20 with Reverse on button 20 (evdev 0x2c4) in the README and changelog, add the adapter to the README matrix and paragraph, and bring the FEATURE_MATRIX note and the two driver comments above wheel_accessory in line with the three-accessory list. Set the release date. --- CHANGELOG.md | 30 ++++++++++++++++++++++-------- README.md | 20 +++++++++++++++----- docs/FEATURE_MATRIX.md | 5 +++-- mainline/hid-logitech-hidpp.c | 18 ++++++++---------- 4 files changed, 48 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1cc88b7..38c6eba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,22 +5,35 @@ 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". -## 0.43.0 - Unreleased +## 0.43.0 - 2026-11-09 **The Logitech RS H-Shifter works on the RS50 and the G PRO.** Plug it into an accessory port on the wheel base. The driver finds it when the module loads and when you plug it in later. The seven gates and reverse report as -buttons 12 to 19. In desktop mode, with no game running, the driver turns +buttons 12 to 20; button 19 is not used, and reverse is button 20 (evdev +`0x2c4`). In desktop mode, with no game running, the driver turns on the base's routing for the shifter, so the gates also work on the desktop. The Info page in logi-wheel shows the gate that is in, and whether the shifter sits on the base or on its own USB cable. Written and tested on real hardware by gonzaloadrio ([#140](../../pull/140)). -**`wheel_accessory` now names the H-Shifter.** A read of the attribute -re-checks the accessory ports, so a shifter plugged in after boot shows up -on the next read. With an RS Shifter & Handbrake and an H-Shifter attached -at the same time, the attribute names the Shifter & Handbrake. Showing both -is tracked in [#144](../../issues/144). +**The Logitech Racing Adapter works on the base, and the Test page reads +two more devices on USB.** The driver finds a Racing Adapter plugged into an +accessory port, confirms it by its device name, and turns on the base's +routing for it in desktop mode, as it does for the H-Shifter. Its pedals and +its DB9 Driving Force Shifter then reach games through the base. The Info / +Testing page in logi-wheel also reads an RS Shifter & Handbrake and a Racing +Adapter plugged straight into the computer: handbrake lever and shift +direction for the one, three pedals and the 6+R shifter for the other. +Written and tested on real hardware by gonzaloadrio +([#139](../../pull/139)). + +**`wheel_accessory` now lists every attached accessory.** A read of the +attribute re-checks the accessory ports, so an accessory plugged in after +boot shows up on the next read. With more than one attached, the attribute +names them all, separated by commas, for example +`RS Shifter & Handbrake, RS H-Shifter, Racing Adapter`. Closes +[#144](../../issues/144). **Module load did not get slower.** The H-Shifter probe runs inside the one accessory pass that already existed, so a wheel without accessories pays @@ -34,7 +47,8 @@ USB port can fail the USB link before any driver runs. The kernel log shows `disabled by hub (EMI?)` or `error -71`. A rear port fixes it ([#141](../../issues/141)). -Thanks to gonzaloadrio for the shifter work and the hot-plug test runs, to +Thanks to gonzaloadrio for the shifter and adapter work and the hot-plug +test runs, to kangaro0 for the first power-up report that found the port problem, and to fenixadam for the Windows captures in [#134](../../issues/134) and [#135](../../issues/135). diff --git a/README.md b/README.md index 21b8ad9..03481f2 100644 --- a/README.md +++ b/README.md @@ -200,6 +200,7 @@ to work ยท ๐ŸŸก needs a tester ยท `-` not applicable. | Pedal response curves, sensitivity, deadzones, combined pedals | โœ… | ๐ŸŸข | | RS Shifter & Handbrake (shift, digital + analog handbrake) | โœ… | ๐ŸŸข | | RS H-Shifter (7 gates + reverse, works on the desktop, hot-plug) | โœ… | ๐ŸŸข | +| Racing Adapter on the base (legacy pedal sets + DB9 shifter, hot-plug) | โœ… | ๐ŸŸข | | LIGHTSYNC RGB LEDs (slots, colors, direction; edits apply live) | โœ… (faceplate strip, see note) | ๐ŸŸก (rev lights) | | RPM rev-light display (level fill; drawn center-out by default - the strip's pattern comes from the wheel's stored display config, separate from the level itself) | โœ… | ๐ŸŸก | | Native texture merge + telemetry rev lights in AC EVO (relay triple -> logi-rpm-bridge -> wheel) | โœ… | ๐ŸŸข | @@ -661,11 +662,20 @@ handbrake curve is live while the two trigger points are not. ![logi-wheel-gui RS Shifter and Handbrake settings](docs/images/logi-wheel-accessory.png) The **RS H-Shifter** works the same way. Plug it into an accessory port on -the base, and its seven gates and reverse appear as buttons 12 to 19. The -driver also turns on the base's routing for it in desktop mode, so the gates -work outside a game. The Info / Testing page shows which gate is in. Plug -the shifter straight into the computer by USB instead, and the page reads it -there too, with the mode shown next to the gate. +the base, and its seven gates and reverse appear as buttons 12 to 20 (button +19 is not used). The driver also turns on the base's routing for it in +desktop mode, so the gates work outside a game. The Info / Testing page +shows which gate is in. Plug the shifter straight into the computer by USB +instead, and the page reads it there too, with the mode shown next to the +gate. + +The **Logitech Racing Adapter** is recognised on the base as well. It takes +a G29, G920 or G923 pedal set and a DB9 Driving Force Shifter. The driver +turns on the base's routing for the adapter in desktop mode, like the +H-Shifter. The Info / Testing page also reads the adapter and the RS Shifter +& Handbrake on their own USB cables: the three pedals and the 6+R shifter +on the adapter, the handbrake lever and the shift direction on the Shifter +& Handbrake. The Info / Testing page doubles as a live input tester (does this button reach the computer?). The Setup page manages the game helpers: diff --git a/docs/FEATURE_MATRIX.md b/docs/FEATURE_MATRIX.md index 55e8e4f..9410ffe 100644 --- a/docs/FEATURE_MATRIX.md +++ b/docs/FEATURE_MATRIX.md @@ -17,8 +17,9 @@ HID++ features (base): 8040=0A 807A=0B 807B=0C 80A4=0D 80D0=0E ... **These are BASE-DEVICE answers.** HID++ sub-devices answer separately. The RS Shifter & Handbrake reports at device index `0x04`. The RS -H-Shifter (`0x812D RS_H_SHIFTER`) reports at the index of the port it is -plugged into. Their features error out here instead of reporting +H-Shifter (`0x812D RS_H_SHIFTER`) and the Racing Adapter (`0x8120 +GAMING_ATTACHMENTS`) report at the index of the port they are plugged into. +Their features error out here instead of reporting themselves. `0x80B1 BANDED_AXIS` and `0x812C WHEEL_CENTER_POSITION` show as absent on the RS50 below, and the driver demonstrably uses both. Absence in this table means "not on the base device". It does not mean diff --git a/mainline/hid-logitech-hidpp.c b/mainline/hid-logitech-hidpp.c index a968455..4fe5e97 100644 --- a/mainline/hid-logitech-hidpp.c +++ b/mainline/hid-logitech-hidpp.c @@ -15141,18 +15141,16 @@ static ssize_t wheel_firmware_show(struct device *dev, static DEVICE_ATTR(wheel_firmware, 0444, wheel_firmware_show, NULL); /* - * wheel_accessory: presence signal for the RS Shifter & Handbrake, an - * optional accessory attached to the base's USB-A port (Phase 1: discovery - * only, see hidpp_dd_discover_settings_features). Reports its 0x0005 name - * when found, or "none" - deliberately not -EOPNOTSUPP, so apps get a - * clean yes/no instead of having to infer presence from every dependent - * attribute's error code. The accessory's three G HUB settings (shift - * sensitivity, handbrake actuation, handbrake sensitivity) are not wired - * up yet: their wire protocol is uncaptured. + * wheel_accessory: presence signal for the base's optional accessories, the + * RS Shifter & Handbrake, the RS H-Shifter and the Racing Adapter, which + * attach to the base's USB-A ports. Lists the attached ones by name (the + * Shifter & Handbrake by its 0x0005 name), comma-separated, or "none" - + * deliberately not -EOPNOTSUPP, so apps get a clean yes/no instead of + * having to infer presence from every dependent attribute's error code. */ /* - * Re-check which accessories are attached: the RS Shifter & Handbrake and - * the RS H-Shifter. + * Re-check which accessories are attached: the RS Shifter & Handbrake, the + * RS H-Shifter and the Racing Adapter. * * Discovery runs once at probe, but an accessory plugs into the base's own * USB-A ports, so it can arrive or leave while the driver is loaded and the