MacroPad Deploy & Usage Guide

A comprehensive guide to building, flashing, and deploying the ESP32-C3 MacroPad firmware and Windows desktop configurator.

Prerequisites

Hardware Requirements

Software Requirements

• Node.js 18.x LTS or newer
• npm 9.x or newer (or pnpm/yarn)
• Arduino IDE 2.x or PlatformIO (VS Code extension)
• ESP32 Board Support (Espressif Systems)
• NimBLE-Arduino library v1.4+
• Git for cloning

Windows-Specific Prerequisites

The desktop app uses PowerShell for key simulation. Ensure:

• PowerShell 5.1 or PowerShell 7+ available at powershell.exe or pwsh
• Execution policy allows script execution (see Troubleshooting)

Installation

1. Clone the Repository

git clone https://github.com/aayushchouhan24/MacroPad.git
cd MacroPad

2. Firmware Dependencies (Arduino IDE)

1. Open Arduino IDE
2. Add ESP32 board support:
   • File → Preferences → Additional Board Manager URLs
   • Add: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   • Tools → Board → Boards Manager → Search "ESP32" → Install "ESP32 by Espressif Systems"
3. Install NimBLE library:
   • Sketch → Include Library → Manage Libraries
   • Search "NimBLE-Arduino" → Install v1.4.0 or newer

3. Desktop App Dependencies

cd MacroPadApp
npm install

Configuration

Hardware Pin Configuration

Wire the ESP32-C3 according to the matrix layout (do not change pins without modifying firmware):

Matrix Layout:

     C1   C2   C3   C4   C5
R1   K1   K2   K3   K4   K5/ENC_BTN
R2   K6   K7   K8   K9   K10

Firmware Board Settings

In Arduino IDE, select these exact settings for ESP32-C3 Mini:

• Board: ESP32C3 Dev Module
• USB CDC On Boot: Enabled (critical for USB serial)
• Flash Mode: QIO
• Flash Size: 4MB
• Partition Scheme: Default 4MB with spiffs
• Upload Speed: 921600

App Configuration (Optional)

The app uses electron-store for persistent configuration stored at:

• %APPDATA%/MacroPad/macropad-config.json

Default settings (no manual editing required):

• Auto-connect: Enabled
• Minimize to tray: Enabled
• Auto-start: Disabled

Build & Run

Firmware (One-time Flash)

1. Open Sketch:

   # In Arduino IDE
   File → Open → MacroPad/MacroPadSketch/MacroPadSketch.ino
   

2. Compile and Upload:

   • Select COM port (appears as USB Serial when ESP32-C3 connected)
   • Click Upload (→ arrow)
   • First-time upload: Hold BOOT button while connecting USB if upload fails

3. Verify:

   • Open Serial Monitor (115200 baud)
   • You should see: "MacroPad BLE Server started" and USB initialization logs

Desktop App (Development)

cd MacroPadApp

# Run in development mode with hot reload
npm run dev

# or if using electron-vite (common with this structure)
npm run electron:dev

Desktop App (Production Build)

cd MacroPadApp

# Build Windows installer (.exe)
npm run build

# Output location:
# dist/MacroPad-Setup-1.0.0.exe (or similar, version dependent)

Deployment

Firmware Deployment

The firmware is deployed directly to the ESP32-C3 flash memory:

1. Via Arduino IDE: Upload button (as above)
2. Via PlatformIO (if configured):

   cd MacroPadSketch
   pio run --target upload
   pio device monitor  # View serial output
   

Note: Configuration profiles are stored in the ESP32's SPIFFS filesystem, uploaded via the desktop app over USB/Bluetooth—no separate firmware flashing required for keymap changes.

Desktop App Distribution

Method 1: Windows Installer (Recommended)

cd MacroPadApp
npm run dist
# Creates: dist/MacroPad-Setup-x.x.x.exe

Distribute the .exe installer. It handles:

• Installing VC++ redistributables (if needed)
• Creating Start Menu shortcuts
• Registering auto-startup capability

Method 2: Portable Build

npm run build:win
# Creates: dist/win-unpacked/ folder

Zip the win-unpacked folder for portable usage (no installer).

Method 3: Store Distribution

The app uses no elevated privileges (standard user level), making it compatible with:

• Microsoft Store (via electron-builder with appx target)
• Winget (via GitHub releases manifest)

Update electron-builder.yml (create if missing) to add targets:

win:
  target:
    - nsis
    - portable
    - appx

Troubleshooting

Firmware Upload Issues

Error: Failed to connect to ESP32: Timed out waiting for packet header

• Solution: Hold the BOOT button on ESP32-C3 while clicking Upload, release when "Connecting..." appears
• Alternative: Lower upload speed to 115200 in Tools menu

Error: USB CDC On Boot must be enabled but greyed out

• Solution: Select "ESP32C3 Dev Module" specifically, not generic "ESP32"

Desktop App Issues

Symptom: App opens but keys don't simulate on Windows

• Cause: PowerShell execution policy blocks the keySender script
• Fix: Run as Administrator:

  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  

Symptom: "Web Serial API not available" or USB device not detected

• Fix:
  1. Ensure USB CDC On Boot was enabled when flashing firmware
  2. Use Chrome/Edge based Electron (bundled) - Web Serial requires Chromium
  3. Check Device Manager shows "USB Serial Device (COMx)" not just charging

Symptom: Bluetooth device appears but won't pair

• Fix:
  1. Ensure NimBLE-Arduino v1.4+ installed (older versions have C3 compatibility issues)
  2. Clear paired devices in Windows Bluetooth settings
  3. Check Windows supports BLE 4.2+ (Bluetooth Settings → Advanced)

Hardware Issues

Symptom: Ghost keys or multiple keys triggering

• Fix: Verify 1N4148 diodes are installed in correct orientation (cathode/band towards column)

Symptom: Encoder rotation backwards

• Fix: Swap GPIO 5 and GPIO 6 wires, or invert in software via desktop app (Encoder Settings → Invert Direction)

Symptom: Key 5 (encoder button) not working

• Fix: Verify encoder button shares Row 1/Column 5 matrix position, not separate GPIO

Data Persistence

Issue: Profiles lost after app update

• Location: %APPDATA%/MacroPad/backups/
• Recovery: Copy macropad-config.backup.json to macropad-config.json in parent directory

Issue: Config uploads to device but resets on power cycle

• Cause: SPIFFS not formatted or partition scheme wrong
• Fix: Re-flash firmware with "Default 4MB with spiffs" partition scheme selected