feat(docs) Adds a feature page about dongles #2401
Conversation
There was a problem hiding this comment.
Thanks for the PR! There has been some discussion on simplifying the dongle setup, but I think there's enough demand for them that it would be useful to document the current state of things.
I think it would be good to scrub all references to split keyboards from the page, and focus on dongles entirely. A separate page can handle the discussion on split keyboards, That would let this page be streamlined a bunch.
My current line of thought is to have this PR be included in a "Blueprints" category following the idea started in #1952, rather than under the features category. I plan on putting some time into that soon, and would like to "eat" this PR (still giving you author credits ofc) for that purpose when I get around to it. Your thoughts?
I wanted to include some of the split information, because there could be builds that implement 3 splits or more (using a numpad as a third split comes to mind) so that is why I did not wish to box it in as much. If we rename and change this to just dongles, then yes, it does make sense to just streamline it. I do not mind if this is moved under somewhere else nor care if I get any credit for writing. I am just trying to give back to the ZMK community for all the free help I am getting. |
|
I also think that now it makes sense to rename the file from splits to dongles, just want avoid any renaming until the doc review is completed |
|
Hi @RasmusKoit, thank you very much for taking the initiative to tackle this. I think it's a good idea to have a guide such as this one to describe the why and how of "dongle" keyboards. However I think it is a bit awkward to have this without first having an explainer page on split keyboards in general. This would also save you from repeating any information in there. My understanding from here/Discord is @Nick-Munnich had similar thoughts and this page right now is being geared more towards being a recipe/blueprint? If so, I think that's a good approach. This pushed me a bit to write a split keyboards feature page at #2406 so we have a good base to add on to. Appreciate the contribution! |
RasmusKoit
changed the title
|
@Nick-Munnich @caksoylar I've improved the document again and would like another review please |
|
Also just going to add that this closes #2044. |
…ut reset behavior
adds a nice picture
Make the documentation more specific to dongles. Moves some of the configuration around. Adds an option for building firmware with left as central. Clarifies different MCU usages. Normalizes file names. Removes duplicate warning.
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
some restructure to cfg files
|
I think a note that this requires defining a custom shield and a pointer to new shield guide as a prerequisite is needed on this page. |
There was a problem hiding this comment.
In my opinion, it should be mentioned somewhere that the number of available profiles will be reduced if CONFIG_BT_MAX_CONN and CONFIG_BT_MAX_PAIRED are not adjusted accordingly (ZMK_BLE_PROFILE_COUNT = CONFIG_BT_MAX_PAIRED - CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS).
One small thing: The definitions in zephyr and zmk are not indented within the if/endif blocks. I would remain consistent with the new-shield guide where there are also no indents.
|
|
||
| ```dts title="my_keyboard_dongle.overlay" | ||
| // import the default shield configuration | ||
| #include "my_keyboard.dtsi" |
There was a problem hiding this comment.
If the common shield configuration is imported and different boards are used for the dongle than for the shields, then this can lead to problems if board-specific aliases (e.g. &pro_micro, &xiao_d) are used.
I therefore had to delete unused nodes with these aliases (e.g. /delete-node/ &kscan0;), but perhaps there is a nicer solution.
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
Co-authored-by: Nicolas Munnich <98408764+Nick-Munnich@users.noreply.github.com>
Co-authored-by: 5Y1VN <86794811+5y1vn@users.noreply.github.com>
Co-authored-by: Maximilian Engl <43675074+englmaxi@users.noreply.github.com>
Fixes pwr choice config improves wording
| config ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS | ||
| default 2 |
There was a problem hiding this comment.
I was not able to overwrite the default like this. During my testing, it only worked inside the .conf file. Have you tested this successfully?
There was a problem hiding this comment.
i have not as i also used a conf
https://github.com/RasmusKoit/pipar/blob/master/config/boards/shields/pipar/pipar_dongle.conf , at some point i shifted from real world examples to what is supposed to be more correct
|
At least as I understand the functionality, displays on both the splits become "peripheral" and are unable to display, for example, active layer. If so, that seems like a significant disadvantage. Edit: Thinking through this, it might be an advantage with, for example, a dongle at the bottom of a monitor that can display information in an arguably easier to glance at location than on the keyboard. |
| config ZMK_SPLIT | ||
| default y | ||
|
|
||
|
|
There was a problem hiding this comment.
In my opinion, this [power increase] is optional and unrelated to using a dongle. I agree it may be helpful and perhaps merits a text reference to documentation of BT_CTLR_TX_PWR_PLUS_8 such as https://zmk.dev/docs/troubleshooting/connection-issues
| :::note | ||
| Depending on how the dongle is used, there are some additional [latency considerations](./split-keyboards.md#latency-considerations) to keep in mind. | ||
| On average, the latency increase is around 3.75ms, in worst case scenario, the latency increase can be up to 7.5ms compared to a unibody keyboard. | ||
| ::: |
There was a problem hiding this comment.
From a product liability perspective, I'd say "in some situations, ..." as poor Bluetooth connectivity can push latency even higher. Is it worth calling out one of the more common scenarios?
|
Hey All, |
Hey @jasper-at-windswept for a functionally working build you can check https://github.com/RasmusKoit/pipar or https://github.com/RasmusKoit/miryoku_zmk |
|
@RasmusKoit |
|
Please keep in mind that pipar uses Xiao ble and not a pro micro, you can reference both this doc and the repo to find the right combination though. Please let me know if you get stuck again |
|
Hey @RasmusKoit |
|
please flash each part with the reset firmware first! then you should get it working |
|
@RasmusKoit |
Contains a quick setup for using a dongle or adding a third split as central
Related to discussion started by user caksoylar under issue #948