USB Vendor-Specific Control Request Timeout: Debug Endpoint Zero Evidence

A USB calibration tool, production fixture, bootloader utility, or vendor SDK may report only LIBUSB_ERROR_TIMEOUT after sending a private firmware command. Standard enumeration can still look healthy, which makes the failure tempting to dismiss as a driver glitch. For a USB vendor-specific control request timeout, the first reliable evidence is more basic: the endpoint-zero setup packet, the requested direction and length, any DATA stage, the STATUS completion (or lack of it), and whether the device stalls, disconnects, resets, or re-enumerates.

The meaning of a vendor-specific bRequest, wValue, or wIndex belongs to the device's own protocol documentation and firmware. A capture cannot invent that private meaning. It can show whether the host sent the request shape the firmware expected, whether the control transfer progressed, how long it waited, and what observable state boundary followed. That is enough to separate many host/request errors from an endpoint-zero state-machine or long-running firmware-operation lead.

Bus Scope helps present this evidence as a reviewable USB transaction rather than a single timeout string.

A control transfer has a visible contract

Every USB control request begins with an eight-byte setup packet on endpoint zero. The request may have no data stage, an IN data stage from device to host, or an OUT data stage from host to device. It then completes with the opposite-direction STATUS stage. Vendor-specific does not mean structurally invisible.

Setup field	What it describes	Debug question
bmRequestType	Direction, request type, and recipient	Does direction/type/recipient match the firmware contract?
bRequest	Vendor-defined command number	Is this the exact command the known-good client sends?
wValue	Vendor-defined value/selector	Is endianness and command argument correct?
wIndex	Often interface, channel, or vendor selector	Does the target interface/state match the command?
wLength	Expected data-stage byte count	Does host expectation match the actual protocol response/input?
Payload bytes	Optional OUT data or returned IN data	Is the payload present, sized, and timed as expected?

Write these fields into the incident note before changing a timeout setting. A timeout that follows an OUT request with the wrong wLength is a different problem from a valid erase command that intentionally resets the device.

Distinguish timeout, STALL, and successful reset

The host's error message summarizes an outcome, not a root cause. A STALL is an explicit protocol response indicating the request was rejected or unsupported in that state. A timeout means the host did not observe completion within its configured window. A disconnect/re-enumeration may be an intended effect of a reset or bootloader switch, but it may also be a crash or power/connection problem.

Observed outcome	Directly supported by the trace	Next evidence to collect
STALL after setup	Device explicitly halted the request path	Request fields, current configuration/interface, firmware state, recovery behaviour
Timeout with no data/STATUS	Host did not observe transfer completion in time	Firmware logs, device responsiveness, capture point, host timeout value
Partial IN/OUT data then timeout	Data stage began but did not visibly complete	wLength, packet count, endpoint-zero state handling, buffer/operation timing
Timeout then disconnect/re-enumeration	The request was followed by an observed device transition	Expected reset/bootloader contract, descriptors after reconnect, host retry logic
Success after long delay	Device completed within an extended window	Whether delay is documented/acceptable and UI polling is safe
Repeated timeout with device still enumerated	Endpoint zero did not visibly return completion for repeated requests	Firmware command dispatch, lock/state machine, request sequence dependency

Avoid treating a timeout as proof that firmware “hung.” A capture at one point may be incomplete; the host may have cancelled the transfer; the device may be doing a documented long operation; or an invalid request may be waiting on a state that never occurs. The correct report names the observed transfer boundary and the next place to inspect.

Decode bmRequestType before comparing command values

bmRequestType packs three independent choices: direction (host-to-device OUT or device-to-host IN), request type (standard, class, or vendor), and recipient (device, interface, endpoint, or other defined recipient). For private commands, a wrong direction or recipient can look deceptively similar to a firmware timeout.

Request-shape mismatch	How it can appear	Verification step
IN/OUT reversed	Host waits for bytes while firmware expects an OUT payload, or vice versa	Compare setup packet and known-good transaction byte-for-byte
wLength wrong	Device sends fewer/more bytes than host contract expects, or waits for absent OUT data	Check protocol version, structure packing, endianness, and response size
Wrong interface in wIndex	Command reaches an interface/state that does not implement it	Confirm configuration, interface number, alternate setting, and recipient
Wrong command selector/value	Firmware enters an unsupported/private branch	Compare command sequence and device mode with reference tool
Command sent too early	Device has not completed configuration or a previous state transition	Preserve enumeration, SET_CONFIGURATION, and preceding requests
Command sent after reset/mode change	Host talks to an earlier device personality	Verify PID/VID/descriptors and reopen the correct handle

