Merge branch 'doc/tinyusb' into 'master'

TinyUSB documentation

See merge request espressif/esp-idf!8862

Author: krzychb

components/soc/soc/esp32s2/include/soc/soc_caps.h

@@ -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

components/tinyusb/additions/include/tinyusb.h

@@ -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);

components/tinyusb/additions/include/tusb_cdc_acm.h

@@ -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;

components/tinyusb/additions/include/tusb_tasks.h

@@ -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
  */

docs/Doxyfile

@@ -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
     ##
@@ -260,7 +268,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
     ##

docs/_static/usb-board-connection.png

@@ -150,6 +150,8 @@
                '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 @@
                 '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}
 

docs/conf_common.py

@@ -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.

docs/en/api-reference/peripherals/index.rst

@@ -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
+

docs/en/api-reference/peripherals/usb.rst

@@ -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` 目录下。

docs/zh_CN/api-reference/peripherals/index.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/peripherals/usb.rst