Prototype your custom keyboard matrix before you solder
Advanced
Or see every lesson.
- 261parts on the bench
- 31boards running now
- 1.00xreal time, on every board
Every custom keyboard, from a three-key macropad to a split ergonomic board, starts with the same circuit: a grid of switches, a diode on each one, and a controller that scans the grid hundreds of times a second. Get the matrix right and the rest is configuration. Get a diode backwards or a row on the wrong pin and you find out after an evening of soldering.
The numpad above is a complete matrix to try that on: twelve switches in four rows and three columns, a 1N4148 on every key, a rotary encoder, a strip of per-key RGB LEDs and a Pro Micro. Press the keys while it runs and the Serial Monitor shows what the keyboard would type, layer by layer.
Two things to know. Mokxi does not simulate the USB connection to a computer, so the Keyboard library prints each report as a [Keyboard] line instead of typing. And the firmware is a readable sketch, not QMK or KMK. It does the same core jobs, the scan, debounce, layers, the encoder and lighting, so you can test a layout and a wiring plan, and then carry them into the firmware you will actually flash.
Want the step-by-step version? The lesson "Rows, columns and the scan" walks through this with checkpoints.
Open the lessonWhy a keyboard is a matrix
One pin per key runs out fast: a 48-key ortholinear board would need 48 pins, and a Pro Micro has 18. A matrix puts each key where a row wire crosses a column wire, so the pins needed are rows plus columns. Four rows by three columns is 12 keys on 7 pins; four by twelve is 48 keys on 16 pins.
To read it, the firmware drives one row LOW, leaves the other rows floating, and reads every column with its pull-up on. A column that reads LOW has a pressed key in that row. Then it moves to the next row, and a full pass over the grid takes well under a millisecond.
Ghosting, and the diode on every key
Without diodes, hold three keys on the corners of a rectangle and the fourth corner reads as pressed too: current finds a way around through the three closed switches. That is ghosting. The course has a membrane keypad with no diodes where you can make it happen, and see that firmware cannot tell the ghost from a real press.
A diode in series with each key blocks the backwards path, so every key reads true however many are held. The direction matters. With rows driven LOW and columns pulled up, current flows from column to row, so the diode’s band, the cathode, faces the row. QMK calls this COL2ROW, and its documentation puts it the same way: the black mark facing the rows, between the switch and the row.
With diodes, the matrix has no rollover limit of its own. The USB report can have one: a standard boot keyboard report, which the Arduino Keyboard library sends, holds six keys at once.
Breadboarding the matrix
The template uses one half-size breadboard per row of keys, stacked like the rows of a keyboard. Each switch straddles its board’s channel, so its left legs join the strip above the channel to the strip below: that pair of strips is the key’s column, and a jumper carries it down to the next board. The switch’s right legs go through the diode onto the row strip, and short jumpers join a board’s row strips into one row. Columns read as straight lines down the stack and rows as a line along each board.
On a handwired build the same circuit is bare wire: a column wire down one leg of each switch, and the diodes’ legs bent along each row to form the row wire.
Layers, an encoder and per-key RGB
The keymap is a table per layer, laid out the way the keys are. MO(NAV) holds a layer while its key is down, TG toggles one, and a transparent key falls through to the layer below, with the highest active layer winning, which is how QMK resolves layers too. The sketch decides each key on the press and keeps it until the release, so letting go of a layer key first never leaves a key stuck down.
The encoder does something different on each layer: the mouse wheel on the base layer, arrows on NAV, undo and redo on EDIT, like an encoder map in QMK. The LEDs are one WS2812B per key in reading order, each in its layer’s color, flashing when its key is pressed.
{ // NAV, held on the bottom-left key
{KEY_HOME, KEY_UP_ARROW, KEY_PAGE_UP},
{KEY_LEFT_ARROW, KEY_ESC, KEY_RIGHT_ARROW},
{KEY_END, KEY_DOWN_ARROW, KEY_PAGE_DOWN},
{____, KEY_BACKSPACE, TG(EDIT)},
},Going on to QMK, KMK and split boards
When the layout and the wiring are settled here, write them into the firmware you will flash. QMK is written in C and runs on many microcontrollers, including the ATmega32U4 in a Pro Micro; KMK is written in CircuitPython for boards such as the RP2040. Both ask for the same facts you just tested: the row and column pins, the diode direction, the layers and what the encoder does.
A split keyboard is two matrices, one per half, with the halves talking over a serial or I2C link on a TRRS cable. QMK’s documentation warns to unplug USB before connecting or disconnecting that cable. Each half’s matrix is exactly the circuit on this page.
Questions
Do I need a diode on every key?
For a keyboard where several keys are held together, yes: without them, three keys on a rectangle make a ghost fourth. A tiny macropad where only one key is pressed at a time can skip them, but most builds include them.
Which way around do the diodes go?
For COL2ROW, which this template uses, the band (the cathode) faces the row, between the switch and the row wire. The firmware has to be set to match the way the diodes are fitted.
Is this QMK?
No. It is a readable Arduino sketch that does the same core jobs: scanning, debounce, layers, an encoder and lighting. Use it to prove the matrix and the layout, then configure QMK or KMK for the real build.
Does Mokxi type into my computer?
No. The USB connection is not simulated, so the Keyboard and Mouse libraries print each report to the Serial Monitor. Flash the sketch to a real Pro Micro and the same reports go over USB.
Keep going
Build this for real
Open the editor, change a value and watch the number move with it. Nothing to install, and no account needed.