USB 设备栈

[English]

概述

USB 设备栈(以下简称设备栈)支持在 ESP32-S2 上启用 USB 设备支持。通过使用设备栈,可以为 ESP32-S2 烧录任意具有明确定义的 USB 设备功能(如键盘、鼠标、摄像头)、自定义功能(也称特定供应商类别)或上述功能的组合(也称复合设备)。

设备栈基于 TinyUSB 栈构建,但对 TinyUSB 进行了一些小的功能扩展和修改,使其更好地集成到 ESP-IDF。设备栈通过 ESP-IDF 组件注册器 作为托管组件分发。

功能列表

  • 支持多种设备类别 (CDC, HID, MIDI, MSC)

  • 支持复合设备

  • 支持特定供应商类别

  • 最多支持 6 个端点

    • 5 个输入/输出端点

    • 1 个输入端点

  • 自供电设备的 VBUS 监测

硬件连接

ESP32-S2 将 USB D+ 和 D- 信号分别路由到 GPIO 20 和 19。为了实现 USB 设备功能,这些 GPIO 应通过某种方式连接到总线上(例如,通过 Micro-B 端口、USB-C 端口或直接连接到标准-A 插头)。

将 USB GPIO 直接接连至 USB 标准-A 插头

备注

如果你使用带有两个 USB 端口的 ESP32-S2 开发板,标有 "USB" 的端口已经连接到 D+ 和 D- GPIO。

备注

自供电设备还必须通过电压分压器或比较器连接 VBUS,详情请参阅 自供电设备

设备栈结构

设备栈以 TinyUSB 栈为基础,在此基础上,该设备栈实现了以下功能:

  • 自定义 USB 描述符

  • 支持串行设备

  • 通过串行设备重定向标准流

  • 提供用于 USB 设备 MSC 类的存储介质(SPI-Flash 和 SD 卡)

  • 封装设备栈中处理 TinyUSB 服务的任务

组件依赖项

设备栈通过 ESP-IDF 组件注册器 分发,使用前,请使用以下命令将设备栈组件添加为依赖项:

idf.py add-dependency esp_tinyusb

配置选项

通过 menuconfig 选项,可以对设备栈进行以下多方面配置:

  • TinyUSB 日志的详细程度

  • 设备栈任务相关选项

  • 默认设备/字符串描述符选项

  • 特定类别的选项

配置描述符

结构体 tinyusb_config_t 提供了与 USB 描述符相关的字段,应进行初始化。

无论是全速 USB 设备还是高速 USB 设备,都应初始化以下描述符:

  • device_descriptor

  • string_descriptor

全速 USB 设备应初始化以下字段,以提供相应的配置描述符:

  • configuration_descriptor

高速 USB 设备应初始化以下字段,以提供不同速度下的配置描述符:

  • fs_configuration_descriptor

  • hs_configuration_descriptor

  • qualifier_descriptor

备注

若设备栈支持高速,为符合 USB 2.0 协议规范,应同时初始化 fs_configuration_descriptorhs_configuration_descriptor

调用 tinyusb_driver_install() 时,设备栈将基于上述字段中提供的描述符实现 USB 设备。

设备栈还提供了默认描述符,将 tinyusb_driver_install() 中的相应字段设置为 NULL 即可安装。默认描述符包括:

  • 默认设备描述符:如需启用,将 device_descriptor 设置为 NULL。默认设备描述符将使用相应的 menuconfig 选项设置的值(如 PID、VID、bcdDevice 等)。

  • 默认字符串描述符:如需启用,将 string_descriptor 设置为 NULL。默认字符串描述符将使用相应的 menuconfig 选项设置的值(如制造商、产品和序列字符串描述符选项)。

  • 默认配置描述符。某些很少需要自定义配置的类别(如 CDC 和 MSC)将提供默认配置描述符。如需启用,将相应的配置描述符字段设置为 NULL

    • configuration_descriptor:全速描述符,仅适用于全速设备

    • fs_configuration_descriptor:全速描述符,适用于高速设备

    • hs_configuration_descriptor:高速描述符,适用于高速设备

备注

为实现向后兼容性,若设备栈支持高速,可使用 configuration_descriptor 代替 fs_configuration_descriptor 来设置全速配置描述符。

安装设备栈

请调用 tinyusb_driver_install() 安装设备栈。结构体 tinyusb_config_t 指定了设备栈的配置,而 tinyusb_config_t 作为参数传递给 tinyusb_driver_install()

备注

结构体 tinyusb_config_t 可以实现零初始化(如 const tinyusb_config_t tusb_cfg = { 0 };)或部分初始化(如下所示)。对于结构体中任何初始化为 0NULL 的成员,设备栈将使用其默认配置,请参阅如下示例。

const tinyusb_config_t partial_init = {
    .device_descriptor = NULL,  // 使用在 menuconfig 中指定的默认设备描述符
    .string_descriptor = NULL,  // 使用在 menuconfig 中指定的默认字符串描述符
    .external_phy = false,      // 使用内部 USB PHY
#if (TUD_OPT_HIGH_SPEED)
    .fs_configuration_descriptor = NULL, // 使用在 menuconfig 中根据设置指定的默认全速配置描述符
    .hs_configuration_descriptor = NULL, // 使用在 menuconfig 中根据设置指定的默认高速配置描述符
    .qualifier_descriptor = NULL,  // 使用默认限定描述符,值取自默认设备描述符
#else
    .configuration_descriptor = NULL,   // 使用在 menuconfig 中根据设置指定的默认配置描述符
#endif // TUD_OPT_HIGH_SPEED

};

自供电设备

