ESP32-C3 USB Keyboard

A simple 9-key USB keyboard implementation for the WeAct ESP32-C3 dev board.

Features

• Acts as a native USB HID keyboard
• 9 programmable switches
• Debounced input for reliable key detection
• Modifier keys (Shift, Ctrl, Alt) work as hold-to-activate
• Works with Arduino IDE and PlatformIO

Hardware Requirements

• WeAct ESP32-C3 Dev Board
• 9 keyboard switches (momentary push buttons)
• Jumper wires
• Optional: pull-up resistors (though internal pull-ups are used)

Key Mappings

Switch	GPIO Pin	Key Function
1	GPIO 0	ESC
2	GPIO 1	TAB
3	GPIO 2	SHIFT
4	GPIO 3	CTRL
5	GPIO 4	ALT
6	GPIO 5	ENTER
7	GPIO 6	SPACE
8	GPIO 7	L
9	GPIO 8	DELETE

Wiring Instructions

Each switch should be connected as follows:

1. One terminal of the switch → GPIO pin (see table above)
2. Other terminal of the switch → GND

The code uses internal pull-up resistors, so the GPIO pins are normally HIGH. When you press a switch, it connects the pin to GND, making it LOW.

         ESP32-C3
         ┌──────┐
Switch 1 │ GPIO0├─┐
         │      │ │
Switch 2 │ GPIO1├─┤
         │      │ │
Switch 3 │ GPIO2├─┤
         │      │ │
Switch 4 │ GPIO3├─┤
         │      │ │
Switch 5 │ GPIO4├─┼─→ One side of all switches
         │      │ │
Switch 6 │ GPIO5├─┤
         │      │ │
Switch 7 │ GPIO6├─┤
         │      │ │
Switch 8 │ GPIO7├─┤
         │      │ │
Switch 9 │ GPIO8├─┤
         │      │ │
         │  GND ├─┘   Other side of all switches
         └──────┘

Setup and Installation

Option 1: Arduino IDE

1. Install ESP32 Board Support:

   • Open Arduino IDE
   • Go to File → Preferences
   • Add this URL to "Additional Board Manager URLs":

     https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
     

   • Go to Tools → Board → Board Manager
   • Search for "esp32" and install "esp32" by Espressif Systems (version 2.0.11 or newer)

2. Select Board:

   • Go to Tools → Board → ESP32 Arduino
   • Select "ESP32C3 Dev Module"

3. Configure USB Settings:

   • Tools → USB Mode → "USB-OTG (TinyUSB)"
   • Tools → USB CDC On Boot → "Disabled"

4. Open and Upload:

   • Open esp32_c3_usb_keyboard.ino
   • Connect your ESP32-C3 via USB
   • Select the correct COM port under Tools → Port
   • Click Upload

Option 2: PlatformIO

1. Install PlatformIO:

   • Install VS Code
   • Install PlatformIO IDE extension

2. Open Project:

   • Open the project folder in VS Code
   • PlatformIO will automatically detect platformio.ini

3. Upload:

   • Click the PlatformIO Upload button (→) in the bottom toolbar
   • Or use the command: pio run --target upload

Usage

1. After uploading the code, unplug and replug the ESP32-C3
2. It should enumerate as a USB HID keyboard on your computer
3. Press any of the switches to send the corresponding key

Notes on Modifier Keys

• SHIFT, CTRL, and ALT work as modifier keys that stay pressed until you release the physical switch
• Other keys (ESC, TAB, ENTER, SPACE, L, DELETE) send a single key press/release when activated

Example Combinations

• Hold SHIFT + press L → sends uppercase "L"
• Hold CTRL + press L → sends Ctrl+L (useful for browser address bar)
• Hold ALT + press TAB → Alt+Tab window switching

Customization

Changing Pin Assignments

Edit the pin definitions in esp32_c3_usb_keyboard.ino:

const int PIN_ESC    = 0;  // Change to your desired GPIO
const int PIN_TAB    = 1;
// ... etc

Changing Key Mappings

Modify the handleKeyPress() function to change what each switch does:

case 0: // First switch
  Keyboard.press(KEY_ESC);  // Change to desired key
  Keyboard.release(KEY_ESC);
  break;

Available Key Constants

Common keys you can use:

• KEY_ESC, KEY_TAB, KEY_RETURN, KEY_DELETE, KEY_BACKSPACE
• KEY_UP_ARROW, KEY_DOWN_ARROW, KEY_LEFT_ARROW, KEY_RIGHT_ARROW
• KEY_LEFT_SHIFT, KEY_RIGHT_SHIFT, KEY_LEFT_CTRL, KEY_RIGHT_CTRL
• KEY_LEFT_ALT, KEY_RIGHT_ALT, KEY_LEFT_GUI, KEY_RIGHT_GUI
• Regular characters: 'a', 'b', '1', ' ', etc.

Troubleshooting

Device Not Recognized

• Make sure you selected the correct board in Arduino IDE
• Verify USB Mode is set to "USB-OTG (TinyUSB)"
• Try a different USB cable (some cables are charge-only)
• Unplug and replug the device

Keys Not Working

• Check your wiring connections
• Verify switches are connected between GPIO and GND
• Use a multimeter to test switch continuity
• Check that the correct GPIO pins are defined in code

Upload Fails

• Hold the BOOT button while clicking Upload
• Release BOOT button after upload starts
• Try reducing upload speed in platformio.ini or Arduino IDE

Multiple Key Presses

• Increase debounceDelay value (currently 50ms)
• Check for loose wiring
• Verify switches are making clean contact

License

This project is provided as-is for educational and personal use.

Contributing

Feel free to modify and adapt this code for your own projects!