Macros and Plugins

Both macros and plugins are code that extend functionality. The difference is that macros are added directly to the .ino file, and plugins are called as libraries and stored as separate files. Often, plugins are much longer than macros, although some plugins are short. A number of third-party macros and plugins are available, and both are discussed and improved on the Keyboardio forum [6]. In installing third-party macros and plugins, you can learn the rudiments of writing your own customizations.

The exact instructions for installing either may differ in detail. For instance, some macros may need to be added before others. However, most follow the same general rules [7]. A typical example is included by default in the firmware, the Any key macro, which produces a random character and is assigned to the Any key. Using the macro requires three pieces in the firmware:

1. Add the macro code and accompanying comments after the keymaps for each layer in the .ino file. Follow the comments to find the proper place.

2. Search for the listing of macros and add the name of each macro, one per line so that they can be easily read; for example:

   enum { MACRO_VERSION_INFO,
          MACRO_ANY
   };

3. Map the name of the macro to a key; for example, M(MACRO_ANY). The M signals that a macro is called, and the text inside the parentheses is the name of the macro.

Installing plugins requires a different general procedure [8]:

1. Add the code to:

   $HOME/Arduino/hardware/keyboardio/ avr/libraries/

         The simplest way to add the code is to change to this directory and then use git clone, specifying the URL to the code.

1. Add calls for the plugin near the top of the firmware file. For example, for Kaleidoscope-MacrosOnTheFly, add:

   #include <Kaleidoscope.h>
   #include <Kaleidoscope-MacrosOnTheFly.h>
   void setup (){
     Kaleidoscope.use(&MacrosOnTheFly);
     Kaleidoscope.setup();

2. Assign the names specified in its code to a key. For example, Kaleidoscope-MacrosOnTheFly requires two assigned keys: Key_MacroRec for recording macros and Key_MacroPlay to playback macros. Many plugins require only one key assignment.

Two third-party plugins that are especially useful if you want to add more than a few macros are Kaleidoscope-MacrosOnTheFly, which not only creates macros by recording keystrokes, but also allows each key to be assigned a macro, and Kaleidoscope-OneShot, which turns any key into a command key. With these tools, your customizations are limited only by your imagination and the Model 01's memory.

Flashing the Firmware

You can add your changes to the keyboard in two ways. At the command line, change to the directory containing the modified .ino file and enter the command make flash. When prompted, keep pressing the Prog key while pressing Enter. Do not release the Prog key until the process is completed. Then, unplug the keyboard and reconnect it to start the keyboard with the revised firmware. Alternatively, from the Arduino IDE, select the modified .ino file and click the Upload button while pressing the Prog key.

In both cases, do not release the Prog key until the process is completed. When the flashing is happening, the left half of the keyboard will have a red spark flash across the keys to show that the process is happening. Then, unplug the keyboard and reconnect it to start the keyboard with the revised firmware.

Should you run into trouble – for example, if you assign a command or character to the Prog key on the default layer – disconnect the keyboard and restart it while holding down the Prog key to revert to the original firmware. The left-hand circuit board has a reset button, although using it requires unscrewing the enclosure to find it. Using either one will allow you to flash another version of the firmware.

At some point, a graphical interface will be completed for simple remappings of the keys and the creation of layers, but for now, programming the Model 01 is strictly a command-line process. The bonus is that, by confronting the code head-on, you can add more complex customizations and learn how to work with other Arduino-driven devices.