From 5417aa4789a6bd784c0c746fa2c429e8accce2e0 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Sun, 4 Aug 2024 22:43:01 -0700 Subject: [PATCH 1/4] feat(docs): Add split keyboards feature page Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com> --- docs/docs/features/split-keyboards.md | 92 +++++++++++++++++++++++++++ docs/sidebars.js | 1 + 2 files changed, 93 insertions(+) create mode 100644 docs/docs/features/split-keyboards.md diff --git a/docs/docs/features/split-keyboards.md b/docs/docs/features/split-keyboards.md new file mode 100644 index 00000000000..96af347235f --- /dev/null +++ b/docs/docs/features/split-keyboards.md @@ -0,0 +1,92 @@ +--- +title: Split Keyboards +sidebar_label: Split Keyboards +--- + +ZMK supports setups where a keyboard is split into two or more physical parts (also called "sides" or "halves" when split in two), each with their own controller running ZMK. The parts communicate with each other to work as a single keyboard device. + +:::note[Split communication protocols] +Currently ZMK only supports split keyboards that communicate with each other wirelessly over BLE. +As such, only controllers that support BLE can be used with ZMK split keyboards. + +Supporting split communication over wired protocols is planned, allowing for ZMK split keyboards using non-wireless controllers. +::: + +## Central and Peripheral Roles + +In split keyboards running ZMK, one part is assigned the "central" role which receives key position and sensor events from the other parts that are called "peripherals." +The central runs the necessary keymap logic to convert received events into HID events such as keycodes and then communicates with the connected host devices, e.g. over USB or bluetooth. + +The internal keyboard state (like active layers) is handled exclusively by the central. +Peripherals _cannot_ communicate with host devices on their own, since they can only communicate with the central. +They will not present as keyboard devices when connected over USB and will not advertise as pairable BLE keyboards. + +By convention, for a keyboard split into two "halves" the left half is set as the central and the right as a peripheral. + +### Configuration + +The [new shield guide](../development/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part. + +Also see the reference section on [split keyboards configuration](../config/system.md#split-keyboards) where the relevant symbols include `CONFIG_ZMK_SPLIT` that enables the feature, `CONFIG_ZMK_SPLIT_ROLE_CENTRAL` which sets the central role and `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` that sets the number of peripherals. + +### Latency Considerations + +Since peripherals communicate through centrals, the key and sensor events originating from them will naturally have a larger latency, especially with a wireless split communication protocol. +For the currently used BLE-based transport, split communication increases the average latency by 3.75ms with a worst case increase of 7.5ms. + +## Building and Flashing Firmware + +ZMK split keyboards require building and flashing different firmware files for each split part. +For instance when [using the GitHub workflow](../user-setup.mdx) to build two part split keyboards, two firmware files that typically contain `_left` and `_right` in the file names will be produced. +These files need to be flashed to the respective controllers of the two halves. + +:::tip[Updating your keymap] +Since the keymap processing is primarily done on the central side, for keymap changes it will typically be enough to flash the controller of the central half. +However if you make changes to [config files](../config/index.md) that should apply to all parts, you need to flash to all parts. +Any changes in ZMK related to split keyboard features might also necessitate doing this. +::: + +## Pairing for Wireless Split Keyboards + +Split keyboards with BLE-based split communications (i.e. all officially supported split keyboards) have an internal pairing procedure between the central and each peripheral. +When the central has an open slot for a peripheral, it will advertise for connections (which will not be visible to non-ZMK devices). +Then, any peripheral that has not yet bonded to a peripheral will pair to it. +Similar to how [bluetooth profiles](bluetooth.md) are managed between the keyboard and host devices, the bonding information will be stored with the corresponding hardware addresses of the other keyboard part, on both the central and peripheral. + +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. + +:::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. +::: + +## Behaviors with Locality + +Most ZMK [behaviors](../behaviors/index.mdx) are processed exclusively on the central of the split keyboard as it handles the keymap state and any communication with the host devices. +However, certain behaviors have "global" or "source" localities, where they can affect the peripherals when invoked. + +### Global Locality Behaviors + +These are behaviors that affect all keyboard parts, such as changing lighting effects. +Currently these are the following behaviors: + +- [RGB underglow behaviors](../behaviors/underglow.md) +- [Backlight behaviors](../behaviors/backlight.md) +- [Power management behaviors](../behaviors/power.md) +- [Soft off behavior](../behaviors/soft-off.md) + +### Source Locality Behaviors + +These behaviors only affect the keyboard part that they are invoked from, given that they were invoked from a plain behavior binding (i.e. not nested inside another behavior) on a keymap layer. These behaviors include: + +- [Reset behaviors](../behaviors/reset.md) + +:::note[Peripheral invocation] +Peripherals must be paired and connected to the central in order to be able to activate these behaviors, even if it is possible to trigger the behavior using only keys on a particular peripheral. +This is because the key bindings are processed on the central side which would then instruct the peripheral side to run the behavior's effect. +::: + +:::note[Combos] +[Combos](combos.md) always invoke behaviors with source locality on the central. +::: diff --git a/docs/sidebars.js b/docs/sidebars.js index 1233ccf1b42..1c718e518cc 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -33,6 +33,7 @@ module.exports = { Features: [ "features/keymaps", "features/bluetooth", + "features/split-keyboards", "features/combos", "features/conditional-layers", "features/debouncing", From 8ad0c68b380131c1a7f00551cb05a60f1991a6f8 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Sun, 4 Aug 2024 22:48:17 -0700 Subject: [PATCH 2/4] feat(docs): Add references to new split keyboards page --- docs/docs/behaviors/backlight.md | 2 +- docs/docs/behaviors/power.md | 2 +- docs/docs/behaviors/reset.md | 6 +----- docs/docs/behaviors/underglow.md | 2 +- docs/docs/config/index.md | 2 +- docs/docs/config/system.md | 2 +- docs/docs/customization.md | 2 +- docs/docs/development/new-behavior.mdx | 2 +- docs/docs/development/new-shield.mdx | 2 +- docs/docs/features/battery.md | 2 +- docs/docs/features/bluetooth.md | 2 +- docs/docs/features/combos.md | 4 ++-- docs/docs/troubleshooting/connection-issues.mdx | 2 +- docs/docs/user-setup.mdx | 2 ++ 14 files changed, 16 insertions(+), 18 deletions(-) diff --git a/docs/docs/behaviors/backlight.md b/docs/docs/behaviors/backlight.md index 12ed01f19f3..040bb7b7950 100644 --- a/docs/docs/behaviors/backlight.md +++ b/docs/docs/behaviors/backlight.md @@ -58,4 +58,4 @@ However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNC ## Split Keyboards -Backlight behaviors are global: This means that when triggered, they affect both the central and peripheral side of split keyboards. +Backlight behaviors are [global](../features/split-keyboards.md#global-locality-behaviors): This means that when triggered, they affect both the central and peripheral side of split keyboards. diff --git a/docs/docs/behaviors/power.md b/docs/docs/behaviors/power.md index dce7b1555d3..53110f9591b 100644 --- a/docs/docs/behaviors/power.md +++ b/docs/docs/behaviors/power.md @@ -70,4 +70,4 @@ However it will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNCE`](../con ## Split Keyboards -Power management behaviors are global: This means that when triggered, they affects both the central and peripheral side of split keyboards. +Power management behaviors are [global](../features/split-keyboards.md#global-locality-behaviors): This means that when triggered, they affects both the central and peripheral side of split keyboards. diff --git a/docs/docs/behaviors/reset.md b/docs/docs/behaviors/reset.md index 60e694313d6..1e2110b94fa 100644 --- a/docs/docs/behaviors/reset.md +++ b/docs/docs/behaviors/reset.md @@ -44,8 +44,4 @@ Example: ## Split Keyboards -Both basic and bootloader reset behaviors are source-specific: This means that it affects the side of the keyboard that contains the behavior binding for split keyboards. For example if you press a key with the `&sys_reset` binding on the left half of the keyboard, the left half will be reset. If you want to be able to reset both sides you can put the bindings on both sides of the keyboard and activate it on the side you would like to reset. - -:::note[Peripheral invocation] -The peripheral side of the keyboard has to be paired and connected to the central side in order to be able to activate these behaviors, even if it is possible to trigger the behavior using only keys on that side. This is because the key bindings are processed on the central side which would then instruct the peripheral side to reset. -::: +Both basic and bootloader reset behaviors are [source-specific](../features/split-keyboards.md##source-locality-behaviors): This means that it affects the side of the keyboard that contains the behavior binding for split keyboards. For example if you press a key with the `&sys_reset` binding on the left half of the keyboard, the left half will be reset. If you want to be able to reset both sides you can put the bindings on both sides of the keyboard and activate it on the side you would like to reset. diff --git a/docs/docs/behaviors/underglow.md b/docs/docs/behaviors/underglow.md index 490789a71be..bd549395ae3 100644 --- a/docs/docs/behaviors/underglow.md +++ b/docs/docs/behaviors/underglow.md @@ -77,4 +77,4 @@ However the settings will only be saved after [`CONFIG_ZMK_SETTINGS_SAVE_DEBOUNC ## Split Keyboards -RGB underglow behaviors are global: This means that when triggered, they affect both the central and peripheral side of split keyboards. +RGB underglow behaviors are [global](../features/split-keyboards.md#global-locality-behaviors): This means that when triggered, they affect both the central and peripheral side of split keyboards. diff --git a/docs/docs/config/index.md b/docs/docs/config/index.md index 666cf4d9a68..a7c89b7ba95 100644 --- a/docs/docs/config/index.md +++ b/docs/docs/config/index.md @@ -24,7 +24,7 @@ When building with a `zmk-config` folder, ZMK will search the `zmk-config/config These files hold your personal settings for the keyboard. All files are optional. If present, they override any configuration set in the board or shield folders. Otherwise, the default configuration and/or keymap is used. -When using a split keyboard, you can use a single file without the `_left` or `_right` suffix to configure both sides. For example, `corne.conf` and `corne.keymap` will apply to both `corne_left` and `corne_right`. If a shared config file exists, any left or right files will be ignored. +When using a [split keyboard](../features/split-keyboards.md), you can use a single file without the `_left` or `_right` suffix to configure both sides. For example, `corne.conf` and `corne.keymap` will apply to both `corne_left` and `corne_right`. If a shared config file exists, any left or right files will be ignored. ### Board Folder diff --git a/docs/docs/config/system.md b/docs/docs/config/system.md index fef9f53a5b5..1a5306bda5f 100644 --- a/docs/docs/config/system.md +++ b/docs/docs/config/system.md @@ -117,7 +117,7 @@ Note that `CONFIG_BT_MAX_CONN` and `CONFIG_BT_MAX_PAIRED` should be set to the s ### Split keyboards -Following split keyboard settings are defined in [zmk/app/src/split/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/src/split/Kconfig) (generic) and [zmk/app/src/split/bluetooth/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/src/split/bluetooth/Kconfig) (bluetooth). +Following [split keyboard](../features/split-keyboards.md) settings are defined in [zmk/app/src/split/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/src/split/Kconfig) (generic) and [zmk/app/src/split/bluetooth/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/src/split/bluetooth/Kconfig) (bluetooth). | Config | Type | Description | Default | | ------------------------------------------------------- | ---- | -------------------------------------------------------------------------- | ------------------------------------------ | diff --git a/docs/docs/customization.md b/docs/docs/customization.md index 87d78a22b1c..5b02003d2f3 100644 --- a/docs/docs/customization.md +++ b/docs/docs/customization.md @@ -49,7 +49,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, only the central (left) side will need to be reflashed if you are just updating your keymap. +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). ## Building Additional Keyboards diff --git a/docs/docs/development/new-behavior.mdx b/docs/docs/development/new-behavior.mdx index dca19288dc0..113ddf0a3b3 100644 --- a/docs/docs/development/new-behavior.mdx +++ b/docs/docs/development/new-behavior.mdx @@ -346,7 +346,7 @@ if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_ROLE_CENTRAL) endif() ``` -For behaviors that do not require central locality, the following options for updating `app/CmakeLists.txt` also exist: +For behaviors that do not require [central locality](../features/split-keyboards.md#behaviors-with-locality), the following options for updating `app/CMakeLists.txt` also exist: - Behavior applies to unibody, or central or peripheral half of keyboard: place `target_sources(app PRIVATE .c)` line _before_ `if ((NOT CONFIG_ZMK_SPLIT) OR CONFIG_ZMK_SPLIT_ROLE_CENTRAL)` - Behavior applies to _only_ central half of split keyboard: place `target_sources(app PRIVATE .c)` after `if (CONFIG_ZMK_SPLIT AND CONFIG_ZMK_SPLIT_ROLE_CENTRAL)` diff --git a/docs/docs/development/new-shield.mdx b/docs/docs/development/new-shield.mdx index ae97f6afe75..5234e13eec9 100644 --- a/docs/docs/development/new-shield.mdx +++ b/docs/docs/development/new-shield.mdx @@ -29,7 +29,7 @@ The high level steps are: It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing. :::note -ZMK support for split keyboards requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place. +ZMK support for [split keyboards](../features/split-keyboards.md) requires a few more files than single boards to ensure proper connectivity between the central and peripheral units. Check the following guides thoroughly to ensure that all the files are in place. ::: ## New Zephyr Module Repository diff --git a/docs/docs/features/battery.md b/docs/docs/features/battery.md index 29142eedc01..14dd6661d69 100644 --- a/docs/docs/features/battery.md +++ b/docs/docs/features/battery.md @@ -5,7 +5,7 @@ sidebar_label: Battery Level If your keyboard has a battery sensor, ZMK will report its battery level to the connected bluetooth host and show it on the keyboard's display, if it has one. -For split keyboards, only the battery level of the central (usually left) side is reported over bluetooth by default. ZMK can be [configured to report the battery levels for peripherals](../config/battery.md#peripheral-battery-monitoring), but not many host systems will display this information without additional configuration or the use of third party utilities. +For [split keyboards](split-keyboards.md), only the battery level of the central (usually left) side is reported over bluetooth by default. ZMK can be [configured to report the battery levels for peripherals](../config/battery.md#peripheral-battery-monitoring), but not many host systems will display this information without additional configuration or the use of third party utilities. :::note diff --git a/docs/docs/features/bluetooth.md b/docs/docs/features/bluetooth.md index d148acd82db..79af22b4c1a 100644 --- a/docs/docs/features/bluetooth.md +++ b/docs/docs/features/bluetooth.md @@ -3,7 +3,7 @@ title: Bluetooth sidebar_label: Bluetooth --- -ZMK's bluetooth functionality allows users to connect their keyboards to hosts using Bluetooth Low Energy (BLE) technology. It also is used for split keyboards to connect the two halves wirelessly. +ZMK's bluetooth functionality allows users to connect their keyboards to hosts using Bluetooth Low Energy (BLE) technology. It also is used for [split keyboards](split-keyboards.md) to connect the two halves wirelessly. :::note diff --git a/docs/docs/features/combos.md b/docs/docs/features/combos.md index 63c57c38cc3..ad24d61f93a 100644 --- a/docs/docs/features/combos.md +++ b/docs/docs/features/combos.md @@ -45,7 +45,7 @@ Key positions are numbered like the keys in your keymap, starting at 0. So, if t - You are not limited to `&kp` bindings. You can use all ZMK behaviors there, like `&mo`, `&bt`, `&mt`, `<` etc. :::note[Source-specific behaviors on split keyboards] -Invoking a source-specific behavior such as one of the [reset behaviors](behaviors/reset.md) using a combo will always trigger it on the central side of the keyboard, regardless of the side that the keys corresponding to `key-positions` are on. +Invoking a [source-specific behavior](split-keyboards.md#source-locality-behaviors) such as one of the [reset behaviors](behaviors/reset.md) using a combo will always trigger it on the central side of the keyboard, regardless of the side that the keys corresponding to `key-positions` are on. ::: -See [combo configuration](/docs/config/combos) for advanced configuration options. +See [combo configuration](../config/combos.md) for advanced configuration options. diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index f077702c5bb..fe80326bf23 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -24,7 +24,7 @@ export const Uf2Tabs = (props) => ( ## Split Keyboard Halves Unable to Pair -Split keyboard 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) halves 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. diff --git a/docs/docs/user-setup.mdx b/docs/docs/user-setup.mdx index f6cb5eb2717..a79a2956054 100644 --- a/docs/docs/user-setup.mdx +++ b/docs/docs/user-setup.mdx @@ -209,6 +209,7 @@ connect to it wirelessly. For split keyboards, only the central half (typically the left side) will send keyboard outputs over USB or advertise to other devices over bluetooth. Peripheral half will only send keystrokes to the central once they are paired and connected. For this reason it is recommended to test the left half of a split keyboard first. +Please refer to [split keyboards documentation](features/split-keyboards.md) for more information. ::: @@ -221,6 +222,7 @@ ZMK supports multiple BLE “profiles”, which allows you to connect to and swi ### Connecting Split Keyboard Halves For split keyboards, after flashing each half individually you can connect them together by resetting them at the same time. Within a few seconds of resetting, both halves should automatically connect to each other. +Please refer to [the pairing section in the split keyboards documentation](features/split-keyboards.md#pairing-for-wireless-split-keyboards) for more information. :::note From 7e37b19addf45d995642acbdea119b43d2990381 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Tue, 6 Aug 2024 17:21:53 -0700 Subject: [PATCH 3/4] feat(docs): Add locality warning for nested behaviors --- docs/docs/features/split-keyboards.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/docs/features/split-keyboards.md b/docs/docs/features/split-keyboards.md index 96af347235f..fd8ce16c3ea 100644 --- a/docs/docs/features/split-keyboards.md +++ b/docs/docs/features/split-keyboards.md @@ -68,8 +68,7 @@ However, certain behaviors have "global" or "source" localities, where they can ### Global Locality Behaviors -These are behaviors that affect all keyboard parts, such as changing lighting effects. -Currently these are the following behaviors: +These are behaviors that affect all keyboard parts, such as changing lighting effects: - [RGB underglow behaviors](../behaviors/underglow.md) - [Backlight behaviors](../behaviors/backlight.md) @@ -78,10 +77,15 @@ Currently these are the following behaviors: ### Source Locality Behaviors -These behaviors only affect the keyboard part that they are invoked from, given that they were invoked from a plain behavior binding (i.e. not nested inside another behavior) on a keymap layer. These behaviors include: +These behaviors only affect the keyboard part that they are invoked from: - [Reset behaviors](../behaviors/reset.md) +:::warning[Nesting behaviors with locality] +Currently there is [an issue](https://github.com/zmkfirmware/zmk/issues/1494) preventing both global and source locality behaviors from working as expected if they are invoked from another behavior, such as a hold-tap, tap dance or a mod-morph. +For this reason it is recommended that these behaviors are placed directly on a keymap layer. +::: + :::note[Peripheral invocation] Peripherals must be paired and connected to the central in order to be able to activate these behaviors, even if it is possible to trigger the behavior using only keys on a particular peripheral. This is because the key bindings are processed on the central side which would then instruct the peripheral side to run the behavior's effect. From 57bef5e6d860e94e67759909048aef8b552c5ab6 Mon Sep 17 00:00:00 2001 From: Cem Aksoylar Date: Wed, 7 Aug 2024 23:47:27 -0700 Subject: [PATCH 4/4] feat(docs): Add battery life remark for split keyboards --- docs/docs/features/split-keyboards.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/docs/features/split-keyboards.md b/docs/docs/features/split-keyboards.md index fd8ce16c3ea..aae61090988 100644 --- a/docs/docs/features/split-keyboards.md +++ b/docs/docs/features/split-keyboards.md @@ -23,6 +23,11 @@ They will not present as keyboard devices when connected over USB and will not a By convention, for a keyboard split into two "halves" the left half is set as the central and the right as a peripheral. +:::info[Battery life impact] +For BLE-based split keyboards, the central uses significantly more power than the peripherals because its radio needs to periodically wake up to check for incoming transmissions. +You can refer to the [power profiler](/power-profiler) to see battery life estimates for different roles. +::: + ### Configuration The [new shield guide](../development/new-shield.mdx) details how to define a split keyboard shield with two parts, enabling the split feature and setting up the necessary roles for each part.