Added soft off setup guide
This commit is contained in:
Nicolas Munnich
parent
8e15b5fa96
commit
04bd81f5aa
10 changed files with 431 additions and 0 deletions
14
docs/docs/advanced-guides/includes/_gpio-key-direct.md
Normal file
14
docs/docs/advanced-guides/includes/_gpio-key-direct.md
Normal file
|
|
@ -0,0 +1,14 @@
|
||||||
|
Here is an example for a keyboard with a dedicated on/off push button that is a direct wire between the GPIO pin and ground:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
keys {
|
||||||
|
compatible = "gpio-keys";
|
||||||
|
soft_off_gpio_key: soft_off_gpio_key {
|
||||||
|
gpios = <&gpio0 2 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
In the above example the soft on/off would be triggered by pulling the specified pin low, typically by pressing a switch that has the other leg connected to ground.
|
||||||
14
docs/docs/advanced-guides/includes/_gpio-key-matrix.md
Normal file
14
docs/docs/advanced-guides/includes/_gpio-key-matrix.md
Normal file
|
|
@ -0,0 +1,14 @@
|
||||||
|
Here is an example for a keyboard with a GPIO pin that reads from the matrix:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
keys {
|
||||||
|
compatible = "gpio-keys";
|
||||||
|
soft_off_gpio_key: soft_off_gpio_key {
|
||||||
|
gpios = <&gpio0 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
14
docs/docs/advanced-guides/includes/_gpio-key-wakeup.md
Normal file
14
docs/docs/advanced-guides/includes/_gpio-key-wakeup.md
Normal file
|
|
@ -0,0 +1,14 @@
|
||||||
|
Here is an example for a keyboard with a GPIO pin reused from a matrix kscan:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
keys {
|
||||||
|
compatible = "gpio-keys";
|
||||||
|
soft_off_gpio_key: soft_off_gpio_key {
|
||||||
|
gpios = <&gpio0 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
37
docs/docs/advanced-guides/includes/_sideband-direct.md
Normal file
37
docs/docs/advanced-guides/includes/_sideband-direct.md
Normal file
|
|
@ -0,0 +1,37 @@
|
||||||
|
### KScan sideband behavior
|
||||||
|
|
||||||
|
The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver.
|
||||||
|
|
||||||
|
With a simple direct pin setup, the [direct kscan](../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix":
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
wakeup_scan: wakeup_scan {
|
||||||
|
compatible = "zmk,kscan-gpio-direct";
|
||||||
|
input-keys = <&soft_off_gpio_key>;
|
||||||
|
wakeup-source;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
With that in place, the kscan sideband behavior will wrap the new driver:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
side_band_behavior_triggers: side_band_behavior_triggers {
|
||||||
|
compatible = "zmk,kscan-sideband-behaviors";
|
||||||
|
|
||||||
|
kscan = <&wakeup_scan>;
|
||||||
|
auto-enable;
|
||||||
|
wakeup-source;
|
||||||
|
|
||||||
|
soft_off {
|
||||||
|
column = <0>;
|
||||||
|
row = <0>;
|
||||||
|
bindings = <&hw_soft_off>;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
As the kscan used only has a single key, both column and row are set to 0. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver).
|
||||||
66
docs/docs/advanced-guides/includes/_sideband-matrix.md
Normal file
66
docs/docs/advanced-guides/includes/_sideband-matrix.md
Normal file
|
|
@ -0,0 +1,66 @@
|
||||||
|
### KScan sideband behavior
|
||||||
|
|
||||||
|
The kscan sideband behavior driver will be used to trigger the [soft off behavior](../../keymaps/behaviors/soft-off.md) "out of band" from the normal keymap processing. To do so, it will decorate/wrap an underlying kscan driver.
|
||||||
|
|
||||||
|
For the matrix-integrated approach you will supplement the existing kscan matrix by adding the additional pin as another entry in
|
||||||
|
the `row-gpios`/`col-gpios` for whichever pins are used to read the matrix state. This approach requires a matrix transform to be present. As an example, consider the following existing kscan matrix:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
kscan: kscan {
|
||||||
|
compatible = "zmk,kscan-gpio-matrix";
|
||||||
|
diode-direction = "col2row";
|
||||||
|
wakeup-source;
|
||||||
|
|
||||||
|
col-gpios
|
||||||
|
= <&gpio0 12 GPIO_ACTIVE_HIGH>
|
||||||
|
, <&gpio1 9 GPIO_ACTIVE_HIGH>
|
||||||
|
;
|
||||||
|
row-gpios
|
||||||
|
= <&gpio0 19 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
|
||||||
|
, <&gpio0 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
|
||||||
|
;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
To supplement it with a soft off input, you would add another row value (without changing the matrix transform):
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
kscan: kscan {
|
||||||
|
compatible = "zmk,kscan-gpio-matrix";
|
||||||
|
diode-direction = "col2row";
|
||||||
|
wakeup-source;
|
||||||
|
|
||||||
|
col-gpios
|
||||||
|
= <&gpio0 12 GPIO_ACTIVE_HIGH>
|
||||||
|
, <&gpio1 9 GPIO_ACTIVE_HIGH>
|
||||||
|
;
|
||||||
|
row-gpios
|
||||||
|
= <&gpio0 19 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
|
||||||
|
, <&gpio0 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
|
||||||
|
, <&gpio0 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
|
||||||
|
;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
With that in place, you would decorate the kscan driver:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
side_band_behavior_triggers: side_band_behavior_triggers {
|
||||||
|
compatible = "zmk,kscan-sideband-behaviors";
|
||||||
|
wakeup-source;
|
||||||
|
kscan = <&kscan>;
|
||||||
|
soft_off {
|
||||||
|
column = <0>;
|
||||||
|
row = <2>;
|
||||||
|
bindings = <&hw_soft_off>;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Critically, the `column` and `row` values would correspond to the location of the added entry. The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver).
|
||||||
|
|
@ -0,0 +1,28 @@
|
||||||
|
### KScan sideband behavior
|
||||||
|
|
||||||
|
With a simple direct pin setup, the [direct kscan](../../config/kscan.md) driver can be used with a [GPIO key](#gpio-key), to make a small "side matrix":
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
wakeup_scan: wakeup_scan {
|
||||||
|
compatible = "zmk,kscan-gpio-direct";
|
||||||
|
input-keys = <&soft_off_gpio_key>;
|
||||||
|
wakeup-source;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
The kscan sideband behavior needs to wrap the new driver to enable it:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
side_band_behavior_triggers: side_band_behavior_triggers {
|
||||||
|
compatible = "zmk,kscan-sideband-behaviors";
|
||||||
|
kscan = <&wakeup_scan>;
|
||||||
|
auto-enable;
|
||||||
|
wakeup-source;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
The properties of the `kscan-sideband-behaviors` node can be found in the [appropriate configuration section](../../config/kscan.md#kscan-sideband-behavior-driver).
|
||||||
15
docs/docs/advanced-guides/includes/_soft-off-behavior.md
Normal file
15
docs/docs/advanced-guides/includes/_soft-off-behavior.md
Normal file
|
|
@ -0,0 +1,15 @@
|
||||||
|
### Soft off behavior instance
|
||||||
|
|
||||||
|
Behind the scenes, a hardware dedicated GPIO pin utilizes the [soft off behavior](../../keymaps/behaviors/soft-off.md) to trigger entering the soft-off state. To use said behavior outside of a keymap, add an instance of the behavior to your `.overlay`/`.dts` file:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
behaviors {
|
||||||
|
hw_soft_off: hw_soft_off {
|
||||||
|
compatible = "zmk,behavior-soft-off";
|
||||||
|
#binding-cells = <0>;
|
||||||
|
hold-time-ms = <2000>; // Only turn off if the key is held for 2 seconds or longer.
|
||||||
|
};
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
16
docs/docs/advanced-guides/includes/_soft-off-waker.md
Normal file
16
docs/docs/advanced-guides/includes/_soft-off-waker.md
Normal file
|
|
@ -0,0 +1,16 @@
|
||||||
|
### Soft off waker
|
||||||
|
|
||||||
|
We need to add another device which will be enabled only when the keyboard is going into soft off state, and will configure the previously declared GPIO key with the correct interrupt configuration to wake the device from soft off once it is pressed.
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
wakeup_scan: wakeup_scan {
|
||||||
|
compatible = "zmk,gpio-key-wakeup-trigger";
|
||||||
|
trigger = <&soft_off_gpio_key>;
|
||||||
|
wakeup-source;
|
||||||
|
extra-gpios = <&gpio0 12 GPIO_ACTIVE_HIGH>
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
The properties for the `gpio-key-wakeup-trigger` node can be found in the [appropriate configuration section](../../config/power.md#gpio-key-wakeup-trigger).
|
||||||
157
docs/docs/advanced-guides/soft-off-setup.mdx
Normal file
157
docs/docs/advanced-guides/soft-off-setup.mdx
Normal file
|
|
@ -0,0 +1,157 @@
|
||||||
|
---
|
||||||
|
title: Adding Soft Off To A Keyboard
|
||||||
|
sidebar_label: Soft Off Setup
|
||||||
|
---
|
||||||
|
|
||||||
|
import Tabs from "@theme/Tabs";
|
||||||
|
import TabItem from "@theme/TabItem";
|
||||||
|
|
||||||
|
import SoftOffBehavior from "./includes/_soft-off-behavior.md";
|
||||||
|
import SoftOffWaker from "./includes/_soft-off-waker.md";
|
||||||
|
import GpioKeyDirect from "./includes/_gpio-key-direct.md";
|
||||||
|
import GpioKeyMatrix from "./includes/_gpio-key-matrix.md";
|
||||||
|
import GpioKeyWakeup from "./includes/_gpio-key-wakeup.md";
|
||||||
|
import SidebandDirect from "./includes/_sideband-direct.md";
|
||||||
|
import SidebandMatrix from "./includes/_sideband-matrix.md";
|
||||||
|
import SidebandWakeupDirect from "./includes/_sideband-wakeup-direct.md";
|
||||||
|
|
||||||
|
Advanced methods of adding [soft off](../features/low-power-states.md#soft-off) to a keyboard are detailed below. The first two tabs describe methods involving hardware changes, while the last describes the firmware changes necessary to define a single specific key switch for waking up.
|
||||||
|
|
||||||
|
<Tabs groupId="advanced-methods" defaultValue="direct">
|
||||||
|
<TabItem value="direct" label="Direct Pin"></TabItem>
|
||||||
|
<TabItem value="matrix" label="Matrix Integrated Pin"></TabItem>
|
||||||
|
<TabItem value="wakeup" label="Wakeup-only Key Switch">
|
||||||
|
The exact method of reusing a key switch to wake from the soft off state
|
||||||
|
differs depending on whether said key switch is part of a direct GPIO kscan
|
||||||
|
or part of a matrix kscan.
|
||||||
|
<Tabs groupId="kscan-type" defaultValue="mkscan">
|
||||||
|
<TabItem value="dkscan" label="Direct GPIO kscan"></TabItem>
|
||||||
|
<TabItem value="mkscan" label="Matrix kscan"></TabItem>
|
||||||
|
</Tabs>
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
## Hardware Changes
|
||||||
|
|
||||||
|
<Tabs groupId="advanced-methods" defaultValue="direct" className="secrettabs">
|
||||||
|
<TabItem value="direct" label="Direct Pin">
|
||||||
|
|
||||||
|
Add a direct push button between a GPIO pin and ground. This button will act as an on/off switch.
|
||||||
|
|
||||||
|
Alternatively, if you wish to integrate a dedicated GPIO pin into a key switch combination using a direct kscan, tie all of the MCU pins that you wish to combine to the dedicated GPIO pin through an OR gate. All firmware changes then follow identically to the direct push button.
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="matrix" label="Matrix Integrated Pin">
|
||||||
|
To integrate the dedicated GPIO pin into your matrix, you will need to tie multiple switch outputs in the matrix together through AND gates and connect the result to the dedicated GPIO pin. This way you can use a (hardware defined) key combination in your existing keyboard matrix to trigger soft on/off.
|
||||||
|
|
||||||
|
Ideally the switches used should be driven by the same matrix output pin so that both will be active simultaneously on the AND gate inputs. The alternative is to connect the switch to two MOSFETs that trigger both the regular matrix connect and the connect to the AND gate to ensure both pins are active/high at the same time even if scanning sets them high at different times.
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="wakeup" label="Wakeup-only Key Switch">
|
||||||
|
No hardware changes are necessary for this approach.
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
## Firmware Changes
|
||||||
|
|
||||||
|
Several items work together to make both triggering soft off properly, and setting up the device to _wake_ from soft off work as expected.
|
||||||
|
|
||||||
|
<Tabs groupId="advanced-methods" defaultValue="direct" className="secrettabs">
|
||||||
|
<TabItem value="direct" label="Direct Pin">
|
||||||
|
<SoftOffBehavior />
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="matrix" label="Matrix Integrated Pin">
|
||||||
|
<SoftOffBehavior />
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="wakeup" label="Wakeup-only Key Switch">
|
||||||
|
|
||||||
|
### Soft off behavior
|
||||||
|
|
||||||
|
For this approach, you will need to make sure that the [soft off behavior](../keymaps/behaviors/soft-off.md) is present in your keymap, to trigger soft off.
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
### GPIO key
|
||||||
|
|
||||||
|
Zephyr's basic [GPIO Key](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/input/gpio-keys.html) concept is used to configure the soft off GPIO pin.
|
||||||
|
{/* secrettabs hides this tab selector. GPIO key changes its "orientation" between simple pin and matrix integrated. */}
|
||||||
|
|
||||||
|
<Tabs groupId="advanced-methods" defaultValue="direct" className="secrettabs">
|
||||||
|
<TabItem value="direct" label="Direct Pin">
|
||||||
|
<GpioKeyDirect />
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="matrix" label="Matrix Integrated Pin">
|
||||||
|
<GpioKeyMatrix />
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="wakeup" label="Wakeup-only Key Switch">
|
||||||
|
<GpioKeyWakeup />
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
GPIO keys are defined using child nodes under the `gpio-keys` compatible node. Each child needs just one property defined:
|
||||||
|
|
||||||
|
- The `gpios` property should be a [phandle-array](https://docs.zephyrproject.org/3.5.0/build/dts/phandles.html#zero-or-more-nodes-with-metadata-phandle-array-type) with a fully defined GPIO pin and with the correct pull up/down and active high/low flags set.
|
||||||
|
|
||||||
|
<Tabs groupId="advanced-methods" defaultValue="direct" className="secrettabs">
|
||||||
|
<TabItem value="direct" label="Direct Pin">
|
||||||
|
<SidebandDirect />
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="matrix" label="Matrix Integrated Pin">
|
||||||
|
<SidebandMatrix />
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="wakeup" label="Wakeup-only Key Switch">
|
||||||
|
<Tabs groupId="kscan-type" defaultValue="mkscan" className="secrettabs">
|
||||||
|
<TabItem value="dkscan" label="Direct GPIO kscan">
|
||||||
|
<SidebandWakeupDirect />
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="mkscan" label="Matrix kscan"></TabItem>
|
||||||
|
</Tabs>
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
<Tabs groupId="advanced-methods" defaultValue="direct" className="secrettabs">
|
||||||
|
<TabItem value="direct" label="Direct Pin"></TabItem>
|
||||||
|
<TabItem value="matrix" label="Matrix Integrated Pin">
|
||||||
|
You also need to update the `zmk,kscan` chosen value to point to the new kscan instance:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
chosen {
|
||||||
|
...
|
||||||
|
zmk,kscan = &side_band_behavior_triggers;
|
||||||
|
...
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
<SoftOffWaker />
|
||||||
|
|
||||||
|
</TabItem>
|
||||||
|
<TabItem value="wakeup" label="Wakeup-only Key Switch">
|
||||||
|
<Tabs groupId="kscan-type" defaultValue="mkscan" className="secrettabs">
|
||||||
|
<TabItem value="dkscan" label="Direct GPIO kscan"></TabItem>
|
||||||
|
<TabItem value="mkscan" label="Matrix kscan"><SoftOffWaker /></TabItem>
|
||||||
|
</Tabs>
|
||||||
|
</TabItem>
|
||||||
|
</Tabs>
|
||||||
|
|
||||||
|
Finally, we will list the `wakeup_scan` device in an additional configuration section so that the ZMK soft off process knows it needs to enable this device as part of the soft off processing so it can wake the keyboard from soft off when pressed:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
soft_off_wakers {
|
||||||
|
compatible = "zmk,soft-off-wakeup-sources";
|
||||||
|
wakeup-sources = <&wakeup_scan>;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Here are the properties for the node:
|
||||||
|
|
||||||
|
- The `compatible` property for the node must be `zmk,soft-off-wakeup-sources`.
|
||||||
|
- The `wakeup-sources` property is a [phandle array](../config/index.md#devicetree-property-types) pointing to all the devices that should be enabled during the shutdown process to be sure they can later wake the keyboard.
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
If you add your kscan to the `wakeup-sources` array, then your keyboard will wake upon pressing any key in your kscan. Essentially, this causes `&soft_off` to behave as one would expect `&sleep` to behave. If you choose to do so, then you can omit everything aside from the `soft_off_wakers` node.
|
||||||
|
:::
|
||||||
70
docs/docs/features/low-power-states.md
Normal file
70
docs/docs/features/low-power-states.md
Normal file
|
|
@ -0,0 +1,70 @@
|
||||||
|
---
|
||||||
|
title: Low Power States
|
||||||
|
sidebar_label: Low Power States
|
||||||
|
---
|
||||||
|
|
||||||
|
## Idle
|
||||||
|
|
||||||
|
In the idle state, peripherals such as displays and lighting are disabled, but the keyboard remains connected to Bluetooth so it can immediately respond when you press a key. Idle state is entered automatically after a timeout period that is [30 seconds by default](../config/power.md#low-power-states).
|
||||||
|
|
||||||
|
## Deep Sleep
|
||||||
|
|
||||||
|
In the deep sleep state, the keyboard additionally disconnects from Bluetooth and any external power output is disabled. This state uses very little power, but it may take a few seconds to reconnect after waking.
|
||||||
|
|
||||||
|
### Config
|
||||||
|
|
||||||
|
Deep sleep must be enabled via its corresponding [config](../config/power.md#low-power-states).
|
||||||
|
|
||||||
|
### Wakeup Sources
|
||||||
|
|
||||||
|
Zephyr has general support for the concept of a device as a "wakeup source". Using deep sleep requires `kscan` nodes to have the `wakeup-source` property to enable them to wake the keyboard, e.g.:
|
||||||
|
|
||||||
|
```dts
|
||||||
|
/ {
|
||||||
|
kscan: kscan {
|
||||||
|
compatible = "zmk,kscan-gpio-matrix";
|
||||||
|
diode-direction = "col2row";
|
||||||
|
wakeup-source;
|
||||||
|
|
||||||
|
...
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
It is recommended to add the `wakeup-source` property to `kscan` devices even if the deep sleep feature is not used -- there is no downside to it.
|
||||||
|
|
||||||
|
## Soft Off
|
||||||
|
|
||||||
|
The soft off feature is used to turn the keyboard on and off explicitly, rather than through a timeout like the deep sleep feature. Depending on the keyboard, this may be through a dedicated on/off push button defined in hardware, or merely through an additional binding in the keymap to turn the device off and an existing reset button to turn the device back on.
|
||||||
|
|
||||||
|
The feature is intended as an alternative to using a hardware switch to physically cut power from the battery to the keyboard. This can be useful for existing PCBs not designed for wireless that don't have a power switch, or for new designs that favor a push button on/off like found on other devices. It yields power savings comparable to the deep sleep state.
|
||||||
|
|
||||||
|
:::note
|
||||||
|
|
||||||
|
The power off is accomplished by putting the MCU into a "soft off" state. Power is _not_ technically removed from the entire system, but the device will only be woken from the state by a few possible events.
|
||||||
|
|
||||||
|
:::
|
||||||
|
|
||||||
|
A device can be put in the soft off state by:
|
||||||
|
|
||||||
|
- Triggering a hardware-defined dedicated GPIO pin, if one exists;
|
||||||
|
- Triggering the [soft off behavior](../keymaps/behaviors/soft-off.md) from the keymap.
|
||||||
|
|
||||||
|
Once in the soft off state, the device can only be woken up by:
|
||||||
|
|
||||||
|
- Triggering any GPIO pin specified to enable waking from sleep, if one exists;
|
||||||
|
- Pressing a reset button found on the device.
|
||||||
|
|
||||||
|
The GPIO pin used to wake from sleep can be a hardware-defined one, such as for a dedicated on-off push button, or it can be a single specific key switch reused for waking up (which may be accidentally pressed, e.g. while the device is being carried in a bag). To allow the simultaneous pressing of multiple key switches to trigger and exit soft off, some keyboards make use of additional hardware to integrate the dedicated GPIO pin into the keyboard matrix.
|
||||||
|
|
||||||
|
### Config
|
||||||
|
|
||||||
|
Soft off must be enabled via [its corresponding config](../config/power.md#low-power-states) before it can be used.
|
||||||
|
|
||||||
|
### Using Soft Off
|
||||||
|
|
||||||
|
If your keyboard has hardware designed to take advantage of soft off, refer to your keyboard's documentation.
|
||||||
|
|
||||||
|
For keyboards which do not have such hardware, using soft off is as simple as placing the [soft off behavior](../keymaps/behaviors/soft-off.md) in your keymap and then invoking it.
|
||||||
|
|
||||||
|
You can then wake up the keyboard by pressing the reset button once, and repeating this for each side for split keyboards.
|
||||||
Loading…
Add table
Reference in a new issue