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

feat(docs) Adding some additional clarity around low power states (#2330)

Browse Source 
* docs(feat): Adding some additional clarity around low power states, with guide portion moved to hardware integration

---------

Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
This commit is contained in:
Nicolas Munnich
2024-11-02 23:20:31 +01:00
committed by GitHub
parent 249ecbc7e6
commit f4582bdaa7
15 changed files with 531 additions and 321 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/docs/config/kscan.md
View File

@@ -71,15 +71,15 @@ Applies to: `compatible = "zmk,kscan-gpio-direct"`
Definition file: [zmk/app/module/dts/bindings/kscan/zmk,kscan-gpio-direct.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/module/dts/bindings/kscan/zmk%2Ckscan-gpio-direct.yaml)
| Property | Type | Description | Default |
| ------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- | ------- |
| `input-gpios` | GPIO array | Input GPIOs (one per key). Can be either direct GPIO pin or `gpio-key` references. | |
| `debounce-press-ms` | int | Debounce time for key press in milliseconds. Use 0 for eager debouncing. | 5 |
| `debounce-release-ms` | int | Debounce time for key release in milliseconds. | 5 |
| `debounce-scan-period-ms` | int | Time between reads in milliseconds when any key is pressed. | 1 |
| `poll-period-ms` | int | Time between reads in milliseconds when no key is pressed and `CONFIG_ZMK_KSCAN_DIRECT_POLLING` is enabled. | 10 |
| `toggle-mode` | bool | Use toggle switch mode. | n |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard from deep sleep | n |
| Property | Type | Description | Default |
| ------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- | ------- |
| `input-gpios` | GPIO array | Input GPIOs (one per key). Can be either direct GPIO pin or `gpio-key` references | |
| `debounce-press-ms` | int | Debounce time for key press in milliseconds. Use 0 for eager debouncing | 5 |
| `debounce-release-ms` | int | Debounce time for key release in milliseconds | 5 |
| `debounce-scan-period-ms` | int | Time between reads in milliseconds when any key is pressed | 1 |
| `poll-period-ms` | int | Time between reads in milliseconds when no key is pressed and `CONFIG_ZMK_KSCAN_DIRECT_POLLING` is enabled | 10 |
| `toggle-mode` | bool | Use toggle switch mode | n |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard | n |
Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`:
@@ -133,16 +133,16 @@ Applies to: `compatible = "zmk,kscan-gpio-matrix"`
Definition file: [zmk/app/module/dts/bindings/kscan/zmk,kscan-gpio-matrix.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/module/dts/bindings/kscan/zmk%2Ckscan-gpio-matrix.yaml)
| Property | Type | Description | Default |
| ------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- | ----------- |
| `row-gpios` | GPIO array | Matrix row GPIOs in order, starting from the top row | |
| `col-gpios` | GPIO array | Matrix column GPIOs in order, starting from the leftmost row | |
| `debounce-press-ms` | int | Debounce time for key press in milliseconds. Use 0 for eager debouncing. | 5 |
| `debounce-release-ms` | int | Debounce time for key release in milliseconds. | 5 |
| `debounce-scan-period-ms` | int | Time between reads in milliseconds when any key is pressed. | 1 |
| `diode-direction` | string | The direction of the matrix diodes | `"row2col"` |
| `poll-period-ms` | int | Time between reads in milliseconds when no key is pressed and `CONFIG_ZMK_KSCAN_MATRIX_POLLING` is enabled. | 10 |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard from deep sleep | n |
| Property | Type | Description | Default |
| ------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- | ----------- |
| `row-gpios` | GPIO array | Matrix row GPIOs in order, starting from the top row | |
| `col-gpios` | GPIO array | Matrix column GPIOs in order, starting from the leftmost row | |
| `debounce-press-ms` | int | Debounce time for key press in milliseconds. Use 0 for eager debouncing | 5 |
| `debounce-release-ms` | int | Debounce time for key release in milliseconds | 5 |
| `debounce-scan-period-ms` | int | Time between reads in milliseconds when any key is pressed | 1 |
| `diode-direction` | string | The direction of the matrix diodes | `"row2col"` |
| `poll-period-ms` | int | Time between reads in milliseconds when no key is pressed and `CONFIG_ZMK_KSCAN_MATRIX_POLLING` is enabled | 10 |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard | n |
The `diode-direction` property must be one of:
@@ -198,7 +198,7 @@ Definition file: [zmk/app/module/dts/bindings/kscan/zmk,kscan-gpio-charlieplex.y
| `debounce-release-ms` | int | Debounce time for key release in milliseconds. | 5 |
| `debounce-scan-period-ms` | int | Time between reads in milliseconds when any key is pressed. | 1 |
| `poll-period-ms` | int | Time between reads in milliseconds when no key is pressed and `interrupt-gpois` is not set. | 10 |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard from deep sleep | n |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard | n |
Define the transform with a [matrix transform](layout.md#matrix-transform). The row is always the driven pin, and the column always the receiving pin (input to the controller).
For example, in `RC(5,0)` power flows from the 6th pin in `gpios` to the 1st pin in `gpios`.
@@ -335,3 +335,29 @@ Definition file: [zmk/app/dts/bindings/zmk,kscan-mock.yaml](https://github.com/z
| `exit-after` | bool | Exit the program after running all events | false |
The `events` array should be defined using the macros from [app/module/include/dt-bindings/zmk/kscan_mock.h](https://github.com/zmkfirmware/zmk/blob/main/app/module/include/dt-bindings/zmk/kscan_mock.h).
## Kscan Sideband Behavior Driver
The Kscan sideband behaviors node can be used to assign behaviors to keys in a manner distinctly separate from the keymap. These assignments and definitions will not be affected by nor have any effect on the keymap.
### Devicetree
Applies to: `compatible = "zmk,kscan-sideband-behaviors"`
Definition file: [zmk/app/dts/bindings/kscan/zmk,matrix-transform.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/kscan/zmk%2Ckscan-sideband-behaviors.yaml)
| Property | Type | Description |
| --------------- | ------- | --------------------------------------------------------- |
| `kscan` | phandle | Phandle to a kscan containing keys to assign behaviors to |
| `auto-enable` | bool | Enables the sideband instance on startup unconditionally |
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard |
If `auto-enable` is not set, then the sideband behavior will wait for an external activation source before being enabled, e.g. being assigned as the chosen `zmk,kscan`. The `kscan` can contain additional keys, which will be used by the keymap if this node is set as the chosen `zmk,kscan` and has an appropriate matrix transformation defined.
Each child node should have the following properties:
| Property | Type | Description | Default |
| ---------- | ------------- | ------------------------------------------------------------------------------------- | ------- |
| `row` | int | The row index of the key in the `kscan` to intercept and trigger a behavior for | 0 |
| `column` | int | The column index of the key in the `kscan` to intercept and trigger a behavior for | |
| `bindings` | phandle-array | The behavior that should be triggered when the matching row and column event triggers | |