102 online 3 members  + Join RP Base  +
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
EspUsbHost
日本語版: README.ja.md

Arduino 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
Requirements
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 the
UsbNetwork example does not fit. ESP32-P4 adds HS OTG; see
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 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, and
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 USBHIDKeyboard API is useful for sending simple
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
  • 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 (Arduino Stream/Print compatible), 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

…