From 1df187ed22cf24856eca74462aaeb0002f91b8c4 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Sun, 3 Dec 2023 22:48:47 -0800 Subject: [PATCH 1/6] fix(docs): Add missing page pointers in behaviors config --- docs/docs/config/behaviors.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index 10096a41f63..452768070eb 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -49,7 +49,7 @@ You can use the following nodes to tweak the default behaviors: 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](../behaviors/hold-tap.md) for more details and examples. +See the [hold-tap behavior](../behaviors/hold-tap.md) documentation for more details and examples. ### Devicetree @@ -157,6 +157,8 @@ The following macro-specific behaviors can be added at any point in the `binding Creates a custom behavior that triggers one of two behaviors depending on whether certain modifiers are held. +See the [mod-morph behavior](../behaviors/mod-morph.md) documentation for more details and examples. + ### Devicetree Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-mod-morph.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-mod-morph.yaml) @@ -208,6 +210,8 @@ You can use the following nodes to tweak the default behaviors: Creates a custom behavior that triggers a different behavior corresponding to the number of times the key is tapped. +See the [tap dance behavior](../behaviors/tap-dance.md) documentation for more details and examples. + ### Devicetree Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-tap-dance.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-tap-dance.yaml) From 9c1d79973853d9e6a57d8304e14641ab91d47244 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Sun, 3 Dec 2023 23:02:35 -0800 Subject: [PATCH 2/6] fix(docs): Fix sticky key #binding-cells --- docs/docs/config/behaviors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index 452768070eb..c1d44f697c3 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -193,7 +193,7 @@ Applies to: `compatible = "zmk,behavior-sticky-key"` | Property | Type | Description | Default | | ------------------ | ------------- | ------------------------------------------------------------------------ | ------- | -| `#binding-cells` | int | Must match the number of parameters the `bindings` behavior uses | | +| `#binding-cells` | int | Must be `<1>` | | | `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 | From 04b0dff6c266b546158a365311c24f29fc6a5fda Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Sun, 3 Dec 2023 23:16:58 -0800 Subject: [PATCH 3/6] fix(docs): Note -var definition files for macros --- docs/docs/config/behaviors.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index c1d44f697c3..db24f805b7c 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -126,7 +126,11 @@ See the [macro behavior](../behaviors/macros.md) documentation for more details ### Devicetree -Definition file: [zmk/app/dts/bindings/behaviors/zmk,behavior-macro.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-macro.yaml) +Definition files: + +- [zmk/app/dts/bindings/behaviors/zmk,behavior-macro.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-macro.yaml) +- [zmk/app/dts/bindings/behaviors/zmk,behavior-macro-one-param.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-macro-one-param.yaml) +- [zmk/app/dts/bindings/behaviors/zmk,behavior-macro-two-param.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-macro-two-param.yaml) | Property | Type | Description | Default | | ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | From b55ccc5896344a47dc157a1142ba11bcb10d9d83 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Sun, 3 Dec 2023 23:04:28 -0800 Subject: [PATCH 4/6] feat(docs): Document sensor-rotate in behaviors config --- docs/docs/config/behaviors.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index db24f805b7c..119b3d22615 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -183,6 +183,27 @@ You can use the following nodes to tweak the default behaviors: | -------- | ----------------------------------------- | | `&gresc` | [Grave escape](../behaviors/mod-morph.md) | +## Sensor Rotation + +Creates a custom behavior which sends a tap of other behaviors when a sensor is rotated. +Has two variants: with `compatible = "zmk,behavior-sensor-rotate"` it accepts no parameters when used, whereas with `compatible = "zmk,behavior-sensor-rotate-var"` it accepts two parameters. + +See the [sensor rotation behavior](../behaviors/sensor-rotate.md) documentation for more details and examples. + +### Devicetree + +Definition files: + +- [zmk/app/dts/bindings/behaviors/zmk,behavior-sensor-rotate.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-sensor-rotate.yaml) +- [zmk/app/dts/bindings/behaviors/zmk,behavior-sensor-rotate-var.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-sensor-rotate-var.yaml) + +| Property | Type | Description | Default | +| ----------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `compatible` | string | Sensor rotation type, **must be _one_ of**:
• `"zmk,behavior-sensor-rotate"`
• `"zmk,behavior-sensor-rotate-var"` | | +| `#sensor-binding-cells` | int | Number of params accepted (depends on `compatible` property), **must be _one_ of**:
• `<0>`
• `<2>` | | +| `bindings` | phandle array | A list of two behaviors to trigger for each rotation direction, must include parameters for `"zmk,behavior-sensor-rotate"` and exclude them for `"zmk,behavior-sensor-rotate-var"` | | +| `tap-ms` | int | The tap duration (between press and release events) in milliseconds for behaviors in `bindings` | 5 | + ## Sticky Key Creates a custom behavior that triggers a behavior and keeps it pressed it until another key is pressed and released. From a1b7fefe122214dcd538f40ea96edc0fe2ef3d47 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Sun, 3 Dec 2023 23:28:41 -0800 Subject: [PATCH 5/6] feat(docs): Note how parameters are forwarded for behaviors --- docs/docs/config/behaviors.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index 119b3d22615..bb5f14e14d7 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -68,6 +68,8 @@ Applies to: `compatible = "zmk,behavior-hold-tap"` | `retro-tap` | bool | Triggers the tap behavior on release if no other key was pressed during a hold | false | | `hold-trigger-key-positions` | array | If set, pressing the hold-tap and then any key position _not_ in the list triggers a tap. | | +This behavior forwards the first parameter it receives to the parameter of the first behavior specified in `bindings`, and second parameter to the parameter of the second behavior. + The `flavor` property may be one of: - `"hold-preferred"` @@ -140,6 +142,8 @@ Definition files: | `wait-ms` | int | The default time to wait (in milliseconds) before triggering the next behavior. | `CONFIG_ZMK_MACRO_DEFAULT_WAIT_MS` | | `tap-ms` | int | The default time to wait (in milliseconds) between the press and release events of a tapped behavior. | `CONFIG_ZMK_MACRO_DEFAULT_TAP_MS` | +With `compatible = "zmk,behavior-macro-one-param"` or `compatible = "zmk,behavior-macro-two-param"`, this behavior forwards the parameters it receives according to the `¯o_param_*` control behaviors noted below. + ### Macro Control Behaviors The following macro-specific behaviors can be added at any point in the `bindings` list to change how the macro triggers subsequent behaviors. @@ -204,6 +208,8 @@ Definition files: | `bindings` | phandle array | A list of two behaviors to trigger for each rotation direction, must include parameters for `"zmk,behavior-sensor-rotate"` and exclude them for `"zmk,behavior-sensor-rotate-var"` | | | `tap-ms` | int | The tap duration (between press and release events) in milliseconds for behaviors in `bindings` | 5 | +With `compatible = "zmk,behavior-sensor-rotate-var"`, this behavior forwards the first parameter it receives to the parameter of the first behavior specified in `bindings`, and second parameter to the parameter of the second behavior. + ## Sticky Key Creates a custom behavior that triggers a behavior and keeps it pressed it until another key is pressed and released. @@ -224,6 +230,8 @@ Applies to: `compatible = "zmk,behavior-sticky-key"` | `quick-release` | bool | Release the sticky key on the next key press instead of release | false | | `ignore-modifiers` | bool | If enabled, pressing a modifier key does not cancel the sticky key | true | +This behavior forwards the one parameter it receives to the parameter of the behavior specified in `bindings`. + You can use the following nodes to tweak the default behaviors: | Node | Behavior | From 3e4aca1e619d40c5696af4e8329cfd6c74567c88 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Tue, 5 Dec 2023 14:14:06 -0800 Subject: [PATCH 6/6] refactor(docs): Convert breaks to unordered lists in tables Co-authored-by: Joel Spadin --- docs/docs/config/behaviors.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/docs/config/behaviors.md b/docs/docs/config/behaviors.md index bb5f14e14d7..09498e6bebd 100644 --- a/docs/docs/config/behaviors.md +++ b/docs/docs/config/behaviors.md @@ -134,13 +134,13 @@ Definition files: - [zmk/app/dts/bindings/behaviors/zmk,behavior-macro-one-param.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-macro-one-param.yaml) - [zmk/app/dts/bindings/behaviors/zmk,behavior-macro-two-param.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-macro-two-param.yaml) -| Property | Type | Description | Default | -| ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `compatible` | string | Macro type, **must be _one_ of**:
• `"zmk,behavior-macro"`
• `"zmk,behavior-macro-one-param"`
• `"zmk,behavior-macro-two-param"` | | -| `#binding-cells` | int | Number of params accepted (depends on `compatible` property), **must be _one_ of**:
• `<0>`
• `<1>`
• `<2>` | | -| `bindings` | phandle array | List of behaviors to trigger | | -| `wait-ms` | int | The default time to wait (in milliseconds) before triggering the next behavior. | `CONFIG_ZMK_MACRO_DEFAULT_WAIT_MS` | -| `tap-ms` | int | The default time to wait (in milliseconds) between the press and release events of a tapped behavior. | `CONFIG_ZMK_MACRO_DEFAULT_TAP_MS` | +| Property | Type | Description | Default | +| ---------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| `compatible` | string | Macro type, **must be _one_ of**:
  • `"zmk,behavior-macro"`
  • `"zmk,behavior-macro-one-param"`
  • `"zmk,behavior-macro-two-param"`
