Debugging your keyboard

What do you do when you’re in the process of building your keyboard, testing the matrix and realise that some keys do not work? Here’s a guide with some pointers on where and how to debug issues that you might have.


In general where to look depends on a couple things:

  • What keyboard you have
  • What keys aren’t working

This guide will be broken down into these sections

Tools needed

You don’t really need any tools other than what you have already for the keyboard construction. A multimeter is helpful for checking continuity and removing some of the guesswork that you might have.

Keyboard matrices: a background

Keyboards work by polling a matrix of keys. Each key is connected to a single row and a single column and usually has a diode in the path to prevent ghosting (i.e. when multiple keys are registered after a single keypress happens). Understanding this layout and structure helps to identify the root cause of any issues.

Litl matrix

The Litl uses a duplex column layout where two physical columns on the board are connected to a single column pin on the controller. So while the board looks like it is a 12 column by 4 row layout, it is actually a 6 column by 8 row layout. This is a design choice to minimise the pins required on the microcontroller.

Litl matrix layout
Litl Controller pinout

Lagom matrix

The Lagom uses 2 demultiplexers or demuxes to power the columns and has the rows directly connected to the controller. This again is a design choice aimed at minimising the pins required for the microcontroller. There are 4 microcontroller pins (mux0 to mux3) that control the output of 16 columns (col0 to col15), and 5 row pins to make a 16 x 5 matrix.

Lagom matrix layout
Lagom demultiplexer pinout (lower is cols 0 to 7, upper is cols 8 to 16)
Lagom Controller pinout

Single key not working

A single key not working is likely indicative of an issue on the soldering of that key or the diode linking that key to the controller. This will more commonly happen once you’ve soldered switches on and have missed a connection and/or have a cold solder joint. If you’re testing without the switches, then checking the diode relating to that key and reflowing the solder is usually a good place to start.

Things to check: connection on the switch, connection on the related diode

How to solve: reflow solder on switch and diode

Whole row not working / Every other key on a row not working

A whole row not working can happen when the row is not connected to the microcontroller properly. This will manifest itself in different ways on different boards. On Litl every other key on the row will likely not work due to the matrix layout and on Lagom every key on the row will likely not work if this is the issue. The solution is checking the connection to the microcontroller and ensuring that the solder joint there is complete.

Things to check: connection from the row to the controller

How to solve: reflow solder on the controller pin for the specific row at fault

Whole column not working / Side by side columns not working

A whole column not working can happen when the connection from the column pin on the microcontroller to the column is not complete. This will also manifest itself differently on different boards. On Litl you will likely have 2 side by side columns not working if this is the case (as the layout has 2 physical columns connected to a single controller pin). On Lagom you may have a single column not working (in which case the issue is between the column and the demux) or you you may have half of the board not working (in which case you should jump to the next section).

For Litl you want to identify the connection pin from the non working columns to the controller and try reflowing that. For Lagom you want to identify the connection from the controller to the demux and reflow the pin there. The upper demux is for cols 8 to 15 and the lower demux is for cols 0 to 7.

Things to check: connection from the column to the controller and connection from the column to the demux

How to solve: reflow solder on the specific pin on the controller or demux

Half of the board not working

Half of the board not working is something that will likely only happen on the Lagom board. If you get this on the Litl board then it’s likely a result of multiple columns having issues. Half of the board not working on the Lagom can be indicative of one of the demuxes not working, or a connection to one of the demuxes from the controller being incomplete.

A good way to identify where the issue might lie here on the Lagom is to carefully swap the IC chips (and make sure that the power is off when you do this). If, after swapping, the same half of the board continues not to work the issue is likely with the soldering and connection to the controller. If the other half of the board then stops working the probably is with the IC itself (and you might need a replacement).

Things to check: swapping the demux ICs to see if that changes the non working half of the board

How to solve: reflow solder on controller or demux pin or replace demux IC

Multiple keys triggering

Multiple keys triggering when a single one is pressed is something that can happen when there is a short between two keys or a single key and ground. In the case that this happens, the issue is most likely related to one of the keys that triggers together. If it is a whole column or row that triggers together then you may want to use a multimeter and identify if there is any unusual continuity to ground.

Things to check: connection on the keys that trigger together, looking for shorts

How to solve: identify the source of the issue and usually reflow solder


Hopefully this provides a little help in debugging issues that you may see when testing your keyboard matrix, but if you’ve tried all of this and are still a little stuck please reach out to hej at sthlmkb dot com and we help!

👋 Happy building

Shopping Basket
Select your currency