testsAndMisc/docs/superpowers/contracts/g29-shifter-hid-bpf-2026-09-14.json
Krzysztof kuhy Rudnicki 7e2d78c7db Add the G29 shifter HID-BPF fix (1st/3rd engage reliably)
Live on this host since 2026-09-11 but never committed. The wheel firmware
decodes the shifter's hall sensor itself and this unit's top row rests at
Y 180-193, below the ~195 engage threshold, so 1st/3rd often did not
register. g29_shifter.bpf.c re-decodes those two gates from the raw X/Y
bytes with hysteresis (engage >= 160, release <= 140) and ORs the bit in
before hid-logitech parses the report; it never clears a bit, so the
firmware's working gates cannot regress. fix_g29_shifter.sh builds,
attaches and installs it persistently (udev-hid-bpf rule + a systemd
safety-net unit pulled in on every re-enumeration); g29_shifter_capture.py
records and grades raw captures per gate.

Two files were over the 250-line cap: the test file is split at the
record/CLI boundary with the report builders moved into a conftest fixture
(the naming hook allows only test_*.py in tests/), and the grader's
docstrings are tightened. No behaviour change to the installed fix.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SS8M5wk88nJTXxDWz61KKk
2026-09-14 22:12:31 +02:00

16 lines
1.5 KiB
JSON

{
"title": "G29 Driving Force Shifter: 1st/3rd engage reliably via HID-BPF",
"objective": "The shifter's top row (1st/3rd) rests at hall Y 180-193 on this unit, below the firmware's ~195 engage threshold, so those gears often did not register. A HID-BPF device_event program re-decodes 1st/3rd from the raw X/Y bytes with hysteresis (engage >= 160, release <= 140) and ORs the bit into the button byte before hid-logitech parses it. It never clears a bit, so the firmware's own decode cannot regress. Persistent across boot and hotplug via udev-hid-bpf install, a systemd safety-net unit and an ensure rule. Live on the host since 2026-09-11; this commit puts it under version control.",
"acceptance_criteria": [
"fix_g29_shifter.sh builds g29_shifter.bpf.c against the udev-hid-bpf headers and --status reports device, persistence, attachment and the safety net",
"g29_shifter_capture.py records raw hidraw reports and grades a capture per gate (attempts, misses); exit 1 on any miss",
"test_g29_shifter_capture.py + test_g29_shifter_capture_cli.py pass (29) with g29_shifter_capture.py at 100% branch coverage",
"every file is under the 250-line cap"
],
"out_of_scope": [
"5th gear (no capture data for the top-right gate; left to the firmware)",
"force feedback (separate: DOCS-g29-ffb.md, install_new_lg4ff.sh)"
],
"verifier": "python3 -m pytest -q linux_configuration/tests/test_g29_shifter_capture.py linux_configuration/tests/test_g29_shifter_capture_cli.py; linux_configuration/fixes/fix_g29_shifter.sh --status"
}