USB Device ADB (Android Debug Bridge) 示例

📁 源码位置: samples/subsys/usb/device/adb 查看源码

功能说明

演示如何将设备实现为 USB ADB (Android Debug Bridge) 设备，支持通过 ADB 协议与主机进行通信。本示例基于 TinyUSB 库和 ADB 应用类，实现了 ADB 设备枚举和基本命令支持，包括 adb shell、adb push、adb pull 和 adb ls。

ADB 是 Android 平台常用的调试工具，本示例允许主机通过标准的 ADB 命令与设备进行交互，执行 shell 命令、传输文件等操作。

硬件连接

1. USB 连接: 将设备通过 USB 线连接到主机（PC/笔记本电脑）

2. 存储设备（可选）: 如果使用 adb push/pull 功能，需要配置文件系统（如 SD 卡）

示例内容

1. 初始化文件系统: 初始化 LSFS 文件系统（用于 adb push/pull 操作）

2. 初始化 USB 设备: 配置 USB 硬件（时钟、PHY、设备模式）并初始化 TinyUSB

3. 初始化 ADB 功能:

   • adb_init(): 初始化 ADB 设备核心功能

   • adb_shell_init(): 初始化 ADB Shell 功能（如果 CONFIG_ADB_SHELL=y）

   • adb_sync_init(): 初始化 ADB Sync 功能（如果 CONFIG_ADB_SYNC=y）

4. USB 设备任务: 在 FreeRTOS 任务中运行 tud_task() 处理 USB 事件

5. 内存监控: 主循环中定期打印堆内存使用情况（用于调试）

编译

重要提示：在编译前，请先确认您使用的开发板型号。SDK 目前支持以下开发板：

• arcs_evb - ARCS EVB 评估板

• arcs_mini - ARCS Mini 开发板

根据您的开发板型号，选择对应的编译命令：

在示例目录下执行编译:

# 使用 arcs_evb 开发板
./build.sh -C -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -DBOARD=arcs_mini

Note

如果在 SDK 根目录执行，需要指定示例路径:

# 使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

# 或使用 arcs_mini 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_mini

Note

确保已安装对应的工具链。

烧录

编译完成后，使用 SDK tools 目录下的 cskburn 工具烧录固件:

./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs

Note

烧录参数说明：

• -s /dev/ttyUSB0：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是 /dev/ttyUSB0 或 /dev/ttyACM0 - 可通过 ls /dev/tty* 命令查看可用串口设备 - 不同开发板或 USB 转串口芯片可能使用不同的设备名

• -b 3000000：烧录波特率（3Mbps）

• 0x0：烧录起始地址

• build/arcs.bin：编译生成的固件路径

• -C arcs：芯片类型

注意事项：

• 确保开发板已正确连接到电脑

• 如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口

预期输出

********Arcs SDK 0.1.0 @ v0.0.23.temp.docs-96-gf56c5084660d********
Running on hart-id: 1
I/elog            [1034:42:44.159 1 elog_async] EasyLogger V2.2.99 is initialize success.
[I][sample] USB CDC Echo example starting...
[I][sample] TinyUSB initialized
[I][sample] USB ADB example running...
[I][sample] [Start]     [End]  [Alloc/BK]  [Free/BK] [Total/BK] [MaxFree/BK] [Alloc/B]  [Free/B]  [MinFree/B]
[I][sample] 0x...       0x...  ...         ...       ...        ...          ...        ...       ...

说明：

• 输出开头包含系统启动信息和日志系统初始化信息

• ADB 设备初始化后显示 “TinyUSB initialized”

• 主循环中定期显示堆内存使用情况

• 当主机通过 ADB 连接时，设备会响应 ADB 协议消息

• 使用 adb devices 命令可以在主机上看到设备列表

主机端使用示例

查看设备

adb devices

输出示例：

List of devices attached
XXXXXXXX        device

ADB Shell

adb shell

进入设备的 shell 环境，可以执行命令。

ADB Push（上传文件到设备）

adb push local_file.txt /SD:/adb/remote_file.txt

说明：

• 如果不使用绝对路径，文件会被推送到 CONFIG_ADB_PUSH_PULL_DEFAULT_ROOT 定义的路径（默认 /SD:/adb/）

• 示例速率：约 3.8 MB/s

ADB Pull（从设备下载文件）

adb pull /SD:/adb/remote_file.txt local_file.txt

说明：

• 如果不使用绝对路径，文件会从 CONFIG_ADB_PUSH_PULL_DEFAULT_ROOT 定义的路径拉取

• 示例速率：约 3.9 MB/s

ADB LS（列出目录）

adb shell ls /SD:/adb/

核心 API

