Keyboardio Model 01 Introduction

Welcome to your Keyboardio Model 01!

The Model 01 was built for uncompromising typists like you—those who love to experiment, create, perfect, and share inspiration. It was designed to be configured and extended by people just like you. What makes that possible is the hardware platform, which is built around an Arduino, and the firmware, called Kaleidoscope, which has been built to be both accessible to novices and powerful enough to please even the most demanding keyboard hackers. There are already dozens of plugins and LED effects being created by talented folks who are refining their keyboarding experience, and sharing their work with the rest of us.

In our community forum you will find both experienced folks and folks new to programming. Your questions and triumphs will be welcomed and celebrated. This is a great first-stop for any issues or questions you may have when customizing your keyboard. We are happy to help you get your keyboard exactly the way you want it, and most likely there are improvements to your keyboarding experience that you have never even dreamed were possible. You can find the community here:

https://community.keyboard.io/

About this guide

The how-to section of this guide is intended for folks who are new to Arduino programming or perhaps to programming in general, and who want a quick tutorial on how to get started customizing the Model 01. We will give you some background on keyboards in general, an introduction to how the Kaleidoscope firmware works, and some details about the Keyboardio Model 01 in specific. Then we will take you through setting up the Arduino customization tools on your computer, and finally walk you through making simple changes to your keyboard's firmware.

After you have worked through this process you will be able to modify the definitions of the keys on your Model 01, enabling you to do tasks such as switching layouts, swapping thumb-key placement, and customizing your LED pattern effects.

We hope this guide will be a helpful first step in customizing your keyboard.

If you're already familiar with Arduino and/or prefer to work on the command line of your computer we encourage you to read through this page to familiarize yourself with how the system works, and then instead of following the tutorial steps in the setup guides, look at the readme in the Model 01 git repository. If the following commands are familiar territory for you then the setup guides may be more of a reference for you:

## Create the destination directory...
mkdir -p hardware/keyboardio

## ..then clone the hardware definitions to make them available to
## the arduino environment:
git clone --recursive https://github.com/keyboardio/Kaleidoscope-Bundle-Keyboardio.git \
    hardware/keyboardio

For our more tech-savvy users, it's probably still worth reading through this wiki page to get a sense for the architecture of the firmware, and you may wish to reference the keycode definitions. We hope you come up with new ideas for customizing Kaleidoscope, and let us know about them!

Kaleidoscope Firmware Overview

Keyboards work by receiving your keypresses and translating them into "keycodes." Those keycodes are passed to your computer's operating system, which can interpret them and turn into characters and control codes. Those characters and codes are passed on to the active application on your computer. Some examples:

• Press the A key while editing a document, and "a" will be inserted where your cursor is currently positioned.

• Hold down SHIFT and press the A key while editing a document, and "A" will be inserted where your cursor is currently positioned.

• Press the PGUP key, and the cursor will move up a page in the document.

In order to change what happens when you press a key on your keyboard, you will need to edit the firmware configuration file to change the keycode that specific key sends to your computer's operating system when you press it. To put it a bit more succinctly, you will edit a keymap. By having this logic on your keyboard itself, you can bring your customizations with you to any machine you use with your keyboard.

NOTE: There's a reference to all the available keycodes here: keycode definitions

Keymaps

Keymaps are the way Kaleidoscope defines what happens when a key is pressed. They are defined in .ino files that are used as configuration files when you build your firmware. They are a block of comma-separated values, one value for each key location on the keyboard. For instance, the QWERTY map looks like this:

  [QWERTY] = KEYMAP_STACKED
  (___,          Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext,
   Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab,
   Key_PageUp,   Key_A, Key_S, Key_D, Key_F, Key_G,
   Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape,
   Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift,
   ShiftToLayer(FUNCTION),

   M(MACRO_ANY),  Key_6, Key_7, Key_8,     Key_9,         Key_0,         LockLayer(NUMPAD),
   Key_Enter,     Key_Y, Key_U, Key_I,     Key_O,         Key_P,         Key_Equals,
                  Key_H, Key_J, Key_K,     Key_L,         Key_Semicolon, Key_Quote,
   Key_RightAlt,  Key_N, Key_M, Key_Comma, Key_Period,    Key_Slash,     Key_Minus,
   Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl,
   ShiftToLayer(FUNCTION)),

Comparing the keymap to your keyboard, it maps the rows and columns of its first and second sections to the rows and columns of the left and right halves of your Model 01.

There are a number of ways a location in the keymap can be defined:

1. Most locations will simply be defined as keys, and will appear as Key_ followed by the character being referenced, such as Key_A or Key_DownArrow. Most of these are pretty self explanatory.

2. Some locations, such as the "fn" key in the default map, will be used to turn a layer on while depressed. These are defined with a command called ShiftToLayer(), for instance ShiftToLayer(FUNCTION).

