USB Part 10: Debugging USB — Capture, Decode, and Diagnose

Capturing USB Traffic with Wireshark

Windows: Installing and Configuring USBPcap

Download USBPcap from https://desowin.org/usbpcap/ and run the installer. During installation, USBPcap registers as a kernel filter driver on each USB root hub. After the required restart, open Wireshark. You will see new interfaces labelled USBPcap1, USBPcap2, etc., corresponding to your system's USB host controllers. Select the one your device is plugged into (trial and error if you have multiple controllers), then click the start capture button before plugging in your device.

Linux: Using usbmon

# Load the usbmon kernel module
sudo modprobe usbmon

# Check which bus your device is on
lsusb -t

# Start Wireshark as root (or add yourself to wireshark group)
sudo wireshark

# In Wireshark, select usbmon0 (all buses) or usbmon1, usbmon2...
# usbmon1 = USB bus 1, usbmon2 = USB bus 2, etc.

Essential Wireshark Filter Expressions

Raw USB captures are extremely noisy — every mouse movement, keyboard scan, and background device poll appears. These filters let you focus on what matters:

Anatomy of a Captured USB Transaction

When you click on a packet in Wireshark, the packet detail pane shows the URB (USB Request Block) structure. Here is an annotated ASCII representation of what a GET_DESCRIPTOR SETUP packet looks like in the capture:

Frame 42: USB URB — GET_DESCRIPTOR Request
─────────────────────────────────────────────────────────
USB URB Header:
  URB id:           0x00000000FFFF0001
  URB type:         URB_SUBMIT (host sending to device)
  Transfer type:    Control (0x02)
  Endpoint:         0x00 (EP0 OUT, host-to-device)
  Device address:   3
  Bus id:           1
─────────────────────────────────────────────────────────
USB Control Setup:
  bmRequestType:    0x80  (device-to-host, standard, device)
  bRequest:         0x06  (GET_DESCRIPTOR)
  wValue:           0x0100 (Descriptor type=0x01 DEVICE, index=0x00)
  wIndex:           0x0000 (Language ID or interface number)
  wLength:          0x0012 (18 bytes requested — device descriptor size)
─────────────────────────────────────────────────────────
Frame 43: USB URB — GET_DESCRIPTOR Response
  Data (18 bytes):
  12 01 10 02 EF 02 01 40 83 04 11 57 00 02 01 02 03 01
  ││ ││ ╰──────╯ ╰──╯ ╰──╯ ╰──╯ ╰──╯ ╰──────╯ ╰──╯ ││ ╰─ bNumConfigurations=1
  ││ ││    bcdUSB     │    │    │    │    idProduct   ││
  ││ ││   =0x0210     │    │   EP0   │   =0x5711      ││
  ││ ││  (USB 2.1)   bDev  │  MaxPkt  │               ╰─ iSerialNumber=1
  ││ ╰─ bDescriptorType=1 │  =64B   idVendor=0x0483
  ╰─ bLength=18          bDeviceProtocol=1

Reading USB Packet Captures

Decoding a GetDescriptor Request Frame by Frame

A complete USB enumeration sequence in Wireshark follows a predictable pattern. Here is what you should see and what each packet means:

Filtering CDC Bulk Transfers

Once your CDC device has enumerated, use this filter to see only the bulk data flowing on the CDC data interface. Replace the address with your device's actual address from the capture:

# Show only bulk transfers to/from device at address 3
usb.transfer_type == 0x03 && usb.device_address == 3

# Show CDC data endpoint traffic (typically EP1 IN and EP1 OUT)
usb.transfer_type == 0x03 && (usb.endpoint_address == 0x81 || usb.endpoint_address == 0x01)

# Show CDC management notifications (interrupt EP, typically EP2 IN)
usb.transfer_type == 0x01 && usb.endpoint_address == 0x82

Filtering HID Reports

# HID reports are interrupt transfers
# Show all HID IN reports (device sending to host)
usb.transfer_type == 0x01 && usb.endpoint_address.direction == 1

# Inspect the raw HID report bytes
# Right-click a HID IN packet → Follow → USB Stream

