From 58de2eb5e96937ece2129d8b47997349aaf5e6c7 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com> Date: Fri, 15 Nov 2024 00:44:40 +0100 Subject: docs: touchups on the soft off information for improved clarity. (#2647) --- .../hardware-integration/includes/_gpio-key-matrix.md | 2 +- .../hardware-integration/includes/_gpio-key-wakeup.md | 1 + .../hardware-integration/includes/_soft-off-behavior.md | 1 + .../hardware-integration/includes/_soft-off-waker.md | 1 + docs/docs/keymaps/behaviors/soft-off.md | 10 ++++++++++ 5 files changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md b/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md index d4fbe44c9e..affed12ef1 100644 --- a/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md +++ b/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md @@ -11,4 +11,4 @@ Here is an example for a keyboard with a GPIO pin that reads from the matrix: }; ``` -Matrix inputs are triggered by pulling the specified pin high, typically by pressing some combination of switches which connects the matrix input to a matrix output. +MCU inputs are triggered by pulling the specified pin high, typically by pressing some combination of switches which connects the MCU input to an MCU output. diff --git a/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md b/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md index 7f8995b5bc..0a02289441 100644 --- a/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md +++ b/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md @@ -12,3 +12,4 @@ Here is an example for a keyboard with a GPIO pin reused from a matrix kscan: ``` The GPIO settings should match those in the kscan, so the above would be set to `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)` for a direct kscan. +The specified pin should be the MCU input pin of the switch used for waking from soft off (for a `col2row` matrix, the MCU input pins are the row pins). diff --git a/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md b/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md index b4377b902e..9967f39893 100644 --- a/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md +++ b/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md @@ -8,6 +8,7 @@ Behind the scenes, a hardware dedicated GPIO pin utilizes the [soft off behavior hw_soft_off: hw_soft_off { compatible = "zmk,behavior-soft-off"; #binding-cells = <0>; + split-peripheral-off-on-press; // Turn peripheral off immediately for reliability hold-time-ms = <2000>; // Only turn off if the key is held for 2 seconds or longer. }; }; diff --git a/docs/docs/development/hardware-integration/includes/_soft-off-waker.md b/docs/docs/development/hardware-integration/includes/_soft-off-waker.md index 214abc970a..2bf5ffef89 100644 --- a/docs/docs/development/hardware-integration/includes/_soft-off-waker.md +++ b/docs/docs/development/hardware-integration/includes/_soft-off-waker.md @@ -14,3 +14,4 @@ We need to add another device which will be enabled only when the keyboard is go ``` The properties for the `gpio-key-wakeup-trigger` node can be found in the [appropriate configuration section](../../../config/power.md#gpio-key-wakeup-trigger). +In particular, note the `extra-gpios` property containing the MCU output pins of any keys used to wake the keyboard (for a `col2row` matrix, these are your columns). diff --git a/docs/docs/keymaps/behaviors/soft-off.md b/docs/docs/keymaps/behaviors/soft-off.md index d51a49255e..0b664df2e4 100644 --- a/docs/docs/keymaps/behaviors/soft-off.md +++ b/docs/docs/keymaps/behaviors/soft-off.md @@ -38,3 +38,13 @@ By default, the keyboard will be turned off as soon as the key bound to the beha }; }; ``` + +The peripheral half of a [split keyboard](../../features/split-keyboards.md) will always enter the soft off state immediately when triggering the behavior, regardless of the `hold-time-ms` setting. This is to ensure reliability, as otherwise the central may enter the soft off state before notifying the peripheral that it should also do so. + +If you wish to change this setting, and thus accept the potential for reliability issues, you may remove the `split-peripheral-off-on-press` flag from the behavior: + +```dts +&soft_off { + /delete-property/ split-peripheral-off-on-press; +}; +``` -- cgit v1.2.3