复合功能主机方案

概述

USB 复合设备 (Composite Device) 架构允许单一物理 USB 设备通过配置多个接口描述符 (Interface Descriptors) 或接口关联描述符 (IAD),在逻辑上呈现多种独立的功能。

Ameba 平台的 USB 主机协议栈已全面支持复合设备的枚举与驱动加载。系统能够智能解析设备的配置结构,并为不同的接口加载对应的类驱动程序。这使得 Ameba 能够通过一个 USB 端口,同时并发处理多种不同类型的业务流。

../../../_images/usb_host_composite_overview.svg

特性

  • 支持以下功能组合:

    • CDC ACM + CDC ECM

    • HID + UAC

  • 支持热插拔

  • 自动解析描述符,自适应速度模式

应用场景

作为 USB 主机,Ameba 可通过复合类驱动同时支持多种接口类的组合,能够与市面上复杂的 USB 复合设备进行交互,适用于多种物联网与多媒体应用场景,例如:

  • 蜂窝网络接入 (CDC ECM + CDC ACM):这是 4G/LTE Cat.1/Cat.4 模组及 USB Dongle 最常见的复合模式。Ameba 利用 CDC ECM (以太网) 接口进行高速互联网接入,广泛应用于工业 IoT 网关的数据回传或车载终端的联网功能;同时 CDC ACM (虚拟串口) 接口并行用于传输 AT 指令,实现对模组信号状态的实时监控和远程控制。

  • 交互式音频设备 (UAC + HID):这是带有物理控制按键的 USB 耳机、智能音箱或游戏手柄的典型应用。Ameba 利用 UAC (音频设备类) 接口处理高品质的语音通话、背景音乐或游戏音效流,同时通过 HID (人机接口设备) 接口实时响应设备上的物理按键(如音量调节、静音、媒体播放控制或手柄输入),实现音频体验与用户交互的无缝融合。

协议简介

USB 复合设备 (USB Composite Device) 规范定义了在 USB 规范框架下,通过单一物理接口同时承载多个独立功能接口的设备架构。 该机制允许主机将单一物理设备识别并枚举为多个逻辑功能的集合,实现不同功能类(如 HID、MSC、CDC 等)的并行处理与独立控制。 遵循该架构的常见设备包括无线键鼠接收器、带声卡的 USB 耳机及集成了存储与调试功能的工业设备等。

复合驱动仅负责顶层管理,具体子功能(如 HID 的报文格式、CDC 的通信协议)的数据处理需遵守其 对应的类协议规范,请参阅相关章节。

描述符结构

复合设备在遵循标准 USB 描述符(设备描述符、配置描述符)的基础上,通过在配置描述符集合中聚合多个接口描述符来实现多功能的定义。

单接口功能类

如果一个接口就代表了一个独立的功能,复合设备在聚合这种功能类的时候直接拼接使用。典型的单接口功能类有 HID 和 MSC。

以 HID 键盘 + HID 鼠标 复合设备为例,其描述符拓扑结构如下所示:

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 键盘 + HID 鼠标 复合设备和单独的键盘/鼠标设备对比,描述符特征如下:

描述符层级

普通设备(Single Function)

复合设备(Composite Device)

设备描述符

bDeviceClass 定义具体类型

bDeviceClass 通常为 0xEF (Misc) 或 0x00 (由接口定义)

配置描述符

1 个配置

1 个配置

接口描述符

1 个接口

有 2 个接口

端点描述符

归属于该接口

每个接口拥有独立的端点

备注

bDeviceClass = 0xEF:这是复合设备的标准标志,会触发主机驱动解析 IAD (可选)和配置描述符中的多个接口描述符,拆分出不同的设备功能,并创建这些逻辑子设备。 然后分别为 Interface 0 加载键盘驱动,为 Interface 1 加载鼠标驱动。

多接口功能类

如果一个逻辑功能需要占用多个接口才能完成,在使用这种功能类的时候必须加入 接口关联描述符 (Interface Association Descriptor, IAD) 将这些接口关联起来。