API	说明
adb_init()	初始化 ADB 设备核心功能
adb_shell_init()	初始化 ADB Shell 功能
adb_sync_init()	初始化 ADB Sync 功能（文件传输）
tud_init()	初始化 TinyUSB 设备栈
tud_task()	处理 USB 设备事件（必须定期调用）
tud_connect() / tud_disconnect()	软件连接/断开 USB

关键代码

/* USB 任务 */
void usb_task(void *arg)
{
    // 配置 USB 硬件
    IP_SYSCTRL->REG_PERI_CLK_CFG6.bit.ENA_USB_CLK = 0x01;
    IP_CMN_SYS->REG_USB_CTRL1.bit.USBPHY_OUTCLKSEL = 0x1;
    IP_CMN_SYS->REG_USB_CTRL1.bit.USBC_CFG_IDDIG = 0x1;   // Config "B" device
    IP_CMN_SYS->REG_USB_CTRL1.bit.UTMI_DATABUS16_8 = 0x1; // 16bit mode
    
    // 初始化 ADB
    adb_init();
    
#if CONFIG_ADB_SHELL
    adb_shell_init();
#endif

#if CONFIG_ADB_SYNC
    adb_sync_init();
#endif

    // 初始化 TinyUSB
    tud_disconnect();
    tusb_init();
    tud_connect();
    
    // 处理 USB 事件
    while (1) {
        tud_task();
    }
}

/* 主函数 */
int main(int argc, char **argv)
{
    // 初始化文件系统
    extern int test_lsfs_init(void);
    test_lsfs_init();
    
    // 创建 USB 任务
    xTaskCreate(usb_task, "usb_task", 1024 * 1, NULL, 5, NULL);
    
    // 主循环（打印内存信息）
    while (1) {
        LOGI("USB ADB example running...\n");
        heap_caps_travel(heap_travel_cb1);
        vTaskDelay(1000);
    }
    
    return 0;
}

ADB 协议说明

ADB 使用基于消息的协议，主要消息类型：

• A_CNXN: 连接消息，设备向主机发送设备信息

• A_OPEN: 打开服务（如 shell、sync）

• A_OKAY: 确认消息

• A_CLSE: 关闭服务

• A_WRTE: 写入数据

• A_SYNC: 同步消息（用于文件传输）

配置说明

必需配置

• CONFIG_TINY_USB=y: 启用 TinyUSB 库

• CONFIG_TINY_USB_USE_CUSTOM_CONFIG_FILE=y: 使用自定义 TinyUSB 配置文件

• CONFIG_TUSB_APP_CLASS=y: 启用 TinyUSB 应用类支持

• CONFIG_ADB_SYNC=y: 启用 ADB Sync 功能（文件传输）

• CONFIG_ADB_SHELL=y: 启用 ADB Shell 功能

文件系统配置（用于 ADB Sync）

• CONFIG_FILE_SYSTEM=y: 启用文件系统

• CONFIG_FATFS_FILESYSTEM=y: 启用 FATFS 文件系统

• CONFIG_DISK_DRIVER=y: 启用磁盘驱动

• CONFIG_DISK_DRIVER_SDMMC=y: 启用 SDMMC 磁盘驱动

• CONFIG_LSFS=y: 启用 LSFS 抽象文件系统

• CONFIG_LSFS_FAT=y: 启用 LSFS FAT 支持

ADB 配置选项

• CONFIG_ADB_PUSH_PULL_DEFAULT_ROOT: ADB push/pull 的默认根目录（默认 /SD:/adb/）

• CONFIG_ADB_MAX_PAYLOAD_SIZE: ADB 最大载荷大小（默认 51200 字节）

• CONFIG_ADB_SHELL_BUFFER_SIZE: ADB Shell 缓冲区大小（默认 4096 字节）

注意事项

1. USB 任务: tud_task() 必须定期调用（在独立任务中运行），否则 USB 通信会失败

2. 文件系统: 如果使用 adb push/pull 功能，必须正确初始化文件系统和存储设备

3. 默认路径: adb push/pull 命令如果不使用绝对路径，会在 CONFIG_ADB_PUSH_PULL_DEFAULT_ROOT 定义的路径下操作

4. 传输速率: 文件传输速率受 USB 速度、存储设备速度、文件系统性能等因素影响，实际速率可能有所不同

5. ADB 版本: 主机上的 ADB 版本应与设备支持的 ADB 协议版本兼容

6. USB 连接: 代码使用软件连接/断开（tud_connect() / tud_disconnect()），允许在初始化完成后再连接主机

7. FreeRTOS: 代码在 FreeRTOS 环境中运行，USB 设备任务在独立任务中运行

8. 内存监控: 主循环中的内存监控功能主要用于调试，实际应用中可以移除

9. Shell 命令: adb shell 支持的命令取决于 CONFIG_ADB_SHELL 的实现，可能支持基本的 shell 命令

10. 文件路径: 文件路径应使用设备上的文件系统路径格式（如 /SD:/adb/file.txt）