docs: added a page on dongles #2525
Conversation
There was a problem hiding this comment.
It might be good to add a pointer from split keyboards feature page to here, saying it is also used for creating "dongles".
I think this is well written overall. As a side note, it is a bit too prescriptive for my taste (do this, then do this, rather than explaining how the config works) but given the current complexity of the setup it seems unavoidable, assuming we do want to document how to do it.
This was intentional, since we keep getting people asking for help setting up a dongle for their keyboard who have not done the whole shield porting thing. I see the dongle setup as just a highly simplified and prescriptive version of the shield docs. I'll adjust to refer readers to the shield guide a bit stronger if they want to understand any details. |
Nick-Munnich
force-pushed
the
dongles
branch
3 times, most recently
from
37522c4 to
ee6f514
Compare
Nick-Munnich
force-pushed
the
dongles
branch
2 times, most recently
from
8530c73 to
c3582ae
Compare
Co-authored-by: rasmuskoit <[email protected]> Co-authored-by: Cem Aksoylar <[email protected]>
Nick-Munnich
force-pushed
the
dongles
branch
from
c3582ae to
70efa98
Compare
| Navigate to the directory defining your keyboard (in-tree keyboards found [here](https://github.com/zmkfirmware/zmk/tree/main/app/boards)) and look through the [devicetree files](../../config/index.md) for nodes with `compatible = "zmk,matrix-transform";`. | ||
| This should look something like this: |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Do you think a note saying "for a shield+board keyboard look under boards/shields" would have helped?
There was a problem hiding this comment.
Yes!
The problem that I had is that instead of cloning the repo, I was trying to find it looking through the GitHub repo. But I missed the board that I was trying to find.
Silly mistake, but can cause some questions like mine to appear
| }; | ||
| ``` | ||
|
|
||
| Copy this node into your `my_keyboard_dongle.overlay` file. Take care to put it under the root node (the `/ { ... };` node). |
There was a problem hiding this comment.
Take care to put it under the root node
Didn't you mean "inside" instead of "under"?
I did not tried to compile it yet, but it "feels" more right to put it contained by the root node.
Or maybe it is just a language barrier because of how I interpret the word "under" as a non native english speaker
There was a problem hiding this comment.
From what I have tested it should be inside the root node
|
|
||
| Make sure that the labels `physical_layout0` and `default_transform` match those of the physical layout node defined in the file and the matrix transform respectively. | ||
|
|
||
| If there are multiple physical layouts in the file, you will need to copy over all of the remaining matrix transformations and assign them similarly. |
There was a problem hiding this comment.
Wouldn't it be better if we put the entire section related to the case of having multiple layouts under a new title?
Something like #### If there are multiple physical layouts in the file.
This is because the next topics seem to have no clear connection with the previous one
Look at:
Copy the physical layout node into your...
Seems like there should be a "In this case," before the text to maintain cohesion.
Or it could be done by a new title that contains all that block.
Without it, I feel that users can get confused to know how far they should follow the instructions
| - board: nice_nano_v2 | ||
| shield: my_keyboard_dongle |
There was a problem hiding this comment.
What about ZMK Studio?
Should we add cmake-args to make it work?
Something like:
- board: nice_nano_v2
shield: my_keyboard_dongle
# cmake-args: -DCONFIG_ZMK_STUDIO=y # For ZMK Studio to work
I may be wrong, because mine is not compiling with that arg and I am trying to figure out why
Added a page on configuring dongles, building on the work that @RasmusKoit did in #2401. The method recommended is personal to each user, but works for both boards and shield based keyboards (requires a board for the dongle, to avoid users messing with flash etc).
Subsumes #2401, closes #2044.