警告

This document is not updated for ESP32P4 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

USB 设备栈

[English]

概述

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

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

功能列表

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

  • 支持复合设备

  • 支持特定供应商类别

  • 最多支持 6 个端点

    • 5 个输入/输出端点

    • 1 个输入端点

  • 自供电设备的 VBUS 监测

硬件连接

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

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

备注

如果你使用带有两个 USB 端口的 ESP32-P4 开发板，标有 "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_descriptor 和 hs_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 };）或部分初始化（如下所示）。对于结构体中任何初始化为 0 或 NULL 的成员，设备栈将使用其默认配置，请参阅如下示例。

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

  • 将 VBUS 连接至电压比较器芯片/电路，该芯片/电路可检测上述阈值（即 4.35 V 和 4.75 V），并向 ESP32-P4 输出 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-P4 芯片，通过串行设备连接获取日志输出

peripherals/usb/device/tusb_serial_device

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

peripherals/usb/device/tusb_midi

设置 ESP32-P4 芯片，将其作为 USB MIDI 设备使用

peripherals/usb/device/tusb_hid

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

peripherals/usb/device/tusb_msc

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

peripherals/usb/device/tusb_composite_msc_serialdevice

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

提供有关此文档的反馈