mirror
/
esp-idf
kopia lustrzana https://github.com/espressif/esp-idf
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

Merge branch 'docs/add_Chinese_translation_for_api-reference/peripherals/usb_device.rst' into 'master' 

docs: provide CN translation for api-reference/peripherals/usb_device.rst

Closes DOC-5759

See merge request espressif/esp-idf!24835
pull/13306/head
Dai Zi Yan 2024-03-15 10:31:59 +08:00
rodzic 7bd5c62659 cb9df99073
commit f3686dcc73
2 zmienionych plików z 331 dodań i 61 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

139
docs/en/api-reference/peripherals/usb_device.rst
Wyświetl plik

@ -1,7 +1,8 @@
USB Device Driver
USB Device Stack
=================
:link_to_translation:`zh_CN:[中文]`
{IDF_TARGET_USB_DP_GPIO_NUM:default="20"}
{IDF_TARGET_USB_DM_GPIO_NUM:default="19"}
{IDF_TARGET_USB_EP_NUM:default="6"}
@ -11,99 +12,108 @@ USB Device Driver
Overview
--------
The driver allows you to use {IDF_TARGET_NAME} chips to develop USB devices on a top of TinyUSB stack. TinyUSB is integrated with ESP-IDF to provide USB features of the framework. Using this driver the chip works as simple or composite device supporting several USB devices simultaneously.
The ESP-IDF USB Device Stack (hereinafter referred to as the Device Stack) enables USB Device support on {IDF_TARGET_NAME}. By using the Device Stack, {IDF_TARGET_NAME} can be programmed with any well defined USB device functions (e.g., keyboard, mouse, camera), a custom function (aka vendor-specific class), or a combination of those functions (aka a composite device).
TinyUSB stack is distributed via `IDF Component Registry <https://components.espressif.com/components/espressif/esp_tinyusb>`__.
Our USB-OTG implementation is limited to {IDF_TARGET_USB_EP_NUM} USB endpoints ({IDF_TARGET_USB_EP_NUM_INOUT} IN/OUT endpoints and {IDF_TARGET_USB_EP_NUM_IN} IN endpoint) . Please note that enabling Secure Boot or flash encryption disables the USB-OTG USB stack in the ROM, disallowing updates via the serial emulation or Device Firmware Update (DFU) on that port. For more details, please refer to `technical reference manual <{IDF_TARGET_TRM_EN_URL}>`_.
The Device Stack is built around the TinyUSB stack, but extends TinyUSB with some minor features and modifications for better integration with ESP-IDF. The Device stack is distributed as a managed component via the `ESP-IDF Component Registry <https://components.espressif.com/components/espressif/esp_tinyusb>`__.
Features
--------
- Configuration of device and string USB descriptors
- USB Serial Device (CDC-ACM)
- Input and output streams through USB Serial Device
- Other USB classes (MIDI, MSC, HID...) support directly via TinyUSB
- USB Composite Device (MSC + CDC)
- Multiple supported device classes (CDC, HID, MIDI, MSC)
- Composite devices
- Vendor specific classes
- Maximum of {IDF_TARGET_USB_EP_NUM} endpoints
- {IDF_TARGET_USB_EP_NUM_INOUT} IN/OUT endpoints
- {IDF_TARGET_USB_EP_NUM_IN} IN endpoints
- VBUS monitoring for self-powered devices
Hardware USB Connection
-----------------------
.. Todo: Refactor USB hardware connect into a separate guide
- Any board with the {IDF_TARGET_NAME} chip with USB connectors or with exposed USB's D+ and D- (DATA+/DATA-) pins.
If the board has no USB connector but has the pins, connect pins directly to the host (e.g., with do-it-yourself cable from any USB connection cable).
On {IDF_TARGET_NAME}, connect GPIO {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} to D+/D- respectively:
Hardware Connection
-------------------
The {IDF_TARGET_NAME} routes the USB D+ and D- signals to GPIOs {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} respectively. For USB device functionality, these GPIOs should be connected to the bus in some way (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug).
.. figure:: ../../../_static/usb-board-connection.png
:align: center
:alt: Connection of an ESP board to a USB host
:alt: Connection of an USB GPIOs directly to a USB standard-A plug
:figclass: align-center
Self-powered devices must also connect VBUS through voltage divider or comparator, more details in :ref:`self-powered-device` subchapter.
.. note::
Driver Structure
----------------
If you are using an {IDF_TARGET_NAME} development board with two USB ports, the port labeled "USB" will already be connected to the D+ and D- GPIOs.
As the basis is used the TinyUSB stack.
.. note::
On top of it the driver implements:
Self-powered devices must also connect VBUS through a voltage divider or comparator. For more details, please refer to :ref:`self-powered-device`.
Device Stack Structure
----------------------
The basis of the Device Stack is TinyUSB, where the Device Stack implements the following features on top of TinyUSB:
- Customization of USB descriptors
- Serial device support
- Redirecting of standard streams through the Serial device
- Storage Media (SPI-Flash and SD-Card) for USB Device MSC Class.
- Encapsulated driver's task servicing the TinyUSB
- A task within the encapsulated device stack that handles TinyUSB servicing
Configuration
-------------
Component Dependency
^^^^^^^^^^^^^^^^^^^^
To use the component, you need to add it as a dependency via the following command. For more details, please refer to `IDF Component Registry <https://components.espressif.com/components/espressif/esp_tinyusb>`__.
The Device Stack is distributed via the `ESP-IDF Component Registry <https://components.espressif.com/components/espressif/esp_tinyusb>`__. Thus, to use it, please add the Device Stack component as dependency using the following command:
.. code:: bash
idf.py add-dependency esp_tinyusb
idf.py add-dependency esp_tinyusb
Via Menuconfig options you can specify:
Configuration Options
^^^^^^^^^^^^^^^^^^^^^
Multiple aspects of the Device Stack can be configured using menuconfig. These include:
- Several descriptor's parameters (see Descriptors Configuration below)
- USB Serial low-level configuration
- The verbosity of the TinyUSB's log
- Disable the TinyUSB main task (for the custom implementation)
- Device Stack task related options
- Default device/string descriptor options
- Class specific options
Descriptors Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^
.. _descriptors-configuration:
The driver's descriptors are provided by :cpp:type:`tinyusb_config_t` structure's :cpp:member:`device_descriptor`, :cpp:member:`configuration_descriptor` and :cpp:member:`string_descriptor` members. Therefore, you should initialize :cpp:type:`tinyusb_config_t` with your desired descriptors before calling :cpp:func:`tinyusb_driver_install` to install the driver.
Descriptor Configuration
^^^^^^^^^^^^^^^^^^^^^^^^
However, the driver also provides default descriptors. You can install the driver with default device and string descriptors by setting the :cpp:member:`device_descriptor` and :cpp:member:`string_descriptor` members of :cpp:type:`tinyusb_config_t` to `NULL` before calling :cpp:func:`tinyusb_driver_install`. To lower your development effort we also provide default configuration descriptor for CDC and MSC class, as these classes rarely require custom configuration. The driver's default device descriptor is specified using Menuconfig, where the following fields should be configured:
The :cpp:type:`tinyusb_config_t` structure provides the following USB descriptor related fields that should be initialized:
- PID
- VID
- bcdDevice
- Manufacturer
- Product name
- Name of CDC or MSC device if it is On
- Serial number
- :cpp:member:`device_descriptor`
- :cpp:member:`configuration_descriptor`
- :cpp:member:`string_descriptor`
If you want to use your own descriptors with extended modification, you can define them during the driver installation process.
The Device Stack will instantiate a USB device based on the descriptors provided in the fields described above when :cpp:func:`tinyusb_driver_install` is called.
Install Driver
--------------
The Device Stack also provides default descriptors that can be installed by setting the corresponding field in :cpp:func:`tinyusb_driver_install` to ``NULL``. Default descriptors include:
To initialize the driver, users should call :cpp:func:`tinyusb_driver_install`. The driver's configuration is specified in a :cpp:type:`tinyusb_config_t` structure that is passed as an argument to :cpp:func:`tinyusb_driver_install`.
- Default device descriptor: Enabled by setting :cpp:member:`device_descriptor` to ``NULL``. Default device descriptor will use the values set by the corresponding menuconfig options (e.g., PID, VID, bcdDevice etc).
- Default string descriptor: Enabled by setting :cpp:member:`string_descriptor` to ``NULL``. Default string descriptors will use the value set by corresponding menuconfig options (e.g., manufacturer, product, and serial string descriptor options).
- Default configuration descriptor. Some classes that rarely require custom configuration (such as CDC and MSC) will provide default configuration descriptors. These can be enabled by setting :cpp:member:`configuration_descriptor` to ``NULL``.
Note that the :cpp:type:`tinyusb_config_t` structure can be zero initialized (e.g., ``const tinyusb_config_t tusb_cfg = { 0 };``) or partially (as shown below). For any member that is initialized to `0` or `NULL`, the driver will use its default configuration values for that member (see example below)
Installation
------------
To install the Device Stack, please call :cpp:func:`tinyusb_driver_install`. The Device Stack's configuration is specified in a :cpp:type:`tinyusb_config_t` structure that is passed as an argument to :cpp:func:`tinyusb_driver_install`.
.. note::
The :cpp:type:`tinyusb_config_t` structure can be zero-initialized (e.g., ``const tinyusb_config_t tusb_cfg = { 0 };``) or partially (as shown below). For any member that is initialized to ``0`` or ``NULL``, the stack uses its default configuration values for that member, see example below.
.. code-block:: c
const tinyusb_config_t partial_init = {
.device_descriptor = NULL, // Use default device descriptor specified in Menuconfig
.string_descriptor = NULL, // Use default string descriptors specified in Menuconfig
.device_descriptor = NULL, // Use the default device descriptor specified in Menuconfig
.string_descriptor = NULL, // Use the default string descriptors specified in Menuconfig
.external_phy = false, // Use internal USB PHY
.configuration_descriptor = NULL, // Use default configuration descriptor according to settings in Menuconfig
.configuration_descriptor = NULL, // Use the default configuration descriptor according to settings in Menuconfig
};
.. _self-powered-device:
@ -111,9 +121,16 @@ To initialize the driver, users should call :cpp:func:`tinyusb_driver_install`.
Self-Powered Device
-------------------
USB specification mandates self-powered devices to monitor voltage level on USB's VBUS signal. As opposed to bus-powered devices, a self-powered device can be fully functional even without USB connection. The self-powered device detects connection and disconnection events by monitoring the VBUS voltage level. VBUS is considered valid if it rises above 4.75 V and invalid if it falls below 4.35 V.
USB specification mandates self-powered devices to monitor voltage levels on USB's VBUS signal. As opposed to bus-powered devices, a self-powered device can be fully functional even without a USB connection. The self-powered device detects connection and disconnection events by monitoring the VBUS voltage level. VBUS is considered valid if it rises above 4.75 V and invalid if it falls below 4.35 V.
No {IDF_TARGET_NAME} pin is 5 V tolerant, so you must connect the VBUS to {IDF_TARGET_NAME} via a comparator with voltage thresholds as described above, or use a simple resistor voltage divider that will output (0.75 x Vdd) if VBUS is 4.4 V (see figure below). In both cases, voltage on the sensing pin must be logic low within 3 ms after the device is unplugged from USB host.
On the {IDF_TARGET_NAME}, this will require using a GPIO to act as a voltage sensing pin to detect when VBUS goes above/below the prescribed thresholds. However, {IDF_TARGET_NAME} pins are 3.3 V tolerant. Thus, even if VBUS rises/falls above/below the thresholds mentioned above, it would still appear as a logic HIGH to the {IDF_TARGET_NAME}. Thus, in order to detect the VBUS valid condition, users can do one of the following:
- Connect VBUS to a voltage comparator chip/circuit that detects the thresholds described above (i.e., 4.35 V and 4.75 V), and outputs a 3.3 V logic level to the {IDF_TARGET_NAME} indicating whether VBUS is valid or not.
- Use a resistor voltage divider that outputs (0.75 x Vdd) if VBUS is 4.4 V (see figure below).
.. note::
In either case, the voltage on the sensing pin must be logic low within 3 ms after the device is unplugged from the USB host.
.. figure:: ../../../_static/diagrams/usb/usb_vbus_voltage_monitor.png
:align: center
@ -122,12 +139,12 @@ No {IDF_TARGET_NAME} pin is 5 V tolerant, so you must connect the VBUS to {IDF_T
Simple voltage divider for VBUS monitoring
To use this feature, in :cpp:type:`tinyusb_config_t` you must set :cpp:member:`self_powered` to ``true`` and :cpp:member:`vbus_monitor_io` to GPIO number that will be used for VBUS monitoring.
To use this feature, in :cpp:type:`tinyusb_config_t`, you must set :cpp:member:`self_powered` to ``true`` and :cpp:member:`vbus_monitor_io` to GPIO number that is used for VBUS monitoring.
USB Serial Device (CDC-ACM)
---------------------------
If the CDC option is enabled in Menuconfig, the USB Serial Device can be initialized with :cpp:func:`tusb_cdc_acm_init` according to the settings from :cpp:type:`tinyusb_config_cdcacm_t` (see example below).
If the CDC option is enabled in Menuconfig, the USB Serial Device can be initialized with :cpp:func:`tusb_cdc_acm_init` according to the settings from :cpp:type:`tinyusb_config_cdcacm_t`, see example below.
.. code-block:: c
@ -142,17 +159,19 @@ If the CDC option is enabled in Menuconfig, the USB Serial Device can be initial
};
tusb_cdc_acm_init(&acm_cfg);
To specify callbacks you can either set the pointer to your :cpp:type:`tusb_cdcacm_callback_t` function in the configuration structure or call :cpp:func:`tinyusb_cdcacm_register_callback` after initialization.
To specify callbacks, you can either set the pointer to your :cpp:type:`tusb_cdcacm_callback_t` function in the configuration structure or call :cpp:func:`tinyusb_cdcacm_register_callback` after initialization.
USB Serial Console
^^^^^^^^^^^^^^^^^^
The driver allows to redirect all standard application streams (stdin, stdout, stderr) to the USB Serial Device and return them to UART using :cpp:func:`esp_tusb_init_console`/:cpp:func:`esp_tusb_deinit_console` functions.
The USB Serial Device allows the redirection of all standard input/output streams (stdin, stdout, stderr) to USB. Thus, calling standard library input/output functions such as ``printf()`` will result into the data being sent/received over USB instead of UART.
Users should call :cpp:func:`esp_tusb_init_console` to switch the standard input/output streams to USB, and :cpp:func:`esp_tusb_deinit_console` to switch them back to UART.
USB Mass Storage Device (MSC)
-----------------------------
If the MSC CONFIG_TINYUSB_MSC_ENABLED option is enabled in Menuconfig, the ESP Chip can be used as USB MSC Device. The storage media (spi-flash or sd-card) can be initialized as shown below (see example below).
If the MSC ``CONFIG_TINYUSB_MSC_ENABLED`` option is enabled in Menuconfig, the ESP Chip can be used as USB MSC Device. The storage media (SPI-Flash or SD-Card) can be initialized as shown below.
- SPI-Flash
@ -211,7 +230,7 @@ If the MSC CONFIG_TINYUSB_MSC_ENABLED option is enabled in Menuconfig, the ESP C
Application Examples
--------------------
The table below describes the code examples available in the directory :example:`peripherals/usb/`.
The table below describes the code examples available in the directory :example:`peripherals/usb/device`:
.. list-table::
:widths: 35 65

