keypad – Support for scanning keys and key matrices

The keypad module provides native support to scan sets of keys or buttons, connected independently to individual pins, connected to a shift register, or connected in a row-and-column matrix.

Available on these boards
  • 8086 Commander
  • ARAMCON Badge 2019
  • ARAMCON2 Badge
  • ATMegaZero ESP32-S2
  • Adafruit CLUE nRF52840 Express
  • Adafruit Circuit Playground Bluefruit
  • Adafruit EdgeBadge
  • Adafruit Feather Bluefruit Sense
  • Adafruit Feather M4 CAN
  • Adafruit Feather M4 Express
  • Adafruit Feather MIMXRT1011
  • Adafruit Feather RP2040
  • Adafruit Feather STM32F405 Express
  • Adafruit Feather nRF52840 Express
  • Adafruit FunHouse
  • Adafruit Grand Central M4 Express
  • Adafruit Hallowing M4 Express
  • Adafruit ItsyBitsy M4 Express
  • Adafruit ItsyBitsy RP2040
  • Adafruit ItsyBitsy nRF52840 Express
  • Adafruit Macropad RP2040
  • Adafruit MagTag
  • Adafruit Matrix Portal M4
  • Adafruit Metro ESP32S2
  • Adafruit Metro M4 Airlift Lite
  • Adafruit Metro M4 Express
  • Adafruit Metro nRF52840 Express
  • Adafruit Monster M4SK
  • Adafruit PyGamer
  • Adafruit PyPortal
  • Adafruit PyPortal Pynt
  • Adafruit PyPortal Titano
  • Adafruit Pybadge
  • Adafruit QT Py RP2040
  • Adafruit QT2040 Trinkey
  • Adafruit Trellis M4 Express
  • AloriumTech Evo M51
  • Arduino Nano 33 BLE
  • Arduino Nano RP2040 Connect
  • Artisense Reference Design RD00
  • AtelierDuMaker nRF52840 Breakout
  • BDMICRO VINA-D51
  • BLE-SS dev board Multi Sensor
  • BastBLE
  • BastWiFi
  • CP32-M4
  • Capable Robot Programmable USB Hub
  • CircuitBrains Deluxe
  • Cytron Maker Pi RP2040
  • DynOSSAT-EDU-OBC
  • Electronut Labs Blip
  • Electronut Labs Papyr
  • Espruino Wifi
  • Feather ESP32S2 without PSRAM
  • Feather MIMXRT1011
  • Feather MIMXRT1062
  • FeatherS2
  • FeatherS2 PreRelease
  • Fomu
  • Franzininho WIFI w/Wroom
  • Franzininho WIFI w/Wrover
  • HiiBot BlueFi
  • IMXRT1010-EVK
  • IkigaiSense Vita nRF52840
  • Kaluga 1
  • LILYGO TTGO T8 ESP32-S2 w/Display
  • MDBT50Q-DB-40
  • MEOWBIT
  • MakerDiary nRF52840 MDK
  • MakerDiary nRF52840 MDK USB Dongle
  • Makerdiary M60 Keyboard
  • Makerdiary Pitaya Go
  • Makerdiary nRF52840 M.2 Developer Kit
  • Metro MIMXRT1011
  • Mini SAM M4
  • NUCLEO STM32F746
  • NUCLEO STM32F767
  • NUCLEO STM32H743
  • OPENMV-H7 R1
  • Open Hardware Summit 2020 Badge
  • PCA10056 nRF52840-DK
  • PCA10059 nRF52840 Dongle
  • Particle Argon
  • Particle Boron
  • Particle Xenon
  • PewPew M4
  • Pimoroni Keybow 2040
  • Pimoroni PGA2040
  • Pimoroni Pico LiPo (16MB)
  • Pimoroni Pico LiPo (4MB)
  • Pimoroni PicoSystem
  • Pimoroni Tiny 2040
  • PyboardV1_1
  • Raspberry Pi Pico
  • Robo HAT MM1 M4
  • SAM E54 Xplained Pro
  • SAM32v26
  • ST STM32F746G Discovery
  • STM32F412G_DISCO
  • STM32F4_DISCO
  • Saola 1 w/Wroom
  • Saola 1 w/Wrover
  • Seeeduino Wio Terminal
  • Silicognition LLC M4-Shim
  • SparkFun MicroMod ATP - RP2040
  • SparkFun MicroMod SAMD51
  • SparkFun MicroMod nRF52840
  • SparkFun Pro Micro RP2040
  • SparkFun Pro nRF52840 Mini
  • SparkFun Thing Plus - RP2040
  • SparkFun Thing Plus - SAMD51
  • TG-Boards' Datalore IP M4
  • TG-Watch
  • THUNDERPACK_v11
  • THUNDERPACK_v12
  • Targett Module Clip w/Wroom
  • Targett Module Clip w/Wrover
  • Teensy 4.0
  • Teensy 4.1
  • Teknikio Bluebird
  • The Open Book Feather
  • TinkeringTech ScoutMakes Azul
  • TinyS2
  • UARTLogger II
  • iMX RT 1020 EVK
  • iMX RT 1060 EVK
  • microS2
  • nanoESP32-S2 w/Wrover
  • nanoESP32-S2 w/Wroom
  • nice!nano
  • stm32f411ce-blackpill
  • stm32f411ce-blackpill-with-flash

