Repository navigation
TrueForce Protocol
TrueForce is Logitech's high-frequency audio-haptic stream. It supplements traditional force feedback. Rather than low-rate force updates, the host sends a ~1000 Hz audio waveform to the wheel's DSP (digital signal processor). The DSP drives the motor with much higher fidelity. This page documents the wire protocol. The user recipe is in Force Feedback in Games. The native implementation is in libtrueforce.
The protocol runs entirely on USB interface 2 (endpoints 0x03 OUT /
0x83 IN). The kernel driver delegates that interface to hidraw (the
kernel's raw HID device node). No HID++ feature activation is required.
(HID++ is Logitech's configuration protocol over USB.) Userspace opens the
hidraw node and starts writing. Two userspace paths consume it:
- Proton sims (verified): Logitech's own signed SDK DLLs run unmodified inside Wine. (The SDK is Logitech's game-side library.) They reach the wheel through Wine's HID stack. This is verified end to end on ACC and AC EVO, in both the RS50's native and compat modes. The SDK drives either PID identically.
- Native Linux apps: libtrueforce reimplements the same protocol in C.
The RS50 and G Pro use byte-for-byte identical init and streaming packets. Treat TrueForce as a single protocol across the direct-drive family.
Usage Page: 0xFFFD (vendor-defined)
Usage: 0xFD01
Report ID: 0x01
Size: 63 bytes IN + 63 bytes OUT (64 with report ID)
byte[0]: 0x01 Report ID
byte[1-3]: 0x00 0x00 0x00 Padding
byte[4]: COMMAND_TYPE
byte[5]: SEQUENCE Rolling u8 counter (wraps), shared across all types
byte[6..]: PAYLOAD Type-specific
| Type | Purpose |
|---|---|
0x01 |
Audio data stream (dominant during gameplay) |
0x03 |
Start / play |
0x04 |
Stop / clear |
0x05 |
Parameter upload (48 floats, one per packet) |
0x06 |
Effect slot configuration (6 slots) |
0x07 |
Query / handshake |
0x09 |
Runtime parameter update |
0x0b |
Unknown (seen in AC EVO's init with float 1.0) |
0x0e |
Operating range, IEEE 754 LE float degrees |
G Hub sends a 68-packet init sequence. Then it sends the same 68 packets
a second time (the sequence counter restarts at 1 each pass). Only then
does the per-sample stream begin. A single pass is unreliable on cold boot.
The packets are stored verbatim in userspace/libtrueforce/src/tf_init_data.h:
| Packets | Type | Purpose |
|---|---|---|
| 1-48 | 0x05 |
48 parameters as IEEE 754 LE floats |
| 49 | 0x01 |
neutral sample (primes the stream) |
| 50 | 0x0e |
operating range = float 2700.0 (the wheel's max) |
| 51, 53, 55... | 0x01 |
neutral samples between the others |
| 52 | 0x07 |
handshake / query |
| 54-66 (even) | 0x06 |
effect slot configurations (slots 1-6) |
| 60 | 0x09 |
runtime parameter update |
| 67 | 0x04 |
stop / clear |
| 68 | 0x03 |
start / play |
Notably, the committed init replays every type-0x05 packet with a zero value payload (only the index byte varies). TrueForce still works end to end. So the specific float values G Hub sends (channel counts, filter coefficients, crossover frequencies) are not required for basic operation.
byte[6-7]: u16 LE Most-recent sample ("cur", the motor torque target)
byte[8-9]: u16 LE Duplicate of bytes 6-7
byte[10]: 0x04 Number of new samples in this packet (0 = none)
byte[11]: 0x0d Sample-present marker, paired with byte 10 (see below)
byte[12-15]: window[0] L, window[0] R (u16 LE each, mono duplicated)
...
byte[60-63]: window[12]
Layout invariants observed across captures:
- A 13-slot rolling window holds the most recent samples, oldest at
window[0]. Each packet advances the window by as many samples as byte 10 declares. That byte is a count, not a constant. G Hub sends 4 nearly always, and 5 in some captures. libtrueforce sends 4 in the steady state, fewer when a drain came up short, and up to 12 on a packet that makes up for a coalesced timer expiry. 13 is the ceiling the window can express. 8 and 12 are hardware-confirmed to render, by ear and on the wire against the 4-sample form. - Every sample is duplicated (L and R). The wheel is single-motor, so the stereo is ceremonial.
- Samples are u16 LE offset binary (centre
0x8000,0x0000= full left,0xFFFF= full right). - Bytes 10 and 11 are a demux pair. Samples ride byte 10 != 0 plus
byte 11 =
0x0d. A no-sample packet carries0x00/0x00. The combination byte 10 =0x04with byte 11 =0x00never occurs on the wire. The wheel silently discards that packet's samples. The byte-11 marker is a render gate, not decoration. - The preamble ("cur") is the motor torque target. 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. AC EVO carries its game force in cur and independent audio in the window of the same packet.
Packet cadence: libtrueforce streams 1000 Hz (4 kHz effective sample rate). The kernel driver's unified texture stream runs 1000 Hz (333 Hz before, see Protocol: Force Feedback). Games send anywhere from 250 to ~1000 packets/s (AC EVO at the top). The wheel accepts the whole range. Under input starvation the sender holds the window for a few ticks. Then it flushes the window toward centre while the held force unwinds. (Windows does something similar.) In the other direction, a producer faster than the wire does not stall. libtrueforce bounds the backlog by time (128 ms). It drops and counts the oldest samples. A deep buffer that fills and stays full puts about a second between what the car does and what the rim does.
The endpoint carries one packet per millisecond in total. So two programs
that stream to it do not share it. They take turns. The wheel then
alternates between their two torque targets every millisecond. The result
is a 500 Hz square wave on the motor, with each side's samples playing at
half rate. The measurements from an RS50 are in the repo's
docs/TRUEFORCE_PROTOCOL.md under "One writer at a time" (packets carrying
samples 49% vs 99%, gaps 2.000 ms vs 1.000 ms, the odd-harmonic signature
that identifies it by ear). The three rules an implementer needs are there
too.
In short: take the stream rather than join it. The Linux driver yields automatically when it sees a userspace writer on interface 2. It carries its own force in that writer's packets instead of sending its own (see Protocol Force Feedback). Two userspace programs must arbitrate between themselves. The ones shipped here do it with a per-wheel lease.
Type-0x0e carries the wheel's operating range as an IEEE 754 LE float in
degrees at bytes 6-9. This is logiWheelSetOperatingRange*() on the wire.
It is the root cause of the "wheel resets to 90° on game launch" bug. Some
games' SDK sessions push a 0x0e with 90.0 once the stream is running.
That flips the physical range with zero HID++ traffic. The kernel driver's
range poll detects a live session's push and auto-restores. The restore is
strike-capped (wheel_range_restore; see the Sysfs API Reference).
Firmware behaviors discovered live:
-
Stream-scoped: a 0x0e only takes effect between stream START (
0x03) and STOP (0x04). Pushes outside that window are no-ops, including the one baked into the init sequence above (packet 50 lands before the start packet). - Idle revert: if a session goes quiet (~a minute), the firmware reverts the session's range change on its own. It broadcasts the restored value over HID++. A running game keeps its session alive. That is why real launch-time resets persist.
A session killed before its teardown reaches the wheel (a game crash, a hard kill) leaves the firmware latched. The next SDK session opens successfully (SetForceMode is acknowledged) but never streams. Only a power cycle of the wheel base recovers it. The practical advice lives in Troubleshooting.
The wheel answers every outgoing packet with real-time feedback:
byte[6-7]: u16 LE Motor current or temperature (undecoded)
byte[8]: status byte (undecoded)
byte[9-10]: wheel position (LE16, matches the joystick axis)
byte[11-12]: wheel position, ~1 sample older
byte[13-16]: 32-bit device-side sample counter
libtrueforce consumes these while a stream is active. It exposes the latest
snapshot via its Linux-native logitf_get_stream_feedback() API. The kernel
driver ignores them.
Classic force packets share this endpoint. The byte 10 / byte 11 demux pair
distinguishes them (0x00/0x00 for a pure force packet, nonzero/0x0d
when samples are present). See Protocol Force Feedback. Playing a sine
on TrueForce while holding a constant-torque effect is verified to work.
The firmware demultiplexes by packet content, and the two coexist.
- The type-0x02 motor field, status byte and checksum-like byte 17 are undecoded. Correlating the motor field against commanded torque on a live wheel would pin it down.
- Why G Hub occasionally sends byte 10 =
0x05is unexplained. The field is a count, and the wheel honours counts either side of it. So the interesting part is what makes G Hub choose a fifth sample, not whether it may. - Whether the 48 init floats are game-specific or universal is unconfirmed. The same data produces working TrueForce across BeamNG and ACC.