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

Software

• QMK Firmware 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:

python3 -m pip install hid

Then run:

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
• 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:

cp -r qmk-config/jacco_4x4_macropad ~/qmk_firmware/keyboards/

Then build and flash:

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.