USB Composite Device Debugging: Interface Numbers, IAD, Endpoints, and Driver Binding

USB composite devices are convenient and dangerous. A single device can expose HID controls, CDC serial, mass storage, vendor-specific endpoints, audio, video, or diagnostics interfaces. When everything is described correctly, the host binds the right drivers and each function works. When one descriptor field is wrong, the whole device can look unreliable.

Searches like "USB composite device not recognized," "CDC interface not showing," "HID works but serial does not," or "wrong driver binding USB interface" usually point to descriptor structure, interface numbering, endpoint assignment, or Interface Association Descriptor behavior.

Composite Devices Need a Coherent Configuration

The configuration descriptor is the top-level map. It must describe the total length, number of interfaces, power attributes, and all nested interface and endpoint descriptors. If wTotalLength is wrong, the host may not read all functions. If interface count is wrong, the host may ignore later interfaces. If endpoint addresses collide, transfers become ambiguous or invalid.

Inspect:

• configuration total length
• number of interfaces
• interface numbers
• alternate settings
• endpoint addresses
• endpoint directions
• class, subclass, protocol values
• descriptor order

A capture should show whether the host requested the full configuration and what bytes the device returned.

IAD Helps Group Related Interfaces

Interface Association Descriptors are often used to group multiple interfaces that belong to one function, such as CDC communication plus CDC data. Without correct grouping, the host may bind drivers incorrectly or expose only part of the function.

IAD evidence to inspect:

• first interface number
• interface count
• function class, subclass, protocol
• placement before grouped interfaces
• consistency with actual interface descriptors

If CDC serial does not appear but HID works, the HID interface may be fine while the CDC grouping is wrong.

Endpoint Address Collisions Are Easy to Miss

Endpoint addresses include direction. Endpoint 0x81 and 0x01 are different directions, but two IN endpoints with the same address are not valid within the same device configuration. Firmware teams sometimes copy endpoint descriptors between interfaces and forget to update addresses.

Symptoms include:

• one interface works, another is silent
• host sends transfers to unexpected endpoint
• class driver loads but application gets no data
• endpoint STALL or timeout after configuration
• only one function works at a time

The capture should show endpoint descriptors and later transfer traffic side by side.

Driver Binding Is Evidence Too

The host chooses drivers based on descriptors. A device that binds incorrectly may have descriptor evidence that explains why. Class, subclass, protocol, interface association, compatible IDs, and OS-specific descriptors can all affect binding.

Do not diagnose driver binding only from Device Manager or application logs. Compare the host's class-specific requests with the descriptor tree. If the expected class requests never arrive, the host probably did not bind the expected driver.

Where Bus Scope Fits

Bus Scope should help firmware teams inspect composite devices at both levels:

• descriptor map
• transfer evidence after driver binding

A good .bscope session for composite debugging shows:

• all interfaces
• IAD grouping
• endpoint assignments
• class-specific requests per interface
• raw descriptor bytes
• transfer status after configuration

That makes the support conversation specific. Instead of "Windows does not like our composite device," the report can say "interface 2 never receives CDC class requests because the grouping descriptor does not match the declared interface layout."

That is the level of evidence firmware teams need.

Build a composite-device map before changing firmware or drivers

Composite USB failures become expensive when the team talks about “the device” as though it has one function. A host may bind one interface correctly, ignore another, and still show a friendly device name. The first diagnostic artifact should be an interface map that aligns descriptor bytes, intended function, expected class driver, endpoints, and observed traffic.

Interface/function	Descriptor facts to record	Expected host behavior	Failure evidence to look for
HID control interface	Interface number, HID class, report descriptor, interrupt endpoints	HID class requests and periodic input/output reports	No class requests, report-size mismatch, missed or stalled interrupt transfers.
CDC communication/data pair	IAD first interface/count, CDC class descriptors, communication and data interfaces	CDC binding plus class requests and bulk/interrupt traffic as appropriate	Only one half appears, no CDC class requests, wrong grouping, endpoint mismatch.
Mass-storage interface	Class/subclass/protocol, bulk IN/OUT endpoints, max packet sizes	BOT/UASP-related host requests and transfer sequence	Reset/timeout, endpoint halt, wrong subclass/protocol, packet-size inconsistency.
Vendor-specific interface	Interface number, class code, WinUSB/compatible-ID intent, endpoints	Intended vendor driver/application opens the correct interface	Wrong driver binding, access denied, application claims another interface.

The map should include every interface and alternate setting in the active configuration, even when only one function appears broken. A wrong bNumInterfaces, wTotalLength, IAD range, or duplicated endpoint address can shift the interpretation of a later interface. The descriptor and other-speed configuration guide is useful when the host seems to read a different configuration picture than the firmware team expects.

A repeatable composite USB debugging sequence

