ESP32 Keypad Matrix (Kaypad-LCD Example) – Arduino IDE

This is a comprehensive guide for ESP32 Keypad interfacing. You’ll learn how to use ESP32 Keypad Matrix with Arduino IDE. We’ll create a few examples to practice the subject and you will modify the examples to achieve what’s needed in your project. The first example will show you how to interface ESP32 with both 4×4 and 4×3 Keypad, then use Keypad with LCD, and finally, we’ll create an electronic lock password-based system with ESP32 keypad and LCD.

The ESP32 Keypad Application Examples That We’ll Create in This Tutorial Are As Follows:

  1. ESP32 Keypad interfacing Demo Example For 4×4 and 3×4 Keypad Matrix
  2. ESP32 Keypad LCD Example (With i2c LCD)
  3. ESP32 Keypad Lock Password-Based System

Table of Contents

  1. ESP32 Keypad Interfacing
  2. ESP32 Keypad Library (Arduino Core)
  3. ESP32 Keypad Example Code (Arduino Core)
  4. ESP32 Keypad LCD Example (I2C LCD)
  5. ESP32 Keypad Lock Password Example
  6. Download Attachments
  7. Concluding Remarks

ESP32 Keypad Interfacing

A keypad is a matrix of buttons connected in rows and columns to form the whole unit. In software, we scan through the rows and columns pins on the microcontroller in order to decide which key on the keypad is pressed by the user. And here is a clear diagram of how the keypad looks internally.

STM32 Keypad Library Code

And this is the keypad pinout.


For the 4×4 Keypad, there are 8 pins (4 rows and 4 columns). And for the 4×3 Keypad, there are 6 pins (4 rows and 3 columns).

Here is how to connect ESP32 with Keypad 4×4 and 4×3.

ESP32 Keypad 4×4 Wiring Diagram


ESP32 Keypad 4×3 Wiring Diagram


ESP32 Keypad Library (Arduino Core)

You need to install the Keypad library for the ESP32 Arduino core first before you’re able to use it, unlike the built-in Arduino Keypad library. But it’s rather simple to do, just open the library manager from the tools menu.


Then, search for this keypad library and click install.


Now, you can use the Keypad library in any project by including the library header file as shown below.


You need to specify the number of rows and columns in your keypad (For a 4×4 matrix it’s 4 rows and 4 columns) and similarly any other variant of membrane keypads. This is done by the following definitions.


Then, you should create a keyMap with the characters that correspond to each key on the keypad. This is done by defining a two-dimensional array as shown below.


Next, we need to select the GPIO pins that we’ll use for connecting the keypad pins. The rows’ pins as well as the columns’ pins, which can be done by defining the following two arrays.


Now, we need to create an instance of the Keypad and pass to it all the information that we’ve defined earlier.


And that’s all about it. Whenever you need to read the keypad status, call this function as shown below, and it’s going to return the equivalent character for the key that’s currently pressed by the user.


And we’ll test this out in the following examples hereafter in this tutorial.

Some Useful APIs (Functions) in The Keypad Library

Here is a brief for some of the useful functions in the Keypad library that you may need to use in your project.

  • setDebounceTime(unsigned int time) sets the number of milliseconds the keypad will wait until it accepts a new keypress/key event.
  • KeyState getState() returns the current state of any of the keys. The four states are IDLE, PRESSED, RELEASED, and HOLD.
  • setHoldTime(unsigned int time) sets the number of milliseconds the user will have to hold a button until the HOLD state is triggered.
  • addEventListener(keypadEvent) triggers an event if the keypad is clicked on. You pass your callback function handler to it.
  • boolean keyStateChanged() lets you know when the key has changed from one state to another. instead of polling for a key state, you can get if it’s changed or not.
  • char waitForKey() waits forever until someone presses a key. Be advised that this is a blocking routine that may mess up your system timing behavior or cause unexpected delays.

ESP32 Keypad Example Code (Arduino Core)