典型的多接口功能类

  • CDC (通信设备类): 通常需要 1 个控制接口 (CCI) + 1 个数据接口 (DCI)。

  • UVC (USB 视频类): 需要 1 个视频控制接口 (VC) + 1 个或多个视频流接口 (VS)。

  • UAC (USB 音频类): 需要 1 个音频控制接口 (AC) + 1 个或多个音频流接口 (AS)。

接口关联描述符(IAD)

IAD 向主机声明紧随其后的一组连续接口属于同一个功能,应由同一个驱动程序加载和管理。如果不加 IAD,主机有时候会把它们识别为两个独立的设备,或者驱动加载失败。

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 使用示例

../../../_images/usb_iad_descriptor.svg
  • 功能 1:设备类占用两个接口,为了让主机将其识别为单一的逻辑功能,必须使用 IAD 将这两个接口进行关联。

  • 功能 2:设备类使用一个独立的接口,不需要 IAD 关联。

类特定请求

USB 协议规范中并没有定义专属的“复合类请求”,其核心逻辑在于通过 USB 标准请求中的寻址机制,将 类特定请求 (Class-Specific Requests) 精确指向指定的接口。

在 SETUP 包的 bmRequestType 字段中,低 5 位(Bits 0..4)表示 Recipient(接收者)。

  • 普通单功能设备:控制请求通常是发给“整个设备”的,即将 Recipient 设置为 Device (00000)。

  • 复合设备:大量的控制请求必须精确地发给“特定的接口”,即将 Recipient 设置为 Interface (00001)。

以下是复合设备在控制请求处理上最显著的几个关键点:

字段

值

含义

复合设备中的体现

bmRequestType

0x21 / 0xA1

Class Request, Recipient=Interface

最常见。例如 CDC 设置波特率、HID 点亮键盘灯

wIndex

Interface Number

接口编号

当 Recipient 是接口时,wIndex 必须填入具体的接口号(如 0, 1, 2), 驱动必须根据这个值把请求分发给对应接口功能驱动处理

类驱动

复合设备指在单个物理 USB 设备中集成多个独立功能的设备。 主机协议栈的任务是解析该设备的配置描述符,为每个接口加载匹配的类驱动,从而把一台物理设备枚举成多个逻辑功能。 各功能随后独立工作——例如在传输网络数据的同时发送 AT 命令,或在播放音乐的同时接收按键输入。

本章介绍主机侧如何组织一个复合应用。

主机侧 没有复合类驱动。协议栈中没有一层"父类"去管理各子功能;相反,每个类驱动自行向 USB Core 注册,Core 在遍历设备配置描述符时,把每个接口交给声明匹配它的类驱动。因此所谓"复合主机",就是一个针对同一端口同时拉起多个类驱动的应用。

涉及三个层次:

  • 主机类驱动回调 API:每个类驱动(CDC ACM、CDC ECM、HID、UAC、MSC、UVC、Vendor)都通过 usbh_register_class() 向 Core 注册一个标准的 usbh_class_driver_t。注册粒度是"每个类一次",而非"每个设备一次"。

  • 面向应用的回调 API:每个类通过自己的回调类型上报事件(usbh_cdc_acm_cb_t、usbh_hid_usr_cb_t、usbh_uac_cb_t 等)。设备级事件(如插拔)则通过传给 usbh_init() 的 usbh_user_cb_t 上报。

  • 面向应用的 API:各类自身的函数,用于启停传输、设置格式等。应用直接调用它们,复合层不做转发。

Core 如何处理多个已注册的类

设备枚举时,Core 逐个接口遍历配置描述符,依次询问已注册的类驱动是否认领该接口。只有当驱动的 id_table 匹配接口的 class/subclass/protocol 三元组或 VID/PID 时,才会接受。由此产生的几点影响:

  • 复合设备会被枚举成若干独立的类实例,每个匹配到的接口组对应一个。以 CDC ECM + CDC ACM 的 4G Dongle 为例:一个 ECM 实例承载以太网数据,一个 ACM 实例承载 AT 命令。

  • usbh_xxx_init() 的调用顺序决定注册顺序,进而决定在接口存在竞争时哪个驱动优先认领。

  • 只能在独立模式下工作的类(因为它假定自己独占整个配置)在复合设备中依然会匹配到接口,但可能找不到预期的描述符。此类限制会在对应章节说明,组合使用前请先查阅。

