usb-rea: Reverse Engineer any USB gadget

<!-- mcp-name: io.github.emirmrkaljevic/usb-rea -->

<p align="center"><a href="https://skintoscan.com/#packages"><img src=".github/assets/skintoscan-support.svg" width="684" alt="Support my open-source work: get a SkinToScan pack"></a><br>_{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.}</p> <p align="center"><a href="https://skintoscan.com/checkout/?add-to-cart=138"><img src=".github/assets/skintoscan-pack-1.svg" width="220" alt="Buy Single Picture Check, €4.49"></a> <a href="https://skintoscan.com/checkout/?add-to-cart=139"><img src=".github/assets/skintoscan-pack-5.svg" width="220" alt="Buy 5 Picture Pack, €19.99 (popular)"></a> <a href="https://skintoscan.com/checkout/?add-to-cart=140"><img src=".github/assets/skintoscan-pack-15.svg" width="220" alt="Buy 15 Picture Pack, €54.99"></a></p>

Concrete result: from captures of the NZXT Kraken X (1e71:170e) fan command, usb-rea recovers 02 4d <channel> 00 <duty> byte for byte, exactly as liquidctl's kraken2.py sends it, and the generated driver emits identical packets for duty values it never saw. Same for the SteelSeries Rival 100 (1038:1702) DPI, polling and RGB tables from rivalcfg. Proof runs in CI: docs/VALIDATION.md. Full walk-through with a CRC8 and a rolling counter: Corsair Hydro Platinum case study.

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

Got a USB device that only ships a Windows vendor app (case LCD, RGB controller, mouse, "smart" lamp)? Click around in the vendor app while usb-rea captures the USB traffic (usbmon on Linux, USBPcap on Windows), diffs the packets per action, infers the protocol, and writes an open-source Python/libusb driver, with every conclusion linked to the exact packets that prove it.

Status: alpha (v0.7.10, on PyPI). Validated on synthetic devices, on protocols documented by liquidctl and rivalcfg, on public Wireshark captures (see docs/VALIDATION.md) and on a real AIO cooler LCD capture a user shared, where it found the same brightness command and image stream format the user had worked out by hand. Your captures are welcome.

Try it in 10 seconds (no hardware needed)

pip install usb-rea
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 | round(value * 1 + 0) | round(value[1] * 1 + 0) | round(value[2] * 1 + 0) | u16le crc16_modbus(bytes[0:6])
  color only sent while mode 3 (3x; other commands ran in mode 1, 2): the driver sets it first

handshake (3 messages sent once when the app opens the device):
  1. 5a 00 01 00 00 00 0d 1d -> a5 01 ?? ?? ?? ?? ??, sent again 2x later (session reopened)
  2. 5a 00 02 38 b4 e6 52 1e 1e -> a5 02 ?? ??, bytes 3-6 = token from step 1, sent again 2x later (session reopened)
     reply byte 2 = 01 (2x, most common): the steps below
     reply byte 2 = 02 (1x): 5a 00 04 01 00 00 5c 11 -> a5 04 01 ??, 5a 00 03 01 00 00 5d 65 -> a5 03 01 ??
  3. 5a 00 03 01 00 00 5d 65 -> a5 03 01 ??, sent again 1x later (session reopened)

device replies:
mode         6/6  0xa5 | = query byte 2 (0x30) | = query byte 1 | = query byte 3 | 0x00 | sum8(bytes[0:5])
fan          6/6  0xa5 | = query byte 2 (0x10) | = query byte 1 | u16le round(value * 1 + 0) | sum8(bytes[0:5])
color        6/6  0xa5 | = query byte 2 (0x20) | = query byte 1 | 0x00 | 0x00 | sum8(bytes[0:5])
poll 1       7/7  0xa5 | = query byte 2 (0x40) | u16le rpm = raw, seen 800..4011 | u8 temp = raw, seen 35..38 | mode: 0x11 = silent, 0x22 = balanced, 0x47 = turbo | sum8(bytes[0:6])

24 of 24 'seen' observations matched a reply byte (mode, rpm, temp)

It writes a synthetic capture of a fan controller (its vendor app first opens a session with a token the fan hands out, then polls the fan's status, and the markers note what the app's screen showed, seen rpm 1207 temp 37 mode silent), recovers the protocol and the replies, names the readings and the fan's mode, notices that the app only sets a color in mode 3, and writes report.md (every claim linked to Wireshark frame numbers) and a working pyusb driver that encodes values it never saw and decodes what the fan answers.

--device lamp (default) is a simple 8-bit device; --device lcd is a pump cap screen whose app streams a JPEG video while you change the brightness; --device dial shows 32-bit values and packed bitfields:

position     100%  0xa5 | 0x01 | u32le round(value * 1 + 0) | sum8(bytes[0:6])
level        100%  0xa5 | 0x02 | bits[0:4] = round(value * 1 + 0) | 0x00 | sum8(bytes[0:4])

What it can infer

