io.github.emirmrkaljevic/usb-rea

Start a USB traffic capture into `out` (usbmon on Linux, USBPcap on Windows). Side effects: launches a background capture process that keeps writing until capture_stop. Needs elevated privileges on Linux (usbmon; typically root or a usbmon group). Does not touch the device itself. Pair every start with capture_stop; do not start a second capture while one is running. Prefer this over analysis tools when you still need live traffic.

Stop the running capture started by capture_start. Side effects: terminates the background capture process. The pcapng at the path given to capture_start is left on disk for report/diff_actions/scaffold_driver. Returns 'no capture running' if nothing was started (not an error). Call this before analysing.

Diff packets per labelled action and infer the protocol (JSON: byte roles + evidence frames). The JSON also has `background` (periodic polls set aside) and `responses`: device replies paired with the query they answer (command, background poll or GET_REPORT), with byte roles (const, echo of a query byte, value fitted to the labels, counter, checksum, or reading with its observed min/max) and query/reply frame numbers. A reading that 'seen' markers explain gets `name`, `scale` and `bias` (raw = value * scale + bias, `signed` for i8/i16) plus the observations in `observed`; a named mode has `table` (raw value -> word the app showed); `observations` lists every 'seen' value and which reply bytes it matched. Read-only analysis: does not write files or talk to hardware. Requires either markers from mark_action or `labels` for a finished capture with pauses between clicks. Prefer report when the human wants a Markdown evidence write-up; prefer scaffold_driver / wireshark_dissector when they want generated code.

Decode a HID report descriptor (and optionally one report payload). Read-only. When `source` is a capture path, finds GET_DESCRIPTOR type 0x22 transfers (replug the device while capturing if none are present). When `source` is hex, parses that descriptor directly (e.g. from /sys/class/hidraw/*/device/report_descriptor). Use this to understand report IDs/sizes before or alongside report/scaffold_driver; it does not infer vendor protocol fields from labelled actions.

Record that the human is about to click this action in the vendor app. Side effects: appends {label, start, end} to <capture>.actions.json (creates the file). Call while capture_start is running, immediately before each click; end times are closed when the next mark arrives. Use the same label stem with different values (brightness 0%, 50%, 100%) so inference can fit scales. For an already-finished Wireshark capture without markers, skip this and pass `labels` to report/diff_actions instead. A label starting with 'seen' ('seen rpm 1180', 'seen rpm 1180 temp 34') is an observation, not an action: what the vendor app displays right now. It does not end the current action and is never diffed; analysis uses it to name and scale the device's reply readings (rpm = raw, temp = (raw - 40) / 2). Mark it when the human reads a value off the screen. On/off states ('seen pump on', 'seen pump off, alarm on') name single status-flag bits; words ('seen mode silent', 'seen mode turbo, rpm 3900': the word last or before a comma) name a mode byte with a value -> word map; negative values ('seen temp -5') allow signed i8/i16 readings.

Send one packet to real USB hardware (destructive / irreversible on the device). Side effects: opens the device via libusb/pyusb and writes the packet. Refuses unless user_confirmed=true after the human approved this exact vid/pid/endpoint/hex_data (and setup_hex if any). Needs OS permission to open the device. Prefer scaffold_driver to generate a driver first; never set user_confirmed from an agent guess.

Generate a Markdown evidence report: every claim links to frame numbers in the capture. Includes a 'Device responses' section when the device answers queries (status polls, command ACKs, GET_REPORT), saying which reply bytes could not be explained, and an 'Observations' section for 'seen' markers (named readings and unmatched observations). Read-only: returns Markdown text (does not write a file). Same inputs as diff_actions. Use after capture_stop (or on an existing pcap). Choose this over diff_actions when the human should read the protocol; choose scaffold_driver when they need a pyusb driver.

Generate a standalone Python/pyusb driver source for the inferred protocol. One set_<command>() per command; when the device replies, also query_<name>() methods that send the command/poll (or GET_REPORT), read the reply and return it decoded as a dict (readings named by 'seen' markers come back scaled and modes as words, e.g. {'rpm': 1180, 'temp': 34, 'mode': 'turbo', 'ok': True}). Read-only analysis that returns driver source as text (does not write a file or open the device). Same capture/markers/labels inputs as report. Prefer wireshark_dissector when the goal is to keep decoding traffic in Wireshark; use replay_packet only after the human approved a specific packet from this driver.

Generate a Wireshark Lua dissector for the inferred protocol. Read-only: returns Lua source as text. Labels commands, decodes values/counters/lookups, and verifies checksums (usbrea.checksum_ok + expert warning). Load with `wireshark -X lua_script:<file>.lua capture.pcapng` or the same flag on tshark. Prefer scaffold_driver for a pyusb driver; prefer hid_descriptor to inspect HID report layouts.