From c56b4da44b94020a88e81ed1369629965ea4e2ea Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Mon, 2 Oct 2017 22:40:54 -0700 Subject: First pass at comments on the rest of the default sketch --- Model01-Firmware.ino | 70 ++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 16 deletions(-) (limited to 'Model01-Firmware.ino') diff --git a/Model01-Firmware.ino b/Model01-Firmware.ino index ff119cc..f2095b8 100644 --- a/Model01-Firmware.ino +++ b/Model01-Firmware.ino @@ -75,6 +75,45 @@ enum { MACRO_VERSION_INFO, +/** The Model 01's key layouts are defined as 'keymaps'. By default, there are three + * keymaps: The standard QWERTY keymap, the "Function layer" keymap and the "Numpad" + * keymap. + * + * Each keymap is defined as a list using the 'KEYMAP_STACKED' macro, built + * of first the left hand's layout, followed by the right hand's layout. + * + * Keymaps typically consist mostly of `Key_` definitions. There are many, many keys + * defined as part of the USB HID Keyboard specification. You can find the names + * (if not yet the explanations) for all the standard `Key_` defintions offered by + * Kaleidoscope in these files: + * https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_keyboard.h + * https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_consumerctl.h + * https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_sysctl.h + * https://github.com/keyboardio/Kaleidoscope/blob/master/src/key_defs_keymaps.h + * + * Additional things that should be documented here include + * using ___ to let keypresses fall through to the previously active layer + * using XXX to mark a keyswitch as 'blocked' on this layer + * using Key_Keymap_ keys to change the active keymap. + + +#define QWERTY_KEYMAP 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, \ + Key_Keymap1_Momentary, \ +\ + M(MACRO_ANY), Key_6, Key_7, Key_8, Key_9, Key_0, Key_KeypadNumLock, \ + 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, \ + Key_Keymap1_Momentary \ +) + + #define FUNCTION_KEYMAP KEYMAP_STACKED ( \ ___, Key_F1, Key_F2, Key_F3, Key_F4, Key_F5, XXX, \ Key_Tab, ___, Key_mouseUp, ___, Key_mouseBtnR, Key_mouseWarpEnd, Key_mouseWarpNE, \ @@ -92,7 +131,6 @@ ___ \ ) - #define NUMPAD_KEYMAP KEYMAP_STACKED (\ ___, ___, ___, ___, ___, ___, ___, \ ___, ___, ___, ___, ___, ___, ___, \ @@ -110,21 +148,17 @@ ___ \ Key_Keymap1_Momentary \ ) -#define QWERTY_KEYMAP 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, \ - Key_Keymap1_Momentary, \ -\ - M(MACRO_ANY), Key_6, Key_7, Key_8, Key_9, Key_0, Key_KeypadNumLock, \ - 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, \ - Key_Keymap1_Momentary \ -) + + +// The "keymaps" data structure is a list of the keymaps compiled into the firmware. +// The order of keymaps in the list is important, as the Key_Keymap# and Key_Keymap#_Momentary +// keys switch to key layers based on this list. +// +// Keymaps are "0-indexed" -- That is the first keymap is Keymap 0. The second one is Keymap 1. +// The third one is Keymap 2. + +// A key defined as 'Key_Keymap1_Momentary' will switch to FUNCTION_KEYMAP while held. +// Similarly, a key defined as 'Key_Keymap2' will switch to NUMPAD_KEYMAP when tapped. const Key keymaps[][ROWS][COLS] PROGMEM = { QWERTY_KEYMAP, @@ -132,6 +166,10 @@ const Key keymaps[][ROWS][COLS] PROGMEM = { NUMPAD_KEYMAP }; + +// Right now, the numpad implementation needs to be told which keymap is the numpad keymap. +// That requirement should go away in the future. + #define NUMPAD_KEYMAP_ID 2 -- cgit v1.2.3