docs: add iot_usbh_cdc api reference

.gitlab/ci/rules.yml

@@ -234,6 +234,7 @@
   - "components/sensors/sensor_hub/include/hal/light_sensor_hal.h"
   - "components/sensors/sensor_hub/include/iot_sensor_hub.h"
   - "components/sensors/sensor_hub/include/sensor_type.h"
+  - "components/usb/iot_usbh_cdc/include/iot_usbh_cdc.h"
   - "components/usb/usb_device_uvc/include/usb_device_uvc.h"
   - "components/usb/usb_stream/include/usb_stream.h"
   - "components/zero_detection/include/zero_detection.h"

components/usb/iot_usbh_cdc/CHANGELOG.md

@@ -1,5 +1,9 @@
 # ChangeLog
 
+## v0.2.2 - 2023-12-08
+
+* Add doc and example
+
 ## v0.2.1 - 2023-11-23
 
 * Fix possible cmake_utilities dependency issue

components/usb/iot_usbh_cdc/README.md

@@ -1,38 +1,36 @@
-## USB Host CDC
+## iot_usbh_cdc Component
 
-This component implements a simple version of the USB CDC host function. It only retains the default control endpoint and bulk transfer endpoints, which streamlines the enumeration logic of the USB host. Users only need to bind the USB CDC device endpoint address to achieve fast Initialization. The component is suitable for the CDC-like vendor classes that require high startup speed.
+This component implements a simple version of the USB host CDC driver. The API is designed similarly to [ESP-IDF UART driver](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/uart.html), which can be used to replace the original UART driver to realize the update from UART to USB.
 
-The design logic of the component API is similar to the [ESP-IDF UART driver](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/uart.html) interface, which can directly replace the UART interface to realize the update of the original code from UART to USB.
+**Features:**
 
-### API Guide
+1. Similar API to ESP-IDF UART driver
+2. Support USB CDC device
+3. Support USB Vendor device
+4. Support USB CDC multiple interface
 
-1. Using `usbh_cdc_driver_install` to configure and start internal USB tasks, most importantly the CDC bulk endpoint addresses `bulk_in_ep_addr` and `bulk_out_ep_addr` is required to be specified for communication, and the transfer buffer memory size needs to be configured too. user is allowed to config descriptor details too through `bulk_in_ep` and `bulk_out_ep`.
+### User Guide
 
