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