# Matrix Keypad

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/059/252/medium800/raspberry_pi_matrix_keypad_phone_product.jpg?1534449588)

Hey, Jenny, I've got your number! And I'm going to punch it into one of these nice matrix keypads. We have a bunch of different options in 3x4- and 4x4-grid styles. These are an easy way to add some input options to your project!

![](https://cdn-learn.adafruit.com/assets/assets/000/059/251/medium800/raspberry_pi_matrix_keypad_3x4_header_product.jpg?1534449578)

The keys are connected into a matrix, so for the 3x4 matrix keypads, you only need 7 microcontroller pins (3-columns and 4-rows) to scan through the pad. On the 4x4 matrix keypads, you only need 8 microcontroller pins (4-columns and 4-rows) to scan through the pad.

We have libraries in Arduino and CircuitPython to make getting started super simple and fast.

![](https://cdn-learn.adafruit.com/assets/assets/000/059/253/medium800/raspberry_pi_matrix_keypad_membrane_product.jpg?1534449833)

So wire it up to your project, and punch in your secret key to open all the possibilities!

# Matrix Keypad

## Pinouts

The following covers the pinout for the various key pad products.

## General Nomenclature

Each keypad is a combination of **row** and **column** circuits. The buttons themselves are simple switch like closures in these circuits. Here's an example of a basic 4x4 keypad arrangement.

![](https://cdn-learn.adafruit.com/assets/assets/000/089/965/medium800/raspberry_pi_3844_diagram.jpg?1585337522)

There is 1 pin for each column and 1 pin for each row. So for the 4x4 keypad, there are 4 + 4 = 8 total pins. For the 3x4 keypad, there are 3 + 4 = 7 pins. Etc. Each of these needs to be connected to a separate digital pin on the microcontroller.

In the diagram above, the pins **1-4** correspond to the **columns** while pins **5-8** correspond to **rows**. Determining if a particular button is pressed is done by programmatically changing the digital pins between input and output and reading pin state. Doing this across all possible pin combinations is referred to as a **scan**. All of that work is typically taken care of for you in a library.

## 4x4 Matrix Keypad (PID 3844)

Pinout

![](https://cdn-learn.adafruit.com/assets/assets/000/089/966/medium800/raspberry_pi_PID3844_pinout.jpg?1585338630)

## 3x4 Matrix Keypad (PID 3845)

Pinout

![](https://cdn-learn.adafruit.com/assets/assets/000/089/967/medium800/raspberry_pi_PID3845_pinout.jpg?1585340216)

## 3x4 Phone-style Matrix Keypad (PID 1824)

Pinout

![](https://cdn-learn.adafruit.com/assets/assets/000/089/978/medium800/raspberry_pi_PID1824_Pinout.jpg?1585343656)

## Membrane 3x4 Matrix Keypad (PID 419)

Pinout

![](https://cdn-learn.adafruit.com/assets/assets/000/089/977/medium800/raspberry_pi_PID419_Pinout.jpg?1585342767)

## Membrane 1x4 Matrix Keypad (PID 1332)

Pinout

![](https://cdn-learn.adafruit.com/assets/assets/000/091/593/medium800/raspberry_pi_PID1332_Pinout.jpg?1590705936)

# Matrix Keypad

## Arduino

The following shows an example using the Adafruit Keypad Arduino library.

## Install Keypad Library

You can install the Keypad library via the Library Manager.

**Tools -\> Manage Libraries...**

Open it, search for 'keypad', and click Install on the one labeled Adafruit Keypad.

![](https://cdn-learn.adafruit.com/assets/assets/000/089/969/medium800/raspberry_pi_arduino_library.jpg?1585341513)

## Example

For this example we will use the 3x4 Matrix Keypad ([PID3845](https://www.adafruit.com/product/3845)). Here is the wiring.

![](https://cdn-learn.adafruit.com/assets/assets/000/091/601/medium800/raspberry_pi_keypad_example.jpg?1590710431)

In the Arduino IDE open the example:

**File -\> Examples -\> Adafruit Keypad -\> keypad\_test**

Find these lines of code up near the top:

```cpp
// define your specific keypad here via PID
#define KEYPAD_PID3844
```

and change it to this to match the keypad being used:

```cpp
// define your specific keypad here via PID
#define KEYPAD_PID3845
```

Upload the sketch and then open the Serial Monitor

**Tools -\> Serial Monitor**

Try pressing the buttons. You should see text like this:

![](https://cdn-learn.adafruit.com/assets/assets/000/091/596/medium800/raspberry_pi_Screenshot_from_2020-05-28_16-06-15.png?1590707191)

Note that each press produces two messages. One for the down ( **pressed** ) and one for the up ( **released** ).

# Matrix Keypad

## Python & CircuitPython

It's easy to use a matrix keypad with Python or CircuitPython and the [Adafruit CircuitPython Matrix Keypad](https://github.com/adafruit/Adafruit_CircuitPython_MatrixKeypad) module.  This module allows you to easily write Python code that reads the button presses from the keypad.

You can use this with any CircuitPython microcontroller board or with a computer that has GPIO and Python [thanks to Adafruit\_Blinka, our CircuitPython-for-Python compatibility library](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux).

**On most native CircuitPython boards, you can use the builtin `keypad` module instead of the Adafruit\_Matrix library. See the [`keypad` Learn Guide](https://learn.adafruit.com/key-pad-matrix-scanning-in-circuitpython) and [this page](https://learn.adafruit.com/key-pad-matrix-scanning-in-circuitpython/keymatrix) for more details.**

# CircuitPython Microcontroller Wiring

First wire up a matrix keypad to your board. Here's an example of wiring a 3x4 matrix to a Feather M0. You can use any free digital I/O pins. The keypad pins are referenced left to right if the keypad is oriented upright and facing you, i.e. pin 1 is the first pin on the side of the header closest to the 1-column on the keypad.

- **Board D13** to **keypad pin 1**
- **Board D12** to **keypad pin 2**
- **Board D11** to **keypad pin 3**
- **Board D10** to **keypad pin 4**
- **Board D9** to **keypad pin 5**
- **Board D6** to **keypad pin 6**
- **Board D5** to **keypad pin 7**

![raspberry_pi_FeatherM0_Matrix_Keypad_2_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/059/263/medium640/raspberry_pi_FeatherM0_Matrix_Keypad_2_bb.jpg?1534452259)

# Python Computer Wiring

Since there's _dozens_ of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, [please visit the guide for CircuitPython on Linux to see whether your platform is supported](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux). 

Here's an example of a 3x4 matrix keypad wired to the Raspberry Pi. You can use any free digital I/O pins. The keypad pins are referenced left to right if the keypad is oriented upright and facing you, i.e. pin 1 is the first pin on the side of the header closest to the 1-column on the keypad.

- **Pi GPIO5** to **keypad pin 1**
- **Pi GPIO6** to **keypad pin 2**
- **Pi GPIO13** to **keypad pin 3**
- **Pi GPIO19** to **keypad pin 4**
- **Pi GPIO26** to **keypad pin 5**
- **Pi GPIO20** to **keypad pin 6**
- **Pi GPIO21** to **keypad pin 7**

![raspberry_pi_raspi_matrix_keypad_bb.jpg](https://cdn-learn.adafruit.com/assets/assets/000/059/265/medium640/raspberry_pi_raspi_matrix_keypad_bb.jpg?1534455027)

# CircuitPython Installation of Matrix Keypad Library

You'll need to install the [Adafruit CircuitPython Matrix Keypad](https://github.com/adafruit/Adafruit_CircuitPython_MatrixKeypad) library on your CircuitPython board.

First make sure you are running the [latest version of Adafruit CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython) for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases).  Our CircuitPython starter guide has [a great page on how to install the library bundle](https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries).

For non-express boards like the Trinket M0 or Gemma M0, you'll need to manually install the necessary libraries from the bundle:

- **adafruit\_matrixkeypad.mpy**

Before continuing make sure your board's lib folder or root filesystem has the **adafruit\_matrixkeypad.mpy ** file copied over.

Next[ connect to the board's serial REPL](https://learn.adafruit.com/welcome-to-circuitpython/the-repl) so you are at the CircuitPython  **\>\>\>**  prompt.

# Python Installation of Matrix Keypad Library

You'll need to install the Adafruit\_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. [Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux)!

Once that's done, from your command line run the following command:

- `pip3 install adafruit-circuitpython-matrixkeypad`

If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!

# CircuitPython & Python Usage

To demonstrate the usage of a matrix keypad, we'll initialise it and read the button presses from the board's Python REPL.

First run the following code to import the necessary libraries:

```auto
import time
import digitalio
import board
import adafruit_matrixkeypad
```

Next we're going to identify what pins are associated with the rows and columns, and set up the order of the keys:

```auto
cols = [digitalio.DigitalInOut(x) for x in (board.D9, board.D6, board.D5)]
rows = [digitalio.DigitalInOut(x) for x in (board.D13, board.D12, board.D11, board.D10)]
keys = ((1, 2, 3),
        (4, 5, 6),
        (7, 8, 9),
        ('*', 0, '#'))
```

Then we initialise the matrix:

```auto
keypad = adafruit_matrixkeypad.Matrix_Keypad(rows, cols, keys)
```

Now you're ready to utilise the keypad with the following property:

- **pressed\_keys** : An array containing all detected keys that are pressed from the initialised list-of-lists passed in during creation.

For example, to print all the key presses:

```auto
while True:
    keys = keypad.pressed_keys
    if keys:
        print("Pressed: ", keys)
    time.sleep(0.1)
```

![](https://cdn-learn.adafruit.com/assets/assets/000/059/268/medium800/raspberry_pi_Matrix_Keypad_Printed_Output.png?1534456529)

That's all there is to using a matrix keypad with CircuitPython!

# Full Example Code
For CircuitPython microcontroller boards:

https://github.com/adafruit/Adafruit_CircuitPython_MatrixKeypad/blob/main/examples/matrixkeypad_simpletest.py

For Raspberry Pi:

https://github.com/adafruit/Adafruit_CircuitPython_MatrixKeypad/blob/main/examples/matrixkeypad_rpi_simpletest.py

# Matrix Keypad

## Python Docs


## Related Guides

- [Grand Central Soundboard in Ten Minutes](https://learn.adafruit.com/grand-central-soundboard-in-ten-minutes.md)
- [Working with Multiple Same Address I2C Devices](https://learn.adafruit.com/working-with-multiple-i2c-devices.md)
- [Running TensorFlow Lite Object Recognition on the Raspberry Pi 4 or Pi 5](https://learn.adafruit.com/running-tensorflow-lite-on-the-raspberry-pi-4.md)
- [Raspberry Pi Camera Timelapse Case](https://learn.adafruit.com/pi-timelapse.md)
- [Adafruit MagTag Project Selector](https://learn.adafruit.com/adafruit-magtag-project-selector.md)
- [Desk Calculator with CircuitPython](https://learn.adafruit.com/desk-calculator-with-circuitpython.md)
- [CircuitPython Libraries on any Computer with MCP2221](https://learn.adafruit.com/circuitpython-libraries-on-any-computer-with-mcp2221.md)
- [Raspberry Pi Computer Quick-Start](https://learn.adafruit.com/raspberry-pi-computer-quick-start.md)
- [NeoTrellis MIDI Feedback Controller](https://learn.adafruit.com/neotrellis-midi-feedback-controller.md)
- [Adafruit PCF8591 Basic 4 x ADC + DAC Breakout](https://learn.adafruit.com/adafruit-pcf8591-adc-dac.md)
- [eInk Slow Movie Player](https://learn.adafruit.com/eink-slow-movie-player.md)
- [Data Logging with Feather and CircuitPython](https://learn.adafruit.com/data-logging-with-feather-and-circuitpython.md)
- [Temperature and Humidity Sensing in Home Assistant with CircuitPython](https://learn.adafruit.com/temperature-and-humidity-sensing-in-home-assistant-with-circuitpython.md)
- [MPR121 Capacitive Touch Sensor on Raspberry Pi & BeagleBone Black](https://learn.adafruit.com/mpr121-capacitive-touch-sensor-on-raspberry-pi-and-beaglebone-black.md)
- [Install bluez on the Raspberry Pi](https://learn.adafruit.com/install-bluez-on-the-raspberry-pi.md)