How to Build a Custom Mechanical Keyboard from Scratch: Hand-Wiring and QMK Firmware

Introduction

Building a custom mechanical keyboard is one of the most satisfying electronics projects you can undertake. You choose every component — the switch type, layout, case material, keycaps, and even program your own firmware. The result is a keyboard perfectly tailored to your hands, workflow, and aesthetic. This guide covers hand-wiring a keyboard matrix (no PCB required), soldering switches, connecting a microcontroller (Pro Micro or Raspberry Pi Pico), and flashing QMK/VIA firmware. Whether you want a compact 40%, a split ergonomic board, or a full-size custom, the principles are the same.

What You Need

• Mechanical switches (Cherry MX, Gateron, Kailh — your choice, 40-110 depending on layout)
• Keycaps matching your switch stem and layout
• Microcontroller: Pro Micro (ATmega32U4), Elite-C, or Raspberry Pi Pico (RP2040)
• Diodes: 1N4148 through-hole (one per switch)
• Wire: 22-24 AWG solid core for rows/columns, 28-30 AWG for jumpers
• Case/plate: 3D printed, laser-cut acrylic, or purchased aluminum plate
• Soldering iron, solder, flush cutters, tweezers
• USB cable

Step 1: Choose Your Layout

Popular layouts include:

• 40% (44-48 keys): Minimal, layer-heavy, portable
• 60% (61 keys): No numpad or F-row — most popular custom size
• 75% (82-84 keys): Compact with F-row and arrows
• Split (Lily58, Corne, Ergodox): Ergonomic, reduces strain
• Numpad/macropad: Simple starter project (17-22 switches)

Use Keyboard Layout Editor (keyboard-layout-editor.com) to design your layout, then export to Plate & Case Builder for files.

Step 2: Understand the Keyboard Matrix

A keyboard matrix organizes switches into a grid of rows and columns. Instead of using one GPIO pin per switch (expensive), a matrix uses R rows + C columns = R×C switches with R+C pins.

For a 60% keyboard: 5 rows × 14 columns = 70 possible positions using only 19 GPIO pins.

How it works: The microcontroller drives one row HIGH at a time and reads all columns. If a switch is pressed, its column reads HIGH, and the controller knows which key is pressed by the active row and active column.

Step 3: Install Switches in the Plate

1. Place switches into the plate/case in your desired layout
2. Ensure they click in securely (plate-mount switches have top and bottom clips)
3. Check alignment — all switch stems should face the same direction
4. Verify stabilizers are installed on larger keys (spacebar, shift, enter) if using a plate that supports them

Step 4: Solder Diodes

Diodes prevent ghosting (phantom keypresses) by ensuring current flows in one direction only.

1. Bend one leg of each 1N4148 diode into a loop or U-shape
2. The banded/cathode end (black stripe) connects to the switch pin
3. Solder the diode leg to one switch pin (typically the pin farthest from you)
4. The other diode leg points toward the next switch in the row
5. Repeat for every switch — all diodes should point the same direction

Step 5: Wire the Rows

1. Cut strips of wire to connect all diodes in each row
2. Solder the free diode legs together in a chain — this is your row wire
3. Leave one end with extra wire to connect to the microcontroller later
4. Insulate with heat shrink or electrical tape where wires cross columns

Step 6: Wire the Columns

1. Cut wires to connect the second pin of each switch in a column
2. Solder column wires vertically through the switch grid
3. Each column wire connects to every switch in that vertical column
4. Label each row and column wire with tape and a marker

Step 7: Connect to the Microcontroller

Pro Micro Pinout (common connections)

• Rows: D0, D1, D2, D3, D4 (Arduino pins)
• Columns: F4, F5, F6, F7, B1, B3, B2, B6, B5, B4, E6, D7, C6, D4

Connection Steps

1. Strip and tin the row/column wires and microcontroller pins
2. Solder each row wire to a separate GPIO pin on the Pro Micro
3. Solder each column wire to separate GPIO pins
4. Connect VCC and GND from Pro Micro to a convenient location (for optional LEDs)
5. Double-check every connection with a multimeter (continuity test)

Step 8: Flash QMK Firmware

Set Up QMK Environment

1. Install QMK MSYS (Windows) or qmk_cli (Mac/Linux)
2. Run: qmk setup
3. Fork the qmk_firmware repository on GitHub

Create Your Keyboard Definition

1. Navigate to keyboards/ directory
2. Create a new folder: mkdir keyboards/handwired/yourkbname
3. Create config.h with matrix dimensions:

#define MATRIX_ROWS 5 #define MATRIX_COLS 14 #define MATRIX_ROW_PINS { D0, D1, D2, D3, D4 } #define MATRIX_COL_PINS { F4, F5, F6, F7, B1, B3, B2, B6, B5, B4, E6, D7, C6, D4 }

Define Your Keymap

1. Create keymaps/default/keymap.c
2. Use QMK keycodes to define each layer:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [0] = LAYOUT( KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_ENT, KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_FN, KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, KC_RGUI, KC_RCTL ), };

Compile and Flash

qmk compile -kb handwired/yourkbname -km default

1. Put Pro Micro in bootloader mode (short RST to GND twice quickly)
2. Flash: qmk flash -kb handwired/yourkbname -km default

Step 9: Test and Debug

1. Open a text editor
2. Press every key — each should output the correct character
3. Use QMK's test matrix mode if keys are wrong — it shows raw matrix positions
4. Fix any wiring errors (swapped rows/columns are the most common issue)

Step 10: Enable VIA (Optional but Recommended)

VIA lets you remap keys in real-time through a web app without recompiling firmware.

1. Add VIA_ENABLE = yes to rules.mk
2. Generate a unique vendor/product ID in config.h
3. Compile and flash
4. Go to usevia.app — your keyboard appears automatically
5. Click any key in the layout and assign a new function

Pro Tips

• Start with a numpad or macropad (17-22 keys) before tackling a full keyboard
• Use a multimeter to test every diode direction before soldering
• Take photos of your wiring before closing the case — future you will thank present you
• Use color-coded wire: one color for rows, another for columns, another for controller connections
• Add reset button pins accessible from outside the case (RST-GND short)
• Lube your switches before soldering for smoother feel
• Use QMK's keymap layers — a 40% keyboard becomes fully functional with 3-4 layers

Conclusion

A hand-wired custom keyboard is a project that combines electronics, programming, and ergonomics into a tool you use every day. The QMK firmware ecosystem gives you unlimited customization — from custom keymaps and macros to RGB lighting and rotary encoders. Start small with a numpad, learn the matrix and wiring fundamentals, then scale up to your dream layout. The keyboard you build will be uniquely yours in every way.