feat(usb_device_uvc): support deinitialization

closes #575

Author: YanKE01

components/usb/usb_device_uvc/CHANGELOG.md

@@ -1,5 +1,10 @@
 # ChangeLog
 
+## v1.2.0 2025-8-5
+
+* Support deinitialization.
+* Fix image format setting during initialization stage.
+
 ## v1.1.3 2025-7-21
 
 * Fix incorrect `_stridx` in UVC descriptors when using dual cameras. 

components/usb/usb_device_uvc/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.1.3"
+version: "1.2.0"
 targets:
   - esp32s2
   - esp32s3
@@ -13,7 +13,7 @@ issues: https://github.com/espressif/esp-iot-solution/issues
 dependencies:
   idf: ">=5.0"
   espressif/tinyusb:
-    version: ">=0.17.0~2"
+    version: ">=0.18.0~1"
   cmake_utilities: "*"
 examples:
   - path: ../../../examples/usb/device/usb_webcam

components/usb/usb_device_uvc/include/usb_device_uvc.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -89,11 +89,12 @@ esp_err_t uvc_device_init(void);
 
 /**
  * @brief Deinitialize the UVC device
- * @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
+ *         ESP_ERR_INVALID_STATE if the UVC device is not initialized, or event group is NULL
+ *
  */
-//esp_err_t uvc_device_deinit(void);
+esp_err_t uvc_device_deinit(void);
 
 #ifdef __cplusplus
 }

components/usb/usb_device_uvc/test_apps/main/usb_device_uvc_test.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -22,6 +22,7 @@ static const char *TAG = "usb_device_uvc_test";
 #define UVC_MAX_FRAMESIZE_SIZE     (60*1024)
 #define WIDTH   CONFIG_UVC_CAM1_FRAMESIZE_WIDTH
 #define HEIGHT  CONFIG_UVC_CAM1_FRAMESIZE_HEIGT
+#define TEST_COUNT (15)
 
 extern const unsigned char jpg_start[] asm("_binary_esp_1280_720_jpg_start");
 extern const unsigned char jpg_end[]   asm("_binary_esp_1280_720_jpg_end");
@@ -85,9 +86,12 @@ TEST_CASE("usb_device_uvc_test", "[usb_device_uvc]")
     };
     uvc_device_config(0, &config);
     uvc_device_init();
-    while (1) {
+    for (int i = 0; i < TEST_COUNT; i++) {
         vTaskDelay(1000 / portTICK_PERIOD_MS);
+        ESP_LOGI(TAG, "UVC Device Test: %d", i);
     }
+    uvc_device_deinit();
+    free(uvc_buffer);
 }
 
 static size_t before_free_8bit;

components/usb/usb_device_uvc/usb_device_uvc.c