3. Others get defined as layers which are switched on and switched off with a function called LockLayer() and work like the NUMPAD layer: tap the key to turn it on, then tap again to turn it off. (In the default config, though, the "NUM" key looks like a normal key: Key_KeypadNumLock, but is managed in the background by a plugin that turns on the layer with LockLayer(NUMPAD), and at the same time makes the LED's change color. Let's pretend it's doing that out in the open where you could see it. :-)

4. Transparent keys are defined as ___, which is three underscore characters in a row. When the firmware is running it looks down through the active stack of keymap layers (ignoring any that are inactive) and sends the operating system the keycode associated with the highest active layer. If the firmware finds a ___ in a map location it will drop to the next layer down, and then the next one, until it finds something. If a given map location is transparent on every layer, like for instance the "prog" key in the default map, the firmware will ignore the keypress.

5. XXX is used to block the firmware from dropping down to check other layers. If it finds XXX in a location it will also ignore the keypress without checking lower layers.

6. Macros and plugins can also be called in the config file. The ANY key in the default config file is a macro: M(MACRO_ANY). It's defined a few lines below the keymaps:

   static void anyKeyMacro(uint8_t keyState) {
     static Key lastKey;
     if (keyToggledOn(keyState))
       lastKey.keyCode = Key_A.keyCode + (uint8_t)(millis() % 36);
   
     if (keyIsPressed(keyState))
       kaleidoscope::hid::pressKey(lastKey);
   }
   

7. Kaleidoscope also supports arbitrary keys being used in the keymap and defined by plugins. I already mentioned Key_KeypadNumLock, and the "led" key works the same way. It looks like a regular key in the keymap-- Key_LEDEffectNext, but that Key_ is defined under the covers to do something special. If you look at the top of the configuration file you will see where the firmware is told to include support for both of these:

   // Support for controlling the keyboard's LEDs
   #include "Kaleidoscope-LEDControl.h"
   
   // Support for "Numlock" mode, which is mostly just the Numlock specific LED mode
       #include "Kaleidoscope-Numlock.h"
       ```

8. At other times a plugin may add functions that can be used in a keymap. There aren't examples of this in the default config, but the plugin OneShot is a fan favorite. You can read more about it here and find it in the firmware repository here if you want to try it out.

The Model 01 ships with three keymaps installed: QWERTY, FUNCTION, and NUMPAD. The laminated sheet that came with your keyboard shows the QWERTY layer in black, the FUNCTION layer in blue, and the NUMPAD layer in red. The back side of the sheet has a blank layout you can write on with a grease pencil or a whiteboard marker to represent a changed layout.

The default layer is numbered zero, and the zero-layer that ships on the Model 01 is called "QWERTY".

NOTE: If you want to use a different layout, such as Dvorak or Colemak, you will find those keymaps here.

Next, Layer 1 is FUNCTION, and Layer 2 is NUMPAD. The FUNCTION layer is activated when one of the FN palm keys is held down. NUMPAD gets toggled on and off with the NUM key in the upper right of the right half of the Model 01.

Imagine the default layer as the base of a stack, and the higher layers as overlays. Keys on the upper layers can be transparent, in which case the default layer "shines through." For example: if NUMPAD is toggled on, all the keys on the left half of the keymap (and some keys on the right side) are transparent. If you press a key on the left half, the keycode corresponding to that key on the QWERTY map will be generated, unless you are also holding down function, in which case you'll send the relevant keycode from the FUNCTION keymap.

The layer numbers are defined in the config, so in the default firmware NUMPAD overlays both QWERTY and FUNCTION. However, turning on higher layers doesn't turn on the ones below them. Each layer gets turned on and off independently. In the example above, when NUMPAD is active, the left side of the keyboard (and all the transparent keys on the right side as well) will send their QWERTY definitions by default, and their FUNCTION definitions when the FN key is held down.

Layers can be locked on, like the NUMPAD, so that their activating key acts like a switch that turns them on when initially pressed, and then off again when pressed again. Layers can also be shifted to, as the FUNCTION layer works. In that case the layer is active if the activating key is held down, and inactive when it's released.

Plugins, Macros, and LED effects

In addition to customizing your keymap you can also add plugins, macros, and LED effects. There are a nice selection of plugins and effects included in the default firmware, as well as the ANY key macro to get you started.

In general, macros are small bits of code that will be added directly into the configuration file, like the macro for the "any" key shown above. Plugins are more complicated code contained in a seperate file or files, and referenced as libraries in the config file like the Kaleidoscope-LEDControl.h and Kaleidoscope-Numlock.h plugins. LED effects are also plugins, they just operate on the LED's instead of affecting what codes the keyboard sends the computer.

This is the area in which most of the community contributions are being made. People are making some wonderful things you can download and install. The process for installing the third party contributions is a little more complicated than just turning on and configuring the included ones, but it's not too difficult, and there are plenty of folks in the community to help if you get stuck.

Commonly Re-mapped Keys

The ANY key and BUTTERFLY key were intentionally left without important "jobs" in the layout, leaving convenient "empty" positions on the physical keyboard to play with. (By default, the ANY key will generate a random alphanumeric keypress and the BUTTERFLY key will generate a Right-Alt keypress. In Europe, this key is often labeled 'AltGr'.)

While most of the Model 01's keys are individually sculpted, the eight thumb keycaps have the same shape so you can can rearrange them to match . means you can rearrange the locations of these keys in the firmware and physically!

As you're getting familiar with your keyboard, you may have noticed the PROG key. As a security feature, your keyboard checks to make sure you're holding this key down when it detects an attempt to update its firmware. Out of the box, PROG has no "regular" function.

Next step: Install Arduino support:

• Mac
• Linux
• Windows