Edit A Keymap

NOTE: If you don't have Arduino support installed yet, you should work through those instructions first. (Mac, Windows, Linux)

If you want to switch to another keyboard layout like Dvorak or Colemak, you should work through this page, and then look at this page.

Editing a keymap is core to what Kaleidoscope (the firmware that powers your keyboard) is about, and probably one of the first things to try. For this example, let's imagine you want to map ESCAPE to the PROG key in the default keymap, as the QWERTY G-ds intended.

Edit the keymap

1. Open the Arduino IDE. In the “File” menu, click on the “Examples” submenu. Scroll down to ‘Model01-Firmware’.

   There is a lot going on in this file. By all means, read through the code and the comments and get familiar with it if you like. Or you can just breeze past it for now and skip down to the keymaps:

2. Scroll down to this line:

   enum { PRIMARY, NUMPAD, FUNCTION }; // layers
   

   That's where the keymaps section begins. It tells you that there are three layers:

   • PRIMARY is the default, or zero layer
   • FUNCTION is layer 1
   • NUMPAD is layer 2

   The PRIMARY keymap itself is a little further down, and looks like this:

   #if defined (PRIMARY_KEYMAP_QWERTY)
     [PRIMARY] = 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)),
   

   It's a map of your keyboard's layout. The top block that starts with (___, and ends with ShiftToLayer(FUNCTION), is the left half of the keyboardio. that first ___, represents the PROG key. It is a transparent key in the keymap, free to be mapped to anything you like.

   At the end of the fourth row is Key_Escape, which corresponds to the ESC key on your keyboard. That means Key_Escape, is the keycode for the ESC key.

3. Replace ___, with Key_Escape, in the first row, so your keymap now looks like this:

   #if defined (PRIMARY_KEYMAP_QWERTY)
     [PRIMARY] = KEYMAP_STACKED
     (Key_Escape,   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)),
   

4. Save the file.

Build and upload the new firmware

1. Click on the right arrow in the sketch window menu bar then hold down the PROG key to compile and install. If you get an error, some systems seem to work better if you hold down the PROG key and then press the arrow. We aren't sure why some systems work better in different order yet, so try both and do whatever works better for you. :-)

2. Your keyboard's LED's will red flash across the board as the firmware is installed, and then the LED key will glow blue.

3. Now when you press the PROG key it will send an ESCAPE to your computer.

Alternatively you can trigger the firmware upload by typing make flash from the Model01-Firmware directory.

Please note, if you have already used Chrysalis, this won't work for you. Please see the explanation here