feature(tinyusb): Added VBUS monitor api and structs

Author: roma-jam

device/esp_tinyusb/CMakeLists.txt

@@ -1,3 +1,5 @@
+idf_build_get_property(target IDF_TARGET)
+
 set(srcs
     "descriptors_control.c"
     "tinyusb.c"
@@ -43,6 +45,13 @@ if(CONFIG_TINYUSB_NET_MODE_NCM)
          )
 endif() # CONFIG_TINYUSB_NET_MODE_NCM
 
+# Software VBUS monitoring is available only on esp32p4
+if(${target} STREQUAL "esp32p4")
+    list(APPEND srcs
+        "tinyusb_vbus_monitor.c"
+        )
+endif() # esp32p4
+
 idf_component_register(SRCS ${srcs}
                        INCLUDE_DIRS "include"
                        PRIV_INCLUDE_DIRS "include_private"

device/esp_tinyusb/include/tinyusb.h

@@ -51,6 +51,7 @@ typedef struct {
                                                 The voltage divider output should be (0.75 * Vdd) if VBUS is 4.4V (lowest valid voltage at device port).
                                                 The comparator thresholds should be set with hysteresis: 4.35V (falling edge) and 4.75V (raising edge). */
     int vbus_monitor_io;                      /*!< GPIO for VBUS monitoring, 3.3 V tolerant (use a comparator or a resistior divider to detect the VBUS valid condition). Ignored if not self_powered. */
+    uint32_t vbus_monitor_debounce_ms;        /*!< Debounce delay for VBUS monitoring in milliseconds. Default is 250 ms. Relevant only for ESP32P4 and ignored if not self_powered. */
 } tinyusb_phy_config_t;
 
 /**

device/esp_tinyusb/include/tinyusb_default_config.h

@@ -63,54 +63,58 @@ extern "C" {
 #define TINYUSB_DEFAULT_TASK_SIZE      4096
 // Default priority for task used in TinyUSB task creation
 #define TINYUSB_DEFAULT_TASK_PRIO      5
+// Default VBUS debounce time in milliseconds
+#define TINYUSB_DEFAULT_DEBOUNCE_MS    250
 
-#define TINYUSB_CONFIG_FULL_SPEED(event_hdl, arg)       \
-    (tinyusb_config_t) {                                \
-        .port = TINYUSB_PORT_FULL_SPEED_0,              \
-        .phy = {                                        \
-            .skip_setup = false,                        \
-            .self_powered = false,                      \
-            .vbus_monitor_io = -1,                      \
-        },                                              \
-        .task = TINYUSB_TASK_DEFAULT(),                 \
-        .descriptor = {                                 \
-            .device = NULL,                             \
-            .qualifier = NULL,                          \
-            .string = NULL,                             \
-            .string_count = 0,                          \
-            .full_speed_config = NULL,                  \
-            .high_speed_config = NULL,                  \
-        },                                              \
-        .event_cb = (event_hdl),                        \
-        .event_arg = (arg),                             \
+#define TINYUSB_CONFIG_FULL_SPEED(event_hdl, arg)                               \
+    (tinyusb_config_t) {                                                        \
+        .port = TINYUSB_PORT_FULL_SPEED_0,                                      \
+        .phy = {                                                        \
+            .skip_setup = false,                                        \
+            .self_powered = false,                                      \
+            .vbus_monitor_io = -1,                                      \
+            .vbus_monitor_debounce_ms = TINYUSB_DEFAULT_DEBOUNCE_MS,    \
+        },                                                              \
+        .task = TINYUSB_TASK_DEFAULT(),                                 \
+        .descriptor = {                                                 \
+            .device = NULL,                                             \
+            .qualifier = NULL,                                          \
+            .string = NULL,                                             \
+            .string_count = 0,                                          \
+            .full_speed_config = NULL,                                  \
+            .high_speed_config = NULL,                                  \
+        },                                                              \
+        .event_cb = (event_hdl),                                        \
+        .event_arg = (arg),                                             \
     }
 
-#define TINYUSB_CONFIG_HIGH_SPEED(event_hdl, arg)       \
-    (tinyusb_config_t) {                                \
-        .port = TINYUSB_PORT_HIGH_SPEED_0,              \
-        .phy = {                                        \
-            .skip_setup = false,                        \
-            .self_powered = false,                      \
-            .vbus_monitor_io = -1,                      \
-        },                                              \
-        .task = TINYUSB_TASK_DEFAULT(),                 \
-        .descriptor = {                                 \
-            .device = NULL,                             \
-            .qualifier = NULL,                          \
-            .string = NULL,                             \
-            .string_count = 0,                          \
-            .full_speed_config = NULL,                  \
-            .high_speed_config = NULL,                  \
-        },                                              \
-        .event_cb = (event_hdl),                        \
-        .event_arg = (arg),                             \
+#define TINYUSB_CONFIG_HIGH_SPEED(event_hdl, arg)                       \
+    (tinyusb_config_t) {                                                \
+        .port = TINYUSB_PORT_HIGH_SPEED_0,                              \
+        .phy = {                                                        \
+            .skip_setup = false,                                        \
+            .self_powered = false,                                      \
+            .vbus_monitor_io = -1,                                      \
+            .vbus_monitor_debounce_ms = TINYUSB_DEFAULT_DEBOUNCE_MS,    \
+        },                                                              \
+        .task = TINYUSB_TASK_DEFAULT(),                                 \
+        .descriptor = {                                                 \
+            .device = NULL,                                             \
+            .qualifier = NULL,                                          \
+            .string = NULL,                                             \
+            .string_count = 0,                                          \
+            .full_speed_config = NULL,                                  \
+            .high_speed_config = NULL,                                  \
+        },                                                              \
+        .event_cb = (event_hdl),                                        \
+        .event_arg = (arg),                                             \
     }
 
-#define TINYUSB_TASK_DEFAULT()                          \
-    (tinyusb_task_config_t) {                           \
-        .size = TINYUSB_DEFAULT_TASK_SIZE,              \
-        .priority = TINYUSB_DEFAULT_TASK_PRIO,          \
-        .xCoreID = TINYUSB_DEFAULT_TASK_AFFINITY,       \
+#define TINYUSB_TASK_DEFAULT()                                          \
+    (tinyusb_task_config_t) {                                           \
+        .size = TINYUSB_DEFAULT_TASK_SIZE,                              \
+        .priority = TINYUSB_DEFAULT_TASK_PRIO,                          \
+        .xCoreID = TINYUSB_DEFAULT_TASK_AFFINITY,                       \
     }
 
 /**

device/esp_tinyusb/include_private/tinyusb_task.h

@@ -8,6 +8,7 @@
 
 #include "esp_err.h"
 #include "tinyusb.h"
+#include "tinyusb_vbus_monitor.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -42,7 +43,10 @@ esp_err_t tinyusb_task_check_config(const tinyusb_task_config_t *task_cfg);
  *    - ESP_ERR_NO_MEM if memory allocation failed
  *    - ESP_OK if TinyUSB Task initialized successfully
  */
-esp_err_t tinyusb_task_start(tinyusb_port_t port, const tinyusb_task_config_t *task_cfg, const tinyusb_desc_config_t *desc_cfg);
+esp_err_t tinyusb_task_start(tinyusb_port_t port,
+                             const tinyusb_task_config_t *task_cfg,
+                             const tinyusb_desc_config_t *desc_cfg,
+                             const tinyusb_vbus_monitor_config_t *vbus_monitor_cfg);
 
 /**
  * @brief Stops TinyUSB Task

device/esp_tinyusb/include_private/tinyusb_vbus_monitor.h

@@ -0,0 +1,44 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include "tinyusb.h"
+#include "driver/gpio.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+    gpio_num_t  gpio_num;          /*!< GPIO number used for VBUS monitoring, 3.3 V tolerant */
+    uint32_t    debounce_delay_ms; /*!< Debounce delay in milliseconds */
+} tinyusb_vbus_monitor_config_t;
+
+/**
+ * @brief Initialize VBUS monitoring on the specified GPIO
+ *
+ * Note:
+ * - This function should be called after tusb_init() when GOTGCTL register is initialized
+ * - This is a single-threaded implementation, so only one instance of VBUS monitoring is supported
+ *
+ * @param config VBUS monitoring configuration
+ *
+ * @return
+ *    - ESP_ERR_INVALID_ARG if config is NULL
+ *    - ESP_OK if VBUS monitoring was initialized successfully
+ */
+esp_err_t tinyusb_vbus_monitor_init(tinyusb_vbus_monitor_config_t *config);
+
+/**
+ * @brief Deinitialize VBUS monitoring
+ */
+void tinyusb_vbus_monitor_deinit(void);
+
+#ifdef __cplusplus
+}
+#endif