应用层回调 API

驱动为应用层提供了回调函数接口,由应用层实现,以便应用代码能响应 USB 事件并处理业务逻辑。回调分为两级,二者之间没有复合层专属的回调类型。

  • 主机应用层回调 API

    usbh_user_cb_t 用于上报端口的设备级事件:插入、拔出以及枚举状态变化。它在 usbh_init() 中传入,无论注册了多少个类驱动,每个事件只触发一次。

  • 类应用层回调 API

    每个类保留自己的回调类型——usbh_cdc_acm_cb_t、usbh_cdc_ecm_state_cb_t、usbh_hid_usr_cb_t、usbh_uac_cb_t、usbh_vendor_cb_t 等——分别在对应的 usbh_xxx_init() 中传入。复合应用为每个类各传一份,不会合并成单一结构体。

    API

    描述

    init

    在类驱动初始化时被调用,用于初始化应用相关的资源

    deinit

    在类驱动注销时被调用,用于释放应用相关的资源

    attach

    匹配到该类的设备接入时被调用,用于启动传输

    detach

    设备断开时被调用,用于停止传输并释放每个设备的状态

    setup

    在控制传输的 setup 或 data 阶段被调用,用于处理类特定请求

    transmitted

    在 IN 传输完成时被调用,用于异步获取传输状态

    received

    在 OUT 传输完成时被调用,用于异步获取接收到的数据

    各类的成员集合略有差异:例如 MSC 除 attach/detach 外基本为空,而 UAC 与 CDC ACM 则实现了上表中的大部分。

  • 类驱动回调 ≠ 应用层回调

    注意区分类驱动交给 Core 的两个结构体。usbh_class_driver_t 由类驱动自身实现(attach、detach、process、sof、setup、completed),并通过 usbh_register_class() 注册;对于 SDK 已提供的类,应用层无需填充它。上面讲的是面向应用层的回调结构体,复合应用提供的是这一种。

由于各类独立上报,复合应用通常为每个类维护一个状态机并发运行。它们之间的协调——例如按住 HID 按键时暂停播放——属于应用层逻辑,协议栈不做仲裁。

下面以 HID + UAC 为例展示两级回调的实际用法:

/* HID user callback interface. */
typedef struct {
    int  (*init)(void);                       /**< Called on initialization */
    void (*deinit)(void);                     /**< Called on de-initialization */
    void (*attached)(void);                   /**< Called when a HID device is attached */
    void (*detached)(void);                   /**< Called when a HID device is detached */
    void (*setup)(void);                      /**< Called during the setup phase */
    void (*report)(usbh_hid_event_t *event);  /**< Called for every INTR IN report received, see usbh_hid_event_t */
} usbh_hid_usr_cb_t;

/* UAC user callback interface. */
typedef struct {
    int  (*init)(void);                        /**< Called once when the UAC driver is initialized */
    void (*deinit)(void);                      /**< Called once when the UAC driver is de-initialized */
    void (*attached)(void);                    /**< Called when a UAC device is enumerated and pipes are opened */
    void (*detached)(void);                    /**< Called when a UAC device is removed */
    void (*setup)(void);                       /**< Called on each USB Setup-stage transaction */
    void (*transmitted)(usbh_urb_state_t state); /**< Reserved: registered but not currently invoked */
    void (*received)(u8 *buf, u32 len);        /**< Reserved: registered but not currently invoked */
} usbh_uac_cb_t;
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,
};

static const usbh_uac_cb_t usbh_uac_cfg = {
    .attached  = usbh_uac_cb_attach,
    .detached  = usbh_uac_cb_detach,
    .setup     = usbh_uac_cb_setup,
};

两者分别直接传给各自的类初始化接口,没有复合层包装。

需要注意,UAC 回调中的 transmitted 与 received 目前只做声明、驱动尚未调用;UAC 数据实际通过 usbh_uac_write() 与 usbh_uac_read() 收发,而不是经这两个回调。

复合主机的启动流程

复合主机应用在同一端口上拉起多个类驱动,然后启动一次 Core。两端的顺序都很关键。

