By dave | August 17, 2019

IoAbstraction: Using matrix keyboards and keypads

Matrix keyboards are arranged such that the keys are in a matrix of rows and columns. This means that instead of needing a spare input for each key, one INPUT for each column and one OUTPUT for each row is all that’s needed.

In order to use the keyboard, we create a class of type MatrixKeyboardManager and configure it with an IoAbstractionRef, a KeyboardLayout that describes the keyboard attached (there are some standard ones already defined) and a listener that will be informed of changes. We also define a class extending from KeyboardListener to get the key events.

Not only does this work connected to Arduino pins, but you can connect your keyboard to any supported device such as an I2C PCF8574 or MCP23017. However, at the moment it does not support interrupt based acquisition so it will poll over I2C, not a problem for most purposes.

Wiring a keyboard to an Arduino / embedded device

In order wire up a matrix keyboard, each row gets configured as an INPUT and is connected to an input capable pin, this pin should be pulled up with a 1K resistor too. Then, each column gets configured as OUTPUT and is wired to an output capable pin. Below is an example circuit, it shows how a matrix keyboard is both wired internally and also where the external resistors are needed. The library will actually set all inputs to INPUT_PULLUP, so for very short wire runs you may get away without the PULL-UP resistors shown in the circuit. You’ll need to test this yourself.

Matrix keyboard circuit diagram

Circuit showing 3 column by 4 row matrix keyboard

How matrix keyboard decoding works with this driver

Keyboard manager registers a task that is frequently run with TaskManager, this task switches between each column, checking the rows in that column. If a key press is detected for the first time, this starts the debounce logic, which determines if a real key press has just occurred. Once that has been determined the keyPress event will be repeated until the key is released. At which point a final released event will be sent to the listener.

Creating a KeyboardListener

You need to extend from a class of type KeyboardListener in order to get key press events from the keyboard. An example of how to do this is shown below:

class MyKeyboardListener : public KeyboardListener {
    void onKeyPressed(char key, bool held) {
        // do something when pressed

    void onKeyReleased(char key) {
        // do something when released    
} myListener;

Initialise the keyboard

First you need to create a KeyboardLayout, to do this the easiest way is to use one the pre-canned ones for 3x4 and 4x4 displays.

// for a 3x4 numeric keypad
// or for a 4x4 hex style keypad

Alternatively you can create one from scratch by providing a KeyboardLayout

const char pgmLayout[] PROGMEM = "charsColByRow";
KeyboardLayout layout(rows, cols, const char* pgmLayout)

Before calling initialise on the MatrixKeyboardManager it is your responsibility to set the pins upon which the keyboard is attached.

keyboardLayout.setColPin(col, pin);
keyboardLayout.setRowPin(row, pin);

Lastly, initialise the keyboard passing an IoAbstractionRef indicating if pins or IoExpander are to be used:

// when you connect the device directly to arduino pins.
IoAbstractionRef arduinoIo = ioUsingArduino();

keyboard.initialise(arduinoIo, &keyLayout, &myListener);

Lastly as the keyboard manager uses task manager, we must call it’s run loop frequently like below.

void loop() {
    // as this indirectly uses taskmanager, we must include this in loop.

And that’s it, you should now get called back when keys are pressed. There’s also a packaged example that you can take a look at.

Go back to the IoAbstraction page

Other pages within this category

comments powered by Disqus

We use cookies to analyse traffic and to personalise content. We also embed Twitter, Youtube and Disqus content on some pages, these companies have their own privacy policies.

Please see our privacy policy should you need more information or wish to adjust your settings.