DRD 解决方案

概述

USB DRD (Dual-Role Device) 是一种允许 USB 接口在主机与设备角色之间进行动态切换的功能。它打破了传统 USB 连接中角色固定的限制,使设备能够根据连接对象或应用需求灵活改变自身属性。

Ameba 能够软件控制切换角色,从而通过单一物理接口满足系统对扩展性与兼容性的双重需求。

DRD 设备模式:

../../_images/usb_drd_device_overview.svg

DRD 主机模式:

../../_images/usb_drd_host_overview.svg

应用场景

DRD 提升了设备灵活性,Ameba 可调整工作模式,通过单一物理接口适应适应多样化的的交互与扩展需求,例如:

  • 智能行车记录仪/运动相机:在主机模式下,Ameba 主动将 GPS 模块轨迹写入外接 U 盘;当插入 PC 时切换为设备模式,模拟成大容量存储设备(MSC),供用户直接拷贝导出文件。

  • 工业手持数据终端:在主机模式下,Ameba 连接扫码枪或红外传感器(HID/CDC)采集现场数据;当回到办公室连接 PC 时切换为设备模式,模拟成串口或 U 盘,将采集的日志与报表批量上传至管理系统。

  • 车载 CarPlay 互联终端:Ameba 刚上电时处于设备模式,完成必要的初始验证流程;验证通过后切换为主机模式,主动连接车机设备,建立 NCM 和 iAP2 双协议通信以实现 CarPlay 全功能。

协议简介

在 USB 应用中,实现主机与设备角色的切换通常采用以下两种方法:

  • 基于 USB OTG (On-The-Go) 协议的硬件切换

    依赖物理线缆的 ID 引脚状态来判定角色。该机制包含以下具体协议:

    • SRP (Session Request Protocol): 允许从设备请求主机开启 VBUS 电源。

    • HNP (Host Negotiation Protocol): 允许连接双方通过协商临时交换 Host/Device 角色。

  • 软件控制的 USB DRD 切换

    不依赖物理连接状态,而是由软件直接修改控制器寄存器来进行角色变更。此方式虽不属于标准 USB 传输协议,但具有极高的实用价值。

DRD 软件切换对比 OTG 的核心优势

尽管硬件自动检测具备基础易用性,但在实现复杂、高可靠性的系统时, DRD 软件切换 展现出不可替代的优势:

  • 摆脱硬件依赖与适配 Type-C

    • 不依赖 ID 引脚,规避了因硬件设计缺陷或物理损坏导致的失效。

    • 特别是在 Type-C 规范中,OTG 定义的 HNP 协议已被弃用,且无传统 ID 引脚,软件切换成为更符合现代接口规范的方案。

  • 灵活的软件切换

    • 支持在不更换物理线缆的情况下动态改变角色,可选择应用主动切换,或外部按键、事件或消息请求等多种方式触发切换。

    • 极大提高了系统的容错率、可维护性以及自动化测试效率。

类驱动

USB DRD 软件控制角色切换本质上属于应用层的功能,主要涉及控制器工作模式的变更,本身并不需要特定的“DRD 类驱动”, 其实质是根据当前的 USB 角色,动态加载相应的标准类驱动。关于 DRD 不同角色下使用的类驱动,请参阅对应设备/主机方案的类驱动章节。

应用示例

应用设计

本节介绍 USB DRD 应用示例的设计。该示例将多个 USB 示例编译进同一个固件,并支持在运行时任意切换:设备 <-> 主机、主机 <-> 主机、设备 <-> 设备。同一时刻只有一个应用占用 USB 控制器。

角色切换在应用层完成,不需要专门的 DRD 类驱动。从一个应用切换到另一个应用的过程可概括为:

  • 停止当前应用:卸载其类驱动及 USB 设备或主机核心驱动,并释放其占用的全部资源

  • 等待一段时间,让对端识别到断开

  • 启动下一个应用:加载 USB 设备或主机核心驱动及其类驱动

应用管理器

每个内置应用由示例应用表中的一个 usb_app_t 条目描述,包括名称、角色和启动/停止入口:

typedef struct {
    const char *name;                       /* Example directory name, e.g. "usbd_cdc_acm" */
    int (*start)(void);                     /* Bring the app up, task context only */
    int (*stop)(void);                      /* Tear it down completely, task context only, idempotent */
    u8 role;                                /* USB_APP_ROLE_DEVICE or USB_APP_ROLE_HOST */
} usb_app_t;

start/stop 入口即各独立示例导出的 example_<app>_start()/example_<app>_stop() 函数,例如 example_usbd_msc_start() 和 example_usbd_msc_stop()。它们与独立示例走相同的代码路径,因此应用启动后的行为与对应的独立示例一致。

应用管理器运行在独立线程中,串行处理 AT+USBAPP 命令发起的启动、停止和切换请求。每个应用都有以其名称命名的专属 AT 命令 AT+USB<D|H><APP>,仅在该应用运行时有效。

备注

SDK 示例通过 AT 命令进行角色切换,主要是为了便于测试。客户实际开发应用时,可根据设计需求在应用程序中通过其他合适的方式触发切换,例如由 USB 控制消息、Wi-Fi 指令或 GPIO 事件驱动。

