Skip to content

Commit

Permalink
docs: Add documentation for config options
Browse files Browse the repository at this point in the history
  • Loading branch information
@joelspadin
joelspadin committed Mar 7, 2021
1 parent a7c6e08 commit 44bc226
Show file tree
Hide file tree
Showing 15 changed files with 1,108 additions and 28 deletions.
100 changes: 100 additions & 0 deletions docs/docs/config/behaviors.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
---
title: Behavior Configuration
sidebar_label: Behaviors
---

Some behaviors have properties to adjust how they behave. These can also be used
as templates to create custom behaviors when none of the built-in behaviors do
what you want.

See [Configuration Overview](/docs/config/index) for instructions on how to
change these settings.

See the [zmk/app/dts/behaviors/](https://github.com/zmkfirmware/zmk/tree/main/app/dts/behaviors)
folder for all default behaviors.

## Hold-Tap

Creates a custom behavior that triggers one behavior when a key is held or a
different one when the key is tapped.

See the [hold-tap behavior documentation](/docs/behaviors/hold-tap) for more details and examples.

### Devicetree

Applies to: `compatible = "zmk,behavior-hold-tap"`

| Property | Type | Description | Default |
| ----------------- | ------------- | ------------------------------------------------------------------------------ | ------------------ |
| `label` | string | Unique label for the node | |
| `#binding-cells` | int | Must be `<2>` | |
| `bindings` | phandle array | A list of two behaviors: one for hold and one for tap | |
| `tapping-term-ms` | int | How long in milliseconds the key must be held to trigger a hold | |
| `quick-tap-ms` | int | Tap twice within this period in milliseconds to trigger a tap, even when held | -1 |
| `flavor` | string | Adjusts how the behavior chooses between hold and tap | `"hold-preferred"` |
| `retro-tap` | bool | Triggers the tap behavior on release if no other key was pressed during a hold | false |

The `flavor` property may be one of:

- `"hold-preferred"`
- `"balanced"`
- `"tap-preferred"`

See the [hold-tap behavior documentation](/docs/behaviors/hold-tap) for an explanation of each flavor.

| Node | Behavior |
| ----- | --------------------------------------------- |
| `&lt` | [Layer-tap](/docs/behaviors/layers#layer-tap) |
| `&mt` | [Mod-tap](/docs/behaviors/mod-tap) |

## Mod-Morph

Creates a custom behavior that triggers one behavior when a key is pressed without
certain modifiers held or a different one if certain modifiers are held.

### Devicetree

Applies to: `compatible = "zmk,behavior-mod-morph"`

| Property | Type | Description |
| ---------------- | ------------- | ----------------------------------------------------------------------------------- |
| `label` | string | Unique label for the node |
| `#binding-cells` | int | Must be `<0>` |
| `bindings` | phandle array | A list of two behaviors: one for normal press and one for mod morphed press |
| `mods` | int | A bit field of modifiers which will switch to the morph behavior if any are pressed |

See [dt-bindings/zmk/modifiers.h](https://github.com/zmkfirmware/zmk/blob/main/app/include/dt-bindings/zmk/modifiers.h)
for a list of modifiers.

You can use the following nodes to tweak the default behaviors:

| Node | Behavior |
| -------- | ------------ |
| `&gresc` | Grave escape |

## Sticky Key

Creates a custom behavior that triggers a behavior and keeps it pressed it until
another key is pressed and released.

See the [sticky key behavior](/docs/behaviors/sticky-key) and [sticky layer behavior](/docs/behaviors/sticky-layer)
documentation for more details and examples.

### Devicetree

Applies to: `compatible = "zmk,behavior-sticky-key"`

| Property | Type | Description | Default |
| ------------------ | ------------- | ------------------------------------------------------------------------ | ------- |
| `label` | string | Unique label for the node | |
| `#binding-cells` | int | Must match the number of parameters the `bindings` behavior uses | |
| `bindings` | phandle array | A behavior (without parameters) to trigger | |
| `release-after-ms` | int | Releases the key after this many milliseconds if no other key is pressed | 1000 |
| `quick-release` | bool | Release the sticky key on the next key press instead of release | false |

You can use the following nodes to tweak the default behaviors:

| Node | Behavior |
| ----- | -------------------------------------------- |
| `&sk` | [Sticky key](/docs/behaviors/sticky-key) |
| `&sl` | [Sticky layer](/docs/behaviors/sticky-layer) |
42 changes: 42 additions & 0 deletions docs/docs/config/combos.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: Combo Configuration
sidebar_label: Combos
---

See the [Combos feature page](/docs/features/combos) for more details and examples.

See [Configuration Overview](/docs/config/index) for instructions on how to
change these settings.

## Kconfig

Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/Kconfig)

| Config | Type | Description | Default |
| ------------------------------------- | ---- | -------------------------------------------------------------- | ------- |
| `CONFIG_ZMK_COMBO_MAX_PRESSED_COMBOS` | int | Maximum number of combos that can be active at the same time | 4 |
| `CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY` | int | Maximum number of active combos that use the same key position | 5 |
| `CONFIG_ZMK_COMBO_MAX_KEYS_PER_COMBO` | int | Maximum number of keys to press to activate a combo | 4 |

## Devicetree

Applies to: `compatible = "zmk,combo"`

Definition file: [zmk/app/dts/bindings/zmk,combos.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Ccombos.yaml)

The `zmk,combos` node itself has no properties. It should have one child node
per combo.

Each child node can have the following properties:

| Property | Type | Description | Default |
| --------------- | ------------- | ---------------------------------------------------------------------------------- | ------- |
| `bindings` | phandle-array | A [behavior](/docs/features/keymaps#behaviors) to run when the combo is triggered | |
| `key-positions` | array | A list of key position indices for the keys which should trigger the combo | |
| `timeout-ms` | int | All the keys must be pressed within this time in milliseconds to trigger the combo | 50 |
| `slow-release` | bool | Releases the combo when all keys are released instead of when any key is released | false |
| `layers` | array | A list of layers on which the combo may be triggered. `-1` allows all layers. | `<-1>` |

The `key-positions` array must not be longer than the `CONFIG_ZMK_COMBO_MAX_KEYS_PER_COMBO` setting,
which defaults to 4. If you want a combo that triggers when pressing 5 keys, then you must
change the setting to 5.
44 changes: 44 additions & 0 deletions docs/docs/config/displays.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: Display Configuration
sidebar_label: Displays
---

See the [displays feature page](/docs/features/displays) for more details.

See [Configuration Overview](/docs/config/index) for instructions on how to
change these settings.

## Kconfig

Definition files:

- [zmk/app/src/display/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/src/display/Kconfig)
- [zmk/app/src/display/widgets/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/src/display/widgets/Kconfig)

| Config | Type | Description | Default |
| ---------------------------------- | ---- | ---------------------------------------------------- | ------- |
| `CONFIG_ZMK_DISPLAY` | bool | Enable support for displays | n |
| `CONFIG_ZMK_WIDGET_LAYER_STATUS` | bool | Enable a widget to show the highest, active layer | y |
| `CONFIG_ZMK_WIDGET_BATTERY_STATUS` | bool | Enable a widget to show battery charge information | y |
| `CONFIG_ZMK_WIDGET_OUTPUT_STATUS` | bool | Enable a widget to show the current output (USB/BLE) | y |
| `CONFIG_ZMK_WIDGET_WPM_STATUS` | bool | Enable a widget to show words per minute | n |

If `CONFIG_ZMK_DISPLAY` is enabled, exactly one of the following options must be set to `y`:

| Config | Type | Description | Default |
| ------------------------------------------- | ---- | ------------------------------ | ------- |
| `CONFIG_ZMK_DISPLAY_STATUS_SCREEN_BUILT_IN` | bool | Use the built-in status screen | y |
| `CONFIG_ZMK_DISPLAY_STATUS_SCREEN_CUSTOM` | bool | Use a custom status screen | n |

You must also configure the Zephyr driver for your display. Here are the Kconfig options for common displays.

- [SSD1306](https://docs.zephyrproject.org/latest/reference/kconfig/CONFIG_SSD1306.html)

## Devicetree

See the Zephyr Devicetree bindings for your display. Here are the bindings for common displays:

- [SSD1306 (i2c)](https://docs.zephyrproject.org/latest/reference/devicetree/bindings/solomon,ssd1306fb-i2c.html)
- [SSD1306 (spi)](https://docs.zephyrproject.org/latest/reference/devicetree/bindings/solomon,ssd1306fb-spi.html)

A full list of supported drivers can be found in [Zephyr's Devicetree bindings index](https://docs.zephyrproject.org/latest/reference/devicetree/bindings.html).
43 changes: 43 additions & 0 deletions docs/docs/config/encoders.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: Encoder Configuration
sidebar_label: Encoders
---

See the [Encoders feature page](/docs/features/encoders) for more details,
including instructions for adding encoder support to a board.

See [Configuration Overview](/docs/config/index) for instructions on how to
change these settings.

## EC11 Encoders

### Kconfig

Definition file: [zmk/app/drivers/sensor/ec11/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/drivers/sensor/ec11/Kconfig)

| Config | Type | Description | Default |
| ------------------------------- | ---- | -------------------------------- | ------- |
| `CONFIG_EC11` | bool | Enable EC11 encoders | n |
| `CONFIG_EC11_THREAD_PRIORITY` | int | Priority of the encoder thread | 10 |
| `CONFIG_EC11_THREAD_STACK_SIZE` | int | Stack size of the encoder thread | 1024 |

If `CONFIG_EC11` is enabled, exactly one of the following options must be set to `y`:

| Config | Type | Description |
| ----------------------------------- | ---- | ----------------------------------------------- |
| `CONFIG_EC11_TRIGGER_NONE` | bool | No trigger (encoders are disabled) |
| `CONFIG_EC11_TRIGGER_GLOBAL_THREAD` | bool | Process encoder interrupts on the global thread |
| `CONFIG_EC11_TRIGGER_OWN_THREAD` | bool | Process encoder interrupts on their own thread |

### Devicetree

Applies to: `compatible = "alps,ec11"`

Definition file: [zmk/app/drivers/zephyr/dts/bindings/sensor/alps,ec11.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/drivers/zephyr/dts/bindings/sensor/alps%2Cec11.yaml)

| Property | Type | Description | Default |
| ------------ | ---------- | ------------------------------------- | ------- |
| `label` | string | Unique label for the node | |
| `a-gpios` | GPIO array | GPIO connected to the encoder's A pin | |
| `b-gpios` | GPIO array | GPIO connected to the encoder's B pin | |
| `resolution` | int | Number of encoder pulses per tick | 1 |
Loading

0 comments on commit 44bc226

Please sign in to comment.