USB support
What a board can do on USB, in two directions: drive devices from its host port, and present itself to a computer or to another board’s host port. The USB guide shows how to use each package; the host’s limits are in the host’s own page.
Host: what a board can drive
Host: what works
Device |
Package |
What you get |
|---|---|---|
Keyboard, mouse, media keys |
Key, button and movement events named as |
|
Gamepad, joystick |
|
|
Flash drive |
Bulk-Only Transport, mounted with |
|
USB serial (CDC-ACM, CH340/CH341, CP210x, FTDI, PL2303) |
A |
|
MIDI controller (MIDI 1.0) |
|
|
Speaker or microphone (USB Audio 1.0 and 2.0) |
|
|
Webcam (UVC) |
Whole MJPEG or YUY2 frames, negotiated with the camera |
|
Phone or camera (MTP and PTP) |
List, read and fetch photos and files, and thumbnails. Read only |
|
Android USB tethering (RNDIS), CDC-ECM Ethernet adapters |
|
|
Board in its DFU bootloader |
Read a board’s flash, a block at a time. Read only: nothing is downloaded or erased |
|
Anything else |
|
Host: where it runs
Board |
Engine |
Speed |
Classes |
|---|---|---|---|
ESP32-S3 |
ESP-IDF’s USB host library |
Full speed |
All of the above |
ESP32-P4 |
ESP-IDF’s USB host library |
High speed |
All of the above |
ESP32-S2 |
ESP-IDF’s USB host library |
Full speed |
The same build; the classes are checked on the S3 and P4 |
ESP32-P4 on CircuitPython |
ESP-IDF’s USB host library |
High speed |
A wireless keyboard and mouse dongle; drives and streams haven’t been tried |
Arduino GIGA R1 Display Shield |
TinyUSB’s host, on the USB-A port |
Full speed |
Control, bulk and interrupt transfers only: a drive, a keyboard and a MIDI controller work |
Host: what isn’t supported
What |
Where |
Because |
|---|---|---|
Audio and video devices |
GIGA |
TinyUSB’s host there has no isochronous transfers |
USB tethering and Ethernet adapters |
GIGA, CircuitPython |
The tethering adapter is built on ESP-IDF’s host and lwIP; the GIGA runs TinyUSB’s host, and CircuitPython’s ESP32-P4 port has no network yet |
Any host at all |
Boards other than the ESP32-S2, S3, P4 and the GIGA |
|
A high-speed link |
ESP32-S2, S3, GIGA |
Their host ports are full speed |
A webcam and a USB Audio 2.0 speaker in one session |
ESP32 |
The controller’s FIFO split is fixed for each |
Every device at once |
ESP32-S3 |
The host has eight channels. A device’s control pipe takes one, a bulk pair two and an interrupt IN one, so a drive and a keyboard fit and a drive and a MIDI controller don’t |
Full- and low-speed devices behind a hub |
ESP32-P4 |
The port runs at high speed. Start the host with |
Device: what a board can present
Device: what works
The board is |
Package |
What you get |
|---|---|---|
A serial port |
Built in, and |
The REPL stays on its own port; |
A MIDI device (MIDI 1.0) |
|
One cable |
A keyboard, mouse or media remote |
|
|
A gamepad, or a pointer that says where it is |
|
|
Any other HID device |
|
|
A network adapter (CDC-NCM) |
|
|
A flash drive |
Bulk-Only Transport over any block device: an SD card, a partition, RAM. |
|
A sound card, a microphone, or both as a headset (USB Audio 2.0) |
|
|
A webcam (UVC 1.1) |
YUY2 or MJPEG, one size or a list for the computer to choose from |
Device: where it runs
The packages run on MicroPython’s machine.USBDevice. Audio and video also
need the OmniPython firmware’s streaming endpoints (USBDevice.Ring and
USBDevice.stream()), which build.py includes. The network adapter needs
the firmware’s network.USBD_NCM, which it has wherever the board has lwIP.
Board |
Link speed |
Notes |
|---|---|---|
ESP32-S2, S3 |
Full speed |
IN endpoints 1 to 4 |
Arduino GIGA R1 Display Shield |
Full speed |
The USB-C port, through TinyUSB’s device |
ESP32-P4 |
High speed on its high-speed port; full speed through the full-speed PHY |
IN endpoints 1 to 7 at high speed, 1 to 4 at full speed. The sound card and the webcam size their packets to the link |
RP2040, RP2350 |
Full speed |
IN endpoints 1 to 15. The network adapter on the W boards, which have lwIP |
Device: what isn’t supported
What |
Because |
|---|---|
More functions than the endpoints allow |
|
Vendor control requests, WebUSB and WinUSB descriptors |
|