Electron based application to drive a physical macro keyboard with Arduino integration.

• Buttons: Support for 8, 12, 16, 24, or 32 button configurations
• Rotary Encoders: Up to 8 rotary encoders for additional input options
• Arduino Micro: Firmware for Arduino Micro controller

• macOS: Status menu integration with native system tray
• Windows: System tray integration with Windows-style notifications
• Linux: Headless service mode with configuration file support

• YAML-based configuration files for easy editing
• GUI configuration interface (macOS/Windows)
• Hot-reload configuration without restart
• Per-button and per-encoder action assignment

• Real-time Recording: Capture key sequences and timing automatically
• Playbook System: Organize macros into reusable playbooks
• Advanced Timing: Configurable delays and timing patterns
• GUI Editor: Visual macro creation and editing interface
• Import/Export: Share macros across devices and teams

• Automatic Switching: Switch profiles based on active application, time, or system state
• Smart Rules Engine: Create complex switching rules with priorities
• Manual Override: Temporary or permanent manual profile control
• Switch History: Complete tracking of all profile switches
• Performance Analytics: Usage statistics and optimization suggestions

• Key Press: Send keyboard shortcuts and key combinations
• Shell Commands: Execute system commands and scripts (with security validation)
• Application Launch: Launch applications and programs

• Input Validation: Comprehensive validation of all user actions
• Command Sanitization: Automatic cleaning and normalization of inputs
• Dangerous Pattern Detection: Blocks malicious commands and system access attempts
• Configurable Security Policies: Allowlist/blacklist modes for fine-grained control
• Cross-platform Protection: Platform-specific security patterns and controls
• Security Logging: Complete audit trail of all security events

• Comprehensive logging with Winston
• Activity monitoring and debugging
• Serial communication status tracking

👉 Complete Getting Started Guide - Everything you need to know in 30 minutes

• Download Latest Release (Recommended)
• Or build from source (see Development Guide)

• Wire your button matrix with diodes (Wiring Guide)
• Flash Arduino firmware (Arduino Guide)
• Connect via USB and configure in the app

buttons:
  button1:
    description: "Volume Up"
    type: "keypress" 
    action: "VolumeUp"
  
  button2:
    description: "Launch Calculator"
    type: "application"
    action: "Calculator"
  
  button3:
    description: "Take Screenshot"
    type: "keypress"
    action: "cmd+shift+3"  # macOS example

Need Help? Check our Troubleshooting Guide or FAQ

The Arduino firmware supports multiple hardware configurations. See the Arduino README for detailed instructions.

• 8 buttons (2×4 matrix) + 0-8 encoders
• 12 buttons (3×4 matrix) + 0-8 encoders
• 16 buttons (4×4 matrix) + 0-8 encoders
• 24 buttons (4×6 matrix) + 0-8 encoders
• 32 buttons (4×8 matrix) + 0-8 encoders

1. Install Arduino IDE
2. Open arduino/macro-keyboard-firmware/macro-keyboard-firmware.ino
3. Configure hardware in config.h
4. Upload to Arduino Micro

macro-keyboard/
├── src/                    # Electron application source
│   ├── main.js            # Main process
│   ├── renderer/          # Renderer process (UI)
│   └── assets/            # Icons and resources
├── arduino/               # Arduino firmware
├── config/                # Configuration files
├── tests/                 # Test files
├── docs/                  # Documentation
└── .github/               # CI/CD workflows

npm start          # Start the application
npm run dev        # Start in development mode
npm run build      # Build for all platforms
npm run lint       # Run ESLint
npm run lint:fix   # Fix linting issues
npm test           # Run tests
npm run icons:generate  # Generate application icons
npm run icons:validate # Validate icon setup

Your guide to all available documentation - start here to find exactly what you need

• Getting Started Guide - Complete setup process for new users
• User Manual - Comprehensive feature reference
• Troubleshooting Guide - Solutions for common problems
• FAQ - Quick answers to frequent questions

• API Reference - Complete API documentation
• Plugin Development Tutorial - Step-by-step plugin creation
• Contributing Guide - How to contribute to the project
• Development Guide - Development environment setup

• Context-Aware Profiles - Automatic profile switching
• Security Architecture - Security model and configuration
• Plugin Architecture - Plugin system design
• Performance Monitoring - Performance tracking and optimization

• Arduino Setup Guide - Hardware setup and firmware installation

The project uses automated releases that trigger when code is pushed to the main branch:

1. CI Pipeline: All tests, linting, and builds must pass
2. Version Increment: Automatically increments version based on commit message:
   • [major] - Major version increment (1.0.0 → 2.0.0)
   • [minor] - Minor version increment (1.0.0 → 1.1.0)
   • Default - Patch version increment (1.0.0 → 1.0.1)
3. Release Creation: Creates GitHub release with platform-specific builds
4. Assets: Includes desktop apps for Windows, macOS, Linux and Arduino firmware

# Run all tests
npm test

# Run specific test files
npx jest tests/config.test.js

# Run with coverage
npm test -- --coverage

• Application appears in the status menu (top bar)
• Uses native macOS notifications
• Supports macOS-specific key combinations

• Application appears in the system tray
• Uses Windows notifications
• Supports Windows-specific key combinations

• Runs as a headless service (no GUI)
• Configuration via YAML file only
• Logs to file and console
• Supports standard Linux key combinations

1. Check that Arduino is properly connected
2. Verify the correct serial port in configuration
3. Ensure no other applications are using the serial port
4. Check Arduino IDE Serial Monitor works first

1. Verify wiring connections
2. Check for proper debouncing (firmware handles this)
3. Add diodes if experiencing "ghosting" (multiple buttons registering)

1. Check logs in logs/macro-keyboard.log
2. Verify configuration file syntax (YAML)
3. Restart application after configuration changes

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Built with Electron
• Serial communication via node-serialport
• Configuration management with js-yaml
• Logging with Winston