Hackpad

Ever wanted a keyboard that does exactly what you need — and nothing else? In this guide, you’ll design a custom macropad from scratch: the circuit board, the case, and the firmware. Hack Club will ship you the parts and fund the manufacturing.

By the end, you’ll have:

• A custom PCB designed in KiCad
• A 3D-printable case designed in Fusion 360
• Working firmware (QMK, KMK, or ZMK)
• A real, physical macropad you built yourself

No prior electronics or CAD experience required. This guide walks you through everything step by step.

What you’ll get

When your design is approved, Hack Club ships you a kit of parts and grants to cover manufacturing:

Plus a $15 card grant for ordering your PCB from JLCPCB, and an $18 grant for a soldering iron if you need one. Your case gets 3D printed for free by Printing Legion.

Design constraints

Before you start, know the rules:

• MCU: Must be the Seeed XIAO RP2040 (through-hole, included in kit)
• PCB size: Max 100mm × 100mm, 2 layers only
• Case size: Max 200mm × 200mm × 100mm, fully 3D-printed (no laser-cut or CNC parts)
• Inputs: Max 16 (switches, encoders, etc.)
• Parts: Only kit parts — anything extra is on you
• Firmware: QMK, KMK, or ZMK

KiCad is the free, open-source tool you’ll use to design your circuit board.

1. Install KiCad

Download and install KiCad from kicad.org. Any recent version works.

2. Install the Hackpad component libraries

The XIAO RP2040 and SK6812 MINI-E LED aren’t in KiCad’s default libraries. Download the care package that includes them:

1. Go to github.com/hackclub/hackpad/releases/tag/v0.1-bugfix and download the zip.
2. Extract it somewhere permanent (like a kicad-libs folder in your Documents).

Install the symbol library (.kicad_sym):

1. In KiCad, open Preferences → Manage Symbol Libraries.
2. Click the + button, then browse to and select the .kicad_sym file from the care package.

Install the footprint library (.pretty folder):

1. Open Preferences → Manage Footprint Libraries.
2. Click the + button, then browse to the .pretty folder from the care package.

The schematic is your wiring diagram — it shows which pins connect to what. Open KiCad, create a new project, and open the Schematic Editor.

1. Place the microcontroller

Press A to open the symbol chooser. Search for MOUDLE-SEEEDUINO-XIAO (yes, the typo is in the library) and place it on the schematic.

This is the brain of your macropad. Every switch, LED, and encoder connects back to it.

2. Place your switches

Press A again, search for SW_Push, and place one for each key you want. For a simple 3-key pad, place 3 switches.

3. Wire them up

Press W to start drawing wires. Connect one side of each switch to a XIAO pin (pins like D0, D1, D2, etc.) and the other side to ground.

Press P and search for GND to place ground symbols. Attach one to the ground side of each switch and to the XIAO’s GND pin.

4. Matrix wiring (for 4+ keys)

If you have more keys than available pins, arrange your switches in a grid (rows × columns). Each intersection has a switch and a diode:

1. Add 1N4148 diodes — search for the D symbol, one per switch.
2. Wire each switch’s output through a diode.
3. Connect all switches in the same row together, and all switches in the same column together.
4. Connect each row wire and column wire to a XIAO pin.

For the diode footprint, use Diode_THT:D_DO-35_SOD27_P7.62mm_Horizontal — this matches the through-hole 1N4148 diodes in your kit.

A 4×4 matrix (16 keys) only needs 8 pins: 4 rows + 4 columns.

5. Assign footprints

Before moving to PCB layout, every schematic symbol needs a physical footprint:

1. Click Tools → Assign Footprints (or the footprint assignment button in the toolbar).
2. For each component, double-click it and select the correct footprint:
   • XIAO: use the footprint from the care package library
   • Switches: MX_Only_1.00u (from the care package)
   • Diodes: Diode_THT:D_DO-35_SOD27_P7.62mm_Horizontal

Your kit includes extras beyond switches. Here’s how to add them to your schematic.

Rotary encoder

A rotary encoder gives you a twist knob (plus a push button). It uses 3 pins on the XIAO: two for rotation (A and B) and one for the button press.

