Skip to the content
2 layers150.2 × 90.2 mmMacropad, the printed circuit board in 3D

Every version lives side by side in this repo — firmware/v4/, firmware/v5/, cad/stl/v5/ and so on. main is always the latest working state; released versions are marked with git tags, so you can grab any of them:

Size
150.2 × 90.2 mm
Copper layers
2
Thickness
1.6 mm
Parts
39
Nets
51
Pads
160
Tracks, vias
242, 7
Routed
Yes
KiCad
KiCad 10.0 (file 20260206)
Created
23 Mar 2026
Updated
2 Oct 2026

Overview

Macropad is an open-source printed circuit board by saiprashanth802, from the saiprashanth802/ESP32-BLE-Macropad repository on GitHub. It is a 2-layer board of 150.2 × 90.2 mm with 39 parts on 51 nets, routed with 242 tracks and 7 vias.

Its parts include 13 switches, 12 diodes, 8 resistors and 6 connectors. It belongs with the keyboards and input boards of this library.

README

README.md

ESP32 BLE HID MacroPad

An open-source, battery-powered wireless BLE HID macro pad built on ESP32 with NimBLE stack. Hand-wired with a custom FDM-printed enclosure, fully self-contained shortcut controller with an on-device UI — no companion app required.

License: CC BY-NC 4.0


Versions

Every version lives side by side in this repo — firmware/v4/, firmware/v5/, cad/stl/v5/ and so on. main is always the latest working state; released versions are marked with git tags, so you can grab any of them:

bash
git clone https://github.com/saiprashanth802/ESP32-BLE-Macropad.git
git checkout v4.1     # or v5.0 — see Releases for downloadable zips
VersionTagStatusDescription
v3—✅ Complete8-button, ST7735 128×160, ESP32-BLE-Keyboard — flagship build
v4v4.1✅ StableNimBLE stack, ghost connection fix, BUILD MODE
v4 + Media Remote—🔬 TestingWireless AS5600 scroll wheel via ESP-NOW
v5v5.0✅ Built & Running12-key MX matrix, ST7789 240×320, multi-host BLE, robot face, Windows companion app
v5.1v5.1✅ CurrentLocal-LLM rewrite menu driven from the pad, wireless encoder puck complete

v3 — Flagship Build

Primary portfolio entry. 8-button macro pad with ST7735 display, NimBLE BLE HID, and on-device preset switching with BUILD MODE.

Build Photos

AssembledInternals
Assembled v3Internal wiring
CAD BodyCAD Knob
Enclosure CADEncoder knob CAD

Hardware

  • ESP32 WROOM-32
  • ST7735 128×160 TN display
  • 8× tactile switches in 4×2 layout
  • EC11 rotary encoder + custom skull knob
  • TP4056 + 18650 2600mAh battery
  • M3 corner studs with heat-set inserts
  • Hand-wired, FDM printed enclosure (PLA, 0.2mm, 20% gyroid)

Features

  • 8 presets: OnShape, KiCad, Music, Gaming, LTspice, SYS, DEV, EDIT
  • BUILD MODE — remap any button live (hold encoder 1.5s)
  • Encoder modes: VOL / SCROLL / ZOOM / ALT-TAB
  • Settings menu: brightness, sleep timeout, sensitivity, OS layout
  • OS Layout: Windows / Linux — remaps shortcuts live
  • RTOS light-sleep with GPIO wakeup
  • Wake-key buffer + reconnect HUD
  • BLE bond clear (hold encoder 3s)
  • Estimated battery life: 3–4 months typical desk use

GPIO Allocation (v3/v4)

GPIOFunction
14,13,26,25,22,21,35,198× buttons
2, 4Encoder CLK, DT
15Encoder SW
5, 17, 16, 12TFT CS, DC, RST, BL
23, 18SPI MOSI, SCLK

v4 — Current Stable

Migrated to NimBLE-Arduino to fix persistent BLE ghost-connection bug on Windows sleep/wake cycles.

Key Changes from v3

  • NimBLE-Arduino replaces ESP32-BLE-Keyboard
  • GAP-layer callbacks for reliable connect/disconnect tracking
  • 1N5819 Schottky diode on VIN rail isolating charger from USB supply
  • esp_sleep_disable_wakeup_source() before re-arming GPIO wakeup each cycle
  • ledcAttach() called on every wake to restore PWM backlight
  • Firmware: macropad_v4_nimble_espnow.ino

