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.

Record that the human is about to click this action in the vendor app.

Side effects: appends {label, start, end} to .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.

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. handshake lists the messages sent once before the first action (request, reply, expect with ?? for token and checksum bytes, uses/tokens for reply bytes reused later as a session token, checksums, retries, reopens, and branches on a step whose reply byte decided what the app sent next). states lists commands the app only sent after a mode command chose one value (also on the command as requires: state, value, count, other values seen, evidence frames), and with source "reply" those it only sent while a named status reply byte showed one mode or flag value (reply, where, reply_frames, and setter: the command seen to make the reply show it). switches lists actions where the app sent a state command first (enter) and maybe again after (restore: "previous", a value or null); that command's packets are kept out of the action, which carries the same switch. streams lists continuous image streams to a screen (JPEG/PNG/GIF, or raw RGB565/RGB888 pixels found by size with raw true): endpoint, endpoints (every host->device endpoint the frame bytes go to, with endpoint_layout 'alternate' or 'blocks' when there are several) and header_endpoint (where the draw command goes, when not with the pixels), format, frame and packet counts, chunk size, per-packet header (nn packet count, ii index, 8 or 16 bit), image size, frame rate, the device's per-frame ack and for raw streams header_packet (the command before each frame, or at the start of its first packet when header_inline is true), region (x/y/width/height fields), byteorder, size_alternatives and channel_order ('rgb' or 'bgr', null = unknown; only settled by frames showing the usb-rea testcard picture, see channel_evidence); those packets are kept out of the commands.

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.

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, a 'Handshake' section for messages sent once before the first action (session setup, tokens), 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_() per command; when the device replies, also query_() 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}). When the capture has a handshake, Device() replays it in open() before any command and checks the fixed reply bytes. A command the app only sent in one mode first calls the mode setter (Device(auto_state=False) raises StateError instead). A capture with an image stream to a screen adds send_image(image), which takes JPEG bytes (or, for a raw stream, a Pillow image or RGB565/RGB888 bytes, optionally a region at x, y), chunks it behind the captured header and returns the device's ack.

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.

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.

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.