mirror of https://github.com/zmkfirmware/zmk.git
docs: Document usage of persistent settings explicitly (#3036)
This commit is contained in:
Cem Aksoylar
GitHub
parent
5225952f96
commit
5144de677d
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
title: Persistent Settings
|
||||
sidebar_label: Settings
|
||||
---
|
||||
|
||||
ZMK uses [Zephyr's settings subsystem](https://docs.zephyrproject.org/3.5.0/services/settings/index.html) to store certain runtime settings in the "storage" partition of the controller's flash memory.
|
||||
These settings will be saved after certain events and loaded on boot.
|
||||
For instance, bond information for [paired Bluetooth hosts](../features/bluetooth.md) are stored in this partition so that users do not need to pair to each device again after the controller loses power.
|
||||
|
||||
Persisted settings are **not** cleared by flashing regular ZMK firmware: this is by design, since modifications like keymap changes should not cause users to lose their Bluetooth pairings.
|
||||
They can only be cleared by setting a special Kconfig symbol or flashing a special firmware build as documented below.
|
||||
|
||||
Below is a non-comprehensive list of ZMK features that utilize persisted settings.
|
||||
|
||||
- [Bluetooth](../features/bluetooth.md): Stores pairing keys and MAC addresses associated with hosts, BT profile selected through the [keymap behavior](../keymaps/behaviors/bluetooth.md)[^1]
|
||||
- [Split keyboards](../features/split-keyboards.md): Stores pairing keys and MAC addresses for wireless connection between parts
|
||||
- [Output selection](../keymaps/behaviors/outputs.md): Stores last selected preferred endpoint changed through the keymap behavior[^1]
|
||||
- [ZMK Studio](../features/studio.md): Stores any runtime keymap modifications and selected physical layouts after they are saved to the keyboard
|
||||
- [Lighting](../features/lighting.md): Stores current brightness/color/effects for [underglow](../keymaps/behaviors/underglow.md) and [backlight](../keymaps/behaviors/backlight.md) features after being changed through their keymap behaviors[^1]
|
||||
- [Power management](../keymaps/behaviors/power.md): Stores the state of the external power toggle as changed through the keymap behavior[^1]
|
||||
|
||||
[^1]: These are not saved immediately, but after `CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE` milliseconds in order to reduce potential wear on the flash memory.
|
||||
|
||||
## Kconfig
|
||||
|
||||
See [Configuration Overview](index.md) for instructions on how to change these settings.
|
||||
|
||||
Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/Kconfig)
|
||||
|
||||
| Config | Type | Description | Default |
|
||||
| ------------------------------------ | ---- | ----------------------------------------------------------------------------- | ------- |
|
||||
| `CONFIG_ZMK_SETTINGS_RESET_ON_START` | bool | Clears all persistent settings from the keyboard at startup | n |
|
||||
| `CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE` | int | Milliseconds to wait after a setting change before writing it to flash memory | 60000 |
|
||||
|
||||
## Clearing Persisted Settings
|
||||
|
||||
While regular ZMK builds will not cause any settings to be cleared upon flashing, flashing a build with `CONFIG_ZMK_SETTINGS_RESET_ON_START` enabled as documented above will cause the firmware to run a special procedure when the controller starts that clears the settings partition.
|
||||
|
||||
For end users, it is recommended to use a special [shield](../development/hardware-integration/index.mdx#boards--shields) named `settings_reset` to build a new firmware file, then flash that firmware.
|
||||
See example for building firmware using this shield in the [troubleshooting docs](../troubleshooting/connection-issues.mdx#building-a-reset-firmware).
|
||||
|
||||
In both cases, regular, non-reset firmware will need to be flashed afterwards for normal operation.
|
||||
|
||||
:::tip
|
||||
|
||||
[ZMK Studio](../features/studio.md)-specific settings can be easily cleared using the "Restore Stock Settings" button in the header of the Studio client.
|
||||
|
||||
:::
|
||||
|
|
@ -13,13 +13,18 @@ Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/
|
|||
|
||||
### General
|
||||
|
||||
| Config | Type | Description | Default |
|
||||
| ------------------------------------ | ------ | ----------------------------------------------------------------------------- | ------- |
|
||||
| `CONFIG_ZMK_KEYBOARD_NAME` | string | The name of the keyboard (max 16 characters) | |
|
||||
| `CONFIG_ZMK_SETTINGS_RESET_ON_START` | bool | Clears all persistent settings from the keyboard at startup | n |
|
||||
| `CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE` | int | Milliseconds to wait after a setting change before writing it to flash memory | 60000 |
|
||||
| `CONFIG_ZMK_WPM` | bool | Enable calculating words per minute | n |
|
||||
| `CONFIG_HEAP_MEM_POOL_SIZE` | int | Size of the heap memory pool | 8192 |
|
||||
| Config | Type | Description | Default |
|
||||
| --------------------------- | ------ | -------------------------------------------- | ------- |
|
||||
| `CONFIG_ZMK_KEYBOARD_NAME` | string | The name of the keyboard (max 16 characters) | |
|
||||
| `CONFIG_ZMK_WPM` | bool | Enable calculating words per minute | n |
|
||||
| `CONFIG_HEAP_MEM_POOL_SIZE` | int | Size of the heap memory pool | 8192 |
|
||||
|
||||
:::tip
|
||||
|
||||
Because ZMK enables [the Zephyr setting](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_DEVICE_NAME_DYNAMIC) that allows for runtime modification of the device BT name,
|
||||
changing `CONFIG_ZMK_KEYBOARD_NAME` requires [clearing the stored settings](./settings.md) on the controller in order to take effect.
|
||||
|
||||
:::
|
||||
|
||||
### HID
|
||||
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ description: Troubleshooting wireless connection issues of ZMK devices.
|
|||
- Replacing the controller for one of the halves.
|
||||
|
||||
These issues can be resolved by flashing a settings reset firmware to both controllers.
|
||||
See [persistent settings documentation](../config/settings.md) for more information.
|
||||
|
||||
:::warning
|
||||
|
||||
|
|
|
|||
|
|
@ -130,6 +130,7 @@ module.exports = {
|
|||
"config/layout",
|
||||
"config/kscan",
|
||||
"config/power",
|
||||
"config/settings",
|
||||
"config/split",
|
||||
"config/system",
|
||||
"config/studio",
|
||||
|
|
|
|||
Loading…
Reference in New Issue