It's easy to use a matrix keypad with Python or CircuitPython and the Adafruit CircuitPython Matrix Keypad 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.
On most native CircuitPython boards, you can use the builtin keypad module instead of the Adafruit_Matrix library. See the keypad Learn Guide and this page 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
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.
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
CircuitPython Installation of Matrix Keypad Library
You'll need to install the Adafruit CircuitPython Matrix Keypad library on your CircuitPython board.
First make sure you are running the latest version of Adafruit 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. Our CircuitPython starter guide has a great page on how to install the library bundle.
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 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!
Once that's done, from your command line run the following command:
sudo 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:
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:
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:
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:
while True:
keys = keypad.pressed_keys
if keys:
print("Pressed: ", keys)
time.sleep(0.1)
That's all there is to using a matrix keypad with CircuitPython!
For CircuitPython microcontroller boards:
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import time
import digitalio
import board
import adafruit_matrixkeypad
# Membrane 3x4 matrix keypad - https://www.adafruit.com/product/419
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)]
# 3x4 matrix keypad - Rows and columns are mixed up for https://www.adafruit.com/product/3845
# Use the same wiring as in the guide with the following setup lines:
# cols = [digitalio.DigitalInOut(x) for x in (board.D11, board.D13, board.D9)]
# rows = [digitalio.DigitalInOut(x) for x in (board.D12, board.D5, board.D6, board.D10)]
keys = ((1, 2, 3), (4, 5, 6), (7, 8, 9), ("*", 0, "#"))
keypad = adafruit_matrixkeypad.Matrix_Keypad(rows, cols, keys)
while True:
keys = keypad.pressed_keys
if keys:
print("Pressed: ", keys)
time.sleep(0.1)
For Raspberry Pi:
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
import time
import digitalio
import board
import adafruit_matrixkeypad
# Membrane 3x4 matrix keypad on Raspberry Pi -
# https://www.adafruit.com/product/419
cols = [digitalio.DigitalInOut(x) for x in (board.D26, board.D20, board.D21)]
rows = [digitalio.DigitalInOut(x) for x in (board.D5, board.D6, board.D13, board.D19)]
# 3x4 matrix keypad on Raspberry Pi -
# rows and columns are mixed up for https://www.adafruit.com/product/3845
# cols = [digitalio.DigitalInOut(x) for x in (board.D13, board.D5, board.D26)]
# rows = [digitalio.DigitalInOut(x) for x in (board.D6, board.D21, board.D20, board.D19)]
keys = ((1, 2, 3), (4, 5, 6), (7, 8, 9), ("*", 0, "#"))
keypad = adafruit_matrixkeypad.Matrix_Keypad(rows, cols, keys)
while True:
keys = keypad.pressed_keys
if keys:
print("Pressed: ", keys)
time.sleep(0.1)