TFT_eSPI User_Setup.h

cpp
#define ST7735_DRIVER
#define TFT_CS   5
#define TFT_DC   17
#define TFT_RST  16
#define TFT_WIDTH  128
#define TFT_HEIGHT 160
#define TFT_MOSI 23
#define TFT_SCLK 18

Media Remote — Test Phase

Standalone wireless scroll wheel using AS5600 magnetic encoder. Connects to v4 macropad via ESP-NOW or directly to PC via BLE HID. Designed for high-resolution smooth scrolling with velocity-based acceleration.

Hardware

  • ESP32 NodeMCU dev board
  • AS5600 magnetic rotary encoder (I2C, 12-bit resolution, 4096 steps/rev)
  • Custom 3D printed enclosure with bearing-mounted 50mm scroll wheel
  • Diametrically magnetized cylinder magnet on axle
  • 3× tactile buttons — Play/Pause, Next, Prev

Design & Prototype

Enclosure CADScroll wheel CAD
Enclosure CADScroll wheel with bearing mount CAD

Media remote prototype

Prototype — printed enclosure with 50mm scroll wheel, AS5600 underneath, wired to NodeMCU ESP32S

Features

  • Velocity-accelerated volume control — slow turn = fine steps, fast spin = large jumps
  • Adjustable sensitivity 1–10, saved to NVS
  • Hold Btn1 + turn wheel = adjust sensitivity live
  • Hold Btn1 + Btn3 for 1.5s = toggle ESP-NOW ↔ BLE mode
  • Mode and sensitivity persist across power cycles
  • LED blink feedback: 1 blink = ESP-NOW, 3 blinks = BLE

Modes

ModeDescription
BLE HIDConnects directly to PC as "MediaRemote"
ESP-NOWSends to v4 macropad which relays via BLE to PC

Wiring

PinGPIOFunction
AS5600 SDA21I2C data
AS5600 SCL22I2C clock
BTN1 Play/Pause27INPUT_PULLUP → GND
BTN2 Next26INPUT_PULLUP → GND
BTN3 Prev25INPUT_PULLUP → GND
LED2Onboard LED

v5 — Built & Running

Full redesign, assembled and working. 12-key MX mechanical switch matrix (4×3 landscape), ST7789 240×320 IPS display, multi-host BLE with 3 device slots (Logitech Easy-Switch style), a state-reactive robot face with personalities, and a Windows companion app that turns the pad into a Stream Deck.

Build Photos

Assembled v5, angledv5 from above
Assembled v5 — printed case, spiral-top keycaps, blue accent lightingTop-down: 4×3 MX grid and the 2" IPS display

v5 front view

The screen shows the pad's two live features at once: the procedural robot eyes in their default robotic blue, and the now-playing strip — track title with a progress bar and elapsed/total time, streamed from the host by the companion app.

Print files: cad/stl/v5/ — three case parts plus the switch plate.

Multi-Host BLE — use it like a Pebble Keys

  • 3 host slots, each remembers one bonded device (NVS persisted across power cycles)
  • Hold FN (K9) 1s → tap K1/K2/K3 to jump between paired devices
  • Hold the slot key 1.5s instead to (re-)pair that slot with a new device
  • Each slot advertises its own static-random BLE address, so every host stores an independent bond. This is what makes the slots real: with one shared identity, two OSes dual-booting the same machine present the same controller MAC, collapse onto one slot, and each re-pair overwrites the other's link key — the endless forget-and-re-pair loop
  • Switching re-advertises open (no accept-list — whitelist filtering breaks reconnection from resolvable private addresses); a bonded host that belongs to a different slot is rejected in software
  • Status bar shows the three slots like Easy-Switch LEDs (green = connected, amber = waiting, magenta = pairing)
  • Firmware: firmware/v5/macropad_v5.ino (NimBLE 2.x API, single file)

Face — state-reactive robot eyes / GIF screensaver

  • Procedural eyes that react to device state: blink when idle-connected, dart when disconnected, widen in pairing mode, glance toward the slot on Easy-Switch, droop before sleep
  • Expression packs: every eye parameter (color, geometry, blink/glance timing) is JSON in the config API — the companion app can generate personalities without reflashing
  • Or upload a looping GIF (≤ ~700 KB) through the web UI as an ambient screensaver
  • Settings → FACE (OFF/IDLE/ALWAYS) and STYLE (EYES/GIF); first press always just wakes, never types
  • Custom partition table: dual 1.5 MB OTA slots + 896 KB SPIFFS for animations

