Repository navigation
Sysfs API Reference
This page lists every setting the hid-logitech-dd driver exposes. The
driver exposes them as sysfs attributes. Sysfs is the kernel's settings file
tree. The attributes live under:
/sys/bus/hid/devices/<DEVICE_ID>/
<DEVICE_ID> is typically 0003:046D:C276.XXXX (RS50),
0003:046D:C272.XXXX (G Pro Xbox/PC or RS50 in compat mode), or
0003:046D:C268.XXXX (G Pro PS/PC). Compat mode is the RS50's G PRO
compatibility mode. To find your device path, run one of these:
find /sys/bus/hid/devices -name "*046D*C276*" # RS50 native
find /sys/bus/hid/devices -name "*046D*C27[28]*" # G Pro / compat
# or, path-stable across models:
H=$(ls -d /sys/class/hidraw/*/device/wheel_range | head -1 | xargs dirname)Most attributes are shared between the RS50 and G Pro. Per-model exceptions
are called out inline. The G923 does not have the wheel_* surface at
all. Its classic engine exposes five classic-name attributes instead. They
are in its own section below. The friendly way to
drive all of this is Configuring the Wheel. The wire-level encodings
live in the Protocol Specification.
The operating mode. RW means you can read and write the attribute. Desktop (profile 0): host software controls the settings. Sensitivity is available. Onboard (profiles 1-5): the settings are stored in wheel profiles. Brake force is available.
The active profile: 0 = desktop mode, 1-5 = onboard slots.
The names of the five onboard slots. The driver queries them live from the wheel:
cat wheel_profile_names
# 1: RACE
# 2: DRIFT
# 3: PROFILE 3
# ...
echo "3:RACE" > wheel_profile_names # rename slot 3The wheel stores the name in its own NVM (non-volatile memory, which
survives a power cycle). On an RS50 the name may be up to 9 characters.
It may contain spaces. The wheel stores it uppercased. The wheel itself
refuses a longer name, and the write fails with -EIO. A bad slot or an
empty name gives -EINVAL.
Steering rotation range. On the G PRO PID (compat mode included) the write only takes effect while the wheel is in desktop mode. PID is the USB product ID. To set the range there:
- Write
0towheel_profile. - Write the range to
wheel_range.
The driver re-reads the true range from the wheel every 20 seconds. The
re-read pauses while force feedback is actively playing. When the range has
changed externally, the driver does three things. It logs
rotation range changed externally in dmesg (the kernel log). It updates
the attribute to the real value. It notifies poll()ers via
sysfs_notify().
Automatic recovery from the launch-time 90° reset. Some games' SDK sessions push an operating range of 90° while their stream is live. (The SDK is Logitech's game-side library.) The push travels in a TrueForce interface-2 packet. TrueForce is Logitech's high-rate haptic channel. HID++, Logitech's configuration protocol over USB, never sees the push. The push decode reads the IEEE float at bytes 6-9. Pushes outside a running stream are firmware no-ops; see TrueForce Protocol. With this enabled, the driver restores the user's range automatically when a live session pushes one. Detection to restore takes under 100 ms once the poll samples the change.
Safety gates: the restore fires only for a silent external push that lands
exactly on 90. A game that applies its real steering lock is respected. The
restore works in desktop mode only. The wheel must be stationary. A restore
only ever widens the range. There are at most 3 restores per session. An
explicit wheel_range write supersedes any pending restore. 0 =
detect-and-report only.
Overall force-feedback strength. 100% corresponds to the wheel's maximum torque (8.0 Nm on the RS50).
Wheel damping (firmware-side resistance when turning).
TrueForce haptic intensity. 0 disables.
Brake pedal force threshold (load cell sensitivity). Returns -EPERM in
desktop mode.
Adjusts the steering response via feature 0x80A4. The value becomes a
64-point cubic Bezier curve (G HUB's Sensitivity slider). G HUB is
Logitech's Windows configuration app. Below 50 softens the response near
centre. Above 50 sharpens it. 50 reverts to the wheel's built-in curve.
Reads return the last value written (a write-through cache; the wheel has no
read-back for the slider). Writes in onboard mode fail with -EPERM.
Force-feedback smoothing level. G HUB's labels: Minimum (1), Low (7), Medium (11), Maximum (15). The driver clamps out-of-range values.
Automatic FFB filter adjustment. FFB is force feedback. The driver splits
the wire flag byte across the two attributes. wheel_ffb_filter stamps the
"user set this level" bit. This attribute toggles only the "auto mode" bit.
Whether the driver inverts the sign of every FF_CONSTANT level. Wine's
DirectInput-to-evdev translation and native evdev apps disagree on the sign
by one flip. (evdev is the Linux input event interface.) The driver cannot
tell them apart at runtime:
-
1(default): invert. Correct for Wine/Proton games. If centring forces push the wheel away from centre, the toggle is at the wrong setting. -
0: pass-through. Correct for native evdev apps followingDocumentation/input/ff.rst(fftest,ffcfstress, custom tools).
This only affects FF_CONSTANT. All other effect types feel identical
either way. Note: strong FFB when you drive in reverse is not a sign error.
It is the sim's physics coming through a direct-drive motor (verified
identical on Windows).
Synthetic damping applied to emulated FF_SPRING effects. The value is a
percentage of a FF_DAMPER that runs the spring's own coefficient. The
driver emulates condition effects host-side. Loop latency on a low-friction
direct-drive motor makes a stiff undamped game spring ring. It rings until
the wheel's over-torque failsafe cuts power (observed live with AC EVO's
map-load centring spring). Real wheels damp the spring inside the firmware
servo loop. This knob restores that behaviour. 0 disables.
Where the wheel actuates vibration-class effects (FF_RUMBLE and periodics
at 20 Hz or faster):
-
tf(default): streamed on the wheel's TrueForce audio-haptic channel. This is the same physical path the Windows SDK uses for texture. Steering-class effects stay on the force channel, so rumble does not modulate the steering axis. -
kf: legacy. Everything is summed into the single steering force. Kept as a fallback and for A/B comparison.
The driver brings up the TrueForce session lazily, on the first
texture-class playback (dmesg: TrueForce texture channel ready). If init
fails, texture falls back to the steering channel (degraded feel, never
lost). Texture amplitude respects FF_GAIN and wheel_strength. The driver
caps it at half of full scale, so a synthetic full-scale rumble cannot
hijack steering torque.
The kernel texture merge. It blends a telemetry-driven engine texture into
a game's own live TrueForce stream. It stamps the byte-11 sample marker so
the wheel renders it (see TrueForce Protocol). This is what gives
Assetto Corsa EVO its engine buzz. The game drives force through Logitech's
SDK but produces no texture itself on any platform. On Windows, G HUB's
stack synthesises the buzz from the game's telemetry and merges it into the
same stream. The driver performs that same merge, validated by feel on an
RS50. wheel_texture_rpm feeds it live RPM.
The live engine RPM that feeds the merged texture. logi-rpm-bridge
(started by logi-launch) normally writes it from the game's own telemetry.
0 means engine off, texture silent.
The cylinder count. The driver derives the firing rate of the merged engine texture from it. Treat it as a feel knob rather than a realism setting. A direct-drive motor's excursion falls as 1/f^2, so high counts put the fundamental above the feelable band.
Low-level centre calibration primitive. W means write-only. It writes a raw
16-bit encoder value, which the wheel adopts as the new centre (HID++
sub-device 0x05, page 0x812C). Use wheel_calibrate_here for the
common case.
One-shot "use the wheel's current physical position as the new centre". The driver performs the GET+SET internally, which mirrors G HUB's Calibrate button. The wheel's firmware persists the new centre across power cycles.
The RS50 has 10 RGB LEDs in a strip across the faceplate, with 5 custom
slots (0-4). These attributes exist on the RS50 in both native and compat
enumeration. On a real G PRO they are hidden. That rim has level-based
rev lights with no per-LED RGB. The driver exposes them as wheel_rev_level
instead.
Workflow:
- Select a slot.
- Set the direction.
- Set the colors.
- Apply.
echo 2 > wheel_led_slot
echo 1 > wheel_led_direction
echo "FF0000 FF0000 FF0000 FF0000 FF0000 FF0000 FF0000 FF0000 FF0000 FF0000" > wheel_led_colors
echo 1 > wheel_led_apply| Attribute | Access | Values | Notes |
|---|---|---|---|
wheel_led_slot |
RW | 0-4 | selects the active custom slot and renders it (on the wire a custom slot IS effect 5 + slot) |
wheel_led_slot_name |
RW | string, max 9 chars, stored in upper case | name of the selected slot, stored on the device |
wheel_led_slot_brightness |
RW | 0-100 | per-slot brightness |
wheel_led_direction |
RW | 0-3 | animation direction: 0 = L to R, 1 = R to L, 2 = inside out, 3 = outside in |
wheel_led_colors |
RW | 10 space-separated RRGGBB
|
LED1 is leftmost |
wheel_led_brightness |
RW | 0-100 | global brightness; changes made on the wheel's OLED are tracked and poll()able |
wheel_led_effect |
RW | 1-9 | 1-4 = built-in animations (inside-out, outside-in, R-to-L, L-to-R); 5-9 ARE the five custom slots. External effect changes are tracked |
wheel_led_apply |
W | 1 | re-applies the current slot configuration, uploading the colours and activating the slot |
The four built-in animations (1-4) play a colour pattern stored in the wheel's own firmware.
wheel_led_colorsdoes not apply to them. Nothing reports what they are showing, so you can see their colours but not read them back. Colours are yours only on the custom slots (5-9).If nothing lights at all, check the active onboard profile. A profile can keep the strip dark while every write here still succeeds.
Rev-light level: how many LEDs are lit. Available on the real G PRO rim AND
the RS50's strip. On the RS50 the fill renders the selected custom slot's
stored colors, drawn center-out by default (5 mirrored steps). The
logi-rpm-bridge helper (started by logi-launch) writes it from the
game's own telemetry. By default it writes LED 1 when the engine is on and
10 at the limiter. With LOGI_REV_MODE=shift it writes the car's dash
shift-light band instead. The strip darkens on telemetry loss. Writes return
immediately. The driver coalesces them and flushes only the newest level, at
a ~10 ms floor (G HUB itself writes about every 16 ms), so a fast telemetry
feeder always shows the latest value. The wheel reverts an unrefreshed level after a while. Feeders should
refresh at ~1 Hz or faster. Write wheel_led_effect to restore the normal
idle pattern.
Pedal response is a 64-point 0x80A4 curve applied on the wheel
base, at axes 1/2/3 for throttle/brake/clutch.
It is not applied on the pedal unit, even though the pedal unit has its own
0x80A4 store. That store accepts an upload and reports it back as loaded.
But it never applies the curve. So a curve written there does nothing, while
it reads back plausible values. Curves therefore go to the base, one axis
up. This was proven on an RS50 with a step curve. An applied step curve
makes it impossible to sweep the axis smoothly through the step. On the
pedal MCU (the pedal unit's microcontroller) the axis swept straight through
it. On base axis 1 the axis snapped to the plateau exactly.
Each pedal <p> in {throttle, brake, clutch} has three attributes.
They all write the single curve the axis holds, so the last write wins.
To combine a deadzone with a custom curve, author both as one _curve
upload. That is what the logi-wheel editor does.
The raw curve. Write reset for the built-in linear curve. Or write 2-64
whitespace-separated in:out pairs (0-65535, strictly increasing in,
non-decreasing out, from 0:0 to 65535:65535). The driver resamples
fewer than 64 pairs. A read returns "<loaded>/<max> points loaded" from
the wheel. That is the honest motion-free check.
echo "0:0 19660:0 65535:65535" > wheel_throttle_curve # dead until 30%
echo reset > wheel_throttle_curveG HUB's simple slider. It generates the same symmetric-Bezier curve that G HUB uploads. A read returns the last written value.
Dead travel at each end. lower + upper must be at most 99. "0 0"
reverts to the built-in curve.
The steering axis's 64-point curve, in the same format as the pedal curves.
It is the store behind G HUB's Sensitivity slider. wheel_sensitivity and
this attribute write the same axis-0 curve, so the last one wins. Note the
wheel sends no reports while held still. So an upload appears to do nothing
until the wheel moves. cat reads the loaded point count back.
Which accessories are plugged into the wheel base: the RS Shifter &
Handbrake, the RS H-Shifter and the Logitech Racing Adapter. The attribute
lists the attached ones by name, separated by commas, in that order. It
reads none when no accessory is attached. It never returns an error. A
read also queues a re-check, so an accessory plugged in later shows up on
the next read.
Which of its three jobs the RS Shifter & Handbrake is currently doing. RO
means read-only. The driver reads it from the accessory's 0x1B30 feature:
shifter, digital-handbrake or analog-handbrake. Without the accessory,
a read returns EOPNOTSUPP.
The apps use it to grey out settings that belong to a different mode. The settings themselves stay writable in any mode. Their values survive a mode change, so you can set one up before you flip the switch.
The RS Shifter & Handbrake's two trigger points, 1-100 (G HUB refuses
0). Without the accessory attached, they return EOPNOTSUPP.
-
wheel_shift_actuation- how far you must push the shifter before a shift registers. G HUB calls it "Shift Sensitivity". It is a trigger point rather than a response curve, hence the name. -
wheel_handbrake_actuation- how far you must pull the handbrake before the digital handbrake button fires (digital-handbrake mode only).
echo 30 > wheel_shift_actuation
echo 70 > wheel_handbrake_actuationG HUB's own handbrake value overflows above about 69%. It wraps to a point shorter than 50%. This driver writes the true value instead, so it stays monotonic across the full range. Above ~69% the two will not match.
The same curve controls for the RS Shifter & Handbrake's analog axis (base axis 4,
evdev ABS_Z). The handbrake input itself needs no configuration.
G HUB's "combined pedals". It merges throttle and brake into a single centred axis for legacy games (released = centre, one pedal up, the other down). The brake's own axis goes silent.
The base's small display is the wheel's Dynamic OLED, feature 0x8130.
Both attributes read unsupported on the G923.
| Attribute | Access | Values | Notes |
|---|---|---|---|
wheel_oled |
RW |
<layout>|<field>|... or off
|
puts a frame on the screen, or hands it back to the wheel's own menu. The layout is a letter A to J; the fields follow in write order. Text wider than its field is refused (EMSGSIZE) rather than cut; number fields take 0 to 255 |
wheel_oled_layouts |
RO | one line per layout | index, letter, field kinds in write order, then the text widths |
echo 'G|3|142' > wheel_oled # a big 3 with 142 beside it
echo 'J|Lap 12|1:42.7|Best|1:41.9' > wheel_oled # four centred rows
echo 'C|191' > wheel_oled # a gauge three quarters full
echo off > wheel_oledThe panel does not hold a frame on its own. So the driver resends the
current frame every 50 ms for as long as it is up. A read returns the last
write, or off. Two of the renderer's rules are worth knowing. First, a
value on a wide large row (H's lower row, I's large rows) draws its first
character pinned left and the rest right-aligned. So 112% shows as 1
and 12% with a gap. A leading space gives a clean right-aligned value
instead. Second, layout E's fields are written in a different order than
they are drawn. The full layout table, and the protocol, are in the
repository's docs/SYSFS_API.md and docs/PROTOCOL_SPECIFICATION.md
section 12.3. Both apps have an editor with presets, so nobody has to
write these frames by hand. See Configuring the Wheel.
The wheel's 12-character serial. The driver reads it from HID++ DeviceInfo
at init. It matches the USB iSerial.
Firmware versions read at init: the base's active main firmware and the motor unit's servo firmware. Include this in bug reports.
base: U1 65.03.B0038
motor: SC 02.01.B0042
The driver creates these for every wheel it binds. They use the de-facto new-lg4ff attribute names and scales (raw device units, not percent). So Oversteer and similar tools work unmodified:
| Attribute | Values | Notes |
|---|---|---|
range |
90-2700 | same as wheel_range
|
gain |
0-65535 | same setting as wheel_strength, raw FF_GAIN scale; the two stay in sync |
autocenter |
0-65535 | a real driver-emulated centring spring (also reachable via evdev FF_AUTOCENTER); games that write 0 before taking over FFB correctly disable it |
spring_level / damper_level / friction_level
|
0-100, default 100 | global output scales for the emulated effect classes; damper_level scales game DAMPER effects, the wheel's own firmware damping is wheel_damping
|
A different force-feedback engine (ported from new-lg4ff) drives the G923
(PlayStation edition, 046d:c266/c267). So it gets the classic attribute
names on its HID device directory instead of the wheel_* surface. None of
the attributes above exist on it. Oversteer and similar tools work
unmodified.
| Attribute | Access | Values | Notes |
|---|---|---|---|
range |
RW | 40-900 | steering rotation range in degrees |
gain |
RW | 0-65535 | master force-feedback gain |
autocenter |
RW | 0-65535 | centring spring strength (also reachable via evdev FF_AUTOCENTER); 0 disables |
combine_pedals |
RW | 0-2 |
0 separate (default), 1 gas + brake on one centred axis, 2 gas + clutch; the driver rewrites the input report, released = centre |
ffb_output |
RO | -32768 to 32767 | the engine's live net force (post-gain), 0 when idle; polled by logi-tf-sim to mirror force feedback into the TrueForce stream |
The rev LEDs are not sysfs attributes here. They are standard LED class
devices: five on/off entries under /sys/class/leds/ named <device>::RPM1
to ::RPM5. There is one per mirrored pair of the 10-LED strip (RPM1 is
the outermost pair). logi-tf-sim writes them directly to run the rev
display from a game's telemetry.
gain and autocenter keep their raw scale in sysfs. logi-wheel and
logi-wheel-gui present them as percentages in their own UI only, so
Oversteer and anything scripting these files are unaffected.
The Xbox edition (046d:c26e) uses the HID++ force-feedback path instead
and exposes none of these. More on both editions: G923.
Raw HID++ command shell for protocol bring-up. It is only present when the
module is built with CONFIG_HID_LOGITECH_HIDPP_DEBUG (make DEBUG=1). To
use it:
- Write
feature fn [params...]in hex. - Read the last response.
| Error | Meaning |
|---|---|
-ENODEV |
device not found or driver not ready |
-EPERM |
operation not permitted in the current mode |
-EINVAL |
invalid value |
-ERANGE |
value out of range |
-EOPNOTSUPP |
feature not supported by this device/firmware |
-EIO |
communication error with the device (including wheel-refused values, like an over-length profile name) |
On 046d:c272 / 046d:c268 (real G PRO and RS50-in-compat), most settings
work via fallback feature paths: wheel_range, wheel_strength,
wheel_trueforce, wheel_damping, wheel_ffb_filter, wheel_profile and
wheel_calibrate. LIGHTSYNC works the same as native on an RS50 in compat.
The compat firmware surface does not support wheel_brake_force,
wheel_ffb_filter_auto and wheel_sensitivity. They return -EOPNOTSUPP
once their mode gating is satisfied. Configure those via the wheel's OLED
menu. Remember that compat mode boots in onboard mode. Write 0 to
wheel_profile first, so live host settings take effect.