docs: Convert "boards, shields, and keymaps" page into category index #2634
Conversation
There was a problem hiding this comment.
Thanks for touching on this, it's been very necessary. In addition to the minor points I raised, I wonder if some parts of the text could be broken up a bit with admonitions, images, or code blocks. Currently it's very "wall-of-text"y which makes it difficult to read.
EDIT: Thinking about the title issue some more, perhaps the best approach would be to make this be the index of the hardware integration section?
|
|
||
| With this type of keyboard, the full ZMK definition for the keyboard exists | ||
| in the `app/boards/${arch}/${board_name}` directory, e.g. `app/boards/arm/planck/`. In that directory, you'll have the following: | ||
| With this type of keyboard, the full ZMK definition for the keyboard exists in the `app/boards/<arch>/<keyboard_name>` directory, e.g. `app/boards/arm/planck/`. |
There was a problem hiding this comment.
I think some rephrasing to account for both in-tree and out-of-tree definitions would be good here.
There was a problem hiding this comment.
Addressed in the new version, although not in a very fundamental way.
docs/docs/development/hardware-integration/boards-shields-keymaps.md
Outdated
Show resolved
Hide resolved
| These three core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that | ||
| keyboard works. For an overview on the general concepts of boards and shields, please see the [FAQs on boards and shields](../../faq.md#why-boards-and-shields-why-not-just-keyboard). | ||
| These core architectural elements are defined per-keyboard, and _where_ they are defined depends on the specifics of how that keyboard is built. | ||
| For an overview on the general concepts of boards and shields, also see the [FAQs on boards and shields](../../faq.md#why-boards-and-shields-why-not-just-keyboard). |
There was a problem hiding this comment.
I think it might be nice to move that info here and linking here from FAQ, or extracting the relevant text into files and importing it into both. Depends on whether we make hardware integration a top level section.
There was a problem hiding this comment.
Good point, I'll have a look at pulling that information in here. I think it'd be fine to link to this page from the FAQ in that case.
There was a problem hiding this comment.
I pulled the board/shield definitions here but left the "why" in the FAQ, seemed to fit better there. I summarized the why in a sentence in the intro.
docs/docs/development/hardware-integration/boards-shields-keymaps.md
Outdated
Show resolved
Hide resolved
docs/docs/development/hardware-integration/boards-shields-keymaps.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Nicolas Munnich <[email protected]>
|
I like the idea of making this the index page for Hardware Integration. I can make it a more "overview" kind of page with an introductory blurb and more pointers to subpages. I am not sure how to specifically fix the wall-of-text issue. One improvement I can think of are code blocks showing |
|
Perhaps some images of pcbs/pcb renders of a keyboard with an on-board MCU vs a board+shield combo? I'm not really sure either. I'd say revisit that point once you've done the reworking making this the index page, it could be that the problem resolves itself. |
caksoylar
changed the title
|
I made some changes like we discussed -- I can take or leave the last two commits, let me know what you think. |
| This section of the documentation describes steps necessary to get ZMK running on a keyboard. | ||
| Please see pages in the sidebar for guides and reference that describe different aspects of this integration. |
There was a problem hiding this comment.
I think this could use some rephrasing, since the section provides (will provide?) more info than just the basics of getting ZMK running, but general info on how to set up various peripherals etc. as well.
|
|
||
| ZMK uses the Zephyr concepts of "boards" and "shields" to refer to different parts of a keyboard build, that in turn get combined during a firmware build. | ||
| This provides the modularity to be able to use [composite keyboards](#composite-keyboards) with different compatible controllers. | ||
| Also see the "Why boards and shields" question in the [FAQ](../../faq.md#why-boards-and-shields-why-not-just-keyboard) for a longer explanation. |
There was a problem hiding this comment.
I'm not a fan of the circular linking happening here. I think we should just pull all of that out of the FAQ and move it here, rather than splitting it in half.
| ``` | ||
| <keyboard_name> | ||
| ├── Kconfig.board | ||
| ├── Kconfig.defconfig | ||
| ├── board.cmake | ||
| ├── <board_name>.dts | ||
| ├── <board_name>_defconfig | ||
| ├── <keyboard_name>.keymap | ||
| └── <keyboard_name>.zmk.yml | ||
| ``` |
There was a problem hiding this comment.
I think this tree (and the later one) should come in front of the itemised list, with the sentences adjusted accordingly.
| - A `Kconfig.board` file that defines the toplevel [Kconfig](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html) items for the board, including which SoC Kconfig setting it depends on. | ||
| - A `Kconfig.defconfig` file that sets some initial defaults when building this keyboard. This usually includes: | ||
| - Setting `ZMK_KEYBOARD_NAME` to a value, for the product name to be used for USB/BLE info. | ||
| - Setting `ZMK_USB` and/or `ZMK_BLE` for the default values for which HID transport(s) to enable by default | ||
| - A `<board_name>_defconfig` file that forces specific Kconfig settings that are specific to this hardware configuration. | ||
| These are mostly SoC settings around the specific hardware configuration. | ||
| - `<board_name>.dts` which contains all the devicetree definitions[^1], including but not limited to: | ||
| - An `#include` line that pulls in the specific microprocessor that is used, e.g. `#include <st/f3/stm32f303Xc.dtsi>`. | ||
| - Kscan, matrix transform and physical layout devicetree nodes as described above | ||
| - A [chosen](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including `zmk,physical-layout` property among others, where each property references the nodes defined in the file. | ||
| - A `board.cmake` file with CMake directives for how to flash to the device. | ||
| - A `<keyboard_name>.keymap` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs. | ||
| - A `<keyboard_name>.zmk.yml` file containing [metadata](hardware-metadata-files.md) for the keyboard. |
There was a problem hiding this comment.
This all still feels very verbose, and it also feels somewhat duplicatey. Perhaps separating out the kconfig, devicetree, and the other files would help? Also wonder if it might be better to link to config sections for things like ZMK_KEYBOARD_NAME.
There was a problem hiding this comment.
Yeah, it seems sensible to split these by category. I'll add a link to the config page for those as well.
|
|
||
| In ZMK, a _shield_ is a _PCB_ or _hardwired set of components_ that when combined with an MCU-only board, like the SparkFun Pro Micro RP2040 or nice!nano, results in a complete usable keyboard. | ||
| Examples would be keyboard PCBs like the Kyria or Lily58. | ||
| he shield is usually the big PCB containing all the keys. |
There was a problem hiding this comment.
| he shield is usually the big PCB containing all the keys. | |
| The shield is usually the big PCB containing all the keys. |
This page https://zmk.dev/docs/development/hardware-integration/boards-shields-keymaps is a good explainer for both the high level concepts needed to define a ZMK keyboard, and also a decent overview for file/folder structure. However it contained some errors and was also outdated in some respects.
I attempted to fix the issues, update and generalize it a little further. I think this page is a bit out-of-place as an explainer and can be refactored into other places later, but meanwhile it still seems valuable to keep.
However, I have an issue with the name and title of this page. "Boards, shields, and keymaps" does not seem descriptive of this overview/explainer but I am drawing a blank on a better name right now. Any suggestions welcome.