Installing Plugins

There are different requirements for installing plugins depending on whether or not they are part of the Kaleidoscope core or not.

Core plugins are all included in the software that's installed as part of the Arduino IDE support. Using those involves turning them on and configuring them. The Kaleidoscope team maintains and supports these plugins, so we are pretty sure they will work as advertised and if they don't we will fix them. We manage this code to make sure the things we want are in it, and nothing we don't want slips in. Of course we're not perfect, but our guarantee to you is that we'll support it and make it as easy as possible for you to use.

Third party plugins are being written and shared by people in the community. Many of these are wonderful, they just take a little more effort to install. The process is straightforward-- you will need to download the files and install them in the correct directory before you can turn them on and configure them.

NOTE: Consider the source before installing software on your computer. For example, while there are many reasons you might be interested in logging your keypresses to, for instance, analyze your keystrokes to optimize your layout, you don't want to have someone else looking at every character you type. It would be entirely possible for a malicious person to install a keylogger on your computer disguised as a useful tool that would send every click off to somewhere on the internet without you knowing. We have a good team managing the core plugins, but we have no control of anything other people may write. If you have a question about something you want to install, please ask on the forums.

Installing core plugins

(Coming soon)

Installing third party plugins

Thanks to @cdisselkoen for the following writeup for his plugin MacrosOnTheFly

1. Find your plugin directory. This is wherever you normally put plugins; it should be $SKETCHBOOK_DIR/hardware/keyboardio/avr/libraries, or at least accessible from there via symlink. (If you don't know what a symlink is, don't worry - just use the libraries directory directly.) $SKETCHBOOK_DIR is your Arduino sketchbook directory, perhaps $HOME/Arduino or $HOME/Documents/Arduino.
2. Install this plugin into your plugin directory using one of the below options.

• (Option 1 - using Git) Clone this Git repo into your plugin directory. This can be done from the command line - just navigate to your plugin directory and type git clone https://github.com/cdisselkoen/Kaleidoscope-MacrosOnTheFly.
• (Option 2 - no Git or command-line required) Click the green "Clone or download" button at the top right of this page, and select "Download ZIP". Then, unzip the folder in your plugin directory.

You're done! It was that easy.

Adding the plugin to your sketch

To activate the plugin, one needs to include the header, tell Kaleidoscope to use the plugin, and place the Key_MacroRec and Key_MacroPlay keys on the keymap.

In general, this plugin desires to be as early as possible in the Kaleidoscope.use() order, so that it can catch all keypresses before other plugins try to handle them. There may be exceptions.

Setup operations in the firmware sketch (example):

#include <Kaleidoscope.h>
#include <Kaleidoscope-MacrosOnTheFly.h>

void setup (){
  Kaleidoscope.use(&MacrosOnTheFly);
  Kaleidoscope.setup();
}

Keymap markup

Somewhere on the keymap, you should place the special keys Key_MacroRec and Key_MacroPlay, which are used for macro recording and playback respectively. Note these keys can be on any layer or on different layers - they could even be the same key on different layers.

Starting from a layout reasonably close to the default Model 01 QWERTY layout, some suggestions for places to put these keys are:

• the pgup and pgdn keys
• the enter key (if like me you use Fn-Space or some other key as 'enter')
• the tab key (if like me you've remapped it somewhere else)
• Fn-q (if you like similarity to Vim)
• Fn-; or Fn-' (both empty in the default firmware)
• the any key
• the prog key
• the butterfly key