USB API

Note

This feature is only supported on ESP chips that have USB peripheral, like the ESP32-S2 and ESP32-S3. Some chips, like the ESP32-C3 include native CDC+JTAG peripheral that is not covered here.

About

The Universal Serial Bus is a widely used peripheral to exchange data between devices. USB was introduced on the ESP32, supporting both device and host mode.

To learn about the USB, see the USB.org for developers.

USB as Device

In the device mode, the ESP32 acts as an USB device, like a mouse or keyboard to be connected to a host device, like your computer or smartphone.

USB as Host

The USB host mode, you can connect devices on the ESP32, like external modems, mouse and keyboards.

Two host stacks are available and only one of them can own the USB peripheral at a time:

TinyUSB, used by the USBHost class and the USBHost* examples. This is what the Arduino USB host API is built on, and it is documented in USB Host API.
the ESP-IDF USB Host Library (usb/usb_host.h), used directly from a sketch. Pick this one when a class driver exists for ESP-IDF but not for TinyUSB. See the USBHostIDF example.

Warning

Since arduino-esp32 3.3.11 the prebuilt libraries are built with CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK enabled, so a sketch calling usb_host_install() must set usb_host_config_t::enum_filter_cb. ESP-IDF treats a NULL callback as “do not enumerate this device” and cancels enumeration for every device, without logging an error. The “Set to NULL otherwise” note in the ESP-IDF header only applies when that option is disabled, which was the case up to 3.3.10.

An allow-all callback is enough when no filtering is needed:

static bool enumFilter(const usb_device_desc_t *dev_desc, uint8_t *bConfigurationValue) {
  *bConfigurationValue = 1;
  return true;
}

host_config.enum_filter_cb = enumFilter;

The callback is also the only way to enumerate a configuration other than the first one, which some devices require. It must not block and must not submit transfers.

Note

The ESP-IDF USB Host Library is not part of the ESP32-S2 prebuilt libraries. On that target only the TinyUSB host is available.

API Description

This is the common USB API description.

For more supported USB classes implementation, see the following sections:

Classes:

USB Common

These are the common APIs for the USB driver.

onEvent

Event handling function to set the callback.

void onEvent(esp_event_handler_t callback);

Event handling function for the specific event.

void onEvent(arduino_usb_event_t event, esp_event_handler_t callback);

Where event can be:

ARDUINO_USB_ANY_EVENT
ARDUINO_USB_STARTED_EVENT
ARDUINO_USB_STOPPED_EVENT
ARDUINO_USB_SUSPEND_EVENT
ARDUINO_USB_RESUME_EVENT
ARDUINO_USB_MAX_EVENT

VID

Set the Vendor ID. This 16 bits identification is used to identify the company that develops the product.

Note

You can’t define your own VID. If you need your own VID, you need to buy one. See https://www.usb.org/getting-vendor-id for more details.

bool VID(uint16_t v);

Get the Vendor ID.

uint16_t VID(void);

Returns the Vendor ID. The default value for the VID is: 0x303A.

PID

Set the Product ID. This 16 bits identification is used to identify the product.

bool PID(uint16_t p);

Get the Product ID.

uint16_t PID(void);

Returns the Product ID. The default PID is: 0x0002.

firmwareVersion

Set the firmware version. This is a 16 bits unsigned value.

bool firmwareVersion(uint16_t version);

Get the firmware version.

uint16_t firmwareVersion(void);

Return the 16 bits unsigned value. The default value is: 0x100.

usbVersion

Set the USB version.

bool usbVersion(uint16_t version);

Get the USB version.

uint16_t usbVersion(void);

Return the USB version. The default value is: 0x200 (USB 2.0).

usbPower

Set the USB power as mA (current).

Note

This configuration does not change the physical power output. This is only used for the USB device information.

bool usbPower(uint16_t mA);

Get the USB power configuration.

uint16_t usbPower(void);

Return the current in mA. The default value is: 0x500 (500 mA).

usbClass

Set the USB class.

bool usbClass(uint8_t _class);

Get the USB class.

uint8_t usbClass(void);

Return the USB class. The default value is: TUSB_CLASS_MISC.

usbSubClass

Set the USB sub-class.

bool usbSubClass(uint8_t subClass);

Get the USB sub-class.

uint8_t usbSubClass(void);

Return the USB sub-class. The default value is: MISC_SUBCLASS_COMMON.

usbProtocol

Define the USB protocol.

bool usbProtocol(uint8_t protocol);

Get the USB protocol.

uint8_t usbProtocol(void);

Return the USB protocol. The default value is: MISC_PROTOCOL_IAD

usbAttributes

Set the USB attributes.

bool usbAttributes(uint8_t attr);

Get the USB attributes.

uint8_t usbAttributes(void);

Return the USB attributes. The default value is: TUSB_DESC_CONFIG_ATT_SELF_POWERED

webUSB

This function is used to enable the webUSB functionality.

bool webUSB(bool enabled);

This function is used to get the webUSB setting.

bool webUSB(void);

Return the webUSB setting (Enabled or Disabled)

productName

This function is used to define the product name.

bool productName(const char * name);

This function is used to get the product’s name.

const char * productName(void);

manufacturerName

This function is used to define the manufacturer name.

bool manufacturerName(const char * name);

This function is used to get the manufacturer’s name.

const char * manufacturerName(void);

serialNumber

This function is used to define the serial number.

bool serialNumber(const char * name);

This function is used to get the serial number.

const char * serialNumber(void);

The default serial number is: 0.

webUSBURL

This function is used to define the webUSBURL.

bool webUSBURL(const char * name);

This function is used to get the webUSBURL.

const char * webUSBURL(void);

The default webUSBURL is: https://docs.espressif.com/projects/arduino-esp32/en/latest/_static/webusb.html

enableDFU

This function is used to enable the DFU capability.

bool enableDFU();

begin

This function is used to start the peripheral using the default configuration.

bool begin();

Example Code

There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device.