1. Capture enumeration from reset/connection. Preserve device, configuration, IAD, interface, endpoint, and class-specific descriptors. Do not begin only after the operating system has decided which driver to bind; the early requests show what it actually learned.
2. Validate descriptor arithmetic. Confirm configuration wTotalLength, bNumInterfaces, each descriptor length, interface numbering, IAD first-interface/count, endpoint address uniqueness, direction, and maximum packet sizes. A small count or length error can make later “driver” symptoms inevitable.
3. Compare intended and observed binding. For each interface, write the expected class/driver and then look for the corresponding class-specific request or traffic. If HID works but CDC has no class requests, the failure may be earlier than the serial application.
4. Follow traffic by interface and endpoint. After configuration, do not group every transfer as device traffic. Endpoint 0x81 is not interchangeable with another IN endpoint, and an endpoint copied from a neighboring function can silently misroute or collide.
5. Change one descriptor or binding variable. Fix one declared inconsistency, rebuild, and capture again. A broad descriptor rewrite can obscure which fix mattered and accidentally repair or break an unrelated function.
6. Preserve a short before/after case. A useful firmware handoff shows the original interface map, changed field, expected host behavior, and observed outcome. It should be possible to review without asking the author to reconstruct a Device Manager session from memory.

Bus Scope is useful here because the descriptor tree and transfer timeline can remain in the same USB case. It does not replace a physical-layer analyzer when electrical signaling is in doubt, and it does not make a host choose a driver against its class/binding rules. It helps establish whether the firmware described a coherent composite configuration and whether the expected host interaction followed.

IAD and interface-number questions teams miss

Is an IAD required for every composite device?

No. An IAD is used to associate related interfaces into one function in situations such as a CDC communication/data pair. The need depends on the function and host behavior. The important point is consistency: when firmware uses an IAD, its first interface number, interface count, class/subclass/protocol, placement, and the interfaces that follow must agree with the actual descriptor layout.

Why does one interface work while another never appears?

The working interface may be independently valid while the failing interface is omitted by a length/count error, described with incompatible class fields, grouped incorrectly, bound to an unexpected driver, or assigned invalid endpoints. Compare the full configuration returned to the host with the firmware's intended map. Do not infer that the whole composite device is correct merely because one function works.

Can two interfaces use the same endpoint number?

Endpoint address includes direction, so 0x01 and 0x81 are different OUT and IN addresses. Two endpoints with the same address and direction in one active configuration are not a valid way to create separate traffic paths. Check both endpoint address and direction, then check maximum packet size and transfer type for the interface's class requirements.

Why does the host bind the wrong Windows driver?

Driver selection follows the descriptors and compatible IDs it sees, plus system policy and installed packages. A vendor-specific interface may need an intended association such as WinUSB, while HID or CDC should normally retain their appropriate class bindings. The libusb and WinUSB debugging guide covers why changing the wrong composite interface can make the situation worse.

A concise support report template

Include the device and firmware identity, active configuration value, total interface count, IAD entries, interface map, endpoint assignments, expected driver/function per interface, relevant descriptor bytes, observed host requests, first failed transfer or missing request, and exact reproduction steps. Then state the narrow finding: for example, “the CDC IAD begins at interface 1 but declares a range that does not include the data interface,” or “interface 3 is present but its expected class request never arrives after binding.”

That report lets the next engineer test a descriptor or driver hypothesis quickly. It is more useful than “composite device unstable” because it keeps the scope to a particular interface boundary. For related endpoint sizing and control-transfer cases, see endpoint max-packet-size mismatch and control-transfer status-stage debugging.

Regression matrix for a composite configuration

Test the descriptor map as a whole after any interface, IAD, or endpoint edit. A change that fixes one driver binding can silently change the interface numbering or endpoint ownership of a neighboring function. Capture a clean reconnect rather than relying on a cached driver state.

Regression case	Acceptance evidence
Fresh attach on a clean host profile	Host reads the complete configuration and exposes every intended interface
One functional action per interface	Expected class request or endpoint traffic appears on the mapped interface
IAD-associated function open	All interfaces in the declared range bind as one intended function where applicable
Alternate setting change	Only the selected interface’s endpoints change, with no collisions
Direct port and permitted hub path	Descriptor tree remains coherent; topology difference is recorded without unsupported physical claims

Does a host-visible capture prove which driver Windows should select?

It proves the descriptors and requests observed at the USB boundary. Driver selection can also depend on installed packages and operating-system policy. Use the trace to rule in a malformed interface contract first, then compare the intended binding policy with the exact interface that the host received.

What is the smallest safe fix?

Correct one demonstrable descriptor inconsistency—such as an IAD range, interface count, or duplicate endpoint address—then recapture from reconnect. Avoid renumbering unrelated interfaces unless the evidence requires it; a small, observable change makes the regression result trustworthy.

<!-- 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 Composite Device Wrong Driver Binding
• USB Device Keeps Disconnecting: Debugging Reset Loops, Power Events, and Enumeration Failures
• USB Device Qualifier and Other Speed Configuration Debugging

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