device/esp_tinyusb/tinyusb.c

@@ -100,6 +100,17 @@ static esp_err_t tinyusb_check_config(const tinyusb_config_t *config)
     ESP_RETURN_ON_FALSE(config->port != TINYUSB_PORT_0, ESP_ERR_INVALID_ARG, TAG, "USB PHY support for OTG1.1 has not been implemented, please update your esp-idf");
 #endif // ESP-IDF supports OTG1.1 peripheral
 #endif // CONFIG_IDF_TARGET_ESP32P4
+
+    // Device is self powered
+    if (config->phy.self_powered) {
+        // VBUS monitoring GPIO must be valid
+        ESP_RETURN_ON_FALSE(config->phy.vbus_monitor_io >= GPIO_NUM_0 && config->phy.vbus_monitor_io < GPIO_NUM_MAX, ESP_ERR_INVALID_ARG, TAG, "VBUS monitor GPIO must be a valid GPIO number when self_powered is true");
+#if (CONFIG_IDF_TARGET_ESP32P4)
+        if (config->port == TINYUSB_PORT_HIGH_SPEED_0) {
+            ESP_RETURN_ON_FALSE(config->phy.vbus_monitor_debounce_ms > 0, ESP_ERR_INVALID_ARG, TAG, "VBUS monitor debounce time must be greater than 0 when self_powered is true");
+        }
+#endif // CONFIG_IDF_TARGET_ESP32P4
+    }
     return ESP_OK;
 }
 