1. Add the symbol RotaryEncoder_Switch.
2. Wire pin A and pin B each to a XIAO data pin.
3. Wire the switch pin to another XIAO pin.
4. Wire the common pin to GND.
5. Assign the footprint RotaryEncoder_Alps_EC11E-Switch_Vertical_H20mm.

OLED display

The 0.91” OLED connects over I2C and uses just 2 data pins (plus power and ground). You can display text, images, or animations like Bongo Cat.

1. Add a generic 4-pin connector symbol.
2. Wire the 4 pins to match the OLED’s pin order: GND → VCC → SCL → SDA.
3. Connect VCC to the XIAO’s 3V3 pin, GND to GND, SCL to the XIAO’s SCL pin, and SDA to the XIAO’s SDA pin.

RGB LEDs

The SK6812 MINI-E LEDs are individually addressable — each one can be a different color. They chain together: the data-out of one LED feeds the data-in of the next.

1. Place one SK6812 MINI-E symbol per LED.
2. Wire the first LED’s DIN (data in) to a XIAO data pin.
3. Wire each LED’s DOUT (data out) to the next LED’s DIN.
4. Connect all VDD pins to 3V3 and all GND pins to GND.

Now you’ll turn the schematic into a physical circuit board.

1. Update the PCB from your schematic

In the PCB Editor, click Tools → Update PCB from Schematic. All your components will appear in a bundle — you’ll drag them into position.

2. Flip the XIAO to the back

Right-click the XIAO footprint and select Flip (or press F). The XIAO gets soldered to the bottom of the board so the USB-C port is accessible from the side.

3. Arrange your components

Drag components into their final positions. Key spacing for MX switches is 19.05mm center-to-center — this is the universal standard.

4. Route the traces

Press X to start routing traces (the copper connections between pads). Route on the F.Cu (front copper) layer. If two traces need to cross, switch one to B.Cu (back copper) using a via.

5. Draw the board outline

Switch to the Edge.Cuts layer and draw a rectangle (or any shape) around your components. This defines the physical edge of your board.

Use the Measure tool to verify your board fits within the 100mm × 100mm limit.

6. Clean up and check

1. Run Tools → Cleanup Tracks & Vias — click “Build changes” twice to apply.
2. Run Inspect → Design Rules Check to catch any errors (unconnected pins, traces too close together, etc.).
3. Open the 3D Viewer (View → 3D Viewer) to see a preview of your finished board.

7. Export Gerber files

Gerber files are what the PCB manufacturer (JLCPCB) uses to fabricate your board.

1. Go to File → Fabrication Outputs → Gerbers.
2. Use the default settings and click Plot.
3. Then click Generate Drill Files to create the drill file.
4. Zip all the generated files into a single gerbers.zip.

Your macropad needs a case to hold everything together. You’ll design a sandwich-style case: a bottom shell and a top plate with cutouts for the switches.

Tools

• Fusion 360 — free for personal use. Download from autodesk.com/products/fusion-360.
• ai03 Plate Generator — generates switch cutout patterns: kbplate.ai03.com.

1. Design the top plate

The top plate has square cutouts where the switches snap in.

1. Go to kbplate.ai03.com.
2. Paste your keyboard layout data. For a 3-key row: ["","",""]. For a 4×4 grid:

   ["","","",""],
   ["","","",""],
   ["","","",""],
   ["","","",""]
   

3. Download the DXF file.
4. In Fusion 360, create a new design and import the DXF as a sketch.
5. Extrude the plate to 3mm thickness.

2. Design the bottom case

1. Start a new sketch. Draw a rectangle matching your PCB dimensions plus 0.4mm tolerance on each side (so 0.8mm wider and taller total).
2. Draw a larger rectangle around it with 10mm margin — this creates the walls.
3. Extrude the base by 3mm.
4. Extrude the walls by 10mm (13mm total height from the bottom).
5. Add a USB-C cutout on the edge where the XIAO’s port sits.

3. Add mounting holes

You need holes to screw the plate to the bottom case. Place them in the corners and optionally along edges:

• Heatset insert holes (in the bottom case): 4.7mm diameter, 4mm deep — the M3×5×4mm heatset inserts press into these.
• Screw pass-through holes (in the plate): 3.4mm diameter — the M3×16mm screws go through these into the heatset inserts below.

4. Export your case files

Export each part as a separate .STEP file (File → Export → .STEP):

