From e0e0928f9c185bd73ad1391605d945e5e3adaace Mon Sep 17 00:00:00 2001 From: Joel Spadin Date: Tue, 3 May 2022 21:28:41 -0500 Subject: [PATCH] fix(docs): Update config docs for review feedback --- docs/docs/config/combos.md | 16 ++++++++-------- docs/docs/config/kscan.md | 10 +++++++++- docs/docs/features/combos.md | 2 +- docs/docs/features/debouncing.md | 10 ++++++++-- docs/docs/features/underglow.md | 2 +- 5 files changed, 27 insertions(+), 13 deletions(-) diff --git a/docs/docs/config/combos.md b/docs/docs/config/combos.md index 479cd8e5..cd351125 100644 --- a/docs/docs/config/combos.md +++ b/docs/docs/config/combos.md @@ -23,7 +23,7 @@ If you want a combo that triggers when pressing 5 keys, you must set `CONFIG_ZMK ## Devicetree -Applies to: `compatible = "zmk,combo"` +Applies to: `compatible = "zmk,combos"` Definition file: [zmk/app/dts/bindings/zmk,combos.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Ccombos.yaml) @@ -31,12 +31,12 @@ The `zmk,combos` node itself has no properties. It should have one child node pe Each child node can have the following properties: -| Property | Type | Description | Default | -| --------------- | ------------- | ---------------------------------------------------------------------------------- | ------- | -| `bindings` | phandle-array | A [behavior](../features/keymaps.md#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>` | +| Property | Type | Description | Default | +| --------------- | ------------- | ----------------------------------------------------------------------------------------------------- | ------- | +| `bindings` | phandle-array | A [behavior](../features/keymaps.md#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 in `key-positions` 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. diff --git a/docs/docs/config/kscan.md b/docs/docs/config/kscan.md index 410f5588..d81d26b6 100644 --- a/docs/docs/config/kscan.md +++ b/docs/docs/config/kscan.md @@ -21,7 +21,7 @@ Definition files: | `CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS` | int | Global debounce time for key press in milliseconds | -1 | | `CONFIG_ZMK_KSCAN_DEBOUNCE_RELEASE_MS` | int | Global debounce time for key release in milliseconds | -1 | -If the debounce press/release values are set to any value other than `-1`, they override the `debounce-press-ms` and `debounce-release-ms` devicetree properties for all keyboard scan drivers which support them. +If the debounce press/release values are set to any value other than `-1`, they override the `debounce-press-ms` and `debounce-release-ms` devicetree properties for all keyboard scan drivers which support them. See the [debouncing documentation](../features/debouncing.md) for more details. ### Devicetree @@ -36,6 +36,10 @@ Applies to: [`/chosen` node](https://docs.zephyrproject.org/latest/guides/dts/in Keyboard scan driver which works like a regular matrix but uses a demultiplexer to drive the rows or columns. This allows N GPIOs to drive N2 rows or columns instead of just N like with a regular matrix. +:::note +Currently this driver does not honor the `CONFIG_ZMK_KSCAN_DEBOUNCE_*` settings. +::: + ### Devicetree Applies to: `compatible = "zmk,kscan-gpio-demux"` @@ -54,6 +58,10 @@ Definition file: [zmk/app/drivers/zephyr/dts/bindings/kscan/zmk,kscan-gpio-demux Keyboard scan driver where each key has a dedicated GPIO. +:::note +Currently this driver does not honor the `CONFIG_ZMK_KSCAN_DEBOUNCE_*` settings. +::: + ### Kconfig Definition file: [zmk/app/drivers/kscan/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/drivers/kscan/Kconfig) diff --git a/docs/docs/features/combos.md b/docs/docs/features/combos.md index 5c73a845..09191896 100644 --- a/docs/docs/features/combos.md +++ b/docs/docs/features/combos.md @@ -25,7 +25,7 @@ Combos configured in your `.keymap` file, but are separate from the `keymap` nod - 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 must be pressed within `timeout-ms` milliseconds to trigger the combo. +- 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. diff --git a/docs/docs/features/debouncing.md b/docs/docs/features/debouncing.md index f0022a59..9629131d 100644 --- a/docs/docs/features/debouncing.md +++ b/docs/docs/features/debouncing.md @@ -19,14 +19,20 @@ socket or using some sharp tweezers to bend the contacts back together. ## Debounce Configuration +:::note +Currently only the `zmk,kscan-gpio-matrix` driver supports these options. The other drivers have not yet been updated to use the new debouncing code. +::: + ### Global Options You can set these options in your `.conf` file to control debouncing globally. -Values must be <= 127. +Values must be <= 16383. - `CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS`: Debounce time for key press in milliseconds. Default = 5. - `CONFIG_ZMK_KSCAN_DEBOUNCE_RELEASE_MS`: Debounce time for key release in milliseconds. Default = 5. +If one of these options is set, it overrides the matching per-driver option described below. + For example, this would shorten the debounce time for both press and release: ```ini @@ -37,7 +43,7 @@ CONFIG_ZMK_KSCAN_DEBOUNCE_RELEASE_MS=3 ### Per-driver Options You can add these Devicetree properties to a kscan node to control debouncing for -that instance of the driver. Values must be <= 127. +that instance of the driver. Values must be <= 16383. - `debounce-press-ms`: Debounce time for key press in milliseconds. Default = 5. - `debounce-release-ms`: Debounce time for key release in milliseconds. Default = 5. diff --git a/docs/docs/features/underglow.md b/docs/docs/features/underglow.md index af182fae..020701fd 100644 --- a/docs/docs/features/underglow.md +++ b/docs/docs/features/underglow.md @@ -145,7 +145,7 @@ Once you have your `led_strip` properly defined you need to add it to the root d }; ``` -Finally you need to enable the `CONFIG_ZMK_RGB_UNDERGLOW` and `CONFIG*_STRIP` configuration values in the `.conf` file of your board (or set a default in the `Kconfig.defconfig`): +Finally you need to enable the `CONFIG_ZMK_RGB_UNDERGLOW` and `CONFIG_*_STRIP` configuration values in the `.conf` file of your board (or set a default in the `Kconfig.defconfig`): ``` CONFIG_ZMK_RGB_UNDERGLOW=y