diff --git a/docs/docs/development/hardware-integration/index.mdx b/docs/docs/development/hardware-integration/index.mdx index 95e1e3715..a9da0109d 100644 --- a/docs/docs/development/hardware-integration/index.mdx +++ b/docs/docs/development/hardware-integration/index.mdx @@ -111,7 +111,7 @@ And other miscellaneous ones: - A `.zmk.yml` file containing [metadata](hardware-metadata-files.md) for the keyboard. See Zephyr's [board porting guide](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html) for information on creating a new board. -Also see the [new keyboard shield guide](new-shield.mdx#shield-overlays) for information on parts of the devicetree specifically related to ZMK. +See also our [new board guide](new-board.md) for information on creating a ZMK-compatible board variant. [^1]: Parts of these files can live in separate `.dtsi` files (typically in the same directory) that are then `#include`d in the files, to reduce duplication or improve organization. diff --git a/docs/docs/development/hardware-integration/new-board.md b/docs/docs/development/hardware-integration/new-board.md index af2b26fec..ebaf03ec1 100644 --- a/docs/docs/development/hardware-integration/new-board.md +++ b/docs/docs/development/hardware-integration/new-board.md @@ -2,9 +2,9 @@ title: New Board --- -This guide will walk through the necessary steps to write a board suitable for use with ZMK. Boards used with ZMK fall into two categories: +This guide will walk through the necessary steps to write a [board](./index.mdx#boards--shields) suitable for use with ZMK. Boards used with ZMK fall into two categories: -- Boards with interconnects, such as `nice_nano` or `seeed_xiao`. Such boards will (active development of ZMK aside) always be used with a shield. +- Boards with interconnects, such as `nice_nano` or `seeed_xiao`. Such boards will (active development of ZMK aside) always be used with a shield to create a keyboard. - Boards that are themselves keyboards, such as `bt75` or `ferris`. Some keyboards are boards but also have interconnects for modular add-ons. These are considered as keyboard-boards for the purpose of this guide. Details on adding an interconnect for modular add-ons are considered out of scope. @@ -86,7 +86,13 @@ board: ### Add Kconfig for ZMK Variant -Add a file to your board's folder called `_zmk_defconfig`. This file will be used to set Kconfig flags specific to the ZMK variant. These flags are typically a subset of the following: +Add a file to your board's folder called `_zmk_defconfig`. This file will be used to set Kconfig flags specific to the ZMK variant. + +:::warning +Make sure you know what each Kconfig flag does before you enable it. Some flags may be incompatible with certain hardware, or have other adverse effects. +::: + +These flags are typically a subset of the following: ```yaml title="_zmk_defconfig" # SPDX-License-Identifier: @@ -138,7 +144,7 @@ CONFIG_GPIO=y CONFIG_ZMK_KSCAN_MATRIX_POLLING=y ``` -Note that none of our in-tree boards have all of the above flags set. We recommend copying the Kconfig flags from an existing in-tree board with the same SoC as the one you are using, rather than figuring out which ones you need yourself. +Note that none of our in-tree boards have all of the above flags set. We recommend referencing the Kconfig flags from an existing in-tree board with the same SoC as the one you are using for your initial definition, making sure you understand what each flag does. ### Add Devicetree for ZMK Variant @@ -149,15 +155,15 @@ Note that none of our in-tree boards have all of the above flags set. We recomme * SPDX-License-Identifier: */ -//include the base board definition +// Include the base board definition #include <../boards///.dts> -//include predefined boot mode settings, e.g. +// Include predefined boot mode settings, e.g. #include -//disable UART nodes if they are not actively in use (wired split) as they increase power draw +// Disable UART nodes if they are not actively in use (wired split) as they increase power draw &uart0 { status = "disabled"; }; -//reduce the code partition section of the memory and add a storage partition to store ZMK Studio changes +// Reduce the code partition section of the memory and add a storage partition to store ZMK Studio changes &code_partition { reg = <0x100 (DT_SIZE_M(2) - 0x100 - DT_SIZE_K(512))>; }; @@ -176,6 +182,6 @@ See [here](./bootloader/index.mdx) for bootloader instructions for other SoCs. D ## Next Steps -If your board is a keyboard, continue from ["Kconfig.defconfig"](https://zmk.dev/docs/development/hardware-integration/new-shield?keyboard-type=unibody#kconfigdefconfig) of the new shield guide. Use your ZMK variant's devicetree instead of the overlay file which would be used for a shield. +If your board is a keyboard, continue from [the `Kconfig.defconfig` step](https://zmk.dev/docs/development/hardware-integration/new-shield?keyboard-type=unibody#kconfigdefconfig) of the new shield guide. Use your ZMK variant's devicetree instead of the overlay file which would be used for a shield. If your board is a board with an interconnect, your next step should be to write a [tester shield](../../troubleshooting/hardware-issues.mdx#identifying-issues). Such a shield should be the bare minimum shield to verify that your board works with ZMK. diff --git a/docs/sidebars.js b/docs/sidebars.js index 29d4f23e1..b52803b9a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -148,7 +148,6 @@ module.exports = { }, collapsed: true, items: [ - "development/hardware-integration/new-board", "development/hardware-integration/new-shield", "development/hardware-integration/physical-layouts", "development/hardware-integration/hardware-metadata-files", @@ -158,6 +157,7 @@ module.exports = { "development/hardware-integration/encoders", "development/hardware-integration/soft-off-setup", "development/hardware-integration/pointing", + "development/hardware-integration/new-board", "development/hardware-integration/battery", { type: "category",