Skip to content

12 USB

Jump to bottom
Geo edited this page Feb 13, 2026 · 20 revisions

USB Mode

This mode allows you to emulate USB HID devices or expose a USB mass storage interface.
Only available on S3. Not supported on M5Stick CPlus2.

⚠️ USB Warning: Using USB commands while connected over Serial terminal may interrupt the session.

🧩 Commands

Arguments in < > are required, while arguments in [ ] are optional.

Command Description
keyboard Bridge mode, forwarding all terminal keystrokes as an USB HID keyboard. Press an esp32 button to stop
keyboard <text> Sends the provided text via USB Keyboard HID
mouse <x> <y> Moves the USB mouse cursor by the given X/Y values
mouse click Sends a left-click mouse event
mouse jiggle [ms] Randomly move the mouse each interval [ms] until ENTER is pressed (default 1sec interval)
gamepad <key> Emulates a gamepad button press (e.g., A, B, LEFT, etc.)
stick Starts USB Mass Storage mode (via SD card)
host Enable USB host mode to connect USB devices to the ESP32 and dump descriptors
reset Resets the USB interface
config Sets the SPI pins used for the USB storage interface

📝 Notes

  • USB commands are not supported on M5Stick.
  • HID interfaces (keyboard, mouse, gamepad) send their data via native USB.
  • keyboard starts a bridge mode where all the keys received in the terminal are sent to USB HID, press any esp32 button to return.
  • keyboard <text> sends the text provided once.
  • mouse move values are capped to -127 to 127.
  • The stick command exposes the SD card over USB as a storage drive (may take up to 30 seconds).
  • host requires 5V power on the USB port, for the S3devkit, you must bridge "USB-OTG" pad to use this feature.
  • The config command lets you define the SPI pins used for the SD card:
    • CS (Chip Select)
    • CLK (Clock)
    • MISO (Master In Slave Out)
    • MOSI (Master Out Slave In)
  • If you're using USB Serial to interact with the Cardputer, note that activating USB HID or mass storage may interrupt your session.
    • Use Web UI instead for uninterrupted control.
    • Reboot device if USB gets stuck or disconnected.

📌 Example Usage

mode usb
keyboard
keyboard Hello World
mouse 100 -120
mouse 10 127
mouse click
mouse jiggle
gamepad A
gamepad left
stick
reset

▶️ Demo

demo15

⚠️ Voltage Warning: Devices should only operate at 3.3V or 5V.
Do not connect peripherals using other voltage levels — doing so may damage your ESP32.

Clone this wiki locally