Greetings. Jesse very kindly helped me sort out some confusion on how to install third-party plugins. I captured the lessons I took from that and would like to post it on the wiki. Before I do, however, I’d appreciate any feedback from the community. Could some points be clearer? Am I just wrong in places? Etc. I’ve tried to aim this at someone at roughly my level of understanding–comfortable on the command line, but not familiar with programming in C++. Also, a strong emphasis on the “Why?”, not just the “What?” Thank you for any feedback.
Glenn
Adding a third-party plugin
If you haven’t worked in a C-based language, you may find some of the directions provided to install a third-party plugin overly terse. Fortunately, it only takes a little knowledge to overcome that challenge. This section walks through installing a simple plugin, which should give you the knowledge you need. It tries to provide both specific steps and a conceptual overview.
To get started, follow the directions at https://github.com/keyboardio/Kaleidoscope/wiki/Install-Arduino to install Arduino onto your computer including installing the “Model01-Firmware” example as discussed on https://github.com/keyboardio/Kaleidoscope/wiki/Edit-A-Keymap. This is important because you need to know how to flash an Arduino sketch to the keyboard and because you want to be sure you have a working sketch you can revert to if need be.
As part of installing Arduino, you should have created a folder for Arduino “sketches”, which is just the name Arduino uses for code files. On a Mac, a typical location is $HOME/Documents/Arduino. The important thing is to let Arduino know where it is. For example, one might add the following to your .profile, .bashrc or .zshrc file:
SKETCHBOOK_DIR=$HOME/Documents/Arduino
export SKETCHBOOK_DIR
After setting up Arduino, you should find three folders in your SKETCHBOOK_DIR, “Hardware”, “libraries” and “Model01-Firmware.”
As a practical example, we’ll install the Kaleidoscope-LED-Fire plugin, which can found at https://github.com/kevinr/Kaleidoscope-LED-Fire. The directions in the “Using the plugin” section of the README file may seem mysterious to the naive, but will be clear once you know the various pieces are doing. So, let’s walk though that in some detail.
Begin by opening the terminal application of your choice and navigating to the “libraries” directory of the SKETCH_BOOK directory. Now clone the plugin by issuing the command
git clone https://github.com/kevinr/Kaleidoscope-LED-Fire
(If you haven’t had cause to use git before, this command simply copies the most recent version of the code in your current directory. If you subsequently want to get an updated version of the plugin, issue git pull from the Kaleidoscope-LED-Fire directory.)
Change directories into the Kaleidoscope-LED-Fire directory and look at what’s been created.
├── COPYING
├── Makefile
├── README.md
├── examples
│ ├── LED-Fire
│ │ └── LED-Fire.ino
│ ├── fire-effect-highlight-wasd.jpg
│ ├── fire-effect-keypress.gif
│ └── fire-effect.gif
├── library.properties
└── src
├── Kaleidoscope
│ ├── LED-Fire.cpp
│ └── LED-Fire.h
└── Kaleidoscope-LED-Fire.h
You can ignore most of this, but so you know, the “src” directory contains the code for the plugin, which will be compiled according to the directions in “Makefile”. “COPYING” details the licence under which the plugin was released and “library.properties” provides some metadata about the plugin (author, etc.).
You’re most interested in the “examples” directory. It contains some graphics files used by the README.md file, but your starting point is the “LED-Fire.ino” file within the “LED-Fire” directory. “.ino” is the suffix for Arduino source files.
Launch Arduino and open “LED-Fire.ino” via the File/Open menu. As you’ll see, the file has five sections.
It begins with a series of #include statements, each of which specifies a file to be included when this file is compiled. The first two, #include <Kaleidoscope.h> and #include <Kaleidoscope-LEDControl.h> reference basic code the Keyboardio needs to function. The interesting addition is #include <Kaleidoscope-LED-Fire.h>, which will in turn incorporate the code that makes the plugin work.
The second section, KEYMAPS(), provides a keymap, as described in the Keyboardio wiki. The [0] refers to layer zero, the primary keyboard layer.
The third section, KALEIDOSCOPE_INIT_PLUGINS(), specifies the Plugins to be used. Again, the first two LEDControl and LEDOff provide basic functionality, while FireEffect enables the LED-Fire plugin.
The fourth section, void setup(){}, takes care of setting up the keyboard. Kaleidoscope.setup(); sets up Kaleidoscope. FireEffect.activate();, well, activates the FireEffect plugin.
The last section, void loop(){}, includes Kaleidoscope.loop(); to start Kaleidoscope running. LED-Fire doesn’t add anything here.
For comparison, open “Model01-Firmware.ino”. Notice that it has the same sections as “LED-Fire.ino” file, just with much more included. So, if you flashed “LED-Fire.ino” to your keyboard, you would have a fully functional keyboard, although it would be very basic. It would have the LED-fire effect but lack most of the other features we’re used to.
In fact, go ahead and flash the “LED-Fire” sketch to your keyboard, just as you flashed the “Model01-Firmware” file before. To wit, click the right-pointing arrow which is second from the left at the top of the Arduino window while holding down the “Prog” button on your keyboard. You should see some messages as Arduino compiles the software and dancing lights on your keyboard as the code is flashed. Assuming all worked, you should now be able to press the LED key a few times until you reach the LED Fire effect. You may now pause for cup of tea or hot cocoa, as seems most appropriate given the cozy atmosphere created by your keyboard.
Of course, you’d like to have the LED fire effect along with all the other nice features enabled in the original Model01-Firmware file. Doing so is as easy as copying and pasting the relevant code from the “LED-Fire.ino” to “Model01-Firmware.ino” and then flashing the latter to your keyboard. Before doing so, you should probably put the original Model01-Firmware file under version control or just make a copy of it to work in.
Open both .ino files and go through section by section. Notice the first two #include statements in LED-Fire are already in Model01-Firmware, so you don’t need to copy them over. You only need to copy the #include <Kaleidoscope-LED-Fire.h> statement over. I chose to put it at the end of the #includes section with an informative comment line, but as long as you follow the order of the five sections, it doesn’t matter.
// Support for LED-Fire (https://github.com/kevinr/Kaleidoscope-LED-Fire)
#include <Kaleidoscope-LED-Fire.h>
The second section, KEYMAPS() is already much more complete in Model01-Firmware, so you don’t need to do anything with it (obviously, in some plugins, this is where the action will be).
Looking at the third section, KALEIDOSCOPE_INIT_PLUGINS(), you’ll see that the only unique line from “LED-Fire” is FireEffect. Again, copy it over to the end of the relevant section in “Model01-Firmware”. Two points to note. First, unlike the #include section, this section is delimited by parentheses, so be sure to stay inside them. Second, plugins need to be separated by commas, so you’ll need to add a comma after whatever is currently the last item in this section. All in all, this section now ends like this.
// The USBQuirks plugin lets you do some things with USB that we aren't
// comfortable - or able - to do automatically, but can be useful
// nevertheless. Such as toggling the key report protocol between Boot (used
// by BIOSes) and Report (NKRO).
USBQuirks,
//LED-Fire (https://github.com/keyboardio/Kaleidoscope/wiki/Edit-A-Keymap)
FireEffect
);
The fourth section, void setup(){}, is very similar. You just need to copy the FireEffect.activate(); line. Note that this section is delimited by braces, so be sure to stay within them. This section should now end something like this in “Model01-Firmware”:
FireEffect.activate();
There is nothing unique in the fifth section, void loop(){}, so no action is needed.
Close “LED-Fire”. Save “Model01-Firmware” and flash it to your keyboard. You should now have all the standard functionality and, somewhere in the cycle of LED effects, the LED-fire effect. Congratulations.
To summarise, you’ve done the following:
- Cloned a desired plug-in into the “libraries” directory of
SKETCHBOOK_DIR - Opened the example sketch (.ino file) which is hopefully included.
- (Optional) Flashed the example to your keyboard to ensure that it works and that you understand what it does.
- Compared each section of the example in turn with the corresponding section of the sketch you are using to run your keyboard (“Model01-Firmware” in our example). Copied over unique entries from the example sketch to the corresponding section of your working sketch.
- Saved your working sketch and flashed it to your keyboard.
With this background, you’ll hopefully find the “Using the plugin” section at https://github.com/kevinr/Kaleidoscope-LED-Fire much clearer. You should also be set to install almost any other plugin.