class keypad.Event(key_number: int = 0, pressed: bool = True)

A key transition event.

Create a key transition event, which reports a key-pressed or key-released transition.

Parameters
  • key_number (int) – the key number

  • pressed (bool) – True if the key was pressed; False if it was released.

key_number :int

The key number.

pressed :bool

True if the event represents a key down (pressed) transition. The opposite of released.

released :bool

True if the event represents a key up (released) transition. The opposite of pressed.

__eq__(self, other: object)bool

Two Event objects are equal if their key_number and pressed/released values are equal.

__hash__(self)int

Returns a hash for the Event, so it can be used in dictionaries, etc..

class keypad.EventQueue

A queue of Event objects, filled by a keypad scanner such as Keys or KeyMatrix.

You cannot create an instance of EventQueue directly. Each scanner creates an instance when it is created.

overflowed :bool

True if an event could not be added to the event queue because it was full. (read-only) Set to False by clear().

get(self)Optional[Event]

Return the next key transition event. Return None if no events are pending.

Note that the queue size is limited; see max_events in the constructor of a scanner such as Keys or KeyMatrix. If a new event arrives when the queue is full, the event is discarded, and overflowed is set to True.

Returns

the next queued key transition Event

Return type

Optional[Event]

get_into(self, event: Event)bool

Store the next key transition event in the supplied event, if available, and return True. If there are no queued events, do not touch event and return False.

The advantage of this method over get() is that it does not allocate storage. Instead you can reuse an existing Event object.

Note that the queue size is limited; see max_events in the constructor of a scanner such as Keys or KeyMatrix.

:return True if an event was available and stored, False if not. :rtype: bool

clear(self)None

Clear any queued key transition events. Also sets overflowed to False.

__bool__(self)bool

True if len() is greater than zero. This is an easy way to check if the queue is empty.

__len__(self)int

Return the number of events currently in the queue. Used to implement len().

class keypad.KeyMatrix(row_pins: Sequence[microcontroller.Pin], column_pins: Sequence[microcontroller.Pin], columns_to_anodes: bool = True, interval: float = 0.02, max_events: int = 64)

Manage a 2D matrix of keys with row and column pins.

Create a Keys object that will scan the key matrix attached to the given row and column pins. There should not be any external pull-ups or pull-downs on the matrix: KeyMatrix enables internal pull-ups or pull-downs on the pins as necessary.

The keys are numbered sequentially from zero. A key number can be computed by row * len(column_pins) + column.

An EventQueue is created when this object is created and is available in the events attribute.

Parameters
  • row_pins (Sequence[microcontroller.Pin]) – The pins attached to the rows.

  • column_pins (Sequence[microcontroller.Pin]) – The pins attached to the colums.

  • columns_to_anodes (bool) – Default True. If the matrix uses diodes, the diode anodes are typically connected to the column pins, and the cathodes should be connected to the row pins. If your diodes are reversed, set columns_to_anodes to False.

  • interval (float) – Scan keys no more often than interval to allow for debouncing. interval is in float seconds. The default is 0.020 (20 msecs).

  • max_events (int) – maximum size of events EventQueue: maximum number of key transition events that are saved. Must be >= 1. If a new event arrives when the queue is full, the oldest event is discarded.

key_count :int

The number of keys that are being scanned. (read-only)

events :EventQueue

The EventQueue associated with this Keys object. (read-only)

deinit(self)None

Stop scanning and release the pins.

__enter__(self)KeyMatrix

No-op used by Context Managers.

__exit__(self)None

Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.

