usb-rea 0.2.1__py3-none-any.whl

usb_rea/__init__.py

@@ -0,0 +1,2 @@
+"""usb-rea: Reverse Engineer any USB gadget."""
+__version__ = "0.2.1"

usb_rea/actions.py

@@ -0,0 +1,73 @@
+"""Action markers: which transfers belong to which user action."""
+from __future__ import annotations
+import json
+import time
+from pathlib import Path
+
+from .model import Action, Transfer
+
+
+def load_markers(path: str | Path) -> list[dict]:
+    """Markers file: JSON list of {label, start, end?} (epoch seconds).
+
+    Missing `end` means "until the next marker starts" (or +infinity).
+    """
+    marks = json.loads(Path(path).read_text())
+    marks = sorted(marks, key=lambda m: m["start"])
+    for i, m in enumerate(marks):
+        if m.get("end") is None:
+            m["end"] = marks[i + 1]["start"] if i + 1 < len(marks) else float("inf")
+    return marks
+
+
+def append_marker(path: str | Path, label: str, ts: float | None = None) -> dict:
+    p = Path(path)
+    marks = json.loads(p.read_text()) if p.exists() else []
+    now = time.time() if ts is None else ts
+    if marks and marks[-1].get("end") is None:
+        marks[-1]["end"] = now
+    m = {"label": label, "start": now, "end": None}
+    marks.append(m)
+    p.write_text(json.dumps(marks, indent=1))
+    return m
+
+
+def assign(transfers: list[Transfer], marks: list[dict]) -> list[Action]:
+    acts = [Action(m["label"], m["start"], m["end"]) for m in marks]
+    for t in transfers:
+        for a in acts:
+            if a.start <= t.ts <= a.end:
+                a.transfers.append(t)
+                break
+    return acts
+
+
+def commands_of(action: Action) -> list[Transfer]:
+    """Host->device messages that carry data (the interesting part)."""
+    return [t for t in action.transfers if t.is_out and t.data]
+
+
+def segment_by_gaps(transfers: list[Transfer], labels: list[str]) -> list[dict]:
+    """Build markers without timestamps: split host->device traffic at the largest pauses.
+
+    For captures made in Wireshark/USBPcap where you simply clicked the actions in order with a
+    short pause between them. Returns markers usable by `assign`.
+    """
+    outs = sorted((t for t in transfers if t.is_out and t.data), key=lambda t: t.ts)
+    n = len(labels)
+    if n == 0 or len(outs) < n:
+        raise ValueError(f"{len(labels)} labels but only {len(outs)} host->device messages in the capture")
+    gaps = sorted(range(1, len(outs)), key=lambda i: outs[i].ts - outs[i - 1].ts, reverse=True)[:n - 1]
+    cuts = [0] + sorted(gaps) + [len(outs)]
+    marks = []
+    for label, a, b in zip(labels, cuts, cuts[1:]):
+        marks.append({"label": label, "start": outs[a].ts - 1e-6, "end": outs[b - 1].ts + 1e-6})
+    return marks
+
+
+def read_labels(spec: str) -> list[str]:
+    """Labels from a file (one per line) or a ';'-separated string."""
+    p = Path(spec)
+    if p.is_file():
+        return [l.strip() for l in p.read_text().splitlines() if l.strip() and not l.startswith("#")]
+    return [s.strip() for s in spec.split(";") if s.strip()]

usb_rea/capture.py

