Using macros and snippets with Keybow

The real power of Keybow is in its ability to become a macro keyboard, triggering a whole series of keypresses from just a single key, for example "control-alt-delete" or typing "The quick brown fox jumps over the lazy dog". This is great for setting up actions that you can never quite remember, like the shortcut to import photos to Lightroom (command/control-shift-I), by just linking them to a single key.

You could also create a Keybow layout that stored all your frequently-used bits of text, like code snippets, email templates, or even complex sets of actions like opening a web browser, then entering an URL or search term and hitting enter. The world is your lobster!

As well as these custom actions, we've put together a couple of files full of handy snippets for Windows and Mac; these are common actions like peeking the desktop, snapping windows to one side or the other, a Spotlight search on Mac, and lots more. You can link these straight to keypresses in your layout files.

We'll assume that you've followed the first two Keybow tutorials already, but if you haven't then go back over them before this one:

Creating a simple macro

We'll create a simple Windows-R (opens the run menu on Windows; if you're on Mac then these keys will refresh your browser page) macro as an example of how to put them together, and how to use modifier keys and the tap key function.

Unplug the USB cable from your Keybow and pop the micro-SD card out and put it in your computer. In the the layouts folder, create a new layout called macros.lua and add the following to it:

require "keybow"

function handle_key_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

Let's break down what the code does.

The macro is bound to key 0, that is the bottom left key when Keybow is in portrait orientation with the USB cable at the right hand side.

We're running this macro when the key is pressed (as opposed to when it's released), hence the if pressed then.

The line keybow.set_modifier(keybow.LEFT_META, keybow.KEY_DOWN) uses the set_modifier function that allows you to keep a modifier key held down while you press another key or keys, and tells Keybow to keep the key held down - keybow.KEY_DOWN. keybow.LEFT_META represents the Windows key on Windows or the command key on Mac.

Next, we use the tap_key function, which simulates a quick press and release of a key, to tap the "r" key - keybow.tap_key("r", pressed).

Last of all, we use the set_modifier function again to release the keybow.LEFT_META (Windows) key - keybow.set_modifier(keybow.LEFT_META, keybow.KEY_UP), before closing both the if statement and the handle_key function with end.

Save your new macros.lua file in the layouts folder, and then open the keys.lua file and link and enable your new layout. The file should look something like this:

