This DIY Gadget Automatically Deciphers Keyboard Matrices

Virtually every keyboard on the planet relies on a matrix circuit, which is essentially a grid of rows and columns with the keys at the intersections. Take the square root of the number of keys, multiply by two, and round up to the nearest whole number. That is the minimum number of pins required, which is less than the total number of keys, assuming you have at least seven keys.

But reverse engineering the pinout of a keyboard matrix can be really laborious, which is why thanishurs31 developed this gadget that does the job automatically.

If you want to use a keyboard matrix with an unknown pinout, the normal strategy is to test continuity between row-column pin pairs while pressing keys. But that takes ages to accomplish. This gadget does all the hard work and saves an immense amount of time.

It works using a Raspberry Pi Pico, plus an appropriate adapter to connect the keyboard matrix’s pins to the Pico’s GPIO pins. That adapter will depend on the kind of cable the keyboard uses (the cable straight from the matrix, not the USB or PS/2 cable). It is possible to cobble something together on a breadboard, but a custom PCB will go a long way here.

All of the magic happens thanks to the CircuitPython firmware that thanishurs31 programmed. It starts with Phase 1, which is a fully automatic baseline scan to determine which pins are power, which are rows, and which are columns. It’ll then pop out a JSON file with that pinout.

But it is Phase 2 that is particularly exciting, because it can identify each key’s position on the matrix. In that phase, you simply hold down a key and the firmware will scan through the matrix until it finds that key’s row-column position. Repeat for all of the keys and when it is done, it will give you a fully populated key map.

It even handles N-key rollover identification and ghost key filtering, depending on if your particular key matrix does or does not have diodes.

From there, you can easily use the same Raspberry Pi Pico, or another MDB, to scan the keyboard matrix and output USB HID events, just like any other USB keyboard does.