FreeScript
EspUsbHost
by tanakamasayuki · version 2.10.2 · updated yesterday
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 1.5 MB
- Code check
- Clean
- Licence
- MIT
- Released
- Nov 2026
Library for using USB Host with ESP32
EspUsbHost
For a practical first run, use Working through the examples and the complete example index. Each example guide covers connections, operation, APIs and failure checks.
USB events are processed in a background FreeRTOS task, so
New to USB Host, or stuck with a device that will not work? Start with the USB Host Development Guide: USB fundamentals, the ESP32-specific limits (power, speeds, hubs, channels), and the route from checking a board through identifying an unknown device to working out an undocumented protocol. The advanced guide continues into descriptor byte layouts, host channels and the FIFO split, error recovery, throughput design, callback context, and writing your own class wrapper. Devices and boards that have been verified on real hardware are listed in Tested Devices and Boards, and everything under
Contents
Minimum Arduino-ESP32 core (board package) version:
Target, Minimum arduino-esp32
ESP32-S2 / ESP32-S3, 3.2.0
ESP32-P4, 3.3.1
Older cores are not supported: 3.1.x and earlier may fail to build. Per-library-version build results across core versions are published under [
ESP32-S3 is the primary target and the one the peer/manual tests run on. ESP32-S2
is built for every release across all supported cores, but it has far less internal
RAM, so
ESP32-P4 notes.
Version 2 status
Version 2 is a ground-up redesign and is not compatible with the 1.x API. The old inheritance/virtual-method style is no longer the primary interface; use the callback-based APIs such as
This release has substantially broader USB class support than 1.x, but it is still a practical Arduino USB Host library under active development, not a fully validated replacement for every ESP-IDF USB class driver. APIs may still change incompatibly in later 2.x releases when that makes the API simpler, safer, or more consistent.
Test coverage is better than the 1.x series and includes example build checks plus peer/manual tests for major paths, but many combinations still depend on real hardware. Treat USB Audio, USB Hub edge cases, multi-device setups, and unusual/non-compliant USB devices as areas that need device-specific verification.
Sibling Library: EspUsbDevice
The device-side sibling library is
[
EspUsbDevice is a USB Device library expanded alongside EspUsbHost, and is used
for Host/Device combination tests and ESP32-P4 single-board loopback validation.
Arduino-ESP32's standard
similar APIs are convenient for short, common USB Device sketches. EspUsbDevice
instead focuses on explicit sketch-side control over port, speed, descriptors,
endpoint packet sizes, HID report IDs, output/feature reports, and raw class
reports.
For keyboards, the standard
text, but it has limits when you need complete Japanese-layout coverage or exact
HID usages for keys such as Muhenkan, Henkan, Kana, Hankaku/Zenkaku, and
JIS-specific symbol keys. EspUsbDevice keeps raw HID usage/report control
available alongside text helpers so EspUsbHost keyboard layout behavior can be
tested precisely.
Use the standard Arduino-ESP32 USB Device APIs first when you only need a normal
keyboard, mouse, CDC, or similar device connected to a PC. Use EspUsbDevice when
you need detailed EspUsbHost validation, descriptors or reports that the
Arduino Core standard Device implementation cannot easily control, or ESP32-P4
Host/Device loopback tests.
Features
日本語版: README.ja.mdArduino library for using USB Host on ESP32-S3, ESP32-S2 and ESP32-P4.
For a practical first run, use Working through the examples and the complete example index. Each example guide covers connections, operation, APIs and failure checks.
USB events are processed in a background FreeRTOS task, so
loop() does not need to call any USB polling function. Register callbacks in setup(), call begin(), and the library handles the rest.New to USB Host, or stuck with a device that will not work? Start with the USB Host Development Guide: USB fundamentals, the ESP32-specific limits (power, speeds, hubs, channels), and the route from checking a board through identifying an unknown device to working out an undocumented protocol. The advanced guide continues into descriptor byte layouts, host channels and the FIFO split, error recovery, throughput design, callback context, and writing your own class wrapper. Devices and boards that have been verified on real hardware are listed in Tested Devices and Boards, and everything under
docs/ is indexed in docs/README.md.Contents
- Requirements
- Version 2 status
- Sibling Library: EspUsbDevice
- Features
- Supported USB classes
- Roadmap
- Current limits and cautions
- Hardware requirements
- Installation
- Quick start
- Examples
- API reference
- Core
- Device events
- HID input
- HID output
- USB serial (CDC ACM and VCP)
- Vendor bulk/control
- CCID smart card reader
- MIDI
- USB audio
- USB Mass Storage
- USB Hub
- USB network (CDC-NCM / CDC-ECM)
- Device discovery
- Error handling
- Design
- Multiple devices
- Tests
- Release checklist
- License
Minimum Arduino-ESP32 core (board package) version:
Target, Minimum arduino-esp32
ESP32-S2 / ESP32-S3, 3.2.0
ESP32-P4, 3.3.1
Older cores are not supported: 3.1.x and earlier may fail to build. Per-library-version build results across core versions are published under [
docs/](https://github.com/tanakamasayuki/EspUsbHost/blob/main/docs/) as COMPATIBILITY..md.ESP32-S3 is the primary target and the one the peer/manual tests run on. ESP32-S2
is built for every release across all supported cores, but it has far less internal
RAM, so
ESP_USB_HOST_MAX_DEVICES defaults to 3 there instead of 8 (raise it with-DESP_USB_HOST_MAX_DEVICES=N and watch for dram0_0_seg overflowed), and theUsbNetwork example does not fit. ESP32-P4 adds HS OTG; seeESP32-P4 notes.
Version 2 status
Version 2 is a ground-up redesign and is not compatible with the 1.x API. The old inheritance/virtual-method style is no longer the primary interface; use the callback-based APIs such as
onKeyboard(), onMouse(), onDeviceConnected(), and class-specific send/start APIs.This release has substantially broader USB class support than 1.x, but it is still a practical Arduino USB Host library under active development, not a fully validated replacement for every ESP-IDF USB class driver. APIs may still change incompatibly in later 2.x releases when that makes the API simpler, safer, or more consistent.
Test coverage is better than the 1.x series and includes example build checks plus peer/manual tests for major paths, but many combinations still depend on real hardware. Treat USB Audio, USB Hub edge cases, multi-device setups, and unusual/non-compliant USB devices as areas that need device-specific verification.
Sibling Library: EspUsbDevice
The device-side sibling library is
[
EspUsbDevice](https://github.com/tanakamasayuki/EspUsbDevice).EspUsbDevice is a USB Device library expanded alongside EspUsbHost, and is used
for Host/Device combination tests and ESP32-P4 single-board loopback validation.
Arduino-ESP32's standard
USB, USBHIDKeyboard, USBHIDMouse, USBCDC, andsimilar APIs are convenient for short, common USB Device sketches. EspUsbDevice
instead focuses on explicit sketch-side control over port, speed, descriptors,
endpoint packet sizes, HID report IDs, output/feature reports, and raw class
reports.
For keyboards, the standard
USBHIDKeyboard API is useful for sending simpletext, but it has limits when you need complete Japanese-layout coverage or exact
HID usages for keys such as Muhenkan, Henkan, Kana, Hankaku/Zenkaku, and
JIS-specific symbol keys. EspUsbDevice keeps raw HID usage/report control
available alongside text helpers so EspUsbHost keyboard layout behavior can be
tested precisely.
Use the standard Arduino-ESP32 USB Device APIs first when you only need a normal
keyboard, mouse, CDC, or similar device connected to a PC. Use EspUsbDevice when
you need detailed EspUsbHost validation, descriptors or reports that the
Arduino Core standard Device implementation cannot easily control, or ESP32-P4
Host/Device loopback tests.
Features
- HID input — keyboard, mouse, consumer control (media keys), system control (power/standby), gamepad
- HID output — keyboard LED control, vendor output/feature reports
- USB serial — CDC ACM and common VCP devices (FTDI, CP210x, CH34x) via
EspUsbHostCdcSerial(ArduinoStream/Printcompatible), including composite devices that publish several CDC ports on one cable - MIDI — USB MIDI input and output
- USB audio — raw isochronous IN payloads and isochronous OUT writes for USB Audio streaming interfaces
- USB Mass Storage — USB Mass Storage Bulk-Only Transport with SCSI capacity/read/write block access