Practical ESP32-S Projects: Build a Native USB HID Macro Pad

Why the ESP32-S3 Changes the Game for USB Projects

When builders talk about ESP32-S projects, they are usually referring to the S2 and S3 variants. The original ESP32 (ESP32-WROOM) is a fantastic Wi-Fi/Bluetooth workhorse, but it lacks native USB. It relies on external bridge chips like the CP2102 or CH340 just to talk to your PC, meaning it cannot natively emulate a keyboard, mouse, or gamepad.

The ESP32-S3 integrates a native USB 1.1 OTG controller. This allows it to act as a true Human Interface Device (HID) directly over the USB cable. For macro pads, MIDI controllers, and custom input devices, this eliminates the need for intermediary microcontrollers like the ATmega32U4 (Pro Micro). According to the Espressif ESP32-S3 Datasheet, the S3 also adds vector instructions for AI acceleration and supports up to 45 configurable GPIOs, making it the definitive choice for modern embedded input devices.

Parts List and Pin Mapping

To keep the build robust and avoid the dreaded "USB Device Not Recognized" error caused by brownouts, we are using the N8R8 variant of the S3 DevKit. It includes an 8MB octal SPI PSRAM, which provides ample memory buffer for USB descriptors and display rendering.

Pin Mapping Table

The ESP32-S3 has specific strapping pins. We avoid GPIO 0, 3, 45, and 46 to prevent boot-loop issues. The following GPIOs support internal pull-up resistors, eliminating the need for external 10kΩ resistors on our switches.

Step-by-Step Build and Wiring

1. Prep the I2C Display: Insert the 0.96" OLED into the breadboard. Connect VCC to the ESP32-S3 3V3 pin and GND to GND. Do not connect VCC to 5V; while many SSD1306 modules have onboard regulators, feeding 3.3V directly ensures logic-level safety for the S3's I2C pins.
2. Wire the I2C Data Lines: Connect OLED SDA to GPIO 8 and SCL to GPIO 9. The ESP32-S3 allows software I2C mapping on almost any pin, but 8 and 9 are safe from boot-strapping conflicts.
3. Mount the Switches: Insert your three tactile or mechanical switches. Wire one leg of each switch to a common GND rail. Wire the opposite legs to GPIO 4, GPIO 5, and GPIO 6 respectively.
4. Verify Connections: Use a multimeter in continuity mode. With the switches unpressed, there should be no continuity between the GPIO pins and GND. When pressed, you should read less than 1 ohm.

Complete Arduino IDE Code (ESP32-S3 Native USB)

This code targets the ESP32-S3-DevKitC-1. It uses the TinyUSB stack included in the ESP32 Arduino Core (v2.0.4 or newer). It includes hardware debouncing logic and error handling for the OLED initialization.

Crucial Board Settings (Tools Menu):

• Board: ESP32S3 Dev Module
• USB Mode: USB-OTG (TinyUSB)
• USB CDC On Boot: Enabled
• Upload Mode: UART0 / Hardware CDC

#include "USB.h"
#include "USBHIDKeyboard.h"
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

// Pin Definitions
#define BTN_1 4
#define BTN_2 5
#define BTN_3 6
#define I2C_SDA 8
#define I2C_SCL 9

// Screen dimensions
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
USBHIDKeyboard Keyboard;

// Debounce variables
unsigned long lastDebounceTime[3] = {0, 0, 0};
unsigned long debounceDelay = 50;
int buttonState[3] = {HIGH, HIGH, HIGH};
int lastButtonState[3] = {HIGH, HIGH, HIGH};

void setup() {
  // Configure internal pull-ups for switches
  pinMode(BTN_1, INPUT_PULLUP);
  pinMode(BTN_2, INPUT_PULLUP);
  pinMode(BTN_3, INPUT_PULLUP);

  // Initialize I2C with custom pins for ESP32-S3
  Wire.begin(I2C_SDA, I2C_SCL);

  // Error handling: Halt if OLED fails to initialize
  if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    while(true) { delay(100); } // Infinite loop on failure
  }

  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0,0);
  display.println("ESP32-S3 MacroPad");
  display.println("System Ready.");
  display.display();

  // Initialize Native USB HID
  Keyboard.begin();
  USB.begin();
}

void loop() {
  checkButton(BTN_1, 0, KEY_UP_ARROW);
  checkButton(BTN_2, 1, KEY_DOWN_ARROW);
  checkButton(BTN_3, 2, KEY_RETURN);
}

