Composite Host Solution
Overview
The USB Composite Device architecture allows a single physical USB device to logically present multiple independent functions by configuring multiple Interface Descriptors or Interface Association Descriptors (IAD).
The USB host protocol stack of the Ameba platform fully supports the enumeration and driver loading of composite devices. The system can intelligently parse the device configuration structure and load the corresponding class drivers for different interfaces. This enables Ameba to handle multiple different types of traffic streams concurrently through a single USB port.
Features
Supports the following combinations of functions:
CDC ACM + CDC ECM
HID + UAC
Supports USB hot-plug
Automatically parse descriptors and adapt to speed modes
Application Scenarios
As a USB host, Ameba can support a combination of multiple interface classes through composite class drivers, enabling interaction with complex USB composite devices on the market. It is suitable for a wide range of IoT and multimedia application scenarios, such as:
Cellular Network Access (CDC ECM + CDC ACM): This is the most common composite mode for 4G/LTE Cat.1/Cat.4 modules and USB Dongles. Ameba utilizes the CDC ECM interface for high-speed Internet access, which is widely used for data backhaul in industrial IoT gateways or networking functions in vehicle-mounted terminals. Meanwhile, the CDC ACM interface is used in parallel to transmit AT commands, enabling real-time monitoring and remote control of the module’s signal status.
Interactive Audio Devices (UAC + HID): This is a typical application for USB headphones, smart speakers, or game controllers equipped with physical control buttons. Ameba utilizes the UAC interface to handle high-quality voice calls, background music, or game sound effects streaming, while simultaneously responding to physical buttons on the device (such as volume adjustment, mute, media playback control, or controller input) in real-time through the HID interface, achieving a seamless integration of audio experience and user interaction.
Protocol Introduction
The USB Composite Device specification defines a device architecture capable of supporting multiple independent function interfaces via a single physical interface within the USB framework.
This mechanism enables the host to identify and enumerate a single physical device as a collection of logical functions, facilitating parallel processing and independent control across different device classes (e.g., HID, MSC, CDC).
Common implementations include wireless keyboard/mouse receivers, USB headsets with integrated audio cards, and industrial devices combining storage and debugging capabilities.
Descriptor Structure
While adhering to standard USB descriptors (Device and Configuration Descriptors), composite devices define multi-functionality by aggregating multiple Interface Descriptors within the Configuration Descriptor set.
Single-Interface Function Class
When a single interface represents a standalone function, the composite device simply aggregates these functional classes. Typical examples of single-interface function classes include HID and MSC.
Taking a HID Keyboard + HID Mouse composite device as an example, the descriptor topology is illustrated below:
Device Descriptor
| bDeviceClass: 0xEF (Miscellaneous)
| bDeviceSubClass: 0x02 (Common Class)
| bDeviceProtocol: 0x01 (Interface Association Descriptor)
│
└── Configuration Descriptor
| bNumInterfaces: 2 (2 Interfaces)
│ ...
├── Interface Descriptor 0 (HID Keyboard)
│ bInterfaceNumber: 0
│ bInterfaceClass: 0x03 (HID)
│ bInterfaceSubClass: 0x01 (Boot Interface)
│ bInterfaceProtocol: 0x01 (Keyboard)
│
└── Interface Descriptor 1 (HID Mouse)
bInterfaceNumber: 1
bInterfaceClass: 0x03 (HID)
bInterfaceSubClass: 0x01 (Boot Interface)
bInterfaceProtocol: 0x02 (Mouse)
HID Keyboard + HID Mouse composite device compared to individual keyboard/mouse devices, with descriptor characteristics as follows:
Descriptor Level |
Single Function Device |
Composite Device |
|---|---|---|
Device Descriptor |
|
|
Configuration Descriptor |
1 Configuration |
1 Configuration |
Interface Descriptor |
1 Interface |
2 (or more) Interfaces |
Endpoint Descriptor |
Belong to the single interface |
Each interface has independent endpoints |
Note
bDeviceClass = 0xEF: This is a standard flag for composite devices, which triggers the host driver to parse the IAD (optional) and multiple interface descriptors in the configuration descriptor,
decompose different device functions, and create these logical sub-devices. Then load the keyboard driver for Interface 0 and the mouse driver for Interface 1.
Multi-Interface Function Class
If a logical function requires the use of multiple interfaces to complete, the Interface Association Descriptor (IAD) must be included when using this type of function to associate these interfaces.
Typical multi-interface functional class
CDC (Communication Device Class): Typically requires 1 Control Interface (CCI) + 1 Data Interface (DCI).
UVC (USB Video Class): Requires 1 Video Control Interface (VC) + 1 or more Video Streaming Interfaces (VS).
UAC (USB Audio Class): Requires 1 Audio Control Interface (AC) + 1 or more Audio Stream Interfaces (AS).
Interface Association Descriptor (IAD)
IAD declares to the host that a set of consecutive interfaces that follow closely belong to the same function and should be loaded and managed by the same driver. Without IAD, the host sometimes recognizes them as two separate devices, or the driver fails to load.
Interface Association Descriptor (IAD)
├── bLength : 1 byte → 0x08 (Fixed Length)
├── bDescriptorType : 1 byte → 0x0B (IAD type code)
├── bFirstInterface : 1 byte → First Interface Number
├── bInterfaceCount : 1 bytes → Count of associated interfaces
├── bFunctionClass : 1 byte → Function Class Code
├── bFunctionSubClass : 1 byte → Function SubClass Code
├── bFunctionProtocol : 1 byte → Function Protocol Code
└── iFunction : 1 byte → Function String Descriptor Index
IAD Usage Example
Function 1: Class utilize two interfaces. In order for the host to recognize them as a single logical function, it is necessary to use IAD to associate these two interfaces.
Function 2: Class utilize a separate interface, eliminating the need for IAD association.
Class-specific request
The USB protocol specification does not define a specific “composite class request”. Their core logic lies in precisely directing Class-Specific Requests to the designated interface through the addressing mechanism in USB standard requests.
In the bmRequestType field of the SETUP packet, the lower 5 bits (Bits 0..4) represent the Recipient.
General single-function device: Control requests are typically sent to the “entire device”, meaning the Recipient is set to
Device (00000).Composite device: A large number of control requests must be precisely sent to a “specific interface”, which means setting the Recipient to
Interface (00001).
The following are the most notable key points regarding the handling of control requests by composite devices:
Field |
Value |
Meaning |
Implementation in Composite Devices |
|---|---|---|---|
bmRequestType |
0x21 / 0xA1 |
Class Request, Recipient=Interface |
Most common scenario. Examples include setting CDC baud rates or controlling HID keyboard LEDs. |
wIndex |
Interface Number |
Interface Number |
When the Recipient is Interface, wIndex must specify the target interface index (e.g., 0, 1, 2). The driver routes the request to the corresponding function driver based on this value. |
Class Driver
A composite device is a device that incorporates multiple independent functions within a single physical USB device. The host stack’s job is to parse that device’s configuration descriptor, load the class driver that matches each interface, and enumerate one physical device as a collection of multiple logical functions. Each function then operates independently — sending AT commands while transmitting network data, or receiving button input while playing music.
This section explains how a composite application is put together on the host side.
There is no composite class driver. The host stack has no parent-class layer that owns the sub-functions; instead, each class driver registers with the USB core on its own, and the core matches every interface in the device’s configuration descriptor to whichever class driver claims it. A “composite host” is therefore an application that brings up several class drivers against the same port.
Three layers are involved:
Host-class driver callback API: every class driver — CDC ACM, CDC ECM, HID, UAC, MSC, UVC, vendor — registers a standard
usbh_class_driver_twith the core throughusbh_register_class(). There is one such registration per class, not one per device.Application-oriented callback API: each class reports its own events through its own callback type (
usbh_cdc_acm_cb_t,usbh_hid_usr_cb_t,usbh_uac_cb_t, …). Device-global events such as attach/detach come throughusbh_user_cb_t, passed tousbh_init().Application-oriented API: the per-class functions for starting and stopping transfers, setting formats, and so on. The application calls those directly; there is no composite-level indirection.
What the core does with several registered classes
When the device is enumerated, the core walks the configuration descriptor interface by interface and offers each interface to the registered class drivers in turn. A driver accepts an interface only if its id_table matches the interface’s class/subclass/protocol triple or its VID/PID. Consequences worth knowing:
A composite device enumerates into several independent class instances, one per matched interface group. For a CDC ECM + CDC ACM dongle, that means one ECM instance carrying Ethernet traffic and one ACM instance carrying AT commands.
The order in which you call the
usbh_xxx_init()functions determines registration order, and therefore which driver gets first refusal on a contested interface.A class that only works standalone — because it assumes it owns the whole configuration — will still match its interface in a composite device, but it may not find the descriptors it expects. Such a class documents the limitation; check its chapter before assuming it composes.
Application Callback API
The driver provides callback interfaces for the application layer, implemented by the application to respond to USB events and handle business logic. There are two levels, and there is no composite-specific callback type between them.
Host Application Layer Callback API
usbh_user_cb_treports device-global events of the port: attach, detach, and enumeration status changes. It is passed tousbh_init()and fires once per event regardless of how many class drivers are registered.Class Application Layer Callback API
Each class keeps its own callback type —
usbh_cdc_acm_cb_t,usbh_cdc_ecm_state_cb_t,usbh_hid_usr_cb_t,usbh_uac_cb_t,usbh_vendor_cb_t, and so on — passed to that class’susbh_xxx_init(). A composite application supplies one per class; they are not merged into a single structure.API
Description
init
Called when the class driver is initialized; used to set up application resources.
deinit
Called when the class driver is de-initialized; used to release application resources.
attach
Called when a device matching this class is attached; used to start transfers.
detach
Called when the device is detached; used to stop transfers and release per-device state.
setup
Called during the setup or data stage of a control transfer; used to handle class-specific requests.
transmitted
Called on completion of an IN transfer; used to asynchronously obtain the transfer status.
received
Called on completion of an OUT transfer; used to asynchronously obtain the received data.
The exact member set differs per class: MSC exposes little beyond
attach/detach, while UAC and CDC ACM implement most of the table.Class driver callbacks are not application callbacks
Distinguish the two structures a class hands the core.
usbh_class_driver_tis implemented by the class driver itself (attach,detach,process,sof,setup,completed) and registered withusbh_register_class(). The application never fills it in for a class the SDK provides. The callback structure above is the application-facing one, and that is the one a composite application supplies.
Because each class reports independently, a composite application typically keeps one state machine per class and lets them run concurrently. Coordination between them — for example, muting playback while a HID button is held — is application logic, not something the stack arbitrates.
Bringing up a composite host
A composite host application brings up several class drivers against one port, then starts the core once. The order matters at both ends.
static int composite_init_stack(void)
{
int ret;
/* 1. Core first: it owns the port and the message queue every class
driver talks to. */
ret = usbh_init(&usbh_cfg, &usbh_usr_cb);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "USBH init fail: %d", ret);
return ret;
}
/* 2. Register each class driver. Every one of these calls
usbh_register_class() internally. Registration order decides which
driver gets first refusal on a contested interface. */
ret = usbh_hid_init(&usbh_hid_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "HID init fail: %d", ret);
goto exit_usbh_init;
}
ret = usbh_uac_init(&usbh_uac_cfg, &uac_class_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "UAC init fail: %d", ret);
goto exit_hid_init;
}
/* 3. Start the core only after every class is registered, so
enumeration cannot run against a half-built stack. */
usbh_start();
return RTK_SUCCESS;
exit_hid_init:
usbh_hid_deinit();
exit_usbh_init:
usbh_deinit();
return ret;
}
Tearing down reverses the order, and follows the same rule as the device side: the core goes last, after every class has detached.
static void composite_deinit_stack(void)
{
/* Classes first: each unregisters itself and releases its pipes. */
usbh_uac_deinit();
usbh_hid_deinit();
/* Core last. */
usbh_deinit();
}
Two failure modes to avoid:
Registering a class after
usbh_start()races enumeration. The device may already have been matched by the time the new driver is in the table, in which case its interface stays unclaimed until the next replug.Calling an individual
usbh_xxx_deinit()while the core is running leaves the core dispatching to a driver that no longer exists. Tear down from the top.
The Kconfig side mirrors this: a composite example simply enables several class menus at once, for example CONFIG_USBH_HID_MENU and CONFIG_USBH_UAC_MENU. No composite-specific option exists.
HID + UAC Example
Bringing up and tearing down a two-class composite stack, with the error unwinding each step needs:
/**
* @brief Bring up the HID + UAC composite host stack
* @retval Status
*/
static int usbh_composite_init_stack(void)
{
int ret;
/* 1. Core first. */
ret = usbh_init(&usbh_cfg, &usbh_usr_cb);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "USBH init fail: %d\n", ret);
return ret;
}
/* 2. Register the HID class driver. usbh_hid_init() calls
usbh_register_class() internally. */
ret = usbh_hid_init(&usbh_hid_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "HID init fail: %d\n", ret);
goto exit_usbh_init;
}
/* 3. Register the UAC class driver against the same core. */
ret = usbh_uac_init(&usbh_uac_cfg, &uac_class_cfg);
if (ret != RTK_SUCCESS) {
RTK_LOGS(TAG, RTK_LOG_ERROR, "UAC init fail: %d\n", ret);
goto exit_hid_init;
}
/* 4. Start enumeration only after both classes are in the table. */
usbh_start();
return RTK_SUCCESS;
exit_hid_init:
usbh_hid_deinit();
exit_usbh_init:
usbh_deinit();
return ret;
}
/**
* @brief Tear the HID + UAC composite stack down
* @retval None
*/
static void usbh_composite_deinit_stack(void)
{
usbh_stop();
/* Classes first, in reverse registration order. */
usbh_uac_deinit();
usbh_hid_deinit();
/* Core last. */
usbh_deinit();
}
There is no usbh_composite_init() to call: the two classes register themselves, and the core matches each interface to whichever driver claims it.
API Reference
For detailed function prototypes and usage, please refer to the Driver API
Application Example
This section takes USB Composite (HID + UAC) as an example to introduce the complete application implementation and the method of running example application.
Application Design
This section walks through the complete development and design process of a composite host application, covering driver initialization, hotplug management, data flow and resource release.
Driver Initialization
Before bringing up the stack, define the core configuration and one callback set per class. Then initialize the core, register each class driver, and start enumeration.
Step Description:
Hardware Configuration: Configure USB speed modes (High Speed/Full Speed), interrupt priority, main task priority and tick source in
usbh_config_t.Callback Registration: Define
usbh_user_cb_tfor device-global events, plus one application callback per class using that class’s own type.Core Initialization: Call
usbh_init()to initialize the USB core driver.Class Driver Registration: Call each class’s
usbh_xxx_init(). Every one of them registers itself with the core; there is no composite class to initialize.Start: Call
usbh_start()once, after all classes are registered.
HID + UAC Example
static usbh_config_t usbh_cfg = {
.speed = USB_SPEED_FULL,
.ext_intr_enable = USBH_SOF_INTR,
.isr_priority = INT_PRI_MIDDLE,
.main_task_priority = USBH_UAC_MAIN_THREAD_PRIORITY,
.tick_source = USBH_SOF_TICK,
};
/* One callback set per class, each with that class's own type. */
static const usbh_uac_cb_t usbh_uac_cfg = {
.init = usbh_uac_cb_init,
.deinit = usbh_uac_cb_deinit,
.attached = usbh_uac_cb_attach,
.detached = usbh_uac_cb_detach,
.setup = usbh_uac_cb_setup,
};
static const usbh_hid_usr_cb_t usbh_hid_cfg = {
.attached = usbh_hid_cb_attach,
.detached = usbh_hid_cb_detach,
.report = usbh_hid_cb_report,
};
/* Device-global callbacks for the port itself. */
static const usbh_user_cb_t usbh_usr_cb = {
.process = usbh_cb_process,
};
int ret = 0;
/* 1. Bring up the host core. */
ret = usbh_init(&usbh_cfg, &usbh_usr_cb);
if (ret != RTK_SUCCESS) {
return;
}
/* 2. Register each class driver against the same core. There is no
usbh_composite_init(): each class registers itself. */
ret = usbh_hid_init(&usbh_hid_cfg);
if (ret != RTK_SUCCESS) {
usbh_deinit();
return;
}
ret = usbh_uac_init(&usbh_uac_cfg);
if (ret != RTK_SUCCESS) {
usbh_hid_deinit();
usbh_deinit();
return;
}
/* 3. Start enumeration only once every class is registered. */
usbh_start();
Hot-Plug Event Handling
As a host, the system must robustly handle the dynamic insertion and removal of USB devices. The SDK supports the hotplug mechanism by default.
Processing Logic:
Attach: The USB core detects the device, enumerates it and offers each interface to the registered class drivers. Each matching class runs its
attachcallback.Detach: The owning class’s
detachcallback fires. The application uses it to signal a worker thread, which tears the whole stack down and rebuilds it for the next connection.
HID + UAC Example
static rtos_sema_t usbh_detach_sema;
/* Detach arrives on one class's callback; the application uses it as the
trigger to rebuild the whole stack. */
static void usbh_uac_cb_detach(void)
{
RTK_LOGS(TAG, RTK_LOG_INFO, "UAC DETACH\n");
rtos_sema_give(usbh_detach_sema);
}
static const usbh_uac_cb_t usbh_uac_cfg = {
.detached = usbh_uac_cb_detach,
};
static void usbh_hotplug_thread(void *param)
{
UNUSED(param);
for (;;) {
if (rtos_sema_take(usbh_detach_sema, RTOS_SEMA_MAX_COUNT) == RTK_SUCCESS) {
/* Let the in-flight disconnect handling finish before tearing down. */
rtos_time_delay_ms(100);
/* 1. Tear the whole stack down, classes before the core. */
composite_deinit_stack();
/* 2. Rebuild it for the next connection. */
if (composite_init_stack() != RTK_SUCCESS) {
break;
}
RTK_LOGS(TAG, RTK_LOG_INFO, "Free heap: 0x%x\n", rtos_mem_get_free_heap_size());
}
}
rtos_task_delete(NULL);
}
Either class’s detached callback can serve as the trigger. Once one class reports detach the device is gone, so rebuilding the entire stack — rather than re-initializing a single class — is the simplest correct response.
Data Transfer Processing
Once the device is attached, the application drives each class through that class’s own APIs — usbh_uac_write() and usbh_uac_read() for audio, usbh_hid_send_report() for HID output. Incoming data arrives through the per-class callbacks registered at initialization (HID reports through the report callback, audio through the UAC callbacks), together with usbh_user_cb_t for device-global events.
There is no composite-level data path: each class owns its pipes and its transfers independently. For the detailed transmit and receive flows, refer to the corresponding chapter of each sub-function solution.
Driver Deinitialization
When USB functionality is no longer needed or the system is shutting down, release resources in the reverse order of loading: stop the port, release the class drivers, then the core.
HID + UAC Example
/* Stop the port first, then release the class drivers, then the core. */
usbh_stop();
/* Release each class driver in reverse registration order. */
usbh_uac_deinit();
usbh_hid_deinit();
/* Release the USB host core driver. */
usbh_deinit();
Operation method
This example demonstrates how to configure the Ameba development board as a host talking to a device that exposes both USB HID (Human Interface Device) and UAC (Audio Device Class) functions. The two class drivers are brought up side by side on one port; there is no separate composite layer.
When the development board is connected to a standard USB headset, the system will recognize two separate logical devices. The development board will send audio data to the headset, and if a button on the headset is pressed, host will recognize the command.
The example code path is: {SDK}/example/usb/usbh_composite_hid_uac. It provides provides a complete reference solution for developers to design custom composite products.
Configuration and Compilation
Compilation and Flashing
Execute the following commands in the SDK root directory to configure the environment, select the target SoC, compile the project, and then program the generated ‘Image’ file onto the development board.
# Initialize environment (required for every new terminal) source env.sh or env.bat(Windows system) # Select Target SoC (replace xxx with your specific SoCs) ameba.py soc xxx ameba.py build -a usbh_composite_hid_uac -p
Confirmation of Menuconfig configuration
If the compilation fails, please execute
ameba.py menuconfigand confirm that bothHIDandUACare selected under CONFIG USB. There is no composite-specific menu entry.- Choose `CONFIG USB --->`: [*] Enable USB USB Mode (Host) ---> [*] HID [*] UAC Select UAC Version (UAC 1.0) --->CONFIG_USB_OTG_EN_MENU=y CONFIG_USB_HOST_EN_MENU=y CONFIG_USBH_HID_MENU=y CONFIG_USBH_UAC_MENU=y
A composite host is configured by enabling several class menus at once. There is no composite-specific menu entry — the example’s
prj.confis simply the union of the classes it uses:The same pattern covers the other combinations shipped as examples:
CONFIG_USBH_CDC_ACM_MENU+CONFIG_USBH_CDC_ECM_MENUfor a cellular dongle, orCONFIG_USBH_UVC_MENU+CONFIG_USBH_UAC_MENUfor a camera with a microphone.
Verification
Host Startup
Reset the development board and observe the serial port log. The following startup information should be displayed:
[COMP-I] USBH HID+UAC comp demo start
Connect to Device
Connect the development board to a USB Type-C wired headphone using a USB cable.
Auto Play Test
The Ameba development board will recognize the headphones and automatically perform an audio playback test.
Audio Recording Test
If the headset includes a microphone, connect a speaker to the board’s audio output. Speak into the microphone, the captured audio will be played back in real time through the speaker.
HID Media Key Test
If the headset also has HID media keys, each press is printed on the serial port and acted on. Holding a key acts once, not repeatedly.
Key
Action
Volume Up / Down
Step the volume of the selected stream (see
AT+USBHHIDUAC=init) byCONFIG_USBH_COMP_HID_UAC_VOLUME_STEP(20 by default), asAT+USBHHIDUAC=vol,up|downdoesMute
Toggle mute of the selected stream, from the mute state the device reports
Play/Pause
Pause playback, press again to resume where it stopped
Stop
Stop playback, Play/Pause then restarts it from the beginning
Volume Up [COMP-I] Vol 70 Play/Pause [COMP-I] Play paused Play/Pause [COMP-I] Play resumed
A paused playback stops the ISOC OUT stream. A volume or mute key prints
Set vol fail/Set mute failwhen the device has no such control. A newly attached device starts playing; its mute state is left as the device keeps it.Shell Commands
Type the following AT commands on the LOGUART console. Parameters are comma separated; the command name is case-sensitive, the parameters are not.
AT+USBHHIDUAC=helpprints the usage, and every command ends withOKorERROR: <code>.Command
Description
AT+USBHHIDUAC=init[,<play|record>]Select the stream the following
mute/volact on, defaultplay.AT+USBHHIDUAC=mute,<0|1>Mute (
1) or unmute (0) the selected stream.AT+USBHHIDUAC=vol,<0..100|up|down>Set the volume of the selected stream in percent, or step it by 20. Each stream starts at 50.
AT+USBHHIDUAC=hotplugPower-cycle the device through the power-control GPIO, to exercise re-enumeration. Prints
Not supportunlessCONFIG_USBH_COMP_HID_UAC_GPIO_POWER_CTRLis set.mute/volneed an attached and set up device.