Merge branch 'docs/usb_device_uvc' into 'master'

docs: add usb_device_uvc user guide Closes AEG-1007 See merge request ae_group/esp-iot-solution!909
espressif · Dec 7, 2023 · 13adff8 · 13adff8
2 parents a6a3965 + 3d3d8b8
commit 13adff8
Show file tree

Hide file tree

Showing 35 changed files with 202 additions and 41 deletions.
diff --git a/.gitlab/ci/rules.yml b/.gitlab/ci/rules.yml
@@ -224,8 +224,8 @@
   - "components/display/touch_panel/touch_panel.h"
   - "components/knob/iot_knob.h"
   - "components/led/led_indicator/include/led_indicator.h"
-  - "components/motor/esp_sensorless_bldc_control/control/include/bldc_control_param.h"
   - "components/motor/esp_sensorless_bldc_control/control/include/bldc_control.h"
+  - "components/motor/esp_sensorless_bldc_control/control/include/bldc_control_param.h"
   - "components/motor/esp_sensorless_bldc_control/user_cfg/bldc_user_cfg.h"
   - "components/motor/servo/include/iot_servo.h"
   - "components/openai/include/OpenAI.h"
@@ -234,8 +234,8 @@
   - "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/usb_device_uvc/include/usb_device_uvc.h"
   - "components/usb/usb_stream/include/usb_stream.h"
-  - "components/bluetooth/ble_conn_mgr/include/esp_ble_conn_mgr.h"
   - "components/zero_detection/include/zero_detection.h"
 
 # examples folder, in the alphabetic order

diff --git a/components/usb/usb_device_uvc/CHANGELOG.md b/components/usb/usb_device_uvc/CHANGELOG.md
@@ -1,5 +1,9 @@
 # ChangeLog
 
+## v0.0.2 2023-12-06
+
+* Add documentation documentation: https://docs.espressif.com/projects/esp-iot-solution/en/latest/usb/usb_device_uvc.html
+
 ## v0.0.1 Init version
 
 * Support Isochronous and Bulk transfer

diff --git a/components/usb/usb_device_uvc/idf_component.yml b/components/usb/usb_device_uvc/idf_component.yml
@@ -1,10 +1,11 @@
-version: "0.0.1"
+version: "0.0.2"
 targets:
   - esp32s2
   - esp32s3
 
 description: USB Device UVC, Streaming Video to Host
 url: https://github.com/espressif/esp-iot-solution/tree/master/components/usb/usb_device_uvc
+documentation: https://docs.espressif.com/projects/esp-iot-solution/en/latest/usb/usb_device_uvc.html
 repository: https://github.com/espressif/esp-iot-solution.git
 issues: https://github.com/espressif/esp-iot-solution/issues
 

