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,16 +13,16 @@ Overview
 
 The driver allows users to use {IDF_TARGET_NAME} chips to develop USB devices on a top of the TinyUSB stack. TinyUSB is integrated with ESP-IDF to provide USB features of the framework. Using this driver the chip works as a composite device supporting several USB devices simultaneously. Currently, only the Communications Device Class (CDC) type of the device with the Abstract Control Model (ACM) subclass and the Musical Instrument Digital Interface (MIDI) are supported.
 
-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
 --------
 
 - Configuration of device and string USB descriptors
 - USB Serial Device (CDC-ACM)
-- Input and output through USB Serial Device
-- USB MIDI Device
-
+- 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -79,22 +78,40 @@ However, the driver also provides a default descriptor. The driver can be instal
 - Name of CDC device if it is On
 - Serial number
 
-If you want to use own descriptors with extended modification, you can define them during the driver installation process
-
+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. ``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)
 
 .. code-block:: c
 
-    tinyusb_config_t partial_init = {
+    const tinyusb_config_t partial_init = {
         .descriptor = NULL;         //Uses default descriptor specified in Menuconfig
         .string_descriptor = NULL;  //Uses default string specified in Menuconfig
         .external_phy = false;
-    }
+    };
+
+.. _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)
 ---------------------------
@@ -119,8 +136,7 @@ To specify callbacks you can either set the pointer to your :cpp:type:`tusb_cdca
 USB Serial Console
 ^^^^^^^^^^^^^^^^^^
 
-The driver allows to redirect all standard application strings (stdin/out/err) to the USB Serial Device and return them to UART using :cpp:func:`esp_tusb_init_console`/:cpp:func:`esp_tusb_deinit_console` functions.
-
+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
 --------------------
@@ -141,7 +157,8 @@ The table below describes the code examples available in the directory :example:
      - How to set up {IDF_TARGET_NAME} chip to work as a USB Serial Device
    * - :example:`peripherals/usb/device/tusb_midi`
      - How to set up {IDF_TARGET_NAME} chip to work as a USB MIDI Device
-
+   * - :example:`peripherals/usb/device/tusb_hid`
+     - How to set up {IDF_TARGET_NAME} chip to work as a USB Human Interface Device
 
 API Reference
 -------------
@@ -152,4 +169,3 @@ API Reference
 .. include-build-file:: inc/tusb_console.inc
 .. include-build-file:: inc/tusb_tasks.inc
 .. include-build-file:: inc/vfs_tinyusb.inc
-