Jacob/zmk
1
0
Fork 0
forked from kofal.net/zmk
Code Pull Requests Activity

refactor(docs): Convert the keymaps section into a base folder (#2430)

Browse Source 
Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
This commit is contained in:
Nicolas Munnich
2024-08-21 19:39:18 +02:00
committed by GitHub
parent 503f6c8e58
commit 5f056f7199
77 changed files with 399 additions and 526 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/docs/features/bluetooth.md
View File

@@ -24,7 +24,7 @@ device should receive the keyboard input.
:::note[Connection Management]
When pairing to a host device ZMK saves bond information to the selected profile. It will not replace this automatically when you initiate pairing with another device. To pair with a new device select an unused profile with or clearing the current profile, using the [`&bt` behavior](../behaviors/bluetooth.md) on your keyboard.
When pairing to a host device ZMK saves bond information to the selected profile. It will not replace this automatically when you initiate pairing with another device. To pair with a new device select an unused profile with or clearing the current profile, using the [`&bt` behavior](../keymaps/behaviors/bluetooth.md) on your keyboard.
A ZMK device may show as "connected" on multiple hosts at the same time. This is working as intended, and only the host associated with the active profile will receive keystrokes.
@@ -34,7 +34,7 @@ Failure to manage the profiles can result in unexpected/broken behavior with hos
## Bluetooth Behavior
Management of the bluetooth in ZMK is accomplished using the [`&bt` behavior](../behaviors/bluetooth.md). Be sure to refer to that documentation to learn how to manage profiles, switch between connected hosts, etc.
Management of the bluetooth in ZMK is accomplished using the [`&bt` behavior](../keymaps/behaviors/bluetooth.md). Be sure to refer to that documentation to learn how to manage profiles, switch between connected hosts, etc.
## Refreshing the HID Descriptor
@@ -43,7 +43,7 @@ This in turn requires [HID report descriptors](https://docs.kernel.org/hid/hidin
Firmware changes that would modify the descriptor include the following:
- Changing any of the settings under the [HID category](../config/system.md#hid), including enabling/disabling NKRO or HID indicators
- Enabling mouse features, such as adding [mouse keys](../behaviors/mouse-emulation.md) to your keymap
- Enabling mouse features, such as adding [mouse keys](../keymaps/behaviors/mouse-emulation.md) to your keymap
While the descriptor refresh happens on boot for USB, hosts will frequently cache this descriptor for BLE devices.
In order to refresh this cache, you need to remove the keyboard from the host device, clear the profile associated with the host on the keyboard, then pair again.

51
docs/docs/features/combos.md
View File

@@ -1,51 +0,0 @@
---
title: 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 configured in your `.keymap` file, but are separate from the `keymap` node found there, since they are processed before the normal keymap. They are specified like this:
```dts
/ {
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.
- All the keys in `key-positions` must be pressed within `timeout-ms` milliseconds to trigger the combo.
- `key-positions` is an array of key positions. See the info section below about how to figure out the positions on your board.
- `layers = <0 1...>` will allow limiting a combo to specific layers. This is an _optional_ parameter, when omitted it defaults to global scope.
- `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.
- (advanced) you can specify a `require-prior-idle-ms` value much like for [hold-taps](behaviors/hold-tap.mdx#require-prior-idle-ms). If any non-modifier key is pressed within `require-prior-idle-ms` before a key in the combo, the combo will not trigger.
:::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`, `&lt` etc.
:::note[Source-specific behaviors on split keyboards]
Invoking a [source-specific behavior](split-keyboards.md#source-locality-behaviors) such as one of the [reset behaviors](behaviors/reset.md) using a combo will always trigger it on the central side of the keyboard, regardless of the side that the keys corresponding to `key-positions` are on.
:::
See [combo configuration](../config/combos.md) for advanced configuration options.

56
docs/docs/features/conditional-layers.md
View File

@@ -1,56 +0,0 @@
---
title: Conditional Layers
---
Conditional layers support activating a particular layer (called the `then-layer`) when all layers
in a specified set (called the `if-layers`) are active. This feature generalizes what's commonly
known as tri-layer support, allowing activation of two layers (usually called "lower" and "raise")
to trigger a third (usually called "adjust").
Another way to think of this feature is as a simple combo system for layers, just like the usual
[combos for behaviors](combos.md).
## Configuration
Conditional layers are configured via a `conditional_layers` node in your `.keymap` file as follows:
```dts
/ {
conditional_layers {
compatible = "zmk,conditional-layers";
tri_layer {
if-layers = <1 2>;
then-layer = <3>;
};
};
};
```
Each conditional layer configuration may have whatever name you like, but it's helpful to choose
something self explanatory like `tri_layer`. The following properties are supported:
- `if-layers` specifies a set of layer numbers, all of which must be active for the conditional
layer to trigger.
- `then-layer` specifies a layer number that should be activated if and only if all the layers
specified in the `if-layers` property are active.
Therefore, in this example, layer 3 ("adjust") will be activated if and only if both layers 1
("lower") and 2 ("raise") are active.
:::tip
Since higher-numbered layers are processed first, a `then-layer` should generally have a higher
number than its associated `if-layers` so the `then-layer` can be accessed when active.
:::
:::info
Activating a `then-layer` in one conditional layer configuration can trigger the `if-layers`
condition in another configuration, possibly repeatedly.
:::
:::warning
When configured as a `then-layer`, a layer's activation status is entirely controlled by the
conditional layers feature. Even if the layer is activated for another reason (such as a
[momentary layer](../behaviors/layers.md#momentary-layer) behavior), it will be immediately
deactivated if the associated `then-layers` configuration is not met. As such, we recommend
avoiding using regular layer behaviors for `then-layer` targets.
:::

2
docs/docs/features/displays.md
View File

@@ -6,5 +6,5 @@ sidebar_label: Displays
Displays in ZMK are currently a proof of concept and official support is coming soon.
:::info
Although ZMK-powered keyboards _are_ capable of utilizing OLED and ePaper displays, the Displays feature is not yet considered production-ready due to an issue where the display remains blank after resuming from [external power cutoff](../behaviors/power.md#external-power-control). This issue can be tracked on GitHub at [zmkfirmware/zmk #674](https://github.com/zmkfirmware/zmk/issues/674).
Although ZMK-powered keyboards _are_ capable of utilizing OLED and ePaper displays, the Displays feature is not yet considered production-ready due to an issue where the display remains blank after resuming from [external power cutoff](../keymaps/behaviors/power.md#external-power-control). This issue can be tracked on GitHub at [zmkfirmware/zmk #674](https://github.com/zmkfirmware/zmk/issues/674).
:::

4
docs/docs/features/encoders.md
View File

@@ -19,13 +19,13 @@ Keyboards and macropads with encoder support will typically take the two EC11 pi
### Rotation
Rotation is handled separately as a type of sensor. The behavior for this is set in `sensor-bindings`. See [Sensor Rotation](../behaviors/sensor-rotate.md) for customizing this behavior.
Rotation is handled separately as a type of sensor. The behavior for this is set in `sensor-bindings`. See [Sensor Rotation](../keymaps/behaviors/sensor-rotate.md) for customizing this behavior.
```dts
sensor-bindings = <BINDING [CW_KEY] [CCW_KEY]>;
```
- `BINDING` is either a user-defined behavior, or `&inc_dec_kp` for key presses (see [Key Press](../behaviors/key-press.md) for details on available keycodes).
- `BINDING` is either a user-defined behavior, or `&inc_dec_kp` for key presses (see [Key Press](../keymaps/behaviors/key-press.md) for details on available keycodes).
- `CW_KEY` is the keycode activated by a clockwise turn.
- `CCW_KEY` is the keycode activated by a counter-clockwise turn.

171
docs/docs/features/keymaps.mdx
View File

@@ -1,171 +0,0 @@
---
title: Keymaps & Behaviors
sidebar_label: Keymaps
---
import KeymapExample from "../keymap-example.md";
ZMK uses a 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, see the [overview page for behaviors](../behaviors/index.mdx).
## 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 "layer stack". Each layer
in ZMK contains a set of bindings that bind a certain behavior to a certain key position in that layer.
| ![Diagram of three layers](../assets/features/keymaps/layer-diagram.png) |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| _A simplified diagram showing three layers. The layout of each layer is the same (they all contain four keys), but the behavior bindings within each layer can be different._ |
All layers are assigned and referred to by a natural number, with the base layer being layer `0`. It is common to [use the C preprocessor to "name" layers](../behaviors/layers.md#defines-to-refer-to-layers), making them more legible.
The default layer (the base layer with index 0) is always enabled. Certain bound behaviors may enable/disable additional layers.
When a key location is pressed/released, the _highest-valued currently active_ layer is used. The press/release event is sent to the behavior bound at that position in said layer, for it to perform whatever actions it wants to in reaction to the event. The behavior can choose to "consume" the event, or "pass it along" and let the next highest-valued active layer _also_ get the event (whose behavior may continue "passing it along").
Note that the _activation_ order isn't relevant for determining the priority of active layers, it is determined _only_ by the definition order.
:::tip
If you wish to use multiple base layers (with a [toggle](../behaviors/layers.md#toggle-layer)), e.g. one for QWERTY and another for Colemak layouts, you will want these layers to have the lowest value possible. In other words, one should be layer `0`, and the other should be layer `1`. This allows other momentary layers activated on top of them to work with both.
:::
## 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/deactivated. For example, when binding
the "key press" (`kp`) behavior at a certain key position, you must specify _which_ keycode should
be used for that key position.
```dts
&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:
```dts
&mt LSHIFT 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:
```dts
#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`, `N1`, `C_PLAY`) and the modifiers (e.g. `LSHIFT`) used for various behavior bindings.
### Root Devicetree Node
All the remaining keymap nodes will be nested inside of the root devicetree node, like so:
```dts
/ {
// Everything else goes here!
};
```
### Keymap Node
Nested under the devicetree root, is the keymap node. The node _name_ itself is not critical, but the node **MUST** have a property
`compatible = "zmk,keymap"` in order to be used by ZMK.
```dts
keymap {
compatible = "zmk,keymap";
// Layer nodes go here!
};
```
### Layers
Each layer of your keymap will be nested under the keymap node. Here is an example of a layer in a 6-key macropad.
```dts
keymap {
compatible = "zmk,keymap";
default_layer { // Layer 0
// ----------------------------------------------
// | Z | M | K |
// | A | B | C |
bindings = <
&kp Z &kp M &kp K
&kp A &kp B &kp C
>;
};
};
```
Each layer should have:
1. A `bindings` property this will be a list of [behavior bindings](../behaviors/index.mdx), one for each key position for the keyboard.
1. (Optional) A `sensor-bindings` property that will be a list of behavior bindings for each sensor on the keyboard. (Currently, only encoders are supported as sensor hardware, but in the future devices like trackpoints would be supported the same way)
### Multiple Layers
Layers are numbered in the order that they appear in keymap node - the first layer is `0`, the second layer is `1`, etc.
Here is an example of a trio of layers for a simple 6-key macropad:
<KeymapExample />
:::note
Even if layer `1` was to be activated after `2`, layer `2` would still have priority as it is higher valued. Behaviors such as [To Layer (`&to`)](../behaviors/layers.md#to-layer) can be used to enable one layer _and disable all other non-default layers_, though.
:::
### Complete Example
Some examples of complete keymaps for a keyboard are:
- [`corne.keymap`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/corne/corne.keymap)
- [`kyria.keymap`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/kyria.keymap)
- [`lily58.keymap`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/lily58/lily58.keymap)
:::tip
Every keyboard comes with a "default keymap". For additional examples, the [ZMK tree's `app/boards` folder](https://github.com/zmkfirmware/zmk/blob/main/app/boards) can be browsed.
:::

6
docs/docs/features/soft-off.md
View File

@@ -24,7 +24,7 @@ Refer to the [soft off config](../config/power.md#soft-off) for details on enabl
## Soft Off With Existing Designs
For existing designs, using soft off is as simple as placing the [Soft Off Behavior](../behaviors/soft-off.md) in your keymap and then invoking it.
For existing designs, using soft off is as simple as placing the [Soft Off Behavior](../keymaps/behaviors/soft-off.md) in your keymap and then invoking it.
You can then wake up the keyboard by pressing the reset button once, and repeating this for each side for split keyboards.
@@ -83,7 +83,7 @@ GPIO keys are defined using child nodes under the `gpio-keys` compatible node. E
### Soft Off Behavior Instance
To use the [soft off behavior](../behaviors/soft-off.md) outside of a keymap, add an instance of the behavior to your `.overlay`/`.dts` file:
To use the [soft off behavior](../keymaps/behaviors/soft-off.md) outside of a keymap, add an instance of the behavior to your `.overlay`/`.dts` file:
```
/ {
@@ -99,7 +99,7 @@ To use the [soft off behavior](../behaviors/soft-off.md) outside of a keymap, ad
### KScan Sideband Behavior
The kscan sideband behavior driver will be used to trigger the [soft off behavior](../behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver. What kscan driver will vary for simple direct pin vs. matrix-integrated hardware combo.
The kscan sideband behavior driver will be used to trigger the [soft off behavior](../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver. What kscan driver will vary for simple direct pin vs. matrix-integrated hardware combo.
#### Simple direct pin

14
docs/docs/features/split-keyboards.md
View File

@@ -68,23 +68,23 @@ If the central keyboard part is either advertising for a pairing or waiting for
## Behaviors with Locality
Most ZMK [behaviors](../behaviors/index.mdx) are processed exclusively on the central of the split keyboard as it handles the keymap state and any communication with the host devices.
Most ZMK [behaviors](../keymaps/behaviors/index.mdx) are processed exclusively on the central of the split keyboard as it handles the keymap state and any communication with the host devices.
However, certain behaviors have "global" or "source" localities, where they can affect the peripherals when invoked.
### Global Locality Behaviors
These are behaviors that affect all keyboard parts, such as changing lighting effects:
- [RGB underglow behaviors](../behaviors/underglow.md)
- [Backlight behaviors](../behaviors/backlight.md)
- [Power management behaviors](../behaviors/power.md)
- [Soft off behavior](../behaviors/soft-off.md)
- [RGB underglow behaviors](../keymaps/behaviors/underglow.md)
- [Backlight behaviors](../keymaps/behaviors/backlight.md)
- [Power management behaviors](../keymaps/behaviors/power.md)
- [Soft off behavior](../keymaps/behaviors/soft-off.md)
### Source Locality Behaviors
These behaviors only affect the keyboard part that they are invoked from:
- [Reset behaviors](../behaviors/reset.md)
- [Reset behaviors](../keymaps/behaviors/reset.md)
:::warning[Nesting behaviors with locality]
Currently there is [an issue](https://github.com/zmkfirmware/zmk/issues/1494) preventing both global and source locality behaviors from working as expected if they are invoked from another behavior, such as a hold-tap, tap dance or a mod-morph.
@@ -97,5 +97,5 @@ This is because the key bindings are processed on the central side which would t
:::
:::note[Combos]
[Combos](combos.md) always invoke behaviors with source locality on the central.
[Combos](../keymaps/combos.md) always invoke behaviors with source locality on the central.
:::