MacroPad Configurator

Desktop application for configuring Adafruit MacroPad RP2040 macro keyboard.

Features

✅ Auto-detect MacroPad - Automatically finds your device
✅ Profile Management - Switch between multiple macro sets
✅ Visual Editor - Intuitive macro configuration with ActionBuilder
✅ Virtual Keyboard - Quick and advanced key selection modes
✅ Template Library - 12 pre-configured macro templates
✅ Color Customization - Customize NeoPixel LED colors
✅ Change Tracking - Unsaved changes indicator, Apply/Revert
✅ Validation - Prevents invalid configurations
✅ Automatic Backup - Creates .bak files before saving

Screenshots

Main Interface

• Profile switcher in sidebar
• 3x4 macro button grid with status indicators
• Click any button to edit its macro

Macro Editor

• Name, type (once/hold/toggle) configuration
• Action list with move up/down
• Add/Edit/Delete actions
• Custom color overrides (optional)

Action Builder

• 7 action types: press, release, type, mouse_click, mouse_move, mouse_scroll, wait
• Dynamic fields based on action type
• Inline wait parameters
• Random duration support

Key Selector

• Quick mode: 10 common key combinations
• Advanced mode: Full virtual keyboard with modifiers
• Live preview of selected combination

Requirements

For Users (Running .exe)

• Windows 10/11
• Adafruit MacroPad RP2040 connected via USB
• MacroPad must appear as USB drive (E:, D:, or F:)

For Developers (Building from source)

• Rust 1.70+
• Node.js v18+
• npm or yarn

Installation & Usage

Option 1: Use Pre-built Executable

1. Download MacroPad_Configurator.exe from releases
2. Connect your MacroPad via USB
3. Double-click the exe file
4. Configure your macros
5. Click "Apply Changes" (or Ctrl+S)
6. Reconnect MacroPad to load new configuration

Option 2: Build from Source

Setup

cd e:\interface
npm install

Development Mode

npm run tauri dev

This will:

1. Start Vite dev server on http://localhost:5173
2. Compile Rust backend
3. Launch application window with hot reload

Build Executable

npm run tauri build

Output: src-tauri/target/release/MacroPad_Configurator.exe (~3-5 MB)

Build Options

# Debug build (faster compile, larger file)
npm run tauri build -- --debug

# Release build with optimizations (slower compile, smaller file)
npm run tauri build

Project Structure

interface/
├── src/                    # React frontend
│   ├── components/         # UI components
│   │   ├── StartScreen.jsx       # Device detection screen
│   │   ├── MainLayout.jsx        # Main app layout
│   │   ├── Sidebar.jsx           # Navigation sidebar
│   │   ├── MacroGrid.jsx         # 3x4 button grid
│   │   ├── MacroEditor.jsx       # Macro configuration modal
│   │   ├── ActionBuilder.jsx     # Action creator/editor
│   │   ├── KeySelector.jsx       # Virtual keyboard
│   │   ├── TemplateSelector.jsx  # Macro templates
│   │   ├── ColorEditor.jsx       # LED color configuration
│   │   └── Settings.jsx          # App settings
│   ├── utils/
│   │   └── templates.js          # Macro template definitions
│   ├── App.jsx             # Main app component
│   ├── main.jsx            # Entry point
│   └── index.css           # Tailwind styles
│
├── src-tauri/              # Rust backend
│   ├── src/
│   │   └── main.rs         # Tauri commands & file I/O
│   ├── Cargo.toml          # Rust dependencies
│   ├── tauri.conf.json     # App configuration
│   └── build.rs            # Build script
│
├── package.json            # NPM dependencies
├── vite.config.js          # Vite configuration
├── tailwind.config.js      # Tailwind CSS config
└── README.md               # This file

Usage Guide

Creating a Macro

1. Click any button in the 3x4 grid (or "+ New Macro")
2. Choose template or start from scratch
3. Configure macro name and type:
   • Once: Executes once per button press
   • Hold: Executes while button held
   • Toggle: Toggles loop on/off
4. Add actions using "+ Add Action"
5. Click "Save Macro"

Action Types

Type	Description	Parameters
press	Press a key combination	key, wait (optional)
release	Release a key	key, wait (optional)
type	Type text	text, wait (optional)
mouse_click	Click mouse button	button (1/2/3), wait (optional)
mouse_move	Move mouse cursor	x, y, wait (optional)
mouse_scroll	Scroll mouse wheel	amount, wait (optional)
wait	Pause execution	duration OR duration_random {min, max}

Keyboard Shortcuts

Shortcut	Action
Ctrl+S	Apply changes
Esc	Close modal/Cancel
↑/↓	Move action in list

Profiles

Profiles are stored in E:\profile.json:

{
  "current": 0,
  "profiles": [
    {
      "id": 0,
      "name": "Wark",
      "macros_file": "profiles/macros_wark.json"
    }
  ]
}

Each profile points to a separate macros JSON file in E:\profiles\.

Color Configuration

8 LED states can be customized:

• ready: Button ready to press
• active: Button currently pressed
• loop: Loop macro running
• wait: Waiting between actions
• queued: Waiting in execution queue
• executing: Currently executing
• no_macro: Empty button slot
• error: Error state

Colors are RGB arrays: [R, G, B] with values 0-255.

Troubleshooting

Device Not Detected

• Ensure MacroPad is connected via USB
• Check if it appears as drive letter (E:, D:, F:)
• Try different USB port or cable
• Restart device by unplugging

Changes Not Applied

• Ensure you clicked "Apply Changes"
• Reconnect MacroPad after applying
• Check for validation errors
• Verify JSON files were updated (check .bak backup)

Build Errors

# Clean build cache
cd src-tauri
cargo clean
cd ..
rm -rf node_modules
npm install

# Rebuild
npm run tauri build

Runtime Errors

Check console for errors:

# Development mode shows detailed errors
npm run tauri dev

Development

Adding New Action Type

1. Add to ACTION_TYPES in ActionBuilder.jsx
2. Add render case in renderFields()
3. Add validation in src-tauri/src/main.rs (validate_macro)
4. Update MacroPad macro_parser.py validation

Adding New Template

Edit src/utils/templates.js:

{
  id: 'my_template',
  name: 'My Template',
  description: 'Description here',
  icon: '🎯',
  type: 'once',
  actions: [
    { type: 'press', key: 'ctrl+c' },
  ],
}

Customizing Colors

Edit tailwind.config.js:

colors: {
  'macropad': {
    'dark': '#1a1a1a',
    'accent': '#00ff88',
  }
}

Technical Details

Tech Stack

• Frontend: React 18 + Vite + Tailwind CSS
• Backend: Rust + Tauri 1.5
• Build: Vite (dev) + Tauri CLI (prod)

File I/O

All file operations go through Rust backend for security:

• detect_macropad() - Auto-find device
• load_profiles() - Read profile.json
• save_profiles() - Write profile.json (with backup)
• load_macros() - Read macros JSON
• save_macros() - Write macros JSON (with backup)
• load_colors() - Read button_colors.json
• save_colors() - Write button_colors.json (with backup)
• validate_macro() - Validate macro structure

Security

• Tauri restricts filesystem access to necessary paths
• All user input validated before saving
• Automatic backups prevent data loss
• No external network access required

License

MIT

Credits

• Built for Adafruit MacroPad RP2040
• Uses Tauri framework
• UI styled with Tailwind CSS

Support

For issues or feature requests, please open an issue on GitHub.