The Adafruit MacroPad RP2040 features a 3x4 key pad and a rotary encoder with push switch. This example uses the first few keys to send different types of HID commands, the rotary encoder switch to send a right mouse click, and the rotary encoder to move the mouse left and right.

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.

Be aware that this an HID demo, which means it will be sending key commands and moving your mouse! Once you hit save, make sure your cursor is in a text editor of some sort so you can see the results typed out.
# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: Unlicense
MacroPad HID keyboard and mouse demo. The demo sends "a" when the first key is pressed, a "B" when
the second key is pressed, "Hello, World!" when the third key is pressed, and decreases the volume
when the fourth key is pressed. It sends a right mouse click when the rotary encoder switch is
pressed. Finally, it moves the mouse left and right when the rotary encoder is rotated
counterclockwise and clockwise respectively.
from adafruit_macropad import MacroPad

macropad = MacroPad()

last_position = 0
while True:
    key_event =

    if key_event:
        if key_event.pressed:
            if key_event.key_number == 0:
            if key_event.key_number == 1:
      , macropad.Keycode.B)
            if key_event.key_number == 2:
                macropad.keyboard_layout.write("Hello, World!")
            if key_event.key_number == 3:


    if macropad.encoder_switch_debounced.pressed:

    current_position = macropad.encoder

    if macropad.encoder > last_position:
        last_position = current_position

    if macropad.encoder < last_position:
        last_position = current_position

Try pressing the first key, it will type out a lowercase "a". Press the second key, it will type out an uppercase "B". Press the third key, it will type out the string "Hello, World!". Press the fourth key, it will decrease the volume. Press down on the rotary encoder switch to send a right mouse click. Rotate the rotary encoder clockwise to move the mouse cursor to the right, and counterclockwise to move it to the left.

The MacroPad library wraps in the ability to send HID commands to your computer, such as key presses, strings, consumer control commands (e.g. volume increase or decrease), and mouse clicks and movement. The library also makes it simple to read key presses and the rotary encoder position, and makes a debounced version of the rotary encoder switch available.

In your code, first, you import the MacroPad library, and then instantiate it.

Then you create a last_position variable to track the rotary encoder position, and set it to 0.

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 do the following based on key number. Remember, key 0 is the first key - Python begins counting at 0.

  • If key 0 is pressed, send the letter "a".
  • If key 1 is pressed, send "shift+b" to send "B".
  • If key 2 is pressed, send the string "Hello, World!"
  • If key 3 is pressed, decrease the volume.

Next, you include macropad.encoder_switch_debounced.update() in your code to continually check the state of the switch. This line is required to use the debounced encoder switch. Once you include the update() line, you can check for two states:

  • macropad.encoder_switch_debounced.pressed - True when the switch is pressed. Sends only one press event per switch press.
  • macropad.encoder_switch_debounced.released - True when the switch is released. Sends only one release event per switch release.

In this case, you check to see if the rotary encoder is pressed, and if so, send a right mouse click. Using the debounced version of the rotary encoder ensures that the mouse click is only sent one time per switch press.

Then, you set current_position = macropad.encoder so you have the current position of the rotary encoder to work with.

Next, you check to see if the encoder position is greater than the last_position (which starts at 0), which is to say, has it been rotated clockwise. If so, move the mouse to the right, and set the last position equal to the current position so you can begin tracking again.

Finally, you do the same again, except this time you're checking whether the encoder position is less than the last position, which is to say, has it been rotated counterclockwise. If so, move the mouse to the left, and set last_position = current_position.

That's all there is to using the Adafruit MacroPad to send HID commends with the CircuitPython MacroPad library!

This guide was first published on Jun 30, 2021. It was last updated on May 26, 2024.

This page (MacroPad Keyboard and Mouse) was last updated on May 26, 2024.

Text editor powered by tinymce.