zmkfirmware
/
zmk
mirror of https://github.com/zmkfirmware/zmk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Add warning box for clearing settings for splits, generalize troubleshooting procedure (#3039) 

Co-authored-by: Nicolas Munnich <98408764+nmunnich@users.noreply.github.com>
This commit is contained in:
Cem Aksoylar 2025-08-19 17:27:21 -07:00 committed by GitHub
parent ee69b9e3c7
commit f09e551929
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 31 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/blog/2023-10-05-zmk-sotf-6.md
View File

@ -104,7 +104,7 @@ Note that documentation is still lacking for utilizing more than one peripheral
[petejohanson] contributed a fix to release held keys on peripheral disconnect [#1340](https://github.com/zmkfirmware/zmk/pull/1340), which makes scenarios where a split disconnects unexpectedly less painful.
[petejohanson] also improved [the `settings_reset` shield](/docs/troubleshooting/connection-issues#split-keyboard-halves-unable-to-pair) by making it clear bonds more reliably, and allow it to build for all boards in [#1879](https://github.com/zmkfirmware/zmk/pull/1879).
[petejohanson] also improved [the `settings_reset` shield](/docs/troubleshooting/connection-issues#split-keyboard-parts-unable-to-pair) by making it clear bonds more reliably, and allow it to build for all boards in [#1879](https://github.com/zmkfirmware/zmk/pull/1879).
[petejohanson] and [xudongzheng] contributed additional split connectivity improvements, via using directed advertising in [#1913](https://github.com/zmkfirmware/zmk/pull/1913) and improving the robustness of central scanning in [#1912](https://github.com/zmkfirmware/zmk/pull/1912).

7
docs/docs/config/settings.md
View File

@ -41,6 +41,13 @@ 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.
:::warning
Since pairing information between split keyboards are also cleared with this process, you will need to clear settings on all parts of a split keyboard.
Please follow the full procedure described in [troubleshooting](../troubleshooting/connection-issues.mdx#split-keyboard-parts-unable-to-pair) so that the parts can pair correctly after clearing.
:::
:::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.

4
docs/docs/config/system.md
View File

@ -19,10 +19,10 @@ Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/
| `CONFIG_ZMK_WPM` | bool | Enable calculating words per minute | n |
| `CONFIG_HEAP_MEM_POOL_SIZE` | int | Size of the heap memory pool | 8192 |
:::tip
:::info
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.
changing `CONFIG_ZMK_KEYBOARD_NAME` requires [clearing the stored settings](./settings.md#clearing-persisted-settings) on the controller in order to take effect.
:::

2
docs/docs/customization.md
View File

@ -50,7 +50,7 @@ It is also possible to build firmware locally on your computer by following the
For normal keyboards, follow the same flashing instructions as before to flash your updated firmware.
For [split keyboards](features/split-keyboards.md#building-and-flashing-firmware), only the central (left) side will need to be reflashed if you are just updating your keymap.
More troubleshooting information for split keyboards can be found [here](troubleshooting/connection-issues.mdx#split-keyboard-halves-unable-to-pair).
More troubleshooting information for split keyboards can be found [here](troubleshooting/connection-issues.mdx#split-keyboard-parts-unable-to-pair).
## Building Additional Keyboards

2
docs/docs/development/hardware-integration/soft-off-setup.mdx
View File

@ -166,7 +166,7 @@ Finally, we will list the `wakeup_scan` device in an additional configuration se
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.
- The `wakeup-sources` property is a [phandle array](../devicetree.md#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 like a behavior that puts the keyboard in deep sleep. If you choose to do so, then you can omit everything aside from the `soft_off_wakers` node.

2
docs/docs/features/split-keyboards.md
View File

@ -87,7 +87,7 @@ Similar to how [bluetooth profiles](bluetooth.md) are managed between the keyboa
In practice, this means that your split keyboard parts will automatically pair and work the first time they are all on at the same time.
However, if this process somehow went wrong or you used controllers in a different split keyboard configuration before, you will need to explicitly clear the stored bond information so that the parts can pair properly.
For this, please follow [the specified procedure](../troubleshooting/connection-issues.mdx#split-keyboard-halves-unable-to-pair) in the troubleshooting section.
For this, please follow [the specified procedure](../troubleshooting/connection-issues.mdx#split-keyboard-parts-unable-to-pair) in the troubleshooting section.
:::warning
If the central keyboard part is either advertising for a pairing or waiting for disconnected peripherals, it will consume more power and drain batteries faster.

2
docs/docs/keymaps/behaviors/backlight.md
View File

@ -37,7 +37,7 @@ Here is a table describing the action for each define:
- Parameter #2: Only applies to `BL_SET`and is the brightness value
:::note[Backlight settings persistence]
The backlight settings that are changed via the `&bl` behavior will be saved to flash storage and hence persist across restarts and firmware flashes.
The backlight settings that are changed via the `&bl` behavior will be [saved to flash storage](../../config/settings.md) and hence persist across restarts and firmware flashes.
They will also override the start values set by [`CONFIG_ZMK_BACKLIGHT_*_START` settings](../../config/lighting.md#kconfig-1).
However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
:::

2
docs/docs/keymaps/behaviors/bluetooth.md
View File

@ -48,7 +48,7 @@ Here is a table describing the command for each define:
| `BT_DISC` | Disconnect from the 0-indexed profile by number, if it's currently connected and inactive; must include a number as an argument in the keymap to work correctly, e.g. `BT_DISC 0`. |
:::note[Selected profile persistence]
The profile that is selected by the `BT_SEL`/`BT_PRV`/`BT_NXT` actions will be saved to flash storage and hence persist across restarts and firmware flashes.
The profile that is selected by the `BT_SEL`/`BT_PRV`/`BT_NXT` actions will be [saved to flash storage](../../config/settings.md) and hence persist across restarts and firmware flashes.
However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
:::

2
docs/docs/keymaps/behaviors/outputs.md
View File

@ -45,7 +45,7 @@ The output selection behavior changes the preferred output on press.
- Parameter #1: Command, e.g. `OUT_BLE`
:::note[Output selection persistence]
The endpoint that is selected by the `&out` behavior will be saved to flash storage and hence persist across restarts and firmware flashes.
The endpoint that is selected by the `&out` behavior will be [saved to flash storage](../../config/settings.md) and hence persist across restarts and firmware flashes.
However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
:::

2
docs/docs/keymaps/behaviors/power.md
View File

@ -44,7 +44,7 @@ Here is a table describing the command for each define:
- Parameter#1: Command, e.g `EP_ON`
:::note[External power state persistence]
The on/off state that is set by the `&ext_power` behavior will be saved to flash storage and hence persist across restarts and firmware flashes.
The on/off state that is set by the `&ext_power` behavior will be [saved to flash storage](../../config/settings.md) and hence persist across restarts and firmware flashes.
However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
:::

2
docs/docs/keymaps/behaviors/underglow.md
View File

@ -56,7 +56,7 @@ Value Limits:
:::
:::note[RGB settings persistence]
The RGB settings that are changed via the `&rgb_ug` behavior will be saved to flash storage and hence persist across restarts and firmware flashes.
The RGB settings that are changed via the `&rgb_ug` behavior will be [saved to flash storage](../../config/settings.md) and hence persist across restarts and firmware flashes.
They will also override the start values set by [`CONFIG_ZMK_RGB_*_START` settings](../../config/lighting.md#kconfig).
However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../../config/system.md#general) milliseconds in order to reduce potential wear on the flash memory.
:::

24
docs/docs/troubleshooting/connection-issues.mdx
View File

@ -8,14 +8,14 @@ description: Troubleshooting wireless connection issues of ZMK devices.
[USB logging](../development/usb-logging.mdx) can be very helpful for diagnosing issues with ZMK. However, when connected to USB your ZMK device will output to USB by default. To troubleshoot wireless connection issues using logging, you will need to [change the preferred output endpoint](../keymaps/behaviors/outputs.md).
:::
## Split Keyboard Halves Unable to Pair
## Split Keyboard Parts Unable to Pair
[Split keyboard](../features/split-keyboards.md) halves will automatically pair with one another, but there are some cases where this breaks, and the pairing needs to be reset, for example:
[Split keyboard](../features/split-keyboards.md) parts will automatically pair with one another, but there are some cases where this breaks and the pairing needs to be reset, for example:
- Switching which halves are the central/peripheral.
- Replacing the controller for one of the halves.
- Changing which part is the central.
- Replacing the controller for one of the parts.
These issues can be resolved by flashing a settings reset firmware to both controllers.
These issues can be resolved by flashing a settings reset firmware to both controllers to clear the stored pairing information.
See [persistent settings documentation](../config/settings.md) for more information.
:::warning
@ -46,16 +46,16 @@ If you use a [local development environment](../development/local-toolchain/setu
### Reset Split Keyboard Procedure
Perform the following steps to reset **_both_** halves of your split keyboard:
Perform the following steps to reset **_all_** parts of your split keyboard:
1. Put each half of the split keyboard into bootloader mode.
1. Flash one of the halves of the split with the settings reset firmware.
1. Repeat step 2 with the other half of the split keyboard.
1. Flash the actual image for each half of the split keyboard (e.g `my_board_left.uf2` to the left half, `my_board_right.uf2` to the right half).
1. Put each part of the split keyboard into bootloader mode.
1. Flash one of the parts of the split with the settings reset firmware.
1. Repeat step 2 with the other parts of the split keyboard.
1. Flash the actual image for each part of the split keyboard (e.g `my_board_left.uf2` to the left half, `my_board_right.uf2` to the right half).
After completing these steps, pair the halves of the split keyboard together by resetting them at the same time. Most commonly, this is done by grounding the reset pins for each of your keyboard's microcontrollers or pressing the reset buttons at the same time.
If the central and a peripheral has not paired after completing these steps, it can help to reset the central and the peripheral at around the same time. Most commonly, this is done by grounding the reset pins for each of your keyboard's microcontrollers or pressing the reset buttons, or turning both off then on with a power switch.
Once this is done, you can remove/forget the keyboard on each host device and pair it again.
Once this is done, you should remove/forget the keyboard on any paired host device and pair it again, since the pairing information for them will also have been cleared from the keyboard.
:::info

2
docs/docs/user-setup.mdx
View File

@ -232,7 +232,7 @@ Please refer to [the pairing section in the split keyboards documentation](featu
:::note
If you have issues connecting the halves, make sure that both sides are getting powered properly through USB or batteries, then follow the
[recommended troubleshooting procedure](troubleshooting/connection-issues.mdx#split-keyboard-halves-unable-to-pair). This is typically necessary if you
[recommended troubleshooting procedure](troubleshooting/connection-issues.mdx#split-keyboard-parts-unable-to-pair). This is typically necessary if you
swapped firmware sides between controllers, like flashing left side firmware to the same controller after flashing the right, or vice versa.
:::