191 lines
4.1 KiB
Text
191 lines
4.1 KiB
Text
---
|
|
title: Keyboard Dongle
|
|
sidebar_label: Keyboard Dongle
|
|
---
|
|
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
:::warning
|
|
This implementation is experimental and subject to change.
|
|
:::
|
|
|
|
A bluetooth dongle can be added to any keyboard running ZMK. The result is a [split keyboard](./split-keyboards.md) with the dongle as "central". There are a number of advantages to adding a dongle, but also some disadvantages:
|
|
|
|
Benefits:
|
|
|
|
- The "central" dongle results in increased battery life for the keyboard/former "central", as it is now a peripheral.
|
|
- It is easier to connect to the host device.
|
|
|
|
Disadvantages:
|
|
|
|
- An extra microcontroller is needed.
|
|
- The keyboard becomes unusable without the dongle.
|
|
|
|
|
|
|
|
## Editing a Keyboard Definition to Support a Dongle
|
|
|
|
|
|
In the examples below, we will be modifying the [New Keyboard Shield](../development/new-shield.mdx) guide files and will be building on top of that.
|
|
|
|
We will add the dongle in a way that it can be easily enabled, but is disabled by default.
|
|
|
|
### Keyboard Shield
|
|
|
|
|
|
Lets start by adding the dongle body to the shield configuration.
|
|
|
|
```kconfig title="Kconfig.shield"
|
|
config SHIELD_MY_KEYBOARD_DONGLE
|
|
def_bool $(shields_list_contains,my_keyboard_dongle)
|
|
```
|
|
|
|
### Keyboard Defconfig
|
|
|
|
|
|
<Tabs
|
|
defaultValue="unibody"
|
|
values={[
|
|
{label: 'Unibody Keyboard', value: 'unibody'},
|
|
{label: 'Split Keyboard', value: 'split'},
|
|
]}
|
|
>
|
|
<TabItem value="unibody">
|
|
|
|
Next we will modify the following lines
|
|
|
|
```kconfig title="Kconfig.defconfig"
|
|
if SHIELD_MY_KEYBOARD_DONGLE
|
|
|
|
config ZMK_KEYBOARD_NAME
|
|
default "My Board"
|
|
|
|
config ZMK_SPLIT_ROLE_CENTRAL
|
|
default y
|
|
|
|
config ZMK_SPLIT
|
|
default y
|
|
|
|
# Prevent the dongle from going to sleep
|
|
config ZMK_SLEEP
|
|
default n
|
|
|
|
# Increase the transmit power of the dongle
|
|
config BT_CLTR_TX_PWR_PLUS_8
|
|
default y
|
|
|
|
endif
|
|
|
|
if SHIELD_MY_KEYBOARD
|
|
config ZMK_KEYBOARD_NAME
|
|
default "My Board"
|
|
|
|
endif
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="split">
|
|
|
|
Next we will modify the following lines
|
|
|
|
```kconfig title="Kconfig.defconfig"
|
|
if SHIELD_MY_KEYBOARD_DONGLE
|
|
|
|
config ZMK_KEYBOARD_NAME
|
|
default "My Keyboard"
|
|
|
|
config ZMK_SPLIT_ROLE_CENTRAL
|
|
default y
|
|
|
|
config ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS
|
|
default 2
|
|
|
|
# Increase the transmit power of the dongle
|
|
config BT_CLTR_TX_PWR_PLUS_8
|
|
default y
|
|
|
|
endif
|
|
|
|
|
|
if SHIELD_MY_KEYBOARD_LEFT
|
|
|
|
# Setting this to y will make the left half the central
|
|
# We want it to be the central when dongle is not used
|
|
config ZMK_SPLIT_ROLE_CENTRAL
|
|
default y
|
|
|
|
# Check if the left half is the central
|
|
if ZMK_SPLIT_ROLE_CENTRAL
|
|
config ZMK_KEYBOARD_NAME
|
|
default "My Keyboard"
|
|
|
|
endif # ZMK_SPLIT_ROLE_CENTRAL
|
|
|
|
endif # SHIELD_MY_KEYBOARD_LEFT
|
|
|
|
if SHIELD_MY_KEYBOARD_DONGLE || SHIELD_MY_KEYBOARD_LEFT || SHIELD_MY_KEYBOARD_RIGHT
|
|
|
|
config ZMK_SPLIT
|
|
default y
|
|
|
|
endif
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### Dongle Overlay
|
|
|
|
We will replace the `kscan` with `kscan-mock` in the dongle overlay.
|
|
|
|
```dts title="my_keyboard_dongle.overlay"
|
|
// import the default shield configuration
|
|
#include "my_keyboard.dtsi"
|
|
|
|
&kscan {
|
|
compatible = "zmk,kscan-mock";
|
|
|
|
columns = <0>;
|
|
rows = <0>;
|
|
events = <0>;
|
|
}
|
|
|
|
```
|
|
|
|
|
|
## Enabling the Dongle
|
|
|
|
Now that we have defined the default shield configuration, we can easily enable the dongle in the user configuration.
|
|
|
|
For a split keyboard, change this
|
|
|
|
```kconfig title="config/my_keyboard_left.conf"
|
|
# Disable central role to use dongle
|
|
CONFIG_ZMK_SPLIT_ROLE_CENTRAL=n
|
|
```
|
|
|
|
For a unibody keyboard, change this
|
|
|
|
```kconfig title="config/my_keyboard.conf"
|
|
# Enable split functionality, this will put the unibody keyboard in peripheral mode
|
|
CONFIG_ZMK_SPLIT=y
|
|
```
|
|
|
|
|
|
## Building the firmware
|
|
|
|
:::warning
|
|
Before flashing your new firmware, flash the `settings_reset` firmware on all devices.
|
|
:::
|
|
|
|
Add the appropriate lines to your `build.yml` file to build the firmware for your dongle, in addition to the other parts of your keyboard.
|
|
|
|
```yaml
|
|
include:
|
|
# -----------------------------------------
|
|
# Your other keyboard parts here
|
|
# -----------------------------------------
|
|
- board: nice_nano_v2
|
|
shield: my_keyboard_dongle
|
|
```
|