diff options
| -rw-r--r-- | .claude/skills/usb-sniffer/SKILL.md | 147 | ||||
| -rw-r--r-- | docs/getting_started.rst | 2 | ||||
| -rw-r--r-- | examples/device/99-tinyusb-examples.rules (renamed from examples/device/99-tinyusb.rules) | 3 | ||||
| -rw-r--r-- | examples/device/webusb_serial/README.md | 2 | ||||
| -rw-r--r-- | examples/device/webusb_serial/src/main.c | 2 | ||||
| -rw-r--r-- | tools/88-tinyusb.rules | 93 |
6 files changed, 245 insertions, 4 deletions
diff --git a/.claude/skills/usb-sniffer/SKILL.md b/.claude/skills/usb-sniffer/SKILL.md new file mode 100644 index 000000000..e9f2d08f2 --- /dev/null +++ b/.claude/skills/usb-sniffer/SKILL.md @@ -0,0 +1,147 @@ +--- +name: usb-sniffer +description: Use when you need wire-level USB evidence that host-side capture can't provide — a device that never enumerates (usbmon shows nothing or only Submits), suspected NAK storms/STALL/babble/bad handshakes, bus-reset or enumeration timing, split-transaction issues, or a usbmon-vs-device-log disagreement the wire must arbitrate. Captures LS/FS/HS packets (PIDs, tokens, handshakes, SE0/line states) with the ataradov usb-sniffer hardware into Wireshark pcapng. +--- + +# usb-sniffer — wire-level capture with the ataradov hardware analyzer + +Extends the debugging trio with the layer below URBs: + +| Skill | Answers | +|---|---| +| `usbmon` | what the host software exchanged (URBs) | +| `usb-debug` | why the host acted (dmesg / dynamic debug) | +| `usb-target-debug` | what the device firmware did | +| **`usb-sniffer`** | **what actually crossed D+/D-** (PIDs, handshakes, resets, timing) | + +Reach for it when usbmon can't see (device never binds, pre-enumeration +failures) or can't be trusted (URB completed but did the wire really ACK?). +For everything visible in URBs, usbmon is cheaper — no hardware, no locks. + +## Rig inventory — find the sniffer and what it taps + +```bash +lsusb -d 6666:6620 # sniffer present? (github.com/ataradov/usb-sniffer) +``` + +The sniffer is a passive tap: host-side and device-side connectors pass +through, the capture port is a separate USB device. What it taps is a cabling +fact you must confirm, not assume: start a capture (below), provoke known +control traffic to a candidate (`lsusb -v -s <bus>:<dev> >/dev/null`), and +see whether those requests appear on the wire. As of 2026-07 the sniffer is +on htpc tapping the hub-3-2 upstream, with `mimxrt1010_evk` (HS) behind it. + +The tapped board is rig hardware: hold its board lock for any session that +resets or reflashes it (`hil` skill). The sniffer itself is not lockable and +capture alone perturbs nothing. + +## Capture + +The tool is `usb_sniffer` (installed in `~/.local/bin`, extcap-symlinked so +Wireshark's GUI also shows a "USB Sniffer" interface). Headless recipe: + +```bash +timeout 15s usb_sniffer --capture --fifo /tmp/cap.pcapng --speed hs # or fs / ls +``` + +- `--speed` MUST match the DUT's link speed (default is fs!). Wrong speed = + no USB packets, only Syslog pseudo-packets ("Line state: SE0", "VBUS ON"). + If you see only those, fix `--speed` before doubting the hardware. +- ALWAYS bound the capture: `timeout` and/or `--limit N` (packets). HS runs + 15–20 MB/s even with `--fold` when any device on the bus is busy (`--fold` + only collapses truly empty frames). Unbounded HS captures reach GB fast. +- The output is valid pcapng the moment the process dies; a plain file path + works (no FIFO needed). `--trigger low|high|falling|rising` arms capture + on the external trigger pin instead of starting immediately. +- Tool diagnostics: `USB_SNIFFER_LOG=/tmp/sniffer.log usb_sniffer ...` + +Start the capture FIRST, then trigger the event you care about. The proven +one-pass enumeration recipe (`--limit` makes the tool exit by itself; on a +busy HS bus ~470k packets/s ≈ 20 MB/s, so 3M packets ≈ 6–7 s ≈ 120 MB — do +NOT capture for 20+ s "to be safe", the raw balloons and every later tshark +pass pays for it; but do NOT go below ~3M either: J-Link connect latency +varies run-to-run (0.5–4 s) and a 3 s window has provably missed the ladder): + +```bash +usb_sniffer --capture --fifo raw.pcapng --speed hs --fold --limit 3000000 & +sleep 1 +# trigger: full ladder incl. SET_ADDRESS (needs board lock; J-Link resets the MCU): +printf 'r\ng\nqc\n' | JLinkExe -device $JLINK_DEVICE -SelectEmuBySN <probe-uid> \ + -if swd -speed 4000 -autoconnect 1 -nogui 1 +wait # tool prints "Capture limit reached" and exits +``` + +No-probe trigger alternative — kernel-side re-enumeration (may reuse the +xHCI address and skip parts of the ladder; fine for descriptor reads, weak +for reset timing): +`echo 0 | sudo tee /sys/bus/usb/devices/<port>/authorized; sleep 1; echo 1 | sudo tee ...` + +## Reading the capture + +```bash +tshark -r cap.pcapng -Y 'usb.bmRequestType' # the control ladder +tshark -r cap.pcapng -Y 'usb.bDescriptorType == 1' \ + -T fields -e usb.idVendor -e usb.idProduct # VID:PID off the wire +tshark -r cap.pcapng -Y 'usbll.pid' # raw token/handshake level +editcap -r cap.pcapng slice.pcapng <first>-<last> # trim huge captures +``` + +On a capture >100 MB, make exactly ONE filtered pass (the ladder filter +above) to find the frame numbers of your event window, `editcap -r` to that +window, and do all further analysis on the slice — repeated broad tshark +passes over a 300 MB raw are what turn a 5-minute job into 15. + +Find the DUT's wire address from the capture, not from lsusb: the +SET ADDRESS request payload carries it (`00 05 <addr> 00 ...`), and all +subsequent traffic goes to `<addr>.<ep>` (`usbll.addr`). **On xHCI hosts the +lsusb device number is NOT the wire address** — they diverge routinely. +Filter analysis to the DUT: `-Y 'usbll.addr contains "4."'`. + +## What the wire really shows (read before concluding anything) + +- **Downstream is broadcast.** Tokens, SETUP and OUT data addressed to EVERY + device on the tapped bus segment appear in the capture; upstream (DATA in + response to IN) appears only from devices on the tapped branch. Lone + IN→ACK pairs without DATA to some other address are normal, not corruption. +- **The sniffer can capture its own upload.** If its capture port shares the + host controller bus with the tap, its bulk-IN polling floods the capture + (easily >90% of packets) — filter it out by address; for surgically clean + captures move the capture cable to a different host controller. +- **Port-reset visibility depends on the tap point.** Tapping the DUT's own + cable: a reset reaches the sniffer PHY and you get explicit + `--- Bus Reset ---` / `Detected speed:` Syslog records. Tapping a hub + upstream (current htpc wiring): the hub isolates the port reset — no + marker appears. Anchor reset timing on the hub choreography instead: + SetPortFeature(PORT_RESET) to the hub's address = reset start, + ClearPortFeature(C_PORT_RESET) = reset end (start the capture before + triggering, or the initiating SetPortFeature is missing from the file). + The DUT's silence gap corroborates, but do not read every gap as a + reset — idle captures contain benign multi-ms gaps. +- **FS device behind an HS hub**: the upstream tap shows SPLIT transactions, + not native FS packets. Tap the DUT's own cable and capture at `fs` for + clean full-speed traffic. + +## One-time setup (already done on htpc) + +udev rules (repo copy: `tools/88-tinyusb.rules` — the rig-only probe/analyzer +allowlist, distinct from the user-facing `examples/device/99-tinyusb-examples.rules`; +installed as `/etc/udev/rules.d/88-tinyusb.rules`; covers 6666:6620 + unconfigured +FX2LP 04b4:8613 along with the rig's other boards/probes), binary from upstream `bin/` to +`~/.local/bin/usb_sniffer`, extcap symlink into +`~/.local/lib/wireshark/extcap/`. Wireshark ≥4.x decodes the payloads. +The tool also has `--mcu-eeprom` / `--fpga-flash` / `--fpga-erase` firmware +commands: those are for bringing up NEW sniffer hardware — never run them +against the rig's working sniffer. + +## Warnings + +- **Bound every capture** (`timeout` / `--limit`) and delete or `editcap`-trim + multi-hundred-MB raws before handing off; a forgotten capture process fills + the disk at HS rates. +- The tap is passive — capturing, or unplugging the capture port, does not + disturb the DUT's link. Unplugging the pass-through DOES. +- Answers must come from packet payloads (SETUP/DATA hex), not from host-side + logs — that is the whole point of being on the wire; if an answer isn't in + the capture, say so rather than approximating from sysfs/dmesg. +- Release the board lock and leave no capture processes running at session + end (`pgrep -a usb_sniffer`). diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 7fcc2f5d1..7e1cd79f3 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -181,7 +181,7 @@ Some examples require udev permissions to access USB devices: .. code-block:: bash - $ cp `examples/device/99-tinyusb.rules <https://github.com/hathach/tinyusb/tree/master/examples/device/99-tinyusb.rules>`_ /etc/udev/rules.d/ + $ cp `examples/device/99-tinyusb-examples.rules <https://github.com/hathach/tinyusb/tree/master/examples/device/99-tinyusb-examples.rules>`_ /etc/udev/rules.d/ $ sudo udevadm control --reload-rules && sudo udevadm trigger Next Steps diff --git a/examples/device/99-tinyusb.rules b/examples/device/99-tinyusb-examples.rules index d306bada5..e7a399345 100644 --- a/examples/device/99-tinyusb.rules +++ b/examples/device/99-tinyusb-examples.rules @@ -1,5 +1,6 @@ +# udev rules for running the TinyUSB device examples as a non-root user. # Copy this file to the location of your distribution's udev rules, for example on Ubuntu: -# sudo cp 99-tinyusb.rules /etc/udev/rules.d/ +# sudo cp 99-tinyusb-examples.rules /etc/udev/rules.d/ # Then reload udev configuration by executing: # sudo udevadm control --reload-rules # sudo udevadm trigger diff --git a/examples/device/webusb_serial/README.md b/examples/device/webusb_serial/README.md index 5ca70f909..15837e59e 100644 --- a/examples/device/webusb_serial/README.md +++ b/examples/device/webusb_serial/README.md @@ -51,4 +51,4 @@ make BOARD=raspberry_pi_pico all After flashing, open the landing page (`https://example.tinyusb.org/webusb-serial/index.html`) in a WebUSB-capable browser such as Chrome, click **Connect**, and select the device — the on-board LED lights solid once connected. Characters typed in the web page are echoed back, and are also mirrored to the CDC serial port (e.g. `/dev/ttyACM0`) and vice versa. -On Linux/macOS you may need to install the udev rules from `examples/device/99-tinyusb.rules` for the browser to access the device. +On Linux/macOS you may need to install the udev rules from `examples/device/99-tinyusb-examples.rules` for the browser to access the device. diff --git a/examples/device/webusb_serial/src/main.c b/examples/device/webusb_serial/src/main.c index 4be5e4db4..e200c334c 100644 --- a/examples/device/webusb_serial/src/main.c +++ b/examples/device/webusb_serial/src/main.c @@ -39,7 +39,7 @@ * is done automatically by firmware. * * - On Linux/macOS, udev permission may need to be updated by - * - copying '/examples/device/99-tinyusb.rules' file to /etc/udev/rules.d/ then + * - copying 'examples/device/99-tinyusb-examples.rules' file to /etc/udev/rules.d/ then * - run 'sudo udevadm control --reload-rules && sudo udevadm trigger' */ diff --git a/tools/88-tinyusb.rules b/tools/88-tinyusb.rules new file mode 100644 index 000000000..fedeb7468 --- /dev/null +++ b/tools/88-tinyusb.rules @@ -0,0 +1,93 @@ +# Copy this file to the location of your distribution's udev rules: +# Then reload udev configuration by executing: +# sudo cp 88-tinyusb.rules /etc/udev/rules.d/ && sudo udevadm control --reload-rules && sudo udevadm trigger + +# Check SUBSYSTEM +SUBSYSTEMS=="hidraw", KERNEL=="hidraw*", MODE="0666", GROUP="dialout" +SUBSYSTEM=="usbmon", MODE="0640", GROUP="wireshark" + +# Rule applies to all TinyUSB example +ATTRS{idVendor}=="cafe", MODE="0666", GROUP="dialout" + +# Rule to make Trinket/Pro Trinket/Gemma/Flora programmable without running Arduino as root. +# Tested with Ubuntu 14.04 and 12.04. Other distributions might need to update GROUP="dialout" +# to another group value like "users". +SUBSYSTEM=="usb", ATTRS{idProduct}=="0c9f", ATTRS{idVendor}=="1781", MODE="0660", GROUP="dialout" + +# Rule to blacklist Adafruit USB CDC boards from being manipulated by ModemManager. +# Fixes issue with hanging references to /dev/ttyACM* devices on Ubuntu 15.04. +ATTRS{idVendor}=="239a", ENV{ID_MM_DEVICE_IGNORE}="1" + +# All Adafruit boards +ATTRS{idVendor}=="239a", MODE="0660", GROUP="adm" + +# All Espressif boards +ATTRS{idVendor}=="303a", MODE="0660", GROUP="adm" + +# All RaspberryPi boards +ATTRS{idVendor}=="2e8a", MODE="0660", GROUP="adm" + +# All NXP Boards +ATTRS{idVendor}=="1fc9", MODE="0660", GROUP="adm" + +# All ST +SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", GROUP="adm" + +# Rule to blacklist TinyUSB example from being manipulated by ModemManager. +SUBSYSTEMS=="usb", ATTRS{idVendor}=="cafe", ENV{ID_MM_DEVICE_IGNORE}="1" + +# Xplained Pro SamG55 Device +SUBSYSTEMS=="usb", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2111", MODE="0666", GROUP="users", ENV{ID_MM_DEVICE_IGNORE}="1" +SUBSYSTEMS=="tty", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="2111", MODE="0666", GROUP="users", ENV{ID_MM_DEVICE_IGNORE}="1" + +# TI Stellaris/Tiva-C Launchpad ICDI +SUBSYSTEM=="usb", ATTRS{idVendor}=="1cbe", ATTRS{idProduct}=="00fd", MODE="0666" + +# CMSIS-DAP, vendor = ARM +SUBSYSTEM=="usb", ATTR{idVendor}=="0d28", MODE="666" + +# wch-link +SUBSYSTEM=="usb", ATTR{idVendor}=="1a86", ATTR{idProduct}=="8010", GROUP="plugdev" +SUBSYSTEM=="usb", ATTR{idVendor}=="4348", ATTR{idProduct}=="55e0", GROUP="plugdev" +SUBSYSTEM=="usb", ATTR{idVendor}=="1a86", ATTR{idProduct}=="8012", GROUP="plugdev" + +# Pxlogic +SUBSYSTEM=="usb", ATTRS{idVendor}=="2a0e", MODE="0666" +SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", MODE="0666" + +# Arduino Renesas +SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", MODE="0666" + +# E2/E2 Lite/E1/E20/IE850A emulator +ATTR{idProduct}=="82a1", ATTR{idVendor}=="045b", MODE="666" +ATTR{idProduct}=="82a0", ATTR{idVendor}=="045b", MODE="666" +ATTR{idProduct}=="823b", ATTR{idVendor}=="045b", MODE="666" +ATTR{idProduct}=="823c", ATTR{idVendor}=="045b", MODE="666" +ATTR{idProduct}=="0250", ATTR{idVendor}=="045b", MODE="666" +# Prevent E2/E2Lite/E1/E20/IE850A from being captured by modem manager service as E2/E2 Lite/E1/E20/IE850A is not a modem +ATTR{idProduct}=="82a1", ATTR{idVendor}=="045b", ENV{ID_MM_DEVICE_IGNORE}="1" +ATTR{idProduct}=="82a0", ATTR{idVendor}=="045b", ENV{ID_MM_DEVICE_IGNORE}="1" +ATTR{idProduct}=="823b", ATTR{idVendor}=="045b", ENV{ID_MM_DEVICE_IGNORE}="1" +ATTR{idProduct}=="823c", ATTR{idVendor}=="045b", ENV{ID_MM_DEVICE_IGNORE}="1" +ATTR{idProduct}=="0250", ATTR{idVendor}=="045b", ENV{ID_MM_DEVICE_IGNORE}="1" + +#TI MSP430UIF +ATTRS{idVendor}=="2047",ATTRS{idProduct}=="0010",MODE="0666" +ATTRS{idVendor}=="2047",ATTRS{idProduct}=="0013",MODE="0666" +ATTRS{idVendor}=="2047",ATTRS{idProduct}=="0014",MODE="0666" +ATTRS{idVendor}=="2047",ATTRS{idProduct}=="0203",MODE="0666" +ATTRS{idVendor}=="2047",ATTRS{idProduct}=="0204",MODE="0666" +ATTRS{idVendor}=="0451",ATTRS{idProduct}=="f432",MODE="0666" + +# fomu +ATTRS{idVendor}=="1209",ATTRS{idProduct}=="5bf0",MODE="0666" + +# FTDI +ATTRS{idVendor}=="0403", MODE="0660", GROUP="adm" + +# Sipeed Slogic16 +SUBSYSTEM=="usb", ATTRS{idVendor}=="359f", MODE="0666", TAG+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1" + +# ataradov usb-sniffer (github.com/ataradov/usb-sniffer): programmed unit + blank FX2LP +ATTRS{idVendor}=="6666", ATTRS{idProduct}=="6620", MODE="0666" +ATTRS{idVendor}=="04b4", ATTRS{idProduct}=="8613", MODE="0666" |