https://github.com/j-a-c-c-o/j-pad
A handwired 4x4 macropad with rotary encoder built on Raspberry Pi Pico.
https://github.com/j-a-c-c-o/j-pad
4x4-keypad cherry-mx diy diy-keyboard handwired handwired-keyboard macropad mechanical-keyboard raspberry-pi-pico rotary-encoder rp2040
Last synced: about 2 months ago
JSON representation
A handwired 4x4 macropad with rotary encoder built on Raspberry Pi Pico.
- Host: GitHub
- URL: https://github.com/j-a-c-c-o/j-pad
- Owner: J-a-c-c-o
- License: gpl-3.0
- Created: 2025-07-08T22:30:39.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-04-04T23:20:45.000Z (about 2 months ago)
- Last Synced: 2026-04-05T00:42:28.937Z (about 2 months ago)
- Topics: 4x4-keypad, cherry-mx, diy, diy-keyboard, handwired, handwired-keyboard, macropad, mechanical-keyboard, raspberry-pi-pico, rotary-encoder, rp2040
- Language: C
- Homepage:
- Size: 22.7 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# J-Pad
A custom 4x4 handwired macropad with rotary encoder and dynamic runtime macro updates.
## Overview
This project is a handwired 4x4 macropad built around a Raspberry Pi Pico and QMK firmware. The firmware maps each physical key to a macro slot, and the `host/` scripts can update macros at runtime over raw HID.
The encoder has layer-aware behavior, and the firmware supports 16 logical layers with 16 macros per layer.
## Requirements
### Hardware
- 1x Raspberry Pi Pico
- 16x Cherry MX compatible switches (or 15 switches plus encoder push if available)
- 1x Rotary encoder (EC11)
- 16x 1N4148 diodes
- 4x 3M 10mm DIN 965 screws (or similar)
- Hookup wire for handwiring
- Keycaps for 16 keys
- MX encoder adapter: [Thingiverse Thing:3770166](https://www.thingiverse.com/thing:3770166)
### Software
- [QMK Firmware](https://qmk.fm/) for firmware compilation/customization
- Python 3 for the UI scripts
- `hid` Python package for raw HID communication
- Computer with USB port
### Tools (for assembly)
- Soldering iron and solder
- Wire strippers
- 3D printer or printing service
- Basic hand tools
## Quick Start
### Flash Firmware
1. Hold the top-left key while plugging in USB.
2. Copy `jacco_4x4_macropad_default.uf2` to the `RPI-RP2` drive.
3. The board will reboot with the loaded firmware.
### Default Behavior
The firmware maps the 16 keys to macro indices `0..15` on every layer. The actual key behavior is defined by macros, so the board is designed to be configured at runtime via the host scripts in `host/`.
**Encoder**: Layer-dependent actions, configured in firmware.
## Host Tool / Dynamic Macro Support
This repo includes a simple Python host-side tool for sending macro updates to the board over raw HID.
- `host/main.py` - sends fragmented raw HID reports to update macro definitions on the device.
- `host/keycode_converter.py` - converts human-readable macro expressions like `LCTL(KC_C)` and `SWITCH_LAYER_5` into QMK keycodes.
- `host/qmk_keycodes.py` - contains the QMK keycode constants used by the converter.
### How it works
The firmware expects raw HID packets to update:
- encoder actions per layer
- macro contents per layer and slot
- repeating macro intervals
The sample script in `host/main.py` demonstrates:
- setting layer 0 key 4 to switch to layer 5
- setting layer 5 key 5 to send `Ctrl+C` and erpeating every 100ms until pressed again
- setting layer 5 rotary encoder actions to send `a` and `b`
- setting layer 5 key 4 to return to layer 0
### Run the host script
Install dependencies:
```bash
python3 -m pip install hid
```
Then run:
```bash
python3 host/main.py
```
Edit `host/main.py` to send the macro updates you want.
## Project Files
- `qmk-config/` - QMK keyboard definition and keymap sources
- `qmk-config/jacco_4x4_macropad/keyboard.json` declares keyboard features
- `qmk-config/jacco_4x4_macropad/keymaps/default/keymap.c` implements the dynamic macro engine and encoder behavior
- `hardware/` - Handwiring guide, BOM, and assembly instructions
- `case/` - 3D printable case files
- `case.3mf` - main case design
- `case.f3d` - Fusion 360 design file
- `stl/` - STL files for printing
- `images/` - Assembly and wiring reference photos
- `host/` - Python scripts for sending macro updates to the device
## Building Your Own
### 1. Print Required Parts
- Print `case.3mf`
- Print the MX encoder adapter from [Thingiverse Thing:3770166](https://www.thingiverse.com/thing:3770166)
- Recommended settings: 0.2mm layer height, 20% infill, PLA or PETG
### 2. Gather Components
See `hardware/README.md` for the full Bill of Materials.
### 3. Handwire Assembly
Follow `hardware/assembly.md` to:
- wire the switch matrix
- connect the Raspberry Pi Pico
- wire the encoder to GP26/GPIO28
- install the case and finish assembly
### 4. Flash Firmware
Use the Quick Start guide above or compile from QMK after copying the keyboard folder.
## Customizing
Copy `qmk-config/jacco_4x4_macropad/` into your local QMK firmware tree under `keyboards/`.
Example:
```bash
cp -r qmk-config/jacco_4x4_macropad ~/qmk_firmware/keyboards/
```
Then build and flash:
```bash
qmk compile -kb jacco_4x4_macropad -km default
qmk flash -kb jacco_4x4_macropad -km default
```
## Notes
- The current firmware stores macro definitions in RAM only. Custom macros are lost after reboot unless resent by the host tool.
- Layer switching is handled by macro keycodes such as `SWITCH_LAYER_0..SWITCH_LAYER_15`.
## License
Open source hardware and software. See individual files for specific licenses.