@@ -110,32 +121,55 @@ esp_err_t tinyusb_driver_install(const tinyusb_config_t *config)
 
     esp_err_t ret;
     usb_phy_handle_t phy_hdl = NULL;
+
+    tinyusb_vbus_monitor_config_t vbus_cfg = {
+        .gpio_num = GPIO_NUM_NC,                /*!< Default: Not connected */
+        .debounce_delay_ms = 0,                 /*!< Default: No debounce */
+    };
+
     if (!config->phy.skip_setup) {
         // Configure USB PHY
         usb_phy_config_t phy_conf = {
-            .controller = USB_PHY_CTRL_OTG,
-            .target = USB_PHY_TARGET_INT,
-            .otg_mode = USB_OTG_MODE_DEVICE,
-            .otg_speed = USB_PHY_SPEED_FULL,
+            .controller = USB_PHY_CTRL_OTG,     /*!< OTG controller */
+            .target = USB_PHY_TARGET_INT,       /*!< Internal PHY */
+            .otg_mode = USB_OTG_MODE_DEVICE,    /*!< OTG mode: Device */
+            .otg_speed = USB_PHY_SPEED_FULL,    /*!< Default: Full speed */
+            .otg_io_conf = NULL,                /*!< Default: No OTG IOs configuration */
         };
+        // Prepare the OTG IOs configuration
+        usb_phy_otg_io_conf_t otg_io_conf = USB_PHY_SELF_POWERED_DEVICE(config->phy.vbus_monitor_io);
 
 #if (SOC_USB_OTG_PERIPH_NUM > 1)
         if (config->port == TINYUSB_PORT_HIGH_SPEED_0) {
-            // Default PHY for OTG2.0 is UTMI
+            // Change the PHY parameters for USB OTG 2.0 High-speed
             phy_conf.target = USB_PHY_TARGET_UTMI;
             phy_conf.otg_speed = USB_PHY_SPEED_HIGH;
         }
 #endif // (SOC_USB_OTG_PERIPH_NUM > 1)
 
-        // OTG IOs config
-        const usb_phy_otg_io_conf_t otg_io_conf = USB_PHY_SELF_POWERED_DEVICE(config->phy.vbus_monitor_io);
         if (config->phy.self_powered) {
-            phy_conf.otg_io_conf = &otg_io_conf;
+            if (config->port == TINYUSB_PORT_FULL_SPEED_0) {
+                // For USB OTG 1.1, mux VBUS monitor GPIO to BVALID signal
+                phy_conf.otg_io_conf = &otg_io_conf;
+            }
+#if (SOC_USB_OTG_PERIPH_NUM > 1)
+            else if (config->port == TINYUSB_PORT_HIGH_SPEED_0) {
+                // For USB OTG 2.0, use VBUS GPIO + debounce to drive BVALID via GOTGCTL
+#if CONFIG_IDF_TARGET_ESP32P4
+                vbus_cfg.gpio_num          = config->phy.vbus_monitor_io;
+                vbus_cfg.debounce_delay_ms = config->phy.vbus_monitor_debounce_ms;
+#else
+                ESP_LOGW(TAG, "VBUS monitoring GPIO for OTG 2.0 is not supported on this target yet");
+#endif
+            }
+#endif // SOC_USB_OTG_PERIPH_NUM > 1
         }
+        // Install PHY
         ESP_RETURN_ON_ERROR(usb_new_phy(&phy_conf, &phy_hdl), TAG, "Install USB PHY failed");
     }
