GOLEM keyboard project
Guide

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.

Connecting each switch to a separate controller pin 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). With 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 (different rows of the grid), and another set of pins (columns) registers these signals (if the key is pressed).

The controller 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 pushed down. Well, kind of.

How many pins will I need?

With the matrix approach the number of required pins 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 bare Atmega32U4 chip (26 pins) can theoretically 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 only 4-6 rows and much more columns in a keyboard.

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.) No problem.

To build a Preonic (5 rows + 12 colums) you would need 17 (5+12) pins to handle the 60 (12*5) keys. With larger keyboards or with extra features like underglow, backlighting, rotary encoder, display etc. you can easily run out of pins.

In this case you can reduce the number of pins further with a more elaborated matrix. I cover this in the advanced keyboard matrix and duplex matrix guides.

Diode array - one way only grid

The signal can flow in multiple directions in our grid, 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.

There are all kinds of diodes available, the most common being the 1N4148. This is dirt cheap, you can get 200 of this for 1$.

Diode direction

You can choose any direction: row to column or column to row, as long as you are consistent. This parameter can be set in the firmware (e.g. QMK).

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.