Skip to content

Commit

Permalink
docs: Add wired split config docs.
Browse files Browse the repository at this point in the history 
Migrate split to its own dedicated config file, and add details
on wired split config.

Co-authored-by: Nicolas Munnich <[email protected]>
  • Loading branch information
@petejohanson @Nick-Munnich
petejohanson and Nick-Munnich committed Feb 18, 2025
1 parent 2edfae0 commit 30a9a25
Show file tree
Hide file tree
Showing 5 changed files with 90 additions and 26 deletions.
2 changes: 1 addition & 1 deletion docs/docs/config/battery.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ On macOS the BLE battery reporting packets can cause the computer to wakeup from

### Peripheral Battery Monitoring

You can [configure ZMK to allow support for peripheral battery monitoring over BLE](system.md#split-keyboards) (e.g. when having a split keyboard with two independent and wirelessly connected sides).
You can [configure ZMK to allow support for peripheral battery monitoring over BLE](split.md) (e.g. when having a split keyboard with two independent and wirelessly connected sides).
If you want to report the battery levels of both sides of a split keyboard, you should have both `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY` and `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING` set to `y`.

:::note[Displaying both battery levels on your host]
Expand Down
85 changes: 85 additions & 0 deletions docs/docs/config/split.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
title: Split Configuration
sidebar_label: Split
---

These are settings that control how split keyboards behave.

See [Configuration Overview](index.md) for instructions on how to change these settings.

## Kconfig

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).

| Config | Type | Description | Default |
| -------------------------------------------- | ---- | ------------------------------------------------------------------------ | ------- |
| `CONFIG_ZMK_SPLIT` | bool | Enable split keyboard support | n |
| `CONFIG_ZMK_SPLIT_ROLE_CENTRAL` | bool | `y` for central device, `n` for peripheral | n |
| `CONFIG_ZMK_SPLIT_PERIPHERAL_HID_INDICATORS` | bool | Enable split keyboard support for passing indicator state to peripherals | n |

### Bluetooth Splits

Following bluetooth [split keyboard](../features/split-keyboards.md) settings are defined in [zmk/app/src/split/bluetooth/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/src/split/bluetooth/Kconfig).

| Config | Type | Description | Default |
| ------------------------------------------------------- | ---- | -------------------------------------------------------------------------- | ------------------------------------------ |
| `CONFIG_ZMK_SPLIT_BLE` | bool | Use BLE to communicate between split keyboard halves | y |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` | int | Number of peripherals that will connect to the central | 1 |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING` | bool | Enable fetching split peripheral battery levels to the central side | n |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY` | bool | Enable central reporting of split battery levels to hosts | n |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_QUEUE_SIZE` | int | Max number of battery level events to queue when received from peripherals | `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_POSITION_QUEUE_SIZE` | int | Max number of key state events to queue when received from peripherals | 5 |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_SPLIT_RUN_STACK_SIZE` | int | Stack size of the BLE split central write thread | 512 |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_SPLIT_RUN_QUEUE_SIZE` | int | Max number of behavior run events to queue to send to the peripheral(s) | 5 |
| `CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_STACK_SIZE` | int | Stack size of the BLE split peripheral notify thread | 756 |
| `CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_PRIORITY` | int | Priority of the BLE split peripheral notify thread | 5 |
| `CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_POSITION_QUEUE_SIZE` | int | Max number of key state events to queue to send to the central | 10 |

### Wired Splits

Following wired [split keyboard](../features/split-keyboards.md) settings are defined in [zmk/app/src/split/wired/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/app/src/split/wired/Kconfig).

:::note

Hardware UARTs have a few different modes/approaches to sending and receiving data, with different levels of complexity and performance. Not all hardware nor drivers support all modes, so ZMK has code to support different interaction modes with the UART as needed. The default mode should be properly selected based on the platform's report support, but you can choose to override the mode if needed.

:::

| Config | Type | Description | Default |
| -------------------------------------------- | ---- | ----------------------------------------------------------------- | ------------------------------------------------------------- |
| `CONFIG_ZMK_SPLIT_WIRED` | bool | Use wired connection to communicate between split keyboard halves | y (if no BLE split and devicetree is set appropriately) |
| `CONFIG_ZMK_SPLIT_WIRED_UART_MODE_ASYNC` | bool | Async (DMA) mode | y if the driver supports it (excluding nRF52 with known bugs) |
| `CONFIG_ZMK_SPLIT_WIRED_UART_MODE_INTERRUPT` | bool | Interrupt mode | `y` if the hardware supports it |
| `CONFIG_ZMK_SPLIT_WIRED_UART_MODE_POLLING` | bool | Polling mode | `y` it neither other mode is supported |

#### Async (DMA) Mode