@@ -1,12 +1,13 @@
 /*
- * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 #include <string.h>
 #include <inttypes.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
+#include "freertos/event_groups.h"
 #include "esp_timer.h"
 #include "esp_check.h"
 #if CONFIG_TINYUSB_RHPORT_HS
@@ -25,13 +26,24 @@ static const char *TAG = "usbd_uvc";
 #define UVC_CAM_NUM 1
 #endif
 
+#define TUSB_EVENT_EXIT         (1<<0)
+#define TUSB_EVENT_EXIT_DONE    (1<<1)
+#define UVC1_EVENT_EXIT         (1<<2)
+#define UVC1_EVENT_EXIT_DONE    (1<<3)
+#if CONFIG_UVC_SUPPORT_TWO_CAM
+#define UVC2_EVENT_EXIT         (1<<4)
+#define UVC2_EVENT_EXIT_DONE    (1<<5)
+#endif
+
 typedef struct {
     usb_phy_handle_t phy_hdl;
     bool uvc_init[UVC_CAM_NUM];
     uvc_format_t format[UVC_CAM_NUM];
     uvc_device_config_t user_config[UVC_CAM_NUM];
     TaskHandle_t uvc_task_hdl[UVC_CAM_NUM];
+    TaskHandle_t tusb_task_hdl;
     uint32_t interval_ms[UVC_CAM_NUM];
+    EventGroupHandle_t event_group;
 } uvc_device_t;
 
 static uvc_device_t s_uvc_device;
@@ -58,8 +70,15 @@ static inline uint32_t get_time_millis(void)
 static void tusb_device_task(void *arg)
 {
     while (1) {
+        EventBits_t uxBits = xEventGroupGetBits(s_uvc_device.event_group);
+        if (uxBits & TUSB_EVENT_EXIT) {
+            ESP_LOGI(TAG, "TUSB task exit");
+            break;
+        }
         tud_task();
     }
+    xEventGroupSetBits(s_uvc_device.event_group, TUSB_EVENT_EXIT_DONE);
+    vTaskDelete(NULL);
 }
 
 void tud_mount_cb(void)
@@ -110,6 +129,12 @@ static void video_task(void *arg)
     uvc_fb_t *pic = NULL;
 
     while (1) {
+        EventBits_t uxBits = xEventGroupGetBits(s_uvc_device.event_group);
+        if (uxBits & UVC1_EVENT_EXIT) {
+            ESP_LOGI(TAG, "UVC task exit");
+            break;
+        }
+
         if (!tud_video_n_streaming(0, 0)) {
             already_start = 0;
             frame_num = 0;
@@ -160,6 +185,9 @@ static void video_task(void *arg)
         tud_video_n_frame_xfer(0, 0, (void *)uvc_buffer, frame_len);
         ESP_LOGD(TAG, "frame %" PRIu32 " transfer start, size %" PRIu32, frame_num, frame_len);
     }
+
+    xEventGroupSetBits(s_uvc_device.event_group, UVC1_EVENT_EXIT_DONE);
+    vTaskDelete(NULL);
 }
 
 #if CONFIG_UVC_SUPPORT_TWO_CAM
@@ -175,6 +203,12 @@ static void video_task2(void *arg)
     uvc_fb_t *pic = NULL;
 
     while (1) {
+        EventBits_t uxBits = xEventGroupGetBits(s_uvc_device.event_group);
+        if (uxBits & UVC2_EVENT_EXIT) {
+            ESP_LOGI(TAG, "UVC2 task exit");
+            break;
+        }
+
         if (!tud_video_n_streaming(1, 0)) {
             already_start = 0;
             frame_num = 0;
@@ -225,6 +259,9 @@ static void video_task2(void *arg)
         tud_video_n_frame_xfer(1, 0, (void *)uvc_buffer, frame_len);
         ESP_LOGD(TAG, "frame %" PRIu32 " transfer start, size %" PRIu32, frame_num, frame_len);
     }
+
+    xEventGroupSetBits(s_uvc_device.event_group, UVC2_EVENT_EXIT_DONE);
+    vTaskDelete(NULL);
 }
 #endif
 
@@ -283,26 +320,38 @@ esp_err_t uvc_device_init(void)
     ESP_RETURN_ON_FALSE(s_uvc_device.uvc_init[1], ESP_ERR_INVALID_STATE, TAG, "uvc device 1 not init, if not use, please disable CONFIG_UVC_SUPPORT_TWO_CAM");
 #endif
 
-#ifdef CONFIG_FORMAT_MJPEG_CAM1
+#if CONFIG_FORMAT_MJPEG_CAM1
     s_uvc_device.format[0] = UVC_FORMAT_JPEG;
+#elif CONFIG_FORMAT_H264_CAM1
+    s_uvc_device.format[0] = UVC_FORMAT_H264;
 #endif
 
 #if CONFIG_UVC_SUPPORT_TWO_CAM
-#ifdef CONFIG_FORMAT_MJPEG_CAM2
+#if CONFIG_FORMAT_MJPEG_CAM2
     s_uvc_device.format[1] = UVC_FORMAT_JPEG;
+#elif CONFIG_FORMAT_H264_CAM2
+    s_uvc_device.format[1] = UVC_FORMAT_H264;
 #endif
 #endif
 
+    s_uvc_device.event_group = xEventGroupCreate();
+    if (s_uvc_device.event_group == NULL) {
+        ESP_LOGE(TAG, "Failed to create event group");
+        return ESP_FAIL;
+    }
+
     // init device stack on configured roothub port
     usb_phy_init();
     bool usb_init = tusb_init();
     if (!usb_init) {
         ESP_LOGE(TAG, "USB Device Stack Init Fail");
+        vEventGroupDelete(s_uvc_device.event_group);
+        s_uvc_device.event_group = NULL;
         return ESP_FAIL;
     }
 
     BaseType_t core_id = (CONFIG_UVC_TINYUSB_TASK_CORE < 0) ? tskNO_AFFINITY : CONFIG_UVC_TINYUSB_TASK_CORE;
-    xTaskCreatePinnedToCore(tusb_device_task, "TinyUSB", 4096, NULL, CONFIG_UVC_TINYUSB_TASK_PRIORITY, NULL, core_id);
+    xTaskCreatePinnedToCore(tusb_device_task, "TinyUSB", 4096, NULL, CONFIG_UVC_TINYUSB_TASK_PRIORITY, &s_uvc_device.tusb_task_hdl, core_id);
 #if (CFG_TUD_VIDEO)
     core_id = (CONFIG_UVC_CAM1_TASK_CORE < 0) ? tskNO_AFFINITY : CONFIG_UVC_CAM1_TASK_CORE;
     xTaskCreatePinnedToCore(video_task, "UVC", 4096, NULL, CONFIG_UVC_CAM1_TASK_PRIORITY, &s_uvc_device.uvc_task_hdl[0], core_id);
@@ -314,3 +363,58 @@ esp_err_t uvc_device_init(void)
     ESP_LOGI(TAG, "UVC Device Start, Version: %d.%d.%d", USB_DEVICE_UVC_VER_MAJOR, USB_DEVICE_UVC_VER_MINOR, USB_DEVICE_UVC_VER_PATCH);
     return ESP_OK;
 }
+
+esp_err_t uvc_device_deinit(void)
+{
+    ESP_RETURN_ON_FALSE(s_uvc_device.uvc_init[0], ESP_ERR_INVALID_STATE, TAG, "uvc device 0 not init");
+#if CONFIG_UVC_SUPPORT_TWO_CAM
+    ESP_RETURN_ON_FALSE(s_uvc_device.uvc_init[1], ESP_ERR_INVALID_STATE, TAG, "uvc device 1 not init, if not use, please disable CONFIG_UVC_SUPPORT_TWO_CAM");
+#endif
+    ESP_RETURN_ON_FALSE(s_uvc_device.event_group != NULL, ESP_ERR_INVALID_STATE, TAG, "event group is NULL");
+
+    // Stop UVC tasks first
+    xEventGroupSetBits(s_uvc_device.event_group, UVC1_EVENT_EXIT);
+    xEventGroupWaitBits(s_uvc_device.event_group, UVC1_EVENT_EXIT_DONE, pdTRUE, pdTRUE, portMAX_DELAY);
+#if CONFIG_UVC_SUPPORT_TWO_CAM
+    xEventGroupSetBits(s_uvc_device.event_group, UVC2_EVENT_EXIT);
+    xEventGroupWaitBits(s_uvc_device.event_group, UVC2_EVENT_EXIT_DONE, pdTRUE, pdTRUE, portMAX_DELAY);
+#endif
+
+    // Call user stop callbacks
+    if (s_uvc_device.user_config[0].stop_cb) {
+        s_uvc_device.user_config[0].stop_cb(s_uvc_device.user_config[0].cb_ctx);
+    }
+#if CONFIG_UVC_SUPPORT_TWO_CAM
+    if (s_uvc_device.user_config[1].stop_cb) {
+        s_uvc_device.user_config[1].stop_cb(s_uvc_device.user_config[1].cb_ctx);
+    }
+#endif
+
+    // Stop TinyUSB task
+    xEventGroupSetBits(s_uvc_device.event_group, TUSB_EVENT_EXIT);
+    EventBits_t bits = xEventGroupWaitBits(s_uvc_device.event_group, TUSB_EVENT_EXIT_DONE, pdTRUE, pdTRUE, pdMS_TO_TICKS(5000));
+    if (!(bits & TUSB_EVENT_EXIT_DONE)) {
+        ESP_LOGW(TAG, "TinyUSB task exit timeout (5s), force delete");
+        if (s_uvc_device.tusb_task_hdl) {
+            vTaskDelete(s_uvc_device.tusb_task_hdl);
+            s_uvc_device.tusb_task_hdl = NULL;
+        }
+    }
+
+    // Clean up event group
+    vEventGroupDelete(s_uvc_device.event_group);
+    s_uvc_device.event_group = NULL;
+
+    // Teardown USB stack
+    tusb_teardown();
+    if (s_uvc_device.phy_hdl) {
+        usb_del_phy(s_uvc_device.phy_hdl);
+        s_uvc_device.phy_hdl = NULL;
+    }
+
+    // Reset initialization flags
+    memset(s_uvc_device.uvc_init, 0, sizeof(s_uvc_device.uvc_init));
+
+    ESP_LOGI(TAG, "UVC Device Deinit");
+    return ESP_OK;
+}

examples/usb/device/usb_dual_uvc_device/CMakeLists.txt

@@ -28,10 +28,12 @@ endif()
 set(OUTPUT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/spiffs")
 file(MAKE_DIRECTORY ${OUTPUT_DIR})
 
-file(GLOB AVI_FILES "${OUTPUT_DIR}/*.avi")
-if(NOT AVI_FILES)
-    file(DOWNLOAD ${URL} ${OUTPUT_DIR}/p4_introduce.avi)
-    message(STATUS "File downloaded from ${URL} to: ${OUTPUT_DIR}/p4_introduce.avi")
-else()
-    message(STATUS "AVI file(s) already exist(s) in the output directory: ${OUTPUT_DIR}")
+set(OUTPUT_FILE "${OUTPUT_DIR}/p4_introduce.avi")
+
+if(EXISTS ${OUTPUT_FILE})
+    file(REMOVE ${OUTPUT_FILE})
+    message(STATUS "Old AVI file removed: ${OUTPUT_FILE}")
 endif()
+
+file(DOWNLOAD ${URL} ${OUTPUT_FILE})
+message(STATUS "File downloaded from ${URL} to: ${OUTPUT_FILE}")

examples/usb/device/usb_dual_uvc_device/main/idf_component.yml

@@ -5,14 +5,12 @@ targets:
   - esp32p4
 dependencies:
   espressif/esp32_s3_usb_otg:
-    version: "^1.5.1"
+    version: "^2.0.0"
     rules:
       - if: "target in [esp32s3]"
   usb_device_uvc:
-    version: "1.1.*"
+    version: "1.2.*"
     override_path: "../../../../../components/usb/usb_device_uvc"
   avi_player:
     version: "2.*"
     override_path: "../../../../../components/avi_player"
-  lvgl/lvgl: #temp to workaround bsp issue
-    version: "9.2.0"

examples/usb/device/usb_lcd_display/main/idf_component.yml

@@ -8,3 +8,6 @@ dependencies:
   esp_lcd_usb_display:
     version: "*"
     override_path: "../../../../../components/display/lcd/esp_lcd_usb_display"
+  usb_device_uvc:
+    version: "*"
+    override_path: "../../../../../components/usb/usb_device_uvc"

examples/usb/device/usb_webcam/main/idf_component.yml

@@ -17,5 +17,5 @@ dependencies:
     override_path: "../eyes_show"
   cmake_utilities: "*"
   usb_device_uvc:
-    version: "1.1.*"
+    version: "1.2.*"
     override_path: "../../../../../components/usb/usb_device_uvc"