-```c
-/* @brief install usbh cdc driver with bulk endpoint configs and size of internal ringbuffer*/
-static usbh_cdc_config_t config = {
-    /* use default endpoint descriptor with user address */
-    .bulk_in_ep_addr = EXAMPLE_BULK_IN_EP_ADDR,
-    .bulk_out_ep_addr = EXAMPLE_BULK_OUT_EP_ADDR,
-    .rx_buffer_size = IN_RINGBUF_SIZE,
-    .tx_buffer_size = OUT_RINGBUF_SIZE,
-    .conn_callback = usb_connect_callback,
-    .disconn_callback = usb_disconnect_callback,
-};
+Please refer: https://docs.espressif.com/projects/esp-iot-solution/en/latest/usb/usb_host_iot_usbh_cdc.html
 
-/* install USB host CDC driver */
-usbh_cdc_driver_install(&config);
+### Add component to your project
 
-/* Waiting for USB device connected */
-usbh_cdc_wait_connect(portMAX_DELAY);
+Please use the component manager command `add-dependency` to add the `iot_usbh_cdc` to your project's dependency, during the `CMake` step the component will be downloaded automatically
+
+```
+idf.py add-dependency "espressif/iot_usbh_cdc=*"
 ```
 
-2. After the driver initialization, the internal state machine will automatically handle the hot plug of the USB, and user can also configure the hot plug related callback function `conn_callback` `disconn_callback`.
-3. `usbh_cdc_wait_connect` can be used to block task until USB CDC Device is connected or timeout.
-4. After successfully connected, the host will automatically receive USB data from CDC device to the internal `ringbuffer`, user can poll `usbh_cdc_get_buffered_data_len` to read buffered data size or register a receive callback to get notified when data is ready. Then `usbh_cdc_read_bytes` can be used to read buffered data out.
-5. `usbh_cdc_write_bytes` can be used to send data to USB Device. The data is first written to the internal transmit `ringbuffer`，then will be sent out during USB bus free.
-6. `usbh_cdc_driver_delete` can uninstall the USB driver completely to release all resources.
+### Examples
+
+Please use the component manager command `create-project-from-example` to create the project from the example template
+
+* USB Host CDC Basic Example
+
+```
+idf.py create-project-from-example "espressif/iot_usbh_cdc=*:usb_cdc_basic"
+```
 
-### CDC Multiple Interface Support
+Then the example will be downloaded in the current folder, you can check into it for build and flash.
 
-This component supports enable multiple CDC interfaces, each interface contains an IN and OUT endpoint. Users can communicate with the specified interfaces using `usbh_cdc_itf_read_bytes` and `usbh_cdc_itf_write_bytes`.
+> Or you can download examples from esp-iot-solution repository: [usb_cdc_basic](https://github.com/espressif/esp-iot-solution/tree/master/examples/usb/host/usb_cdc_basic).

components/usb/iot_usbh_cdc/idf_component.yml

@@ -1,10 +1,11 @@
-version: "0.2.1"
+version: "0.2.2"
 targets:
   - esp32s2
   - esp32s3
 description: Simple USB Host CDC driver maintained in esp-iot-solution
 url: https://github.com/espressif/esp-iot-solution/tree/master/components/usb/iot_usbh_cdc
 repository: https://github.com/espressif/esp-iot-solution/tree/master/components/usb/iot_usbh_cdc
+documentation: https://docs.espressif.com/projects/esp-iot-solution/en/latest/usb/usb_host_iot_usbh_cdc.html
 issues: https://github.com/espressif/esp-iot-solution/issues
 dependencies:
   idf: ">=4.4.1"

docs/Doxyfile

@@ -42,6 +42,7 @@ INPUT = \
     $(PROJECT_PATH)/components/sensors/sensor_hub/include/hal/light_sensor_hal.h \
     $(PROJECT_PATH)/components/sensors/sensor_hub/include/iot_sensor_hub.h \
     $(PROJECT_PATH)/components/sensors/sensor_hub/include/sensor_type.h \
+    $(PROJECT_PATH)/components/usb/iot_usbh_cdc/include/iot_usbh_cdc.h \
     $(PROJECT_PATH)/components/usb/usb_device_uvc/include/usb_device_uvc.h \
     $(PROJECT_PATH)/components/usb/usb_stream/include/usb_stream.h \
     $(PROJECT_PATH)/components/zero_detection/include/zero_detection.h \

docs/en/usb/usb_host_index.rst

@@ -6,4 +6,5 @@ USB Host Drivers
 .. toctree::
     :maxdepth: 1
 
-    USB UVC/UAC Host <usb_stream>
+    USB UVC/UAC Host <usb_stream>
+    USB CDC Host <usb_host_iot_usbh_cdc>

docs/en/usb/usb_host_iot_usbh_cdc.rst

@@ -0,0 +1,55 @@
+USB Host CDC 
+=====================
+
+:link_to_translation:`zh_CN:[中文]`
+
+The ``iot_usbh_cdc`` component implements a simple version of the USB host CDC driver. The API is designed similar like `ESP-IDF UART driver <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/uart.html>`_, which can be used to replace the original UART driver to realize the update from UART to USB.
+
+User Guide
+---------------
+
+1. Using ``usbh_cdc_driver_install`` to configure, user can simply configure the bulk endpoint address and the size of the internal ringbuffer, user can also configure the hot plug related callback function ``conn_callback`` ``disconn_callback``.
+
+.. code:: c
+
+    /* install usbh cdc driver with bulk endpoint configs and size of internal ringbuffer */
+    static usbh_cdc_config_t config = {
+        /* use default endpoint descriptor with user address */
+        .bulk_in_ep_addr = EXAMPLE_BULK_IN_EP_ADDR,
+        .bulk_out_ep_addr = EXAMPLE_BULK_OUT_EP_ADDR,
+        .rx_buffer_size = IN_RINGBUF_SIZE,
+        .tx_buffer_size = OUT_RINGBUF_SIZE,
+        .conn_callback = usb_connect_callback,
+        .disconn_callback = usb_disconnect_callback,
+    };
+    /* if user want to use multiple interfaces, can configure like this */
+    #if (EXAMPLE_BULK_ITF_NUM > 1)
+    config.itf_num = 2;
+    config.bulk_in_ep_addrs[1] = EXAMPLE_BULK_IN1_EP_ADDR;
+    config.bulk_out_ep_addrs[1] = EXAMPLE_BULK_OUT1_EP_ADDR;
+    config.rx_buffer_sizes[1] = IN_RINGBUF_SIZE;
+    config.tx_buffer_sizes[1] = OUT_RINGBUF_SIZE;
+    #endif
+
+    /* install USB host CDC driver */
+    usbh_cdc_driver_install(&config);
+
+    /* Waiting for USB device connected */
+    usbh_cdc_wait_connect(portMAX_DELAY);
+
+2. After the driver initialization, the internal state machine will automatically handle the hot plug of the USB.
+3. ``usbh_cdc_wait_connect`` can be used to block task until USB CDC Device is connected or timeout.
+4. After successfully connected, the host will automatically receive USB data from CDC device to the internal ``ringbuffer``, user can poll ``usbh_cdc_get_buffered_data_len`` to read buffered data size or register a receive callback to get notified when data is ready. Then ``usbh_cdc_read_bytes`` can be used to read buffered data out.
+5. ``usbh_cdc_write_bytes`` can be used to send data to USB Device. The data is first written to the internal transmit ``ringbuffer``，then will be sent out during USB bus free.
+6. ``usbh_cdc_driver_delete`` can uninstall the USB driver completely to release all resources.
+7. If config multiple CDC interfaces, each interface contains an IN and OUT endpoint. Users can communicate with the specified interfaces using ``usbh_cdc_itf_read_bytes`` and ``usbh_cdc_itf_write_bytes``.
+
+Examples
+-------------------------------
+
+:example:`usb/host/usb_cdc_basic`
+
+API Reference
+-------------------------------
+
+.. include-build-file:: inc/iot_usbh_cdc.inc

docs/zh_CN/usb/usb_host_index.rst

@@ -6,4 +6,5 @@ USB 主机驱动
 .. toctree::
     :maxdepth: 1
 
-    USB UVC/UAC 主机 <usb_stream>
+    USB UVC/UAC 主机 <usb_stream>
+    USB CDC 主机 <usb_host_iot_usbh_cdc>

docs/zh_CN/usb/usb_host_iot_usbh_cdc.rst

@@ -0,0 +1,55 @@
+USB 主机 CDC 
+=====================
+
+:link_to_translation:`en:[English]`
+
+``iot_usbh_cdc`` 组件实现了一个 USB 主机 CDC 驱动的简化版本。该 API 的设计类似于 `ESP-IDF UART 驱动程序 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/uart.html>`_，可在一些应用中替代 UART，快速实现从 UART 到 USB 的迁移。
+
+使用指南
+---------------
+
+1. 使用 ``usbh_cdc_driver_install`` 配置，用户可以简单配置 bulk 端点地址和内部 ringbuffer 的大小，除此之外，用户还可以配置热插拔相关的回调函数 ``conn_callback`` ``disconn_callback``：
+
+.. code:: c
+
+    /* 安装 USB 主机 CDC 驱动程序，配置 bulk 端点地址和内部 ringbuffer 的大小 */
+    static usbh_cdc_config_t config = {
+        /* use default endpoint descriptor with user address */
+        .bulk_in_ep_addr = EXAMPLE_BULK_IN_EP_ADDR,
+        .bulk_out_ep_addr = EXAMPLE_BULK_OUT_EP_ADDR,
+        .rx_buffer_size = IN_RINGBUF_SIZE,
+        .tx_buffer_size = OUT_RINGBUF_SIZE,
+        .conn_callback = usb_connect_callback,
+        .disconn_callback = usb_disconnect_callback,
+    };
+    /* 如果用户想要使用多个接口，可以像这样配置 */
+    #if (EXAMPLE_BULK_ITF_NUM > 1)
+    config.itf_num = 2;
+    config.bulk_in_ep_addrs[1] = EXAMPLE_BULK_IN1_EP_ADDR;
+    config.bulk_out_ep_addrs[1] = EXAMPLE_BULK_OUT1_EP_ADDR;
+    config.rx_buffer_sizes[1] = IN_RINGBUF_SIZE;
+    config.tx_buffer_sizes[1] = OUT_RINGBUF_SIZE;
+    #endif
+
+    /* 安装 USB 主机 CDC 驱动程序 */
+    usbh_cdc_driver_install(&config);
+
+    /* 等待 USB 设备连接 */
+    usbh_cdc_wait_connect(portMAX_DELAY);
+
+2. 驱动程序初始化后，内部状态机将自动处理 USB 的热插拔。
+3. ``usbh_cdc_wait_connect`` 可以用于阻塞任务，直到 USB CDC 设备连接或超时。
+4. 成功连接后，主机将自动从 CDC 设备接收 USB 数据到内部 ``ringbuffer``，用户可以轮询 ``usbh_cdc_get_buffered_data_len`` 以读取缓冲数据大小，或者注册接收回调以在数据准备就绪时得到通知。然后 ``usbh_cdc_read_bytes`` 可以用于读取缓冲数据。
+5. ``usbh_cdc_write_bytes`` 可以用于向 USB 设备发送数据。数据首先被写入内部传输 ``ringbuffer``，然后在 USB 总线空闲时发送出去。
+6. ``usbh_cdc_driver_delete`` 可以完全卸载 USB 驱动程序以释放所有资源。
+7. 如果配置多个 CDC 接口，每个接口都包含一个 IN 和 OUT 端点。用户可以使用 ``usbh_cdc_itf_read_bytes`` 和 ``usbh_cdc_itf_write_bytes`` 与指定的接口通信。
+
+示例代码
+-------------------------------
+
+:example:`usb/host/usb_cdc_basic`
+
+API 参考
+-------------------------------
+
+.. include-build-file:: inc/iot_usbh_cdc.inc