mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-19 14:26:01 -04:00
docs: tinyusb documentation
This commit is contained in:
parent
3663c6df0d
commit
c863b4c777
@ -9,3 +9,4 @@
|
||||
#define SOC_CPU_CORES_NUM 1
|
||||
#define SOC_SUPPORTS_SECURE_DL_MODE 1
|
||||
#define SOC_RISCV_COPROC_SUPPORTED 1
|
||||
#define SOC_USB_SUPPORTED 1
|
||||
|
@ -71,9 +71,9 @@ extern "C" {
|
||||
* @brief Configuration structure of the tinyUSB core
|
||||
*/
|
||||
typedef struct {
|
||||
tusb_desc_device_t *descriptor;
|
||||
char **string_descriptor;
|
||||
bool external_phy;
|
||||
tusb_desc_device_t *descriptor; /*!< Pointer to a device descriptor */
|
||||
char **string_descriptor; /*!< Pointer to an array of string descriptors */
|
||||
bool external_phy; /*!< Should USB use an external PHY */
|
||||
} tinyusb_config_t;
|
||||
|
||||
esp_err_t tinyusb_driver_install(const tinyusb_config_t *config);
|
||||
|
@ -40,22 +40,22 @@ typedef enum{
|
||||
* @brief Data provided to the input of the `callback_rx_wanted_char` callback
|
||||
*/
|
||||
typedef struct {
|
||||
char wanted_char;
|
||||
char wanted_char; /*!< Wanted character */
|
||||
} cdcacm_event_rx_wanted_char_data_t;
|
||||
|
||||
/**
|
||||
* @brief Data provided to the input of the `callback_line_state_changed` callback
|
||||
*/
|
||||
typedef struct {
|
||||
bool dtr;
|
||||
bool rts;
|
||||
bool dtr; /*!< Data Terminal Ready (DTR) line state */
|
||||
bool rts; /*!< Request To Send (RTS) line state */
|
||||
} cdcacm_event_line_state_changed_data_t;
|
||||
|
||||
/**
|
||||
* @brief Data provided to the input of the `line_coding_changed` callback
|
||||
*/
|
||||
typedef struct {
|
||||
cdc_line_coding_t const *p_line_coding;
|
||||
cdc_line_coding_t const *p_line_coding; /*!< New line coding value */
|
||||
} cdcacm_event_line_coding_changed_data_t;
|
||||
|
||||
/**
|
||||
@ -72,7 +72,7 @@ typedef enum {
|
||||
* @brief Describes an event passing to the input of a callbacks
|
||||
*/
|
||||
typedef struct {
|
||||
cdcacm_event_type_t type;
|
||||
cdcacm_event_type_t type; /*!< Event type */
|
||||
union {
|
||||
cdcacm_event_rx_wanted_char_data_t rx_wanted_char_data;
|
||||
cdcacm_event_line_state_changed_data_t line_state_changed_data;
|
||||
|
@ -33,7 +33,7 @@ extern "C" {
|
||||
esp_err_t tusb_run_task(void);
|
||||
|
||||
/**
|
||||
* @brief Stops a FreeRTOS task with @ref tusb_device_task
|
||||
* @brief Stops a FreeRTOS task
|
||||
*
|
||||
* @return ESP_OK or ESP_FAIL
|
||||
*/
|
||||
|
@ -21,6 +21,14 @@ PROJECT_NAME = "ESP32 Programming Guide"
|
||||
## and used to include in API reference documentation
|
||||
|
||||
INPUT = \
|
||||
## TinyUSB
|
||||
$(IDF_PATH)/components/tinyusb/additions/include/tinyusb.h \
|
||||
$(IDF_PATH)/components/tinyusb/additions/include/tinyusb_types.h \
|
||||
$(IDF_PATH)/components/tinyusb/additions/include/tusb_cdc_acm.h \
|
||||
$(IDF_PATH)/components/tinyusb/additions/include/tusb_config.h \
|
||||
$(IDF_PATH)/components/tinyusb/additions/include/tusb_console.h \
|
||||
$(IDF_PATH)/components/tinyusb/additions/include/tusb_tasks.h \
|
||||
$(IDF_PATH)/components/tinyusb/additions/include/vfs_tinyusb.h \
|
||||
##
|
||||
## Wi-Fi - API Reference
|
||||
##
|
||||
@ -259,7 +267,7 @@ INPUT = \
|
||||
## NOTE: for line below header_file.inc is not used
|
||||
$(IDF_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h \
|
||||
$(IDF_PATH)/components/ulp/include/esp32s2/ulp_riscv.h \
|
||||
$(IDF_PATH)/components/ulp/include/ulp_common.h \
|
||||
$(IDF_PATH)/components/ulp/include/ulp_common.h \
|
||||
##
|
||||
## Application Level Tracing - API Reference
|
||||
##
|
||||
|
BIN
docs/_static/usb-board-connection.png
vendored
Normal file
BIN
docs/_static/usb-board-connection.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 93 KiB |
@ -150,6 +150,8 @@ LEGACY_DOCS = ['api-guides/build-system-legacy.rst',
|
||||
'api-guides/unit-tests-legacy.rst',
|
||||
'get-started-legacy/**']
|
||||
|
||||
USB_DOCS = ['api-reference/peripherals/usb.rst']
|
||||
|
||||
ESP32_DOCS = ['api-guides/ulp_instruction_set.rst',
|
||||
'api-reference/system/himem.rst',
|
||||
'api-guides/RF_calibration.rst',
|
||||
@ -168,13 +170,15 @@ ESP32S2_DOCS = ['esp32s2.rst',
|
||||
'api-reference/peripherals/ds.rst',
|
||||
'api-reference/peripherals/spi_slave_hd.rst',
|
||||
'api-reference/peripherals/temp_sensor.rst',
|
||||
'api-reference/system/async_memcpy.rst']
|
||||
'api-reference/system/async_memcpy.rst',
|
||||
'api-reference/peripherals/usb.rst']
|
||||
|
||||
# format: {tag needed to include: documents to included}, tags are parsed from sdkconfig and peripheral_caps.h headers
|
||||
conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
|
||||
'SOC_SDMMC_HOST_SUPPORTED':SDMMC_DOCS,
|
||||
'SOC_SDIO_SLAVE_SUPPORTED':SDIO_SLAVE_DOCS,
|
||||
'SOC_MCPWM_SUPPORTED':MCPWM_DOCS,
|
||||
'SOC_USB_SUPPORTED':USB_DOCS,
|
||||
'esp32':ESP32_DOCS,
|
||||
'esp32s2':ESP32S2_DOCS}
|
||||
|
||||
|
@ -32,6 +32,7 @@ Peripherals API
|
||||
Touch Sensor <touch_pad>
|
||||
TWAI <twai>
|
||||
UART <uart>
|
||||
:SOC_USB_SUPPORTED: USB <usb>
|
||||
|
||||
|
||||
Code examples for this API section are provided in the :example:`peripherals` directory of ESP-IDF examples.
|
||||
|
143
docs/en/api-reference/peripherals/usb.rst
Normal file
143
docs/en/api-reference/peripherals/usb.rst
Normal file
@ -0,0 +1,143 @@
|
||||
|
||||
USB Driver
|
||||
==========
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The driver allows users to use {IDF_TARGET_NAME} chips to develop USB devices on top the TinyUSB stack. TinyUSB is integrating with ESP-IDF to provide USB features of the framework. Using this driver the chip works as a composite device supporting to represent several USB devices simultaneously. Currently, only the communications device class (CDC) type of the device with the ACM (Abstract Control Model) subclass is supported.
|
||||
|
||||
|
||||
Features
|
||||
--------
|
||||
|
||||
- Configuration of device and string USB descriptors
|
||||
- USB Serial Device (CDC-ACM)
|
||||
- Input and output through USB Serial Device
|
||||
|
||||
|
||||
Hardware USB Connection
|
||||
-----------------------
|
||||
|
||||
- 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). For example, connect GPIO19/20 to D-/D+ respectively for an ESP32-S2 board:
|
||||
|
||||
|
||||
.. figure:: ../../../_static/usb-board-connection.png
|
||||
:align: center
|
||||
:alt: Connection of a board to a host ESP32-S2
|
||||
:figclass: align-center
|
||||
|
||||
Driver Structure
|
||||
----------------
|
||||
|
||||
As the basis is used the TinyUSB stack.
|
||||
|
||||
On top of it the driver implements:
|
||||
|
||||
- Customization of USB descriptors
|
||||
- Serial device support
|
||||
- Redirecting of standard streams through the Serial device
|
||||
- Encapsulated driver's task servicing the TinyuSB
|
||||
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Via Menuconfig options you can specify:
|
||||
|
||||
- Several of descriptor's parameters (see: Descriptors Configuration bellow)
|
||||
- USB Serial low-level Configuration
|
||||
- The verbosity of the TinyUSB's log
|
||||
- Disable the TinyUSB main task (for the custom implementation)
|
||||
|
||||
|
||||
Descriptors Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The driver's descriptors are provided by the :cpp:type:`tinyusb_config_t` structure's :cpp:member:`descriptor` and :cpp:member:`string_descriptor` members. Therefore, users should initialize :cpp:type:`tinyusb_config_t` to their desired descriptor before calling :cpp:func:`tinyusb_driver_install` to install driver.
|
||||
|
||||
However, the driver also provides a default descriptor. The driver can be installed with the default descriptor by setting the :cpp:member:`descriptor` and :cpp:member:`string_descriptor` members of :cpp:type:`tinyusb_config_t` to `NULL` before calling :cpp:func:`tinyusb_driver_install`. The driver's default descriptor is specified using Menuconfig, where the following fields should be configured:
|
||||
|
||||
- PID
|
||||
- VID
|
||||
- bcdDevice
|
||||
- Manufacturer
|
||||
- Product name
|
||||
- Name of CDC device if it is On
|
||||
- Serial number
|
||||
|
||||
If you want to use own descriptors with extended modification, you can define them during the driver installation process
|
||||
|
||||
|
||||
Install Driver
|
||||
--------------
|
||||
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`.
|
||||
|
||||
Note that the :cpp:type:`tinyusb_config_t` structure can be zero initialized (e.g. ``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)
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
tinyusb_config_t partial_init = {
|
||||
.descriptor = NULL; //Uses default descriptor specified in Menuconfig
|
||||
.string_descriptor = NULL; //Uses default string specified in Menuconfig
|
||||
.external_phy = false;
|
||||
}
|
||||
|
||||
USB Serial Device (CDC-ACM)
|
||||
---------------------------
|
||||
|
||||
If the CDC option is enabled in Menuconfig, the USB Serial Device could 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
|
||||
|
||||
tinyusb_config_cdcacm_t amc_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(&amc_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.
|
||||
|
||||
USB Serial Console
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The driver allows to redirect all standard application strings (stdin/out/err) to the USB Serial Device and return them to UART using :cpp:func:`esp_tusb_init_console`/:cpp:func:`esp_tusb_deinit_console` functions.
|
||||
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
The table below describes the code examples available in the directory :example:`peripherals/usb/`.
|
||||
|
||||
.. list-table::
|
||||
:widths: 35 65
|
||||
:header-rows: 1
|
||||
|
||||
* - Code Example
|
||||
- Description
|
||||
* - :example:`peripherals/usb/tusb_console`
|
||||
- How to set up {IDF_TARGET_NAME} chip to get log output via Serial Device connection
|
||||
* - :example:`peripherals/usb/tusb_sample_descriptor`
|
||||
- How to set up {IDF_TARGET_NAME} chip to work as a Generic USB Device with a user-defined descriptor
|
||||
* - :example:`peripherals/usb/tusb_serial_device`
|
||||
- How to set up {IDF_TARGET_NAME} chip to work as a USB Serial Device
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/tinyusb.inc
|
||||
.. include-build-file:: inc/tinyusb_types.inc
|
||||
.. include-build-file:: inc/tusb_cdc_acm.inc
|
||||
.. include-build-file:: inc/tusb_console.inc
|
||||
.. include-build-file:: inc/tusb_tasks.inc
|
||||
.. include-build-file:: inc/vfs_tinyusb.inc
|
||||
|
@ -4,31 +4,32 @@
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 1
|
||||
|
||||
ADC <adc>
|
||||
DAC <dac>
|
||||
GPIO (包括 RTC 低功耗 I/O) <gpio>
|
||||
:esp32s2: HMAC <hmac>
|
||||
:esp32s2: Digital Signature <ds>
|
||||
I2C <i2c>
|
||||
I2S <i2s>
|
||||
LED Control <ledc>
|
||||
:SOC_MCPWM_SUPPORTED: MCPWM <mcpwm>
|
||||
Pulse Counter <pcnt>
|
||||
Remote Control <rmt>
|
||||
:SOC_SDMMC_HOST_SUPPORTED: SDMMC Host <sdmmc_host>
|
||||
SD SPI Host <sdspi_host>
|
||||
:SOC_SDIO_SLAVE_SUPPORTED: SDIO Slave <sdio_slave>
|
||||
Sigma-delta Modulation <sigmadelta>
|
||||
SPI Master <spi_master>
|
||||
SPI Slave <spi_slave>
|
||||
:esp32: Secure Element <secure_element>
|
||||
:esp32s2: SPI Slave 半双工 (half duplex) <spi_slave_hd>
|
||||
:esp32s2: Temp sensor <temp_sensor>
|
||||
Timer <timer>
|
||||
Touch Sensor <touch_pad>
|
||||
TWAI <twai>
|
||||
UART <uart>
|
||||
ADC <adc>
|
||||
DAC <dac>
|
||||
GPIO (包括 RTC 低功耗 I/O) <gpio>
|
||||
:esp32s2: HMAC <hmac>
|
||||
:esp32s2: Digital Signature <ds>
|
||||
I2C <i2c>
|
||||
I2S <i2s>
|
||||
LED Control <ledc>
|
||||
:SOC_MCPWM_SUPPORTED: MCPWM <mcpwm>
|
||||
Pulse Counter <pcnt>
|
||||
Remote Control <rmt>
|
||||
:SOC_SDMMC_HOST_SUPPORTED: SDMMC Host <sdmmc_host>
|
||||
SD SPI Host <sdspi_host>
|
||||
:SOC_SDIO_SLAVE_SUPPORTED: SDIO Slave <sdio_slave>
|
||||
Sigma-delta Modulation <sigmadelta>
|
||||
SPI Master <spi_master>
|
||||
SPI Slave <spi_slave>
|
||||
:esp32: Secure Element <secure_element>
|
||||
:esp32s2: SPI Slave 半双工 (half duplex) <spi_slave_hd>
|
||||
:esp32s2: Temp sensor <temp_sensor>
|
||||
Timer <timer>
|
||||
Touch Sensor <touch_pad>
|
||||
TWAI <twai>
|
||||
UART <uart>
|
||||
:SOC_USB_SUPPORTED: USB <usb>
|
||||
|
||||
本部分的 API 示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals` 目录下。
|
1
docs/zh_CN/api-reference/peripherals/usb.rst
Normal file
1
docs/zh_CN/api-reference/peripherals/usb.rst
Normal file
@ -0,0 +1 @@
|
||||
.. include:: ../../../en/api-reference/peripherals/usb.rst
|
Loading…
Reference in New Issue
Block a user