Rewrite Menu — local LLM text tools, driven from the pad

  • Select text anywhere, press a key on the pad, pick a style — the pad rewrites it in place
  • Styles: formalise, casualise, shorten, clarify, fix spelling/grammar, summarise, expand rough notes into an email, or treat the selection as a prompt and answer it
  • Runs against a local Ollama instance, so nothing leaves the machine unless a style is deliberately pointed at a hosted model
  • Prompts, temperature, reasoning and per-style model live in a hot-reloaded styles.json — tune them without a rebuild
  • Pad shows the style picker, then ACCEPT / REGEN / CANCEL; the side-by-side preview on screen is editable before you accept
  • Built entirely on the existing host-link opcodes — no firmware changes required
  • A fine-tuned FIX model was trained for this and measured against the general-purpose one across two sizes and four epoch counts. It wins on corrections and speed and loses on restraint, which is the axis that decides — so it did not ship, and the lab is in the repo anyway: ml/ and docs/FIX_MODEL_FINETUNE.md
  • Full guide: docs/REWRITE_MENU.md · Linux setup: docs/LINUX_REWRITE_SETUP.md

Companion App — Windows and Linux

The pad works standalone. The companion turns it into a Stream Deck: it launches and focuses apps from a key press, streams now-playing to the pad's screen, switches presets to follow the foreground window, feeds the puck a real volume number, and drives the rewrite menu.

  • Two front-ends over one shared .NET 9 core — MacroPadDeck.Core holds the wire protocol, profiles and orchestration; MacroPadDeck is WinRT/SMTC/WPF, and MacroPadDeck.Linux is BlueZ/MPRIS/X11/GTK3
  • Install, build and run: companion/README.md — .NET 9 SDK per platform, the dependencies, pairing, the publish command, and what each failure in deck.log means

