Make repetitive tasks and computer shortcuts even quicker with the use of a Macro Pad.

BUILD TIME: under 1 hour
DIFFICULTY RATING: Intermediate

We often find ourselves performing repetitive tasks when using our computer which could easily be automated. For example, when programming devices and writing articles, we take advantage of various shortcuts and simple commands which could easily be mapped to an external input device for easy use. These shortcuts are often found in advanced programs for streamers, programmers, designers, artists, and other enthusiast applications. The commands can often be hard to remember so having them available as dedicated buttons would increase productivity significantly.

We decided the best solution would be a macro pad which could easily be programmed to execute these simple repetitive keystrokes. We considered creating the device from scratch using individual switches and breakout boards soldered directly to a programmable controller device. This option would have provided us with the most customisation as we would fully control the design, however, it would also require strong soldering skills and result in a larger footprint.

We also didn’t want to go for a complete product like those offered by Elgato as they required proprietary software which restricted customisation and compatibility. These are quite expensive too.

This guided us towards the Keybow MINI (3-key) kit from Pimoroni which offered the customisation we desired with hot-swappable key switches, an extensive scripting language, along with the simplicity of a ready-made PCB.

^Starter kit from Altronics (Without header) Use P5410 40-way header if buying this Starter kit.

How it works

The Pimoroni Keybow MINI comes as a kit that we need to assemble. The kit includes the Keybow MINI board and plate, three mechanical switches, clear keycaps, acrylic baseplate, mounting hardware, and a 50cm Micro USB cable.

The Keybow MINI comes with clicky Kailh Speed Gold mechanical switches, however, as the PCB uses Kailh hot-swap switch sockets, we can easily swap these for any Cherry MX-compatible switch.

The Keybow MINI also includes three APA102 RGB LEDs that sit in the cavity underneath each key. This design allows them to shine up through the switch and into the keycap without adding extra space to the board.

These LEDs can be animated to show a custom user-defined pattern or sequence simply by uploading an image file to the device. We can also individually program the lighting for each key to react to our actions.

We will also need a Raspberry Pi Zero WH or another Raspberry Pi Zero model with a soldered 40-pin header so that we can attach the Keybow MINI. The Raspberry Pi Zero will require a microSD card to hold the Keybow OS. The Keybow OS is very lightweight and only requires a card with over 1 GB capacity, however, a class 10 rating is recommended for speed and reliability.

The Build:

The advantage of using a kit like the Pimoroni Keybow MINI is the quick assembly time while still offering options for customisation. The entire kit can be assembled in under 10 minutes which means we can get into programming and using it much quicker.

The first step in assembling the kit is preparing the main PCB board. Start by removing the protective film covering the four corners holes on the PCB, then screw in four metal standoffs into these holes on the underside of the PCB. These standoffs will be used to secure our Raspberry Pi Zero WH to the board when assembled.

To attach the Raspberry Pi Zero WH to the main PCB, align the 40 pin header ensuring all the pins are straight. Secure the two boards together until the four metal standoffs make contact with the holes on the Pi.

The next step in assembly is attaching the included acrylic backplate to the bottom of the Raspberry Pi Zero WH, which helps prevent electrical shorts to the board, and will also serve as a platform to attach some rubber feet.

The acrylic sheet comes with a protective film installed which needs to be removed before assembly. The sheet includes a cutout for the 40 pin header along with a protrusion to offer some protection for the microSD card.

Attach the acrylic sheet on the bottom of the Raspberry Pi Zero WH using the included screws, ensuring the 40 pin cutout, microSD card protrusion, and mounting holes are correctly positioned. The screws should be carefully screwed from the bottom into the board assembly, ensuring they do not get over-tightened as this may cause the acrylic to crack.

The acrylic sheet and screw heads have smooth surfaces, so to keep the keypad firmly in place on your desk, attach the included rubber feet to each corner of the acrylic sheet.

The main assembly is now complete and we can proceed to prepare the mechanical key switches, keycaps, and switch plate. The three mechanical switches need to be installed into the switch plate to position them correctly. Gently push the three switches into the switch plate, ensuring that the pins on the switches all remain in the same orientation so they can later be attached to the main assembly.

Next, install the three slim profile transparent keycaps onto the switches. Simply insert them onto the switch’s stem and press firmly. The orientation of the keycaps is not important as they feature a symmetrical design.

Join the two pieces together to form a completed mini macro pad. Do this by aligning the pins of the key switches with the sockets on the top of the PCB, then apply light pressure.

Software Installation

The Keybow MINI runs the custom Keybow firmware which has been specifically designed and optimised for the device. The Keybow OS is a RAM-disk-based operating system built upon a light version of Raspbian. The system can run Lua scripts to control the key bindings and lighting.

The software is fully open-source so anyone can customise the firmware to their specific needs. Download the latest stable Keybow OS release from the GitHub repository: https://github.com/pimoroni/keybow-firmware/releases

At the time of writing, the latest release is v0.0.4, so we downloaded the keybow-0.0.4.zip file.

To install Keybow OS, ensure the microSD card has been formatted using the SD Memory Card Formatter application. Download and run the SD Memory Card Formatter app from the SD Association to wipe all data off the card.

The SD Card Formatter can be downloaded here: https://www.sdcard.org/downloads/formatter/

Once installed, select the microSD card and choose Format.

Once the microSD card has been formatted, prepare the downloaded Keybow OS files. Unzip the keybow-0.0.4.zip file and navigate to the sdcard folder. Copy the files within this folder to the root directory of the microSD card.

The Keybow OS has now been installed onto the microSD card. Eject the card from your computer.

Set up the completed macro keypad by inserting the prepared microSD card into the Raspberry Pi Zero WH and attaching the included micro USB cable to the centre port. This centre USB port enables the keypad to communicate with our computer to send keystrokes.

