ESP32 USB HID: Emulate Keyboard and Mouse from Microcontroller

The ability to use ESP32 USB HID keyboard mouse emulation opens up a world of automation possibilities that were previously limited to dedicated USB microcontrollers like the Pro Micro or Teensy. With the ESP32-S2 and ESP32-S3, Espressif introduced native USB support, allowing these powerful Wi-Fi/Bluetooth microcontrollers to also act as USB Human Interface Devices (HID) — keyboards, mice, gamepads, and more. In this tutorial, we will cover everything from understanding the USB HID protocol to writing complete Arduino sketches for keyboard macros and mouse control.

Which ESP32 Supports USB HID?

Not all ESP32 variants support native USB HID. This is a critical distinction before you purchase hardware:

Recommendation: For USB HID projects, use the ESP32-S3. It is dual-core, more powerful, and has the best Arduino library support for HID. The Waveshare ESP32-S3 development boards available at Zbotic are excellent choices.

Waveshare ESP32-S3 1.43inch AMOLED Display Development Board

A premium ESP32-S3 board with a gorgeous AMOLED display — perfect for building a USB HID macro pad with visual feedback showing current macro profiles.

View on Zbotic

Understanding USB HID Protocol

USB HID (Human Interface Device) is a USB device class specification that defines how input devices communicate with host computers. The beauty of HID is that it is natively supported by all major operating systems (Windows, macOS, Linux, Android) — no drivers needed.

When your ESP32 acts as a USB HID device:

• It presents itself to the PC as a keyboard, mouse, or gamepad.
• The OS loads its built-in HID driver automatically.
• Your ESP32 sends HID reports — small data packets describing key presses, mouse movements, or button states.
• The OS translates these reports into system-level input events.

HID Report Descriptors

Every HID device must provide a Report Descriptor — a binary data structure that tells the OS what kind of data the device sends. For a keyboard, this describes which keys it can report. For a mouse, it describes X/Y movement range, buttons, and scroll wheel. The Arduino USB HID library handles this for you automatically.

Setting Up Arduino IDE for ESP32 USB HID

The Arduino ESP32 core (version 2.0.0+) includes USB HID support for S2/S3 variants. Here is the setup:

Step 1: Select the Correct Board

In Arduino IDE, under Tools → Board, select:

• “ESP32S3 Dev Module” for generic ESP32-S3 boards
• Or your specific board variant

Step 2: Configure USB Mode

Under Tools → USB Mode, select “USB-OTG (TinyUSB)”. This is the critical setting that enables HID functionality.

Step 3: Include the HID Library

#include "USB.h"
#include "USBHIDKeyboard.h"
#include "USBHIDMouse.h"

USBHIDKeyboard Keyboard;
USBHIDMouse Mouse;

void setup() {
  Keyboard.begin();
  Mouse.begin();
  USB.begin();
  delay(1000); // Wait for PC to enumerate the device
}

Waveshare ESP32-S3 1.46inch Round Display Development Board

An ESP32-S3 board with a stylish round display, accelerometer, and speaker — build a wearable USB HID controller or a rotary macro encoder with visual feedback.

View on Zbotic

Keyboard Emulation: Macros and Key Combinations

Here is a complete example of ESP32 as a USB keyboard macro device. When a button connected to GPIO0 is pressed, it types a predefined text string:

#include "USB.h"
#include "USBHIDKeyboard.h"

USBHIDKeyboard Keyboard;

const int BUTTON_PIN = 0;  // Boot button on most ESP32-S3 boards
bool buttonPressed = false;

void setup() {
  pinMode(BUTTON_PIN, INPUT_PULLUP);
  Keyboard.begin();
  USB.begin();
  delay(1000);
}

void sendMacro() {
  // Example: Open Windows Run dialog and launch Notepad
  Keyboard.press(KEY_LEFT_GUI);  // Windows key
  Keyboard.press('r');
  delay(100);
  Keyboard.releaseAll();
  delay(500);
  Keyboard.print("notepad");
  Keyboard.press(KEY_RETURN);
  delay(100);
  Keyboard.releaseAll();
  delay(1000);
  
  // Type a message
  Keyboard.println("Hello from ESP32 USB HID! Built with components from Zbotic.in");
}

void loop() {
  bool currentState = (digitalRead(BUTTON_PIN) == LOW);
  
  if (currentState && !buttonPressed) {
    buttonPressed = true;
    sendMacro();
  } else if (!currentState) {
    buttonPressed = false;
  }
  
  delay(50);
}

Key Code Reference

The Arduino HID library includes constants for special keys:

