Building and Contributing

Building and Contributing

How to build every piece from source, run the tests, and contribute the things the project needs most: hardware reports and USB captures.

Building from source

The kernel driver

The supported path is DKMS via the setup script (details in Installation):

sudo ./tools/setup.sh        # DKMS build, udev rule, module load, health check
./tools/setup.sh doctor      # re-run the health check alone, as your user

For driver development, the module also builds directly from mainline/ with the usual kernel build (make against your running kernel's headers). The module is hid-logitech-dd, scoped to the three direct-drive PIDs so it coexists with the in-tree hid-logitech-hidpp. A debug build (make DEBUG=1, CONFIG_HID_LOGITECH_HIDPP_DEBUG) adds the wheel_hidpp_debug raw HID++ shell described in the Sysfs API Reference, invaluable for protocol bring-up.

The Rust workspace (logi-dd, logi-dd-gui, logi-ffb, logi-tf-sim)

cd userspace/logi-dd
cargo build --release
# binaries: target/release/{logi-dd,logi-dd-gui,logi-ffb,logi-tf-sim}

Toolchain floor: Rust 1.88 (edition 2021); the Slint GUI needs 1.92. On distributions whose packaged rustc is older (Debian stable, for one), install with rustup. The TUI needs no system libraries; the GUI additionally needs pkg-config and the fontconfig headers (libfontconfig-dev on Debian/Ubuntu, fontconfig-devel on Fedora, fontconfig on Arch).

The workspace crates share one version (workspace.package in Cargo.toml) that follows the repository's release tag; bump it as part of cutting a release.

libtrueforce

cd userspace/libtrueforce
make && sudo make install && sudo make udev-install

See libtrueforce for the API and the LGPL boundary.

Running tests

• Rust workspace: cargo test in userspace/logi-dd (registry and validation logic in logi-dd-core, parser and synth fixtures in tf-sim, proxy logic in ffb-proxy).
• Developing without a wheel: set LOGI_DD_SYSFS_DIR=/path/to/dir with a directory of plain wheel_* files; both frontends run fully headless against it.
• FFB sign matrix: tests/ff_matrix_test.c cross-checks each wheel_ffb_constant_sign toggle value against native evdev expectations on live hardware.
• libtrueforce: the programs under userspace/libtrueforce/tests/ (discover, kf, sine, ...) exercise each surface against a live wheel. They move a strong wheel; hold the rim.

Contributing

Contributions are welcome in three flavors:

Code

The driver is forked from JacKeTUs/hid-logitech-hidpp; changes that apply to other Logitech devices are worth contributing upstream too. Read Architecture first for the lay of the land, and the protocol pages before touching wire formats. One safety rule from the protocol work: use GET (read-only) functions when probing unknown HID++ features; never blindly SET uncharacterized features.

Hardware reports

Testing on hardware the project cannot reach moves the support matrix:

• a real G PRO: texture routing feel (wheel_texture_route tf vs kf) and the rev-light control (wheel_rev_level),
• a DirectInput sim with logi-ffb,
• a G923 under Proton with the TrueForce recipe (same TrueForce protocol, unconfirmed),
• any sim from the "expected" list in Force Feedback in Games.

Open an issue with your kernel version, distribution, relevant dmesg output, and wheel_firmware (see Troubleshooting for the full bug-report checklist).

USB captures

Everything in the protocol pages came from captures, and captures of wheel variants that are not yet fully supported are the most valuable contribution there is. Tooling in the repo:

• Linux side: tools/linux_game_capture.sh wraps a usbmon capture of a game session. usbmon plus Wireshark works fine by hand too.
• Windows side (G HUB behavior): dev/tools/windows_*.bat scripts drive USBPcap for specific scenarios: G HUB startup and init, slider sweeps, LIGHTSYNC edits, profile switches, compat-mode behavior, TrueForce gameplay. Each script names its scenario; run it, perform the named action, and attach the .pcapng.
• Live HID++ probing: the wheel_hidpp_debug attribute (debug builds) sends raw feature commands; hidpp-list-features --device-index N from cvuchener/hidpp enumerates a sub-device catalog over hidraw, useful for mapping a new wheel's features without a Windows round-trip.

When you contribute a capture, note the wheel model, firmware (wheel_firmware), mode (native/compat), and exactly what you did while it ran. Small, single-action captures (one slider sweep, one LED change) are far easier to decode than a whole session.

What a capture has settled, historically: the entire settings protocol, the force stream, the LIGHTSYNC pair, the TrueForce init and framing, the 90-degree launch reset root cause, and the pedal-curve mechanism. See the revision history in docs/PROTOCOL_SPECIFICATION.md in the repo for the full archaeology.

Releases and packaging

The three packages (logitech-trueforce-dkms, logi-dd, logi-dd-gui) ship on AUR, as Debian .debs on Releases, on COPR (Fedora akmod) and on OBS (openSUSE); see Installation. The packaging sources live under packaging/ in the repo.