应用的启动与停止

启动时按独立示例相同的方式加载 USB 协议栈。以 usbd_msc 和 usbh_msc 为例:

  • MSC 设备启动:定义配置结构体和回调函数,随后调用初始化接口,对底层存储初始化并加载 USB 设备核心驱动及 MSC 类驱动。

    static usbd_config_t usbd_msc_cfg = {
        .speed = CONFIG_USBD_MSC_SPEED,
        .isr_priority = INT_PRI_MIDDLE,
    };
    
    static usbd_msc_cb_t usbd_msc_cb = {
        .status_changed = usbd_msc_cb_status_changed  /* USB status change callback. */
    };
    
    int ret = 0;
    ret = usbd_msc_disk_init();    /* Initializes the underlying storage disk. */
    if (ret != RTK_SUCCESS) {
        return;
    }
    
    ret = usbd_init(&usbd_msc_cfg);     /* Initialize USB device core driver with configuration. */
    if (ret != RTK_SUCCESS) {
        usbd_msc_disk_deinit();
        return;
    }
    
    ret = usbd_msc_init(&usbd_msc_cb);  /* Initializes the MSC device class. */
    if (ret != RTK_SUCCESS) {
        usbd_msc_disk_deinit();
        usbd_deinit();
        return;
    }
    
  • MSC 主机启动:定义配置结构体和回调函数,随后调用初始化接口,加载 USB 主机核心驱动及 MSC 类驱动。

    static usbh_config_t usbh_cfg = {
      .speed = USB_SPEED_HIGH,
      .ext_intr_enable = USBH_SOF_INTR,
      .isr_priority = INT_PRI_MIDDLE,
      .main_task_priority = 3U,
      .tick_source = USBH_SOF_TICK,
      }
    
    static usbh_msc_cb_t usbh_msc_usr_cb = {
      .attach = usbh_msc_cb_attach,                  /* USB device attach callback */
      .setup = usbh_msc_cb_setup,                    /* USB device setup done, indicate that device is ready for bulk transfer */
    };
    
    static const usbh_msc_config_t usbh_msc_cfg = {
      .buf_size = 0,                                 /* READ(10)/WRITE(10) bounce buffer size, 0 takes USBH_MSC_DEFAULT_BUF_SIZE */
    };
    
    static usbh_user_cb_t usbh_usr_cb = {
      .process = usbh_msc_cb_process
    };
    
    int ret = 0;
    ret = usbh_init(&usbh_cfg, &usbh_usr_cb);   /* Initialize USB host core driver with configuration and user callback. */
    if (ret != RTK_SUCCESS) {
        return;
    }
    
    ret = usbh_msc_init(&usbh_msc_usr_cb, &usbh_msc_cfg);  /* Initializes the MSC host class with MSC class user callback and configuration. */
    if (ret != RTK_SUCCESS) {
        usbd_msc_disk_deinit();
        return;
    }
    

停止时按启动的反序释放资源,且不得遗留任何资源,以保证反复切换后可用堆内存保持稳定:

  • MSC 设备停止:

    /* De-initializes the underlying storage disk. */
    usbd_msc_disk_deinit();
    /* Deinitialize MSC device class driver. */
    usbd_msc_deinit();
    /* Deinitialize USB device core driver. */
    usbd_deinit();
    
  • MSC 主机停止:

    /* Deinitialize MSC host class driver. */
    usbh_msc_deinit();
    /* Deinitialize USB host core driver. */
    usbh_deinit();
    

应用工作线程的生命周期由 usb_app.h 中的 usb_app_ctx_t 管理:停止时先通知各工作线程退出,对每个线程最多等待 USB_APP_JOIN_TIMEOUT_MS,确认全部退出后才释放它们可能访问的资源。若有工作线程未能按时退出,该应用保留其资源,应用管理器在开发板复位前拒绝再启动任何应用。

备注

运行方式

本节介绍一个 USB DRD(Dual Role Device)应用示例。该示例将多个 USB 示例编译进同一个固件,并通过 AT+USBAPP 命令在运行时切换。同一时刻只有一个应用占用 USB 控制器。

内置的应用即示例 prj.conf 中已使能其类驱动的各个示例。默认只使能 usbd_msc 和 usbh_msc,其余可用应用在 prj.conf 中以注释形式列出,取消对应分组的注释即可加入该应用。当前支持的应用及其对端请参考 {SDK}/example/usb/usb_drd/README.md。

每个应用的行为与对应的独立示例一致,其测试步骤和预期日志请参考对应的设备或主机方案。每个应用都有以其名称命名的专属 AT 命令 AT+USB<D|H><APP>,各应用之间不会共用命令。该命令仅在对应应用运行时有效,否则打印 Not running 并以 ERROR 结束。

备注

  • 同一个固件中最多只能编入一个网络类应用(CDC ECM/NCM 设备或主机、4G 模块、Wi-Fi 桥接等),否则编译报错。

  • Kconfig 中互斥的类驱动选项在同一个固件中只能取一个值:设备 HID 类型、UAC 版本和 MSC 存储介质均以 prj.conf 中的选择为准。