USB 规范要求自供电设备监测 USB 的 VBUS 信号的电压水平。与总线供电设备相反,即使没有 USB 连接,自供电设备也可以正常工作。通过监测 VBUS 电压水平,自供电设备可以检测连接和断开事件。当 VBUS 电压升高到 4.75 V 以上时视为有效;当 VBUS 电压下降到 4.35 V 以下时视为无效。

在 ESP32-S2 上,需要使用一个 GPIO 作为电压感测管脚,检测 VBUS 处于在规定阈值之上/之下。然而,由于 ESP32-S2 管脚具有 3.3 V 容差,即使 VBUS 上升/下降到高于/低于上述规定阈值,ESP32-S2 仍会显示为逻辑高电平。因此,为了检测 VBUS 是否有效,可以采用以下方法:

  • 将 VBUS 连接至电压比较器芯片/电路,该芯片/电路可检测上述阈值(即 4.35 V 和 4.75 V),并向 ESP32-S2 输出 3.3 V 逻辑电平,指示 VBUS 是否有效。

  • 如果 VBUS 为 4.4 V,则使用电阻分压器输出 (0.75 x Vdd)(见下图)。

备注

在这两种情况下,设备从 USB 主机拔出后 3 毫秒内,传感引脚上的电压必须为逻辑低电平。

用于 VBUS 监测的简易分压器

用于 VBUS 监测的简易分压器

请在结构体 tinyusb_config_t 中将 self_powered 设置为 true,并将 vbus_monitor_io 设置为用于 VBUS 监测的 GPIO 管脚编号以使用此功能。

USB 串行设备 (CDC-ACM)

如果在 menuconfig 中启用了 CDC 选项,则可以根据 tinyusb_config_cdcacm_t 的设置,使用 tusb_cdc_acm_init() 初始化 USB 串行设备,请参阅如下示例:

const tinyusb_config_cdcacm_t acm_cfg = {
    .usb_dev = TINYUSB_USBDEV_0,
    .cdc_port = TINYUSB_CDC_ACM_0,
    .rx_unread_buf_sz = 64,
    .callback_rx = NULL,
    .callback_rx_wanted_char = NULL,
    .callback_line_state_changed = NULL,
    .callback_line_coding_changed = NULL
};
tusb_cdc_acm_init(&acm_cfg);

可以在配置结构体中设置指向 tusb_cdcacm_callback_t 函数的指针指定回调函数,或在初始化 USB 串行设备后,调用 tinyusb_cdcacm_register_callback() 指定回调函数。

USB 串行控制台

USB 串行设备支持将所有标准输入/输出流 (stdin、stdout、stderr) 重定向到 USB。因此,调用如 printf() 等标准库输入/输出函数将导致通过 USB 而不是 UART 发送/接收数据。

建议调用 esp_tusb_init_console() 将标准输入/输出流切换到 USB,并调用 esp_tusb_deinit_console() 将其切换回 UART。

USB 大容量存储设备 (MSC)

在 menuconfig 中启用 MSC CONFIG_TINYUSB_MSC_ENABLED 选项时,可以将 ESP 芯片作为 USB 大容量存储设备使用。按如下示例,可以初始化存储媒介(SPI-Flash 或 SD 卡)。

  • SPI-Flash

static esp_err_t storage_init_spiflash(wl_handle_t *wl_handle)
{
    ***
    esp_partition_t *data_partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, NULL);
    ***
    wl_mount(data_partition, wl_handle);
    ***
}
storage_init_spiflash(&wl_handle);

const tinyusb_msc_spiflash_config_t config_spi = {
    .wl_handle = wl_handle
};
tinyusb_msc_storage_init_spiflash(&config_spi);
  • SD 卡

static esp_err_t storage_init_sdmmc(sdmmc_card_t **card)
{
    ***
    sdmmc_host_t host = SDMMC_HOST_DEFAULT();
    sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT();
    // 对于 SD 卡,设置要使用的总线宽度

    slot_config.width = 4;
    slot_config.clk = CONFIG_EXAMPLE_PIN_CLK;
    slot_config.cmd = CONFIG_EXAMPLE_PIN_CMD;
    slot_config.d0 = CONFIG_EXAMPLE_PIN_D0;
    slot_config.d1 = CONFIG_EXAMPLE_PIN_D1;
    slot_config.d2 = CONFIG_EXAMPLE_PIN_D2;
    slot_config.d3 = CONFIG_EXAMPLE_PIN_D3;
    slot_config.flags |= SDMMC_SLOT_FLAG_INTERNAL_PULLUP;

    sd_card = (sdmmc_card_t *)malloc(sizeof(sdmmc_card_t));
    (*host.init)();
    sdmmc_host_init_slot(host.slot, (const sdmmc_slot_config_t *) &slot_config);
    sdmmc_card_init(&host, sd_card);
    ***
}
storage_init_sdmmc(&card);

const tinyusb_msc_sdmmc_config_t config_sdmmc = {
    .card = card
};
tinyusb_msc_storage_init_sdmmc(&config_sdmmc);

应用示例

下表列出了 peripherals/usb/device 目录下的代码示例:

代码示例

描述

peripherals/usb/device/tusb_console

设置 ESP32-S2 芯片,通过串行设备连接获取日志输出

peripherals/usb/device/tusb_serial_device

设置 ESP32-S2 芯片,将其作为 USB 串行设备使用

peripherals/usb/device/tusb_midi

设置 ESP32-S2 芯片,将其作为 USB MIDI 设备使用

peripherals/usb/device/tusb_hid

设置 ESP32-S2 芯片,将其作为 USB 人机界面设备使用

peripherals/usb/device/tusb_msc

设置 ESP32-S2 芯片,将其作为 USB 大容量存储设备使用

peripherals/usb/device/tusb_composite_msc_serialdevice

设置 ESP32-S2 芯片,将其作为复合 USB 设备使用 (MSC + CDC)