Persistent Settings
ZMK uses Zephyr's settings subsystem 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 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: Stores pairing keys and MAC addresses associated with hosts, BT profile selected through the keymap behavior1
- Split keyboards: Stores pairing keys and MAC addresses for wireless connection between parts
- Output selection: Stores last selected preferred endpoint changed through the keymap behavior1
- ZMK Studio: Stores any runtime keymap modifications and selected physical layouts after they are saved to the keyboard
- Lighting: Stores current brightness/color/effects for underglow and backlight features after being changed through their keymap behaviors1
- Power management: Stores the state of the external power toggle as changed through the keymap behavior1
Kconfig
See Configuration Overview for instructions on how to change these settings.
Definition file: zmk/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 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.
In both cases, regular, non-reset firmware will need to be flashed afterwards for normal operation.
ZMK Studio-specific settings can be easily cleared using the "Restore Stock Settings" button in the header of the Studio client.