The USB control-transfer setup-packet guide provides a field-level baseline. Use it before assuming that a private command needs private debugging techniques.

Capture the sequence, not one request in isolation

Vendor commands commonly depend on an earlier unlock, interface selection, mode query, status poll, firmware chunk, or authentication/handshake step. One failed control transfer may make no sense until the preceding ten seconds are preserved.

Use this capture workflow:

1. Start capture before opening the utility or sending the command.
2. Retain enumeration, configuration, relevant interface/alternate-setting changes, and the first vendor request.
3. Identify the exact setup packet and record host timestamp, bus/device address, and interface context.
4. Track DATA and STATUS stages; note any STALL, timeout boundary, or cancellation.
5. Look for device reset, disconnect, re-enumeration, driver rebinding, or a new PID/VID after the command.
6. Compare with a known-good run using the same firmware and tool version when possible.
7. Correlate to firmware logging by request ID/time, then make one controlled code or timeout change.

Evidence section for a bug report	Example of useful wording
Observed request	“Vendor/device OUT request used this bRequest, value, index, and length after configuration.”
Completion result	“No endpoint-zero STATUS completion was observed before the host timeout.”
State change	“The device disconnected/re-enumerated 180 ms later with this visible descriptor change.”
Supported lead	“Confirm whether this command intentionally resets into bootloader mode.”
Claim to avoid	“The USB stack randomly loses vendor packets.”

The last row matters. A reproducible capture lets a firmware engineer answer the private-protocol question instead of arguing over a generic host error string.

Bootloader, flash, and mode-switch commands need different timeout logic

Vendor control requests may initiate a flash erase, reset, bootloader entry, EEPROM operation, calibration, sensor read, or status poll. Some operations legitimately take longer than normal control transfers. Others should return quickly and move long work to a later polling/status protocol. The capture tells you which observable contract the host and device currently follow; firmware design and documentation decide which one is intended.

Command class	Expected evidence pattern to define	Dangerous shortcut
Small register/status read	IN data then STATUS in a short, bounded window	Raising host timeout until any stalled firmware appears to work
Configuration write	OUT data, STATUS, then optional verification read	Assuming successful USB completion means value was accepted semantically
Flash erase/program start	Defined acknowledgment, documented wait/poll/reconnect path	Treating every disconnect as a crash or every wait as safe
Bootloader switch	Control result plus predictable disconnect/re-enumeration/personality change	Reopening the old device handle after PID/interface changes
Reset command	Completion/reset ordering documented by firmware	Sending retries while the device is intentionally transitioning
Long sensor/calibration operation	Progress/status behaviour or bounded busy response	Blocking endpoint zero indefinitely without an observable contract

Increase a host timeout only after a known-good trace or firmware contract shows that the operation legitimately needs it. Otherwise a longer timeout can hide an endpoint-zero deadlock and make production recovery slower.

Compare known-good and failing runs carefully

A working capture is often the quickest way to discover a missing prerequisite or changed command layout. Compare the start of the session as well as the failing request: descriptor values, configuration, interface/alternate setting, preceding vendor commands, timing, payload length, status responses, and reconnect mode.

Difference between runs	Plausible lead
Same command number but different direction/length	SDK/protocol-version or request packing mismatch
Failing run lacks an earlier unlock/status command	State prerequisite or command sequence dependency
Re-enumerated identity differs after a successful reference command	Bootloader/application personality change
Only one host sees the timeout	Driver binding, permissions, controller, cable/power, or host timing evidence
Both runs send identical setup packet, only failing firmware times out	Firmware command/state handling is a stronger lead
Trace begins after the command sequence diverged	Capture scope is insufficient; recapture before the first command

Bus Scope can make this comparison easier to review. It still cannot replace source-level logging for the firmware branch that owns the vendor request.

USB vendor-control timeout QA checklist

