Skip to content

Commit

Permalink
feat(docs): Update configuration overview
Browse files Browse the repository at this point in the history
  • Loading branch information
joelspadin committed Apr 30, 2022
1 parent 3f7f4ab commit 157d5bb
Showing 1 changed file with 20 additions and 10 deletions.
30 changes: 20 additions & 10 deletions docs/docs/config/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Configuration Overview
sidebar_label: Overview
---

ZMK has several configuration settings that can be changed to change the behavior of your keyboard. They are set in either Kconfig or Devicetree files.
ZMK has many configuration settings that can be changed to change the behavior of your keyboard. They are set in either Kconfig or Devicetree files.

This page describes the Kconfig and Devicetree file formats and how to change settings in them. See the other pages in the configuration section for a list of settings you can change.

Expand Down Expand Up @@ -41,7 +41,7 @@ ZMK will search the board folder for the following config files:
- `<board>.dts` (Devicetree)
- `<board>.keymap` (Devictree, standalone boards only)

For more documentation on creating and configuring a new board, see [Zephyr's board porting guide](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html#write-kconfig-files).
For more documentation on creating and configuring a new board, see [Zephyr's board porting guide](https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html#write-kconfig-files).

### Shield Folder

Expand All @@ -58,7 +58,7 @@ ZMK will search the shield folder for the following config files:
- `<shield>.overlay` (Devicetree)
- `<shield>.keymap` (Devicetree)

For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/latest/guides/porting/shields.html) and [ZMK's new keyboard shield](/docs/development/new-shield) guide.
For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/latest/hardware/porting/shields.html) and [ZMK's new keyboard shield](/docs/development/new-shield) guide.

## Kconfig Files

Expand All @@ -74,7 +74,7 @@ CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y

The list of available settings is determined by various files in ZMK whose names start with `Kconfig`. Note that options are _not_ prefixed with `CONFIG_` in these files.

See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/latest/guides/kconfig/index.html) for more details on Kconfig files.
See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/latest/build/kconfig/index.html) for more details on Kconfig files.

### KConfig Value Types

Expand Down Expand Up @@ -117,7 +117,7 @@ Devicetree files look like this:

Devicetree properties apply to specific nodes in the tree instead of globally. The properties that can be set for each node are determined by `.yaml` files in ZMK in the various `dts/bindings` folders.

See [Zephyr's Devicetree guide](https://docs.zephyrproject.org/latest/guides/dts/index.html) for more details on Devicetree files.
See [Zephyr's Devicetree guide](https://docs.zephyrproject.org/latest/build/dts/index.html) for more details on Devicetree files.

### Changing Devicetree Properties

Expand All @@ -138,7 +138,7 @@ The part before the colon, `kscan0`, is a label. This is optional, and it provid
The `compatible` property indicates what type of node it is. Search this documentation for the text inside the quotes to see which properties the node
supports. You can also search ZMK for a file whose name is the value of the `compatible` property with a `.yaml` file extension.

To set a property, see below for examples for common property types, or see [Zephyr's Devicetree documentation](https://docs.zephyrproject.org/latest/guides/dts/intro.html#writing-property-values) for more details on the syntax for properties.
To set a property, see below for examples for common property types, or see [Zephyr's Devicetree documentation](https://docs.zephyrproject.org/latest/build/dts/intro.html#writing-property-values) for more details on the syntax for properties.

To change a property for an existing node, first find the node you want to change and find its label. Next, outside of any other node, write an ampersand (`&`)
followed by the node's label, an opening curly brace (`{`), one or more new property values, a closing curly brace (`}`), and a semicolon (`;`).
Expand All @@ -147,13 +147,23 @@ For example, to adjust the debouncing of the `zmk,kscan-gpio-matrix` node shown

```devicetree
&kscan0 {
debounce-period = <7>;
debounce-press-ms = <0>;
};
```

If the node you want to edit doesn't have a label, you can also write a new tree and it will be merged with the existing tree, overriding any properties. Adding this to your keymap would be equivalent to the previous example.

```devicetree
/ {
kscan {
debounce-press-ms = <0>;
};
};
```

### Devicetree Property Types

These are some of the property types you will see most often when working with ZMK. [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/latest/guides/dts/bindings.html) provides more detailed information and a full list of types.
These are some of the property types you will see most often when working with ZMK. [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/latest/build/dts/bindings.html) provides more detailed information and a full list of types.

#### bool

Expand Down Expand Up @@ -207,14 +217,14 @@ Example: `property = <&none &mo 1>;`

Values can also be split into multiple blocks, e.g. `property = <&none>, <&mo 1>;`

See the documentation for "phandle-array" in [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/latest/guides/dts/bindings.html)
See the documentation for "phandle-array" in [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/latest/build/dts/bindings.html)
for more details on how parameters are associated with nodes.

#### GPIO array

This is just a phandle array. The documentation lists this as a different type to make it clear which properties expect an array of GPIOs.

Each item in the array should be a label for a GPIO node (the names of which differ between hardware platforms) followed by an index and configuration flags. See [Zephyr's GPIO documentation](https://docs.zephyrproject.org/latest/reference/peripherals/gpio.html) for a full list of flags.
Each item in the array should be a label for a GPIO node (the names of which differ between hardware platforms) followed by an index and configuration flags. See [Zephyr's GPIO documentation](https://docs.zephyrproject.org/latest/hardware/peripherals/gpio.html) for a full list of flags.

Example:

Expand Down

0 comments on commit 157d5bb

Please sign in to comment.