usb-rea
Open-source MCP server and CLI that reverse engineers Windows-only USB gadgets (case LCDs, RGB controllers, mice). Capture USB traffic while using the vendor app, it infers the protocol and generates a Python Linux driver. pip install usb-rea. MIT.
문서
usb-rea
If you find this useful, you can support me by getting a SkinToScan pack, my other project. It's a one-time purchase that directly funds my open-source work.
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.

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
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
- Usage: capture, markers, inference and the generated driver
- Capturing on Windows with USBPcap
- Capturing from a Windows VM on Linux
- MCP server
- How is this different from Wireshark?
- Known devices
- Validation
- Case studies: Corsair Hydro Platinum, ASUS TUF LC III LCD
MCP Registry name: io.github.emirmrkaljevic/usb-rea
License
MIT