Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
caksoylar opened this issue Sep 21, 2021 · 4 comments · Fixed by #2406
Closed

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

caksoylar opened this issue Sep 21, 2021 · 4 comments · Fixed by #2406
Labels
documentation Improvements or additions to documentation split

Comments

@caksoylar
Copy link
Contributor

caksoylar commented Sep 21, 2021

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 Invoke behaviors with different "locality" #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
@caksoylar caksoylar changed the title docs: Add a "feature" page on split boards/shields docs: Add a feature page on split boards/shields Sep 21, 2021
@dxmh
Copy link
Collaborator

dxmh commented Sep 23, 2021

Related: #550

@dxmh dxmh added documentation Improvements or additions to documentation split labels Sep 23, 2021
@dxmh
Copy link
Collaborator

dxmh commented Sep 23, 2021

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

Somewhat relevant PR:

@caksoylar
Copy link
Contributor Author

Added it to the list, thanks!

@dxmh
Copy link
Collaborator

dxmh commented Feb 12, 2022

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.

Related conversation on Discord: https://discord.com/channels/719497620560543766/719909884769992755/941708637523574814

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation split
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants