diff --git a/Model01-Firmware.ino b/Model01-Firmware.ino index 6a008e11..b6e50344 100644 --- a/Model01-Firmware.ino +++ b/Model01-Firmware.ino @@ -90,193 +90,11 @@ 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 ShiftToLayer() and LockLayer() keys to change the active keymap. - * keeping NUM and FN consistent and accessible on all layers - * - * The PROG key is special, since it is how you indicate to the board that you - * want to flash the firmware. However, it can be remapped to a regular key. - * When the keyboard boots, it first looks to see whether the PROG key is held - * down; if it is, it simply awaits further flashing instructions. If it is - * not, it continues loading the rest of the firmware and the keyboard - * functions normally, with whatever binding you have set to PROG. More detail - * here: https://community.keyboard.io/t/how-the-prog-key-gets-you-into-the-bootloader/506/8 - * - * 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 ShiftToLayer(#) and LockLayer(#) - * macros switch to key layers based on this list. - * - * - - * A key defined as 'ShiftToLayer(FUNCTION)' will switch to FUNCTION while held. - * Similarly, a key defined as 'LockLayer(NUMPAD)' will switch to NUMPAD when tapped. - */ - /** - * Layers are "0-indexed" -- That is the first one is layer 0. The second one is layer 1. - * The third one is layer 2. - * This 'enum' lets us use names like QWERTY, FUNCTION, and NUMPAD in place of - * the numbers 0, 1 and 2. - * + * Keymaps are defined in a separate file */ +#include "keymaps.h" -enum { PRIMARY, NUMPAD, FUNCTION }; // layers - - -/** - * To change your keyboard's layout from QWERTY to DVORAK or COLEMAK, comment out the line - * - * #define PRIMARY_KEYMAP_QWERTY - * - * by changing it to - * - * // #define PRIMARY_KEYMAP_QWERTY - * - * Then uncomment the line corresponding to the layout you want to use. - * - */ - -#define PRIMARY_KEYMAP_QWERTY -// #define PRIMARY_KEYMAP_COLEMAK -// #define PRIMARY_KEYMAP_DVORAK -// #define PRIMARY_KEYMAP_CUSTOM - - - -/* This comment temporarily turns off astyle's indent enforcement - * so we can make the keymaps actually resemble the physical key layout better - */ -// *INDENT-OFF* - -KEYMAPS( - -#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)), - -#elif defined (PRIMARY_KEYMAP_DVORAK) - - [PRIMARY] = KEYMAP_STACKED - (___, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, - Key_Backtick, Key_Quote, Key_Comma, Key_Period, Key_P, Key_Y, Key_Tab, - Key_PageUp, Key_A, Key_O, Key_E, Key_U, Key_I, - Key_PageDown, Key_Semicolon, Key_Q, Key_J, Key_K, Key_X, 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_F, Key_G, Key_C, Key_R, Key_L, Key_Slash, - Key_D, Key_H, Key_T, Key_N, Key_S, Key_Minus, - Key_RightAlt, Key_B, Key_M, Key_W, Key_V, Key_Z, Key_Equals, - Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl, - ShiftToLayer(FUNCTION)), - -#elif defined (PRIMARY_KEYMAP_COLEMAK) - - [PRIMARY] = KEYMAP_STACKED - (___, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, - Key_Backtick, Key_Q, Key_W, Key_F, Key_P, Key_G, Key_Tab, - Key_PageUp, Key_A, Key_R, Key_S, Key_T, Key_D, - 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_J, Key_L, Key_U, Key_Y, Key_Semicolon, Key_Equals, - Key_H, Key_N, Key_E, Key_I, Key_O, Key_Quote, - Key_RightAlt, Key_K, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, - Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl, - ShiftToLayer(FUNCTION)), - -#elif defined (PRIMARY_KEYMAP_CUSTOM) - // Edit this keymap to make a custom layout - [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)), - -#else - -#error "No default keymap defined. You should make sure that you have a line like '#define PRIMARY_KEYMAP_QWERTY' in your sketch" - -#endif - - - - [NUMPAD] = KEYMAP_STACKED - (___, ___, ___, ___, ___, ___, ___, - ___, ___, ___, ___, ___, ___, ___, - ___, ___, ___, ___, ___, ___, - ___, ___, ___, ___, ___, ___, ___, - ___, ___, ___, ___, - ___, - - M(MACRO_VERSION_INFO), ___, Key_7, Key_8, Key_9, Key_KeypadSubtract, ___, - ___, ___, Key_4, Key_5, Key_6, Key_KeypadAdd, ___, - ___, Key_1, Key_2, Key_3, Key_Equals, ___, - ___, ___, Key_0, Key_Period, Key_KeypadMultiply, Key_KeypadDivide, Key_Enter, - ___, ___, ___, ___, - ___), - - [FUNCTION] = KEYMAP_STACKED - (___, Key_F1, Key_F2, Key_F3, Key_F4, Key_F5, Key_CapsLock, - Key_Tab, ___, Key_mouseUp, ___, Key_mouseBtnR, Key_mouseWarpEnd, Key_mouseWarpNE, - Key_Home, Key_mouseL, Key_mouseDn, Key_mouseR, Key_mouseBtnL, Key_mouseWarpNW, - Key_End, Key_PrintScreen, Key_Insert, ___, Key_mouseBtnM, Key_mouseWarpSW, Key_mouseWarpSE, - ___, Key_Delete, ___, ___, - ___, - - Consumer_ScanPreviousTrack, Key_F6, Key_F7, Key_F8, Key_F9, Key_F10, Key_F11, - Consumer_PlaySlashPause, Consumer_ScanNextTrack, Key_LeftCurlyBracket, Key_RightCurlyBracket, Key_LeftBracket, Key_RightBracket, Key_F12, - Key_LeftArrow, Key_DownArrow, Key_UpArrow, Key_RightArrow, ___, ___, - Key_PcApplication, Consumer_Mute, Consumer_VolumeDecrement, Consumer_VolumeIncrement, ___, Key_Backslash, Key_Pipe, - ___, ___, Key_Enter, ___, - ___) -) // KEYMAPS( - -/* Re-enable astyle's indent enforcement */ -// *INDENT-ON* /** versionInfoMacro handles the 'firmware version info' macro * When a key bound to the macro is pressed, this macro diff --git a/README.md b/README.md index 84d0dbf7..90013759 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ _The default firmware for the Keyboardio Model 01_