diff --git a/components/usb/usb_device_uvc/include/usb_device_uvc.h b/components/usb/usb_device_uvc/include/usb_device_uvc.h
@@ -14,36 +14,61 @@
 extern "C" {
 #endif
 
+/**
+ * @brief UVC format
+ */
 typedef enum {
-    UVC_FORMAT_JPEG,
+    UVC_FORMAT_JPEG,            /*!< JPEG format */
 } uvc_format_t;
 
+/**
+ * @brief Frame buffer structure
+ */
 typedef struct {
-    uint8_t * buf;              /*!< Pointer to the pixel data */
+    uint8_t *buf;               /*!< Pointer to the frame data */
     size_t len;                 /*!< Length of the buffer in bytes */
-    size_t width;               /*!< Width of the buffer in pixels */
-    size_t height;              /*!< Height of the buffer in pixels */
-    uvc_format_t format;        /*!< Format of the pixel data */
-    struct timeval timestamp;   /*!< Timestamp since boot of the first DMA buffer of the frame */
+    size_t width;               /*!< Width of the image frame in pixels */
+    size_t height;              /*!< Height of the image frame in pixels */
+    uvc_format_t format;        /*!< Format of the frame data */
+    struct timeval timestamp;   /*!< Timestamp since boot of the frame */
 } uvc_fb_t;
 
+/**
+ * @brief type of callback function when host open the UVC device
+ */
 typedef esp_err_t (*uvc_input_start_cb_t)(uvc_format_t format, int width, int height, int rate, void *cb_ctx);
+
+/**
+ * @brief type of callback function when host request a new frame buffer
+ */
 typedef uvc_fb_t* (*uvc_input_fb_get_cb_t)(void *cb_ctx);
+
+/**
+ * @brief type of callback function when the frame buffer is no longer used
+ */
 typedef void (*uvc_input_fb_return_cb_t)(uvc_fb_t *fb, void *cb_ctx);
+
+/**
+ * @brief type of callback function when host close the UVC device
+ */
 typedef void (*uvc_input_stop_cb_t)(void *cb_ctx);
 
+/**
+ * @brief Configuration for the UVC device
+ */
 typedef struct {
     uint8_t *uvc_buffer;                   /*!< UVC transfer buffer */
     uint32_t uvc_buffer_size;              /*!< UVC transfer buffer size, should bigger than one frame size */
-    uvc_input_start_cb_t start_cb;         /*!< callback function for UVC start */
-    uvc_input_fb_get_cb_t fb_get_cb;       /*!< callback function for UVC get frame buffer */
-    uvc_input_fb_return_cb_t fb_return_cb; /*!< callback function for UVC return frame buffer */
-    uvc_input_stop_cb_t stop_cb;           /*!< callback function for UVC stop */
-    void *cb_ctx;                          /*!< callback context */
+    uvc_input_start_cb_t start_cb;         /*!< callback function of host open the UVC device with the specific format and resolution */
+    uvc_input_fb_get_cb_t fb_get_cb;       /*!< callback function of host request a new frame buffer */
+    uvc_input_fb_return_cb_t fb_return_cb; /*!< callback function of the frame buffer is no longer used */
+    uvc_input_stop_cb_t stop_cb;           /*!< callback function of host close the UVC device */
+    void *cb_ctx;                          /*!< callback context, for user specific usage */
 } uvc_device_config_t;
 
 /**
- * @brief Initialize the UVC device
+ * @brief Initialize the UVC device, after this function is called, the UVC device will be visible to the host
+ *       and the host can open the UVC device with the specific format and resolution.
  *
  * @param config Configuration for the UVC device
  *
@@ -55,7 +80,7 @@ esp_err_t uvc_device_init(uvc_device_config_t *config);
 
 /**
  * @brief Deinitialize the UVC device
- * TODO: This function is not implemented yet because tinyusb does not support deinitialization
+ * @note  This function is not implemented yet because tinyusb does not support deinitialization
  * @return ESP_OK on success
  *         ESP_FAIL if the UVC device could not be deinitialized
  */

diff --git a/docs/Doxyfile b/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/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 \
 

diff --git a/docs/convert_to_rst.sh b/docs/convert_to_rst.sh
diff --git a/docs/en/usb/index.rst b/docs/en/usb/index.rst
@@ -16,4 +16,5 @@ USB Host & Device
     USB Device Solution <usb_device_solutions>
     USB Self Power Device <usb_device_self_power>
     USB Device Set Const COM <usb_device_const_COM>
+    usb_host_index
     usb_driver_index
diff --git a/docs/en/usb/usb_device_const_COM.rst b/docs/en/usb/usb_device_const_COM.rst
@@ -2,6 +2,8 @@
 Prevent Windows from incrementing COM numbers based on USB device serial number
 --------------------------------------------------------------------------------
 
+:link_to_translation:`zh_CN:[中文]`
+
 Due to the fact that any device connected to a Windows PC is identified by its VID (Vendor ID), PID (Product ID), and Serial number. If any of these three parameters undergo a change, the PC will detect new hardware and assigns it to a different COM port. For more details, please refer to the `Windows USB device registry entries <https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/usb-device-specific-registry-settings>`_.
 
 In the ESP ROM Code, the configuration of USB descriptors is as follows:

diff --git a/docs/en/usb/usb_device_self_power.rst b/docs/en/usb/usb_device_self_power.rst
@@ -2,6 +2,8 @@
 Self-Powered USB Device Solutions
 ----------------------------------
 
+:link_to_translation:`zh_CN:[中文]`
+
 According to the USB protocol requirements, self-powered USB devices must detect the 5V VBUS voltage to determine if the device is unplugged, thereby enabling hot-plugging. For host-powered devices, since the device shuts down immediately when the host VBUS is disconnected, there is no need to implement this logic.
 
 There are generally two methods for USB device VBUS detection: detection by USB PHY hardware, or \ **detection by software with the help of ADC/GPIO**\.

diff --git a/docs/en/usb/usb_device_solutions.rst b/docs/en/usb/usb_device_solutions.rst
@@ -1,3 +1,5 @@
 
 USB Device Solution
 --------------------
+
+:link_to_translation:`zh_CN:[中文]`
diff --git a/docs/en/usb/usb_device_uvc.rst b/docs/en/usb/usb_device_uvc.rst
@@ -0,0 +1,85 @@
+USB Device UVC
+====================
+
+:link_to_translation:`zh_CN:[中文]`
+
+``usb_device_uvc`` is a USB ``UVC`` device driver for ESP32-S2/ESP32-S3, which supports streaming JPEG frames to the USB Host. User can wrapper the Camera or any devices as a UVC standard device through the callback functions.
+
+Features:
+
+1. Support video stream through the UVC Stream interface
+
+2. Support both ``Isochronous`` and ``Bulk`` mode
+
+3. Support multiple resolutions and frame rates
+
+Add component to your project
+-------------------------------
+
+Please use the component manager command ``add-dependency`` to add the ``usb_device_uvc`` to your project's dependency, during the ``CMake`` step the component will be downloaded automatically
+
+.. code:: sh
+
+    idf.py add-dependency "espressif/usb_device_uvc=*"
+
+User Reference
+-------------------------------
+
+The component provides only one API to configure the UVC device. As the driver based on the ``TinyUSB`` stack, the deinit API is not provided. 
+
+.. code:: c
+
+    #include "usb_device_uvc.h"
+
+    static esp_err_t camera_start_cb(uvc_format_t format, int width, int height, int rate, void *cb_ctx)
+    {
+        // user can initialize the camera here
+        // camera should be initialized with the given format, width, height and frame rate
+        return ESP_OK;
+    }
+
+    static void camera_stop_cb(void *cb_ctx)
+    {
+        //user code
+        return;
+    }
+
+    static uvc_fb_t* camera_fb_get_cb(void *cb_ctx)
+    {
+        // user code to return a image frame buffer
+        // camera should prepare next frame, and return the frame buffer
+        return uvc_fb;
+    }
+
+    static void camera_fb_return_cb(uvc_fb_t *fb, void *cb_ctx)
+    {
+        // the frame buffer is returned after it is copied to the transfer buffer
+        // user code to recycle the frame buffer
+        return;
+    }
+
+    //the buffer is used to store the data to be sent to the host
+    const size_t buff_size = 30 * 1024;
+    uint8_t *uvc_buffer = (uint8_t *)heap_caps_malloc(buff_size, MALLOC_CAP_DEFAULT);
+    assert(uvc_buffer != NULL);
+
+    uvc_device_config_t config = {
+        .uvc_buffer = uvc_buffer,
+        .uvc_buffer_size = buff_size,
+        .start_cb = camera_start_cb,
+        .fb_get_cb = camera_fb_get_cb,
+        .fb_return_cb = camera_fb_return_cb,
+        .stop_cb = camera_stop_cb,
+    };
+
+    ESP_ERROR_CHECK(uvc_device_init(&config));
+
+Examples
+-------------------------------
+
+:example:`usb/device/usb_webcam`
+
+API Reference
+-------------------------------
+
+.. include-build-file:: inc/usb_device_uvc.inc
diff --git a/docs/en/usb/usb_driver_index.rst b/docs/en/usb/usb_driver_index.rst
@@ -1,9 +1,9 @@
-USB Class Drivers
+USB Device Drivers
 *********************
 
 :link_to_translation:`zh_CN:[中文]`
 
 .. toctree::
     :maxdepth: 1
 
-    USB Host UVC/UAC <usb_stream>
+    USB UVC Device <usb_device_uvc>
diff --git a/docs/en/usb/usb_host_index.rst b/docs/en/usb/usb_host_index.rst
@@ -0,0 +1,9 @@
+USB Host Drivers
+*********************
+
+:link_to_translation:`zh_CN:[中文]`
+
+.. toctree::
+    :maxdepth: 1
+
+    USB UVC/UAC Host <usb_stream>
diff --git a/docs/en/usb/usb_host_solutions.rst b/docs/en/usb/usb_host_solutions.rst
@@ -2,6 +2,8 @@
 USB Host Solution
 ------------------
 
+:link_to_translation:`zh_CN:[中文]`
+
 ESP32-S2/S3 and similar chips come with built-in USB-OTG peripherals, supporting the connection of various type of USB devices through the USB interface. The following provides an overview of the USB Host solutions supported by the ESP32-S2/S3 chips.
 
 ESP USB Camera Video Solution

diff --git a/docs/en/usb/usb_otg.rst b/docs/en/usb/usb_otg.rst
@@ -2,6 +2,8 @@
 USB-OTG Peripheral Introduction
 --------------------------------
 
+:link_to_translation:`zh_CN:[中文]`
+
 The ESP32-S2/S3 and other chips come with built-in USB On-The-Go (USB-OTG) peripherals. They include a USB controller and USB PHY, supporting connection to a PC via a USB cable, enabling USB Host and USB Device functionalities.
 
 USB-OTG Transfer Rate

diff --git a/docs/en/usb/usb_overview.rst b/docs/en/usb/usb_overview.rst
@@ -2,6 +2,8 @@
 **ESP USB Peripheral Introduction**
 ====================================
 
+:link_to_translation:`zh_CN:[中文]`
+
 USB Introduction
 -----------------
 

diff --git a/docs/en/usb/usb_phy.rst b/docs/en/usb/usb_phy.rst
@@ -2,6 +2,8 @@
 USB PHY/Transceiver Introduction
 ---------------------------------
 
+:link_to_translation:`zh_CN:[中文]`
+
 The function of the USB Full-speed PHY/Transceiver is to convert the digital signals from the USB controller into USB bus signal levels, providing bus driving capability, and detecting receive errors, among other functions. Chips like ESP32-S2/S3 have a built-in USB Full-speed PHY, allowing users to directly use the USB D+ D- pins specified by the chip for communication with an external USB system. Additionally, ESP32-S2/S3 retains an external PHY extension interface, allowing users to connect an external PHY when needed.
 
 Use the internal PHY

diff --git a/docs/en/usb/usb_serial_jtag.rst b/docs/en/usb/usb_serial_jtag.rst
@@ -2,6 +2,8 @@
 USB-Serial-JTAG Peripheral Introduction
 -----------------------------------------
 
+:link_to_translation:`zh_CN:[中文]`
+
 The ESP32-S3/C3 chips come with a built-in USB-Serial-JTAG peripheral, which includes a USB-to-serial converter and a USB-to-JTAG converter. It supports connection to a PC via a USB cable, enabling functions such as firmware downloading, debugging, and printing system logs. The internal structure of the USB-Serial-JTAG peripheral can be referred to in the `ESP32-C3 Technical Reference Manual - USB Serial/JTAG Controller <https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf>`_\ .
 
 USB-Serial-JTAG  peripheral driver

diff --git a/docs/en/usb/usb_stream.rst b/docs/en/usb/usb_stream.rst
@@ -1,5 +1,6 @@
 USB Stream Component
 =====================
+
 :link_to_translation:`zh_CN:[中文]`
 
 ``usb_stream`` is an USB ``UVC`` + ``UAC`` host driver for ESP32-S2/ESP32-S3, which supports read/write/control multimedia streaming from usb device. For example, at most one UVC + one Microphone + one Speaker streaming can be supported at the same time.
@@ -139,7 +140,9 @@ ESP32-S2 ECO0 Chip SPI screen jitter when work with usb camera
 Examples
 ---------
 
-:example:`usb/host/usb_camera_mic_spk`
+1. :example:`usb/host/usb_camera_mic_spk`
+2. :example:`usb/host/usb_camera_lcd_display`
+3. :example:`usb/host/usb_audio_player`
 
 API Reference
 ---------------------

diff --git a/docs/en/usb/usb_vid_pid.rst b/docs/en/usb/usb_vid_pid.rst
@@ -1,6 +1,8 @@
 USB VID and PID
 -----------------
 
+:link_to_translation:`zh_CN:[中文]`
+
 VID and PID are unique identifiers for USB devices, used to distinguish between different USB devices. Generally, VID and PID are assigned by USB-IF, which is the USB Implementers Forum. 
 
 In the following scenarios, you can exempt from applying for VID and PID

diff --git a/docs/zh_CN/usb/index.rst b/docs/zh_CN/usb/index.rst
@@ -16,4 +16,5 @@ USB 主机 & 设备
     USB Device 方案 <usb_device_solutions>
     USB 自供电设备解决方案 <usb_device_self_power>
     USB 设备序列号递增 COM 编号 <usb_device_const_COM>
-    usb_driver_index 
+    usb_host_index
+    usb_driver_index
diff --git a/docs/zh_CN/usb/usb_device_const_COM.rst b/docs/zh_CN/usb/usb_device_const_COM.rst
@@ -2,6 +2,8 @@
 阻止 Windows 依据 USB 设备序列号递增 COM 编号
 ---------------------------------------------
 
+:link_to_translation:`en:[English]`
+
 由于任何连接到 Windows PC 的设备都通过其 VID、PID 和 Serial 号进行识别。如果这 3 个参数中的任何一个发生了变化，那么 PC 将检测到新的硬件，并与该设备关联一个不同的 COM 端口，详情请参考 `Windows USB device registry entries <https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/usb-device-specific-registry-settings>`_\ 。
 
 ESP ROM Code 中对 USB 描述符配置如下：

diff --git a/docs/zh_CN/usb/usb_device_self_power.rst b/docs/zh_CN/usb/usb_device_self_power.rst
@@ -2,6 +2,8 @@
 自供电 USB 设备解决方案
 -----------------------
 
+:link_to_translation:`en:[English]`
+
 按照 USB 协议要求，USB 自供电设备必须通过检测 5V VBUS 电压来判断设备是否拔出，进而实现热插拔。对于主机供电设备，由于主机 VBUS 断电之后，设备直接掉电关机，无需实现该逻辑。
 
 USB 设备 VBUS 检测方法一般有两种方法：由 USB PHY 硬件检测，或\ **借助 ADC/GPIO 由软件检测**\ 。

diff --git a/docs/zh_CN/usb/usb_device_solutions.rst b/docs/zh_CN/usb/usb_device_solutions.rst
@@ -1,3 +1,5 @@
 
 USB Device 方案
 ---------------
+
+:link_to_translation:`en:[English]`