The keypad will power up and boot once you attach it to your computer using the supplied USB cable. The Raspberry Pi Zero WH will boot shortly after and load the Keybow OS.

Note: It can take up to 15 seconds before the macro pad will be detected by your computer.

When the device has successfully booted, you will see the RGB lights showing a simple animation, cycling through blue, pink, and orange hues. This signifies that the keypad is working correctly and ready to proceed to macro configuration.

Macro Configuration

The Keybow OS comes with several example key layouts which are stored in the layouts folder on the microSD card. Unplug the macro keypad and remove the microSD card to access these examples or they can also be found on GitHub. The default.lua file is automatically loaded by the device when booted and acts as a simple three-key number pad.

The layouts folder contains examples for both the Keybow MINI, which we are using, and the full-size Keybow. You can use any of the examples with mini at the start of the file name by renaming them to default.lua on the microSD card, then powering up the keypad. The examples include media volume controls with mute, and playback controls which allow you to play/pause, previous, and skip any media playing on your computer.

These examples are great for getting started, however, to create customised macros, we need to learn how to program them. First, create a default.lua file in your favourite text editor. To begin the file we need to specify that the program is for the Keybow MINI by placing the following code:

require "keybow"
function setup()
    keybow.use_mini()
end

We can now map the three available switches on our Keybow MINI to any character to be sent to the computer. Define these links by first creating a function for when a key is pressed and setting the character to be sent to our computer. The following code will link the first key to send the number one to the computer:

function handle_minikey_00(pressed)
    keybow.set_key("0", pressed)
end

Repeat this for the other two keys which will give the following completed file. We can change the characters sent by simply updating this file.

To send special keys such as functions and arrows we can refer to their names in the keybow.lua file.

Code Example 1

require "keybow"
function setup()
    keybow.use_mini()
end
function handle_minikey_00(pressed)
    keybow.set_key("1", pressed)
end
function handle_minikey_01(pressed)
    keybow.set_key("2", pressed)
end
function handle_minikey_02(pressed)
    keybow.set_key("3", pressed)
end

This code will allow us to configure our macro keys to act as any keyboard key but if we want to set up advanced shortcuts we will need to combine multiple commands. Use the keybow.set_modifier command to hold a button that will allow us to access keyboard shortcuts. Update the default.lua file and replace the function for the first key with this:

Example Code 2

function handle_minikey_00(pressed)
    if pressed then
        keybow.set_modifier(keybow.LEFT_META, 
keybow.KEY_DOWN)
        keybow.tap_key("r", pressed)
        keybow.set_modifier(keybow.LEFT_META, 
keybow.KEY_UP)
    end
end

This will launch the command prompt on Windows or Mac by holding the command key and tapping the ‘r’ key. You could expand this by entering a command into the terminal and executing it with the keybow.text("") and keybow.tap_enter() options.

These commands allow us to script complex macros which we can use to automate whatever tasks we need. We can also take advantage of the ready-made snippets for Windows and Mac which include common commands that we can run. The win-snippets.lua file located in the snippets directory contains several functions which we can use to do things such as Windows search and app switching.

We will use the win_snippets.search() function to search for cat GIFs. The function accepts a single text argument which will be our search query. To use the command, include the win-snippets.lua file in the default.lua program by adding the following line:

require "snippets/win_snippets"

Next, call the function from any of the macro keys by adding the win_snippets.search(“cat gifs”) command to the program. This enables us to quickly create advanced macros without the need for duplicating code.

The final default.lua file will look like this once completed:

Code Example 3

require "snippets/win_snippets"
function setup()
    keybow.use_mini()
end
function handle_minikey_00(pressed)
    if pressed then
        win_snippets.search("cat gifs")
    end
end

This program will launch Windows search and search for “cat gifs” which will launch a new browser window with the results. This program can easily be modified to search for a different term or combined with other functions and commands for more advanced actions.

Lighting Configuration

The Keybow MINI will default to displaying the contents of default.png. The lights will update with each line in the image at a rate of 60 frames per second to create an animation. We can create custom lighting animations by creating a png file 3 pixels wide and as many pixels deep as we want frames in our animation. The three pixels across will each correlate to one RGB LED on the Keybow MINI. This approach works well when we want to display a static pattern or animation on the device, regardless of user input.

Use the same default.lua file that contains the key mappings and macros to configure reactive lighting. Update the file to disable default lighting and clear any lit LEDs. Include the following two commands in the setup function to achieve this:

keybow.auto_lights(false)
keybow.clear_lights()

Set the colour of any LED using the keybow.set_pixel() command which accepts four arguments for LED number and RGB index. We can set the three LEDs to be red, green, and blue with the following commands in the setup function.

keybow.set_pixel(0, 255, 0, 0)
keybow.set_pixel(1, 0, 255, 0)
keybow.set_pixel(2, 0, 0, 255)

These values can be tweaked to display any RGB colour value, however, the colours will not change as we only set them once during setup. We can move the code to set the LED colours to our key commands which will result in the keys lighting up when pressed. The following code shows an example of how this could be done for a single key:

Example Code 4

require "keybow"
function setup()
    keybow.use_mini()
    keybow.auto_lights(false)
    keybow.clear_lights()
    keybow.set_pixel(0, 255, 0, 0)
end
function handle_minikey_00(pressed)
    keybow.set_key("0", pressed)
    if pressed then
        keybow.set_pixel(0, 0, 255, 0)
    else
        keybow.set_pixel(0, 255, 0, 0)
    end
end

Where to from here?

These examples show the many possibilities you can create using the Keybow MINI and lua scripting language. The Keybow OS firmware contains various other examples and snippets which you can use to create your own macros.