Macropad Hotkeys II

A rebuild of the Macropad Hotkeys example from the Adafruit Learning System Guide.

Modifications

• A number of sample macros for things such as Blender, a MIDI drum kit, DaVinici Resolve, and more
• Sleep the display and LEDs to avoid burn-in
• Support for HID consumer control codes
• Support for mouse buttons & mouse wheel
• Support for sending MIDI notes
• When no HID connection is present (power only), keep LEDs off and provide a message
• Stop your OS from shouting when you unplug the Macropad - don't mount as USB storage unless the KEY1 button is pressed on boot
• Refactored the code to make it (maybe) easier to modify

Demo

Using

You use the Macropad Hotkeys in a similar way to the original Adafruit version, with several improvements.

At first install you don't have any macros installed - however several examples are provided in the macros/examples directory. The Macropad Hotkeys II Wiki has a number of additional templates you can customize for things like DaVinci Resolve or Baldur's Gate III. See Configuration for details.

Once you have some macros installed, push down & rotate the dial to select the macro template you would like to use; the macros appear in the order specified within each config file. Once you have the macro you like selected, you are free to hammer away at the keys.

Configuration

The macros/examples/ folder has template macro pages to start from, or you can view some read-made macro pages in the Macropad Hotkeys II Wiki.

To add a new macro page, first make sure to mount your Macropad in read/write mode (see Updating) and then copy a .py example in the macros/ folder. Note that each has a list of settings, including:

• The name that will show at the top of the OLED display
• The sequential order that it will be shown when rotating the encoder dial
• An optional timeout before the LEDs and display go to sleep
• A macro to launch when switching to this screen
• A list of macros, sorted by row
• A list of macros for the rotary encoder

Each macro consists of an LED color, a label to appear on the OLED display, and a sequence of keys. A "key" can be text, a keyboard key, a consumer control key (like play/pause), a mouse action, or a MIDI note. More than one key can be specified in a sequence.

The example in macros/examples/minimal.py is a good starter for your own custom macro. From this example you can see the triplets which specify color, label, and commands and visualize the key layout for the configuration.

Note the "launch" setting is a macro that will run when you switch to a given screen. It does not run when the macropad first starts, but it will once you switch from another screen. See macros/examples/example.py for an example of all configuration options.

Configuration Options

Each macro screen has optional attributes you can define, including: * name: The name of the page to show on screen * order: The sequence in which this screen will appear when flipping through macros (defaults to 0) * timeout': Number of seconds before the screen and LEDs turn off (default 300 seconds) * powersave': Go into a "low power" mode after timeout - this means keys don't immediately respond when waking up (defaults to True) * launch': Macro to fire off when first loading this macro page (defaults to no macro launched)

Installing

First make sure that your Macropad has the latest version of CircuitPython 10.0 installed. See https://learn.adafruit.com/adafruit-macropad-rp2040/circuitpython for instructions on how to update the Macropad to have the latest version of CircuitPython.

When installing Macropad Hotkeys for the first time, extract the latest MacroPad Hotkeys.zip into a directory, then copy the contents of that extracted archive into the CIRCUITPY drive that appears when you plug in your Macropad. Ensure that the contents of the lib/ subdirectory are also copied - these are the precompiled Adafruit libraries that power the Macropad.

You can also install some initial macros to get started. Copy any of the .py files from the macros/examples directory into macros/ to start with a pre-built example. Modify the examples to change LED colors, label text, or key/mouse/control macros as needed. You can also copy-and-paste macros listed in the Macropad Hotkeys II Wiki then tweak as needed.

Updating

After you first install this version of Macropad Hotkeys and reboot the Macropad, the CIRCUITPY filesystem will not be mounted. In this mode Windows and MacOS won't complain if you unplug or reboot the device without unmounting it, making it act like a regular old HID device.

To update or edit the code on the device, or to modify the macros, you first need to reboot the device with the CIRCUITPY drive mounted in read/write mode. To do that, reboot the device using the boot switch on the left of the Macropad, and then after releasing the button immediately hold down the blinking top-left key on the keypad (KEY1). You should see the text "Mounting Read/Write" quickly appear on the screen, and then the CIRCUITPY drive will mount in read/write mode.

Building

I've attempted to build mocks of all necessary libraries so things can be tested locally.

Running tests

Tests can be run with the native Python unittest module, as in:

python3 -m unittest discover