reset(self)None

Reset the internal state of the scanner to assume that all keys are now released. Any key that is already pressed at the time of this call will therefore immediately cause a new key-pressed event to occur.

key_number_to_row_column(self, row: int, column: int)Tuple[int]

Return the row and column for the given key number. The row is key_number // len(column_pins). The column is key_number % len(column_pins).

Returns

(row, column)

Return type

Tuple[int]

row_column_to_key_number(self, row: int, column: int)int

Return the key number for a given row and column. The key number is row * len(column_pins) + column.

class keypad.Keys(pins: Sequence[microcontroller.Pin], *, value_when_pressed: bool, pull: bool = True, interval: float = 0.02, max_events: int = 64)

Manage a set of independent keys.

Create a Keys object that will scan keys attached to the given sequence of pins. Each key is independent and attached to its own pin.

An EventQueue is created when this object is created and is available in the events attribute.

Parameters
  • pins (Sequence[microcontroller.Pin]) – The pins attached to the keys. The key numbers correspond to indices into this sequence.

  • value_when_pressed (bool) – True if the pin reads high when the key is pressed. False if the pin reads low (is grounded) when the key is pressed. All the pins must be connected in the same way.

  • pull (bool) – True if an internal pull-up or pull-down should be enabled on each pin. A pull-up will be used if value_when_pressed is False; a pull-down will be used if it is True. If an external pull is already provided for all the pins, you can set pull to False. However, enabling an internal pull when an external one is already present is not a problem; it simply uses slightly more current.

  • interval (float) – Scan keys no more often than interval to allow for debouncing. interval is in float seconds. The default is 0.020 (20 msecs).

  • max_events (int) – maximum size of events EventQueue: maximum number of key transition events that are saved. Must be >= 1. If a new event arrives when the queue is full, the oldest event is discarded.

key_count :int

The number of keys that are being scanned. (read-only)

events :EventQueue

The EventQueue associated with this Keys object. (read-only)

deinit(self)None

Stop scanning and release the pins.

__enter__(self)Keys

No-op used by Context Managers.

__exit__(self)None

Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.

reset(self)None

Reset the internal state of the scanner to assume that all keys are now released. Any key that is already pressed at the time of this call will therefore immediately cause a new key-pressed event to occur.

class keypad.ShiftRegisterKeys(*, clock: microcontroller.Pin, data: microcontroller.Pin, latch: microcontroller.Pin, value_to_latch: bool = True, key_count: int, value_when_pressed: bool, interval: float = 0.02, max_events: int = 64)

Manage a set of keys attached to an incoming shift register.

Create a Keys object that will scan keys attached to a parallel-in serial-out shift register like the 74HC165 or CD4021. Note that you may chain shift registers to load in as many values as you need.

Key number 0 is the first (or more properly, the zero-th) bit read. In the 74HC165, this bit is labeled Q7. Key number 1 will be the value of Q6, etc.

An EventQueue is created when this object is created and is available in the events attribute.

Parameters
  • clock (microcontroller.Pin) – The shift register clock pin. The shift register should clock on a low-to-high transition.

  • data (microcontroller.Pin) – the incoming shift register data pin

  • latch (microcontroller.Pin) – Pin used to latch parallel data going into the shift register.

  • value_to_latch (bool) – Pin state to latch data being read. True if the data is latched when latch goes high False if the data is latched when latch goes low. The default is ``True, which is how the 74HC165 operates. The CD4021 latch is the opposite. Once the data is latched, it will be shifted out by toggling the clock pin.

  • key_count (int) – number of data lines to clock in

  • value_when_pressed (bool) – True if the pin reads high when the key is pressed. False if the pin reads low (is grounded) when the key is pressed.

  • interval (float) – Scan keys no more often than interval to allow for debouncing. interval is in float seconds. The default is 0.020 (20 msecs).

  • max_events (int) – maximum size of events EventQueue: maximum number of key transition events that are saved. Must be >= 1. If a new event arrives when the queue is full, the oldest event is discarded.

key_count :int

The number of keys that are being scanned. (read-only)

events :EventQueue

The EventQueue associated with this Keys object. (read-only)

deinit(self)None

Stop scanning and release the pins.

__enter__(self)Keys

No-op used by Context Managers.

__exit__(self)None

Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.

reset(self)None

Reset the internal state of the scanner to assume that all keys are now released. Any key that is already pressed at the time of this call will therefore immediately cause a new key-pressed event to occur.