```lua
require "keybow"

-- require "layouts/default" -- Numberpad

-- Custom layouts (uncomment to enable) --

-- require "layouts/boilerplate" -- Handy bits of boilerplate text like Lorem Ipsum
-- require "layouts/lightroom" -- Handy hotkeys for Adobe Lightroom Classic CC
-- require "layouts/pico8" -- Controls for Pico-8

require "layouts/macros" -- Macros layout

Save the keys.lua filem, eject and pop the micro-SD card out and into your Keybow, then plug it in with its USB cable. Once booted, give your new macro a try!

Entering strings of text

Entering strings of text can be really handy. It might be a snippet of text that you use frequently, like an address or some Lorem Ipsum placeholder text, or it could be a search term that gets entered once you've opened your web browser with a macro.

Here, we'll extend our Windows-R run menu macro that we made and type "cmd" to open the command prompt, and then tap enter to open it. We'll also use the keybow.sleep() function to introduce a couple of short pauses between the parts of the macro.

Disconnect your Keybow, remove the micro-SD card again, and pop it into your computer. Open the macros.lua file.

Within the handle_key_00 function that we added our macro to, add a keybow.sleep(500) straight after the keybow.set_modifier(keybow.LEFT_META, keybow.KEY_UP) line. This will introduce a half-second (500 milliseconds) pause before the next line in our macro.

Next, we'll use the keybow.text() function to type our "cmd" text. Add the line keybow.text("cmd") below the keybow.sleep(500) line.

You can use the keybow.text() function with any of the text characters on your keyboard, including shifted characters (uppercase letters, !, @, £, etc.), and also spaces, and even tabs and new lines with \t and \n respectively.

Add another keybow.sleep(500) below that last line to introduce another small pause.

Last of all, we'll add the line keybow.tap_enter() to tap the enter key. There are keybow.tap_ functions for several of the most commonly used keys like enter, space, and tab, as well as the tap_key() function that we used earlier, to which you can pass any key to tap it. You can see them all towards the bottom of the keybow.lua file.

Your whole macros.lua file should now look like this:

require "keybow"

function handle_key_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)
        keybow.sleep(500)
        keybow.text("cmd")
        keybow.sleep(500)
        keybow.tap_enter()
    end
end

Save that file, eject the micro-SD card, and pop it into your Keybow. Does the macro work, and open the command prompt?

If you're using a Mac, then you can change this macro example to hold command, tap space, and then type something like "chrome" to open Google Chrome.

Using the ready-made snippets for Windows and Mac

We've included a folder called snippets with two files in, windows_snippets and mac_snippets. These files have a whole bunch of ready made functions - hotkeys and macros - that you can use directly in your layouts. They cover basic things like switching between app windows, snapping windows, opening spotlight or Windows search, and a lot more.

We'll put together an example that uses a couple of the Mac snippets to do something that you probably do several times a day, but now you can do it with just a single keypress - search for cat GIFs!

Let's add this new macro to our 'macros.lua' file that we've been using, and assign it to key 1 (the middle bottom key). Think about the steps involved in doing our cat gifs search. We have to:

  1. Open Spotlight
  2. Get Spotlight to open Safari
  3. Focus on the smart search field
  4. Type in "cat gifs" and press enter

Luckily, there are snippets we can use to do the trickier steps of a Spotlight search and the Safari search, so it's just a case of adding two lines rather than a whole bunch.

Disconnect your Keybow, remove the micro-SD card, and pop it into your computer. Open the macros.lua file.

At the top of the file, just below the require "keybow" line, add require "snippets/mac_snippets". This will let us use functions from the mac_snippets.lua file in the snippets folder.

Create a new handle_key function at the bottom of your macros file, that looks like this:

function handle_key_01(pressed)
    if pressed then
        mac_snippets.spotlight("safari")
        mac_snippets.safari_search("cat gifs")
    end
end

Remarkably easy, huh? The spotlight and safari_search snippets take a string as input and handle the other parts of the process, i.e. the keyboard shortcut, entering the text, and then pressing enter.

Your whole macros.lua file should now look like this:

require "keybow"
require "snippets/mac_snippets"

function handle_key_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)
        keybow.sleep(500)
        keybow.text("cmd")
        keybow.sleep(500)
        keybow.tap_enter()
    end
end

function handle_key_01(pressed)
    if pressed then
        mac_snippets.spotlight("safari")
        mac_snippets.safari_search("cat gifs")
    end
end

Eject the micro-SD card, put it into your Keybow, then plug it into your computer. Press key 1 and... SHAZAM... cat GIFs!

Take a look though the windows_snippets and mac_snippets files in the snippets folder to see all of the functionality included, everything from general navigation shortcuts, to screenshots, to specific app shortcuts for Safari, Chrome, and email.

Shopping basket

Need something for this project? You can use the links below to add products to your Pimoroni Shop basket for easy checkout.

Keybow Mini Mechanical Keyboard Kit
Linear (quiet) keys £49.98
Keybow Mini Mechanical Keyboard Kit
Clicky keys £49.98
Want to checkout or change something? Click here to view your cart.

Tutorial
Advanced
Raspberry Pi, Pi Zero

Sandy Macdonald

sandy@pimoroni.com
@sandyjmacdonald
http://sandyjmacdonald.github.io
Formerly, Sandy worked at the University of York, in the biology department, analysing data and telling people that they should have used more replicates. Now a fully-fledged crew member at Pimoroni - head of digital content - working on learning materials and digital chunterings. Find him on Twitter and most everywhere else, as sandyjmacdonald.