+
     // Init TinyUSB stack in task
-    ESP_GOTO_ON_ERROR(tinyusb_task_start(config->port, &config->task, &config->descriptor), del_phy, TAG, "Init TinyUSB task failed");
+    ESP_GOTO_ON_ERROR(tinyusb_task_start(config->port, &config->task, &config->descriptor, &vbus_cfg), del_phy, TAG, "Init TinyUSB task failed");
 
     s_ctx.port = config->port;              // Save the port number
     s_ctx.phy_hdl = phy_hdl;                // Save the PHY handle for uninstallation
@@ -155,9 +189,11 @@ esp_err_t tinyusb_driver_install(const tinyusb_config_t *config)
 esp_err_t tinyusb_driver_uninstall(void)
 {
     ESP_RETURN_ON_ERROR(tinyusb_task_stop(), TAG, "Deinit TinyUSB task failed");
+
     if (s_ctx.phy_hdl) {
         ESP_RETURN_ON_ERROR(usb_del_phy(s_ctx.phy_hdl), TAG, "Unable to delete PHY");
         s_ctx.phy_hdl = NULL;
     }
+
     return ESP_OK;
 }

device/esp_tinyusb/tinyusb_task.c

@@ -11,8 +11,11 @@
 #include "esp_log.h"
 #include "esp_check.h"
 #include "tinyusb.h"
+#include "tinyusb_task.h"
+#include "tinyusb_vbus_monitor.h"
 #include "sdkconfig.h"
 #include "descriptors_control.h"
+#include "soc/usb_dwc_struct.h"
 
 #if TUSB_VERSION_NUMBER < 1900 // < 0.19.0
 #define tusb_deinit(x)  tusb_teardown(x)  // For compatibility with tinyusb component versions from 0.17.0~2 to 0.18.0~5
@@ -45,7 +48,10 @@ typedef struct {
     const tinyusb_desc_config_t *desc_cfg;  /*!< USB Device descriptors configuration pointer */
     // Task related
     TaskHandle_t handle;                    /*!< Task handle */
-    volatile TaskHandle_t awaiting_handle;           /*!< Task handle, waiting to be notified after successful start of TinyUSB stack */
+    volatile TaskHandle_t awaiting_handle;  /*!< Task handle, waiting to be notified after successful start of TinyUSB stack */
+#if (CONFIG_IDF_TARGET_ESP32P4)
+    tinyusb_vbus_monitor_config_t vbus_monitor_cfg; /*!< VBUS monitoring configuration */
+#endif // CONFIG_IDF_TARGET_ESP32P4
 } tinyusb_task_ctx_t;
 
 static bool _task_is_running = false;               // Locking flag for the task, access only from the critical section
@@ -77,6 +83,15 @@ static void tinyusb_device_task(void *arg)
         goto desc_free;
     }
 
+#if (CONFIG_IDF_TARGET_ESP32P4)
+    if (task_ctx->vbus_monitor_cfg.gpio_num != GPIO_NUM_NC) {
+        if (tinyusb_vbus_monitor_init(&task_ctx->vbus_monitor_cfg) != ESP_OK) {
+            ESP_LOGE(TAG, "Init VBUS monitoring failed");
+            goto desc_free;
+        }
+    }
+#endif // CONFIG_IDF_TARGET_ESP32P4
+
     TINYUSB_TASK_ENTER_CRITICAL();
     task_ctx->handle = xTaskGetCurrentTaskHandle(); // Save task handle
     p_tusb_task_ctx = task_ctx;                     // Save global task context pointer