@@ -0,0 +1,38 @@
+"""Capture helpers: thin wrappers around dumpcap/tshark (Linux usbmon) and USBPcapCMD (Windows)."""
+from __future__ import annotations
+import os
+import shutil
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+PIDFILE = ".usb-rea-capture.pid"
+
+
+def capture_command(out: str, bus: int = 0) -> list[str]:
+    if sys.platform.startswith("win"):
+        exe = shutil.which("USBPcapCMD.exe") or r"C:\Program Files\USBPcap\USBPcapCMD.exe"
+        return [exe, "-d", rf"\\.\USBPcap{bus or 1}", "-o", out, "-A"]
+    tool = shutil.which("dumpcap") or shutil.which("tshark")
+    if not tool:
+        raise RuntimeError("need dumpcap or tshark (apt install tshark) and `sudo modprobe usbmon`")
+    return [tool, "-i", f"usbmon{bus}", "-w", out, "-q"]
+
+
+def start(out: str, bus: int = 0, workdir: str = ".") -> int:
+    proc = subprocess.Popen(capture_command(out, bus), stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    Path(workdir, PIDFILE).write_text(str(proc.pid))
+    return proc.pid
+
+
+def stop(workdir: str = ".") -> bool:
+    p = Path(workdir, PIDFILE)
+    if not p.exists():
+        return False
+    try:
+        os.kill(int(p.read_text()), signal.SIGINT)
+    except ProcessLookupError:
+        pass
+    p.unlink()
+    return True

usb_rea/checksums.py

@@ -0,0 +1,46 @@
+"""Checksum / CRC algorithms usb-rea can recognise. Self-contained: copied verbatim into generated drivers."""
+
+
+def _crc(data, width, poly, init, refin, refout, xorout):
+    top, mask = 1 << (width - 1), (1 << width) - 1
+    crc = init
+    for byte in data:
+        if refin:
+            byte = int("{:08b}".format(byte)[::-1], 2)
+        crc ^= byte << (width - 8)
+        for _ in range(8):
+            crc = ((crc << 1) ^ poly) & mask if crc & top else (crc << 1) & mask
+    if refout:
+        crc = int("{:0{w}b}".format(crc, w=width)[::-1], 2)
+    return crc ^ xorout
+
+
+def _xor(data):
+    x = 0
+    for c in data:
+        x ^= c
+    return x
+
+
+# name -> (width in bytes, function)
+CHECKSUMS = {
+    "sum8": (1, lambda b: sum(b) & 0xFF),
+    "xor8": (1, _xor),
+    "neg_sum8": (1, lambda b: (-sum(b)) & 0xFF),
+    "inv_sum8": (1, lambda b: (~sum(b)) & 0xFF),
+    "crc8": (1, lambda b: _crc(b, 8, 0x07, 0x00, False, False, 0x00)),
+    "crc8_maxim": (1, lambda b: _crc(b, 8, 0x31, 0x00, True, True, 0x00)),
+    "sum16": (2, lambda b: sum(b) & 0xFFFF),
+    "crc16_ccitt_false": (2, lambda b: _crc(b, 16, 0x1021, 0xFFFF, False, False, 0x0000)),
+    "crc16_xmodem": (2, lambda b: _crc(b, 16, 0x1021, 0x0000, False, False, 0x0000)),
+    "crc16_modbus": (2, lambda b: _crc(b, 16, 0x8005, 0xFFFF, True, True, 0x0000)),
+    "crc16_kermit": (2, lambda b: _crc(b, 16, 0x1021, 0x0000, True, True, 0x0000)),
+}
+
+
+def compute(algo, data):
+    return CHECKSUMS[algo][1](bytes(data))
+
+
+def width(algo):
+    return CHECKSUMS[algo][0]

usb_rea/cli.py

@@ -0,0 +1,180 @@
+"""usb-rea command line."""
+from __future__ import annotations
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def _int(s):
+    return int(s, 0)
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="usb-rea", description="Reverse Engineer any USB gadget")
+    p.add_argument("--version", action="version", version=__version__)
+    sub = p.add_subparsers(dest="cmd")
+
+    c = sub.add_parser("capture", help="start/stop a usbmon/USBPcap capture")
+    c.add_argument("op", choices=["start", "stop"])
+    c.add_argument("-o", "--out", default="capture.pcapng")
+    c.add_argument("--bus", type=int, default=0)
+
+    m = sub.add_parser("mark", help="mark the action you are about to do in the vendor app")
+    m.add_argument("label")
+    m.add_argument("-m", "--markers", default="capture.pcapng.actions.json")
+
+    for name, hlp in (("transfers", "list parsed transfers"), ("infer", "infer protocol (JSON)"),
+                      ("report", "write evidence report (markdown)"), ("scaffold", "write pyusb driver"),
+                      ("dissector", "write a Wireshark Lua dissector")):
+        s = sub.add_parser(name, help=hlp)
+        s.add_argument("capture")
+        s.add_argument("-m", "--markers")
+        s.add_argument("-l", "--labels", help="no markers? actions in the order you clicked them, "
+                       "';'-separated or a file with one per line; split at the pauses between them")
+        s.add_argument("-d", "--device", type=int)
+        s.add_argument("-o", "--out")
+        if name == "dissector":
+            s.add_argument("-n", "--name", default="usbrea", help="protocol/filter name in Wireshark")
+
+    h = sub.add_parser("hid", help="decode a HID report descriptor (from a capture or hex)")
+    h.add_argument("source", help="capture file, or descriptor hex (e.g. from /sys/class/hidraw/*/device/report_descriptor)")
+    h.add_argument("--decode", metavar="HEX", help="also decode one report payload")
+    h.add_argument("--type", default="Input", choices=["Input", "Output", "Feature"], help="report type for --decode")
+    h.add_argument("--items", action="store_true", help="print every descriptor item")
+
+    d = sub.add_parser("demo", help="generate a synthetic capture and run the whole pipeline")
+    d.add_argument("-o", "--outdir", default="usb-rea-demo")
+    d.add_argument("--device", choices=["lamp", "fan", "dial"], default="lamp")
+
+    r = sub.add_parser("replay", help="send one packet to a real device (requires --yes)")
+    r.add_argument("vid", type=_int)
+    r.add_argument("pid", type=_int)
+    r.add_argument("endpoint", type=_int)
+    r.add_argument("hex")
+    r.add_argument("--setup", help="8-byte setup packet hex for control transfers")
+    r.add_argument("--yes", action="store_true")
+
+    sub.add_parser("mcp", help="run the MCP server (stdio)")
+
+    a = p.parse_args(argv)
+    if a.cmd is None:
+        p.print_help()
+        return 0
+    if a.cmd == "capture":
+        from . import capture
+        if a.op == "start":
+            print(f"capturing to {a.out} (pid {capture.start(a.out, a.bus)})")
+        else:
+            print("stopped" if capture.stop() else "no capture running")
+        return 0
+    if a.cmd == "mark":
+        from .actions import append_marker
+        print(json.dumps(append_marker(a.markers, a.label)))
+        return 0
+    if a.cmd == "replay":
+        from .replay import replay
+        try:
+            print(replay(a.vid, a.pid, a.endpoint, bytes.fromhex(a.hex),
+                         bytes.fromhex(a.setup) if a.setup else None, confirm=a.yes))
+        except PermissionError as e:
+            print(e, file=sys.stderr)
+            return 2
+        return 0
+    if a.cmd == "mcp":
+        from .mcp_server import run
+        run()
+        return 0
+    if a.cmd == "hid":
+        return _hid(a)
+    if a.cmd == "demo":
+        return _demo(Path(a.outdir), a.device)
+    if a.cmd == "transfers":
+        from .pcap import read_transfers
+        for t in read_transfers(a.capture):
+            print(f"{t.frame:6d} dev {t.device:3d} ep 0x{t.endpoint:02x} {t.kind:9s} "
+                  f"{'OUT' if t.is_out else 'IN '} {(t.setup.hex() + ' | ') if t.setup else ''}{t.data.hex(' ')}")
+        return 0
+
+    from .pipeline import analyze, sha256
+    labels = None
+    if getattr(a, "labels", None):
+        from .actions import read_labels
+        labels = read_labels(a.labels)
+    proto = analyze(a.capture, a.markers, a.device, labels)
+    if a.cmd == "infer":
+        text = json.dumps(proto.to_dict(), indent=1, default=str)
+    elif a.cmd == "report":
+        from .report import render
+        text = render(proto, a.capture, sha256(a.capture))
+    elif a.cmd == "dissector":
+        from .dissector import generate
+        text = generate(proto, a.name)
+    else:
+        from .scaffold import generate
+        text = generate(proto)
+    if a.out:
+        Path(a.out).write_text(text)
+        print(f"wrote {a.out}")
+    else:
+        print(text)
+    return 0
+
+
+def _hid(a) -> int:
+    from . import hid
+    src = Path(a.source)
+    if src.exists() and src.suffix in (".pcap", ".pcapng", ".cap"):
+        from .pcap import read_transfers
+        found = hid.from_transfers(read_transfers(src))
+        if not found:
+            print("no HID report descriptor (GET_DESCRIPTOR 0x22) in this capture; "
+                  "replug the device while capturing, or pass the descriptor hex", file=sys.stderr)
+            return 1
+        descs = [(f"device {d}, interface {i}", raw) for (d, i), raw in sorted(found.items())]
+    elif src.exists():
+        raw = src.read_bytes()
+        descs = [(str(src), raw)]
+    else:
+        descs = [("hex", bytes.fromhex(a.source.replace("0x", "").replace(",", " ")))]
+    for name, raw in descs:
+        desc = hid.parse(raw)
+        print(f"# {name}: {len(raw)} bytes, top level {', '.join(desc.top_usages) or '?'}")
+        if a.items:
+            print(hid.dump(desc))
+        for r in desc.reports:
+            print(f"\n{r.title()}")
+            for f in r.fields:
+                print(f"  {f.describe()}")
+        if a.decode:
+            print(f"\n{a.type} {a.decode}:")
+            for label, v in hid.decode(desc, a.type, bytes.fromhex(a.decode)):
+                print(f"  {label} = {v}")
+    return 0
+
+
+def _demo(outdir: Path, device: str = "lamp") -> int:
+    from .synth import make_capture
+    from .pipeline import analyze, sha256
+    from .report import render
+    from .scaffold import generate
+    outdir.mkdir(parents=True, exist_ok=True)
+    cap, _ = make_capture(outdir / f"{device}.pcap", device=device)
+    proto = analyze(cap)
+    (outdir / "report.md").write_text(render(proto, str(cap), sha256(cap)))
+    (outdir / f"{device}_driver.py").write_text(generate(proto))
+    from .dissector import generate as dissector
+    (outdir / f"{device}.lua").write_text(dissector(proto))
+    (outdir / "__init__.py").touch()
+    print(f"captured {sum(len(c.samples) for c in proto.commands)} labelled actions, "
+          f"device {proto.vid:04x}:{proto.pid:04x}\n")
+    for c in proto.commands:
+        print(f"{c.name:12s} {c.confidence:4.0%}  " + " | ".join(f.describe() for f in c.fields))
+    print(f"\nwrote {outdir}/report.md, {outdir}/{device}_driver.py and the Wireshark dissector {outdir}/{device}.lua")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

