⚡ Action Pad

Your Physical Shortcut to Digital Productivity

Transform a simple Arduino keypad into a powerful productivity tool that executes commands, hotkeys, and macros at the press of a button.

Features • Quick Start • Demo • Configuration • Contributing

---

👁️ Demo

A button that executes the command google-chrome & code to open the browser and VS Code, improving efficiency.

---

✨ Features

✅ Custom Button Actions Assign commands, hotkeys, or macros to each button ✅ Multi-Layer Support Expand functionality without adding hardware ✅ Short & Long Press Double your actions with press duration detection ✅ Command Execution Run any terminal command instantly

✅ Hotkey Automation Trigger complex key combinations effortlessly ✅ Macro Chaining Combine multiple actions into workflows ✅ Plug & Play Auto-detects Arduino devices ✅ JSON Configuration Easy-to-edit, human-readable config

---

🤔 Why Action Pad?

As developers, designers, and power users, we constantly switch between applications, execute repetitive commands, and trigger the same hotkey combinations dozens of times a day. Action Pad was born from frustration with this inefficiency.

The Problem

• ⏱️ Repetitive keyboard shortcuts slow you down
• 🧠 Remembering complex key combinations is mentally taxing
• 💻 Context switching breaks your flow
• 🔄 Running the same terminal commands over and over is tedious

The Solution

A physical, programmable button pad that puts your most-used actions at your fingertips. One button press can:

• Launch your entire development environment
• Copy text and send a notification
• Switch between different workflow "modes"
• Execute complex multi-step macros

It's like having a custom control panel for your digital life. 🎮

---

🚀 Quick Start

Prerequisites

• Arduino board (Uno, Nano, Mega, etc.)
• 4x4 matrix keypad (or any compatible keypad)
• Python 3.6+
• Arduino IDE

Installation

1. Clone the repository

git clone https://github.com/HimC29/action-pad.git
cd action-pad

2. Install Python dependencies

pip install pyserial pyautogui

3. Wire your keypad to Arduino
Connect keypad pins to Arduino digital pins (see Wiring Guide)

4. Upload Arduino code

• Open /code/arduino/main/main.ino in Arduino IDE
• Select your board and port
• Click Upload ⬆️

5. Configure your buttons

# Edit config.json to customize button actions
nano config.json  # or use your favorite editor

6. Launch Action Pad

# Linux/macOS
./launch.sh

# Windows
launch.bat

7. Select your Arduino from the menu and start pressing buttons! 🎉

---

🔌 Wiring Guide

Matrix keypads typically have 7-8 pins that connect to Arduino digital pins.

Connection Steps

1. Connect all keypad pins to Arduino digital pins
2. Check your keypad's datasheet for the correct pin order (or experiment!)
3. Update the Arduino code if your mapping differs from the example

Example Pin Mapping (4x4 Keypad)

Keypad Pin  →  Arduino Pin
─────────────────────────
Pin 1       →  D2
Pin 2       →  D3
Pin 3       →  D4
Pin 4       →  D5
Pin 5       →  D6
Pin 6       →  D7
Pin 7       →  D8
Pin 8       →  D9

💡 Tip: Different keypads may have different pin configurations. If buttons don't respond correctly, try adjusting the pin assignments in /code/arduino/main/main.ino.

---

⚙️ Configuration

Action Pad uses a simple JSON file to define button behaviors. Edit config.json to customize your setup.

Configuration Structure

{
    "active_layer": "default",
    "layers": {
        "default": {
            "btn1": { /* button config */ }
        }
    }
}

• active_layer - The layer that loads on startup
• layers - Contains all your layer definitions

Button Action Types

🔹 Hotkey

Trigger keyboard shortcuts

"btn1": {
    "type": "hotkey",
    "keys": ["ctrl", "c"],
    "long": {
        "type": "hotkey",
        "keys": ["ctrl", "v"]
    }
}

🔹 Command

Execute terminal commands

"btn2": {
    "type": "command",
    "command": "google-chrome"
}

🔹 Macro

Chain multiple actions together

"btn3": {
    "type": "macro",
    "actions": [
        {
            "type": "hotkey",
            "keys": ["ctrl", "c"]
        },
        {
            "type": "command",
            "command": "notify-send 'Copied!'"
        }
    ]
}

🔹 Layer Switch

Change to a different button layout

"btn16": {
    "type": "layer",
    "target": "code-mode"
}

Complete Example

Click to expand full config.json example

{
    "active_layer": "default",
    "layers": {
        "default": {
            "btn1": {
                "type": "macro",
                "actions": [
                    {
                        "type": "hotkey",
                        "keys": ["ctrl", "c"]
                    },
                    {
                        "type": "command",
                        "command": "notify-send --app-name='System' 'Copied text!'"
                    }
                ],
                "long": {
                    "type": "macro",
                    "actions": [
                        {
                            "type": "hotkey",
                            "keys": ["ctrl", "v"]
                        },
                        {
                            "type": "command",
                            "command": "notify-send --app-name='System' 'Pasted text!'"
                        }
                    ]
                }
            },
            "btn2": {
                "type": "command",
                "command": "google-chrome",
                "long": {
                    "type": "command",
                    "command": "firefox"
                }
            },
            "btn16": {
                "type": "layer",
                "target": "code-mode"
            }
        },
        "code-mode": {
            "btn1": {
                "type": "command",
                "command": "google-chrome & code"
            },
            "btn16": {
                "type": "layer",
                "target": "default"
            }
        }
    }
}

---

🤝 Contributing

Contributions make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated!

How to Contribute

1. Fork the Project
2. Create your Feature Branch

   git checkout -b feature/AmazingFeature

3. Commit your Changes

   git commit -m 'Add some AmazingFeature'

4. Push to the Branch

   git push origin feature/AmazingFeature

5. Open a Pull Request

Contribution Ideas

• 🎨 Add new action types (mouse movements, delays, conditionals)
• 🖥️ Build a GUI configuration tool
• 📚 Improve documentation and examples
• 🐛 Report bugs and suggest features via Issues

---

🌟 Contributors

Thanks to everyone who has contributed to Action Pad!

Want to see your name here? Check out the Contributing section!

---

🗺️ Roadmap

• Additional action types (mouse control, delays, conditionals)
• Web-based GUI configuration tool
• Support for ESP32 and Raspberry Pi Pico
• Profile switching for different workflows
• Cloud sync for configurations
• Mobile companion app

Have an idea? Open an issue and let's discuss!

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

TL;DR: You can use, modify, and distribute this project freely. Just keep the original license notice.

---

🙏 Acknowledgments

Built with amazing open-source tools:

• Arduino - The hardware platform that makes this possible
• pyserial - Python serial communication library
• pyautogui - GUI automation for Python

---

⭐ Star this repo if you find it useful!

Made with ❤️ by HimC29

Report Bug • Request Feature • Discussions