This is a quick start guide for folks who are familiar with Arduino and prefer to use the command line. For everyone else: - * [Check out the wiki](https://github.com/keyboardio/Kaleidoscope/wiki/Keyboardio-Model-01-Introduction) for a more in depth introduction to how the Model 01 keyboard and the Kaleidoscope firmware work. - + * [Check out the wiki](https://github.com/keyboardio/Kaleidoscope/wiki/Keyboardio-Model-01-Introduction) for a more in depth introduction to how the Model 01 keyboard and the Kaleidoscope firmware work. + * If you have questions, [The community forums are happy to help!](https://community.keyboard.io/)

# Download and install @@ -30,17 +30,17 @@ If you install Arduino into some place that's /not/ `/usr/local/arduino`, you'll ### MacOS ```sh mkdir -p $HOME/Documents/Arduino -cd $HOME/Documents/Arduino +cd $HOME/Documents/Arduino ``` ### Linux ```sh mkdir -p $HOME/Arduino -cd $HOME/Arduino +cd $HOME/Arduino ``` -## Download hardware platform, including library source code +## Download hardware platform, including library source code ```sh mkdir -p hardware @@ -81,7 +81,7 @@ Hold down the "Prog" key in the top left corner of your keyboard, until the comp # Start to customize the firmware -You can customize your keyboard's key layout and LED effects by modifying the `Model01-Firmware.ino` file in the same directory as this README. Model01-Firmware.ino is a computer program written in 'Arduino C'. You can find documentation about Arduino C at https://arduino.cc. +You can customize your keyboard's behaviour by modifying the `Model01-Firmware.ino` file in the same directory as this README. Model01-Firmware.ino is a computer program written in 'Arduino C'. You can find documentation about Arduino C at https://arduino.cc. The keyboard layout is defined in the include file `keymaps.h`, which consists mainly of C preprocessor macros. # Updating the firmware and libraries diff --git a/keymaps.h b/keymaps.h new file mode 100644 index 00000000..9bc9bfca --- /dev/null +++ b/keymaps.h @@ -0,0 +1,186 @@ +/** 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 ShiftToLayer() and LockLayer() keys to change the active keymap. + * keeping NUM and FN consistent and accessible on all layers + * + * The PROG key is special, since it is how you indicate to the board that you + * want to flash the firmware. However, it can be remapped to a regular key. + * When the keyboard boots, it first looks to see whether the PROG key is held + * down; if it is, it simply awaits further flashing instructions. If it is + * not, it continues loading the rest of the firmware and the keyboard + * functions normally, with whatever binding you have set to PROG. More detail + * here: https://community.keyboard.io/t/how-the-prog-key-gets-you-into-the-bootloader/506/8 + * + * 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 ShiftToLayer(#) and LockLayer(#) + * macros switch to key layers based on this list. + * + * + + * A key defined as 'ShiftToLayer(FUNCTION)' will switch to FUNCTION while held. + * Similarly, a key defined as 'LockLayer(NUMPAD)' will switch to NUMPAD when tapped. + */ + +/** + * Layers are "0-indexed" -- That is the first one is layer 0. The second one is layer 1. + * The third one is layer 2. + * This 'enum' lets us use names like QWERTY, FUNCTION, and NUMPAD in place of + * the numbers 0, 1 and 2. + * + */ + +enum { PRIMARY, NUMPAD, FUNCTION }; // layers + + +/** + * To change your keyboard's layout from QWERTY to DVORAK or COLEMAK, comment out the line + * + * #define PRIMARY_KEYMAP_QWERTY + * + * by changing it to + * + * // #define PRIMARY_KEYMAP_QWERTY + * + * Then uncomment the line corresponding to the layout you want to use. + * + */ + +#define PRIMARY_KEYMAP_QWERTY +// #define PRIMARY_KEYMAP_COLEMAK +// #define PRIMARY_KEYMAP_DVORAK +// #define PRIMARY_KEYMAP_CUSTOM + + + +/* This comment temporarily turns off astyle's indent enforcement + * so we can make the keymaps actually resemble the physical key layout better + */ +// *INDENT-OFF* + +KEYMAPS( + +#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)), + +#elif defined (PRIMARY_KEYMAP_DVORAK) + + [PRIMARY] = KEYMAP_STACKED + (___, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, + Key_Backtick, Key_Quote, Key_Comma, Key_Period, Key_P, Key_Y, Key_Tab, + Key_PageUp, Key_A, Key_O, Key_E, Key_U, Key_I, + Key_PageDown, Key_Semicolon, Key_Q, Key_J, Key_K, Key_X, 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_F, Key_G, Key_C, Key_R, Key_L, Key_Slash, + Key_D, Key_H, Key_T, Key_N, Key_S, Key_Minus, + Key_RightAlt, Key_B, Key_M, Key_W, Key_V, Key_Z, Key_Equals, + Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl, + ShiftToLayer(FUNCTION)), + +#elif defined (PRIMARY_KEYMAP_COLEMAK) + + [PRIMARY] = KEYMAP_STACKED + (___, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, + Key_Backtick, Key_Q, Key_W, Key_F, Key_P, Key_G, Key_Tab, + Key_PageUp, Key_A, Key_R, Key_S, Key_T, Key_D, + 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_J, Key_L, Key_U, Key_Y, Key_Semicolon, Key_Equals, + Key_H, Key_N, Key_E, Key_I, Key_O, Key_Quote, + Key_RightAlt, Key_K, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, + Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl, + ShiftToLayer(FUNCTION)), + +#elif defined (PRIMARY_KEYMAP_CUSTOM) + // Edit this keymap to make a custom layout + [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)), + +#else + +#error "No default keymap defined. You should make sure that you have a line like '#define PRIMARY_KEYMAP_QWERTY' in your sketch" + +#endif + + + + [NUMPAD] = KEYMAP_STACKED + (___, ___, ___, ___, ___, ___, ___, + ___, ___, ___, ___, ___, ___, ___, + ___, ___, ___, ___, ___, ___, + ___, ___, ___, ___, ___, ___, ___, + ___, ___, ___, ___, + ___, + + M(MACRO_VERSION_INFO), ___, Key_7, Key_8, Key_9, Key_KeypadSubtract, ___, + ___, ___, Key_4, Key_5, Key_6, Key_KeypadAdd, ___, + ___, Key_1, Key_2, Key_3, Key_Equals, ___, + ___, ___, Key_0, Key_Period, Key_KeypadMultiply, Key_KeypadDivide, Key_Enter, + ___, ___, ___, ___, + ___), + + [FUNCTION] = KEYMAP_STACKED + (___, Key_F1, Key_F2, Key_F3, Key_F4, Key_F5, Key_CapsLock, + Key_Tab, ___, Key_mouseUp, ___, Key_mouseBtnR, Key_mouseWarpEnd, Key_mouseWarpNE, + Key_Home, Key_mouseL, Key_mouseDn, Key_mouseR, Key_mouseBtnL, Key_mouseWarpNW, + Key_End, Key_PrintScreen, Key_Insert, ___, Key_mouseBtnM, Key_mouseWarpSW, Key_mouseWarpSE, + ___, Key_Delete, ___, ___, + ___, + + Consumer_ScanPreviousTrack, Key_F6, Key_F7, Key_F8, Key_F9, Key_F10, Key_F11, + Consumer_PlaySlashPause, Consumer_ScanNextTrack, Key_LeftCurlyBracket, Key_RightCurlyBracket, Key_LeftBracket, Key_RightBracket, Key_F12, + Key_LeftArrow, Key_DownArrow, Key_UpArrow, Key_RightArrow, ___, ___, + Key_PcApplication, Consumer_Mute, Consumer_VolumeDecrement, Consumer_VolumeIncrement, ___, Key_Backslash, Key_Pipe, + ___, ___, Key_Enter, ___, + ___) +) // KEYMAPS( + +/* Re-enable astyle's indent enforcement */ +// *INDENT-ON*