| | +| `#binding-cells` | int | Must be
  • `<0>` if `compatible = "zmk,behavior-macro"`
  • `<1>` if `compatible = "zmk,behavior-macro-one-param"`
  • `<2>` if `compatible = "zmk,behavior-macro-two-param"`
| | +| `bindings` | phandle array | List of behaviors to trigger | | +| `wait-ms` | int | The default time to wait (in milliseconds) before triggering the next behavior. | `CONFIG_ZMK_MACRO_DEFAULT_WAIT_MS` | +| `tap-ms` | int | The default time to wait (in milliseconds) between the press and release events of a tapped behavior. | `CONFIG_ZMK_MACRO_DEFAULT_TAP_MS` | With `compatible = "zmk,behavior-macro-one-param"` or `compatible = "zmk,behavior-macro-two-param"`, this behavior forwards the parameters it receives according to the `¯o_param_*` control behaviors noted below. @@ -203,8 +203,8 @@ Definition files: | Property | Type | Description | Default | | ----------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| `compatible` | string | Sensor rotation type, **must be _one_ of**:
• `"zmk,behavior-sensor-rotate"`
• `"zmk,behavior-sensor-rotate-var"` | | -| `#sensor-binding-cells` | int | Number of params accepted (depends on `compatible` property), **must be _one_ of**:
• `<0>`
• `<2>` | | +| `compatible` | string | Sensor rotation type, **must be _one_ of**:
  • `"zmk,behavior-sensor-rotate"`
  • `"zmk,behavior-sensor-rotate-var"`
| | +| `#sensor-binding-cells` | int | Must be
  • `<0>` if `compatible = "zmk,behavior-sensor-rotate"`
  • `<2>` if `compatible = "zmk,behavior-sensor-rotate-var"`
| | | `bindings` | phandle array | A list of two behaviors to trigger for each rotation direction, must include parameters for `"zmk,behavior-sensor-rotate"` and exclude them for `"zmk,behavior-sensor-rotate-var"` | | | `tap-ms` | int | The tap duration (between press and release events) in milliseconds for behaviors in `bindings` | 5 |