Skip to content

Sysfs API Reference

mescon edited this page Nov 14, 2026 · 11 revisions

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.

Mode and profile

wheel_mode (RW: desktop / onboard)

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.

wheel_profile (RW: 0-5)

The active profile: 0 = desktop mode, 1-5 = onboard slots.

wheel_profile_names (RW)

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 3

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

Force feedback

wheel_range (RW: 90-2700 degrees)

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:

  1. Write 0 to wheel_profile.
  2. 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().

wheel_range_restore (RW: 0/1, default 1)

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.

wheel_strength (RW: 0-100 %)

Overall force-feedback strength. 100% corresponds to the wheel's maximum torque (8.0 Nm on the RS50).

wheel_damping (RW: 0-100 %)

Wheel damping (firmware-side resistance when turning).

wheel_trueforce (RW: 0-100 %)

TrueForce haptic intensity. 0 disables.

wheel_brake_force (RW: 0-100 %, onboard mode only)

Brake pedal force threshold (load cell sensitivity). Returns -EPERM in desktop mode.

wheel_sensitivity (RW: 0-100, writes desktop mode only)

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.

wheel_ffb_filter (RW: 1-15)

Force-feedback smoothing level. G HUB's labels: Minimum (1), Low (7), Medium (11), Maximum (15). The driver clamps out-of-range values.

wheel_ffb_filter_auto (RW: 0/1)

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.

wheel_ffb_constant_sign (RW: 0/1, default 1)

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 following Documentation/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).

wheel_spring_damping (RW: 0-100 %, default 25)

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.

wheel_texture_route (RW: tf / kf, default tf)

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.

wheel_tf_merge (RW: 0/1)

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.

wheel_texture_rpm (RW)

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.

wheel_texture_cylinders (RW: 1-16, default 4)

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.

wheel_calibrate (W: 0-65535)

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.

wheel_calibrate_here (W: any value)

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.

LIGHTSYNC LEDs

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:

  1. Select a slot.
  2. Set the direction.
  3. Set the colors.
  4. 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_colors does 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.

wheel_rev_level (RW: 0-10)

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.

Pedals and handbrake

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.

wheel_<p>_curve (RW)

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_curve

wheel_<p>_sensitivity (RW: 0-100, 50 = linear)

G HUB's simple slider. It generates the same symmetric-Bezier curve that G HUB uploads. A read returns the last written value.

wheel_<p>_deadzone (RW: "<lower> <upper>" percent)

Dead travel at each end. lower + upper must be at most 99. "0 0" reverts to the built-in curve.

wheel_response_curve (RW)

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.

wheel_accessory (RO)

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.

wheel_accessory_mode (RO)

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.

wheel_shift_actuation / wheel_handbrake_actuation (RW)

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_actuation

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

wheel_handbrake_curve / wheel_handbrake_sensitivity (RW)

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.

wheel_combined_pedals (RW: 0/1, desktop mode only)

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 screen (RS50 and G PRO)

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_oled

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

Identity

wheel_serial (RO)

The wheel's 12-character serial. The driver reads it from HID++ DeviceInfo at init. It matches the USB iSerial.

wheel_firmware (RO)

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

Oversteer compatibility aliases

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

G923 (classic engine)

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.

Debug

wheel_hidpp_debug (RW, root only, debug builds)

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:

  1. Write feature fn [params...] in hex.
  2. Read the last response.

Error codes

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)

Compat-mode notes (G PRO PID)

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.

Clone this wiki locally