void checkButton(int pin, int index, char keyCode) {
  int reading = digitalRead(pin);
  
  if (reading != lastButtonState[index]) {
    lastDebounceTime[index] = millis();
  }
  
  if ((millis() - lastDebounceTime[index]) > debounceDelay) {
    if (reading != buttonState[index]) {
      buttonState[index] = reading;
      if (buttonState[index] == LOW) {
        Keyboard.press(keyCode);
        updateScreen(keyCode);
      } else {
        Keyboard.release(keyCode);
      }
    }
  }
  lastButtonState[index] = reading;
}

void updateScreen(char key) {
  display.clearDisplay();
  display.setCursor(0,0);
  display.println("Macro Triggered:");
  display.setTextSize(2);
  display.setCursor(0,20);
  if (key == KEY_UP_ARROW) display.print("UP");
  else if (key == KEY_DOWN_ARROW) display.print("DOWN");
  else if (key == KEY_RETURN) display.print("ENTER");
  display.display();
  display.setTextSize(1);
}

Debugging: When the PC Says "USB Device Not Recognized"

Native USB on the S3 is powerful, but when the USB stack crashes or misconfigures, it fails silently or throws OS-level errors. If you encounter the exact Windows error string "USB Device Not Recognized" or the Arduino IDE throws "A fatal error occurred: Failed to connect to ESP32-S3: No serial data was received.", follow these first three things to check:

1. Verify Arduino IDE USB Mode Settings: The most common failure in ESP32-S projects is leaving the board in standard UART mode. Go to Tools > USB Mode and ensure USB-OTG (TinyUSB) is selected. If you select Hardware CDC and JTAG, the chip acts as a serial debugger, not an HID keyboard.
2. Check the Physical Cable and Port: The ESP32-S3 DevKitC-1 uses a USB Type-C connector. Many Type-C cables bundled with cheap electronics are "charge-only" and lack the D+ and D- data lines. Swap to a verified data cable. Also, plug directly into the motherboard's rear I/O; front panel hubs often lack the 500mA current spike capability needed when the S3 initializes the USB PHY.
3. Execute the Manual Bootloader Sequence: If your code crashed the USB stack (e.g., a memory leak in the HID descriptor loop), the chip might be stuck. Press and hold the BOOT button on the DevKit, tap the RST button, and then release BOOT. This forces the ROM bootloader to enumerate as a standard serial device, allowing you to flash a corrected sketch.

How to Extend or Simplify the Build

To Simplify: If you don't have an I2C OLED on hand, strip out the Adafruit_SSD1306 and Wire libraries. Replace the updateScreen() function calls with Serial.println(). Because we enabled "USB CDC On Boot", the native USB port will simultaneously handle HID keyboard outputs and Serial Monitor debug outputs over the same cable.

To Extend: Upgrade the build by adding a rotary encoder for volume or timeline scrubbing. The ESP32-S3 features a dedicated Pulse Counter (PCNT) peripheral. By wiring the encoder's A and B pins to GPIO 17 and 18, you can use the pcnt driver to track rotation without consuming CPU cycles in the main loop, leaving the TinyUSB stack completely uninterrupted. For wireless operation, you can pivot the code to use the BleKeyboard library, though you will lose the native USB-OTG benefits and rely on BLE HID profiles instead.

FAQ: Your ESP32-S Projects Questions Answered

Can I use the original ESP32 (ESP32-WROOM) for these ESP32-S projects?

No, not for native USB HID. The original ESP32 lacks the USB OTG peripheral required to emulate a keyboard directly. You would need to add an external USB-to-Serial/HID bridge chip or use Bluetooth Classic/BLE to achieve similar functionality. If your project strictly requires a wired USB keyboard interface, the ESP32-S2 or ESP32-S3 is mandatory.

Why does my ESP32-S3 get stuck in download mode after uploading?

This happens when the GPIO 0 strapping pin is held low during a reset. On the DevKitC-1, this usually occurs if your external circuit (like a button wired to GPIO 0) is pulling the pin to GND when the board reboots after a flash. Always use GPIO 4 through 18 for user inputs to avoid interfering with the S3's boot-strapping sequence.

How do I enable the USB CDC On Boot for Serial Monitor output?

In the Arduino IDE Tools menu, set USB CDC On Boot to Enabled. This tells the TinyUSB stack to instantiate a Communications Device Class (CDC) interface alongside your HID interface. This allows you to use Serial.println() for debugging while simultaneously sending keystrokes to the host PC.

What is the difference between the ESP32-S2 and ESP32-S3 for HID projects?

Both support native USB OTG and can run TinyUSB for HID projects. However, the ESP32-S3 is a dual-core 240MHz chip with Bluetooth 5 (LE) support, whereas the S2 is single-core and lacks Bluetooth entirely. For a simple wired macro pad, the S2 is sufficient and often cheaper. But if you plan to add wireless BLE macros or run local voice-command AI models via the S3's vector instructions, the S3 is the superior choice. For more on architectural differences, refer to the Arduino ESP32 Core Documentation.