Exporting to CSV for Batch Analysis

For timing analysis or regression testing, export your capture to CSV: File → Export Packet Dissections → As CSV. The resulting CSV has columns for frame number, time, source, destination, protocol, length, and info. You can then use Python's pandas to analyse transfer timing, packet sizes, and error rates across a large capture.

Hardware Protocol Analyzers

Total Phase Beagle 480

The Total Phase Beagle 480 is the industry-standard hardware USB analyzer for Full Speed and High Speed. It is a pass-through device: plug the USB cable from the host into the Beagle's upstream port, and the downstream port connects to your device. The Beagle captures every packet on the physical bus — SOF tokens, SETUP/DATA/ACK handshakes, NAKs, STALLs — at the wire level.

Key capabilities of the Beagle 480:

• Capture rate: Full Speed (12 Mbit/s) and High Speed (480 Mbit/s) — all speeds simultaneously if the device negotiates HS
• Timestamp resolution: 16.67 nanoseconds — sufficient to measure individual bit times
• Trigger system: Hardware triggers on specific PID (SETUP, DATA0, DATA1, SOF, NAK, STALL), on specific device address, on specific data pattern in the packet payload, or on a specific endpoint address
• Buffer depth: 4 GB on-board capture memory — captures minutes of HS traffic
• Eye diagram: The Beagle 480 with the Signal Integrity option shows HS eye diagrams directly, enabling compliance-level signal integrity analysis

When Hardware Analysis Is Necessary

Software capture tools (USBPcap, usbmon) only see packets that the OS USB stack successfully received and decoded. The following situations require a hardware analyzer:

• Device fails to enumerate: The OS shows nothing in Device Manager. A hardware analyzer will show whether the device is sending any response to the initial GET_DESCRIPTOR, and if so, what is wrong with the response.
• HS device falls back to Full Speed: The HS handshake (Chirp sequence) happens before the OS USB stack is engaged. Only a hardware analyzer can capture the Chirp K/J sequences and determine whether the device's HS PHY is responding correctly.
• Intermittent disconnects under load: The signal integrity may degrade at high data rates due to cable quality or impedance mismatch. The hardware analyzer's eye diagram shows exactly when signal margins collapse.
• Timing compliance testing: USB compliance requires responses within specific time windows (e.g., device must respond to host tokens within 6.5 bit times at HS). Only hardware analysis with nanosecond timestamps can verify this.

Comparing Hardware vs Software Capture

STM32 USB Debug via UART

When you cannot use a hardware analyzer, the next best option is to redirect TinyUSB's internal debug log output to a UART. TinyUSB has a built-in debug logging system controlled by CFG_TUSB_DEBUG in tusb_config.h. At level 2, it prints every USB transaction including descriptor contents, endpoint activity, and class-specific events.

Enabling TinyUSB Debug Logging

// In tusb_config.h — set debug level
// Level 0: No debug output
// Level 1: Errors only
// Level 2: All USB transactions (use during development)
// Level 3: Very verbose including internal state (slow, for TinyUSB development)
#define CFG_TUSB_DEBUG  2

Redirecting tu_printf to HAL_UART_Transmit

TinyUSB's debug system calls tu_printf() which by default calls the standard C printf(). If your target has no semihosting and printf goes nowhere, you need to override this. The cleanest approach is to define tu_printf as a macro that calls your UART transmit function:

// In tusb_config.h — override tu_printf to use UART
// First, declare your UART debug function
// (define this in a .c file and declare extern here)
#ifdef __cplusplus
extern "C" {
#endif
int usb_debug_printf(const char *fmt, ...);
#ifdef __cplusplus
}
#endif

#define tu_printf  usb_debug_printf

// In usb_debug.c — the actual UART printf implementation
#include "usbd_conf.h"
#include "stm32f4xx_hal.h"
#include <stdarg.h>
#include <stdio.h>

extern UART_HandleTypeDef huart2;  // Your debug UART handle

