Harrison Riehle
All guides

Build a three-key Bluetooth keyboard

Wire up an ESP32 and three mechanical switches, then map each key to anything you want.

By Harrison Riehle, updated November 6, 2026

Build time
2 to 4 hours
Parts cost
About $18
Level
Beginner
License
MIT
Get the code on GitHub

How it works

VibeKey is three mechanical keys wired to an ESP32. The board connects to your computer, phone or tablet as a Bluetooth keyboard, so there are no drivers to install.

Each key sends whatever you assign to it, such as mute, volume, push-to-talk or a multi-key macro. Your mappings are saved on the board, so they stay with it when you switch devices. Changing a mapping doesn't require reflashing the firmware.

The build takes about 2 to 4 hours and costs about $18.

What you need

  • ESP32-S3 DevKitC-1, about $8 to $10
  • 3 MX-compatible key switches and keycaps, about $5 to $6
  • A USB-C cable
  • 6 short wires, 22 to 26 AWG
  • Optional: an LED and a 220 ohm resistor for a status light
  • Optional: a 3D printer for the case

1. Wire the switches

Each switch connects to one GPIO pin and to ground.

SwitchPin A to ESP32Pin B to ESP32
Button 1GPIO 4GND
Button 2GPIO 5GND
Button 3GPIO 6GND
Wiring diagram: buttons 1, 2 and 3 connect to GPIO 4, 5 and 6, and each one also connects to ground.
You can regenerate this diagram any time with ./vibekey diagram.

The repo's HARDWARE.md has the full assembly walkthrough, with soldering tips and LED wiring.

2. Run the setup wizard

Plug in the board, get the code and start the wizard:

git clone https://github.com/hpriehle/vibekey.git
cd vibekey
./vibekey setup

The wizard installs PlatformIO and pyserial, configures your pins and Bluetooth name, and flashes the firmware. It then helps you pair over Bluetooth and map your three buttons.

3. Change your keys

You can remap at any time without reflashing:

./vibekey map                 # interactive menu
./vibekey map mute f13 space  # set all three at once
./vibekey map --get           # show current mappings
./vibekey keys                # list every key name

For combos, assign a macro to a button. Separate the steps with spaces, and use 0 for a pause:

./vibekey macro 1 left_ctrl+c
./vibekey macro 3 left_ctrl+a 0 left_ctrl+c

The board stores three profiles, which you switch with ./vibekey profile 1. You can also hold buttons 1 and 3 during boot to cycle through them.

4. Print the case

The case holds the three switches side by side, with the board underneath. Generating the STL files requires OpenSCAD:

cd case && make

Print with a 0.2mm layer height and 20% infill in PLA or PETG. It doesn't need supports.

If something goes wrong

ProblemWhat to do
VibeKey doesn't appear in BluetoothRun ./vibekey monitor to check the firmware output, then reset the board.
A press isn't detectedCheck the wiring, then watch ./vibekey monitor while you press the key.
The computer doesn't receive the keystrokeRemove the Bluetooth pairing and pair again.
One press registers twiceRaise DEBOUNCE_MS in firmware/config.h to 80 to 100, then reflash.
The serial port isn't foundRun ./vibekey ports, then pass the port with -p.
The upload failsHold the BOOT button on the board while it uploads.

This guide is free

Follow along if it helps, and pay what you like. $0 is fine.

I'll only use it to send you new guides.