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:
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
Example Code
There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device.