Adabox 019 MacroPad



AdaBox 019 - Adafruit MicroPad



  • Programmable with Arduino or CircuitPython
  • 3.3V in/out max
  • RP2040 chip (does not support QMK) Dual ARM cortex-M0+ 133MHz with 264kB on-chip SRAM
  • 8MB flash memory QSPI chip
  • USB-C connector
  • 12 buttons (cherry mx-compatible)
  • 12 neopixels
  • OLED display (128x64 monochrome) SH1106 - over SPI
  • rotary encoder (20 detents per rotation) - with push button
  • tiny speaker - 8mm speaker/buzzer - class D amplifier and RC filter
  • reset button
  • Red LED (right next to usb plug, facing upward)
  • STEMMA QT port next to reset button on side (i2c/StemmaQT/Qwiic) - Add any i2c peripher
  • Four M3 mounting bosses

Enter bootloader

  • Hold down rotary button when powering up or resetting


Setup CircuitPy firmware

Download the latest CircuitPy firmware.

Plug in the MacroPad to the computer. Press and hold the rotary encoder button, and then press the reset button on the side of the board. This will start it in bootloader mode. The computer will see it as a USB drive where you can drop the .uf2 firmware file with CircuitPy. It will automatically reboot after you copy the file over. Then the board will show up as CIRCUITPY removable drive with a file and a lib/ directory. Any time you modify the file it will reboot and run. Libraries like .mpy files can be dropped in the lib/ directory.

Accessing the REPL

It can be useful to access the interactive REPL. You can connect to the board over serial. For example, load PuTTy, and connect over serial to COM4 (for example) at 115200 baud. Then you'll get the REPL. In Windows, if you need to figure out what COM port it is, run Device Manager, and expand Ports.

>>> help('modules')
>>> import board
>>> dir(board)
>>> import sys
>>> sys.version
>>> sys.path 
>>> sys.implementation
>>> sys.platform
>>> exec(open('').read())
# Get interactive input from the console
name = input('What is your name?')

Add libraries

Copy all the recommended libraries from the AdaFruit library collection into the lib/ directory on the board. Some are just .mpy modules, some are packages with a directory.

Download the full library bundle from Included is a MacroPad library specifically for this device. Docs for the library are at:

The recommended libraries from this bundle are listed below. Copy these into your lib/ directory from the downloaded bundle.

  • adafruit_macropad.mpy - A helper library for using the features of the Adafruit MacroPad.
  • adafruit_debouncer.mpy - A helper library for debouncing pins. Used to provide a debounced instance of the rotary encoder switch.
  • adafruit_simple_text_display.mpy - A helper library for easily displaying lines of text on a display.
  • neopixel.mpy - A CircuitPython driver for NeoPixel LEDs.
  • adafruit_display_text/ - A library to display text using displayio. Used for the text display functionality of the MacroPad library that allows you easily display lines of text on the built-in display.
  • adafruit_hid/ - CircuitPython USB HID drivers.
  • adafruit_midi/ - A CircuitPython helper for encoding/decoding MIDI packets over a MIDI or UART connection
  • adafruit_ticks.mpy - A helper to work with intervals and deadlines in milliseconds
  • adafruit_displayio_layout - A library that includes a grid layout helper. (Optional)

Example code

# Docs:
from adafruit_macropad import MacroPad
macropad = MacroPad() # Default rotation, usb port to top
# Optionally set rotation, 90, 180, 270, rotating counterclock
# macropad = MacroPad(rotation=90) # usb port to left
# Rotation will change which button is 0 as well as direction
# of the OLED display text! Giving more lines of text in other dir

# Open files
# exec(open('').read())

# Red LED
macropad.red_led = True

# NeoPixels
macropad.pixels.fill(0, 255, 0)
macropad.pixels[0] = (255, 0, 255)
macropad.pixels[11] = (0, 0, 255)
macropad.pixels.brightness = 0.5 # up to 1

# Rotary encoder and button
print(macropad.encoder) # Relative clicks from origin 0
print(macropad.encoder_switch)  # True or False

# Key buttons (poll for events)
event =
while event:
    event.key_number  # 0-11 from top left to bottom right but can be changed with rotation
    event.pressed  # True or False
    event.released  # True or False
    # Check if another is in the queue
    event =

# OLED display (4 lines x 21 characters in default rotation)
# The title is unchangeable and takes up the first line. Optional.
lines = macropad.display_text(title="My text") # First line
lines[0].text = 'testing1'  # Second line
lines[1].text = 'abcdeABCDEabcdeABCDEab'  # Third line
lines[2].text = '0123456789012345678901'  # Fourth line
lines[3].text = 'testing4'  # Fifth line barely shows # Only required the first time?

# Display image 128x64
# Save as Monochrome Bitmap or it will convert to black/white only (not grayscale))

# Speaker buzzer
macropad.start_tone(440)  # A

# Do nothing
while True:

Example as keyboard/mouse

See more keycodes at

macropad.keyboard.send(macropad.Keycode.A), macropad.Keycode.B)
# Press and hold the shifted '1' key to get '!' (exclamation mark)., Keycode.ONE)
# Release the ONE key and send another report.
# Press shifted '2' to get '@'.
# Release all keys.

Example as MIDI

import time
from adafruit_macropad import MacroPad
# Default midi channel if not provided is 1
macropad = MacroPad(rotation=90, midi_in_channel=1, midi_out_channel=1)

# Set a CC value
macropad.midi.send(macropad.ControlChange(7, 64))

# Note on and off (Velocity 0-127)
macropad.midi.send(macropad.NoteOn("G#2", 64))  # On
macropad.midi.send(macropad.NoteOff("G#2", 0))  # off

# whole chord
macropad.midi.send([macropad.NoteOn(44, 127),
                    macropad.NoteOn(48, 127),
                    macropad.NoteOn(51, 127)])
macropad.midi.send([macropad.NoteOff(44, 0),
                    macropad.NoteOff(48, 0),
                    macropad.NoteOff(51, 0)])

# Pitch bend (8192 (center) down to 0 up to 16383)

# Program change
macropad.midi.send(macropad.ProgramChange(63))  # Either note 0-127 or note like "C4". A4=69