Repository navigation
Architecture
The project is one repository. It builds a kernel driver plus a userspace
toolset. (Userspace means the normal programs that run outside the
kernel.) The sysfs attribute surface is the interface between the two.
(sysfs is the kernel's file tree under /sys. An attribute is one file in
it.) The kernel driver owns the wheel and exposes every setting as a
wheel_* file. The userspace apps are clients of those files. They also
use evdev for input and force feedback, and hidraw for the TrueForce
stream. (evdev is the kernel's input-device interface. hidraw is the
kernel's raw access to a USB HID device. TrueForce is Logitech's fine,
fast vibration layer on top of normal force feedback.)
games (native, Proton)
| |
evdev FF hidraw intf 2 (TrueForce SDK / logi-ffb virtual wheel)
| |
+------------------------v------------v--------------------------------+
| hid-logitech-dd (kernel driver) |
| evdev input + FF effect engine | HID++ settings | TF stream |
+-----------------+------------------+---------+----------+------------+
| |
/dev/input/event* /sys/.../wheel_* (sysfs)
| |
+----------+--------------+-----------------------------+
| | | |
logi-ffb logi-tf-sim logi-wheel (TUI) logi-wheel-gui
(uhid FF (telemetry -> +------------------------------------+
proxy) TF + rev LEDs) | logi-wheel-core |
| | (shared settings library) |
libtrueforce +------------------------------------+
(C, hidraw)
Source: mainline/hid-logitech-hidpp.c. It is built as the
hid-logitech-dd module (DKMS/akmod in the packages). It is a fork of
JacKeTUs/hid-logitech-hidpp.
It is scoped to the three direct-drive wheel PIDs (046d:c276,
046d:c272, 046d:c268) plus the G923 PIDs (046d:c266/c267/c26e).
(A PID is a USB product id. A direct-drive wheel's motor turns the rim
directly.) So it coexists with the in-tree Logitech driver, the one
shipped inside the kernel. No blanket blacklisting is needed.
The G923 rides along as a separate code path. mainline/dd-lg4ff.c is a
classic force-feedback engine ported from berarma's new-lg4ff. It drives
the PlayStation edition (c266/c267) with the classic sysfs names:
range/gain/autocenter/combine_pedals, plus a read-only
ffb_output that logi-tf-sim mirrors into the TrueForce stream. It
exposes the rev LEDs as LED class devices. The Xbox edition (c26e)
instead routes through the driver's HID++ 0x8123 force-feedback path.
(HID++ is Logitech's command protocol on top of USB HID.) User-facing
details: G923.
What it does:
- Input: standard HID input via interface 0 (steering, pedals, buttons, hat). The kernel HID core decodes it natively.
- Force feedback: the wheel firmware only understands raw constant forces on its dedicated interface-2 endpoint. So the driver emulates the complete Linux FF effect set on top of it: constant, ramp, periodic with all waveforms, and the four condition effects. It does this in a 1 kHz effect loop that reads the live wheel position. See Protocol Force Feedback.
-
Texture routing: vibration-class effects (rumble, fast periodics)
can stream on the wheel's TrueForce audio channel instead of modulating
the steering axis. This matches the Windows KF/TF split
(
wheel_texture_route). -
Texture merge: a telemetry-driven engine texture can be merged into
a game's own live TrueForce stream (
wheel_tf_merge). (Telemetry is the live data a game publishes about the car.) G HUB, Logitech's Windows software, performs the same merge on Windows for AC EVO. Thelogi-rpm-bridgehelper feeds the merge (wheel_texture_rpm) and the rev-light level (wheel_rev_level) from the game's own telemetry. -
Settings: every G HUB setting via HID++ on interface 1. They are
exposed as sysfs
wheel_*attributes plus Oversteer-compatible aliases. (Oversteer is the community wheel-settings app.) See the Sysfs API Reference. - TrueForce passthrough: interface 2's hidraw node is left open for userspace. This is how the SDK-under-Proton recipe and libtrueforce work. (The SDK is Logitech's TrueForce software library. Proton is Steam's layer for running Windows games.)
- Self-healing: a 20-second range poll detects external range changes (a live SDK session's 90° push) and auto-restores. Several safety checks gate it.
A Rust workspace (userspace/logi-wheel/) of five crates. (A crate is a
Rust package.)
| Crate | Builds | Role |
|---|---|---|
logi-wheel-core |
library | the setting registry, typed values, validation, the sysfs read/write layer, plus steam (Steam/Proton game discovery), evtest (live input monitoring), lightsync (composed per-slot LED model), response_view (the per-axis simple/advanced view toggles), and tfsim (daemon control) modules. Reusable without either frontend |
logi-wheel-tui |
logi-wheel |
the terminal UI (ratatui + crossterm) |
logi-wheel-gui |
logi-wheel-gui |
the desktop UI (Slint) |
logi-ffb |
logi-ffb |
the DirectInput force-feedback proxy; see logi-ffb |
logi-tf-sim |
logi-tf-sim |
the simulated-TrueForce daemon; see Simulated TrueForce Internals |
Both frontends are thin. The registry in logi-wheel-core describes each
setting (type, range, mode requirements, category, help text). The UIs
render that description. Adding a setting is mostly a core change.
The workspace crates share one version (workspace.package in
Cargo.toml). It follows the repository's release tag.
Development without a wheel: set LOGI_WHEEL_SYSFS_DIR=/path/to/dir. This
points the apps at a directory of plain wheel_* files. Both frontends
then run fully headless against it. (logi-tf-sim's rev-LED feeder honors
the same override.)
userspace/libtrueforce/ is a native C reimplementation of Logitech's
TrueForce SDK. It is LGPL-2.1-or-later, so apps may link it freely. It
talks to the wheel's interface-2 hidraw node directly. It mirrors the
Windows SDK's API surface. logi-tf-sim links it statically. See
libtrueforce.
| Surface | Who provides it | Who consumes it |
|---|---|---|
/dev/input/event* (input + FF) |
kernel driver | games, logi-ffb, the Test views |
/sys/.../wheel_* (settings) |
kernel driver | logi-wheel, logi-wheel-gui, Oversteer, scripts, logi-tf-sim (rev LEDs) |
| hidraw interface 2 (TrueForce) | kernel driver (passthrough) | the SDK DLLs under Proton, libtrueforce |
/dev/uhid |
kernel | logi-ffb (creates the virtual wheel) |
| UDP telemetry | games | logi-tf-sim |
(/dev/uhid is the kernel interface for a virtual input device. UDP is
the network packet format the games broadcast on.)
Everything the driver does was reverse-engineered from USB captures of G HUB on Windows. It was then verified against live hardware. The write-ups:
- Protocol Specification: device identification, interfaces, input reports, HID++.
- Protocol Force Feedback: the constant-force stream and effect engine.
- Protocol LIGHTSYNC: the LED feature pair.
- TrueForce Protocol: the audio-haptic stream.