docs: revise keyboard dongle guide#3405
Conversation
For the keyboard dongle page, the main change is now it instructs the user to use the same physical layout(s) instead of making new ones for the dongle. The rest are mostly formatting and wording changes, and some clarifications. Also adjusted the new shield guide to include some information about multi-peripheral split setup. Added a new "ReadMore" component as an alternative to admonitions with less visual importance, for linking to other pages.
| The approach described below assumes the dongle will not have any keys assigned to itself, so it will not work for that scenario. | ||
| If you want to understand the details of how it all works better, please read through the [new shield guide](new-shield.mdx). | ||
| This guide assumes that you are adding a dongle to an existing keyboard definition, with the keyboard boards and/or shields defined in the main ZMK repository or external modules. | ||
| The dongle shield is defined in your personal ZMK config, no change is needed to the existing keyboard boards and/or shields. |
There was a problem hiding this comment.
This needs some sort of introductory phrase to make it read more natural. Maybe a reorganization like this:
This guide describes a dongle setup where we add the dongle as a new part with no keys with the central role, then switch the role of existing keyboard parts to peripheral.
It assumes that you are adding a dongle to an existing keyboard definition, with the keyboard boards and/or shields defined in the main ZMK repository or external modules.
The dongle shield is defined in your personal ZMK config, no change is needed to the existing keyboard boards and/or shields.
|
|
||
| As there are a very large number of possible devices that could be used as a dongle, you will be defining your dongle as a personal shield intended for your exclusive use. | ||
| If you are creating a new keyboard, the dongle shield can be defined together with other parts of the keyboard. | ||
| Follow the [new keyboard shield guide](../hardware-integration/new-shield.mdx) and repeat the steps for "right" for each peripheral part of the keyboard. |
There was a problem hiding this comment.
The newly added "split keyboards with more than two parts" expanders cover the repeating remark, so we could probably omit that.
| If you are creating a new keyboard, the dongle shield can be defined together with other parts of the keyboard. | ||
| Follow the [new keyboard shield guide](../hardware-integration/new-shield.mdx) and repeat the steps for "right" for each peripheral part of the keyboard. | ||
|
|
||
| Prior to adding a dongle to your keyboard, please test its functionality without a dongle. The below guide will assume that your keyboard is named `my_keyboard`, replace accordingly. |
There was a problem hiding this comment.
Why remove the my_keyboard remark?
There was a problem hiding this comment.
Instead of:
- ... assume that your keyboard is named
my_keyboard, replace accordingly - Create a subdirectory called
my_keyboard
Now it's worded:
- create a subdirectory with your keyboard's name
- for example
my_keyboard
So I feel this is not needed anymore.
There was a problem hiding this comment.
I see it now, mentioned under the Dongle Folder section. On second thought, maybe it'd be better to explicitly introduce this at the beginning? It bothers me that we aren't properly distinguishing keyboard name from shield/part names (not new with this PR), which also came up in the other comments I left. Something like:
This guide describes creating a shield for a keyboard, named
my_keyboardin below examples. The corresponding shield name is the same, unless the keyboard is a split keyboard where it will have two "part" shields namedmy_keyboard_leftandmy_keyboard_right.
There was a problem hiding this comment.
Added a new sentence about naming under the Dongle Folder section and removed the one under Kconfig.shield.
I skipped the part about the name of other parts, IMHO it sounds a bit too wordy and I had to read it twice to parse the meaning. Hopefully the current wording in the latest commit is clear enough.
After reading https://docs.zephyrproject.org/latest/hardware/porting/shields.html#shield-variants I do agree the current shield name terminology usage is ambiguous, but that would be addressed separately.
| def_bool $(shields_list_contains,my_keyboard_dongle) | ||
| ``` | ||
|
|
||
| To use the same keymap file, the dongle shield name should match other parts of the keyboard, e.g. `my_keyboard_dongle` if other parts are named `my_keyboard` (for unibody) or `my_keyboard_left` (for split). |
There was a problem hiding this comment.
This actually goes by the containing folder's name, which is the "keyboard name." The names of the parent folders of the main shield/board definition for the keyboard and the dongle's should match
There was a problem hiding this comment.
Looking at https://github.com/zmkfirmware/zmk/blob/main/app/boards/post_boards_shields.cmake, I don't think the folder name is used anywhere. On line 84, ${SHIELD_DIR} is part of the keymap_prefix foreach but I searched both ZMK and Zephyr and I can't find where it's defined.
There was a problem hiding this comment.
The shield_dir_name extracted in line 16, 40 etc. is the folder name of the shield, and I think the SHIELD_DIR_${s} it is extracted from is defined in https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/cmake/modules/shields.cmake#L70 as the folder path containing the shield.overlay (for a shield example, also applies to boards). shield_dir_name in turn gets saved in shield_candidate_names which gets used for .keymap lookup etc.
|
|
||
| [^1]: If you have a custom dongle that uses an onboard MCU, then you will need to take a slightly different approach that isn't currently documented. | ||
|
|
||
| [^2]: If you are building locally, you can append these flags to the end of the [build command](../development/local-toolchain/build-flash.mdx#cmake-arguments). |
There was a problem hiding this comment.
This might bo good to keep somewhere.
Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
| This should look something like this: | ||
| <ReadMore> | ||
| See [Devicetree Overview](../development/devicetree.md) for details on the devicetree format. | ||
| format. |
2 participants
Semi-follow-up to #3371
Preview: https://deploy-preview-3405--zmk.netlify.app/docs/hardware-integration/dongle
Added a new "ReadMore" component with much less visual emphasis than admonitions.
Content wise, the main changes are:
my_keyboardplaceholder.Since some people were asking how to make "dongle with keys", added few sections to the new keyboard shield guide to show multi-peripheral setup.
PR check-list
N/A