Before escalating the case, verify all of the following:

1. bmRequestType, bRequest, wValue, wIndex, and wLength are captured in the report.
2. The expected IN/OUT data and STATUS stages are explicitly described.
3. The host timeout value and observed time-to-failure are recorded separately.
4. Device state before the command—configuration, interface, mode, and prior request sequence—is retained.
5. Any STALL, reset, disconnect, re-enumeration, or driver rebinding is included in the time window.
6. A known-good run is compared when available, with firmware/tool version noted.
7. The report labels host/request evidence, firmware hypotheses, and unproven root cause separately.

Continue with USB endpoint STALL and bulk-transfer timeout debugging, USB DFU firmware-update failure debugging, Bus Scope troubleshooting, or download Bus Scope for local capture inspection.

Frequently asked questions

Does a USB control timeout always mean the device firmware froze?

No. It means the host did not observe completion within its timeout. Wrong direction/length, invalid device state, a reset transition, host cancellation, capture limitations, or a legitimately long operation can lead to that symptom. Use the setup and stage evidence to narrow it.

When should a vendor request return STALL rather than time out?

That is a firmware/protocol design decision, but an unsupported or invalid request state can often be expressed as an explicit failure rather than leaving endpoint zero incomplete. Compare the actual firmware contract and host expectations before changing behaviour.

Is it safe to solve the problem by increasing the timeout?

Only after evidence shows the command legitimately takes longer and has a defined completion/recovery path. A larger timeout can conceal a state-machine or request-shape defect and make error recovery slower.

How do you accept a vendor-control-request fix?

Retain the complete control transfer from SETUP through data and status, plus the first host action after failure. Record bmRequestType, bRequest, wValue, wIndex, wLength, direction, recipient, actual data length, endpoint-zero status, timeout owner, device state, firmware build, and any reset or re-enumeration. Compare these fields with the firmware contract rather than guessing from the numeric request alone.

Test case	Expected evidence	Pass condition
Supported request, valid state	Correct setup and data/status stages	Completes within documented bound
Unsupported request	Explicit documented rejection	Host does not wait for an unbounded transfer
Wrong length/direction	Reproducible error behavior	Firmware remains responsive and recoverable
Long-running operation	Defined status/polling or completion model	Timeout covers a measured legitimate duration
Retry after failure	Clear reset/stall recovery if required	Next valid EP0 request succeeds

Run one known-good standard request immediately before and after the vendor request. That control shows whether endpoint zero or the whole device state machine became unresponsive. If increasing a timeout is proposed, capture a duration distribution over multiple runs and document the maximum supported operation; do not choose a larger number from a single lucky completion.

Acceptance requires a cold reconnect and repeated valid/invalid sequences without a stuck EP0, silent reset loop, or stale state. Keep the failed and corrected traces in the Bus Scope session workflow and use the control-transfer setup packet guide to verify request fields before assigning the cause to firmware internals.

Measure time separately for SETUP completion, data-stage progress, status stage, host cancellation, and the next recovery request. “Timed out after five seconds” is incomplete when the device returned data promptly but never completed status, or when the host canceled before the firmware’s documented operation bound.

Test zero-length, minimum, typical, and maximum supported payloads where the contract allows them. Verify little-endian fields such as wValue, wIndex, and wLength at the decoded and raw-byte levels. A request that works only for one payload size may expose buffer handling, direction, or state assumptions rather than a general timing problem.

The final report should name the exact request shape, valid device state, measured completion distribution, failure stage, recovery behavior, and first successful corrected request. Redact vendor payload bytes when required, but retain the setup and length evidence used to support the conclusion.

Also test the request immediately after configuration and after the normal application setup sequence. If only one state works, document that precondition in the host contract or correct the firmware state machine; do not leave it as an undocumented timing delay.

Preserve both state timelines so a later client implementation can reproduce the required ordering without relying on accidental pauses.

<!-- 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:

• USB Endpoint STALL and Bulk Transfer Timeout
• USB Device Descriptor Request Failed on Windows: Debugging Code 43 with Bus-Level Evidence
• USB Bulk Transfer Timeout: Debugging High-Speed, Full-Speed, STALL, NAK, and Device Firmware Delays

<!-- multilingual-related-reading:end -->