usb_rea/dissector.py

@@ -0,0 +1,271 @@
+"""Generate a Wireshark Lua dissector from an inferred protocol.
+
+The dissector is a postdissector: it looks at the payload Wireshark already extracted for every
+USB transfer (bulk/interrupt `usb.capdata`, control `usb.data_fragment`, HID `usbhid.data`), matches
+it against the inferred commands (endpoint or setup packet, length, constant bytes) and labels each
+field, decodes values, and verifies checksums. It is pure Lua with no bit library, so it runs on
+Wireshark 3.x (Lua 5.2) and 4.x (Lua 5.4).
+"""
+from __future__ import annotations
+import re
+
+from .infer import Protocol
+
+# name -> (width, lua expression over `d`, a list of byte values)
+_LUA_CHECKSUMS = {
+    "sum8": "sum(d) % 256",
+    "xor8": "xorall(d)",
+    "neg_sum8": "(256 - sum(d) % 256) % 256",
+    "inv_sum8": "255 - sum(d) % 256",
+    "sum16": "sum(d) % 65536",
+    "crc8": "crc(d, 8, 0x07, 0x00, false, false, 0x00)",
+    "crc8_maxim": "crc(d, 8, 0x31, 0x00, true, true, 0x00)",
+    "crc16_ccitt_false": "crc(d, 16, 0x1021, 0xFFFF, false, false, 0x0000)",
+    "crc16_xmodem": "crc(d, 16, 0x1021, 0x0000, false, false, 0x0000)",
+    "crc16_modbus": "crc(d, 16, 0x8005, 0xFFFF, true, true, 0x0000)",
+    "crc16_kermit": "crc(d, 16, 0x1021, 0x0000, true, true, 0x0000)",
+}
+
+_HELPERS = r'''
+-- ---- arithmetic-only helpers (no bit library needed) ----
+local function bxor(a, b)
+    local r, p = 0, 1
+    while a > 0 or b > 0 do
+        if a % 2 ~= b % 2 then r = r + p end
+        a, b, p = math.floor(a / 2), math.floor(b / 2), p * 2
+    end
+    return r
+end
+
+local function reflect(v, w)
+    local r = 0
+    for _ = 1, w do r = r * 2 + v % 2; v = math.floor(v / 2) end
+    return r
+end
+
+local function sum(d) local s = 0 for _, b in ipairs(d) do s = s + b end return s end
+local function xorall(d) local x = 0 for _, b in ipairs(d) do x = bxor(x, b) end return x end
+
+local function crc(d, w, poly, init, refin, refout, xorout)
+    local top, mod, c = 2 ^ (w - 1), 2 ^ w, init
+    for _, b in ipairs(d) do
+        if refin then b = reflect(b, 8) end
+        c = bxor(c, b * 2 ^ (w - 8))
+        for _ = 1, 8 do
+            if c >= top then c = bxor((c * 2) % mod, poly) else c = (c * 2) % mod end
+        end
+    end
+    if refout then c = reflect(c, w) end
+    return math.floor(bxor(c, xorout))
+end
+
+local function bytes_of(r)
+    local t = {}
+    for i = 0, r:len() - 1 do t[#t + 1] = r(i, 1):uint() end
+    return t
+end
+
+-- show the integer the user most likely picked when the raw byte is consistent with it
+-- (brightness 25% -> 0x40 -> 25.098 is shown as 25)
+local function fmt(v, scale)
+    local n = math.floor(v + 0.5)
+    if math.abs(v - n) <= 0.5 / math.abs(scale or 1) + 1e-9 then return string.format("%d", n) end
+    return string.format("%.4g", v)
+end
+'''
+
+
+def _ident(name: str) -> str:
+    s = re.sub(r"\W+", "_", name).strip("_").lower() or "cmd"
+    return s if not s[0].isdigit() else "cmd_" + s
+
+
+def _lua_str(s: str) -> str:
+    return '"' + s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ") + '"'
+
+
+def generate(proto: Protocol, name: str = "usbrea") -> str:
+    p = _ident(name)
+    ids = f"{proto.vid:04x}:{proto.pid:04x}" if proto.vid is not None else "unknown id"
+    out = [f'''-- Wireshark dissector for USB device {ids}.
+-- Generated by usb-rea (https://github.com/emirmrkaljevic/usb-rea) from captured traffic;
+-- every command below is backed by frames listed in the accompanying report.md.
+--
+-- Use:   wireshark -X lua_script:{p}.lua capture.pcapng
+--        tshark -X lua_script:{p}.lua -r capture.pcapng -Y {p}
+-- or copy this file to your personal Lua plugins folder (Help > About Wireshark > Folders).
+-- Filter fields: {p}.command, {p}.<command>.<field>, {p}.checksum_ok
+''']
+    out.append(_HELPERS)
+    out.append(f'''
+local P = Proto({_lua_str(p)}, {_lua_str(f"usb-rea: USB device {ids}")})
+local f_command = ProtoField.string("{p}.command", "Command")
+local f_checksum_ok = ProtoField.bool("{p}.checksum_ok", "Checksum OK")
+local f_unknown = ProtoField.bytes("{p}.unknown", "Unknown bytes")
+local fields = {{ f_command, f_checksum_ok, f_unknown }}
+local e_bad_checksum = ProtoExpert.new("{p}.checksum_bad", "Checksum mismatch", expert.group.CHECKSUM, expert.severity.WARN)
+P.experts = {{ e_bad_checksum }}
+
+local function pf(f) fields[#fields + 1] = f; return f end
+''')
+    cmds = []
+    for c in proto.commands:
+        cid = _ident(c.name)
+        roles = []
+        for f in c.fields:
+            if f.kind in ("const", "part"):
+                continue
+            idx = "" if f.index == 0 else str(f.index)
+            if f.kind == "command":
+                fid, decl = f"{cid}.command_id", f'ProtoField.uint8("{p}.{cid}.command_id", "Command id", base.HEX)'
+            elif f.kind in ("value", "bitfield"):
+                label = c.name if f.index == 0 else f"{c.name}[{f.index}]"
+                fid = f"{cid}.value{idx}"
+                decl = f'ProtoField.double("{p}.{fid}", {_lua_str(label)})'
+            elif f.kind == "lookup":
+                fid = f"{cid}.value{idx}"
+                vs = ", ".join(f"[{v}] = {_lua_str(f'{k:g}')}" for k, v in sorted(f.table.items()))
+                decl = f'ProtoField.uint8("{p}.{fid}", {_lua_str(c.name + " (lookup)")}, base.HEX, {{ {vs} }})'
+            elif f.kind == "counter":
+                fid = f"{cid}.counter"
+                decl = f'ProtoField.uint{8 * f.width}("{p}.{fid}", "Sequence counter")'
+            elif f.kind == "checksum":
+                fid = f"{cid}.checksum"
+                decl = f'ProtoField.uint{8 * f.width}("{p}.{fid}", {_lua_str(f.algo)}, base.HEX)'
+            else:
+                fid, decl = None, None
+            var = "f_" + re.sub(r"\W", "_", fid) if fid else "f_unknown"
+            if decl:
+                out.append(f"local {var} = pf({decl})\n")
+            role = {"kind": f.kind, "var": var, "off": f.offset, "w": f.width, "le": f.endian == "le"}
+            if f.kind in ("value", "bitfield"):
+                role.update(scale=f.scale, bias=f.bias, idx=f.index)
+            if f.kind == "bitfield":
+                role.update(bo=f.bit_offset, bw=f.bit_width)
+            if f.kind == "lookup":
+                role.update(idx=f.index, table={v: k for k, v in f.table.items()})
+            if f.kind == "checksum":
+                role.update(algo=f.algo, a=f.covers[0], z=f.covers[1])
+            roles.append(role)
+        consts = [(f.offset, f.const) for f in c.fields if f.kind in ("const", "command")]
+        setup = None
+        if c.setup:
+            s = c.setup
+            setup = (s[0], s[1], s[2] | s[3] << 8)
+        cmds.append((c, cid, roles, consts, setup))
+
+    out.append("\nlocal COMMANDS = {\n")
+    for c, cid, roles, consts, setup in cmds:
+        frames = ", ".join(map(str, c.frames[:8]))
+        out.append(f"    -- {c.name}: {c.confidence:.0%} confidence, evidence frames {frames}\n")
+        cs = ", ".join(f"{{{o}, 0x{v:02x}}}" for o, v in consts)
+        su = f"{{0x{setup[0]:02x}, 0x{setup[1]:02x}, 0x{setup[2]:04x}}}" if setup else "nil"
+        rs = []
+        for r in roles:
+            parts = [f'kind = "{r["kind"]}"', f'f = {r["var"]}', f'off = {r["off"]}', f'w = {r["w"]}',
+                     f'le = {"true" if r["le"] else "false"}']
+            for k in ("scale", "bias"):
+                if k in r:
+                    parts.append(f"{k} = {r[k]!r}")
+            for k in ("idx", "bo", "bw", "a", "z"):
+                if k in r:
+                    parts.append(f"{k} = {r[k]}")
+            if "table" in r:
+                parts.append("table = { " + ", ".join(f"[{b}] = {v!r}" for b, v in sorted(r["table"].items())) + " }")
+            if "algo" in r:
+                parts.append(f'check = function(d) return {_LUA_CHECKSUMS[r["algo"]]} end')
+            rs.append("            { " + ", ".join(parts) + " },\n")
+        out.append(f'''    {{ name = {_lua_str(c.name)}, ep = {c.endpoint}, control = {"true" if setup else "false"}, setup = {su},
+      length = {c.length}, consts = {{ {cs} }},
+      roles = {{
+{"".join(rs)}      }} }},
+''')
+    out.append("}\n")
+    out.append(f'''
+P.fields = fields
+
+local fd_capdata = Field.new("usb.capdata")
+local fd_fragment = Field.new("usb.data_fragment")
+local fd_endpoint = Field.new("usb.endpoint_address")
+local fd_reqtype = Field.new("usb.bmRequestType")
+local fd_request = Field.new("usb.setup.bRequest")
+local fd_wvalue = Field.new("usb.setup.wValue")
+local ok_hid, fd_hid = pcall(Field.new, "usbhid.data")
+if not ok_hid then fd_hid = nil end
+
+local function payload()
+    for _, fd in ipairs({{ fd_capdata, fd_fragment, fd_hid }}) do
+        local fi = fd and fd()
+        if fi and fi.range and fi.len > 0 then return fi.range end
+    end
+end
+
+local function matches(c, r)
+    if r:len() ~= c.length then return false end
+    if c.control then
+        local rt, rq, wv = fd_reqtype(), fd_request(), fd_wvalue()
+        if not (rt and rq and wv) then return false end
+        if rt.value ~= c.setup[1] or rq.value ~= c.setup[2] or wv.value ~= c.setup[3] then return false end
+    else
+        local ep = fd_endpoint()
+        if not ep or ep.value ~= c.ep then return false end
+    end
+    for _, k in ipairs(c.consts) do
+        if r(k[1], 1):uint() ~= k[2] then return false end
+    end
+    return true
+end
+
+local function raw(role, r)
+    local s = r(role.off, role.w)
+    return role.le and s:le_uint() or s:uint(), s
+end
+
+function P.dissector(tvb, pinfo, tree)
+    local r = payload()
+    if not r then return end
+    for _, c in ipairs(COMMANDS) do
+        if matches(c, r) then
+            local t = tree:add(P, r)
+            t:add(f_command, r, c.name)
+            local vals, ok = {{}}, nil
+            for _, role in ipairs(c.roles) do
+                local v, s = raw(role, r)
+                local add = role.le and t.add_le or t.add
+                if role.kind == "value" then
+                    local x = (v - role.bias) / role.scale
+                    add(t, role.f, s, x); vals[#vals + 1] = fmt(x, role.scale)
+                elseif role.kind == "bitfield" then
+                    local bits = math.floor(v / 2 ^ role.bo) % 2 ^ role.bw
+                    local x = (bits - role.bias) / role.scale
+                    add(t, role.f, s, x):append_text(string.format(" (bits %d-%d)", role.bo, role.bo + role.bw - 1))
+                    vals[#vals + 1] = fmt(x, role.scale)
+                elseif role.kind == "lookup" then
+                    add(t, role.f, s); vals[#vals + 1] = role.table[v] and fmt(role.table[v]) or string.format("0x%02x?", v)
+                elseif role.kind == "checksum" then
+                    local want = role.check(bytes_of(r(role.a, role.z - role.a)))
+                    local item = add(t, role.f, s)
+                    ok = (ok ~= false) and (v == want)
+                    if v == want then item:append_text(" [correct]")
+                    else
+                        item:append_text(string.format(" [incorrect, should be 0x%x]", want))
+                        item:add_proto_expert_info(e_bad_checksum)
+                    end
+                elseif role.kind == "unknown" then
+                    t:add(f_unknown, s)
+                else
+                    add(t, role.f, s)
+                end
+            end
+            if ok ~= nil then t:add(f_checksum_ok, ok):set_generated() end
+            pinfo.cols.protocol:set({_lua_str(p.upper())})
+            pinfo.cols.info:set(c.name .. (#vals > 0 and (" " .. table.concat(vals, " ")) or "")
+                .. (ok == false and " [bad checksum]" or ""))
+            return
+        end
+    end
+end
+
+register_postdissector(P)
+''')
+    return "".join(out)