• Top.STEP — the switch plate
• Bottom.STEP — the bottom shell

Firmware is the code that tells your macropad what each key does. You have three options:

Option A: KMK (easiest — Python)

KMK runs on CircuitPython. You write a single main.py file and drop it onto the XIAO like a USB drive.

1. Install CircuitPython on your XIAO RP2040 (hold the BOOT button while plugging in USB, then drag the CircuitPython .uf2 file onto the drive that appears).
2. Install KMK by copying the kmk folder onto the CIRCUITPY drive.
3. Create main.py:

import board
from kmk.kmk_keyboard import KMKKeyboard
from kmk.keys import KC
from kmk.scanners import DiodeOrientation

keyboard = KMKKeyboard()

# Define your matrix pins (adjust to match your wiring)
keyboard.col_pins = (board.D0, board.D1, board.D2)
keyboard.row_pins = (board.D3,)
keyboard.diode_orientation = DiodeOrientation.COL2ROW

# Define what each key does
keyboard.keymap = [
    [KC.A, KC.B, KC.C],
]

if __name__ == "__main__":
    keyboard.go()

Option B: QMK (most features — C)

QMK is the industry standard for custom keyboards. It supports layers, tap-dance, OLED displays, RGB effects, and VIA (a GUI for remapping keys).

Follow the official porting guide: docs.qmk.fm/porting_your_keyboard_to_qmk

You’ll create a keyboard definition folder with:

• info.json — matrix layout, pin assignments, USB IDs
• keymap.c — your default keymap
• rules.mk — feature flags (OLED, encoder, RGB, etc.)

Option C: ZMK (wireless-focused)

ZMK is best for wireless keyboards, but works fine wired too. See zmk.dev/docs.

Encoder support

All three firmware options support rotary encoders. You’ll map the twist action to volume up/down, scrolling, or anything else:

• QMK: ENCODER_MAP_ENABLE in rules.mk
• KMK: from kmk.modules.encoder import EncoderHandler
• ZMK: &sensors in your .keymap file

OLED support

If you’re using the OLED display, you can show text, battery status, current layer, or animations. QMK’s OLED driver is the most mature — it supports custom graphics and animations like the famous Bongo Cat.

Your project needs to be in a GitHub repository with this folder structure:

your-macropad/
├── README.md
├── CAD/
│   └── assembled-model.STEP
├── PCB/
│   ├── your-project.kicad_pro
│   ├── your-project.kicad_sch
│   └── your-project.kicad_pcb
├── Firmware/
│   └── main.py (or QMK source folder)
└── production/
    ├── gerbers.zip
    ├── Top.STEP
    ├── Bottom.STEP
    └── firmware.uf2 (or main.py)

Your README should include

• A screenshot or render of your macropad design
• A screenshot of your schematic
• A screenshot of your PCB layout
• A screenshot of your case in 3D
• A bill of materials listing every component

Pre-submission checklist

• PCB is 100mm × 100mm or smaller (2-layer)
• Case fits within 200mm × 200mm × 100mm
• Case is fully 3D-printable (no acrylic, laser-cut, or CNC parts)
• Only using parts from the kit (or buying extras yourself)
• Gerber files are exported and zipped
• Case parts exported as .STEP files
• Firmware compiles and is included in the repo
• Heatset insert holes are 4.7mm diameter
• Screw holes have clearance (3.4mm for pass-through)
• 0.2mm tolerance on mating surfaces
• USB-C port has a cutout in the case
• README has screenshots and BOM

Once everything is in your GitHub repo:

1. Post your project in #hackpad-ships on the Hack Club Slack.
2. Fill out the submission form at forms.hackclub.com/hackpad-submission.

A reviewer will check your design. If approved, your kit ships and you’ll get card grants for the PCB and soldering iron. Your case goes to Printing Legion for 3D printing.

KiCad resources

• KiCad Getting Started guide
• Hackpad KiCad care package

Fusion 360 resources

• ai03 Plate Generator
• Fusion 360 for beginners (YouTube)

Firmware resources

• QMK Porting Guide
• KMK Documentation
• ZMK Documentation

Key measurements for reference

Getting help

Stuck? Ask in #hackpad on the Hack Club Slack. Post your schematic or PCB screenshot and describe what’s going wrong — the community is friendly and fast.