feat(docs) Adds a feature page about dongles

docs/docs/features/dongle.mdx

@@ -0,0 +1,208 @@
+---
+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.
+
+The information below is for [shield+board](../faq.md#why-boards-and-shields-why-not-just-keyboard) configuration, [board](../faq.md#what-is-a-board) builds is not documented.
+:::
+
+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.
+
+:::note
+Depending on how the dongle is used, there are some additional [latency considerations](./split-keyboards.md#latency-considerations) to keep in mind. 
+:::
+
+
+## Editing a Keyboard Definition to Support a Dongle
+
+You will modify the [files defining your keyboard](../config/index.md#shield-folder) to support a dongle. 
+The recommended approach to doing so (found below) allows you to easily enable a dongle, but it is disabled by default. 
+This is done to ensure that backwards compatibility is maintained for users who do not wish to use a dongle.
+
+### Shield Configuration Files
+
+
+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)
+```
+
+### Shield Defconfig Files
+
+Next, add the dongle configuration to your keyboard's `Kconfig.defconfig`.
+
+<Tabs
+defaultValue="unibody"
+values={[
+{label: 'Unibody Keyboard', value: 'unibody'},
+{label: 'Split Keyboard', value: 'split'},
+]}
+>
+<TabItem value="unibody">
+
+```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">
+
+Add the following to your `Kconfig.defconfig` file.
+
+```kconfig title="Kconfig.defconfig"
+if SHIELD_MY_KEYBOARD_DONGLE || SHIELD_MY_KEYBOARD_LEFT || SHIELD_MY_KEYBOARD_RIGHT
+
+    config ZMK_SPLIT
+        default y
+
+endif
+
+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
+```
+
+Modify the `Kconfig.defconfig` file to include the following:
+
+```kconfig title="Kconfig.defconfig"
+
+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
+```
+
+</TabItem>
+</Tabs>
+
+### Dongle Overlay File
+
+Replace the `kscan` with `kscan-mock` in the dongle overlay.
+
+:::warning
+Matrix transform must be included here or in the `my_keyboard.dtsi` file.
+:::
+
+```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 it is possible to 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
+
+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
+  - board: nice_nano_v2
+    shield: settings_reset
+```
+
+:::note
+Any microcontroller with BLE support can be used as a dongle.
+:::
+
+:::warning
+Before flashing your new firmware, flash the `settings_reset` [UF2 firmware](../troubleshooting/connection-issues.mdx#acquiring-a-reset-uf2) on all devices.
+:::

docs/sidebars.js

@@ -44,6 +44,7 @@ module.exports = {
         "features/backlight",
         "features/battery",
         "features/soft-off",
+        "features/dongle",
       ],
     },
     {