The Adafruit MacroPad RP2040 features a 3x4 key pad with NeoPixel LEDs, and a rotary encoder with push switch. This example reads the key presses, the relative position of the rotary encoder and the state of the rotary encoder switch, and prints the information to the serial console.

Update your to the following.

Click the Download Project Bundle button below to download the necessary libraries and the file in a zip file. Extract the contents of the zip file, open the folder that matches your CircuitPython version, and copy the entire lib folder and the file to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:

# SPDX-FileCopyrightText: Copyright (c) 2021 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: Unlicense
Simpletest demo for MacroPad. Prints the key pressed, the relative position of the rotary
encoder, and the state of the rotary encoder switch to the serial console.
import time
from adafruit_macropad import MacroPad

macropad = MacroPad()

while True:
    key_event =
    if key_event and key_event.pressed:
        print("Key pressed: {}".format(key_event.key_number))
    print("Encoder: {}".format(macropad.encoder))
    print("Encoder switch: {}".format(macropad.encoder_switch))

Now, connect to the serial console. Try pressing keys, rotating the rotary encoder, and pressing the rotary encoder switch to see the results printed out.

To use the MacroPad library, you need to import it and instantiate it with the following code:

from adafruit_macropad import MacroPad

macropad = MacroPad()

Once, instantiated as macropad, you have access to all the features of the MacroPad library. To use the features of the library, you include macropad.feature_name in your code. This example uses the following features:

  • keys - The keys on the MacroPad. Uses events to track key number and state, e.g. pressed or released. You must fetch the events using and then the events are available for usage in your code. Each event has three properties: key_number, pressed, and released.
  • encoder - The rotary encoder relative rotation position. Always begins at 0 when the code is run, so the value returned is relative to the initial location.
  • encoder_switch - The rotary encoder switch. Returns True when pressed.

Therefore, to read the rotary encoder, you would include macropad.encoder in your code.

In this example, you first import time, then the MacroPad library, and instantiate the library as macropad.

Inside the loop, the first thing you do is setup to look for the key press by creating the key_event variable and assigning it to Then, you check to see if there is a key_event (i.e. a key being pressed) and if it is a key being pressed (key_event.pressed). Then, if so, print the key number (key_event.key_number) being pressed to the serial console.

Then, you print to the serial console the relative position of the rotary encoder (with macropad.encoder) and the state of the encoder switch (with macropad.encoder_switch).

Finally, you include a time.sleep(0.4) to print the information every 0.4 seconds to keep the serial console results readable.

That's all there is to reading the key presses, rotary encoder relative position, and rotary encoder switch state on the Adafruit MacroPad using the CircuitPython MacroPad library!

This guide was first published on Jun 30, 2021. It was last updated on Jul 20, 2024.

This page (MacroPad Basics) was last updated on Jul 20, 2024.

Text editor powered by tinymce.