• KEY_LEFT_CTRL, KEY_LEFT_ALT, KEY_LEFT_SHIFT — modifier keys
• KEY_LEFT_GUI — Windows/Command key
• KEY_F1 through KEY_F12 — function keys
• KEY_UP_ARROW, KEY_DOWN_ARROW, KEY_LEFT_ARROW, KEY_RIGHT_ARROW
• KEY_TAB, KEY_CAPS_LOCK, KEY_BACKSPACE, KEY_DELETE, KEY_RETURN, KEY_ESC
• KEY_INSERT, KEY_HOME, KEY_PAGE_UP, KEY_PAGE_DOWN, KEY_END

Mouse Emulation: Cursor Movement and Clicks

Mouse emulation allows your ESP32 to move the cursor, click buttons, and scroll. Here is an example using a DHT11 sensor — tilting a real accelerometer module translates to mouse movement (perfect for accessibility devices):

#include "USB.h"
#include "USBHIDMouse.h"

USBHIDMouse Mouse;

void setup() {
  Mouse.begin();
  USB.begin();
  delay(1000);
}

void loop() {
  // Move mouse in a circle
  for (int angle = 0; angle < 360; angle += 5) {
    int x = (int)(3 * cos(angle * PI / 180.0));
    int y = (int)(3 * sin(angle * PI / 180.0));
    Mouse.move(x, y, 0);  // x, y, scroll
    delay(20);
  }
  
  // Left click
  Mouse.click(MOUSE_LEFT);
  delay(2000);
}

// Mouse.move(x, y, wheel)  — relative movement
// Mouse.click(button)      — MOUSE_LEFT, MOUSE_RIGHT, MOUSE_MIDDLE
// Mouse.press(button)      — hold button
// Mouse.release(button)    — release button

Practical HID Project Ideas

1. Custom Macro Keyboard (Streamdeck Alternative)

Build a 6-key or 12-key macro pad using physical buttons or a touch screen on the ESP32-S3. Each button triggers a different keyboard shortcut or text snippet. Store macro profiles in NVS so they persist after power off. This is a popular project among Indian content creators and developers who want to automate repetitive tasks.

2. Presentation Clicker with Laser

Combine ESP32 USB HID with Bluetooth: connect wirelessly to a phone via Bluetooth, receive gesture commands, and translate them to USB keyboard events (arrow keys for slide navigation) on a connected laptop. Add a laser pointer circuit for a complete presentation tool — a commercially viable product that several Indian makers have successfully built.

3. Accessibility Device

Combine an accelerometer with the ESP32-S3 USB HID mouse emulation to create a head-tracking mouse for people with physical disabilities. India has millions of people who could benefit from affordable assistive technology — and an ESP32-based solution costs a fraction of commercial alternatives.

4. Automated Testing Jig

Use ESP32 USB HID in a factory testing environment to automatically enter test data into a PC application, replacing manual keyboard entry with precise, repeatable, GPIO-triggered typing sequences.

Waveshare ESP32-S3 1.47inch 172×320 LCD Display Development Board

Compact ESP32-S3 board with a color LCD display — ideal for a handheld USB HID macro device that shows the current active macro profile on-screen.

View on Zbotic

Frequently Asked Questions

Can I use the original ESP32 (not S2/S3) for USB HID?

No. The original ESP32 does not have native USB hardware. Its USB port is connected to a separate USB-to-UART chip (like CP2102 or CH340) which only provides serial communication, not HID. You must use ESP32-S2 or ESP32-S3 for native USB HID.

Can my ESP32 HID device work on Android and iOS?

Android supports USB HID when connected via OTG cable — your ESP32 keyboard or mouse will work without any additional software. iOS also supports USB HID keyboards and mice since iOS 13 (with Lightning to USB OTG adapter). This makes ESP32 HID devices useful for mobile device control scenarios.

Can the ESP32 be both a USB HID device AND stay connected to Wi-Fi?

Yes! This is one of the most powerful features of the ESP32-S3. It can simultaneously act as a USB HID keyboard/mouse to the host PC while maintaining a Wi-Fi connection. This enables use cases like: receive commands from the internet and translate them to keystrokes, or function as a network-connected macro keyboard that gets its macros from a cloud service.

How do I upload new firmware if USB is in HID mode?

This is a common pain point. When in USB HID mode, the normal USB serial upload does not work. Solutions: (1) Use a separate USB-UART adapter connected to UART0 pins for serial upload. (2) Implement OTA (Over-the-Air) updates over Wi-Fi. (3) Hold the BOOT button while pressing RESET to enter bootloader mode, which temporarily switches the USB to serial mode for flashing.

Is ESP32 USB HID legal for use in India?

Yes, building and using USB HID devices is perfectly legal. Commercial products based on ESP32 HID are sold globally. However, use it responsibly — creating automated input devices that interact with systems without authorization may violate computer fraud laws. For legitimate automation, testing, and accessibility applications, there are no legal concerns.