The following settings only apply when using wired split in async (DMA) mode:

| Config | Type | Description | Default |
| ----------------------------------------- | ---- | ----------------------------------------------------------- | ------- |
| `CONFIG_ZMK_SPLIT_WIRED_ASYNC_RX_TIMEOUT` | int | RX Timeout (in microseconds) before reporting received data | 20 |

#### Polling Mode

The following settings only apply when using wired split in polling mode:

| Config | Type | Description | Default |
| ------------------------------------------ | ---- | ---------------------------------------------------- | ------- |
| `CONFIG_ZMK_SPLIT_WIRED_POLLING_RX_PERIOD` | int | Number of ticks between calls to poll for split data | 10 |

## Devicetree

### Wired Split

Wired splits require a properly configured UART to function. If writing a shield, you may be able to use the standard UART already provided by the board, e.g. `&pro_micro_serial`. See the shield overlays section in the [new shield guide](../development/hardware-integration/new-shield.mdx#shield-overlays) for details on the UART node labels provided by various interconnects. If you are creating your own board, or using custom pins for the UART, see the documentation on [pin control](../development/hardware-integration/pinctrl.mdx#additional-examples) to configure the pins for your UART.

Once you have a properly configured UART device, it needs to be assigned to the `zmk,split-uart` property in the `chosen` node. For example:

```dts
/ {
chosen {
zmk,split-uart = &pro_micro_serial;
};
}
```
21 changes: 0 additions & 21 deletions docs/docs/config/system.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -115,27 +115,6 @@ Note that `CONFIG_BT_MAX_CONN` and `CONFIG_BT_MAX_PAIRED` should be set to the s
| `CONFIG_ZMK_USB_LOGGING` | bool | Enable USB CDC ACM logging for debugging | n |
| `CONFIG_ZMK_LOG_LEVEL` | int | Log level for ZMK debug messages | 4 |

### Split keyboards

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 |
| ------------------------------------------------------- | ---- | -------------------------------------------------------------------------- | ------------------------------------------ |
| `CONFIG_ZMK_SPLIT` | bool | Enable split keyboard support | n |
| `CONFIG_ZMK_SPLIT_ROLE_CENTRAL` | bool | `y` for central device, `n` for peripheral | |
| `CONFIG_ZMK_SPLIT_PERIPHERAL_HID_INDICATORS` | bool | Enable split keyboard support for passing indicator state to peripherals | n |
| `CONFIG_ZMK_SPLIT_BLE` | bool | Use BLE to communicate between split keyboard halves | y |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` | int | Number of peripherals that will connect to the central | 1 |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_FETCHING` | bool | Enable fetching split peripheral battery levels to the central side | n |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_PROXY` | bool | Enable central reporting of split battery levels to hosts | n |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_BATTERY_LEVEL_QUEUE_SIZE` | int | Max number of battery level events to queue when received from peripherals | `CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS` |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_POSITION_QUEUE_SIZE` | int | Max number of key state events to queue when received from peripherals | 5 |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_SPLIT_RUN_STACK_SIZE` | int | Stack size of the BLE split central write thread | 512 |
| `CONFIG_ZMK_SPLIT_BLE_CENTRAL_SPLIT_RUN_QUEUE_SIZE` | int | Max number of behavior run events to queue to send to the peripheral(s) | 5 |
| `CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_STACK_SIZE` | int | Stack size of the BLE split peripheral notify thread | 756 |
| `CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_PRIORITY` | int | Priority of the BLE split peripheral notify thread | 5 |
| `CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_POSITION_QUEUE_SIZE` | int | Max number of key state events to queue to send to the central | 10 |

## Snippets

:::danger
Expand Down
7 changes: 3 additions & 4 deletions docs/docs/features/split-keyboards.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,9 @@ 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.
Currently ZMK only supports split keyboards that communicate with each other wirelessly over BLE or with a wired, full-duplex UART.

Supporting split communication over wired protocols is planned, allowing for ZMK split keyboards using non-wireless controllers.
Future single-wire, half-duplex UART support, which is planned, will allow using wired ZMK with designs like Corne, Sweep, etc. that use only a single GPIO pin for bidirectional communication between split sides.
:::

## Central and Peripheral Roles
Expand All @@ -32,7 +31,7 @@ You can refer to the [power profiler](/power-profiler) to see battery life estim

The [new shield guide](../development/hardware-integration/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.
Also see the reference section on [split keyboards configuration](../config/split.md) 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

Expand Down
1 change: 1 addition & 0 deletions docs/sidebars.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ module.exports = {
"config/layout",
"config/kscan",
"config/power",
"config/split",
"config/system",
"config/studio",
],
Expand Down

0 comments on commit 30a9a25

Please sign in to comment.