diff_actions
Diffs captured USB packets by labelled action and infers the device protocol, showing byte roles, handshake, states, responses, and image streams for driver development.
Instructions
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/BMP/WEBP, 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"capture": "<capture>"
},
"name": "diff_actions"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| device | No | USB device address to analyse; default = bus address with the most host→device payloads | |
| labels | No | Marker-free mode: ';'-separated labels in click order, or a text file path (one label per line). Splits traffic at the largest pauses between host→device messages | |
| capture | Yes | Path to a usbmon or USBPcap pcap/pcapng file | |
| markers | No | Markers JSON path; default <capture>.actions.json. Ignored when labels is set |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |