From 35543dc5088889dec72198815aba0362bec32b27 Mon Sep 17 00:00:00 2001 From: Nicolas Munnich Date: Mon, 16 Dec 2024 00:47:33 +0100 Subject: [PATCH] docs: Configuration page overhaul --- docs/blog/2020-08-12-zmk-sotf-1.md | 2 +- docs/blog/2021-07-17-zephyr-2-5.md | 2 +- .../2022-03-08-zephyr-3-0-upgrade-prep.md | 2 +- docs/blog/2022-04-02-zephyr-3-0.md | 2 +- docs/blog/2022-04-10-zmk-sotf-5.md | 2 +- docs/blog/2022-04-21-zmk-2yo.md | 2 +- docs/blog/2023-10-05-zmk-sotf-6.md | 2 +- docs/blog/2024-01-05-zmk-tools.md | 2 +- docs/docs/customization.md | 78 ------ .../hardware-integration/index.mdx | 8 +- .../hardware-integration/new-shield.mdx | 4 +- .../local-toolchain/build-flash.mdx | 2 +- docs/docs/development/usb-logging.mdx | 2 +- docs/docs/features/modules.mdx | 4 +- docs/docs/features/split-keyboards.md | 2 +- .../customisation/devicetree.md | 235 ++++++++++++++++++ .../getting-started/customisation/index.md | 136 ++++++++++ .../getting-started/customisation/kconfig.md | 3 + docs/docs/{ => getting-started}/faq.md | 0 docs/docs/{ => getting-started}/hardware.mdx | 0 docs/docs/{ => getting-started}/intro.md | 0 .../{ => getting-started}/keymap-example.md | 0 .../{ => getting-started}/user-setup-cli.mdx | 2 +- .../docs/{ => getting-started}/user-setup.mdx | 4 +- docs/docs/keymaps/index.mdx | 2 +- .../troubleshooting/connection-issues.mdx | 2 +- docs/sidebars.js | 22 +- 27 files changed, 415 insertions(+), 107 deletions(-) delete mode 100644 docs/docs/customization.md create mode 100644 docs/docs/getting-started/customisation/devicetree.md create mode 100644 docs/docs/getting-started/customisation/index.md create mode 100644 docs/docs/getting-started/customisation/kconfig.md rename docs/docs/{ => getting-started}/faq.md (100%) rename docs/docs/{ => getting-started}/hardware.mdx (100%) rename docs/docs/{ => getting-started}/intro.md (100%) rename docs/docs/{ => getting-started}/keymap-example.md (100%) rename docs/docs/{ => getting-started}/user-setup-cli.mdx (99%) rename docs/docs/{ => getting-started}/user-setup.mdx (99%) diff --git a/docs/blog/2020-08-12-zmk-sotf-1.md b/docs/blog/2020-08-12-zmk-sotf-1.md index c93566b1981..d021f007fc9 100644 --- a/docs/blog/2020-08-12-zmk-sotf-1.md +++ b/docs/blog/2020-08-12-zmk-sotf-1.md @@ -18,7 +18,7 @@ There's been lots of various activity in ZMK land! - Tons of [documentation](/docs) work. - Refactoring ([#73](https://github.com/zmkfirmware/zmk/pull/73), [#74](https://github.com/zmkfirmware/zmk/pull/74)) of [keymaps](/docs/keymaps) to make them simpler for users. - Mod-Tap Behavior (docs coming!) is much improved ([#69](https://github.com/zmkfirmware/zmk/pull/69)) and usable now. -- An initial [`setup.sh`](/docs/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you. +- An initial [`setup.sh`](/docs/getting-started/user-setup#user-config-setup-script) script was created, allowing users to quickly bootstrap a "user config" setup and push it to GitHub, where GitHub Actions will build the firmware for you. - Corne shield ([#80](https://github.com/zmkfirmware/zmk/pull/80)) shield definition was added. - Initial [encoder](/docs/features/encoders) support ([#61](https://github.com/zmkfirmware/zmk/pull/61)) was added. diff --git a/docs/blog/2021-07-17-zephyr-2-5.md b/docs/blog/2021-07-17-zephyr-2-5.md index 4d119ade967..9d1d12cb69e 100644 --- a/docs/blog/2021-07-17-zephyr-2-5.md +++ b/docs/blog/2021-07-17-zephyr-2-5.md @@ -39,7 +39,7 @@ and should work, fine as is. However, to upgrade to the newer Docker image, you If you created your user config repository a while ago, you may find that your `build.yml` file instead references a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that -instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation +instead you [re-create your config repository](/docs/getting-started/user-setup) to get an updated setup using the new automation approach. ::: diff --git a/docs/blog/2022-03-08-zephyr-3-0-upgrade-prep.md b/docs/blog/2022-03-08-zephyr-3-0-upgrade-prep.md index 6086991b595..dfcbf251604 100644 --- a/docs/blog/2022-03-08-zephyr-3-0-upgrade-prep.md +++ b/docs/blog/2022-03-08-zephyr-3-0-upgrade-prep.md @@ -22,7 +22,7 @@ A future blog post will outline the complete Zephyr 3.0 changes once that work i If you created your user config repository a while ago, you may find that your `build.yml` file instead references a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that -instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation +instead you [re-create your config repository](/docs/getting-started/user-setup) to get an updated setup using the new automation approach. ::: diff --git a/docs/blog/2022-04-02-zephyr-3-0.md b/docs/blog/2022-04-02-zephyr-3-0.md index 15a79500f61..d675ddbff43 100644 --- a/docs/blog/2022-04-02-zephyr-3-0.md +++ b/docs/blog/2022-04-02-zephyr-3-0.md @@ -40,7 +40,7 @@ Existing user config repositories using Github Actions to build will pull down Z If you created your user config repository a while ago, you may find that your `build.yml` file instead references a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that -instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation +instead you [re-create your config repository](/docs/getting-started/user-setup) to get an updated setup using the new automation approach. ::: diff --git a/docs/blog/2022-04-10-zmk-sotf-5.md b/docs/blog/2022-04-10-zmk-sotf-5.md index 55faeb41c20..1cd9612439f 100644 --- a/docs/blog/2022-04-10-zmk-sotf-5.md +++ b/docs/blog/2022-04-10-zmk-sotf-5.md @@ -219,7 +219,7 @@ This can be useful to be sure that lowering brightness doesn't set the brightnes ## Board/Shield Metadata -[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/development/hardware-integration/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/hardware) page and our +[nicell] and [petejohanson] worked together in [#883](https://github.com/zmkfirmware/zmk/pull/883) to settle on a [metadata format](/docs/development/hardware-integration/hardware-metadata-files) that is used to document every board and shield. This now drives automatic generation of our [supported hardware](/docs/getting-started/hardware) page and our more nuanced GH Actions automation for testing changes to ZMK. ## Coming Soon! diff --git a/docs/blog/2022-04-21-zmk-2yo.md b/docs/blog/2022-04-21-zmk-2yo.md index 102e07489c6..76b0ed42b3f 100644 --- a/docs/blog/2022-04-21-zmk-2yo.md +++ b/docs/blog/2022-04-21-zmk-2yo.md @@ -58,7 +58,7 @@ The day I was finally able to type on a wireless, split keyboard running ZMK was ## Onward and Upward -We've come a long way since then, with our [supported hardware](/docs/hardware), [features](/docs/keymaps) and [behaviors](/docs/keymaps/behaviors/key-press) growing regularly. +We've come a long way since then, with our [supported hardware](/docs/getting-started/hardware), [features](/docs/keymaps) and [behaviors](/docs/keymaps/behaviors/key-press) growing regularly. ZMK powered keyboards are now available in group buys and in stock at various vendors; compatible controllers have been used in a wide range of builds to empower our users to free themselves from their USB/TRRS cables and move about untethered. diff --git a/docs/blog/2023-10-05-zmk-sotf-6.md b/docs/blog/2023-10-05-zmk-sotf-6.md index b0c8c4d894e..1daba74e6cc 100644 --- a/docs/blog/2023-10-05-zmk-sotf-6.md +++ b/docs/blog/2023-10-05-zmk-sotf-6.md @@ -185,7 +185,7 @@ In addition to the specific contributions listed above, various improvements and #### Reusable GitHub build workflow -[elagil](https://github.com/elagil) helped switch the build workflow used by the [user config repos](/docs/user-setup) to a reusable one in [#1183](https://github.com/zmkfirmware/zmk/pull/1183) and it was further tweaked by [filterpaper] in [#1258](https://github.com/zmkfirmware/zmk/pull/1258). This allows any changes in the workflow to be propagated automatically to users, rather than requiring them to make the updates. The build workflow can be customized by the users [using input parameters](https://github.com/zmkfirmware/zmk/blob/main/.github/workflows/build-user-config.yml#L5) if desired. +[elagil](https://github.com/elagil) helped switch the build workflow used by the [user config repos](/docs/getting-started/user-setup) to a reusable one in [#1183](https://github.com/zmkfirmware/zmk/pull/1183) and it was further tweaked by [filterpaper] in [#1258](https://github.com/zmkfirmware/zmk/pull/1258). This allows any changes in the workflow to be propagated automatically to users, rather than requiring them to make the updates. The build workflow can be customized by the users [using input parameters](https://github.com/zmkfirmware/zmk/blob/main/.github/workflows/build-user-config.yml#L5) if desired. #### Pre-commit hooks diff --git a/docs/blog/2024-01-05-zmk-tools.md b/docs/blog/2024-01-05-zmk-tools.md index 1104396d036..16ceb000124 100644 --- a/docs/blog/2024-01-05-zmk-tools.md +++ b/docs/blog/2024-01-05-zmk-tools.md @@ -19,7 +19,7 @@ Stay tuned for future installments in the series! ## ZMK Tools -[ZMK Tools](https://github.com/joelspadin/zmk-tools) is an extension for [Visual Studio Code](https://code.visualstudio.com) that helps with editing a ZMK user config repo or a fork of ZMK. I originally created it to add some code completion in `.keymap` files, but then I realized that with the web version of VS Code, I could also let you set up a user config repo and build firmware, much like the [user setup script](/docs/user-setup#user-config-setup-script), except without downloading a single thing. +[ZMK Tools](https://github.com/joelspadin/zmk-tools) is an extension for [Visual Studio Code](https://code.visualstudio.com) that helps with editing a ZMK user config repo or a fork of ZMK. I originally created it to add some code completion in `.keymap` files, but then I realized that with the web version of VS Code, I could also let you set up a user config repo and build firmware, much like the [user setup script](/docs/getting-started/user-setup#user-config-setup-script), except without downloading a single thing. ### User Config Setup in Browser diff --git a/docs/docs/customization.md b/docs/docs/customization.md deleted file mode 100644 index e35bb426713..00000000000 --- a/docs/docs/customization.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Customizing ZMK/zmk-config folders -sidebar_label: Customizing ZMK ---- - -After verifying you can successfully flash the default firmware, you will probably want to begin customizing your keymap and other keyboard options. -[In the initial setup tutorial](user-setup.mdx), you created a Github repository called `zmk-config`. This repository is a discrete filesystem which works -with the main `zmk` firmware repository to build your desired firmware. The main advantage of a discrete configuration folder is ensuring that the -working components of ZMK are kept separate from your personal keyboard settings, reducing the amount of file manipulation in the configuration process. -This makes flashing ZMK to your keyboard much easier, especially because you don't need to keep an up-to-date copy of zmk on your computer at all times. - -By default, the `zmk-config` folder should contain two files: - -- `.conf` -- `.keymap` - -However, your config folder can also be modified to include a `boards/` directory for keymaps and configurations for multiple boards/shields -outside of the default keyboard setting definitions. - -## Configuration Changes - -The setup script creates a `config/.conf` file that allows you to add additional configuration options to -control what features and options are built into your firmware. Opening that file with your text editor will allow you to see the -various config settings that can be commented/uncommented to modify how your firmware is built. - -Refer to the [Configuration](/docs/config) documentation for more details on this file. - -## Keymap - -Once you have the basic user config completed, you can find the keymap file in `config/.keymap` and customize from there. -Refer to the [Keymaps](keymaps/index.mdx) documentation to learn more. - -## Publishing - -After making any changes you want, you should commit the changes and then push them to GitHub. That will trigger a new -GitHub Actions job to build your firmware which you can download once it completes. - -:::note -If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) will help you get these steps right. -::: - -:::note -It is also possible to build firmware locally on your computer by following the [toolchain setup](development/local-toolchain/setup/index.md) and -[building instructions](development/local-toolchain/build-flash.mdx), which includes pointers to -[building using your `zmk-config` folder](development/local-toolchain/build-flash.mdx#building-from-zmk-config-folder). -::: - -## Flashing Your Changes - -For normal keyboards, follow the same flashing instructions as before to flash your updated firmware. - -For [split keyboards](features/split-keyboards.md#building-and-flashing-firmware), only the central (left) side will need to be reflashed if you are just updating your keymap. -More troubleshooting information for split keyboards can be found [here](troubleshooting/connection-issues.mdx#split-keyboard-halves-unable-to-pair). - -## Building Additional Keyboards - -You can build additional keyboards with GitHub actions by appending them to `build.yml` in your `zmk-config` folder. For instance assume that we have set up a Corne shield with nice!nano during [initial setup](user-setup.mdx) and we want to add a Lily58 shield with nice!nano v2. The following is an example `build.yaml` file that would accomplish that: - -```yaml -include: - - board: nice_nano - shield: corne_left - - board: nice_nano - shield: corne_right - - board: nice_nano_v2 - shield: lily58_left - - board: nice_nano_v2 - shield: lily58_right -``` - -In addition to updating `build.yaml`, Lily58's shield files should also be added into the `config` sub-folder inside `zmk-config` together with your Corne files, e.g.: - -``` -corne.conf -corne.keymap -lily58.conf -lily58.keymap -``` diff --git a/docs/docs/development/hardware-integration/index.mdx b/docs/docs/development/hardware-integration/index.mdx index efde1081d15..681f5fc58af 100644 --- a/docs/docs/development/hardware-integration/index.mdx +++ b/docs/docs/development/hardware-integration/index.mdx @@ -41,7 +41,7 @@ The shield is usually the big PCB containing all the keys. ### Why not just "keyboard"? -["Composite" keyboards](../../hardware.mdx#composite) are keyboards which use a separate small PCB MCU module for its "brains". +["Composite" keyboards](../../getting-started/hardware.mdx#composite) are keyboards which use a separate small PCB MCU module for its "brains". In such keyboards, the [shield](#what-is-a-shield) is a brainless shell containing all the keys, RGB LEDs, encoders etc. It typically maps all of these features to a standard pin footprint, such as the Pro Micro pinout. @@ -52,7 +52,7 @@ But each board comes with its own features (MCU, flash, BLE, etc.) which must al Therefore in ZMK, board and shield are considered two different (but related) entities so that it is easier to mix and match them, and they are combined during a ZMK build. This provides the modularity to be able to use composite keyboards with different compatible controllers. -Note that ["self-contained" keyboards](../../hardware.mdx#onboard) only have a single PCB which includes the "brains" (MCU) onboard. +Note that ["self-contained" keyboards](../../getting-started/hardware.mdx#onboard) only have a single PCB which includes the "brains" (MCU) onboard. In ZMK, these have no shield, only a board. ## Organization Overview @@ -66,7 +66,7 @@ values={[ -For a [self-contained keyboard](../../hardware.mdx#onboard) that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition and no shield is defined. +For a [self-contained keyboard](../../getting-started/hardware.mdx#onboard) that includes the microprocessor, all of the above architecture components are included in the Zephyr _board_ definition and no shield is defined. You can see an example for the [Planck V6](https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm/planck) board directory. With this type of keyboard, the full ZMK definition for the keyboard exists in the `/boards//` directory where `` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/arm/planck/`. @@ -118,7 +118,7 @@ Also see the [new keyboard shield guide](new-shield.mdx#shield-overlays) for inf -Keyboards that require an add-on board to operate are [composite keyboards](../../hardware.mdx#composite), where the ZMK integration pieces are placed in the _shield_ definition for that keyboard. +Keyboards that require an add-on board to operate are [composite keyboards](../../getting-started/hardware.mdx#composite), where the ZMK integration pieces are placed in the _shield_ definition for that keyboard. This allows users to swap in different boards that use the same interconnect (e.g. Pro Micro RP2040, or nice!nano) and build a firmware the matches their actual combination of physical components. With this type of keyboard, the partial definition for the keyboard exists in the `/boards/shields/` directory where `` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/shields/clueboard_california/`. diff --git a/docs/docs/development/hardware-integration/new-shield.mdx b/docs/docs/development/hardware-integration/new-shield.mdx index 5f532ab8001..e50b5607ee6 100644 --- a/docs/docs/development/hardware-integration/new-shield.mdx +++ b/docs/docs/development/hardware-integration/new-shield.mdx @@ -100,7 +100,7 @@ mkdir boards/shields/ ## Base Kconfig Files :::tip[Example shields] -You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../../hardware.mdx) in order to copy and modify as a starting point. +You can check out the [`shields` folder](https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields) in the ZMK repo that houses [the in-tree supported shields](../../getting-started/hardware.mdx) in order to copy and modify as a starting point. ::: There are two required [Kconfig](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html) files that need to be created for your new keyboard shield to get it picked up for ZMK, `Kconfig.shield` and `Kconfig.defconfig`. @@ -549,7 +549,7 @@ If you wish to test that your keyboard works with [ZMK Studio](../../features/st ### GitHub Actions To use GitHub Actions to test, push the files defining the keyboard to GitHub. -Next, [update the `build.yaml`](../../customization.md#building-additional-keyboards) of your `zmk-config` to build your keyboard. +Next, [update the `build.yaml`](../../getting-started/customisation/index.md) of your `zmk-config` to build your keyboard. - If your shield is defined in your `zmk-config`, then the shield should start building. - If the shield is defined in a separate module, you will need to [adjust your `west.yml` to reference the module](https://zmk.dev/docs/features/modules#building-with-modules). diff --git a/docs/docs/development/local-toolchain/build-flash.mdx b/docs/docs/development/local-toolchain/build-flash.mdx index 982d00f4bd4..590dd938eb2 100644 --- a/docs/docs/development/local-toolchain/build-flash.mdx +++ b/docs/docs/development/local-toolchain/build-flash.mdx @@ -160,7 +160,7 @@ west build -b nice_nano_v2 -- -DSHIELD=vendor_shield -DZMK_EXTRA_MODULES="C:/Use ### Building from `zmk-config` Folder Instead of building .uf2 files using the default keymap and config files, you -can build using files from your [`zmk-config` folder](../../user-setup.mdx#github-repo) +can build using files from your [`zmk-config` folder](../../getting-started/user-setup.mdx#github-repo) by adding `-DZMK_CONFIG="C:/the/absolute/path/config"` to your `west build` command. **Notice that this path should point to the folder labeled `config` within your `zmk-config` folder.** diff --git a/docs/docs/development/usb-logging.mdx b/docs/docs/development/usb-logging.mdx index b7c3d233820..8d3878c7668 100644 --- a/docs/docs/development/usb-logging.mdx +++ b/docs/docs/development/usb-logging.mdx @@ -110,7 +110,7 @@ zephyr_udc0: &usbd { Previously, enabling logging required setting the `CONFIG_ZMK_USB_LOGGING` Kconfig symbol. If for whatever reason a custom board definition does not support the new `zmk-usb-logging` snippet, you can try setting this symbol at the keyboard level, typically in the `config/.conf` -file if you are using a [user config repository](user-setup.mdx). It can also be enabled at the ZMK level using the `app/prj.conf` file, or other +file if you are using a [user config repository](../getting-started/user-setup.mdx). It can also be enabled at the ZMK level using the `app/prj.conf` file, or other search locations described in the [configuration overview](config/index.md#config-file-locations). :::note diff --git a/docs/docs/features/modules.mdx b/docs/docs/features/modules.mdx index 5cc6e3d1c97..90c0ec52f87 100644 --- a/docs/docs/features/modules.mdx +++ b/docs/docs/features/modules.mdx @@ -25,7 +25,7 @@ The shift to using modules for keyboards is a relatively recent one, and not all ### GitHub Actions -When [using GitHub Actions to build ZMK](../user-setup.mdx), adding modules is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. The recommended way of doing so is: +When [using GitHub Actions to build ZMK](../getting-started/user-setup.mdx), adding modules is as simple as modifying the `west.yml` found in your `zmk-config`'s `config` directory. The recommended way of doing so is: 1. Find the URL base (the parent URL) for the module and add it as an entry to the [remotes](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#remotes). 2. Add the module as an entry to the [projects](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html#projects). @@ -141,7 +141,7 @@ branch and create the pull request. ### GitHub Actions -When [using GitHub Actions to build ZMK](../user-setup.mdx), once you have obtained the correct URL, you'll need to modify the `west.yml` file similarly to [Building With Modules](#building-with-modules). Add the remote for the branch like in said section. The difference is that you will need to change the selected remote and revision (or branch) for the `zmk` project. +When [using GitHub Actions to build ZMK](../getting-started/user-setup.mdx), once you have obtained the correct URL, you'll need to modify the `west.yml` file similarly to [Building With Modules](#building-with-modules). Add the remote for the branch like in said section. The difference is that you will need to change the selected remote and revision (or branch) for the `zmk` project. #### Example diff --git a/docs/docs/features/split-keyboards.md b/docs/docs/features/split-keyboards.md index ff9397f7dd4..a7b92ce3a7f 100644 --- a/docs/docs/features/split-keyboards.md +++ b/docs/docs/features/split-keyboards.md @@ -42,7 +42,7 @@ For the currently used BLE-based transport, split communication increases the av ## Building and Flashing Firmware ZMK split keyboards require building and flashing different firmware files for each split part. -For instance when [using the GitHub workflow](../user-setup.mdx) to build two part split keyboards, two firmware files that typically contain `_left` and `_right` in the file names will be produced. +For instance when [using the GitHub workflow](../getting-started/user-setup.mdx) to build two part split keyboards, two firmware files that typically contain `_left` and `_right` in the file names will be produced. These files need to be flashed to the respective controllers of the two halves. :::tip[Updating your keymap] diff --git a/docs/docs/getting-started/customisation/devicetree.md b/docs/docs/getting-started/customisation/devicetree.md new file mode 100644 index 00000000000..8078c9884ec --- /dev/null +++ b/docs/docs/getting-started/customisation/devicetree.md @@ -0,0 +1,235 @@ +--- +title: Devicetree +sidebar_label: Devicetree +--- + +ZMK makes heavy usage of a type of [tree data structure]() known as _devicetree_. +Devicetree is a _declarative_ way of describing almost everything about a Zephyr device, from the definition of keymaps and configuration of behaviors all the way to the internal storage partitions and architecture of the board's MCU. + +This page is an introduction to devicetree for ZMK users and designers. +For further reading, refer to the [devicetree spec](https://github.com/devicetree-org/devicetree-specification/releases) and [Zephyr's documentation](https://docs.zephyrproject.org/latest/build/dts/index.html#devicetree-guide). + +## Running Example + +The following segment taken from a keymap will be used as a running example: + +```dts +#include +#include + +/ { + behaviors { + spc_ul: space_underscore { + compatible = "zmk,behavior-mod-morph"; + #binding-cells = <0>; + bindings = <&kp SPACE>, <&kp UNDERSCORE>; + mods = <(MOD_LSFT|MOD_RSFT)>; + }; + }; + keymap { + compatible = "zmk,keymap"; + default_layer { + bindings = <&spc_ul &kp Z &kp M &kp K>; + }; + }; +}; +``` + +It may be helpful to open this page twice and leave one copy open at this example. +Note also that Devicetree uses C-style comments, i.e. `// ...` for line comments and `/* ... */` for block comments. + +## Structure + +A devicetree node has the general structure (parts within `[]` being optional) + +```dts +[label:] name { + [properties] + [child nodes] +}; +``` + +The root node of the devicetree always has the name `/`, i.e. is written as + +```dts + / { + [child nodes] + }; +``` + +It is also the _only_ node which has the `/` character as a name. See the devicetree spec for permitted characters for node names. + +After various preprocessing steps, all contents of the devicetree will be found within/under the root node. +If one node is found within another node, we say that the first node is a _child node_ of the second one. Similarly, one can also refer to a _grandchild node_, etc. + +In the running example, `behaviors` and `keymap` are child nodes of the root node. `space_underscore` and `default_layer` are child nodes of `behaviors` and `keymap` respectively, making them both grandchild nodes of the root node. + +### Properties + +What properties a node may have varies drastically. Of the standard properties, there are two which are of particularly relevant to users and designers: `compatible` and `status`. Additional standard properties may be found in the [devicetree spec](https://github.com/devicetree-org/devicetree-specification/releases). + +#### Compatible + +The most important property that a node has is generally the `compatible` property. This property is used to map code to nodes. There are some special cases, such as the node named `chosen`, where the node name is used rather than a `compatible` property. + +In the running example, `space_underscore` has the property `compatible = "zmk,behavior-mod-morph";`. The [ZMK's mod-morph behavior code](https://github.com/zmkfirmware/zmk/blob/main/app/src/behaviors/behavior_mod_morph.c#L7) acts on all nodes with `compatible` set to this value. The [ZMK keymap code](https://github.com/zmkfirmware/zmk/blob/main/app/src/keymap.c#L29) acts similarly for `compatible = "zmk,keymap";`. + +The `compatible` property is also used to identify what additional properties a node may have. Any properties which are not one of the standard properties must be listed in a "devicetree bindings" file. These files will sometimes also include some additional information on the usage of the node. + +ZMK keeps all of its devicetree bindings under the [`app/dts/bindings` directory](https://github.com/zmkfirmware/zmk/tree/main/app/dts/bindings). + +The bindings file for `compatible = "zmk,behavior-mod-morph";` is [`app/dts/bindings/behaviors/zmk,behavior-mod-morph.yaml`](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zmk%2Cbehavior-mod-morph.yaml). + +```dts title="zmk,behavior-mod-morph.yaml" +# Copyright (c) 2020 The ZMK Contributors +# SPDX-License-Identifier: MIT + +description: Mod Morph Behavior + +compatible: "zmk,behavior-mod-morph" + +include: zero_param.yaml + +properties: + bindings: + type: phandle-array + required: true + mods: + type: int + required: true + keep-mods: + type: int + required: false +``` + +The properties the node can have are listed under `properties`. Some additional properties are imported from [zero_param.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/behaviors/zero_param.yaml). Bindings files are **the authority** on node properties, with our [documentation of said properties](https://zmk.dev/docs/config/behaviors#devicetree-7) sometimes omitting things like the `#binding-cells` property (imported from the previously mentioned file, describing the number of parameters that the behavior accepts). A full description of the bindings file syntax can be found in [Zephyr's documentation](https://docs.zephyrproject.org/3.5.0/build/dts/bindings-syntax.html). + +Note that binding files can also specify properties for children, like the [`zmk,keymap.yaml` bindings file](https://github.com/zmkfirmware/zmk/blob/main/app/dts/bindings/zmk%2Ckeymap.yaml) specifying properties for layers in the keymap. + +#### Status + +The `status` property simply describes the status of a node. For ZMK users and designers, there are only two relevant values that this could be set to: + +- `status = "disabled";` The node is disabled. Code should not take effect or make use of the node, but it can still be referenced by other parts of the devicetree. +- `status = "okay";` The default setting when not explicitly stated. The node is treated as "active". This property is generally only explicitly stated when overwriting a `status = "disabled";`. + +How this property is used in practice will become more clear after the [devicetree preprocessing](#devicetree-preprocessing) section later on. + +### Labels and Phandles + +In addition to _names_, nodes can also have _labels_. For the ZMK user/designer, labels are arguably more important than node names. Whereas node names are used within code to access individual nodes, labels are used to reference other nodes from within devicetree itself. Such a reference is called a _phandle_, and can be thought of as similar to a pointer in C. + +In the running example, `spc_ul` is the label given to the node `space_underscore`. The `bindings` property of the `default_layer` node is a "phandle-array" - an array of references to other nodes[^1]. Its first element is `&spc_ul` - a phandle to the node with label `spc_ul`, i.e. `space_underscore`. `&kp` is another example of a phandle. It points to the node + +```dts +/ { + behaviors { + kp: key_press { + compatible = "zmk,behavior-key-press"; + #binding-cells = <1>; + display-name = "Key Press"; + }; + }; +}; +``` + +which is imported from a different file - imports will be discussed later on. The `&kp` phandles found in the running example also show the concept of _parameters_ being passed to phandles. In this case, `Z`, `M`, and `K` are passed as parameters. When ZMK needs to trigger a behavior found at a location in the keymap, it uses the phandle to identify the node which needs to be triggered. It then triggers the code corresponding to the `compatible` property of said node, passing in parameters while doing so. Depending on the behavior, another phandle may need to be triggered, in which case the same process is used to identify the node and thus lines of code which need to be triggered. + +Essentially, each layer in a keymap consists of an array of phandles pointing to various behaviors (alongside parameters) that were defined elsewhere. If you do not need to define the behavior node yourself, that just means ZMK has already defined it for you. + +[^1]: A phandle array by definition also includes metadata, i.e. parameters. Strictly speaking, a list of phandles without metadata has type `phandles` rather than `phandle-array`. A property with a single phandle has type `phandle`. + +## Devicetree Preprocessing + +Much of the complexity in `dts` files comes from preprocessing. To see the resulting devicetree after all preprocessing has finished, you can view the "Devicetree file" in the build log of your GitHub Action, or alternatively if building locally it can be found under `/zephyr/zephyr.dts`. For reasons that will make more sense later, your keymap and most of your customisations will be found near the bottom of the file. + +Preprocessing comes from two sources: + +1. The [C preprocessor](https://gcc.gnu.org/onlinedocs/cpp/) can be used within Devicetree Source (`dts`) files. +2. Devicetree has its own system for merging together, overwriting, and even deleting nodes and properties. + +### C Preprocessor + +An introduction to the C preprocessor is beyond the scope of this page. There are plenty of resources online for the unfamiliar reader to refer to. + +However, some specific methods of how the C preprocessor is used in ZMK's devicetree files can be useful, to better understand how everything fits together. + +The C preprocessor is used to import some nodes and other preprocessor definitions from other files. The lines + +```dts +#include +#include +``` + +which are found at the top of the running example import the default behavior node definitions for ZMK, along with a list of preprocessor definitions. The parameters `Z`, `M`, and `K` (passed to the `&kp` phandle in the running example) are actually C preprocessor defines. For example, during preprocessing references to `Z` get turned into the number `0x07001D`, which is the number that gets passed to the ZMK host device (e.g. your computer) for it to then re-interpret as the letter "z". + +The C preprocessor often gets leveraged by ZMK power users to reduce repetition in their keymap files. An example of this is the [macro-behavior convenience macro](../../keymaps/behaviors/macros.md#convenience-c-macro). ZMK designers will also come across the `RC` macro used for matrix transformations, and make use of convenience defines such as `GPIO_ACTIVE_HIGH`. + +### Devicetree Processing + +A devicetree is almost always constructed from multiple files. These files are generally speaking: + +- `.dtsi` files, which exist exclusively to be included via the C preprocessor (their contents get "pasted" at the location of the `#include` command). +- A `.dts` file, which forms the "base" of the devicetree. A single one of these is always present when a devicetree is constructed. For ZMK, the `.dts` file contains the sections of the devicetree describing the [_board_](../../development/hardware-integration/index.mdx#what-is-a-board). This includes importing a number of `.dtsi` files describing the specific SoC that the board uses. +- Any number of `.overlay` files. These files can come from various sources, such as [shields](../../development/hardware-integration/index.mdx#what-is-a-shield) or [snippets](index.md#snippets). An overlay is applied to a `.dts` file by appending its contents to the end of the `.dts` file, i.e. it is placed at the bottom of the file. Multiple overlays are applied by doing so repeatedly in a particular order. Without going into the details of the exact order in which overlays are applied, it is enough to know that if you specify e.g. `shield: corne_left nice_view_adapter nice_view` in your `build.yaml`, then the overlays are applied left to right. +- A single `.keymap` file. This file being included is ZMK-specific, and is treated as the "final" `.overlay` file, appended after all other overlays. + +In devicetree, parts written further down in the page have priority. + +#### Merging and overwriting nodes + +When a node appears multiple times in the devicetree (after the files are imported and merged together), it gets merged into a single node as a preprocessing step. For example: + +```dts +/ { + mn_ex: my_example_node { + property1 = <0>; + property2 = <2>; + }; +}; + +/ { + my_example_node { + property2 = <1>; + property3 = <4>; + }; + + example2 { + property; + }; +}; +``` + +The second appearance of `my_example_node` has priority, thus its `property2` value will overwrite the first appearance. The two root nodes also get merged in the process. The resulting tree after processing would be + +```dts +/ { + mn_ex: my_example_node { + property1 = <0>; + property2 = <1>; + property3 = <4>; + }; + + example2 { + property; + }; +}; +``` + +Labels do not get overwritten; a node can have multiple labels. Phandles can also be used to overwrite or add properties: + +```dts +&mn_ex { + property4 = <2>; +}; +``` + +The phandle approach is the recommended one, as one does not need to know the exact names of all the parent nodes with this approach. Crucially, when using phandles to overwrite or add properties, **the phandle must not be located within the root node**. It is instead placed outside of the tree entirely. + +#### Special devicetree directives + +Devicetree has some special directives that affect the tree. Relevant ones are: + +- Nodes can be deleted with the /delete-node/ directive: `/delete-node/ &node_label;` outside of the root node. +- Properties can be deleted with the /delete-property/ directive: `/delete-property/ node-property;` inside the relevant node. +- `/omit-if-no-ref/` causes a node to be omitted from the resulting devicetree if there are no references/phandles to the node: `/omit-if-no-ref/ &node_label;` diff --git a/docs/docs/getting-started/customisation/index.md b/docs/docs/getting-started/customisation/index.md new file mode 100644 index 00000000000..4b648877410 --- /dev/null +++ b/docs/docs/getting-started/customisation/index.md @@ -0,0 +1,136 @@ +--- +title: Customizing ZMK/zmk-config folders +sidebar_label: Customizing ZMK +--- + +After verifying you can successfully flash the default firmware, you will probably want to begin customizing your keymap and other keyboard options. +[In the initial setup tutorial](../user-setup.mdx), you created a Github repository called `zmk-config`. This repository is a discrete filesystem which works +with the main `zmk` firmware repository to build your desired firmware. + +By default, the `zmk-config` repo has the following structure: + +``` +zmk-config/ +|- .github/ +|- boards/ +|- config/ +|- zephyr/ +-- build.yaml +``` + +To customize ZMK, the [`build.yaml` file](#yaml-build-matrix) and the [`config` directory](#config-directory) are the main points of interest. + +After making any changes you want, commit the changes and then push them to GitHub. That will trigger a new +GitHub Actions job to build your firmware which you can download once it completes. Alternatively, using a [local toolchain](development/local-toolchain/setup/index.md) you could [build your firmware locally](development/local-toolchain/build-flash.mdx). + +Follow the same [flashing instructions](../user-setup.mdx#installing-the-firmware) as before to flash your updated firmware. + +:::note +If you need to, a review of [Learn The Basics Of Git In Under 10 Minutes](https://www.freecodecamp.org/news/learn-the-basics-of-git-in-under-10-minutes-da548267cc91/) will help you get these steps right. +::: + +## Config Directory + +``` +corne.conf +corne.keymap +lily58.conf +lily58.keymap +``` + +The purpose of the remaining directories is described below. + +- `.conf` +- `.keymap` + +However, your config folder can also be modified to include a `boards/` directory for keymaps and configurations for multiple boards/shields +outside of the default keyboard setting definitions. + +### Configuration Changes + +The setup script creates a `config/.conf` file that allows you to add additional configuration options to +control what features and options are built into your firmware. Opening that file with your text editor will allow you to see the +various config settings that can be commented/uncommented to modify how your firmware is built. + +Refer to the [Configuration](/docs/config) documentation for more details on this file. + +### Keymap + +Once you have the basic user config completed, you can find the keymap file in `config/.keymap` and customize from there. +Refer to the [Keymaps](keymaps/index.mdx) documentation to learn more. + +## YAML Build Matrix + +### Multiple Keyboards + +The `build.yaml` file is used by the GitHub Actions job to identify which keyboards should be built, and allows you to set some additional settings. +You can build multiple keyboards with GitHub actions by appending them to `build.yaml` like so: + +```yaml title="build.yaml" +include: + - board: nice_nano_v2 + shield: corne_left + - board: nice_nano_v2 + shield: corne_right + - board: bt60_v1 + - board: seeeduino_xiao_ble + shield: hummingbird +``` + +The above would cause the GitHub Actions job to build firmware for the left and right halves of a Corne keyboard (using nice!nano V2 controllers) along with a BT60 V1 Soldered keyboard and a Hummingbird keyboard (using a Seeed Studio XIAO nRF52840 controller). + +### Multiple Shields, One Board + +Multiple shields can be applied to the same board by listing them one after the other. For example: + +```yaml title="build.yaml" +include: + - board: nice_nano_v2 + shield: corne_left nice_view_adapter nice_view + # Other boards & shields +``` + +The above would build firmware for a Corne keyboard's left half with a nice!view installed. The `nice_view_adapter` shield is used as a "bridge", altering the `corne_left`'s configuration to enable the nice!view shield (for the default configuration). + +### Snippets + +Snippets are a combination of [Kconfig] settings and [devicetree] nodes that are generally independent of the choice of board and shield. In other words, they can be reused across a wide range of keyboards. ZMK provides the following snippets: + +- `zmk_usb_logging`, enabling [USB logging](../../development/usb-logging.mdx) +- `studio-rpc-usb-uart`, used to enable [ZMK Studio](../../features/studio.md) for live keymap customisation +- `nrf52833-nosd` and `nrf52840-nosd`, providing additional storage space for the corresponding MCUs at the cost of some [downsides](../../config/system.md#snippets). + +To build with a particular snippet, add it to the `snippet` field of a `board` entry: + +```yaml +include: + - board: nice_nano_v2 + shield: corne_left + snippet: zmk-usb-logging +``` + +### Artifact Name + +By default, the name given to a particular firmware file is `-.uf2`. The `artifact-name` field can be used to change this. Most commonly, this is used if you are building firmware for the same keyboard multiple times, with a snippet enabled or slightly modified settings. For example: + +```yaml +include: + - board: nice_nano_v2 + shield: corne_left + - board: nice_nano_v2 + shield: corne_left + snippet: zmk-usb-logging + artifact-name: nice_nano_v2_corne_left_usb_logging +``` + +### CMake Arguments + +## Other Directories + +### .github Directory + +### Boards Directory + +### Zephyr Directory + +This directory contains a single file, `module.yml`. This file causes your `zmk-config` to be a [Zephyr Module](../../features/modules.mdx), enabling the previously named [boards directory](#boards-directory). More advanced functionality exists; read through our page on [Module Creation](#artifact-name) for details. diff --git a/docs/docs/getting-started/customisation/kconfig.md b/docs/docs/getting-started/customisation/kconfig.md new file mode 100644 index 00000000000..17947b947e2 --- /dev/null +++ b/docs/docs/getting-started/customisation/kconfig.md @@ -0,0 +1,3 @@ +--- +title: Kconfig +--- diff --git a/docs/docs/faq.md b/docs/docs/getting-started/faq.md similarity index 100% rename from docs/docs/faq.md rename to docs/docs/getting-started/faq.md diff --git a/docs/docs/hardware.mdx b/docs/docs/getting-started/hardware.mdx similarity index 100% rename from docs/docs/hardware.mdx rename to docs/docs/getting-started/hardware.mdx diff --git a/docs/docs/intro.md b/docs/docs/getting-started/intro.md similarity index 100% rename from docs/docs/intro.md rename to docs/docs/getting-started/intro.md diff --git a/docs/docs/keymap-example.md b/docs/docs/getting-started/keymap-example.md similarity index 100% rename from docs/docs/keymap-example.md rename to docs/docs/getting-started/keymap-example.md diff --git a/docs/docs/user-setup-cli.mdx b/docs/docs/getting-started/user-setup-cli.mdx similarity index 99% rename from docs/docs/user-setup-cli.mdx rename to docs/docs/getting-started/user-setup-cli.mdx index d486d7635a6..88e8bc2b4f5 100644 --- a/docs/docs/user-setup-cli.mdx +++ b/docs/docs/getting-started/user-setup-cli.mdx @@ -161,7 +161,7 @@ Otherwise, leave this first prompt blank and press Enter, and it will Once you finish following all the instructions, you will have a copy of the repo stored on your computer. All `zmk` commands will run on this repo (unless the working directory is inside a different repo). If you ever forget where the repo is located, you can run `zmk cd` to find it. -Now that you have a repo created, see the instructions below for how ZMK CLI can automate some common tasks, or see [Customizing ZMK](customization.md) for more hands-on customization information. +Now that you have a repo created, see the instructions below for how ZMK CLI can automate some common tasks, or see [Customizing ZMK](customisation/index.md) for more hands-on customization information. ### Keyboard Management diff --git a/docs/docs/user-setup.mdx b/docs/docs/getting-started/user-setup.mdx similarity index 99% rename from docs/docs/user-setup.mdx rename to docs/docs/getting-started/user-setup.mdx index 9f0dd1ce773..57181e7b7ad 100644 --- a/docs/docs/user-setup.mdx +++ b/docs/docs/getting-started/user-setup.mdx @@ -188,12 +188,12 @@ push the initial commit. Once the setup script is complete and the new user config repository has been pushed, GitHub will automatically run the action to build your keyboard firmware files. You can view the actions by clicking on the "Actions" tab on your GitHub repository. -![](./assets/user-setup/github-actions-link.png) +![](../assets/user-setup/github-actions-link.png) Once you have loaded the Actions tab, select the top build from the list. Once you load it, the right side panel will include a link to download the `firmware` upload: -![](./assets/user-setup/firmware-archive.png) +![](../assets/user-setup/firmware-archive.png) Once downloaded, extract the zip and you can verify it should contain one or more `uf2` files, which will be copied to your keyboard. diff --git a/docs/docs/keymaps/index.mdx b/docs/docs/keymaps/index.mdx index bbef41acb8e..9d10912f053 100644 --- a/docs/docs/keymaps/index.mdx +++ b/docs/docs/keymaps/index.mdx @@ -3,7 +3,7 @@ title: Keymaps & Behaviors sidebar_label: Keymaps --- -import KeymapExample from "../keymap-example.md"; +import KeymapExample from "../getting-started/keymap-example.md"; ZMK uses a declarative approach to keymaps instead of using C code for all keymap configuration. Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for diff --git a/docs/docs/troubleshooting/connection-issues.mdx b/docs/docs/troubleshooting/connection-issues.mdx index 6689885a9fe..84f54d9c14c 100644 --- a/docs/docs/troubleshooting/connection-issues.mdx +++ b/docs/docs/troubleshooting/connection-issues.mdx @@ -25,7 +25,7 @@ This procedure will erase all settings, such as Bluetooth profiles, output selec ### Building a Reset Firmware -If you are using GitHub Actions to build your firmware as described in the [user setup](../user-setup.mdx), find the `build.yaml` file in your `zmk-config` folder and add an additional settings reset build for the board used by your split keyboard. For example, assuming that the config repo is setup for nice!nano v2 with Corne, append the `settings_reset` shield to the `build.yaml` file as follows: +If you are using GitHub Actions to build your firmware as described in the [user setup](../getting-started/user-setup.mdx), find the `build.yaml` file in your `zmk-config` folder and add an additional settings reset build for the board used by your split keyboard. For example, assuming that the config repo is setup for nice!nano v2 with Corne, append the `settings_reset` shield to the `build.yaml` file as follows: ```yml include: diff --git a/docs/sidebars.js b/docs/sidebars.js index 9eba3718a1c..46e955e59f6 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -5,14 +5,26 @@ module.exports = { label: "Getting Started", link: { type: "doc", - id: "intro", + id: "getting-started/intro", }, collapsed: false, items: [ - "hardware", - "faq", - "user-setup", - "customization", + "getting-started/hardware", + "getting-started/faq", + "getting-started/user-setup", + { + type: "category", + label: "Customisation", + link: { + type: "doc", + id: "getting-started/customisation/index", + }, + collapsed: true, + items: [ + "getting-started/customisation/devicetree", + "getting-started/customisation/kconfig", + ], + }, { type: "category", label: "Troubleshooting",