Skip to content

Architecture

mescon edited this page Nov 14, 2026 · 8 revisions

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)

The kernel driver: hid-logitech-dd

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. The logi-rpm-bridge helper 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.

The userspace workspace: userspace/logi-wheel

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.)

The C library: libtrueforce

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.

Interfaces at a glance

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.)

Protocol knowledge

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:

Clone this wiki locally