You can add or remove MACROPAD configurations for different applications just by moving files in or out of the CIRCUITPY/macros folder. At its simplest, you can collect existing configuration files and never need to edit anything.
Each of these files is really just a snippet of CircuitPython code. They can be modified with any text editor, and text files are easily shared, for example in the Adafruit Forums.
You could start by copying one of the examples in the macros folder. Give it a descriptive name…and, if you’ll be sharing this with others, consider mentioning right in the filename what system it’s for, since key sequences vary among platforms (e.g. COMMAND vs. CONTROL on Mac vs Windows).
Here’s one of the examples, mac-safari.py, for the Safari web browser on MacOS:
# SPDX-FileCopyrightText: 2021 Phillip Burgess for Adafruit Industries
#
# SPDX-License-Identifier: MIT
# MACROPAD Hotkeys example: Safari web browser for Mac
from adafruit_hid.keycode import Keycode # REQUIRED if using Keycode.* values
app = { # REQUIRED dict, must be named 'app'
'name' : 'Mac Safari', # Application name
'macros' : [ # List of button macros...
# COLOR LABEL KEY SEQUENCE
# 1st row ----------
(0x004000, '< Back', [Keycode.COMMAND, '[']),
(0x004000, 'Fwd >', [Keycode.COMMAND, ']']),
(0x400000, 'Up', [Keycode.SHIFT, ' ']), # Scroll up
# 2nd row ----------
(0x202000, '< Tab', [Keycode.CONTROL, Keycode.SHIFT, Keycode.TAB]),
(0x202000, 'Tab >', [Keycode.CONTROL, Keycode.TAB]),
(0x400000, 'Down', ' '), # Scroll down
# 3rd row ----------
(0x000040, 'Reload', [Keycode.COMMAND, 'r']),
(0x000040, 'Home', [Keycode.COMMAND, 'H']),
(0x000040, 'Private', [Keycode.COMMAND, 'N']),
# 4th row ----------
(0x000000, 'Ada', [Keycode.COMMAND, 'n', -Keycode.COMMAND,
'www.adafruit.com\n']), # Adafruit in new window
(0x800000, 'Digi', [Keycode.COMMAND, 'n', -Keycode.COMMAND,
'www.digikey.com\n']), # Digi-Key in new window
(0x101010, 'Hacks', [Keycode.COMMAND, 'n', -Keycode.COMMAND,
'www.hackaday.com\n']), # Hack-a-Day in new win
# Encoder button ---
(0x000000, '', [Keycode.COMMAND, 'w']) # Close window/tab
]
}
This is just a single Python dictionary (which must be named 'app' for the project code to find it) containing two keys: 'name' and 'macros'.
'name' is what’s shown across the top of MACROPAD’s display when turning the knob to switch settings. This must be a short string in quotes, no more than 20 characters, for example 'Safari'.
'macros' is a list [enclosed in square brackets] of tuples (each enclosed in parenthesis) — one for each of MACROPAD’s 12 keys, and optionally one more for the encoder button. These appear sequentially, first item for the top-left key, second for top-center, and so forth. The examples have some Python comments to explain what’s happening.
Each of these tuples contains three elements:
- A hexadecimal RGB color value for the corresponding LED. You may want to avoid bright values, as a whole keypad of these can be distracting. If you like, color-code related groups of keys, or theme whole applications so you can tell what’s active at a glance.
- A brief description, in quotes. This is what’s displayed on MACROPAD’s OLED screen. BRIEF is the operative word here, ideally six characters or less. You can sometimes sneak in a 7-character label if adjoining items are shorter.
- A key sequence, which can either be:
- A single character or a string, in quotes, if the key sequence is just regular keypresses (including SHIFT for uppercase characters).
- A list [enclosed in square brackets] of key code constants and quoted-strings, which will be issued in-order.
Most letters, numbers and symbols are best done as quoted strings…but for special navigation-type keys…arrows, COMMAND/CONTROL/OPTION, function keys and so forth…key constants are required. We can see a complete list of these by typing in the CircuitPython REPL:
>>> from adafruit_hid.keycode import Keycode >>> print(dir(Keycode)) ['__class__', '__module__', '__name__', '__qualname__', '__bases__', '__dict__', 'C', 'M', 'A', 'B', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'ONE', 'TWO', 'THREE', 'FOUR', 'FIVE', 'SIX', 'SEVEN', 'EIGHT', 'NINE', 'ZERO', 'ENTER', 'RETURN', 'ESCAPE', 'BACKSPACE', 'TAB', 'SPACEBAR', 'SPACE', 'MINUS', 'EQUALS', 'LEFT_BRACKET', 'RIGHT_BRACKET', 'BACKSLASH', 'POUND', 'SEMICOLON', 'QUOTE', 'GRAVE_ACCENT', 'COMMA', 'PERIOD', 'FORWARD_SLASH', 'CAPS_LOCK', 'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12', 'PRINT_SCREEN', 'SCROLL_LOCK', 'PAUSE', 'INSERT', 'HOME', 'PAGE_UP', 'DELETE', 'END', 'PAGE_DOWN', 'RIGHT_ARROW', 'LEFT_ARROW', 'DOWN_ARROW', 'UP_ARROW', 'KEYPAD_NUMLOCK', 'KEYPAD_FORWARD_SLASH', 'KEYPAD_ASTERISK', 'KEYPAD_MINUS', 'KEYPAD_PLUS', 'KEYPAD_ENTER', 'KEYPAD_ONE', 'KEYPAD_TWO', 'KEYPAD_THREE', 'KEYPAD_FOUR', 'KEYPAD_FIVE', 'KEYPAD_SIX', 'KEYPAD_SEVEN', 'KEYPAD_EIGHT', 'KEYPAD_NINE', 'KEYPAD_ZERO', 'KEYPAD_PERIOD', 'KEYPAD_BACKSLASH', 'APPLICATION', 'POWER', 'KEYPAD_EQUALS', 'F13', 'F14', 'F15', 'F16', 'F17', 'F18', 'F19', 'LEFT_CONTROL', 'CONTROL', 'LEFT_SHIFT', 'SHIFT', 'LEFT_ALT', 'ALT', 'OPTION', 'LEFT_GUI', 'GUI', 'WINDOWS', 'COMMAND', 'RIGHT_CONTROL', 'RIGHT_SHIFT', 'RIGHT_ALT', 'RIGHT_GUI', 'modifier_bit']
The Safari example was chosen because it demonstrates most permutations quite nicely…
The third key, “Up,” for example…in Safari, this is done with SHIFT+SPACE. There’s no such thing as an “uppercase space,” so we can’t just use a quoted string here. Keycode.SHIFT is a constant telling the code to press and hold the SHIFT key, and then the quoted space is issued. SHIFT is automatically released at the end of the sequence.
You can see other keys doing similar operations, sometimes with Keycode.COMMAND or sometimes multiple modifiers (“Previous Tab,” for example, is CONTROL+SHIFT+TAB).
The bottom three keys show how to press and release keys mid-sequence. Each of these opens a new window (COMMAND+n) and enters a URL. We want the COMMAND key released after pressing 'n', so the characters in the URL string type normally, not as a list of commands. A negative Keycode value is used to indicate “release this key now”: -Keycode.COMMAND in the example.
Instead of a Keycode or string, a floating-point number inserts a pause in the key-pressing sequence. The duration is in seconds, either whole or partial. For example:
[Keycode.CONTROL, 0.5, 'a', 1.0, 'b']
This would press (and keep held) the 'Control' key, pause one half second, type an “a,” pause one second, then type a “b” (Control is implicitly released at the end of the sequence). Even if pausing for whole seconds, the decimal must be included…this is how it distinguishes from Keycodes, which are integer values.
Though you could store passwords in there, this is strongly discouraged, since the CircuitPython code is not protected or secure. Anyone with access to your MACROPAD can read these files!