Config Mode — wireless setup + OTA firmware update

  • Settings → CONFIG (WiFi/OTA) suspends BLE and raises a WiFi hotspot (MacroPad-Setup / macropad123, http://192.168.4.1)
  • Built-in web UI + JSON API to remap keys, edit presets, and change settings — no re-flash needed
  • Every key can be a built-in action, an arbitrary modifier+keycode chord, a media code, a type-a-string, or a multi-step macro — the schema a companion app targets
  • OTA firmware update: upload a new .bin from the browser; it flashes the inactive OTA partition and reboots (safe rollback if it fails)
  • WiFi and BLE never run at once (WROOM-32 coexistence); entering/leaving Config Mode reboots cleanly
  • Full contract: docs/CONFIG_API.md

Wireless Encoder Puck — a dial that isn't attached to anything

Puck beside the padPuck in hand
The puck beside the v5 — a separate battery-powered device, no cable between them50 mm dial in the two-part printed housing
  • Separate device, talks to the pad over ESP-NOW — no cable, no second BLE connection to manage
  • AS5600 magnetic angle sensor — 12-bit, contactless, nothing mechanical to wear out. The magnet is diametrically magnetised and sits in a pocket in the dial
  • The pad owns the dial mode (VOLUME / ZOOM). The puck renders whatever it's told and never self-changes, so a pad key and the puck can't disagree
  • Volume is pushed, never estimated. BLE HID volume is relative — the pad sends up/down and is never told the level — so the companion reading Windows Core Audio is the only way either device knows a real number
  • Deep sleep when unlinked, waking on rotation. The AS5600 has no motion interrupt, so waking is timer-poll-and-look with a movement threshold, which stops a knock or thermal drift waking it
  • Sealed housing with no reset button — spinning the dial a few turns while unlinked reboots it. Gated strictly on being unlinked, since spinning hard is completely ordinary during normal volume use
  • Wiring: hardware/puck_wiring.md · Protocol: docs/PUCK_PROTOCOL.md · Print files: cad/stl/puck/

Hardware Spec

  • NodeMCU ESP32-S V1.1 (WROOM-32) dev board
  • ST7789 240×320 IPS display, landscape mount, glass flush-mounted (30.6×40.8mm active area)
  • 12× MX compatible mechanical switches, plate mount, 4×3 landscape matrix, 19.05mm pitch
  • 12× 1N4148 diodes for n-key rollover (cathode → row line — see hardware/pin_reference_v5.md)
  • Wireless encoder puck: AS5600 + 50mm bearing-mounted dial, ESP-NOW (separate device — built and working; see hardware/puck_wiring.md and docs/PUCK_PROTOCOL.md)
  • CKCS charge+boost module + 18650 cell
  • Custom copper-tape ridge substrate PCB

Enclosure

  • 115×95×30mm main body
  • Encoder dial lobe: half-proud right edge, 50mm diameter, 25mm proud (XP-Pen style)
  • Screen: 31.0×41.2mm flush glass window, 35.2×48.4mm module ledge 2.1mm deep
  • Bottom cover: M3 screws into brass heat-set inserts, 4× corners

PCB Technique — Copper Tape Ridge Substrate

3D printed plate with elevated ridges as trace isolation guides. A single copper sheet is laid over the entire surface — the ridges act as cutting guides. Scalpel-cut along ridge edges isolates traces. Looks like a real PCB, built from scratch.

v5 GPIO Allocation

GPIOBoard LabelFunctionNotes
18P18TFT SCKSPI clock
23P23TFT MOSIST7789 SDA
5P5TFT CS
21P21TFT DC
22P22TFT RST
19P19TFT BLPWM via LEDC
25P25Matrix Row 1Driven LOW to scan
26P26Matrix Row 2Driven LOW to scan
27P27Matrix Row 3Driven LOW to scan
32P32Matrix Row 4Driven LOW to scan
33P33Matrix Col 1INPUT_PULLUP
13P13Matrix Col 2INPUT_PULLUP
14P14Matrix Col 3INPUT_PULLUP

Zero strapping pins used — clean boot every time, no pull resistors needed for boot. No I2C or encoder switch on the main board — the AS5600 puck is wireless. Full details + diode orientation: hardware/pin_reference_v5.md.


Repository Structure

text
ESP32-BLE-MacroPad/
├── firmware/
│   ├── v4/macropad_v4_nimble_espnow.ino   — v4 + optional ESP-NOW
│   ├── v5/
│   │   ├── macropad_v5/                   — v5 multi-host firmware + partition table
│   │   ├── puck_encoder/                  — wireless encoder puck (ESP32)
│   │   ├── puck_encoder_8266/             — puck on ESP-12E
│   │   └── User_Setup.h                   — TFT_eSPI config for the ST7789
│   ├── media_remote/                      — BLE + ESP-NOW scroll wheel
│   └── tests/                             — per-peripheral bring-up sketches
├── companion/
│   ├── README.md                          — install / build / run — start here
│   ├── MacroPadDeck.Core/                 — protocol, profiles, controller (net9.0)
│   ├── MacroPadDeck/                      — Windows front-end (WinRT/WPF)
│   └── MacroPadDeck.Linux/                — Linux front-end (BlueZ/MPRIS/GTK3)
├── ml/                                    — the FIX fine-tune lab: data generator,
│                                            eval harness, training configs, runbook
├── cad/stl/                               — print files: v5 case, keycaps, puck
├── hardware/
│   ├── pin_reference_v5.md                — complete v5 GPIO table + diode orientation
│   ├── puck_wiring.md                     — encoder puck wiring
│   ├── kicad/                             — KiCad project + fab gerbers
│   ├── datasheets/                        — ESP-12E
│   └── ESP32_DevKitC_v4.kicad_mod         — custom KiCad footprint

Dependencies

LibraryPurpose
NimBLE-ArduinoBLE HID stack
TFT_eSPIDisplay driver
PreferencesNVS persistent storage
WireI2C for AS5600
esp_nowESP-NOW for media remote

Companion app (see companion/README.md):

RequirementPurpose
.NET 9 SDKBuilds all three companion projects
BlueZ / WinRTBLE host link to the pad
GTK3 + libayatana-appindicatorLinux tray and editor
MPRIS / SMTCNow-playing source
Ollama (optional)Local model behind the rewrite menu

Key Learnings

  • NimBLE vs ESP32-BLE-Keyboard — NimBLE with GAP callbacks is required for reliable connect/disconnect tracking. The Arduino BLE stack returns false positives after Windows sleep/wake.
  • GPIO 12 strapping pin — Must read LOW at boot. Avoided entirely in v5 by moving TFT backlight to GPIO 19.
  • LEDC + BLE init order — BLE radio init resets the LEDC peripheral. Always call ledcAttach() after NimBLEDevice::init().
  • WiFi + BLE coexistence — ESP-NOW and NimBLE share the antenna. Made optional in v4 (toggle in settings) to avoid connection instability.
  • ST7789 RAM constraint — Full 240×320 16-bit sprite = 153KB, too large for WROOM-32 with BLE active. Solution: direct TFT drawing with small reusable sprites.
  • Input-only GPIOs — GPIO 34, 35, 36, 39 have no internal pullups. Always use external 10kΩ resistors.

License

CC BY-NC 4.0 — Free to use and modify for personal and non-commercial purposes only. Commercial use requires explicit written permission from the author.

Parts

39
QtyValueFootprintReferences
121N4148Diode_THT:D_DO-35_SOD27_P7.62mm_HorizontalD12, D13, D14, D15, D16, D17, D18, D19, D20, D21, D22, D23
12SW_PushButton_Switch_Keyboard:SW_Cherry_MX_1.00u_PCBSW1, SW2, SW3, SW4, SW5, SW6, SW7, SW8, SW9, SW10, SW11, SW12
810kResistor_THT:R_Axial_DIN0207_L6.3mm_D2.5mm_P7.62mm_HorizontalR1, R2, R3, R4, R5, R6, R7, R8
2Conn_01x19Connector_PinHeader_2.54mm:PinHeader_1x19_P2.54mm_HorizontalJ4, J5
1Conn_01x02Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_HorizontalJ6
1Conn_01x03Connector_PinHeader_2.54mm:PinHeader_1x03_P2.54mm_VerticalJ1
1Conn_01x04Connector_PinHeader_2.54mm:PinHeader_1x04_P2.54mm_VerticalJ3
1Conn_01x09Connector_PinHeader_2.54mm:PinHeader_1x09_P2.54mm_VerticalJ2
1SW_PushButton_Switch_THT:SW_PUSH_6mm_H4.3mmSW13

Similar boards

  • 2 layers24.4 × 24.4 mmOSO SWAT B1, the printed circuit board in 3D

    OSO SWAT B1

    joeycastillo/Sensor-Watch

    A board replacement for the classic Casio F-91W wristwatch

    39 parts2.1k
  • 2 layers33 × 26 mmVL53L1x pwm, the printed circuit board in 3D

    VL53L1x pwm

    hackclub/OnBoard

    💡 Join 1,000 teenagers and make your first PCB with a $100 grant!

    39 parts915
  • 2 layers43.4 × 18.8 mmUsb sniffer lite, the printed circuit board in 3D

    Usb sniffer lite

    ataradov/usb-sniffer-lite

    A simple USB sniffer based on Raspberry Pi RP2040

    39 parts706BSD-3-Clause
  • 2 layers40 × 20 mmESP8266, the printed circuit board in 3D

    ESP8266

    windowsair/wireless-esp8266-dap

    CMSIS-DAP compatible wireless debugger for ESP8266/ESP32/ESP32C3/ESP32S3. Optional 40MHz SPI acceleration, etc. 适配多种ESP芯片的无线调试器

    39 parts690MIT
  • 2 layers100 × 70.3 mmModulAdapterMagnet, the printed circuit board in 3D

    ModulAdapterMagnet

    GaudiLabs/OpenDrop

    Open Source Digital Microfluidics Bio Lab

    39 parts492GPL-3.0
  • 2 layers81.3 × 53.3 mmRGB LED 1.4, the printed circuit board in 3D

    RGB LED 1.4

    lachlanA/eagle-to-kicad

    Eagle SCH/LIB to KiCad SCH/LIB ULP conversion script

    39 parts429GPL-2.0
  • 2 layers65.7 × 44.8 mmDock, the printed circuit board in 3D

    Dock

    mackieks/Kawaii

    Tiny, beautiful metal Wii keychain

    39 parts374

Questions

How big is the Macropad PCB?

It measures 150.2 × 90.2 mm and has 2 copper layers, 1.6 mm thick.

What parts does the Macropad use?

39 parts. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the Macropad KiCad files?

From the saiprashanth802/ESP32-BLE-Macropad repository on GitHub, at the commit this page was made from: the board is hardware/kicad/macropad.kicad_pcb and its schematic hardware/kicad/macropad.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the Macropad design in my own project?

Its repository states no licence, so its author keeps all rights: ask saiprashanth802 before reusing the design.