How do you debug USB enumeration failures on an embedded device?

USB enumeration failures — where the device is not recognized by the host, shows as "Unknown USB Device," or disconnects during enumeration — are among the most frustrating embedded debugging problems because the failure happens in a fast, multi-step protocol with no serial console output available (the USB link itself is what you are trying to bring up). The debugging approach combines host-side diagnostics, protocol analysis, and systematic firmware verification.

Host-side diagnostics (start here): On Linux, run dmesg -w while plugging in the device — the kernel logs every enumeration step and the exact point of failure (e.g., "device descriptor read/64, error -71" means the device did not respond to the first GET_DESCRIPTOR). On Windows, use USBView (from the Windows SDK) or USBTreeView to inspect the device's descriptors if enumeration partially succeeded, or check Device Manager for error codes (Code 43 means the device was rejected after enumeration). On macOS, use system_profiler SPUSBDataType or the USB Prober utility. These tools are free and available immediately — always check them before reaching for a protocol analyzer.

Protocol analysis: A hardware USB protocol analyzer (Total Phase Beagle, Ellisys, or LeCroy) captures every packet on the bus, showing exactly what the host sent and what the device responded (or failed to respond). This is the definitive debugging tool for USB — it removes all guesswork. For budget-constrained debugging, a logic analyzer (Saleae Logic, Sigrok-compatible) with a USB decoder can capture low-speed and full-speed traffic, though it cannot handle high-speed. Software-based capture (Wireshark with USBPcap on Windows, or usbmon on Linux) captures traffic from the host's perspective and is free.

Common root causes to check systematically: (1) Incorrect descriptors — wTotalLength in the configuration descriptor does not match the actual concatenated length of all subordinate descriptors; endpoint addresses collide; missing CDC functional descriptors; string descriptor indices point to nonexistent strings. Verify your descriptor tables byte-by-byte against the USB specification. (2) Pull-up resistor — the 1.5K pull-up on D+ (full-speed) must be present and correctly valued. Some MCUs have an internal pull-up enabled by software; if your initialization code does not enable it, the host never detects the device. (3) Clock accuracy — USB requires a clock tolerance of 0.25% (2500 ppm) or better. An internal RC oscillator (typically 1-2% accuracy) is not sufficient for USB — you need a crystal or MEMS oscillator. Many enumeration failures on STM32 are traced to attempting USB with the HSI (internal RC) instead of HSE (external crystal). (4) VBUS detection — some USB peripherals require VBUS sensing to be configured before enabling the pull-up; if the VBUS pin is not connected or not configured, the device never starts enumeration. (5) Endpoint 0 response timing — the device must respond to setup packets within 500 ms. If your firmware has a long initialization sequence before the USB stack starts, the host times out.