@@ -100,9 +115,9 @@ static void tinyusb_device_task(void *arg)
 
 esp_err_t tinyusb_task_check_config(const tinyusb_task_config_t *config)
 {
-    ESP_RETURN_ON_FALSE(config, ESP_ERR_INVALID_ARG, TAG, "Task configuration can't be NULL");
-    ESP_RETURN_ON_FALSE(config->size != 0, ESP_ERR_INVALID_ARG, TAG, "Task size can't be 0");
-    ESP_RETURN_ON_FALSE(config->priority != 0, ESP_ERR_INVALID_ARG, TAG, "Task priority can't be 0");
+    ESP_RETURN_ON_FALSE(config, ESP_ERR_INVALID_ARG, TAG, "Task configuration cannot be NULL");
+    ESP_RETURN_ON_FALSE(config->size != 0, ESP_ERR_INVALID_ARG, TAG, "Task size cannot be 0");
+    ESP_RETURN_ON_FALSE(config->priority != 0, ESP_ERR_INVALID_ARG, TAG, "Task priority cannot be 0");
 #if CONFIG_FREERTOS_UNICORE
     ESP_RETURN_ON_FALSE(config->xCoreID == 0, ESP_ERR_INVALID_ARG, TAG, "Task affinity must be 0 only in uniprocessor mode");
 #else
@@ -111,9 +126,13 @@ esp_err_t tinyusb_task_check_config(const tinyusb_task_config_t *config)
     return ESP_OK;
 }
 
-esp_err_t tinyusb_task_start(tinyusb_port_t port, const tinyusb_task_config_t *config, const tinyusb_desc_config_t *desc_cfg)
+esp_err_t tinyusb_task_start(tinyusb_port_t port,
+                             const tinyusb_task_config_t *config,
+                             const tinyusb_desc_config_t *desc_cfg,
+                             const tinyusb_vbus_monitor_config_t *vbus_monitor_cfg)
 {
     ESP_RETURN_ON_ERROR(tinyusb_descriptors_check(port, desc_cfg), TAG, "TinyUSB descriptors check failed");
+    ESP_RETURN_ON_FALSE(vbus_monitor_cfg != NULL, ESP_ERR_INVALID_ARG, TAG, "VBUS configuration cannot be NULL");
 
     TINYUSB_TASK_ENTER_CRITICAL();
     TINYUSB_TASK_CHECK_FROM_CRIT(p_tusb_task_ctx == NULL, ESP_ERR_INVALID_STATE);     // Task shouldn't started
@@ -133,6 +152,11 @@ esp_err_t tinyusb_task_start(tinyusb_port_t port, const tinyusb_task_config_t *c
     task_ctx->rhport_init.role = TUSB_ROLE_DEVICE;              // Role selection: esp_tinyusb is always a device
     task_ctx->rhport_init.speed = (port == TINYUSB_PORT_FULL_SPEED_0) ? TUSB_SPEED_FULL : TUSB_SPEED_HIGH; // Speed selection
     task_ctx->desc_cfg = desc_cfg;
+#if (CONFIG_IDF_TARGET_ESP32P4)
+    // VBUS monitor config
+    task_ctx->vbus_monitor_cfg.gpio_num = vbus_monitor_cfg->gpio_num;
+    task_ctx->vbus_monitor_cfg.debounce_delay_ms = vbus_monitor_cfg->debounce_delay_ms;
+#endif // CONFIG_IDF_TARGET_ESP32P4
 
     TaskHandle_t task_hdl = NULL;
     ESP_LOGD(TAG, "Creating TinyUSB main task on CPU%d", config->xCoreID);
@@ -177,8 +201,23 @@ esp_err_t tinyusb_task_stop(void)
         vTaskDelete(task_ctx->handle);
         task_ctx->handle = NULL;
     }
+
+    /* TODO: Free descriptors and disable the VBUS monitor should be in the task itself
+     * but currently we don't have a way to signal the task to do it and exit.
+     * So we do it here for now.
+     * Refer to https://github.com/espressif/esp-usb/pull/272
+     */
+
     // Free descriptors
     tinyusb_descriptors_free();
+
+#if (CONFIG_IDF_TARGET_ESP32P4)
+    if (task_ctx->vbus_monitor_cfg.gpio_num != GPIO_NUM_NC) {
+        // Deinit VBUS monitoring if it was enabled
+        tinyusb_vbus_monitor_deinit();
+    }
+#endif // CONFIG_IDF_TARGET_ESP32P4
+
     // Stop TinyUSB stack
     ESP_RETURN_ON_FALSE(tusb_deinit(task_ctx->rhport), ESP_ERR_NOT_FINISHED, TAG, "Unable to teardown TinyUSB stack");
     // Cleanup