Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/emirmrkaljevic/usb-rea with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/emirmrkaljevic/usb-rea'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/emirmrkaljevic--usb-rea/badge.svg)](/listings/emirmrkaljevic--usb-rea)

HTML

<a href="/listings/emirmrkaljevic--usb-rea"><img src="/api/listings/emirmrkaljevic--usb-rea/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 80 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # usb-rea
  2. <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><sub>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.</sub></p>
  3. <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>
  4. <!-- mcp-name: io.github.emirmrkaljevic/usb-rea -->
  5. [![ci](https://github.com/emirmrkaljevic/usb-rea/actions/workflows/ci.yml/badge.svg)](https://github.com/emirmrkaljevic/usb-rea/actions/workflows/ci.yml) ![license](https://img.shields.io/badge/license-MIT-blue) [![usb-rea MCP server](https://glama.ai/mcp/servers/emirmrkaljevic/usb-rea/badges/score.svg)](https://glama.ai/mcp/servers/emirmrkaljevic/usb-rea)
  6. 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.
  7. ![usb-rea demo: capture labelled clicks, get the protocol and a working driver](docs/demo.gif)
  8. 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](docs/VALIDATION.md).
  9. ## Install
  10. ```sh
  11. pip install usb-rea
  12. ```
  13. On Arch Linux, use `pipx install usb-rea` instead; the [FAQ](docs/faq.md) has the packages for capture.
  14. ## Example
  15. ```sh
  16. usb-rea demo --device fan
  17. ```
  18. ```
  19. mode 100% 0x5a | counter (+1 per message) | 0x30 | lookup 1→0x11, 2→0x22, 3→0x47 | 0x00 | 0x00 | u16le crc16_modbus(bytes[0:6])
  20. fan 100% 0x5a | counter (+1 per message) | 0x10 | u16be round(value * 1 + 0) | 0x00 | u16le crc16_modbus(bytes[0:6])
  21. color 100% 0x5a | counter (+1 per message) | 0x20 | RGB bytes | u16le crc16_modbus(bytes[0:6])
  22. color only sent while mode 3: the driver sets it first
  23. ```
  24. 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.
  25. On a real device, label each click in the vendor app, then infer:
  26. ```sh
  27. sudo modprobe usbmon
  28. usb-rea capture start -o lamp.pcapng
  29. usb-rea mark -m lamp.pcapng.actions.json "brightness 0%" # then click it; 3+ values per setting
  30. usb-rea capture stop
  31. usb-rea report lamp.pcapng -o report.md
  32. usb-rea scaffold lamp.pcapng -o lamp_driver.py
  33. ```
  34. 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](docs/usage.md).
  35. 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](docs/known-devices.md).
  36. ## Limitations
  37. Status: alpha (v0.7.14, [on PyPI](https://pypi.org/project/usb-rea/)). 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.
  38. How this differs from Wireshark is in the [FAQ](docs/faq.md).
  39. 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.
  40. Have a Windows-only device? [Open a device request](https://github.com/emirmrkaljevic/usb-rea/discussions/1) with a capture and I will run it and publish the result.
  41. ## Docs
  42. - [Usage: capture, markers, inference and the generated driver](docs/usage.md)
  43. - [Capturing on Windows with USBPcap](docs/capture-windows.md)
  44. - [Capturing from a Windows VM on Linux](docs/capture-vm.md)
  45. - [MCP server](docs/mcp.md)
  46. - [How is this different from Wireshark?](docs/faq.md)
  47. - [Does this work on Arch Linux?](docs/faq.md)
  48. - [Known devices](docs/known-devices.md)
  49. - [Validation](docs/VALIDATION.md)
  50. - Case studies: [Corsair Hydro Platinum](docs/case-study-hydro-platinum.md), [ASUS TUF LC III LCD](docs/case-study-asus-tuf-lc3.md)
  51. MCP Registry name: `io.github.emirmrkaljevic/usb-rea`
  52. ## License
  53. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.