The Keys scanner is the simplest. Each key or button is connected to its own pin on your microcontroller board. When you create a Keys scanner, you give it a sequence of pins, and say whether the pins become True or False (high or low logic value) when pressed. You also say whether internal pull-up or pull-down resistors need to be enabled on the pins to force a stable voltage level when the keys or buttons are not pressed.

One-Button Example

Here's a really simple example, with just one button:

One terminal of a button is connected to pin D5 on this Feather board, and the other terminal is grounded. D5 will need to be pulled up, because there is no external pull-up resistor. When the button is not pressed, D5 will be high (True), and when it is pressed, D5 will be low (False).

import board
import keypad

keys = keypad.Keys((board.D5,), value_when_pressed=False, pull=True)

while True:
    event = keys.events.get()
    # event will be None if nothing has happened.
    if event:
        print(event)

The program creates a Keys object, and passes it a tuple of one pin (D5). That pin will be key_number 0.

We set value_when_pressed to False, because the pin goes low when the button is pressed. We set pull to True because we haven't provided an external resistor. When pull is True, it will enable a pull-up or a pull-down appropriately:

  • If value_is_pressed is True, enable an internal pull-down resistor, to hold the pin low when not pressed.
  • If value_is_pressed is False, enable an internal pull-up resistor, to hold the pin high when not pressed.

When you press the button, you'll get an Event saying that key_number 0 has been pressed (see below). When you release, the button you'll get a released event. The output will look like this:

<Event: key_number 0 pressed>
<Event: key_number 0 released>
<Event: key_number 0 pressed>
<Event: key_number 0 released>

Events and EventQueues

We glossed over how events are fetched in the example above. When you press or release a key, the scanner notices that a key has changed state. It records an Event in the EventQueue attached to the scanner. You get the EventQueue by accessing the events property of the scanner. In the example above the EventQueue is available from keys.events.

To fetch the next Event from the EventQueue, you use events.get(). If nothing has happened (no press or release of any key) since you last asked, events.get() returns None.

Every Event has three properties:

  • key_number: the number of the key that changed. Keys are numbered starting at 0.
  • pressed: True if the event is a transition from released to pressed.
  • released: True if the event is a transition from pressed to released. released is always the opposite of pressed; it's provided for convenience and clarity, in case you want to test for key-release events explicitly.

You only get a pressed or released event once per transition. If you keep holding down a key, you won't get multiple pressed events.

MacroPad Example

The Adafruit MacroPad has 12 keys, with one key per pin. This program illuminates a key when it's pressed, and turns off the illumination when it's released.

Note that the key pin names are KEY1 to KEY12, but the key_number values are 0 to 11.

import board
import keypad
import neopixel

KEY_PINS = (
    board.KEY1,
    board.KEY2,
    board.KEY3,
    board.KEY4,
    board.KEY5,
    board.KEY6,
    board.KEY7,
    board.KEY8,
    board.KEY9,
    board.KEY10,
    board.KEY11,
    board.KEY12,
)

keys = keypad.Keys(KEY_PINS, value_when_pressed=False, pull=True)

neopixels = neopixel.NeoPixel(board.NEOPIXEL, 12, brightness=0.4)

while True:
    event = keys.events.get()
    if event:
        # A key transition occurred.
        print(event)

        if event.pressed:
            # Turn the key blue when pressed
            neopixels[event.key_number] = (0, 0, 255)

        # This could just be `else:`,
        # since event.pressed and event.released are opposites.
        if event.released:
            neopixels[event.key_number] = (0, 0, 0)

Here's some sample output from the program. In this case I pressed down key number 0, held it down, and then pressed key 1. Then I released key 0 and then released key 1. Then I pressed key 2.

<Event: key_number 0 pressed>
<Event: key_number 1 pressed>
<Event: key_number 0 released>
<Event: key_number 1 released>
<Event: key_number 2 pressed>
<Event: key_number 2 released>

This guide was first published on Jun 29, 2021. It was last updated on Jun 29, 2021.

This page (Keys and Events) was last updated on Sep 25, 2021.

Text editor powered by tinymce.