| Role | Example | |---|---| | constant header / command id | 5a, 10 vs 20 vs 30 | | linear values, 8-, 16- or 32-bit LE/BE, several per action | fan 2650 → 0a 5a; color 255 24 0; position 50000 → 50 c3 00 00 | | packed bitfields (bits beside constant flag bits, incl. 12-bit spans over two bytes) | level 7 → b7 = flags b0 + bits[0:4] | | lookup tables (non-linear choices) | DPI 250→08, 500→07 … | | rolling counters | sequence byte +1 per message | | checksums | sum8, xor8, neg/inv sum8, sum16, CRC8, CRC8/MAXIM, CRC16 CCITT-FALSE/XMODEM/MODBUS/KERMIT | | device replies: echoed query bytes, values fitted to labels, readings | status poll → a5 40 2a 07 26 00 3c = RPM u16le reading, temperature u8 reading, sum8 | | named readings, from what the vendor app shows (seen rpm 1180) | bytes 2-3 u16le rpm = raw, byte 4 temp = (raw - 40) / 2 | | on/off status flags (seen pump on, seen pump off) | byte 5 bit 0: pump (1 = on) | | modes / enum values (seen mode silent, seen mode turbo) | byte 5 mode: 0x00 = silent, 0x02 = turbo, or bits[4:6] profile: … beside flags | | signed readings, when the app shows negative values (seen temp -5) | byte 4 i8 temp = raw, bytes 2-3 i16be … | | handshake: messages sent once when the app opens the device, session tokens | step 2 bytes 3-6 = bytes 2-5 of the reply to step 1 | | image streams to a screen, kept apart from the commands | JPEG on EP 0x03, header 08 nn 00 80 then 08 ii 00 00, ack 08 81 per frame | | raw pixel streams (RGB565/RGB888), found by size and by the region the draw command names | 320x480 RGB565 LE after rr rr rr rr rr c5 (Turing Smart Screen rev A) |

Linear fits must survive leave-one-out cross-checks; otherwise usb-rea falls back to an honest lookup table and says so.

Real device workflow (Linux)

sudo modprobe usbmon
usb-rea capture start -o lamp.pcapng
usb-rea mark -m lamp.pcapng.actions.json "brightness 0%"    # then click it in the vendor app
usb-rea mark -m lamp.pcapng.actions.json "brightness 50%"   # ...repeat for 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
usb-rea dissector lamp.pcapng -o lamp.lua      # Wireshark dissector for the same protocol

Captured on Windows with USBPcap/Wireshark and no markers? Click each action with a short pause in between, then just list them in order, and usb-rea splits the traffic at the pauses:

usb-rea report lamp.pcapng --labels "brightness 0%; brightness 50%; brightness 100%; power off; power on"
usb-rea scaffold lamp.pcapng --labels labels.txt -o lamp_driver.py   # one label per line

(Markers, if you have them, are a JSON list of {"label", "start", "end"} epoch timestamps.)

Most vendor apps also poll the device on their own (a "get status" every few hundred ms, keep-alives). usb-rea spots identical host→device messages sent on a steady rhythm, away from your clicks, and sets them aside before splitting and diffing; the report lists them under Background traffic (ignored) with their period and frame numbers. A constant "apply" packet that always follows a real command is not treated as background. Polls that carry a sequence number are caught too: same-shape messages that differ only in a byte counting up by one (plus a trailing checksum that changes with it) show up as e.g. aa 10 ?? 00 ??. Those need at least 8 copies, so a user stepping a value by one is not mistaken for a poll.

Device responses

Devices answer too: an ACK after each command, a status reply to every poll (RPM, temperature, firmware version), or the data of a GET_REPORT. usb-rea pairs each query with the IN transfer that follows it (by endpoint and typical delay, so a poll sent in the middle of a click doesn't steal the click's reply) and decodes the replies with the same machinery: constants, bytes that echo the query (command id, sequence number), counters, checksums, and values fitted to your labels (fan 1200 → u16le in the reply). Anything else that varies is reported as a reading with its observed range, and the report says that its meaning is unknown. A 16-bit reading is only claimed when one byte order changes smoothly and the other jumps. The generated driver gets query_<name>() methods that send the query, read the reply and return a dict ({"reading_2": 1834, "checksum_ok": True, …}). Try it with usb-rea demo --device fan or on a capture with polls.

Naming readings: tell it what the vendor app shows

A reading is just bytes until you say what it is. While capturing, note what the vendor app displays now and then:

usb-rea mark -m fan.pcapng.actions.json "seen rpm 1180 temp 34"   # several name/value pairs are fine

A seen marker is an observation, not an action: it does not end the action in progress, is never diffed, and never becomes a command. Each observation is compared with the reply just before it (what the app was showing) or just after it, within 1 s. A reading takes the name when it equals every observation of that name (2+ observations, within one unit or 1%), or when a linear raw = value * scale + bias fits them exactly and survives the same leave-one-out check as commands (3+ observations with distinct values). Two neighbouring byte readings are also tried as one 16-bit LE/BE number, and four as one 32-bit LE/BE number (three are enough when the high byte is still 0x00), so energy counters and uptimes work: mark "seen energy 2.968" names bytes 1-4 u32be energy = raw / 1000. The report shows the formula with the frames and marker times behind it, and lists observations that matched nothing; the driver returns {"rpm": 1180, "temp": 34, "ok": True, …}.

On/off states work too: mark "seen pump on, alarm off" (also true/false, yes/no). A name seen both on and off becomes a status flag, the one bit of a reply byte that is 1 every time the app said on and 0 every time it said off; several flags can share a byte, and the driver returns {"pump": True, "alarm": False, …}. Two bits that always flip together are left unnamed, and bits of a flag byte that change but were never named are pointed out in the report.

Modes and other enum values are words: mark "seen mode silent", mark "seen profile gaming" (a word value goes last, or before a comma: `seen mode turb