mirror of
https://github.com/espressif/esp-idf.git
synced 2025-10-10 13:55:23 +02:00
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
This commit is contained in:
Tomas Rezucha
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user