|
|
|
|
@ -0,0 +1,150 @@
|
|
|
|
|
---
|
|
|
|
|
id: keymaps
|
|
|
|
|
title: Keymaps & Behaviors
|
|
|
|
|
sidebar_label: Keymaps
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
ZMK uses an declarative approach to keymaps, instead of using C code for all keymap configuration.
|
|
|
|
|
Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for
|
|
|
|
|
supporting dynamic loading of declarative keymaps, e.g. over USB Mass Storage or via a custom BLE
|
|
|
|
|
service.
|
|
|
|
|
|
|
|
|
|
:::note
|
|
|
|
|
For advanced users looking to implement custom behaviors for their keymaps, this will be possible
|
|
|
|
|
in the future by allowing user configs to add to the CMake application built by Zephyr.
|
|
|
|
|
:::
|
|
|
|
|
|
|
|
|
|
## Big Picture
|
|
|
|
|
|
|
|
|
|
All keyboard definitions (complete boards or shields) include the _default_ keymap for that keyboard,
|
|
|
|
|
so ZMK can produce a "stock" firmware for that keyboard without any further modifications. For users
|
|
|
|
|
looking to customize their keyboard's behavior, they can copy the stock `.keymap` file into their
|
|
|
|
|
user config directory, and customize the keymap to their liking.
|
|
|
|
|
|
|
|
|
|
## Behaviors
|
|
|
|
|
|
|
|
|
|
ZMK implements the concept of "behaviors", which can be bound to a certain key position, sensor (encoder),
|
|
|
|
|
or layer, to perform certain actions when events occur for that binding (e.g. when a certain key position
|
|
|
|
|
is pressed or released, or an encoder triggers a rotation event).
|
|
|
|
|
|
|
|
|
|
For example, the simplest behavior in ZMK is the "key press" behavior, which responds to key position
|
|
|
|
|
(a certain spot on the keyboard), and when that position is pressed, send a keycode to the host, and
|
|
|
|
|
when the key position is released, updates the host to notify of the keycode being released.
|
|
|
|
|
|
|
|
|
|
For the full set of possible behaviors, start at the [Key Press](/docs/behavior/key-press) behavior.
|
|
|
|
|
|
|
|
|
|
## Layers
|
|
|
|
|
|
|
|
|
|
Like many mechanical keyboard firmwares, ZMK keymaps are composed of a collection of layers, with a
|
|
|
|
|
minimum of at least one layer that is the default, usually near the bottom of the "stack". Each layer
|
|
|
|
|
in ZMK contains a set of bindings that bind a certain behavior to a certain key position in that layer.
|
|
|
|
|
|
|
|
|
|
In addition to the base default layer (which can be changed), certain bound behaviors may also
|
|
|
|
|
enable/disable additional layers "on top" of the default layer.
|
|
|
|
|
|
|
|
|
|
**TODO**: A diagram to help visualize layers
|
|
|
|
|
|
|
|
|
|
When a key location is pressed/released, the stack of all active layers from "top to bottom" is used,
|
|
|
|
|
and the event is sent to the behavior bound at that position in each layer, for it to perform whatever
|
|
|
|
|
actions it wants to in reaction to the event. Those behaviors can choose to "handle" the event, and stop
|
|
|
|
|
it from being passed to any lower layers, or may choose to "pass it along", and let the next layer
|
|
|
|
|
in the stack _also_ get the event.
|
|
|
|
|
|
|
|
|
|
## Behavior Bindings
|
|
|
|
|
|
|
|
|
|
Binding a behavior at a certain key position may include up to two extra parameters that are used to
|
|
|
|
|
alter the behavior when that specific key position is activated/deactived. For example, when binding
|
|
|
|
|
the "key press" (`kp`) behavior at a certain key position, you must specific _which_ keycode should
|
|
|
|
|
be used for that key position.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
&kp A
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
In this case, the `A` is actually a define for the raw HID keycode, to make keymaps easier to read and write.
|
|
|
|
|
|
|
|
|
|
For example of a binding that uses two parameters, you can see how "mod-tap" (`mt`) is bound:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
&mt MOD_LSFT D
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Here, the first parameter is the set of modifiers that should be used for the "hold" behavior, and the second
|
|
|
|
|
parameter is the keycode that should be sent when triggering the "tap" behavior.
|
|
|
|
|
|
|
|
|
|
## Keymap File
|
|
|
|
|
|
|
|
|
|
A keymap file is composed of several sections, that together make up a valid devicetree file for describing the keymap and its layers.
|
|
|
|
|
|
|
|
|
|
### Includes
|
|
|
|
|
|
|
|
|
|
THe devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders
|
|
|
|
|
for what would otherwise be cryptic integer keycodes, etc. This also allows bringing in _other_ devicetree nodes from separate files.
|
|
|
|
|
|
|
|
|
|
The top two lines of most keymaps should include:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
#include <behaviors.dtsi>
|
|
|
|
|
#include <dt-bindings/zmk/keys.h>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The first defines the nodes for all the available behaviors in ZMK, which will be referenced in the behavior bindings. This is how bindings like `&kp` can reference the key press behavior defined with an anchor name of `kp`.
|
|
|
|
|
|
|
|
|
|
The second include brings in the defines for all the keycodes (e.g. `A`, `NUM_1`, `M_PLAY`) and the modifiers (e.g. `MOD_LSFT`) used for various behavior bindings.
|
|
|
|
|
|
|
|
|
|
### Root devicetree Node
|
|
|
|
|
|
|
|
|
|
ALl the remaining keymap nodes will be nested inside of the root devicetree node, like so:
|
|
|
|
|
|
|
|
|
|
```devicetree
|
|
|
|
|
/ {
|
|
|
|
|
// Everything else goes here!
|
|
|
|
|
};
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Layers
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
layers {
|
|
|
|
|
compatible = "zmk,layers";
|
|
|
|
|
|
|
|
|
|
default: layer_0 {
|
|
|
|
|
label = "DEFAULT";
|
|
|
|
|
// ---------------------------------------------------------------------------------------------------------------------------------
|
|
|
|
|
// | ESC | Q | W | E | R | T | | Y | U | I | O | P | \ |
|
|
|
|
|
// | TAB | A | S | D | F | G | | H | J | K | L | ; | ' |
|
|
|
|
|
// | SHIFT | Z | X | C | V | B | L SHIFT | L SHIFT | | L SHIFT | L SHIFT | N | M | , | . | / | CTRL |
|
|
|
|
|
// | GUI | DEL | RET | SPACE | ESC | | RET | SPACE | TAB | BSPC | R-ALT |
|
|
|
|
|
bindings = <
|
|
|
|
|
&kp ESC &kp Q &kp W &kp E &kp R &kp T &kp Y &kp U &kp I &kp O &kp P &kp BSLH
|
|
|
|
|
&kp TAB &kp A &kp S &mt MOD_LCTL D &mt MOD_LSFT F &kp G &kp H &mt MOD_LSFT J &mt MOD_LCTL K &kp L &kp SCLN &kp QUOT
|
|
|
|
|
&kp LSFT &kp Z &kp X &kp C &kp V &kp B &kp LSFT &kp LSFT &kp LSFT &kp LSFT &kp N &kp M &kp CMMA &kp DOT &kp FSLH &kp RCTL
|
|
|
|
|
&kp LGUI &kp DEL &kp RET &kp SPC &mo 1 &mo 2 &kp SPC &kp RET &kp BKSP &kp RALT
|
|
|
|
|
>;
|
|
|
|
|
|
|
|
|
|
sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>;
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Keymap
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
keymap0: keymap {
|
|
|
|
|
compatible = "zmk,keymap";
|
|
|
|
|
label ="Default Kyria Keymap";
|
|
|
|
|
layers = <&default>;
|
|
|
|
|
};
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Chosen Keymap
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
chosen {
|
|
|
|
|
zmk,keymap = &keymap0;
|
|
|
|
|
};
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Complete Example
|
|
|
|
|
|
|
|
|
|
You can see a complete example if you see the [stock Kyria keymap](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/kyria.keymap).
|
Pete Johanson