USB Diagnostics Guide: Debug USB Devices with Capture Evidence
A practical USB diagnostics workflow for firmware and driver teams: capture with usbmon or USBPcap, verify enumeration, inspect descriptors and transfers, compare sessions, and prepare evidence.
USB failures often arrive as unhelpful host symptoms: Code 10 or Code 43, “device descriptor request failed,” an adapter that mounts then disappears, a HID control that never takes effect, or a bulk transfer that times out. The visible error is not the diagnosis. A defensible USB diagnostics workflow follows the bus evidence from capture setup through enumeration, descriptors, endpoints, class/vendor requests, recovery, and comparison with a known-good session.
This guide is a map for firmware, driver, QA, and support teams. It does not promise that a packet trace alone reveals an undocumented firmware state or identifies the responsible cable/controller/hop. It does show how to retain enough USB evidence to turn a vague operating-system message into a specific next question for the owning team.
Bus Scope is a local USB protocol analyzer workbench for that case-oriented process: capture selection, dense transfer inspection, setup fields, descriptors, class decoding, filtering, and session comparison. Use a hardware analyzer, usbmon, USBPcap, firmware logs, host traces, or electrical measurements whenever the evidence boundary calls for them.
Start by naming the symptom and capture point
Before opening a capture, record what the operator saw, which host/port/controller was involved, device firmware version if available, the time window, and whether the device worked on another host or cable. That context prevents the next person from treating one endpoint trace as a universal USB truth.
| Reported symptom | First evidence question | Likely diagnostic layer |
|---|---|---|
| Device never appears | Did connect/reset/enumeration traffic reach the observed bus? | Physical path, hub/controller, enumeration |
| “Descriptor request failed” | Which standard request failed or returned malformed/short data? | Endpoint zero and descriptors |
| Device appears with wrong driver | Are interfaces, IAD, class/subclass/protocol fields coherent? | Configuration/interface binding |
| HID input is late or missing | Are interrupt transfers present at expected intervals and report format? | Endpoint polling, report descriptor, firmware timing |
| Bulk transfer stalls/times out | Which endpoint/direction/transfer preceded the failure? | Endpoint state and protocol flow |
| Vendor tool times out | What setup packet/data/status/reset pattern was observed? | Endpoint zero, private firmware command |
| Device recovers only after unplug | Did clear-halt/reset/re-enumeration restore the expected state? | Recovery/state machine/power |
Write “observed on this capture point” in the case note. A client-side USBPcap trace and a device-side hardware analyzer do not expose exactly the same evidence or failure modes.
Choose the capture path deliberately
Software capture is often the quickest way to begin, but it has limits. Linux usbmon and Windows USBPcap observe traffic through their platform paths. A hardware analyzer can be useful when host capture is incomplete, timing precision matters, electrical/low-level events are suspect, or an embedded device fails before the operating system can observe it normally.
| Capture approach | Useful when | Important limit to record |
|---|---|---|
| Linux usbmon | Reproducing a Linux host/driver/device interaction | Permissions, interface selection, and host-capture perspective matter |
| Windows USBPcap | Reproducing on Windows and collecting a PCAP-style trace | Correct root hub/controller selection is required |
| Bus Scope local session | Reviewing supported USB capture evidence and case context | It is not a hardware electrical analyzer |
| Hardware analyzer | Precise wire-level timing or early/host-independent failure needs investigation | Cost, physical placement, and analyzer configuration affect scope |
| Firmware/serial logs | Explaining private state branches after a specific request | Logs need time/request correlation with bus evidence |
| Host controller/system logs | Driver binding, power, reset, and OS policy context | Log text does not replace transfer-level evidence |
Begin with platform capture setup and connect to a device. For a practical platform comparison, read USBPcap vs usbmon capture. Do not switch capture tools randomly after a failure; preserve the original context and state why a second point is needed.
Work through USB in layers
USB debugging is quicker when it follows the dependency order. An application command cannot succeed reliably if enumeration, configuration, interface selection, or endpoint state was already wrong.
| Layer | What to inspect | Evidence that should survive a handoff |
|---|---|---|
| Connection/reset | Device arrival, reset, speed/power/hub context where visible | Time window and controller/hub context |
| Enumeration | Device/configuration/string/BOS descriptor requests and responses | Setup fields, response lengths, stalls/timeouts |
| Configuration | SET_CONFIGURATION, interface/alternate-setting selections | Chosen configuration/interface before later transfers |
| Binding/class setup | IAD/interface descriptors, class requests, driver-side outcome | Descriptor fields and exact host request sequence |
| Endpoint traffic | Interrupt, bulk, control, isochronous direction/length/status | Endpoint address, transfer type, timing, status |
| Recovery | STALL, clear feature, class reset, disconnect/re-enumeration | Preceding transaction and first post-recovery success/failure |
| Application/firmware | Vendor request meaning, payload state, internal logs | Correlated request ID/time and clear uncertainty boundary |
This sequence is more credible than starting from a broad “USB protocol error” label. It also keeps a team from increasing a timeout or changing a driver before understanding the request that triggered it.
Enumeration and descriptors: prove the host got the contract it asked for
Enumeration is a structured negotiation. The host requests descriptors; the device reports device, configuration, interface, endpoint, and sometimes string/BOS/other-speed information. A malformed length, wrong interface layout, unsupported request, or unexpected reset can block normal driver binding long before an application opens a pipe.
| Descriptor or control symptom | Evidence to check | Useful next step |
|---|---|---|
| Device descriptor request fails | Setup packet, data-stage length, status/stall/reset | Compare with the USB descriptor contract and firmware response buffer |
| Device appears as an unknown device | VID/PID, class fields, configuration response, OS binding log | Verify descriptor identity and driver selection |
| Composite device binds incorrectly | IAD/interface numbering/class/subclass/protocol | Compare the full configuration descriptor, not only one interface |
| Interface appears but endpoint is absent | Endpoint descriptor address/type/max packet/interval | Check alternate setting and endpoint declaration |
| Other-speed/qualifier request behaves unexpectedly | Request/response and device speed/state | Verify whether the descriptor applies to the current speed/configuration |
| String/serial mismatch | LANGID/string descriptor transaction and bytes | Retain the request sequence and encoding/context |
Use control-transfer setup packet debugging, composite device and IAD debugging, and device qualifier/other-speed configuration for field-level investigation.
Endpoint and transfer failures: follow direction, status, and time
Once a device configures, each endpoint has a direction and transfer type. A timeout, STALL, short transfer, or missing report needs the surrounding request/response context. Do not declare “firmware is slow” from the first failed bulk row.
| Transfer family | Common symptom | Evidence to preserve |
|---|---|---|
| Control | Vendor command timeout, descriptor failure, class request rejected | Setup fields, DATA/STATUS stages, reset/re-enumeration behaviour |
| Interrupt/HID | Missed reports, input lag, feature report not applied | Poll interval, endpoint direction, report bytes, timing over several polls |
| Bulk | Read/write timeout, endpoint STALL, protocol data mismatch | Endpoint, direction, expected/actual length, clear-halt/retry sequence |
| Isochronous | Audio/video dropout or jitter | Transfer interval, packet-size pattern, overflow/underflow context |
| Mass storage BOT/UASP | Mount/error/recovery loop | Command wrapper/status/sense or transport recovery context |
The related guides lead to precise evidence: USB endpoint STALL and bulk timeout, USB HID input lag and missed reports, vendor-specific control request timeout, and BOT/UASP mass-storage reset timeout.
Compare a working session with a failing one
A known-good capture is often more useful than another hour of speculation. Capture the same host/tool action against a working device, firmware build, port, or configuration when safely possible. Compare from connection through the first divergence, not only the final error row.
| Difference between sessions | A defensible lead |
|---|---|
| Descriptor bytes/configuration differ | Firmware identity/configuration/driver-binding issue to verify |
| Same setup request, different data or status stage | Firmware command implementation/state is a stronger lead |
| Failing run lacks a prerequisite request | Tool sequence, timing, mode, or authentication/state dependency |
| Failure starts after a specific endpoint STALL | Recovery/endpoint state machine should be checked |
| One controller/port fails but another succeeds | Host controller, power, cable, hub, driver, or timing context needs comparison |
| Both runs match on the bus but user result differs | Application/driver/log layer may own the remaining difference |
Save cases with enough metadata for a teammate to reproduce the comparison. Saving and comparing USB sessions explains the local handoff path; troubleshooting capture issues covers an empty or incomplete evidence view.
Build a useful firmware or support handoff
The best USB diagnostic report has three layers. First, quote the observable transfer fact. Second, state the bounded hypothesis it supports. Third, name the log/capture/device test needed to prove ownership. That avoids a driver team receiving a capture that simply says “USB broken.”
| Report level | Example wording |
|---|---|
| Observed fact | “After SET_CONFIGURATION, bulk OUT endpoint 0x02 stalled on this request; the host then attempted this recovery sequence.” |
| Supported lead | “Compare endpoint 0x02 state and the preceding command length in firmware.” |
| Needed proof | “Collect a firmware trace for the request ID and repeat on a second host/controller.” |
| Claim to avoid | “The cable permanently caused a firmware protocol defect.” |
Keep raw capture, filtered case, tool/firmware version, time window, host/controller identity, and any transformation notes together. A screen capture alone cannot preserve direction, bytes, timing, and reproducibility.
USB diagnostics QA checklist
Before closing a case or escalating it, confirm:
- The capture point and device/host/controller context are written down.
- Enumeration/configuration evidence precedes the first application-level failure.
- Endpoint direction, type, payload/length, status, and timing are retained for the failing transfer.
- Recovery, disconnect, re-enumeration, or retry evidence is included when it occurs.
- A working comparison exists or the report explains why it cannot safely be collected.
- Firmware/driver hypotheses are separated from direct observations.
- The recipient knows what to verify next and can reopen the same evidence scope.
Browse the Bus Scope blog, open the help index, or download Bus Scope to begin a local USB diagnostics case.
Frequently asked questions
Can software capture diagnose every USB problem?
No. It is often enough for descriptor, request, endpoint, and driver-workflow evidence. Electrical integrity, pre-enumeration behaviour, controller visibility, timing precision, and host-capture loss can require a hardware analyzer, logs, or another capture point.
Is a timeout always a firmware defect?
No. Record request shape, device state, endpoint direction, host timeout, reset/recovery sequence, and capture point first. A malformed request, host configuration, power/cable issue, or intended mode transition can produce a similar symptom.
Should I share a full USB capture with a vendor?
Preserve the original, then prepare a focused case with enough enumeration and transfer context to reproduce the issue. Review any identifiers or payloads according to your own privacy and support policy before external sharing.
A complete USB diagnosis acceptance matrix
“Complete” means every conclusion is tied to the lowest observed failure boundary, not that every possible tool was used. Begin with device identity and topology, capture enumeration, locate the first request or endpoint sequence that differs from expectation, and preserve enough context for another engineer to challenge the finding.
| Symptom | Minimum evidence | Next boundary if evidence is healthy |
|---|---|---|
| Device not recognized | Attach/reset, descriptor requests, status, topology | Host controller, power, cable, hardware capture |
| Descriptor failure | Raw descriptor bytes, request stages, parser result | Firmware descriptor source and build |
| Control timeout/STALL | Setup/data/status, state, recovery | Firmware request handler or host request contract |
| Bulk/interrupt loss | Endpoint map, sequence/timing/status | Driver, firmware queue, application framing |
| HID/CDC semantic issue | Class descriptor/request/report plus payload | Class driver, app mapping, device semantics |
| Reset/disconnect loop | Full lifecycle and first trigger | Power, firmware watchdog, controller/hub evidence |
How do you produce a defensible final report?
State reproduction, expected behavior, capture point, environment, first observed divergence, evidence references, bounded conclusion, competing explanations checked, unobserved layer, proposed owner, and corrected retest. Separate facts such as “control-IN timed out after the SETUP stage” from hypotheses such as “firmware task was blocked.” Include original evidence identity and a redacted reduced window where policy permits.
Ask a second engineer to reopen the case and follow the evidence without oral context. Acceptance requires the packet-level boundary and original user-visible symptom to improve together, plus adjacent negative/recovery tests. If the trace cannot observe the claimed layer, document an escalation rather than filling the gap with certainty.
Use the Bus Scope platform-capture guide to preserve provenance, the USB firmware debugging workflow for the retest loop, and software versus hardware USB analysis when the host-visible boundary is insufficient.
Final USB diagnostics questions
Does a working retry prove the root cause?
No. Retain the failed run and identify what changed before the retry. A reset, different device state, new driver binding, cable move, longer delay, or changed request can all produce a success without proving which factor corrected the original failure.
Should every diagnosis include firmware logs?
Only when the claim crosses into firmware state. Bus evidence can establish descriptors, requests, transfers, timing, status, reset, and host-visible recovery. Internal scheduler, parser, flash, or watchdog claims need authorized device-side evidence.
A ten-minute first-pass workflow
Start capture before attachment or before the controlled trigger. Confirm the correct host controller and device identity, then mark enumeration completion and the application action. Filter only after preserving the unfiltered source. Find the first response, status, length, timing, or lifecycle event that differs from the documented expectation; do not begin at the final timeout dialog and work backward by assumption.
For each finding, write one sentence in the form: “At this capture point, during this action, the host observed X while the expected contract was Y.” Add the packet/transfer reference and one sentence naming what the capture cannot prove. This format is useful for descriptor errors, control requests, endpoint stalls, missing HID reports, CDC framing, resets, and recovery.
Before handing off, run a known-good comparison with the same topology and capture scope. If the comparison changes operating system, driver, cable, hub, firmware, request, and application at once, it is a lead rather than an A/B result. Keep all changed variables visible.
Close with an owner and next evidence request: firmware log around a bounded handler, host-driver trace, application read record, hardware measurement, or second capture point. A report without a next boundary tends to become a large attachment that every team forwards unchanged.
<!-- multilingual-related-reading:start -->Related guides
Continue with the same-language pages below. They cover adjacent stages without changing the canonical owner of this topic:
<!-- multilingual-related-reading:end -->