diff --git a/docs/docs/config/settings.md b/docs/docs/config/settings.md new file mode 100644 index 000000000..292d6b470 --- /dev/null +++ b/docs/docs/config/settings.md @@ -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. + +::: diff --git a/docs/docs/config/system.md b/docs/docs/config/system.md index cae2b5285..3bc69ef0f 100644 --- a/docs/docs/config/system.md +++ b/docs/docs/config/system.md @@ -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 diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 6689885a9..3a8c16764 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -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 diff --git a/docs/sidebars.js b/docs/sidebars.js index 63b8ec3fe..69de26e78 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -130,6 +130,7 @@ module.exports = { "config/layout", "config/kscan", "config/power", + "config/settings", "config/split", "config/system", "config/studio",