该示例代码路径: {SDK}/example/usb/usb_drd,可为开发者设计自定义 USB DRD 产品提供完整的设计参考。

配置与编译

  • 编译与烧录

    在 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 usb_drd -p
    
  • Menuconfig 配置

    示例的 prj.conf 选择了 USB Mode (DRD),并按应用分组列出各自的选项及注释,编译该示例时会自动应用。取消某个分组的注释即可加入该应用,注释掉则将其移除。默认配置如下:

    - Choose `CONFIG USB --->`:
    
        [*] Enable USB
            USB Mode (DRD)  --->
            ()  Auto-start USB app
    
            *** USB Device Class ***
        [*] MSC
            Select storage media (SD Card (SD mode))  --->
    
            *** USB Host Class ***
        [*] MSC
    

    CONFIG_USB_APP_DEFAULT (CONFIG USB > Auto-start USB app)指定上电后自动启动的应用,例如 "usbd_cdc_acm";留空则不自动启动,等待 AT+USBAPP=start。

  • 硬件配置

    主机类应用需要主机端口提供 VBUS。部分 Ameba 开发板需要硬件改板才能支持 USB 主机模式,详情请参考 EVB 用户指南。

结果验证

本小节以默认的 usbd_msc 和 usbh_msc 应用为例进行演示,MSC 设备使用 SD 卡 作为存储介质。

  • 启动设备

    将 SD 卡插入开发板的 SD 卡槽并重启开发板,观察串口日志,应列出内置的应用:

    [DRD-I] USB DRD demo start
    [APP-I] Apps (2):
      usbd_msc device
      usbh_msc host
    
  • 命令

    在 LOGUART 控制台通过以下 AT 命令管理应用,每条命令结束时输出 OK 或 ERROR: <code>。

    命令

    说明

    AT+USBAPP=list

    列出内置的应用,* 标识正在运行的应用。

    AT+USBAPP=start,<app>

    启动一个应用,要求 USB 控制器空闲。

    AT+USBAPP=stop

    停止正在运行的应用,并释放其占用的全部资源。

    AT+USBAPP=switch,<app>[,<ms>]

    停止正在运行的应用,等待 ms 毫秒(0~10000,默认 500)以便对端识别到断开,然后启动 app。

    AT+USBAPP=status

    打印正在运行的应用、切换次数和可用堆内存。

    AT+USBAPP=help

    打印用法。

  • MSC 设备模式测试

    执行 AT+USBAPP=start,usbd_msc,并使用 USB 线将开发板连接至 PC:

    [MSC-I] USBD MSC demo start
    [MSC-I] Disk init
    [USBD-A] INIT
    [MSC-I] Init
    [APP-I] Start usbd_msc (device), heap 0x...
    [MSC-I] ATTACHED
    

    PC 的文件管理器中会自动出现一个新的可移动磁盘,对其进行文件读写操作以验证数据传输。

  • 角色切换

    执行 AT+USBAPP=switch,usbh_msc 停止 MSC 设备并启动 MSC 主机。启动和停止时会打印可用堆内存,反复切换后该值应保持稳定:

    [MSC-I] USBD MSC demo stop
    [APP-I] Stop usbd_msc, heap 0x...->0x...
    [MSC-I] USBH MSC demo start
    [MSC-I] Wait for device attach...
    [APP-I] Start usbh_msc (host), heap 0x...
    
  • MSC 主机模式测试

    断开开发板与 PC 的 USB 连接,将格式化为 FATFS 的 U 盘接入开发板。开发板识别 MSC 设备后进行读写性能测试:

    [USBH-A] Dev attach, speed 0
    [USBH-A] PID 6545
    [USBH-A] VID 0930
    [USBH-A] Addr 1
    [USBH-A] MFG: TOSHIBA
    [USBH-A] PROD: TransMemory
    [USBH-A] SN: C03FD5F7715FE3417000DE76
    [USBH-A] Enum done, 1 cfg
    [USBH-A] Switch to itf: 0
    [USBH-A] Class: 0x08
    [USBH-A] SubClass: 0x06
    [USBH-A] Protocol: 0x50
    [MSC-I] ATTACH
    [MSC-I] Max lun 1
    [MSC-I] Lun 0
    [MSC-I] SETUP
    [MSC-I] Device ready
    [MSC-I] FatFS USB W/R performance test start, free heap: 0x...
    [MSC-I] Open file: 0:/TEST0.DAT
    [MSC-I] W test: size 512, round 20...
    [MSC-I] W rate 204.0 KB/s for 20 round @ 49 ms
    [MSC-I] R test: size = 512 round = 20...
    [MSC-I] R rate 476.1 KB/s for 20 round @ 21 ms
    ...
    [MSC-I] File 0:/TEST0.DAT done
    ...
    [MSC-I] FatFS USB W/R performance test done, free heap: 0x...
    

备注

若停止应用或启动失败后的回滚操作超时(应用线程未能按时退出),该应用将保留其资源,AT+USBAPP=status 显示 broken,在开发板复位前无法再启动任何应用。