Here are two examples to test the ESP32 Keypad library functionality with both a 4×4 keypad matrix and a 4×3 keypad matrix. You can modify the code to achieve any different functionality that you want.

In the examples below, clicking on any key on the keypad will trigger a serial write operation for the equivalent character of the key that’s held down by the user. Just a very simple application to test that everything is running ok as we expect it to.

ESP32 Keypad 4×4 Example


Here is what the output looks like on the serial monitor. I’ve tried all the keys and it’s working as expected.


ESP32 Keypad 4×3 Example


And here is the output on the serial monitor, as you can see all the keys are working just as fine.


ESP32 Keypad LCD Example (I2C LCD)

In this example, we’ll add an LED to the project and it’s going to display the text written using the keypad instead of using the serial monitor. We’ll be using the I2C version of the alphanumeric LCD 16×2 because it’s the most efficient way to do it in terms of GPIO pins utilization. All the keys’ characters will be displayed on the LCD except for the “D” key, we’ll program it to be a “Clear Screen” button instead.

The screen shall also be cleared whenever we reach the 16th character which is the limit per line of characters.


Here is how to hook up the ESP32 with i2C LCD and Keypad.


ESP32 GPIO PinConnect To
GPIO14 Row1
GPIO27 Row2
GPIO26 Row3
GPIO25 Row4
GPIO33 Col1
GPIO32 Col2
GPIO18 Col3
GPIO19 Col4

Example Code

Here is the full code listing for this example project.


Testing Results

This is a quick demo showing the testing results for this example project.

ESP32 Keypad Lock Password Example

This is a simple password-based lock system with ESP32 Keypad + I2C LCD. The password is a 6-char string and the user is allowed to enter 6 numbers only. if the password is correct, we’ll print “Access Granted!” to the LCD. If it’s not correct, we’ll print “Wrong PassWord!”. The ‘D’ key is used for clearing the display and re-try.


Exactly the same as the previous example.

Example Code

Here is the full code listing for this example project.


Testing Results

This is a quick demo showing the testing results for this example project.

Parts List

Here is the full components list for all parts that you’d need in order to perform the practical LABs mentioned here in this article and for the whole ESP32 series of tutorials found here on DeepBlueMbedded. Please, note that those are affiliate links and we’ll receive a small commission on your purchase at no additional cost to you, and it’d definitely support our work.

Download Attachments

You can download all attachment files for this Article/Tutorial (project files, schematics, code, etc..) using the link below. Please consider supporting my work through the various support options listed in the link down below. Every small donation helps to keep this website up and running and ultimately supports our community.

Concluding Remarks

In conclusion, keypads can be used for so many applications and we’ll definitely address some of them in future tutorials. A better version of the password-based lock system can be built using NVS (non-volatile storage) in the ESP32 in order to save new passwords that the user can input into the system in order to be truly flexible, not hard-coded.

The password should be stored in a memory that’s not whipped out when the controller’s power goes OFF, which is a typical application where you need to use the NVS of the ESP32. To learn more about ESP32 NVS check the following tutorials that cover all possible options to store and retrieve data to/from the ESP32 Non-Volatile Storage.

  • ESP32 EEPROM Tutorial
  • ESP32 Flash Memory (External SPI Flash) Tutorial
  • ESP32 Preferences Flash Memory Tutorial
Share This Page With Your Network!
Join Our +25,000 Newsletter Subscribers!

Stay Updated With All New Content Releases. You Also Get Occasional FREE Coupon Codes For Courses & Other Stuff!

Photo of author
Khaled Magdy
Embedded systems engineer with several years of experience in embedded software and hardware design. I work as an embedded SW engineer in the Automotive & e-Mobility industry. However, I still do Hardware design and SW development for DSP, Control Systems, Robotics, AI/ML, and other fields I'm passionate about.
I love reading, writing, creating projects, and teaching. A reader by day and a writer by night, it's my lifestyle. I believe that the combination of brilliant minds, bold ideas, and a complete disregard for what is possible, can and will change the world! I will be there when it happens, will you?

Leave a Comment