Architecture

Architecture

The project is one repository building a kernel driver plus a userspace toolset. The sysfs attribute surface is the interface between the two: the kernel driver owns the wheel and exposes every setting as a wheel_* file; the userspace apps are clients of those files (plus evdev for input and force feedback, and hidraw for the TrueForce stream).

                         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-dd (TUI)         logi-dd-gui
     (uhid FF   (telemetry ->    +---------------------------+
      proxy)     TF + rev LEDs)  |     logi-dd-core          |
                     |           | (shared settings library) |
               libtrueforce      +---------------------------+
               (C, hidraw)

The kernel driver: hid-logitech-dd

Source: mainline/hid-logitech-hidpp.c, built as the hid-logitech-dd module (DKMS/akmod in the packages). It is a fork of JacKeTUs/hid-logitech-hidpp, scoped to the three direct-drive wheel PIDs (046d:c276, 046d:c272, 046d:c268) so it coexists with the in-tree Logitech driver; no blacklisting is needed.

What it does:

• Input: standard HID input via interface 0 (steering, pedals, buttons, hat), decoded natively by the kernel HID core.
• 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) in a 500 Hz 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, matching the Windows KF/TF split (wheel_texture_route).
• Settings: every G HUB setting via HID++ on interface 1, exposed as sysfs wheel_* attributes plus Oversteer-compatible aliases. See the Sysfs API Reference.
• TrueForce passthrough: interface 2's hidraw node is left open for userspace, which is how the SDK-under-Proton recipe and libtrueforce work.
• Self-healing: a 20-second range poll detects external range changes (the SDK's session-init 90° push) and auto-restores, gated by several safety checks.

The userspace workspace: userspace/logi-dd

A Rust workspace (userspace/logi-dd/) of five crates:

Crate	Builds	Role
logi-dd-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), shaping (simple/advanced attribute split), and tfsim (daemon control) modules. Reusable without either frontend
logi-dd-tui	logi-dd	the terminal UI (ratatui + crossterm)
logi-dd-gui	logi-dd-gui	the desktop UI (Slint)
ffb-proxy	logi-ffb	the DirectInput force-feedback proxy; see logi-ffb
tf-sim	logi-tf-sim	the simulated-TrueForce daemon; see Simulated TrueForce Internals

Both frontends are thin: the registry in logi-dd-core describes each setting (type, range, mode requirements, category, help text), and the UIs render that description. Adding a setting is mostly a core change.

The workspace crates share one version (workspace.package in Cargo.toml) that follows the repository's release tag.

Development without a wheel: set LOGI_DD_SYSFS_DIR=/path/to/dir to point 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 (LGPL-2.1-or-later, so apps may link it freely). It talks to the wheel's interface-2 hidraw node directly and 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-dd, logi-dd-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

Protocol knowledge

Everything the driver does was reverse-engineered from USB captures of G HUB on Windows and 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.