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.

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"