static int composite_init_stack(void)
{
   int ret;

   /* 1. 先初始化 Core:它持有端口,以及所有类驱动通信所用的消息队列。 */
   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. 逐个注册类驱动。下面每个调用内部都会执行 usbh_register_class()。
         注册顺序决定接口存在竞争时哪个驱动优先认领。 */
   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. 所有类注册完成后才启动 Core,确保枚举不会跑在半成品协议栈上。 */
   usbh_start();

   return RTK_SUCCESS;

exit_hid_init:
   usbh_hid_deinit();
exit_usbh_init:
   usbh_deinit();
   return ret;
}

卸载按相反顺序进行,规则与设备侧一致:所有类都解绑之后,Core 最后释放。

static void composite_deinit_stack(void)
{
   /* 先卸载各类:它们各自注销并释放管道。 */
   usbh_uac_deinit();
   usbh_hid_deinit();

   /* Core 最后释放。 */
   usbh_deinit();
}

需要避免的两种错误做法:

  • 在 usbh_start() 之后才注册类,会与枚举过程竞争。新驱动进入表项时设备可能已被匹配完毕,此时它的接口会一直无人认领,直到下次重新插拔。

  • 在 Core 运行期间单独调用某个 usbh_xxx_deinit(),会让 Core 继续向一个已不存在的驱动分发事件。应从上层往下卸载。

Kconfig 侧也体现了这一点:复合示例只需同时打开多个类菜单,例如 CONFIG_USBH_HID_MENU 与 CONFIG_USBH_UAC_MENU,并不存在复合专属的配置项。

HID + UAC 示例

下面是一个双类复合协议栈的完整加载与卸载流程,含每步失败时的回滚处理:

