diff options
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/custom_quantum_functions.md | 199 | ||||
| -rw-r--r-- | docs/feature_advanced_keycodes.md | 2 | ||||
| -rw-r--r-- | docs/feature_eeprom.md | 134 | ||||
| -rw-r--r-- | docs/feature_layers.md | 49 |
5 files changed, 198 insertions, 187 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index bf49bbb140..ca6fb91a79 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -80,6 +80,7 @@ * [Caps Word](feature_caps_word.md) * [Combos](feature_combo.md) * [Debounce API](feature_debounce_type.md) + * [EEPROM](feature_eeprom.md) * [Key Lock](feature_key_lock.md) * [Key Overrides](feature_key_overrides.md) * [Layers](feature_layers.md) diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 7b7849ad07..2917fbad26 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -102,11 +102,11 @@ These are the three main initialization functions, listed in the order that they ## Keyboard Pre Initialization code -This runs very early during startup, even before the USB has been started. +This runs very early during startup, even before the USB has been started. Shortly after this, the matrix is initialized. -For most users, this shouldn't be used, as it's primarily for hardware oriented initialization. +For most users, this shouldn't be used, as it's primarily for hardware oriented initialization. However, if you have hardware stuff that you need initialized, this is the best place for it (such as initializing LED pins). @@ -134,9 +134,9 @@ void keyboard_pre_init_user(void) { ## Matrix Initialization Code -This is called when the matrix is initialized, and after some of the hardware has been set up, but before many of the features have been initialized. +This is called when the matrix is initialized, and after some of the hardware has been set up, but before many of the features have been initialized. -This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependant on where it's started. +This is useful for setting up stuff that you may need elsewhere, but isn't hardware related nor is dependant on where it's started. ### `matrix_init_*` Function Documentation @@ -227,185 +227,6 @@ void suspend_wakeup_init_user(void) { * Keyboard/Revision: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` * Keymap: `void suspend_power_down_kb(void)` and `void suspend_wakeup_init_user(void)` -# Layer Change Code :id=layer-change-code - -This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. - -### Example `layer_state_set_*` Implementation - -This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example. - -```c -layer_state_t layer_state_set_user(layer_state_t state) { - switch (get_highest_layer(state)) { - case _RAISE: - rgblight_setrgb (0x00, 0x00, 0xFF); - break; - case _LOWER: - rgblight_setrgb (0xFF, 0x00, 0x00); - break; - case _PLOVER: - rgblight_setrgb (0x00, 0xFF, 0x00); - break; - case _ADJUST: - rgblight_setrgb (0x7A, 0x00, 0xFF); - break; - default: // for any other layers, or the default layer - rgblight_setrgb (0x00, 0xFF, 0xFF); - break; - } - return state; -} -``` - -Use the `IS_LAYER_ON_STATE(state, layer)` and `IS_LAYER_OFF_STATE(state, layer)` macros to check the status of a particular layer. - -Outside of `layer_state_set_*` functions, you can use the `IS_LAYER_ON(layer)` and `IS_LAYER_OFF(layer)` macros to check global layer state. - -### `layer_state_set_*` Function Documentation - -* Keyboard/Revision: `layer_state_t layer_state_set_kb(layer_state_t state)` -* Keymap: `layer_state_t layer_state_set_user(layer_state_t state)` - - -The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status) - - -# Persistent Configuration (EEPROM) - -This allows you to configure persistent settings for your keyboard. These settings are stored in the EEPROM of your controller, and are retained even after power loss. The settings can be read with `eeconfig_read_kb` and `eeconfig_read_user`, and can be written to using `eeconfig_update_kb` and `eeconfig_update_user`. This is useful for features that you want to be able to toggle (like toggling rgb layer indication). Additionally, you can use `eeconfig_init_kb` and `eeconfig_init_user` to set the default values for the EEPROM. - -The complicated part here, is that there are a bunch of ways that you can store and access data via EEPROM, and there is no "correct" way to do this. However, you only have a DWORD (4 bytes) for each function. - -Keep in mind that EEPROM has a limited number of writes. While this is very high, it's not the only thing writing to the EEPROM, and if you write too often, you can potentially drastically shorten the life of your MCU. - -* If you don't understand the example, then you may want to avoid using this feature, as it is rather complicated. - -### Example Implementation - -This is an example of how to add settings, and read and write it. We're using the user keymap for the example here. This is a complex function, and has a lot going on. In fact, it uses a lot of the above functions to work! - - -In your keymap.c file, add this to the top: -```c -typedef union { - uint32_t raw; - struct { - bool rgb_layer_change :1; - }; -} user_config_t; - -user_config_t user_config; -``` - -This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits. You can mix and match, but changing the order can cause issues, as it will change the values that are read and written. - -We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_init_user` and `process_record_user` to configure everything. - -Now, using the `keyboard_post_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like: -```c -void keyboard_post_init_user(void) { - // Call the keymap level matrix init. - - // Read the user config from EEPROM - user_config.raw = eeconfig_read_user(); - - // Set default layer, if enabled - if (user_config.rgb_layer_change) { - rgblight_enable_noeeprom(); - rgblight_sethsv_noeeprom_cyan(); - rgblight_mode_noeeprom(1); - } -} -``` -The above function will use the EEPROM config immediately after reading it, to set the default layer's RGB color. The "raw" value of it is converted in a usable structure based on the "union" that you created above. - -```c -layer_state_t layer_state_set_user(layer_state_t state) { - switch (get_highest_layer(state)) { - case _RAISE: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } - break; - case _LOWER: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); } - break; - case _PLOVER: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); } - break; - case _ADJUST: - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); } - break; - default: // for any other layers, or the default layer - if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } - break; - } - return state; -} -``` -This will cause the RGB underglow to be changed ONLY if the value was enabled. Now to configure this value, create a new keycode for `process_record_user` called `RGB_LYR`. Additionally, we want to make sure that if you use the normal RGB codes, that it turns off Using the example above, make it look this: -```c - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case FOO: - if (record->event.pressed) { - // Do something when pressed - } else { - // Do something else when release - } - return false; // Skip all further processing of this key - case KC_ENTER: - // Play a tone when enter is pressed - if (record->event.pressed) { - PLAY_SONG(tone_qwerty); - } - return true; // Let QMK send the enter press/release events - case RGB_LYR: // This allows me to use underglow as layer indication, or as normal - if (record->event.pressed) { - user_config.rgb_layer_change ^= 1; // Toggles the status - eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM - if (user_config.rgb_layer_change) { // if layer state indication is enabled, - layer_state_set(layer_state); // then immediately update the layer color - } - } - return false; - case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference) - if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled - if (user_config.rgb_layer_change) { // only if this is enabled - user_config.rgb_layer_change = false; // disable it, and - eeconfig_update_user(user_config.raw); // write the setings to EEPROM - } - } - return true; break; - default: - return true; // Process all other keycodes normally - } -} -``` -And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic Lite](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. - -```c -void eeconfig_init_user(void) { // EEPROM is getting reset! - user_config.raw = 0; - user_config.rgb_layer_change = true; // We want this enabled by default - eeconfig_update_user(user_config.raw); // Write default value to EEPROM now - - // use the non noeeprom versions, to write these values to EEPROM too - rgblight_enable(); // Enable RGB by default - rgblight_sethsv_cyan(); // Set it to CYAN by default - rgblight_mode(1); // set to solid by default -} -``` - -And you're done. The RGB layer indication will only work if you want it to. And it will be saved, even after unplugging the board. And if you use any of the RGB codes, it will disable the layer indication, so that it stays on the mode and color that you set it to. - -### 'EECONFIG' Function Documentation - -* Keyboard/Revision: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` and `void eeconfig_update_kb(uint32_t val)` -* Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)` - -The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. - # Deferred Execution :id=deferred-execution QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers. To enable this functionality, set `DEFERRED_EXEC_ENABLE = yes` in rules.mk. @@ -471,3 +292,15 @@ If registrations fail, then you can increase this value in your keyboard or keym ```c #define MAX_DEFERRED_EXECUTORS 16 ``` + +# Advanced topics :id=advanced-topics + +This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for. + +## Layer Change Code :id=layer-change-code + +[Layer change code](feature_layers.md#layer-change-code) + +## Persistent Configuration (EEPROM) :id=persistent-configuration-eeprom + +[Persistent Configuration (EEPROM)](feature_eeprom.md) diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md index 83066187c7..b04721b23a 100644 --- a/docs/feature_advanced_keycodes.md +++ b/docs/feature_advanced_keycodes.md @@ -161,7 +161,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { }; ``` -# Legacy Content :id=legacy-content +# Advanced topics :id=advanced-topics This page used to encompass a large set of features. We have moved many sections that used to be part of this page to their own pages. Everything below this point is simply a redirect so that people following old links on the web find what they're looking for. diff --git a/docs/feature_eeprom.md b/docs/feature_eeprom.md new file mode 100644 index 0000000000..e261c455cb --- /dev/null +++ b/docs/feature_eeprom.md @@ -0,0 +1,134 @@ +# Persistent Configuration (EEPROM) + +This allows you to configure persistent settings for your keyboard. These settings are stored in the EEPROM of your controller, and are retained even after power loss. The settings can be read with `eeconfig_read_kb` and `eeconfig_read_user`, and can be written to using `eeconfig_update_kb` and `eeconfig_update_user`. This is useful for features that you want to be able to toggle (like toggling rgb layer indication). Additionally, you can use `eeconfig_init_kb` and `eeconfig_init_user` to set the default values for the EEPROM. + +The complicated part here, is that there are a bunch of ways that you can store and access data via EEPROM, and there is no "correct" way to do this. However, you only have a DWORD (4 bytes) for each function. + +Keep in mind that EEPROM has a limited number of writes. While this is very high, it's not the only thing writing to the EEPROM, and if you write too often, you can potentially drastically shorten the life of your MCU. + +* If you don't understand the example, then you may want to avoid using this feature, as it is rather complicated. + +## Example Implementation + +This is an example of how to add settings, and read and write it. We're using the user keymap for the example here. This is a complex function, and has a lot going on. In fact, it uses a lot of the above functions to work! + + +In your keymap.c file, add this to the top: +```c +typedef union { + uint32_t raw; + struct { + bool rgb_layer_change :1; + }; +} user_config_t; + +user_config_t user_config; +``` + +This sets up a 32 bit structure that we can store settings with in memory, and write to the EEPROM. Using this removes the need to define variables, since they're defined in this structure. Remember that `bool` (boolean) values use 1 bit, `uint8_t` uses 8 bits, `uint16_t` uses up 16 bits. You can mix and match, but changing the order can cause issues, as it will change the values that are read and written. + +We're using `rgb_layer_change`, for the `layer_state_set_*` function, and use `keyboard_post_init_user` and `process_record_user` to configure everything. + +Now, using the `keyboard_post_init_user` code above, you want to add `eeconfig_read_user()` to it, to populate the structure you've just created. And you can then immediately use this structure to control functionality in your keymap. And It should look like: +```c +void keyboard_post_init_user(void) { + // Call the keymap level matrix init. + + // Read the user config from EEPROM + user_config.raw = eeconfig_read_user(); + + // Set default layer, if enabled + if (user_config.rgb_layer_change) { + rgblight_enable_noeeprom(); + rgblight_sethsv_noeeprom_cyan(); + rgblight_mode_noeeprom(1); + } +} +``` +The above function will use the EEPROM config immediately after reading it, to set the default layer's RGB color. The "raw" value of it is converted in a usable structure based on the "union" that you created above. + +```c +layer_state_t layer_state_set_user(layer_state_t state) { + switch (get_highest_layer(state)) { + case _RAISE: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } + break; + case _LOWER: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_red(); rgblight_mode_noeeprom(1); } + break; + case _PLOVER: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_green(); rgblight_mode_noeeprom(1); } + break; + case _ADJUST: + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_white(); rgblight_mode_noeeprom(1); } + break; + default: // for any other layers, or the default layer + if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_cyan(); rgblight_mode_noeeprom(1); } + break; + } + return state; +} +``` +This will cause the RGB underglow to be changed ONLY if the value was enabled. Now to configure this value, create a new keycode for `process_record_user` called `RGB_LYR`. Additionally, we want to make sure that if you use the normal RGB codes, that it turns off Using the example above, make it look this: +```c + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case FOO: + if (record->event.pressed) { + // Do something when pressed + } else { + // Do something else when release + } + return false; // Skip all further processing of this key + case KC_ENTER: + // Play a tone when enter is pressed + if (record->event.pressed) { + PLAY_SONG(tone_qwerty); + } + return true; // Let QMK send the enter press/release events + case RGB_LYR: // This allows me to use underglow as layer indication, or as normal + if (record->event.pressed) { + user_config.rgb_layer_change ^= 1; // Toggles the status + eeconfig_update_user(user_config.raw); // Writes the new status to EEPROM + if (user_config.rgb_layer_change) { // if layer state indication is enabled, + layer_state_set(layer_state); // then immediately update the layer color + } + } + return false; + case RGB_MODE_FORWARD ... RGB_MODE_GRADIENT: // For any of the RGB codes (see quantum_keycodes.h, L400 for reference) + if (record->event.pressed) { //This disables layer indication, as it's assumed that if you're changing this ... you want that disabled + if (user_config.rgb_layer_change) { // only if this is enabled + user_config.rgb_layer_change = false; // disable it, and + eeconfig_update_user(user_config.raw); // write the setings to EEPROM + } + } + return true; break; + default: + return true; // Process all other keycodes normally + } +} +``` +And lastly, you want to add the `eeconfig_init_user` function, so that when the EEPROM is reset, you can specify default values, and even custom actions. To force an EEPROM reset, use the `EEP_RST` keycode or [Bootmagic Lite](feature_bootmagic.md) functionallity. For example, if you want to set rgb layer indication by default, and save the default valued. + +```c +void eeconfig_init_user(void) { // EEPROM is getting reset! + user_config.raw = 0; + user_config.rgb_layer_change = true; // We want this enabled by default + eeconfig_update_user(user_config.raw); // Write default value to EEPROM now + + // use the non noeeprom versions, to write these values to EEPROM too + rgblight_enable(); // Enable RGB by default + rgblight_sethsv_cyan(); // Set it to CYAN by default + rgblight_mode(1); // set to solid by default +} +``` + +And you're done. The RGB layer indication will only work if you want it to. And it will be saved, even after unplugging the board. And if you use any of the RGB codes, it will disable the layer indication, so that it stays on the mode and color that you set it to. + +## 'EECONFIG' Function Documentation + +* Keyboard/Revision: `void eeconfig_init_kb(void)`, `uint32_t eeconfig_read_kb(void)` and `void eeconfig_update_kb(uint32_t val)` +* Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)` + +The `val` is the value of the data that you want to write to EEPROM. And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. diff --git a/docs/feature_layers.md b/docs/feature_layers.md index e30c540a79..5ad4005f5d 100644 --- a/docs/feature_layers.md +++ b/docs/feature_layers.md @@ -1,6 +1,6 @@ # Layers :id=layers -One of the most powerful and well used features of QMK Firmware is the ability to use layers. For most people, this amounts to a function key that allows for different keys, much like what you would see on a laptop or tablet keyboard. +One of the most powerful and well used features of QMK Firmware is the ability to use layers. For most people, this amounts to a function key that allows for different keys, much like what you would see on a laptop or tablet keyboard. For a detailed explanation of how the layer stack works, checkout [Keymap Overview](keymap.md#keymap-and-layers). @@ -9,7 +9,7 @@ For a detailed explanation of how the layer stack works, checkout [Keymap Overvi These functions allow you to activate layers in various ways. Note that layers are not generally independent layouts -- multiple layers can be activated at once, and it's typical for layers to use `KC_TRNS` to allow keypresses to pass through to lower layers. When using momentary layer switching with MO(), LM(), TT(), or LT(), make sure to leave the key on the above layers transparent or it may not work as intended. * `DF(layer)` - switches the default layer. The default layer is the always-active base layer that other layers stack on top of. See below for more about the default layer. This might be used to switch from QWERTY to Dvorak layout. (Note that this is a temporary switch that only persists until the keyboard loses power. To modify the default layer in a persistent way requires deeper customization, such as calling the `set_single_persistent_default_layer` function inside of [process_record_user](custom_quantum_functions.md#programming-the-behavior-of-any-keycode).) -* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. +* `MO(layer)` - momentarily activates *layer*. As soon as you let go of the key, the layer is deactivated. * `LM(layer, mod)` - Momentarily activates *layer* (like `MO`), but with modifier(s) *mod* active. Only supports layers 0-15 and the left modifiers: `MOD_LCTL`, `MOD_LSFT`, `MOD_LALT`, `MOD_LGUI` (note the use of `MOD_` constants instead of `KC_`). These modifiers can be combined using bitwise OR, e.g. `LM(_RAISE, MOD_LCTL | MOD_LALT)`. * `LT(layer, kc)` - momentarily activates *layer* when held, and sends *kc* when tapped. Only supports layers 0-15. * `OSL(layer)` - momentarily activates *layer* until the next key is pressed. See [One Shot Keys](one_shot_keys.md) for details and additional functionality. @@ -31,7 +31,7 @@ Care must be taken when switching layers, it's possible to lock yourself into a If you are just getting started with QMK you will want to keep everything simple. Follow these guidelines when setting up your layers: -* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). +* Setup layer 0 as your default, "base" layer. This is your normal typing layer, and could be whatever layout you want (qwerty, dvorak, colemak, etc.). It's important to set this as the lowest layer since it will typically have most or all of the keyboard's keys defined, so would block other layers from having any effect if it were above them (i.e., had a higher layer number). * Arrange your layers in a "tree" layout, with layer 0 as the root. Do not try to enter the same layer from more than one other layer. * In a layer's keymap, only reference higher-numbered layers. Because layers are processed from the highest-numbered (topmost) active layer down, modifying the state of lower layers can be tricky and error-prone. @@ -89,3 +89,46 @@ It is also possible to check the state of a particular layer using the following |---------------------------------|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------| | `layer_state_is(layer)` | Checks if the specified `layer` is enabled globally. | `IS_LAYER_ON(layer)`, `IS_LAYER_OFF(layer)` | | `layer_state_cmp(state, layer)` | Checks `state` to see if the specified `layer` is enabled. Intended for use in layer callbacks. | `IS_LAYER_ON_STATE(state, layer)`, `IS_LAYER_OFF_STATE(state, layer)` | + +## Layer Change Code :id=layer-change-code + +This runs code every time that the layers get changed. This can be useful for layer indication, or custom layer handling. + +### Example `layer_state_set_*` Implementation + +This example shows how to set the [RGB Underglow](feature_rgblight.md) lights based on the layer, using the Planck as an example. + +```c +layer_state_t layer_state_set_user(layer_state_t state) { + switch (get_highest_layer(state)) { + case _RAISE: + rgblight_setrgb (0x00, 0x00, 0xFF); + break; + case _LOWER: + rgblight_setrgb (0xFF, 0x00, 0x00); + break; + case _PLOVER: + rgblight_setrgb (0x00, 0xFF, 0x00); + break; + case _ADJUST: + rgblight_setrgb (0x7A, 0x00, 0xFF); + break; + default: // for any other layers, or the default layer + rgblight_setrgb (0x00, 0xFF, 0xFF); + break; + } + return state; +} +``` + +Use the `IS_LAYER_ON_STATE(state, layer)` and `IS_LAYER_OFF_STATE(state, layer)` macros to check the status of a particular layer. + +Outside of `layer_state_set_*` functions, you can use the `IS_LAYER_ON(layer)` and `IS_LAYER_OFF(layer)` macros to check global layer state. + +### `layer_state_set_*` Function Documentation + +* Keyboard/Revision: `layer_state_t layer_state_set_kb(layer_state_t state)` +* Keymap: `layer_state_t layer_state_set_user(layer_state_t state)` + + +The `state` is the bitmask of the active layers, as explained in the [Keymap Overview](keymap.md#keymap-layer-status) |