Skip to content

Commit

Permalink
fixup! feat(docs): Add split keyboards feature page
Browse files Browse the repository at this point in the history
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
  • Loading branch information
caksoylar and Nick-Munnich authored Aug 5, 2024
1 parent bdd2e92 commit 826e23a
Showing 1 changed file with 6 additions and 4 deletions.
10 changes: 6 additions & 4 deletions docs/docs/features/split-keyboards.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ ZMK supports split keyboard setups where two or more keyboard parts (also called
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, which would allow using ZMK split keyboards with non-wireless controllers.
Supporting split communication over wired protocols is planned, allowing for ZMK split keyboards using non-wireless controllers.
:::

## Central and Peripheral Roles
Expand All @@ -18,7 +18,7 @@ In ZMK splits, one keyboard part has the "central" role that receives key positi
This part 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.

As a result of this architecture the internal keyboard state (like active layers) is shared and is mainly handled by the central part.
However this also means that the peripheral parts _cannot_ communicate with host devices on their own, since they can only communicate with the central part.
Peripherals _cannot_ communicate with host devices on their own, since they can only communicate with the central part.
They will not present as keyboard devices when connected over USB and will not advertise as pairable BLE keyboards.

:::note[Latency considerations]
Expand All @@ -35,17 +35,19 @@ Also see the reference section on [split keyboards configuration](../config/syst

## Building and Flashing Firmware

Unlike some of the other firmware implementations, ZMK split keyboards require building and flashing different firmware files for each split part.
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 `<keyboard>_left` and `<keyboard>_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 (which are all split keyboards that are officially supported) have an internal pairing procedure between the central and each peripheral.
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.
Expand Down

0 comments on commit 826e23a

Please sign in to comment.