ESP8266: Interfacing with a 4×4 Matrix Keypad

The objective of this post is to explain how to use a 4×4 matrix keypad with the ESP8266. For simplicity, we will assume the use of the ESP8266 integrated in a NodeMCU board.

Introduction

The objective of this post is to explain how to use a 4×4 matrix keypad with the ESP8266. For simplicity, we will assume the use of the ESP8266 integrated in a NodeMCU board.

For this tutorial, I’ve used a membrane keypad similar to the one shown in figure 1. This is a very simple keypad that can be bought at eBay for less than 1 euro.

Figure 1 – Membrane 4×4 matrix keypad. Adapted from [1]

We will be using the Arduino Keypad library that can be found here. If you prefer, you can also find it at GitHub here. The easiest way to install the library is via Arduino IDE library manager, as shown bellow in figure 2.

Figure 2 – Installation of the library via library manager.

Although there is no explicit mention for the support in the ESP8266, it works fine with it as we will see bellow.

 

The hardware

As we can see from figure 1, a 4×4 matrix only has 8 interface pins, which correspond to the columns and rows of the matrix. Explaining how we can use only 8 pins to check which of the 16 keys is pressed is outside the scope of this post, but I strongly recommend you to read this article which explains the working principle.

Although the library we are going to use hides the implementation details from us, if you want to check how it works the mentioned article provides a useful help.

So, to interface with the matrix keypad, we simply need to connect both its columns and rows to the pins of the NodeMCU. This is shown in figure 3.

Figure 3 – Connection diagram for the NodeMCU and keypad matrix.

Note that we don’t need to connect any power supply to the keypad because half of the digital pins will work as outputs and the other half as inputs, as can be seen in this private method of the library, which is responsible for scanning for pressed keys. Again, this is just an implementation detail that we don’t need to worry about when using the library.

 

The code

This code is very similar to the one in the “CustomKeypad” example of the library. The examples are very simple and easy to use, so I encourage you to check them.

We will start by including the previously installed library, so we can access all the functionality needed to interact with the keypad.

#include <Keypad.h>

Next, we will declare some global variables. Since we are using a 4×4 keypad, we will declare a variable to store the number of lines and another for the number of columns. Note that this library works with keypads with sizes different from 4×4.

const byte n_rows = 4;
const byte n_cols = 4;

Then, we will declare a char matrix with the same size of our keyboard (4 lines and 4 columns). We will initialize this matrix with the same values as the keys of our keypad. So, when a key is pressed, we will receive a value that matches the one in our keypad, which is simpler to interpret than having to convert, for example, integers in our keys.

For our keypad, shown in figure 1, we have the following mappings:

char keys[n_rows][n_cols] = {

  {'1','2','3','A'},

  {'4','5','6','B'},

  {'7','8','9','C'},

  {'*','0','#','D'}

};

Then, we declare two byte arrays, which will contain the pins of the NodeMCU that are connected to the rows and the columns of our keypad.

byte colPins[n_rows] = {D3, D2, D1, D0};
byte rowPins[n_cols] = {D7, D6, D5, D4};

Note that we are using the constants defined here so we don’t need to worry about mapping the pins of the NodeMCU board to the pins of the ESP8266.

Finally, we instantiate an object of class Keypad and pass to the constructor our matrix of keys, the arrays containing the numbers of the digital pins of the NodeMCU connected to the rows and columns of the matrix, and the number of rows and columns.

Note that the matrix of keys needs to be passed to a macro that will cast it to a char array. But this is just a detail, we can just think of it as passing the matrix to a regular function.

Keypad myKeypad = Keypad( makeKeymap(keys), rowPins, colPins, n_rows, n_cols);

In the setup function, we simply initialize a serial connection, so we can output the result of our code.

void setup(){
  Serial.begin(115200);
}

Now, in the main loop, we can call the getKey method of the class Keypad to get a char corresponding to the key pressed. This char will correspond to the one defined in the previously mentioned matrix, for the button pressed.

If there’s no key being pressed, the function will return NULL.

char myKey = myKeypad.getKey();

The full code is shown bellow, already including the printing of the pressed key to the serial port.

#include <Keypad.h>

const byte n_rows = 4;
const byte n_cols = 4;

char keys[n_rows][n_cols] = {
  {'1','2','3','A'},
  {'4','5','6','B'},
  {'7','8','9','C'},
  {'*','0','#','D'}
};

byte colPins[n_rows] = {D3, D2, D1, D0};
byte rowPins[n_cols] = {D7, D6, D5, D4};

Keypad myKeypad = Keypad( makeKeymap(keys), rowPins, colPins, n_rows, n_cols); 

void setup(){
  Serial.begin(115200);
}

void loop(){
  char myKey = myKeypad.getKey();

  if (myKey != NULL){
    Serial.print("Key pressed: ");
    Serial.println(myKey);
  }
}

To test the program, just upload the code to the ESP8266, open the Arduino IDE serial monitor and press some keys. You can check the expected output in figure 4.

Figure 4 – Output of the program.

References

[1] https://www.parallax.com/product/27899

Technical details

• ESP8266 libraries: v2.3.0
• Keypad library: v3.1.1