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
TheUniversal 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 theUSB.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.
voidonEvent(esp_event_handler_tcallback);
Event handling function for the specific event.
voidonEvent(arduino_usb_event_tevent,esp_event_handler_tcallback);
Whereevent 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. Seehttps://www.usb.org/getting-vendor-id for more details.
boolVID(uint16_tv);
Get the Vendor ID.
uint16_tVID(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.
boolPID(uint16_tp);
Get the Product ID.
uint16_tPID(void);
Returns the Product ID. The default PID is:0x0002.
firmwareVersion
Set the firmware version. This is a 16 bits unsigned value.
boolfirmwareVersion(uint16_tversion);
Get the firmware version.
uint16_tfirmwareVersion(void);
Return the 16 bits unsigned value. The default value is:0x100.
usbVersion
Set the USB version.
boolusbVersion(uint16_tversion);
Get the USB version.
uint16_tusbVersion(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.
boolusbPower(uint16_tmA);
Get the USB power configuration.
uint16_tusbPower(void);
Return the current in mA. The default value is:0x500 (500 mA).
usbClass
Set the USB class.
boolusbClass(uint8_t_class);
Get the USB class.
uint8_tusbClass(void);
Return the USB class. The default value is:TUSB_CLASS_MISC.
usbSubClass
Set the USB sub-class.
boolusbSubClass(uint8_tsubClass);
Get the USB sub-class.
uint8_tusbSubClass(void);
Return the USB sub-class. The default value is:MISC_SUBCLASS_COMMON.
usbProtocol
Define the USB protocol.
boolusbProtocol(uint8_tprotocol);
Get the USB protocol.
uint8_tusbProtocol(void);
Return the USB protocol. The default value is:MISC_PROTOCOL_IAD
usbAttributes
Set the USB attributes.
boolusbAttributes(uint8_tattr);
Get the USB attributes.
uint8_tusbAttributes(void);
Return the USB attributes. The default value is:TUSB_DESC_CONFIG_ATT_SELF_POWERED
webUSB
This function is used to enable thewebUSB functionality.
boolwebUSB(boolenabled);
This function is used to get thewebUSB setting.
boolwebUSB(void);
Return thewebUSB setting (Enabled orDisabled)
productName
This function is used to define the product name.
boolproductName(constchar*name);
This function is used to get the product’s name.
constchar*productName(void);
manufacturerName
This function is used to define the manufacturer name.
boolmanufacturerName(constchar*name);
This function is used to get the manufacturer’s name.
constchar*manufacturerName(void);
serialNumber
This function is used to define the serial number.
boolserialNumber(constchar*name);
This function is used to get the serial number.
constchar*serialNumber(void);
The default serial number is:0.
webUSBURL
This function is used to define thewebUSBURL.
boolwebUSBURL(constchar*name);
This function is used to get thewebUSBURL.
constchar*webUSBURL(void);
The defaultwebUSBURL is:https://docs.espressif.com/projects/arduino-esp32/en/latest/_static/webusb.html
enableDFU
This function is used to enable the DFU capability.
boolenableDFU();
begin
This function is used to start the peripheral using the default configuration.
boolbegin();
Example Code
There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device.