diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs/behaviors/combos.md | 52 | ||||
| -rw-r--r-- | docs/docs/intro.md | 2 | ||||
| -rw-r--r-- | docs/sidebars.js | 1 |
3 files changed, 54 insertions, 1 deletions
diff --git a/docs/docs/behaviors/combos.md b/docs/docs/behaviors/combos.md new file mode 100644 index 0000000..e9b0176 --- /dev/null +++ b/docs/docs/behaviors/combos.md @@ -0,0 +1,52 @@ +--- +title: Combo Behavior +sidebar_label: Combos +--- + +## Summary + +Combo keys are a way to combine multiple keypresses to output a different key. For example, you can hit the Q and W keys on your keyboard to output escape. + +### Configuration + +Combos are specified like this: + +``` +/ { + combos { + compatible = "zmk,combos"; + combo_esc { + timeout-ms = <50>; + key-positions = <0 1>; + bindings = <&kp ESC>; + }; + }; +}; +``` + +- The name of the combo doesn't really matter, but convention is to start the node name with `combo_`. +- The `compatible` property should always be `"zmk,combos"` for combos. +- `timeout-ms` is the number of milliseconds that all keys of the combo must be pressed. +- `key-positions` is an array of key positions. See the info section below about how to figure out the positions on your board. +- `bindings` is the behavior that is activated when the behavior is pressed. +- (advanced) you can specify `slow-release` if you want the combo binding to be released when all key-positions are released. The default is to release the combo as soon as any of the keys in the combo is released. + +:::info + +Key positions are numbered like the keys in your keymap, starting at 0. So, if the first key in your keymap is `Q`, this key is in position `0`. The next key (possibly `W`) will have position 1, etcetera. + +::: + +### Advanced usage + +- Partially overlapping combos like `0 1` and `0 2` are supported. +- Fully overlapping combos like `0 1` and `0 1 2` are supported. +- You are not limited to `&kp` bindings. You can use all ZMK behaviors there, like `&mo`, `&bt`, `&mt`, `<` etc. + +### Advanced configuration + +There are three global combo parameters which are set through KConfig. You can set them in the `<boardname>.conf` file in the same directory as your keymap file. + +- `CONFIG_ZMK_COMBO_MAX_PRESSED_COMBOS` is the number of combos that can be active at the same time. Default 4. +- `CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY` is the maximum number of combos that can be active on a key position. Defaults to 5. (So you can have 5 separate combos that use position `3` for example) +- `CONFIG_ZMK_COMBO_MAX_KEYS_PER_COMBO` is the maximum number of keys that need to be pressed to activate a combo. Default 4. If you want a combo that triggers when pressing 5 keys, you'd set this to 5 for example. diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 57670ea..2215291 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -26,7 +26,7 @@ ZMK is currently missing some features found in other popular firmware. This tab | [Display Support](features/displays)[^2] | 🚧 | 🚧 | ✅ | | [RGB Underglow](features/underglow) | ✅ | ✅ | ✅ | | One Shot Keys | ✅ | ✅ | ✅ | -| [Combo Keys](https://github.com/zmkfirmware/zmk/pull/504) | 🚧 | | ✅ | +| [Combo Keys](behaviors/combos) | ✅ | | ✅ | | Macros | 🚧 | ✅ | ✅ | | Mouse Keys | 💡 | ✅ | ✅ | | Low Active Power Usage | ✅ | | | diff --git a/docs/sidebars.js b/docs/sidebars.js index 8fc1dc5..d095a47 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -20,6 +20,7 @@ module.exports = { "behaviors/misc", "behaviors/hold-tap", "behaviors/mod-tap", + "behaviors/combos", "behaviors/reset", "behaviors/bluetooth", "behaviors/outputs", |