diff --git a/docs/blog/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md index 0e9f3768e..45c2af497 100644 --- a/docs/blog/2023-10-05-zmk-sotf-6.md +++ b/docs/blog/2023-10-05-zmk-sotf-6.md @@ -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). diff --git a/docs/docs/config/settings.md b/docs/docs/config/settings.md index 292d6b470..da162c752 100644 --- a/docs/docs/config/settings.md +++ b/docs/docs/config/settings.md @@ -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. diff --git a/docs/docs/config/system.md b/docs/docs/config/system.md index 3bc69ef0f..4575a50d1 100644 --- a/docs/docs/config/system.md +++ b/docs/docs/config/system.md @@ -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. ::: diff --git a/docs/docs/customization.md b/docs/docs/customization.md index e35bb4267..aacbe00e7 100644 --- a/docs/docs/customization.md +++ b/docs/docs/customization.md @@ -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 diff --git a/docs/docs/development/hardware-integration/soft-off-setup.mdx b/docs/docs/development/hardware-integration/soft-off-setup.mdx index 097595b12..690ca1720 100644 --- a/docs/docs/development/hardware-integration/soft-off-setup.mdx +++ b/docs/docs/development/hardware-integration/soft-off-setup.mdx @@ -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. diff --git a/docs/docs/features/split-keyboards.md b/docs/docs/features/split-keyboards.md index c10c305bd..36cf90434 100644 --- a/docs/docs/features/split-keyboards.md +++ b/docs/docs/features/split-keyboards.md @@ -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. diff --git a/docs/docs/keymaps/behaviors/backlight.md b/docs/docs/keymaps/behaviors/backlight.md index 6dbb6e7b2..c65b03efd 100644 --- a/docs/docs/keymaps/behaviors/backlight.md +++ b/docs/docs/keymaps/behaviors/backlight.md @@ -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. ::: diff --git a/docs/docs/keymaps/behaviors/bluetooth.md b/docs/docs/keymaps/behaviors/bluetooth.md index 93d084281..44e38d309 100644 --- a/docs/docs/keymaps/behaviors/bluetooth.md +++ b/docs/docs/keymaps/behaviors/bluetooth.md @@ -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. ::: diff --git a/docs/docs/keymaps/behaviors/outputs.md b/docs/docs/keymaps/behaviors/outputs.md index 20ce8a696..98d2186ee 100644 --- a/docs/docs/keymaps/behaviors/outputs.md +++ b/docs/docs/keymaps/behaviors/outputs.md @@ -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. ::: diff --git a/docs/docs/keymaps/behaviors/power.md b/docs/docs/keymaps/behaviors/power.md index 4c3330805..1814e67c8 100644 --- a/docs/docs/keymaps/behaviors/power.md +++ b/docs/docs/keymaps/behaviors/power.md @@ -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. ::: diff --git a/docs/docs/keymaps/behaviors/underglow.md b/docs/docs/keymaps/behaviors/underglow.md index ecffca756..245c68581 100644 --- a/docs/docs/keymaps/behaviors/underglow.md +++ b/docs/docs/keymaps/behaviors/underglow.md @@ -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. ::: diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 3a8c16764..1d102d96d 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -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 diff --git a/docs/docs/user-setup.mdx b/docs/docs/user-setup.mdx index 9fd333177..7433292e9 100644 --- a/docs/docs/user-setup.mdx +++ b/docs/docs/user-setup.mdx @@ -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. :::