mirror of
https://github.com/hathach/tinyusb.git
synced 2026-08-18 11:02:16 +00:00
skill: add usb-sniffer — wire-level capture with the ataradov hardware tap
Fourth view in the USB debugging toolset (usbmon = host URBs, usb-debug = host reasoning, usb-target-debug = device firmware, usb-sniffer = what actually crossed D+/D-). Covers the ataradov/usb-sniffer analyzer: headless pcapng capture (--speed ls/fs/hs, --fold, --limit self-exit), Wireshark/tshark analysis recipes, and the wire realities that bite: downstream broadcast, sniffer self-capture noise, xHCI devnum != wire address, tap-point-dependent reset visibility (hub choreography anchors), FS-behind-HS-hub splits. Every recipe hardware-validated on the rig, including the capture-window floor (a 3 s window provably misses the enumeration ladder; 3M packets minimum). Two udev files with distinct audiences, not one: - examples/device/99-tinyusb-examples.rules (renamed from 99-tinyusb.rules): the user-facing rules the examples need — cafe VID access, hidraw, the ModemManager blacklist, a couple of board probes. getting_started.rst, the webusb_serial README and its source comment point here. - tools/88-tinyusb.rules: the HIL rig's private probe/analyzer allowlist, now with the sniffer (6666:6620 + blank FX2LP 04b4:8613). Installed on the rig only; the usb-sniffer skill references it.
This commit is contained in:
hathach
147
.claude/skills/usb-sniffer/SKILL.md
Normal file
147
.claude/skills/usb-sniffer/SKILL.md
Normal file
@ -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`).
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
@ -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.
|
||||
|
||||
@ -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'
|
||||
*/
|
||||
|
||||
|
||||
93
tools/88-tinyusb.rules
Normal file
93
tools/88-tinyusb.rules
Normal file
@ -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"
|
||||
Reference in New Issue
Block a user