Usb Rea

Reverse Engineer any USB gadget: capture vendor-app traffic, infer the protocol with evidence, generate an open Python/libusb driver. CLI + MCP server.

LLM Mart 0 views 16 listing impressions

usb-rea reads a USB capture (pcap or pcapng, from usbmon or USBPcap) and does the step after Wireshark: it infers the command and protocol structure from labelled actions, then writes a Markdown report and a standalone pyusb driver. I built it for gadgets that only ship a Windows vendor app, such as a case LCD, an RGB controller, a mouse or a "smart" lamp. No hardware is needed to try it.

usb-rea demo: capture labelled clicks, get the protocol and a working driver

From captures of the NZXT Kraken X (1e71:170e) fan command, it recovers 02 4d <channel> 00 <duty> byte for byte, as liquidctl's kraken2.py sends it, and the generated driver emits identical packets for duty values it never saw. The same holds for the SteelSeries Rival 100 DPI, polling and RGB tables from rivalcfg. Those checks run in CI; details are in validation.

Install

pip install usb-rea

On Arch Linux, use pipx install usb-rea instead; the FAQ has the packages for capture.

Example

usb-rea demo --device fan
mode         100%  0x5a | counter (+1 per message) | 0x30 | lookup 1→0x11, 2→0x22, 3→0x47 | 0x00 | 0x00 | u16le crc16_modbus(bytes[0:6])
fan          100%  0x5a | counter (+1 per message) | 0x10 | u16be round(value * 1 + 0) | 0x00 | u16le crc16_modbus(bytes[0:6])
color        100%  0x5a | counter (+1 per message) | 0x20 | RGB bytes | u16le crc16_modbus(bytes[0:6])
  color only sent while mode 3: the driver sets it first

It writes a synthetic capture of a fan controller, recovers the protocol and the replies, and writes report.md (every claim linked to Wireshark frame numbers) plus a working pyusb driver. --device lamp is a simpler 8-bit device; --device lcd is a pump cap screen; --device dial shows 32-bit values and packed bitfields.

On a real device, label each click in the vendor app, then infer:

sudo modprobe usbmon
usb-rea capture start -o lamp.pcapng
usb-rea mark -m lamp.pcapng.actions.json "brightness 0%"   # then click it; 3+ values per setting
usb-rea capture stop
usb-rea report lamp.pcapng -o report.md
usb-rea scaffold lamp.pcapng -o lamp_driver.py

Captured on Windows with USBPcap and no markers? List the actions in order and usb-rea splits the traffic at the pauses. The full CLI, including markers, replies, handshakes, image streams and HID, is in usage.

Before you capture, usb-rea lookup 1e71:170e (or the ID 1e71:170e form from lsusb) checks a VID:PID against devices whose protocol an open-source project already implements. The offline table is in known devices.

Limitations

Status: alpha (v0.7.14, on PyPI). It is validated on synthetic devices, on protocols documented by liquidctl and rivalcfg, on public Wireshark captures, and on a real AIO cooler LCD capture a user shared. Linear fits must survive leave-one-out cross-checks; otherwise usb-rea falls back to a lookup table and says so. A matching USB ID alone does not prove your unit speaks the same protocol.

How this differs from Wireshark is in the FAQ.

Reverse engineering for interoperability is permitted (EU Directive 2009/24/EC Art. 6, US DMCA §1201(f)). usb-rea only analyzes traffic of devices you own and never redistributes vendor code.

Have a Windows-only device? Open a device request with a capture and I will run it and publish the result.

Docs

From the project's README.

Related servers

Read and write RAGE Package Format archives

23 views

See how ChatGPT, Claude, Gemini and Perplexity read any website. Scored out of 100.

19 views

MCP server for Geargrafx PC Engine / TurboGrafx-16 emulator

19 views

Read-only on-chain intel for AI agents on Base: balances, tokens, gas, tx status. No API keys.

15 views