CircuitPython hotkey MacroPad

What you’re building

Adafruit’s MacroPad Hotkeys project turns the 12-key RP2040 MacroPad into a USB automation controller with per-application profiles. CircuitPython reads profile files from /macros, uses the rotary encoder to switch profiles, updates OLED labels and per-key RGB colors, and sends keyboard, consumer-control, mouse, text, timing, tone, or audio actions when keys are pressed. The expected result is a desktop-connected keypad whose visible layout and shortcuts change for applications such as creative tools or operating-system tasks. It requires the MacroPad-specific CircuitPython build, the project bundle’s code.py and libraries, and a known-good USB data cable. macOS and Windows use different modifier keys, so their sample profiles are not interchangeable. Copying a newer bundle can overwrite customized macro files; preserve personal configurations before updates and keep only profiles intended for the host operating system.

Key steps

1. Enter the RP2040 bootloader by holding the encoder BOOT button while resetting, then copy the MacroPad CircuitPython UF2 to RPI-RP2.
2. Download and unpack the Adafruit project bundle, then copy its contents to the new CIRCUITPY drive.
3. Back up any existing custom profiles before replacing code.py, libraries, or the macros folder.
4. Remove irrelevant mac- or win-prefixed sample profiles and edit a remaining profile’s name, colors, labels, and action sequences.
5. Reconnect the MacroPad, rotate the encoder to select a profile, and test every key against the intended application.