/**
* @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();
}

这里没有 usbh_composite_init() 可调:两个类各自完成注册,由 Core 把每个接口交给声明匹配它的驱动。

API 参考

详细的函数原型与用法请参考 驱动 API

应用示例

本节以 USB Composite (HID + UAC) 为例,介绍完整的应用实现和运行测试的方式。

应用设计

本节详细介绍复合主机应用的完整开发设计流程,涵盖加载驱动、热插拔管理、数据收发以及资源释放等核心环节。

加载驱动

拉取协议栈之前,先定义核心配置与每个类各自的回调集;然后初始化核心、注册各类驱动、最后启动枚举。

步骤说明:

  • 硬件配置:在 usbh_config_t 中配置 USB 速度模式(High Speed/Full Speed)、中断优先级、主任务优先级与 tick 源。

  • 回调注册:定义 usbh_user_cb_t 处理设备级事件,并为每个类按该类自己的类型定义一份应用回调。

  • 加载核心驱动:调用 usbh_init() 加载 USB 核心驱动。

  • 注册类驱动:调用各类的 usbh_xxx_init()。每个调用都会自行向 Core 注册,不存在需要初始化的复合类。

  • 启动:所有类注册完成后,调用一次 usbh_start()。

HID + UAC 示例

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();

热插拔事件处理

作为主机,系统必须能够健壮地处理 USB 设备的动态插入与移除,SDK 默认支持热插拔机制。

处理逻辑:

  • 设备插入 (Attach):USB 核心检测到设备,完成枚举并把每个接口提供给已注册的类驱动,匹配到的类执行各自的 attach 回调。

  • 设备拔出 (Detach):对应类的 detach 回调被触发,应用据此通知工作线程,由该线程卸载整个协议栈并为下次连接重建。

HID + UAC 示例

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);
}

任选一个类的 detached 回调作为触发点即可。只要有一个类报告拔出,设备就已经不在了,因此直接重建整个协议栈——而不是只重新初始化某一个类——是最简单也最稳妥的处理。 数据收发处理 ++++++++++++++++++++++++++++

设备连接后,应用通过各类自己的 API 驱动对应功能——音频使用 usbh_uac_write() 与 usbh_uac_read(),HID 输出使用 usbh_hid_send_report(),等等。 接收到的数据通过初始化时注册的各类回调上报(HID 报文经 report 回调,音频经 UAC 回调),设备级事件则通过 usbh_user_cb_t 上报。

复合层不存在统一的数据通路:每个类独立持有自己的管道与传输。详细的数据收发过程请参考各子功能方案的对应章节。

卸载驱动

在不再需要 USB 功能或系统关机时,按加载的反序释放资源:先停止端口,再释放各类驱动,最后释放核心。

HID + UAC 示例

/* 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();

运行方式

该示例演示了如何通过复合主机协议栈,将 Ameba 开发板配置为同时具备 USB HID (人机接口设备) 与 UAC (音频设备类) 功能的主机。

当开发板连接至标准 USB 耳机时,系统将识别出两个独立的逻辑设备。开发板会将音频数据发送到耳机,如果耳机上的按钮被按下,主机将识别该命令。

该示例路径: {SDK}/example/usb/usbh_composite_hid_uac ,可为开发者设计自定义 Composite 产品提供完整的参考方案。

配置与编译

  • 编译与烧录

    在 SDK 根目录下执行以下命令以配置环境,选择目标 SoC,编译工程,然后将生成的 Image 文件烧录至开发板。

    # 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
    
  • Menuconfig 配置确认

    若编译失败,请执行 ameba.py menuconfig,确认在 CONFIG USB 下同时选中 HID 与 UAC。复合本身没有独立的配置项。

    - 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
    

    复合主机通过同时开启多个类菜单来配置。并不存在复合专属的菜单项——示例的 prj.conf 就是其所用各类配置的并集。

    其他示例组合遵循同样的模式:4G Dongle 用 CONFIG_USBH_CDC_ACM_MENU + CONFIG_USBH_CDC_ECM_MENU,带麦克风的摄像头用 CONFIG_USBH_UVC_MENU + CONFIG_USBH_UAC_MENU。

结果验证

  • 启动设备

    重启开发板,观察串口日志,应显示如下启动信息:

    [COMP-I] USBH HID+UAC comp demo start
    
  • 连接主机

    使用 USB 线缆将开发板连接 USB Type-C 有线耳机。

  • 自动播放测试

    Ameba 开发板将识别出耳机,并自动进行音频播放测试。

  • 录音测试

    若耳机带有麦克风,将扬声器连接至开发板音频输出。对麦克风讲话,采集到的数据将通过扬声器实时播放。

  • HID 媒体按键测试

    若耳机还带有 HID 媒体按键,每次按键都会在串口打印并执行相应动作。长按按键只执行一次,不会重复触发。

    按键

    动作

    Volume Up / Down

    按 CONFIG_USBH_COMP_HID_UAC_VOLUME_STEP (默认 20)步进调节当前所选音频流(见 AT+USBHHIDUAC=init)的音量,效果与 AT+USBHHIDUAC=vol,up|down 相同

    Mute

    以设备上报的静音状态为基础,切换当前所选音频流的静音状态

    Play/Pause

    暂停播放,再次按下从暂停处继续播放

    Stop

    停止播放,之后按 Play/Pause 从头开始播放

    Volume Up
    [COMP-I] Vol 70
    Play/Pause
    [COMP-I] Play paused
    Play/Pause
    [COMP-I] Play resumed
    

    暂停播放会停止 ISOC OUT 数据流。若设备不支持对应控制,音量或静音按键会打印 Set vol fail / Set mute fail。新接入的设备会自动开始播放,其静音状态保持设备自身的状态。

  • Shell 命令

    在 LOGUART 控制台输入以下 AT 命令。参数以逗号分隔;命令名区分大小写,参数不区分。AT+USBHHIDUAC=help 可打印用法,每条命令结束时输出 OK 或 ERROR: <code>。

    命令

    说明

    AT+USBHHIDUAC=init[,<play|record>]

    选择后续 mute/vol 命令作用的音频流,默认 play。

    AT+USBHHIDUAC=mute,<0|1>

    对所选音频流静音(1)或取消静音(0)。

    AT+USBHHIDUAC=vol,<0..100|up|down>

    以百分比设置所选音频流的音量,或按 20 步进调节。各音频流初始音量为 50。

    AT+USBHHIDUAC=hotplug

    通过电源控制 GPIO 对设备重新上电,以测试重新枚举。未设置 CONFIG_USBH_COMP_HID_UAC_GPIO_POWER_CTRL 时打印 Not support。

    mute/vol 命令需设备已连接并完成 setup。