tinyusb: Add VBUS voltage monitoring feature

VBUS voltage monitoring is mandated by USB specification for self-powered devices.
This implementation maps selected GPIO to bvalid signal of USB-OTG peripheral.

Closes https://github.com/espressif/esp-idf/issues/7747

components/tinyusb/additions/include/tinyusb.h

@@ -19,7 +19,12 @@ extern "C" {
 #endif
 
 /**
- * @brief Configuration structure of the tinyUSB core
+ * @brief Configuration structure of the TinyUSB core
+ *
+ * USB specification mandates self-powered devices to monitor USB VBUS to detect connection/disconnection events.
+ * If you want to use this feature, connected VBUS to any free GPIO through a voltage divider or voltage comparator.
+ * 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).
  */
 typedef struct {
     union {
@@ -29,6 +34,8 @@ typedef struct {
     const char **string_descriptor;            /*!< Pointer to an array of string descriptors */
     bool external_phy;                         /*!< Should USB use an external PHY */
     const uint8_t *configuration_descriptor;   /*!< Pointer to a configuration descriptor. If set to NULL, TinyUSB device will use a default configuration descriptor whose values are set in Kconfig */
+    bool self_powered;                         /*!< This is a self-powered USB device. USB VBUS must be monitored. */
+    int vbus_monitor_io;                       /*!< GPIO for VBUS monitoring. Ignored if not self_powered. */
 } tinyusb_config_t;
 
 /**

components/tinyusb/additions/src/tinyusb.c

@@ -32,6 +32,8 @@ esp_err_t tinyusb_driver_install(const tinyusb_config_t *config)
         .controller = USB_PHY_CTRL_OTG,
         .otg_mode = USB_OTG_MODE_DEVICE,
     };
+
+    // External PHY IOs config
     usb_phy_ext_io_conf_t ext_io_conf = {
         .vp_io_num = USBPHY_VP_NUM,
         .vm_io_num = USBPHY_VM_NUM,
@@ -46,6 +48,12 @@ esp_err_t tinyusb_driver_install(const tinyusb_config_t *config)
     } else {
         phy_conf.target = USB_PHY_TARGET_INT;
     }
+
+    // OTG IOs config
+    const usb_phy_otg_io_conf_t otg_io_conf = USB_PHY_SELF_POWERED_DEVICE(config->vbus_monitor_io);
+    if (config->self_powered) {
+        phy_conf.otg_io_conf = &otg_io_conf;
+    }
     ESP_RETURN_ON_ERROR(usb_new_phy(&phy_conf, &phy_hdl), TAG, "Install USB PHY failed");
 
 #if (CONFIG_TINYUSB_HID_COUNT > 0)

docs/en/api-reference/peripherals/usb_device.rst

@@ -13,7 +13,7 @@ Overview
 
 The driver allows you to use {IDF_TARGET_NAME} chips to develop USB devices on a top of TinyUSB stack. TinyUSB is integrated with ESP-IDF to provide USB features of the framework. Using this driver the chip works as simple or composite device supporting several USB devices simultaneously.
 
-Our USB-OTG implementation is limited to {IDF_TARGET_USB_EP_NUM} number of USB endpoints ({IDF_TARGET_USB_EP_NUM_INOUT} IN/OUT endpoints and {IDF_TARGET_USB_EP_NUM_IN} IN endpoint) - find more information in `technical reference manual <{IDF_TARGET_TRM_EN_URL}>`_.
+Our USB-OTG implementation is limited to {IDF_TARGET_USB_EP_NUM} USB endpoints ({IDF_TARGET_USB_EP_NUM_INOUT} IN/OUT endpoints and {IDF_TARGET_USB_EP_NUM_IN} IN endpoint) - find more information in `technical reference manual <{IDF_TARGET_TRM_EN_URL}>`_.
 
 Features
 --------
@@ -22,7 +22,7 @@ Features
 - USB Serial Device (CDC-ACM)
 - Input and output streams through USB Serial Device
 - Other USB classes (MIDI, MSC, HID...) support directly via TinyUSB
-
+- VBUS monitoring for self-powered devices
 
 Hardware USB Connection
 -----------------------
@@ -36,9 +36,11 @@ On {IDF_TARGET_NAME}, connect GPIO {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_
 
 .. figure:: ../../../_static/usb-board-connection.png
     :align: center
-    :alt: Connection of a board to a host ESP chip
+    :alt: Connection of an ESP board to a USB host 
     :figclass: align-center
 
+Self-powered devices must also connect VBUS through voltage divider or comparator, more details in :ref:`self-powered-device` subchapter.
+
 Driver Structure
 ----------------
 
@@ -51,8 +53,6 @@ On top of it the driver implements:
 - Redirecting of standard streams through the Serial device
 - Encapsulated driver's task servicing the TinyUSB
 
-
-
 Configuration
 -------------
 
@@ -63,7 +63,6 @@ Via Menuconfig options you can specify:
 - The verbosity of the TinyUSB's log
 - Disable the TinyUSB main task (for the custom implementation)
 
-
 Descriptors Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -81,9 +80,9 @@ However, the driver also provides default descriptors. You can install the drive
 
 If you want to use your 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. ``const 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)
@@ -97,6 +96,24 @@ To initialize the driver, users should call :cpp:func:`tinyusb_driver_install`.
         .configuration_descriptor = NULL, // Use default configuration descriptor according to settings in Menuconfig
     };
 
+.. _self-powered-device:
+
+Self-Powered Device
+-------------------
+
+USB specification mandates self-powered devices to monitor voltage level on USB's VBUS signal. As opposed to bus-powered devices, a self-powered device can be fully functional even without USB connection. The self-powered device detects connection and disconnection events by monitoring the VBUS voltage level. VBUS is considered valid if it rises above 4.75V and invalid if it falls below 4.35V.
+
+No {IDF_TARGET_NAME} pin is 5V tolerant, so you must connect the VBUS to {IDF_TARGET_NAME} via a comparator with voltage thresholds as described above, or use a simple resistor voltage divider that will output (0.75 x Vdd) if VBUS is 4.4V (see figure below). In both cases, voltage on the sensing pin must be logic low within 3ms after the device is unplugged from USB host.
+
+.. figure:: ../../../_static/diagrams/usb/usb_vbus_voltage_monitor.png
+    :align: center
+    :alt: Simple voltage divider for VBUS monitoring
+    :figclass: align-center
+
+    Simple voltage divider for VBUS monitoring
+
+To use this feature, in :cpp:type:`tinyusb_config_t` you must set :cpp:member:`self_powered` to ``true`` and :cpp:member:`vbus_monitor_io` to GPIO number that will be used for VBUS monitoring.
+
 USB Serial Device (CDC-ACM)
 ---------------------------
 
@@ -122,7 +139,6 @@ USB Serial Console
 
 The driver allows to redirect all standard application streams (stdinm stdout, stderr) 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
 --------------------
 
@@ -143,7 +159,6 @@ The table below describes the code examples available in the directory :example:
    * - :example:`peripherals/usb/device/tusb_hid`
      - How to set up {IDF_TARGET_NAME} chip to work as a USB Human Interface Device
 
-
 API Reference
 -------------
 
@@ -153,4 +168,3 @@ API Reference
 .. include-build-file:: inc/tusb_console.inc
 .. include-build-file:: inc/tusb_tasks.inc
 .. include-build-file:: inc/vfs_tinyusb.inc
-