253
docs/zh_CN/api-reference/peripherals/usb_device.rst
Wyświetl plik

@ -1 +1,252 @@
.. include:: ../../../en/api-reference/peripherals/usb_device.rst
USB 设备栈
=================
:link_to_translation:`en:[English]`
{IDF_TARGET_USB_DP_GPIO_NUM:default="20"}
{IDF_TARGET_USB_DM_GPIO_NUM:default="19"}
{IDF_TARGET_USB_EP_NUM:default="6"}
{IDF_TARGET_USB_EP_NUM_INOUT:default="5"}
{IDF_TARGET_USB_EP_NUM_IN:default="1"}
概述
--------
USB 设备栈（以下简称设备栈）支持在 {IDF_TARGET_NAME} 上启用 USB 设备支持。通过使用设备栈，可以为 {IDF_TARGET_NAME} 烧录任意具有明确定义的 USB 设备功能（如键盘、鼠标、摄像头）、自定义功能（也称特定供应商类别）或上述功能的组合（也称复合设备）。
设备栈基于 TinyUSB 栈构建，但对 TinyUSB 进行了一些小的功能扩展和修改，使其更好地集成到 ESP-IDF。设备栈通过 `ESP-IDF 组件注册器 <https://components.espressif.com/components/espressif/esp_tinyusb>`__ 作为托管组件分发。
功能列表
--------
- 支持多种设备类别 (CDC, HID, MIDI, MSC)
- 支持复合设备
- 支持特定供应商类别
- 最多支持 {IDF_TARGET_USB_EP_NUM} 个端点
- {IDF_TARGET_USB_EP_NUM_INOUT} 个输入/输出端点
- {IDF_TARGET_USB_EP_NUM_IN} 个输入端点
- 自供电设备的 VBUS 监测
.. Todo: Refactor USB hardware connect into a separate guide
硬件连接
--------
{IDF_TARGET_NAME} 将 USB D+ 和 D- 信号分别路由到 GPIO {IDF_TARGET_USB_DP_GPIO_NUM} 和 {IDF_TARGET_USB_DM_GPIO_NUM}。为了实现 USB 设备功能，这些 GPIO 应通过某种方式连接到总线上（例如，通过 Micro-B 端口、USB-C 端口或直接连接到标准-A 插头）。
.. figure:: ../../../_static/usb-board-connection.png
:align: center
:alt: 将 USB GPIO 直接接连至 USB 标准-A 插头
:figclass: align-center
.. note::
如果你使用带有两个 USB 端口的 {IDF_TARGET_NAME} 开发板，标有 "USB" 的端口已经连接到 D+ 和 D- GPIO。
.. note::
自供电设备还必须通过电压分压器或比较器连接 VBUS，详情请参阅 :ref:`self-powered-device`。
设备栈结构
----------
设备栈以 TinyUSB 栈为基础，在此基础上，该设备栈实现了以下功能：
- 自定义 USB 描述符
- 支持串行设备
- 通过串行设备重定向标准流
- 提供用于 USB 设备 MSC 类的存储介质（SPI-Flash 和 SD 卡）
- 封装设备栈中处理 TinyUSB 服务的任务
组件依赖项
-------------
设备栈通过 `ESP-IDF 组件注册器 <https://components.espressif.com/components/espressif/esp_tinyusb>`__ 分发，使用前，请使用以下命令将设备栈组件添加为依赖项：
.. code:: bash
idf.py add-dependency esp_tinyusb
配置选项
^^^^^^^^^
通过 menuconfig 选项，可以对设备栈进行以下多方面配置：
- TinyUSB 日志的详细程度
- 设备栈任务相关选项
- 默认设备/字符串描述符选项
- 特定类别的选项
.. _descriptors-configuration:
配置描述符
^^^^^^^^^^^^^^^^^^^^^^^^^
结构体 :cpp:type:`tinyusb_config_t` 提供了以下与 USB 描述符相关的字段，应进行初始化：
- :cpp:member:`device_descriptor`
- :cpp:member:`configuration_descriptor`
- :cpp:member:`string_descriptor`
调用 :cpp:func:`tinyusb_driver_install` 时，设备栈将基于上述字段中提供的描述符实现 USB 设备。
设备栈还提供了默认描述符，将 :cpp:func:`tinyusb_driver_install` 中的相应字段设置为 ``NULL`` 即可安装。默认描述符包括：
- 默认设备描述符：启用时，将 :cpp:member:`device_descriptor` 设置为 ``NULL``。默认设备描述符将使用相应的 menuconfig 选项设置的值（如 PID、VID、bcdDevice 等）。
- 默认字符串描述符：启用时，将 :cpp:member:`string_descriptor` 设置为 ``NULL``。默认字符串描述符将使用相应的 menuconfig 选项设置的值（如制造商、产品和序列字符串描述符选项）。
- 默认配置描述符。某些很少需要自定义配置的类别（如 CDC 和 MSC）将提供默认配置描述符。启用时，将 :cpp:member:`configuration_descriptor` 设置为 ``NULL``。
安装设备栈
----------
请调用 :cpp:func:`tinyusb_driver_install` 安装设备栈。结构体 :cpp:type:`tinyusb_config_t` 指定了设备栈的配置，而 :cpp:type:`tinyusb_config_t` 作为参数传递给 :cpp:func:`tinyusb_driver_install`。
.. note::
结构体 :cpp:type:`tinyusb_config_t` 可以实现零初始化（如 ``const tinyusb_config_t tusb_cfg = { 0 };``）或部分初始化（如下所示）。对于结构体中任何初始化为 ``0`` 或 ``NULL`` 的成员，设备栈将使用其默认配置，请参阅如下示例。
.. code-block:: c
const tinyusb_config_t partial_init = {
.device_descriptor = NULL, // 使用在 menuconfig 中指定的默认设备描述符
.string_descriptor = NULL, // 使用在 menuconfig 中指定的默认字符串描述符
.external_phy = false, // 使用内部 USB PHY
.configuration_descriptor = NULL, // 使用在 menuconfig 中根据设置指定的默认配置描述符
};
.. _self-powered-device:
自供电设备
-------------------
USB 规范要求自供电设备监测 USB 的 VBUS 信号的电压水平。与总线供电设备相反，即使没有 USB 连接，自供电设备也可以正常工作。通过监测 VBUS 电压水平，自供电设备可以检测连接和断开事件。当 VBUS 电压升高到 4.75 V 以上时视为有效；当 VBUS 电压下降到 4.35 V 以下时视为无效。
在 {IDF_TARGET_NAME} 上，需要使用一个 GPIO 作为电压感测管脚，检测 VBUS 处于在规定阈值之上/之下。然而，由于 {IDF_TARGET_NAME} 管脚具有 3.3 V 容差，即使 VBUS 上升/下降到高于/低于上述规定阈值，{IDF_TARGET_NAME} 仍会显示为逻辑高电平。因此，为了检测 VBUS 是否有效，可以采用以下方法：
- 将 VBUS 连接至电压比较器芯片/电路，该芯片/电路可检测上述阈值（即 4.35 V 和 4.75 V），并向 {IDF_TARGET_NAME} 输出 3.3 V 逻辑电平，指示 VBUS 是否有效。
- 如果 VBUS 为 4.4 V，则使用电阻分压器输出 (0.75 x Vdd)（见下图）。
.. note::
在这两种情况下，设备从 USB 主机拔出后 3 毫秒内，传感引脚上的电压必须为逻辑低电平。
.. figure:: ../../../_static/diagrams/usb/usb_vbus_voltage_monitor.png
:align: center
:alt: 用于 VBUS 监测的简易分压器
:figclass: align-center
用于 VBUS 监测的简易分压器
请在结构体 :cpp:type:`tinyusb_config_t` 中将 :cpp:member:`self_powered` 设置为 ``true``，并将 :cpp:member:`vbus_monitor_io` 设置为用于 VBUS 监测的 GPIO 管脚编号以使用此功能。
USB 串行设备 (CDC-ACM)
---------------------------
如果在 menuconfig 中启用了 CDC 选项，则可以根据 :cpp:type:`tinyusb_config_cdcacm_t` 的设置，使用 :cpp:func:`tusb_cdc_acm_init` 初始化 USB 串行设备，请参阅如下示例：
.. code-block:: c
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);
可以在配置结构体中设置指向 :cpp:type:`tusb_cdcacm_callback_t` 函数的指针指定回调函数，或在初始化 USB 串行设备后，调用 :cpp:func:`tinyusb_cdcacm_register_callback` 指定回调函数。
USB 串行控制台
^^^^^^^^^^^^^^^^^^
USB 串行设备支持将所有标准输入/输出流 (stdin、stdout、stderr) 重定向到 USB。因此，调用如 ``printf()`` 等标准库输入/输出函数将导致通过 USB 而不是 UART 发送/接收数据。
建议调用 :cpp:func:`esp_tusb_init_console` 将标准输入/输出流切换到 USB，并调用 :cpp:func:`esp_tusb_deinit_console` 将其切换回 UART。
USB 大容量存储设备 (MSC)
-----------------------------
在 menuconfig 中启用 MSC ``CONFIG_TINYUSB_MSC_ENABLED`` 选项时，可以将 ESP 芯片作为 USB 大容量存储设备使用。按如下示例，可以初始化存储媒介（SPI-Flash 或 SD 卡）。
- SPI-Flash
.. code-block:: c
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 卡
.. code-block:: c
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);
应用示例
--------------------
下表列出了 :example:`peripherals/usb/device` 目录下的代码示例：
.. list-table::
:widths: 35 65
:header-rows: 1
* - 代码示例
- 描述
* - :example:`peripherals/usb/device/tusb_console`
- 设置 {IDF_TARGET_NAME} 芯片，通过串行设备连接获取日志输出
* - :example:`peripherals/usb/device/tusb_serial_device`
- 设置 {IDF_TARGET_NAME} 芯片，将其作为 USB 串行设备使用
* - :example:`peripherals/usb/device/tusb_midi`
- 设置 {IDF_TARGET_NAME} 芯片，将其作为 USB MIDI 设备使用
* - :example:`peripherals/usb/device/tusb_hid`
- 设置 {IDF_TARGET_NAME} 芯片，将其作为 USB 人机界面设备使用
* - :example:`peripherals/usb/device/tusb_msc`
- 设置 {IDF_TARGET_NAME} 芯片，将其作为 USB 大容量存储设备使用
* - :example:`peripherals/usb/device/tusb_composite_msc_serialdevice`
- 设置 {IDF_TARGET_NAME} 芯片，将其作为复合 USB 设备使用 (MSC + CDC)