int usb_debug_printf(const char *fmt, ...)
{
    char buf[256];
    va_list args;
    va_start(args, fmt);
    int len = vsnprintf(buf, sizeof(buf), fmt, args);
    va_end(args);

    if (len > 0) {
        // Use DMA or blocking depending on your setup
        // Blocking is fine for debug — it won't affect USB if
        // called outside of USB interrupt context
        HAL_UART_Transmit(&huart2, (uint8_t*)buf, (uint16_t)len, 10);
    }
    return len;
}

Using ITM/SWO for USB Debug Messages

For Cortex-M3/M4/M7 targets with a SWD debug probe (ST-Link V2, J-Link), the ITM (Instrumentation Trace Macrocell) over the SWO pin is a zero-overhead alternative to UART. Configure ITM stimulus port 0 and redirect tu_printf to use ITM_SendChar():

// ITM-based debug output for Cortex-M targets with SWO
// CoreDebug and ITM registers are part of CMSIS — no extra headers needed

static inline void itm_send_string(const char *str)
{
    while (*str) {
        // Wait for ITM stimulus port 0 to be ready
        while (ITM->PORT[0].u32 == 0) { __NOP(); }
        ITM->PORT[0].u8 = (uint8_t)(*str++);
    }
}

int usb_debug_printf(const char *fmt, ...)
{
    char buf[256];
    va_list args;
    va_start(args, fmt);
    int len = vsnprintf(buf, sizeof(buf), fmt, args);
    va_end(args);
    itm_send_string(buf);
    return len;
}

Semihosting Alternative

If your project uses a J-Link or OpenOCD-compatible debug probe with semihosting enabled, standard printf will route to the debug console automatically. Enable semihosting by linking with the semihosting libraries: in GCC, add --specs=rdimon.specs -lrdimon to your linker flags and call initialise_monitor_handles() at startup. Semihosting significantly slows down execution (each printf call blocks waiting for the debug probe) — only use it for initial bringup, not for timing-sensitive USB debugging.

Diagnosing Enumeration Failures

Enumeration failure is the most common USB problem. The host connects to your device and… nothing. No COM port appears, no device in Device Manager, or a yellow warning icon. The following decision tree guides systematic diagnosis:

ENUMERATION FAILURE DECISION TREE
══════════════════════════════════════════════════════════════════

Device plugged in → Does anything appear in Device Manager / lsusb?
│
├── NO: Device not detected at all
│   ├── Check VBUS: measure voltage on USB +5V pin — should be 4.5–5.5 V
│   ├── Check D+ pull-up: FS device needs 1.5 kΩ to 3.3 V on D+
│   │   (TinyUSB / STM32 OTG_FS does this in hardware automatically)
│   ├── Check USB clock: STM32 OTG_FS needs 48 MHz exactly from PLL
│   │   (measured with oscilloscope or confirm in CubeMX clock tree)
│   ├── Check reset handler: did tud_init() get called before main loop?
│   └── Hardware analyzer: does device respond to GET_DESCRIPTOR at all?
│
├── YES but "Unknown Device" or error code
│   ├── Address 0 → stuck at first GET_DESCRIPTOR
│   │   ├── Check bMaxPacketSize0 in device descriptor (must be 8, 16, 32, or 64)
│   │   ├── Check that EP0 is configured and tud_task() is running
│   │   └── Enable CFG_TUSB_DEBUG 2 and check UART output for errors
│   │
│   ├── "Device not recognized" (Windows code 43 or similar)
│   │   ├── Wrong bMaxPacketSize0 — must match actual EP0 buffer size
│   │   ├── wTotalLength in configuration descriptor is wrong
│   │   ├── bNumEndpoints does not match actual endpoint descriptors
│   │   └── Class-specific descriptor missing (e.g. CDC functional descriptors)
│   │
│   └── Driver error / wrong class loaded
│       ├── bDeviceClass / bInterfaceClass mismatch
│       ├── Missing IAD descriptor for composite device
│       └── bcdUSB version mismatch (HS device claiming USB 1.1)
│
└── YES and partially works → see Section 9 (top 10 problems)

══════════════════════════════════════════════════════════════════

Symptom / Cause / Fix Reference Table

Descriptor Validation

