diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 2 | ||||
| -rw-r--r-- | docs/breaking_changes.md | 4 | ||||
| -rw-r--r-- | docs/chibios_upgrade_instructions.md | 56 | ||||
| -rw-r--r-- | docs/cli_commands.md | 2 | ||||
| -rw-r--r-- | docs/compatible_microcontrollers.md | 2 | ||||
| -rw-r--r-- | docs/config_options.md | 33 | ||||
| -rw-r--r-- | docs/custom_quantum_functions.md | 8 | ||||
| -rw-r--r-- | docs/eeprom_driver.md | 3 | ||||
| -rw-r--r-- | docs/feature_debounce_type.md | 4 | ||||
| -rw-r--r-- | docs/feature_dip_switch.md | 16 | ||||
| -rw-r--r-- | docs/feature_haptic_feedback.md | 26 | ||||
| -rw-r--r-- | docs/feature_key_overrides.md | 229 | ||||
| -rw-r--r-- | docs/feature_oled_driver.md | 4 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 141 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 47 | ||||
| -rw-r--r-- | docs/feature_split_keyboard.md | 122 | ||||
| -rw-r--r-- | docs/feature_st7565.md | 274 | ||||
| -rw-r--r-- | docs/ja/compatible_microcontrollers.md | 2 | ||||
| -rw-r--r-- | docs/ja/feature_dip_switch.md | 16 | ||||
| -rw-r--r-- | docs/serial_driver.md | 15 | ||||
| -rw-r--r-- | docs/syllabus.md | 1 | ||||
| -rw-r--r-- | docs/understanding_qmk.md | 1 | ||||
| -rw-r--r-- | docs/zh-cn/custom_quantum_functions.md | 6 |
23 files changed, 924 insertions, 90 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 9798ef5127..6c39aeda09 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -77,6 +77,7 @@ * [Combos](feature_combo.md) * [Debounce API](feature_debounce_type.md) * [Key Lock](feature_key_lock.md) + * [Key Overrides](feature_key_overrides.md) * [Layers](feature_layers.md) * [One Shot Keys](one_shot_keys.md) * [Pointing Device](feature_pointing_device.md) @@ -93,6 +94,7 @@ * Hardware Features * Displays * [HD44780 LCD Controller](feature_hd44780.md) + * [ST7565 LCD Driver](feature_st7565.md) * [OLED Driver](feature_oled_driver.md) * Lighting * [Backlight](feature_backlight.md) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index b0d56a81bd..a1a56bd457 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -100,3 +100,7 @@ This happens immediately after the previous `develop` branch is merged. * [ ] `git pull --ff-only` * [ ] `git merge --no-ff develop` * [ ] `git push upstream master` + +## Post-merge operations + +* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md) diff --git a/docs/chibios_upgrade_instructions.md b/docs/chibios_upgrade_instructions.md new file mode 100644 index 0000000000..40c2faafcf --- /dev/null +++ b/docs/chibios_upgrade_instructions.md @@ -0,0 +1,56 @@ +# ChibiOS Upgrade Procedure + +ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a branch tied to the ChibiOS version in use and should not be mixed with different versions. + +## Getting ChibiOS + +* `svn` Initialisation: + * Only needed to be done once + * You might need to separately install `git-svn` package in your OS's package manager + * `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/` + * `git remote add qmk git@github.com:qmk/ChibiOS.git` +* Updating: + * `git svn fetch` + * First time around this will take several hours + * Subsequent updates will be incremental only +* Tagging example (work out which version first!): + * `git tag -a ver20.3.3 -m ver20.3.3 svn/tags/ver20.3.3` + * `git push qmk ver20.3.3` + * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN svn/tags/ver20.3.3` + * `git push qmk breaking_YYYY_qN` + +## Getting ChibiOS-Contrib + +* `git` Initialisation: + * `git clone git@github.com:qmk/ChibiOS-Contrib` + * `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib` + * `git checkout -b chibios-20.3.x upstream/chibios-20.3.x` +* Updating: + * `git fetch --all --tags --prune` + * `git checkout chibios-20.3.x` + * `git pull --ff-only` + * `git push origin chibios-20.3.x` + * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN chibios-20.3.x` + * `git push origin breaking_YYYY_qN` + +## Updating submodules + +* Update the submodules + * `cd $QMK_FIRMWARE` + * `git checkout develop` + * `git pull --ff-only` + * `git checkout -b chibios-version-bump` + * `cd lib/chibios` + * `git fetch --all --tags --prune` + * `git checkout breaking_YYYY_qN` + * `cd ../chibios-contrib` + * `git fetch --all --tags --prune` + * `git checkout breaking_YYYY_qN` +* Build everything + * `cd $QMK_FIRMWARE` + * `qmk multibuild -j4` + * Make sure there are no errors +* Push to the repo + * `git commit -am 'Update ChibiOS to XXXXXXXXX'` + * `git push --set-upstream origin chibios-version-bump` +* Make a PR to qmk_firmware with the new branch
\ No newline at end of file diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 581342093a..e30593daa9 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -368,7 +368,7 @@ qmk generate-docs ## `qmk generate-rgb-breathe-table` -This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/`. +This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight.md) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`. **Usage**: diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 0f5b140de0..865b29feec 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -31,6 +31,8 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [STM32F446](https://www.st.com/en/microcontrollers-microprocessors/stm32f446.html) * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) + * [STM32L412](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) + * [STM32L422](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x2.html) * [STM32L433](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) * [STM32L443](https://www.st.com/en/microcontrollers-microprocessors/stm32l4x3.html) diff --git a/docs/config_options.md b/docs/config_options.md index d0f0b316e0..0c98b31010 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -51,8 +51,10 @@ This is a C header file that is one of the first things included, and will persi * the number of columns in your keyboard's matrix * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` * pins of the rows, from top to bottom + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` * pins of the columns, from left to right + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define MATRIX_IO_DELAY 30` * the delay in microseconds when between changing matrix pin state and reading values * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }` @@ -193,6 +195,8 @@ If you define these options you will enable the associated feature, which may in * Sets the delay between `register_code` and `unregister_code`, if you're having issues with it registering properly (common on VUSB boards). The value is in milliseconds. * `#define TAP_HOLD_CAPS_DELAY 80` * Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPSLOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher. +* `#define KEY_OVERRIDE_REPEAT_DELAY 500` + * Sets the key repeat interval for [key overrides](feature_key_overrides.md). ## RGB Light Configuration @@ -272,7 +276,7 @@ There are a few different ways to set handedness for split keyboards (listed in ### Other Options * `#define USE_I2C` - * For using I2C instead of Serial (defaults to serial) + * For using I2C instead of Serial (default is serial; serial transport is supported on ARM -- I2C is AVR-only) * `#define SOFT_SERIAL_PIN D0` * When using serial, define this. `D0` or `D1`,`D2`,`D3`,`E6`. @@ -280,6 +284,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define MATRIX_ROW_PINS_RIGHT { <row pins> }` * `#define MATRIX_COL_PINS_RIGHT { <col pins> }` * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns. + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`. @@ -300,7 +305,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_USB_DETECT` * Detect (with timeout) USB connection when delegating master/slave * Default behavior for ARM - * Required for AVR Teensy + * Required for AVR Teensy (without hardware mods) * `#define SPLIT_USB_TIMEOUT 2000` * Maximum timeout when detecting master/slave when using `SPLIT_USB_DETECT` @@ -308,6 +313,28 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define SPLIT_USB_TIMEOUT_POLL 10` * Poll frequency when detecting master/slave when using `SPLIT_USB_DETECT` +* `#define FORCED_SYNC_THROTTLE_MS 100` + * Deadline for synchronizing data from master to slave when using the QMK-provided split transport. + +* `#define SPLIT_TRANSPORT_MIRROR` + * Mirrors the master-side matrix on the slave when using the QMK-provided split transport. + +* `#define SPLIT_LAYER_STATE_ENABLE` + * Ensures the current layer state is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_LED_STATE_ENABLE` + * Ensures the current host indicator state (caps/num/scroll) is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_MODS_ENABLE` + * Ensures the current modifier state (normal, weak, and oneshot) is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_WPM_ENABLE` + * Ensures the current WPM is available on the slave when using the QMK-provided split transport. + +* `#define SPLIT_TRANSACTION_IDS_KB .....` +* `#define SPLIT_TRANSACTION_IDS_USER .....` + * Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard.md#custom-data-sync) for more information. + # The `rules.mk` File This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features. @@ -375,6 +402,8 @@ Use these to enable or disable building certain features. The more you have enab * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work * `AUDIO_ENABLE` * Enable the audio subsystem. +* `KEY_OVERRIDE_ENABLE` + * Enable the key override feature * `RGBLIGHT_ENABLE` * Enable keyboard underlight functionality * `LEADER_ENABLE` diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 694b421e79..30c637bb49 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -144,6 +144,14 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw * Keyboard/Revision: `void matrix_init_kb(void)` * Keymap: `void matrix_init_user(void)` +### Low-level Matrix Overrides Function Documentation :id=low-level-matrix-overrides + +* GPIO pin initialisation: `void matrix_init_pins(void)` + * This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override. +* `COL2ROW`-based row reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)` +* `ROW2COL`-based column reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` +* `DIRECT_PINS`-based reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` + * These three functions need to perform the low-level retrieval of matrix state of relevant input pins, based on the matrix type. Only one of the functions should be implemented, if needed. By default this will iterate through `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, configuring the inputs and outputs based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no manipulation of matrix GPIO pin state will occur within QMK itself, instead deferring to the keyboard's override. ## Keyboard Post Initialization code diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md index e2c262546d..6dcf10c04d 100644 --- a/docs/eeprom_driver.md +++ b/docs/eeprom_driver.md @@ -31,6 +31,9 @@ Currently QMK supports 24xx-series chips over I2C. As such, requires a working i `#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32 `#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2 `#define EXTERNAL_EEPROM_WRITE_TIME` | Write cycle time of the EEPROM, as specified in the datasheet | 5 +`#define EXTERNAL_EEPROM_WP_PIN` | If defined the WP pin will be toggled appropriately when writing to the EEPROM. | _none_ + +Some I2C EEPROM manufacturers explicitly recommend against hardcoding the WP pin to ground. This is in order to protect the eeprom memory content during power-up/power-down/brown-out conditions at low voltage where the eeprom is still operational, but the i2c master output might be unpredictable. If a WP pin is configured, then having an external pull-up on the WP pin is recommended. Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`. diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md index 3ad74224c1..306185fe83 100644 --- a/docs/feature_debounce_type.md +++ b/docs/feature_debounce_type.md @@ -121,16 +121,16 @@ DEBOUNCE_TYPE = <name of algorithm> Where name of algorithm is one of: * ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed. * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant. -* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. +* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row. For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use. * ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key * ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed. +* ```asym_eager_defer_pk``` - debouncing per key. On a key-down state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key-up status change is pushed. ### A couple algorithms that could be implemented in the future: * ```sym_defer_pr``` * ```sym_eager_g``` -* ```asym_eager_defer_pk``` ### Use your own debouncing code You have the option to implement you own debouncing algorithm. To do this: diff --git a/docs/feature_dip_switch.md b/docs/feature_dip_switch.md index 15e449c4c4..5e8c19bfa7 100644 --- a/docs/feature_dip_switch.md +++ b/docs/feature_dip_switch.md @@ -23,8 +23,9 @@ or The callback functions can be inserted into your `<keyboard>.c`: ```c -void dip_switch_update_kb(uint8_t index, bool active) { - dip_switch_update_user(index, active); +bool dip_switch_update_kb(uint8_t index, bool active) { + if !(dip_switch_update_user(index, active)) { return false; } + return true; } ``` @@ -32,7 +33,7 @@ void dip_switch_update_kb(uint8_t index, bool active) { or `keymap.c`: ```c -void dip_switch_update_user(uint8_t index, bool active) { +bool dip_switch_update_user(uint8_t index, bool active) { switch (index) { case 0: if(active) { audio_on(); } else { audio_off(); } @@ -57,6 +58,7 @@ void dip_switch_update_user(uint8_t index, bool active) { } break; } + return true; } ``` @@ -64,8 +66,9 @@ Additionally, we support bit mask functions which allow for more complex handlin ```c -void dip_switch_update_mask_kb(uint32_t state) { - dip_switch_update_mask_user(state); +bool dip_switch_update_mask_kb(uint32_t state) { + if (!dip_switch_update_mask_user(state)) { return false; } + return true; } ``` @@ -73,7 +76,7 @@ void dip_switch_update_mask_kb(uint32_t state) { or `keymap.c`: ```c -void dip_switch_update_mask_user(uint32_t state) { +bool dip_switch_update_mask_user(uint32_t state) { if (state & (1UL<<0) && state & (1UL<<1)) { layer_on(_ADJUST); // C on esc } else { @@ -89,6 +92,7 @@ void dip_switch_update_mask_user(uint32_t state) { } else { layer_off(_TEST_B); } + return true; } ``` diff --git a/docs/feature_haptic_feedback.md b/docs/feature_haptic_feedback.md index a092e784c7..469c9c7981 100644 --- a/docs/feature_haptic_feedback.md +++ b/docs/feature_haptic_feedback.md @@ -162,4 +162,28 @@ This will set what sequence HPT_RST will set as the active mode. If not defined, ### DRV2605L Continuous Haptic Mode -This mode sets continuous haptic feedback with the option to increase or decrease strength. +This mode sets continuous haptic feedback with the option to increase or decrease strength. + +## Haptic Key Exclusion +The Haptic Exclusion is implemented as `__attribute__((weak)) bool get_haptic_enabled_key(uint16_t keycode, keyrecord_t *record)` in haptic.c. This allows a re-definition at the required level with the specific requirement / exclusion. + +### NO_HAPTIC_MOD +With the entry of `#define NO_HAPTIC_MOD` in config.h, modifiers from Left Control to Right GUI will not trigger a feedback. This also includes modifiers in a Mod Tap configuration. + +### NO_HAPTIC_FN +With the entry of `#define NO_HAPTIC_FN` in config.h, layer keys will not rigger a feedback. + +### NO_HAPTIC_ALPHA +With the entry of `#define NO_HAPTIC_ALPHA` in config.h, none of the alpha keys (A ... Z) will trigger a feedback. + +### NO_HAPTIC_PUNCTUATION +With the entry of `#define NO_HAPTIC_PUNCTUATION` in config.h, none of the following keys will trigger a feedback: Enter, ESC, Backspace, Space, Minus, Equal, Left Bracket, Right Bracket, Backslash, Non-US Hash, Semicolon, Quote, Grave, Comma, Slash, Dot, Non-US Backslash. + +### NO_HAPTIC_LOCKKEYS +With the entry of `#define NO_HAPTIC_LOCKKEYS` in config.h, none of the following keys will trigger a feedback: Caps Lock, Scroll Lock, Num Lock. + +### NO_HAPTIC_NAV +With the entry of `#define NO_HAPTIC_NAV` in config.h, none of the following keys will trigger a feedback: Print Screen, Pause, Insert, Delete, Page Down, Page Up, Left Arrow, Up Arrow, Right Arrow, Down Arrow, End, Home. + +### NO_HAPTIC_NUMERIC +With the entry of `#define NO_HAPTIC_NUMERIC` in config.h, none of the following keys between 0 and 9 (KC_1 ... KC_0) will trigger a feedback.
\ No newline at end of file diff --git a/docs/feature_key_overrides.md b/docs/feature_key_overrides.md new file mode 100644 index 0000000000..861c4bef5d --- /dev/null +++ b/docs/feature_key_overrides.md @@ -0,0 +1,229 @@ +# Key Overrides + +Key overrides allow you to override modifier-key combinations to send a different modifier-key combination or perform completely custom actions. Don't want `shift` + `1` to type `!` on your computer? Use a key override to make your keyboard type something different when you press `shift` + `1`. The general behavior is like this: If `modifiers w` + `key x` are pressed, replace these keys with `modifiers y` + `key z` in the keyboard report. + +You can use key overrides in a similar way to momentary layer/fn keys to activate custom keycodes/shortcuts, with a number of benefits: You completely keep the original use of the modifier keys, while being able to save space by removing fn keys from your keyboard. You can also easily configure _combinations of modifiers_ to trigger different actions than individual modifiers, and much more. The possibilities are quite vast and this documentation contains a few examples for inspiration throughout. + +##### A few more examples to get started: You could use key overrides to... +- Send `brightness up/down` when pressing `ctrl` + `volume up/down`. +- Send `delete` when pressing `shift` + `backspace`. +- Create custom shortcuts or change existing ones: E.g. Send `ctrl`+`shift`+`z` when `ctrl`+`y` is pressed. +- Run custom code when `ctrl` + `alt` + `esc` is pressed. + +## Setup + +To enable this feature, you need to add `KEY_OVERRIDE_ENABLE = yes` to your `rules.mk`. + +Then, in your `keymap.c` file, you'll need to define the array `key_overrides`, which defines all key overrides to be used. Each override is a value of type `key_override_t`. The array `key_overrides` is `NULL`-terminated and contains pointers to `key_override_t` values (`const key_override_t **`). + +## Creating Key Overrides + +The `key_override_t` struct has many options that allow you to precisely tune your overrides. The full reference is shown below. Instead of manually creating a `key_override_t` value, it is recommended to use these dedicated initializers: + +#### `ko_make_basic(modifiers, key, replacement)` +Returns a `key_override_t`, which sends `replacement` (can be a key-modifer combination), when `key` and `modifiers` are all pressed down. This override still activates if any additional modifiers not specified in `modifiers` are also pressed down. See `ko_make_with_layers_and_negmods` to customize this behavior. + +#### `ko_make_with_layers(modifiers, key, replacement, layers)` +Additionally takes a bitmask `layers` that defines on which layers the override is used. + +#### `ko_make_with_layers_and_negmods(modifiers, key, replacement, layers, negative_mods)` +Additionally takes a bitmask `negative_mods` that defines which modifiers may not be pressed for this override to activate. + +#### `ko_make_with_layers_negmods_and_options(modifiers, key, replacement, layers, negative_mods, options)` +Additionally takes a bitmask `options` that specifies additional options. See `ko_option_t` for available options. + +For more customization possibilities, you may directly create a `key_override_t`, which allows you to customize even more behavior. Read further below for details and examples. + +## Simple Example + +This shows how the mentioned example of sending `delete` when `shift` + `backspace` are pressed is realized: + +```c +const key_override_t delete_key_override = ko_make_basic(MOD_MASK_SHIFT, KC_BSPACE, KC_DELETE); + +// This globally defines all key overrides to be used +const key_override_t **key_overrides = (const key_override_t *[]){ + &delete_key_override, + NULL // Null terminate the array of overrides! +}; +``` + +## Intermediate Difficulty Examples + +### Media Controls & Screen Brightness + +In this example a single key is configured to control media, volume and screen brightness by using key overrides. + +- The key is set to send `play/pause` in the keymap. + +The following key overrides will be configured: + +- `Ctrl` + `play/pause` will send `next track`. +- `Ctrl` + `Shift` + `play/pause` will send `previous track`. +- `Alt` + `play/pause` will send `volume up`. +- `Alt` + `Shift` + `play/pause` will send `volume down`. +- `Ctrl` + `Alt` + `play/pause` will send `brightness up`. +- `Ctrl` + `Alt` + `Shift` + `play/pause` will send `brightness down`. + + +```c +const key_override_t next_track_override = + ko_make_with_layers_negmods_and_options( + MOD_MASK_CTRL, // Trigger modifiers: ctrl + KC_MPLY, // Trigger key: play/pause + KC_MNXT, // Replacement key + ~0, // Activate on all layers + MOD_MASK_SA, // Do not activate when shift or alt are pressed + ko_option_no_reregister_trigger); // Specifies that the play key is not registered again after lifting ctrl + +const key_override_t prev_track_override = ko_make_with_layers_negmods_and_options(MOD_MASK_CS, KC_MPLY, + KC_MPRV, ~0, MOD_MASK_ALT, ko_option_no_reregister_trigger); + +const key_override_t vol_up_override = ko_make_with_layers_negmods_and_options(MOD_MASK_ALT, KC_MPLY, + KC_VOLU, ~0, MOD_MASK_CS, ko_option_no_reregister_trigger); + +const key_override_t vol_down_override = ko_make_with_layers_negmods_and_options(MOD_MASK_SA, KC_MPLY, + KC_VOLD, ~0, MOD_MASK_CTRL, ko_option_no_reregister_trigger); + +const key_override_t brightness_up_override = ko_make_with_layers_negmods_and_options(MOD_MASK_CA, KC_MPLY, + KC_BRIU, ~0, MOD_MASK_SHIFT, ko_option_no_reregister_trigger); + +const key_override_t brightness_down_override = ko_make_basic(MOD_MASK_CSA, KC_MPLY, KC_BRID); + +// This globally defines all key overrides to be used +const key_override_t **key_overrides = (const key_override_t *[]){ + &next_track_override, + &prev_track_override, + &vol_up_override, + &vol_down_override, + &brightness_up_override, + &brightness_down_override, + NULL +}; +``` + +### Flexible macOS-friendly Grave Escape +The [Grave Escape feature](https://docs.qmk.fm/using-qmk/advanced-keycodes/feature_grave_esc) is limited in its configurability and has [bugs when used on macOS](https://docs.qmk.fm/using-qmk/advanced-keycodes/feature_grave_esc#caveats). Key overrides can be used to achieve a similar functionality as Grave Escape, but with more customization and without bugs on macOS. + +```c +// Shift + esc = ~ +const key_override_t tilde_esc_override = ko_make_basic(MOD_MASK_SHIFT, KC_ESC, S(KC_GRAVE)); + +// GUI + esc = ` +const key_override_t grave_esc_override = ko_make_basic(MOD_MASK_GUI, KC_ESC, KC_GRAVE); + +const key_override_t **key_overrides = (const key_override_t *[]){ + &tilde_esc_override, + &grave_esc_override, + NULL +}; +``` + +In addition to not encountering unexpected bugs on macOS, you can also change the behavior as you wish. Instead setting `GUI` + `ESC` = `` ` `` you may change it to an arbitrary other modifier, for example `Ctrl` + `ESC` = `` ` ``. + +## Advanced Examples +### Modifiers as Layer Keys + +Do you really need a dedicated key to toggle your fn layer? With key overrides, perhaps not. This example shows how you can configure to use `rGUI` + `rAlt` (right GUI and right alt) to access a momentary layer like an fn layer. With this you completely eliminate the need to use a dedicated layer key. Of course the choice of modifier keys can be changed as needed, `rGUI` + `rAlt` is just an example here. + +```c +// This is called when the override activates and deactivates. Enable the fn layer on activation and disable on deactivation +bool momentary_layer(bool key_down, void *layer) { + if (key_down) { + layer_on((uint8_t)(uintptr_t)layer); + } else { + layer_off((uint8_t)(uintptr_t)layer); + } + + return false; +} + +const key_override_t fn_override = {.trigger_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), // + .layers = ~(1 << LAYER_FN), // + .suppressed_mods = MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL), // + .options = ko_option_no_unregister_on_other_key_down, // + .negative_mod_mask = (uint8_t) ~(MOD_BIT(KC_RGUI) | MOD_BIT(KC_RCTL)), // + .custom_action = momentary_layer, // + .context = (void *)LAYER_FN, // + .trigger = KC_NO, // + .replacement = KC_NO, // + .enabled = NULL}; +``` + +## Keycodes + +You can enable, disable and toggle all key overrides on the fly. + +|Keycode |Description |Function Equivalent| +|----------|---------------------------------|--------| +|`KEY_OVERRIDE_ON` |Turns on Key Override feature | `key_override_on(void)`| +|`KEY_OVERRIDE_OFF` |Turns off Key Override feature |`key_override_off(void)`| +|`KEY_OVERRIDE_TOGGLE` |Toggles Key Override feature on and off |`key_override_toggle(void)`| + +## Reference for `key_override_t` + +Advanced users may need more customization than what is offered by the simple `ko_make` initializers. For this, directly create a `key_override_t` value and set all members. Below is a reference for all members of `key_override_t`. + +| Member | Description | +|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `uint16_t trigger` | The non-modifier keycode that triggers the override. This keycode, and the necessary modifiers (`trigger_mods`) must be pressed to activate this override. Set this to the keycode of the key that should activate the override. Set to `KC_NO` to require only the necessary modifiers to be pressed and no non-modifier. | +| `uint8_t trigger_mods` | Which mods need to be down for activation. If both sides of a modifier are set (e.g. left ctrl and right ctrl) then only one is required to be pressed (e.g. left ctrl suffices). Use the `MOD_MASK_XXX` and `MOD_BIT()` macros for this. | +| `layer_state_t layers` | This is a BITMASK (!), defining which layers this override applies to. To use this override on layer i set the ith bit `(1 << i)`. | +| `uint8_t negative_mod_mask` | Which modifiers cannot be down. It must hold that `(active_modifiers & negative_mod_mask) == 0`, otherwise the key override will not be activated. An active override will be deactivated once this is no longer true. | +| `uint8_t suppressed_mods` | Modifiers to 'suppress' while the override is active. To suppress a modifier means that even though the modifier key is held down, the host OS sees the modifier as not pressed. Can be used to suppress the trigger modifiers, as a trivial example. | +| `uint16_t replacement` | The complex keycode to send as replacement when this override is triggered. This can be a simple keycode, a key-modifier combination (e.g. `C(KC_A)`), or `KC_NO` (to register no replacement keycode). Use in combination with suppressed_mods to get the correct modifiers to be sent. | +| `ko_option_t options` | Options controlling the behavior of the override, such as what actions are allowed to activate the override. | +| `bool (*custom_action)(bool activated, void *context)` | If not NULL, this function will be called right before the replacement key is registered, along with the provided context and a flag indicating whether the override was activated or deactivated. This function allows you to run some custom actions for specific key overrides. If you return `false`, the replacement key is not registered/unregistered as it would normally. Return `true` to register and unregister the override normally. | +| `void *context` | A context that will be passed to the custom action function. | +| `bool *enabled` | If this points to false this override will not be used. Set to NULL to always have this override enabled. |