135 lines
No EOL
4.9 KiB
Text
135 lines
No EOL
4.9 KiB
Text
---
|
|
title: Split boards with Dongles
|
|
sidebar_label: Split & Dongle
|
|
---
|
|
|
|
ZMK supports split keyboards that communicate wirelessly using BLE. Commonly these keyboards are split into two halves, each with its own microcontroller and battery.
|
|
Usually the left half of the keyboard is given the split role of central, and the right half is given the split role of peripheral.
|
|
The central half is responsible for communicating with the peripheral half and the host device.
|
|
|
|
Using this setup does have one drawback: the central half of the keyboard usually runs out of battery faster than the peripheral half.
|
|
This is because the central half is responsible for maintaining the connection with the peripheral half and the host device.
|
|
|
|
To solve this problem, a third microcontroller can be used as the new central or as more widely known a dongle.
|
|
The dongle will act as a central device and communicate with the keyboard halves which will both act as peripherals.
|
|
Dongles are usually connected to the host device using USB. This way the central half of the keyboard can be powered by the host device,
|
|
and the peripheral halves can be powered by their own batteries. This setup allows both halves of the keyboard to have a longer battery life.
|
|
|
|
Here is an example diagram of a split keyboard with a dongle:
|
|
|
|
```mermaid
|
|
graph TD;
|
|
A[Computer/Host Device] <-- USB/BLE --> DONGLE[Dongle/Central];
|
|
DONGLE -. BLE .-> LEFT[Left Half/Peripheral];
|
|
DONGLE -. BLE .-> RIGHT[Right Half/Peripheral];
|
|
```
|
|
|
|
Dotted lines represent BLE connections.
|
|
Solid lines represent USB connections.
|
|
|
|
:::info
|
|
For more information on how to set up a two split keyboard, refer to [New Keyboard Shield](../development/new-shield.mdx) under Guides.
|
|
After setting up the split keyboard, you can follow the steps below to add a dongle to the setup.
|
|
:::
|
|
|
|
## Benefits/Disadvantages of using a Dongle/Split setup
|
|
|
|
Benefits:
|
|
|
|
- Longer battery life for peripheral halves of the keyboard.
|
|
- Dongle can be powered by the host device and no long wires are needed.
|
|
- Easier to connect to the host device.
|
|
- Only the central side needs to reflashed for keymap updates
|
|
|
|
Disadvantages:
|
|
|
|
- More complex setup.
|
|
- More components needed.
|
|
- Added latency due to the extra hop between the host device and the keyboard halves.
|
|
- Each half of the keyboard needs its own firmware (ex: left, right, and dongle).
|
|
|
|
:::warning[Reset/Bootloader behavior]
|
|
When using a combo to trigger reset/bootloader, only the central side will be affected. To avoid this, you can avoid using the combo and instead use a physical reset button on the central half.
|
|
That will allow you to locally reset the central/peripheral side without affecting other halves.
|
|
|
|
## Building a Split Keyboard shield with a Dongle
|
|
|
|
:::note
|
|
Because we will be changing the roles of the keyboard halves, we will also need to flash the reset firmware to the keyboard halves.
|
|
Information about the reset firmware can be found under Troubleshooting [Reset firmware](../troubleshooting/connection-issues.mdx#acquiring-a-reset-uf2)
|
|
:::
|
|
|
|
### Kconfig.shield
|
|
|
|
First we will introduce a third split to our keyboard configuration. This will be used as the dongle.
|
|
|
|
```kconfig
|
|
config SHIELD_MY_BOARD_DONGLE
|
|
def_bool $(shields_list_contains,my_board_dongle)
|
|
|
|
config SHIELD_MY_BOARD_LEFT
|
|
def_bool $(shields_list_contains,my_board_left)
|
|
|
|
config SHIELD_MY_BOARD_RIGHT
|
|
def_bool $(shields_list_contains,my_board_right)
|
|
```
|
|
|
|
### Kconfig.defconfig
|
|
|
|
Next we will define the roles of the keyboard halves. The left and right halves will be set as peripherals, and the dongle will be set as the central.
|
|
We will also only give the dongle the keyboard name.
|
|
|
|
```kconfig
|
|
if SHIELD_MY_BOARD_DONGLE
|
|
|
|
config ZMK_KEYBOARD_NAME
|
|
default "My Board"
|
|
|
|
config ZMK_SPLIT_ROLE_CENTRAL
|
|
default y
|
|
|
|
endif
|
|
|
|
if SHIELD_MY_BOARD_DONGLE || SHIELD_MY_BOARD_LEFT || SHIELD_MY_BOARD_RIGHT
|
|
|
|
config ZMK_SPLIT
|
|
default y
|
|
|
|
endif
|
|
```
|
|
|
|
### Dongle configuration
|
|
|
|
Finally, we will define the dongle configuration. We want to set the number of peripherals to 2 and disable sleep mode for the dongle since it will be connected to the host device.
|
|
In case you want to use the dongle with a battery, you can enable sleep mode for the dongle. Since the dongle will be connected to the host device, we will also increase the broadcast power.
|
|
|
|
```ini title="my_board_dongle.conf"
|
|
CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS=2
|
|
|
|
CONFIG_ZMK_SLEEP=n
|
|
# Uncomment if sleep is enabled
|
|
# CONFIG_ZMK_IDLE_SLEEP_TIMEOUT=3600000
|
|
# Make the dongle broadcast with more power
|
|
CONFIG_BT_CTLR_TX_PWR_PLUS_8=y
|
|
```
|
|
|
|
### Dongle Overlay
|
|
|
|
In most common cases the dongle will not have any keys, in that case we can instead use a mock kscan module to simulate the keys.
|
|
|
|
```dts title="my_board_dongle.overlay"
|
|
|
|
/ {
|
|
chosen {
|
|
zmk,kscan = &mock_kscan;
|
|
// zmk,kscan = &kscan0;
|
|
};
|
|
|
|
mock_kscan: kscan_0 {
|
|
compatible = "zmk,kscan-mock";
|
|
columns = <0>;
|
|
rows = <0>;
|
|
events = <0>;
|
|
};
|
|
};
|
|
``` |