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.

Note

This mode is still under development for the ESP32.

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 (500mA).

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://espressif.github.io/arduino-esp32/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.