GOLEM keyboard project

Skip to main content

Keyboard matrix basics

The keyboard matrix is a clever trick to handle much more switches/keys than the number of GPIO pins on your controller. Matrices can be easy and straightforward (ortholinear boards) or much more complicated if you want to spare on more pins. In this guide we will design our first matrix for a 3x2 macropad.

Handling switch states

I presume you want to build a mechanical keyboard. In this case a keyboard is just a bunch of switches managed by a microcontroller. (Each key is a switch.)

You may be familiar with handling switch states with GPIO pins. You usually read the state of your switch (is it pressed or not?) by reading its voltage level through a dedicated pin of your controller.

You connect each switch to a controller pin. This approach works fine with a few switches, but the number of pins on the microcontroller is limited (eg. 18 on a Pro Micro or 26 on the bare ATmega32U4 chip). Assigning a pin to each switch we would run out of pins after 18-26 switches.

Because of this limitation, clever people came up with the idea of keyboard matrices: Instead of wasting one pin for a single switch, we arrange the keys in a grid and handle a full row or column of switches with the same pin.

The grid aka matrix

After arranging the keys in a grid, we program the controller to burst out a signal through one set of pins (to different rows of the grid), and another set of pins (columns) registers these signals (if the key is pressed). The controller takes care of this process. It keeps track of what's happening: what row fired the signal and what column registered it. And tries to guess what key has been pressed. The key at the crosspoint of the active row and column in the grid is pressed. Well, kind of.

How many pins will I need?

With matrices the number of pins needed will be the sum of your rows and columns (instead of using one pin for every single key).

This is a drastic reduction: In case of a Pro Micro (18 easily accessible pins) the maximal number of switches handled by the matrix would be 81. (9 rows + 9 colums consume all the 18 available pins, but can handle a grid of 9*9=81 keys!) (Pro tip: You can utilize two more pins on a Pro Micro and handle 100 keys.)

How many keys can your matrix handle?

What's the number of switches a Teensy, Elite C etc. (26 pins) can handle? With 13 rows and 13 columns (ideal case) we can handle 169 (13*13) switches. But this arrangement is pretty unrealistic. We usually have 4-6 rows and much more columns.

If we wire up 4 rows and 12 columns, we need 16 (4+12) pins to handle 48 (4*12) keys. (This could be a Planck.)

To build a Preionic (5 rows + 12 colums) you would need 17 (5+12) pins to handle the 60 (12*5) keys. (With a more elaborated matrix though you can reduce the number of pins significantly.) I cover this in the advanced keyboard matrix guide.

Diode array - one way only grid

In our grid electricity (the signal) may flow in multiple directions, making the controller's task to identify the pressed key pretty much impossible. Look at the picture below. [ambiguous keypress]

To make sure a keypress defines the row and column of a switch unambiguously, we have to make the grid one way only. That's what diodes do: they let electricity flow in one direction only.

That's why we have to solder a diode to each switch. There are all kinds of diodes, the most common being the 1N4148. This is dirt cheap, you can get 200 of this for 1$.

Diode direction

You can choose row to column or column to row diode direction, but you'll have to be consistent and set this parameter in your firmware (eg. QMK) accordingly.

Do you need a matrix at all?

Theoretically, you can wire up a macropad or numpad (anything with less than 18-26 keys) without a matrix, wiring the switches directly to the controller pins.

Further reading

To see this concept in action check my macropad build log, or a more advanced keyboard matrix and its implementation in my T.Storm build.