mirror of
https://github.com/espressif/esp-idf.git
synced 2025-09-24 01:20:23 +00:00
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
This commit is contained in:
Dai Zi Yan
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user