alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-11-18 10:31:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

tinyusb: Add VBUS voltage monitoring feature

Browse Source 
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
This commit is contained in:
Tomas Rezucha
2022-09-22 12:33:33 +02:00
parent dc705312a3
commit 1410f5a798
5 changed files with 40 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/en/api-reference/peripherals/usb_device.rst
View File

@@ -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