diff --git a/components/soc/soc/esp32s2/include/soc/soc_caps.h b/components/soc/soc/esp32s2/include/soc/soc_caps.h index 6efffea191..4d0b9fc412 100644 --- a/components/soc/soc/esp32s2/include/soc/soc_caps.h +++ b/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 diff --git a/components/tinyusb/additions/include/tinyusb.h b/components/tinyusb/additions/include/tinyusb.h index 84f6e453ce..8a31086b3b 100644 --- a/components/tinyusb/additions/include/tinyusb.h +++ b/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); diff --git a/components/tinyusb/additions/include/tusb_cdc_acm.h b/components/tinyusb/additions/include/tusb_cdc_acm.h index f17f375d10..4e4001f1c4 100644 --- a/components/tinyusb/additions/include/tusb_cdc_acm.h +++ b/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; diff --git a/components/tinyusb/additions/include/tusb_tasks.h b/components/tinyusb/additions/include/tusb_tasks.h index f1a47991b5..94ed4eafce 100644 --- a/components/tinyusb/additions/include/tusb_tasks.h +++ b/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 */ diff --git a/docs/Doxyfile b/docs/Doxyfile index bf3d97308a..c5e1d8effe 100644 --- a/docs/Doxyfile +++ b/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 ## diff --git a/docs/_static/usb-board-connection.png b/docs/_static/usb-board-connection.png new file mode 100644 index 0000000000..cdb81eccf3 Binary files /dev/null and b/docs/_static/usb-board-connection.png differ diff --git a/docs/conf_common.py b/docs/conf_common.py index e2d09c1966..dd4cc9ee20 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -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} diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index ce9de1034e..9972fec217 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -32,6 +32,7 @@ Peripherals API Touch Sensor TWAI UART + :SOC_USB_SUPPORTED: USB Code examples for this API section are provided in the :example:`peripherals` directory of ESP-IDF examples. diff --git a/docs/en/api-reference/peripherals/usb.rst b/docs/en/api-reference/peripherals/usb.rst new file mode 100644 index 0000000000..72bda70c93 --- /dev/null +++ b/docs/en/api-reference/peripherals/usb.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 + diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 86d5f79233..d3a350b503 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -4,31 +4,32 @@ :link_to_translation:`en:[English]` .. toctree:: - :maxdepth: 1 + :maxdepth: 1 - ADC - DAC - GPIO (包括 RTC 低功耗 I/O) - :esp32s2: HMAC - :esp32s2: Digital Signature - I2C - I2S - LED Control - :SOC_MCPWM_SUPPORTED: MCPWM - Pulse Counter - Remote Control - :SOC_SDMMC_HOST_SUPPORTED: SDMMC Host - SD SPI Host - :SOC_SDIO_SLAVE_SUPPORTED: SDIO Slave - Sigma-delta Modulation - SPI Master - SPI Slave - :esp32: Secure Element - :esp32s2: SPI Slave 半双工 (half duplex) - :esp32s2: Temp sensor - Timer - Touch Sensor - TWAI - UART + ADC + DAC + GPIO (包括 RTC 低功耗 I/O) + :esp32s2: HMAC + :esp32s2: Digital Signature + I2C + I2S + LED Control + :SOC_MCPWM_SUPPORTED: MCPWM + Pulse Counter + Remote Control + :SOC_SDMMC_HOST_SUPPORTED: SDMMC Host + SD SPI Host + :SOC_SDIO_SLAVE_SUPPORTED: SDIO Slave + Sigma-delta Modulation + SPI Master + SPI Slave + :esp32: Secure Element + :esp32s2: SPI Slave 半双工 (half duplex) + :esp32s2: Temp sensor + Timer + Touch Sensor + TWAI + UART + :SOC_USB_SUPPORTED: USB 本部分的 API 示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals` 目录下。 \ No newline at end of file diff --git a/docs/zh_CN/api-reference/peripherals/usb.rst b/docs/zh_CN/api-reference/peripherals/usb.rst new file mode 100644 index 0000000000..6fc57107c6 --- /dev/null +++ b/docs/zh_CN/api-reference/peripherals/usb.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/peripherals/usb.rst