警告
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 设备栈
概述
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 插头](../../_images/usb-board-connection.png)
备注
如果你使用带有两个 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 描述符相关的字段,应进行初始化:
device_descriptor
configuration_descriptor
string_descriptor
调用 tinyusb_driver_install()
时,设备栈将基于上述字段中提供的描述符实现 USB 设备。
设备栈还提供了默认描述符,将 tinyusb_driver_install()
中的相应字段设置为 NULL
即可安装。默认描述符包括:
默认设备描述符:启用时,将
device_descriptor
设置为NULL
。默认设备描述符将使用相应的 menuconfig 选项设置的值(如 PID、VID、bcdDevice 等)。默认字符串描述符:启用时,将
string_descriptor
设置为NULL
。默认字符串描述符将使用相应的 menuconfig 选项设置的值(如制造商、产品和序列字符串描述符选项)。默认配置描述符。某些很少需要自定义配置的类别(如 CDC 和 MSC)将提供默认配置描述符。启用时,将
configuration_descriptor
设置为NULL
。
安装设备栈
请调用 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
.configuration_descriptor = NULL, // 使用在 menuconfig 中根据设置指定的默认配置描述符
};
自供电设备
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 监测的简易分压器](../../_images/usb_vbus_voltage_monitor.png)
用于 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 目录下的代码示例:
代码示例 |
描述 |
---|---|
设置 ESP32-P4 芯片,通过串行设备连接获取日志输出 |
|
设置 ESP32-P4 芯片,将其作为 USB 串行设备使用 |
|
设置 ESP32-P4 芯片,将其作为 USB MIDI 设备使用 |
|
设置 ESP32-P4 芯片,将其作为 USB 人机界面设备使用 |
|
设置 ESP32-P4 芯片,将其作为 USB 大容量存储设备使用 |
|
设置 ESP32-P4 芯片,将其作为复合 USB 设备使用 (MSC + CDC) |