Before spending hours with Wireshark, validate your descriptors with dedicated tools. A single wrong byte in a descriptor causes silent failure that looks like a hardware problem.

Windows: USB Device Tree Viewer

USB Device Tree Viewer (UVCView.exe, available from Microsoft's Windows Driver Kit samples or from uwe-sieber.de) shows the complete parsed descriptor tree for every connected USB device. It decodes every field, flags invalid values, and shows the raw bytes alongside the parsed interpretation. If your device shows up in Device Manager but the driver is wrong, this tool shows exactly which descriptor field caused the mismatch.

Linux: lsusb -v

# Show verbose descriptor dump for device at bus 1, device 5
lsusb -v -s 1:5

# Or by VID:PID (replace with your values)
lsusb -v -d 0483:5740

# The output includes every descriptor field with names and values:
# bLength, bDescriptorType, bcdUSB, bDeviceClass, etc.
# Look for lines starting with ** — these indicate descriptor parse errors

# Example of a CDC device with correct descriptors:
# bDeviceClass            0xef (Miscellaneous Device Class)
# bDeviceSubClass          2 (Common Class)
# bDeviceProtocol          1 (Interface Association Descriptor)
# ... (IAD present for composite device)

Common Descriptor Mistakes

Calculating wTotalLength Manually

The wTotalLength field in the configuration descriptor must be the byte count of every descriptor in the configuration, including interfaces, endpoints, and class-specific descriptors. For a CDC-ACM device:

wTotalLength calculation for CDC-ACM device:

Configuration descriptor:         9 bytes
  Interface 0 (CDC Control):      9 bytes
    CDC Header Functional:        5 bytes
    CDC Call Management:          5 bytes
    CDC ACM Functional:           4 bytes
    CDC Union Functional:         5 bytes
    Endpoint 0x82 (INT IN):       7 bytes
  Interface 1 (CDC Data):         9 bytes
    Endpoint 0x01 (BULK OUT):     7 bytes
    Endpoint 0x81 (BULK IN):      7 bytes
                              ──────────
Total wTotalLength:              67 bytes (0x0043)

For composite CDC + HID, add:
  IAD descriptor:                 8 bytes  (prepend before CDC interface 0)
  Interface 2 (HID):              9 bytes
    HID Class Descriptor:         9 bytes
    Endpoint 0x83 (INT IN):       7 bytes
                              ──────────
Total wTotalLength:             100 bytes (0x0064)

Bus Utilization Analysis

USB bandwidth is shared. Multiple devices on the same host controller compete for bandwidth within each frame. Understanding bus utilization helps explain why your bulk throughput is lower than theoretical maximum, and is essential for designing isochronous audio/video devices.

Full Speed Frame Structure

At Full Speed (12 Mbit/s), USB operates in 1 ms frames. Each frame starts with a SOF (Start-of-Frame) packet (3 bytes + timing = ~21 bit times), leaving roughly 11,979 bit times (or approximately 1,497 bytes) of usable payload per frame. Every packet also has headers and handshakes that consume bandwidth beyond the payload:

Full Speed Frame Budget (1 ms / 12 Mbit/s):
──────────────────────────────────────────────────────
Total bits per frame:     12,000 bits (1 ms × 12 Mbit/s)
SOF packet overhead:         24 bits (~2 bits header + 22 bit stuffing)
Available payload bits:   ~11,976 bits = ~1,497 bytes/frame

Per-transaction overhead (SETUP/DATA/ACK sequence):
  Token packet:  3 bytes (PID + ADDR + ENDP + CRC5)
  DATA packet:   3 bytes overhead + N bytes payload + 2 bytes CRC16
  Handshake:     1 byte (ACK/NAK/STALL)
  Total fixed:   7 bytes overhead per transaction

Maximum bulk throughput at FS:
  64-byte max packet + 7 bytes overhead = 71 bytes per transaction
  ~1497 / 71 = ~21 transactions/frame × 64 bytes = ~1344 bytes/ms = ~1.3 MB/s
  (theoretical max; real-world ~1.0–1.1 MB/s due to host scheduling)

High Speed Microframe Structure

High Speed Microframe Budget (125 µs / 480 Mbit/s):
──────────────────────────────────────────────────────
Total bits per microframe:  60,000 bits (125 µs × 480 Mbit/s)
SOF/SOA overhead:              ~400 bits
Available:                   ~59,600 bits = ~7,450 bytes/microframe

8 microframes per 1 ms frame → 8 × 7,450 = ~59,600 bytes/ms = ~59.6 MB/s total bus capacity

Maximum bulk throughput at HS:
  512-byte max packet + overhead = ~519 bytes per transaction
  ~7450 / 519 ≈ 14 transactions/microframe × 512 bytes = ~7168 bytes/125 µs
  = ~57.3 MB/s theoretical; real-world ~40–45 MB/s

Bandwidth Utilization Formula

Bus Utilization % = (packet_size_bytes × packets_per_frame × 8) / frame_bits × 100

Example: HID mouse at Full Speed
  packet_size   = 4 bytes (mouse report)
  packets/frame = 1 (1 ms polling interval)
  frame_bits    = 12,000

  Utilization = (4 × 1 × 8) / 12,000 × 100 = 0.27%

Example: CDC bulk streaming at Full Speed
  packet_size   = 64 bytes
  packets/frame = 21 (fitting as many as possible)
  frame_bits    = 12,000

  Utilization = (64 × 21 × 8) / 12,000 × 100 = 89.6%

Example: Isochronous audio at Full Speed (44.1 kHz, 16-bit stereo)
  44100 samples × 2 channels × 2 bytes = 176,400 bytes/sec
  = 176.4 bytes/ms = 176.4 bytes/frame (rounded to 177)
  packet_size   = 177 bytes (actual USB audio uses alternating 176/177)
  packets/frame = 1 (isochronous has guaranteed 1/frame)
  frame_bits    = 12,000

  Utilization = (177 × 1 × 8) / 12,000 × 100 = 11.8%

Why Bulk Gets Leftover Bandwidth

The USB host scheduler assigns bandwidth in this priority order: Control → Isochronous → Interrupt → Bulk. Isochronous and interrupt transfers have guaranteed bandwidth allocations reserved at device enumeration time (the host checks the bInterval field and the wMaxPacketSize and rejects the device if there is insufficient bandwidth). Bulk transfers use whatever bus time remains after all guaranteed transfers have been scheduled. This is why CDC bulk throughput varies under load — if you add a high-bandwidth isochronous audio device to the same host controller, your CDC throughput will decrease.

The 10 Most Common USB Problems

Practical Exercises

USB Debug Plan Generator

Use this tool to document your USB debugging session — project details, MCU, chosen debug tool, issue description, capture file path, and findings. Download as Word, Excel, PDF, or PPTX for issue tracking or design review.

Conclusion & Next Steps

USB debugging is systematic once you have the right tools and mental model. The key points from this part:

• Start free: Wireshark + USBPcap (Windows) or usbmon (Linux) handles the majority of post-enumeration debugging at zero cost. Install these tools before you write your first USB descriptor.
• Know the limits of software capture: If the device does not enumerate, the OS sees nothing — you need a hardware analyzer. The Cynthion or OpenVizsla covers Full Speed at low cost; the Total Phase Beagle 480 is the professional standard for High Speed.
• Enable TinyUSB debug level 2: Redirect tu_printf to UART. The debug output tells you exactly which descriptor request is failing, which callback was called, and what error was returned — before you even open Wireshark.
• Validate descriptors first: Most enumeration failures are descriptor errors. Use lsusb -v on Linux or USB Device Tree Viewer on Windows to catch descriptor mistakes without debugging firmware at all.
• Know the top 10 problems: Enumeration loops, missing CDC functional descriptors, DMA cache coherency on Cortex-M7, and VBUS voltage droop account for the majority of USB issues in the field. The symptom/cause/fix table in Section 6 covers all of them.
• Bus utilization matters for high-throughput designs: Bulk does not have guaranteed bandwidth — it gets what control, isochronous, and interrupt leave behind. Calculate your utilization budget before committing to USB for a high-throughput application.