Skip to content

Device report and opt-in experimental product ID for untested decks - #2

Merged
ValentinTorassa merged 2 commits into
mainfrom
feat/device-probe
Oct 26, 2026
Merged

ValentinTorassa merged 2 commits into
mainfrom
feat/device-probe

Conversation

@ValentinTorassa

Copy link
Copy Markdown
Owner

Groundwork for evaluating the SS551 (0200:2000) and other vendor-0200 decks. It does not add support for any new device.

What

  • ragnaros diagnose [--device VID:PID]: prints a Markdown report for every vendor-0200 device plugged in, ready to paste into an issue. It covers the IDs and strings, interfaces and endpoints (type, max packet, interval), the HID report descriptors from sysfs (hex) with the length each interface declares, the hidraw and /dev/bus/usb nodes with their permissions, the udev rules and usbhid quirks that cover the device, the raw configuration descriptors, and the ragnaros, kernel, distro and libusb versions. Next steps for an untested deck go to stderr, so > report.md keeps only the report.
  • ragnarosd --experimental-pid 0x2000 (or RAGNAROS_EXPERIMENTAL_PID): after the SS552, the daemon also tries that product ID and drives it with the SS552 protocol. It is off by default. When it is on, the daemon prints EXPERIMENTAL at startup and on attach, ragnarosctl status shows the device, and every raw input report is logged. A deck with a single interface still gets claimed. Only vendor 0200 is accepted.
  • README: a new "Reporting a new device" section. To give the user temporary access to an untested deck, it uses a one-off sudo chown "$USER" /dev/bus/usb/BBB/DDD, which lasts until the deck is unplugged. The default udev rule is unchanged.

Why

For #1 we need the SS551's descriptors and a quick test with the SS552 protocol. With this, the reporter can do both without editing code.

Safety

  • diagnose only reads sysfs files and stats the /dev nodes. It never opens the device, so it needs no root and is safe while ragnarosd runs. A test checks that it only opens files read-only and never opens anything under /dev or the serial attribute.
  • The serial number is never read; the report only says whether the device has one. Hostname and user names are left out: an owner or group is named only when it is a system account, otherwise it shows as "you" or "another user". A test checks this.
  • Default behaviour is unchanged: with no flag and no env var, the daemon opens 0200:3001 only, with the same error message, the same interface claiming and the same status reply. Tests pin this.

How verified

  • Ran the same commands as CI on Python 3.13: pytest -q (242 passed), compileall, py_compile, bash -n. The changed test files also pass on Python 3.9.
  • New tests mock sysfs with a fake tree (the same approach as test_builtin_usbhid_is_detected) and libusb with a stub CDLL. Fixtures use the SS552's real configuration descriptors.
  • Ran ragnaros diagnose read-only against the SS552 on my machine while the daemon was running: it showed the IGNORE quirk, the 70-ragnaros rule, both interfaces bound to usbfs, and report descriptor lengths of 54 and 63.
  • Not tested on an SS551, because none is available.

Refs #1

ragnarosd --experimental-pid 0x2000 (or RAGNAROS_EXPERIMENTAL_PID) also
opens that product ID after the SS552 and drives it with the SS552
protocol, so an owner of a sibling deck can see whether image writes and
input work. Off by default; the daemon says EXPERIMENTAL at startup and
on attach, ragnarosctl status shows it, and every raw input report is
logged while it is on. A single-interface deck is still claimed.
For every vendor-0200 device (or --device VID:PID) it prints Markdown
with the IDs and strings, interfaces and endpoints, HID report
descriptors, hidraw and USB nodes with their permissions, the udev rules
and usbhid quirks that cover it, and the ragnaros, kernel and distro
versions. It only reads sysfs and /dev permissions, never opens the
device, and leaves out the serial number, hostname and user names. Next
steps for an untested deck go to stderr. README: Reporting a new device.
@ValentinTorassa
ValentinTorassa merged commit 28121c2 into main Oct 26, 2026
5 checks passed
@ValentinTorassa
ValentinTorassa deleted the feat/device-probe branch October 26, 2026 23:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant