docs: Add a feature page on split boards/shields

caksoylar commented 3 years ago

I noticed that there isn't a unified location on the docs on how split keyboards work with ZMK, while there are a few pieces of information in some pages such as the FAQ. Would it be helpful to have a "Split Keyboards" page, maybe under "Features" that details how they work?

A few things that come to my mind that we might document in such a page:

Central/peripheral definitions clarified w.r.t. left/right halves
Noting the peripheral only communicates with the central over BLE, then central to other devices through USB/BLE
Noting reset behaviors &reset, &bootloader only affect central side -- or the source side of the behavior when #547 is merged
Two firmwares _left and _right are produced to be flashed to two halves
Link to "New shield" page on developing new split shields
"Dongle mode"-related information in the future can also be placed here and the page title could be changed to reflect the generalization to multiple peripherals

dxmh commented 3 years ago

It would also be good to cover how things like &reset behave on splits, etc.

Somewhat relevant PR:

547

caksoylar commented 3 years ago

Added it to the list, thanks!

dxmh commented 2 years ago

I think such a page could also be good place to document the frequently asked question of setting up left and right halves each as "central" (e.g. CONFIG_ZMK_SPLIT=n, different ZMK_KEYBOARD_NAME for each), along with some of the caveats such as no shared layer state, OS compatibility with cross-half modifiers (e.g. works on Linux, requires additional software on macOS), potential incompatibly with cross-half mod-taps, etc.

zmkfirmware / zmk

docs: Add a feature page on split boards/shields #948

547