From c863b4c777cb0c39019f73acb3f23f5f5ad15133 Mon Sep 17 00:00:00 2001 From: Andrei Gramakov Date: Tue, 18 Aug 2020 11:51:32 +0200 Subject: [PATCH] docs: tinyusb documentation --- .../soc/soc/esp32s2/include/soc/soc_caps.h | 1 + .../tinyusb/additions/include/tinyusb.h | 6 +- .../tinyusb/additions/include/tusb_cdc_acm.h | 10 +- .../tinyusb/additions/include/tusb_tasks.h | 2 +- docs/Doxyfile | 10 +- docs/_static/usb-board-connection.png | Bin 0 -> 95518 bytes docs/conf_common.py | 6 +- docs/en/api-reference/peripherals/index.rst | 1 + docs/en/api-reference/peripherals/usb.rst | 143 ++++++++++++++++++ .../zh_CN/api-reference/peripherals/index.rst | 51 ++++--- docs/zh_CN/api-reference/peripherals/usb.rst | 1 + 11 files changed, 195 insertions(+), 36 deletions(-) create mode 100644 docs/_static/usb-board-connection.png create mode 100644 docs/en/api-reference/peripherals/usb.rst create mode 100644 docs/zh_CN/api-reference/peripherals/usb.rst 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 b62b4062a3..66eba70bd3 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 ## @@ -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 ## diff --git a/docs/_static/usb-board-connection.png b/docs/_static/usb-board-connection.png new file mode 100644 index 0000000000000000000000000000000000000000..cdb81eccf33cd667d527f933083cf8e7067eb96f GIT binary patch literal 95518 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ξ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%0A_`hAt3 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
  • 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 literal 0 HcmV?d00001 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