mirror of
https://github.com/zmkfirmware/zmk.git
synced 2026-03-20 04:55:20 -05:00
feat!: Move to zephyr v4.1 (#3060)
refactor: Move to Zephyr v4.1.0 Move to Zephyr v4.1.0, with various build/compilation fixes needed for basic use. refactor(tests): Move to native_sim for tests. feat(core): (Optionally) use Zephyr keyboard input devices Add ability to assign a keyboard `input` device to a physical layout, or use a chosen `zmk,matrix-input`. fix(pointing): Refactor for changes to input API Pass NULL user_data to input callbacks. fix(tests): Fix BLE test to account for Zephyr changes Handle additional read callback invocation once all matching characteristic have been read. fix(sensors): Initialize sensor data to 0 before fetching. Be sure we don't get back any uninitialized data by initializing the channel data to 0 before calling into the sensor API. refactor(input): Adjust split input to input API changes. Input callbacks now have a user_data parameter, adjust accordingly. chore(bluetooth): Minor cleanup of split BT code after refactor Small fixes and remove commented dead code left after the split refactor. refactor: Fix up BLE tests after Zephyr upgrade. Minor changes to snapshots based on newer Zephyr version. refactor(boards): Move to upstream xiao_ble board ID. Move to official upstream board definition for the Seeed XIAO BLE. refactor: Adjust metadata schema for HWMv2 board IDs w/ qualifiers Adjust our ZMK metadata to allow for board IDs that include qualifiers with slash delimeters. refactor!(boards): Move nice!nano to HWMv2, and proper revisioning Upgrade the nice!nano board to HWMv2, under the proper nicekeyboards vendor directory, and with proper revisions. Includes a breaking change to default the `2.0.0` version instead of the much older v1 (`1.0.0`). fix: Disable Nordic dt-bindings header checks. Disable the recently added Nordic dt-bindings header checks, which cause issues for our HID related headers. fix(studio): Correct `memset` usage. Use the correct memset call to clear our RPC memory. fix: Refactor for new Zephyr PM API Adjustments to our PM code to match Zephyr PM APIs. refactor(ble): Use correct BT opt for connectable. Adjust for upstream Zephyr BT API changes for advertising options. refactor(boards): Move MakerDiary M2 board to HWMv2. Run the HWMv2 script to convert the MakerDiary M2 board. fix(studio): Correct usage of thread analyzer API Fix up the RPC code that invoke the thread analyzer API to account for API changes. chore: Remove nanopb module override. Leverage nanopb version that's used by Zephyr. feat(core): mapper for magic bootloader values. To trigger bootloaders that use a magic value in RAM to trigger bootloader mode, add a mapping retained memory driver that maps write/read of boot mode values to a special magic value stored in the actually backing RAM. feat(behaviors): Add retention boot mode to reset. Support new generic Zephyr retention boot mode API in the reset behavior. feat: Add double tap to enter bootloader functionality Add ability to enter the bootloader if double tapping reset within the specified window. refactor(CI): Move to 4.1 container tags. Move to the new 4.1 tagged container, to ensure updated SDK, Python packages, etc. refactor(boards): Move nRFMicro to HWMv2 Refactor nRFMicro to HWMv2, using proper SoC, revisions, and variants (for flipped). Also move to devicetree setup of DCDC/HV DCDC. refactor(boards): Move QMK Proton-C to HWMv2 Move Proton-C to HWMv2 for use with Zephyr 4.1. chore(ci): Adjust core coverage for new board IDs. Use correct board IDs, with qualifiers, for our core coverage testing. refactor(boards): Move BDN9 to HWMv2 Move BDN9 to HWMv2, using the base `bdn9` ID, no longer including the `_rev2` suffix in the ID. refactor(boards): Move nice!60 to HWMv2 Migrate nice!60 to HWMv2. refactor: Adjust how we're searching/loading keymap files Use new post_boards_shields extension point for loading keymap files from board/shield directories. refactor(boards): Move planck rev6 to HWMv2. Move Planck board definition to HWMv2, including versioning tweaks. refactor(boards): Move OLKB Preonic to HWMv2 Move Preonic board definition to HWMv2 and remove `_rev3` variant suffix in favor of board versioning with `3.0.0` as the default. chore(deps): Pull in Zephyr optional group for nanopb. Ensure we enable nanopb by adding +optional group filter. fix(ci): Prevent slash characters in artifact names. Move to HWMv2 means board IDs often include slashes, so replace those with underscores when doing file uploads. fix(usb): Adjust Kconfig settings for USB. * Ensure USB isn't initialized automatically before we do, which can happen if USB CDC logging is used/enabled for a given board. * Adjust USB HID to initialize the USB class/interface before we enable the USB device itself. fix(display): Fix setting the small font for the mono theme. Adjust for modified mono theme init function to pass the small font. chore(ci): Fix changed board IDs for core coverage. Adjust board IDs for our core coverage after move to HWMv2 and board versioning consistently. * planck_rev6 -> planck * bdn9_rev2 -> bdn9 fix(underglow): Remove use of removed Kconfig WS2812 symbol refactor(boards): Move PW CKP boards to HWMv2 Migrate the bt60, bt65, and bt75 to HWMv2. refactor(boards): Move Puchi BLE to HWMv2 Migrate the Puchi BLE to HWMv2. refactor(boards): Migrate Ferris rev02 to HWMv2. Move Ferris rev02 to HMWv2, and remove the revision from the ID. refactor(boards): Move Pillbug to HWMv2 Migrate the MechWild PillBug board to HWMv2. refactor(boards): Migrate s40nc to HWMv2 Move the ShortyFortyNoCordy (s40nc) to HWMv2. refactor(boards): Move bluemicro840 board to HWMv2. Migrate bluemicro840 board to HWMv2, set up boot mode retention. fix(boards): Retore bootloader support on XIAO BLE. Set up necessary boot mode/retention to properly set GPREGRET to trigger Adafruit bootloader to run on the XIAO BLE. refactor(boards): Move Adv360 Pro to HWMv2. Migrate Adv360 Pro left/right to HWMv2. refactor(boards): Move Glove80 to HMWv2 Refactor the MoErgo Glove80 left/right to HWMv2. refactor(boards): Move Mikoto to HMWv2. Migrate Mikoto to HWMv2, with non-exact matching, tweaks to I2C selection to imply it for the 7.2.0 revision for the fuel gauge. refactor(boards): Move kbdfans Tofu65 2.0 to HMWv2 Move Tofu65 2.0 to HMWv2, with ID of just `tofu65`. refactor(boards): Remove dz60rgb board Remove dz60rgb, it's no longer readily available and we have other current stm32 reference designs for testing. refactor(boards): Move Corneish Zen to HMWv2 Move Corneish Zen to HMWv2, with IDs of `corneish_zen_left`/`corneish_zen_right`. refactor(boards): Migrate Corne-ish Zen status screen * refactor(boards): Add boot mode to the nice!nano using common dtsi * Add a new .dtsi for setting up nRF52 boot mode/retained memory settings * Adjust XIAO BLE to use the new include file * Add boot mode to to the nice!nano refactor(boards): Add boot mode support to nice!60 board Enable boot mode for nice!60 board. refactor(boards): Adjust Zephyr board metadata file locations Move the ZMK metadata files for upstream Zephyr boards to align with the HWMv2 directory structure that uses the vendor ID for the parent directory for a board directory. fix: Don't enable ZMK Display by default for a few shields By convention, avoid enabling ZMK Display by default on shields that may be built with under-resourced controllers (e.g. nRF52833 based ones). fix: Remove usage of renamed Kconfig from core coverage. Avoid using WS2812_LED_STRIP, since that Kconfig was renamed/split into SPI/GPIO/I2S symbols. refactor(boards): Adjust XIAO RP2040 override names, bootloader support Adjust the .conf/.overlay files to match the proper naming for the XIAO rp2040 board. Also add the necessary Kconfig/DTS bits for supporting bootloader using retained memory/boot mode retention. fix(display): Adjust stack sizes for display usage. Updated LVGL is bumping our stack size, so adjust the system work queue and dedicated display queue stack sizes as needed to account for this. feat(display): Add thread name to dedicated display queue. When thread names are enabled, pass a name to the dedicated display queue for better tracibility when using the thread analyzer. docs(blog): Add Zephyr upgrade post docs: Add bootloader integration page Add a dedicated page to outline steps to set up bootloader integration using the boot retention mechanism in newer Zephyr versions. fix(display): port nice!view display code * remove `lv_` prefix from old LVGL methods doc: Update local setup docs to use `west packages pip` Install Zephyr deps using the newer `west packages pip --install`. Signed-off-by: Peter Johanson <peter@peterjohanson.com> refactor(split): Adjust BT split code for newer Zephyr APIs. refactor(boards): Adjust upstream RP2040 boards for boot mode retention Add necessary DTS/Kconfig settings to upstream RP2040 boards so they can use the ZMK bootloader functionality using the boot mode retention infrastructure. docs: Update Zephyr docs links to 4.1.0 version. Update all links to the Zephyr docs to the 4.1.0 versions to match our Zephyr version in use. docs: Add a note about using CMake v3 for maximum compatibility. Some optional modules, like libmetal, which is used on nRF5340, specifically require CMake v3, so add a note in the native toolchain setup about this. feat(pointing): Handle INPUT_BTN_TOUCH codes for mouse buttons Translate INPUT_BTN_TOUCH input codes into button 0 press/release for HID layer. chore(pointing): Clean up some warning messages. Properly check return code from queue-ing messages, and fix up some type warnings in our logging calls. * Fix input event codes line numbers fix(studio): Properly serialize GATT RPC indications. fix(core): Set a system work queue stack size of 2048 by default We use a fair amount of stack even without BLE or RP2040, so default to 2048 by default everywhere, and constrained platforms can lowes this if they really need. refactor(core): Move away from deprecated DIS Kconfig symbols Use the correct Device Information Service Kconfig symbols for our model number and manufacturer. refactor: Move upstream Zephyr board overrides to extensions dirs Newer Zephyr supports "board extensions" to formally do what we've added in ourselves via some hacks, so move all our board overlay/config file overrides for upstream Zephyr boards into that correct structure. fix(boards): Add xiao_ble sd_partition label for nosd snippet compat Upstream xiao_ble uses different naming convention for the partition labels, so add an additional label for the SD range, so the existing nrf52840-nosd snippet will still work with the board. fix(core): Don't force CBPRINTF_NANO, for proper formatting. The nano CBPRINTF implementation lacks some padded formatting needed to ensure consistent formatting of BLE addresses, which we use to store keys as strings in a few places, so use the complete CBPRINTF by default now. fix(boards): Remove some references to old nice_nano_v2 board ID. The nice!nano board definition now properly uses versioning, so avoid referring to it with old `nice_nano_v2` board ID. fix(boards): Remove nano overlays for old nice_nano_v2 board ID. With board versioning in place, we can remove the unused `nice_nano_v2.overlay` files from shields. --------- Signed-off-by: Peter Johanson <peter@peterjohanson.com> Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com> Co-authored-by: Nicolas Munnich <munnich@lipn.univ-paris13.fr> Co-authored-by: snoyer <noyer.stephane@gmail.com>
This commit is contained in:
Pete Johanson
GitHub
455
docs/blog/2025-xx-xx-zephyr-4-1.md
Normal file
455
docs/blog/2025-xx-xx-zephyr-4-1.md
Normal file
@@ -0,0 +1,455 @@
|
||||
---
|
||||
title: "Zephyr 4.1 Update"
|
||||
authors: nmunnich
|
||||
tags: [firmware, zephyr, core]
|
||||
---
|
||||
|
||||
We're happy to announce that after a long wait, ZMK's `main` branch is now running [Zephyr 4.1](https://docs.zephyrproject.org/latest/releases/release-notes-4.1.html)!
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
Zephyr 4.1 is a large leap forward from our previous version of 3.5, featuring:
|
||||
|
||||
- Support for lots of new SoCs, boards, and shields, such as the WCH CH32V003, the Raspberry Pi Pico 2, and [many many more](https://docs.zephyrproject.org/4.1.0/boards/index.html#boards).
|
||||
- Hardware Model V2 (HWMv2), providing better support for SoCs which have multiple cores on the same chip, such as the nRF5340.
|
||||
- Lots of new drivers for chips such as the nPM1300.
|
||||
|
||||
This was a very large undertaking, and a big congratulations and thanks to [petejohanson] is due for all of his hard work in making this possible.
|
||||
|
||||
After we have verified functionality, ironed out any major bugs, and given any third party module maintainers time to update their code, we will be releasing ZMK `v0.4` as the first version to include this Zephyr version update.
|
||||
|
||||
**All** out-of-tree keyboards will need to be updated to use HWMv2. If you maintain such a keyboard, you can find instructions on doing so [below](#moving-to-hwmv2).
|
||||
|
||||
## Switching To the Previous Release
|
||||
|
||||
Some readers may be coming here because the above changes have _broken_ their builds. ZMK uses a formal release process that allows users to build against a specific release, instead of following the unstable/development version found in the `main` branch. However, since this is a relatively new process, many users may still be tracking `main`.
|
||||
|
||||
For all users, except those willing to accept periodic breaks they need to track down, we highly recommend [pinning your ZMK version](./2025-06-20-pinned-zmk.md). Doing so will allow you to avoid any issues related to the Zephyr upgrade, and allow you to choose when to upgrade to a future ZMK release when you are ready.
|
||||
|
||||
## Getting The Changes
|
||||
|
||||
Since the changes are merged to ZMK `main`, you'll need to be using that version of ZMK to use/tests these changes.
|
||||
|
||||
### Local Development
|
||||
|
||||
To get the update, first pull the latest ZMK `main`:
|
||||
|
||||
```
|
||||
git checkout main && git pull main
|
||||
```
|
||||
|
||||
Once you have the updated ZMK code, update the referenced modules:
|
||||
|
||||
```
|
||||
west update
|
||||
```
|
||||
|
||||
To be sure you've got all the updated Python packages needed to build ZMK, use west again:
|
||||
|
||||
```
|
||||
west packages pip --install
|
||||
```
|
||||
|
||||
### GitHub Actions Builds
|
||||
|
||||
To test these changes, you need to verify that the `west.yml` for your build is using a `revision: main` property. Once this is verified, simply run a new build and the updated Zephyr version will be used.
|
||||
|
||||
## Board Revisions
|
||||
|
||||
As part of this change, ZMK is now using board/shield revisions, rather than duplicate board/shield definitions. This means that instead of having e.g. `nice_nano`, and `nice_nano_v2`, we only have `nice_nano`, which by default points to the `2.0.0` revision. To point to the original Nice!Nano V1, you would need to use `nice_nano@1.0.0` where you would have previously used `nice_nano`. Of course, you could also put `nice_nano@2.0.0` if you wished to make that explicit, instead of merely replacing `nice_nano_v2` with `nice_nano`. Some boards, such as the `nrfmicro`, also have additional _board qualifiers_ such as the choice between multiple SoCs. Board qualifiers must always be specified, and do not have defaults. See [Zephyr's overview](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#board-terminology) for more information on board qualifiers. The below table provides an overview of some of the differences in in-tree boards we have in ZMK, and how they are selected in the new build system. The shorthand shows the minimum needed to build with a specific board, taking into account defaults.
|
||||
|
||||
- nice!nano (`nice_nano`)
|
||||
- `nice_nano` -> `nice_nano@1.0.0` (short: `nice_nano@1`)
|
||||
- `nice_nano_v2` -> `nice_nano@2.0.0` (short: `nice_nano`)
|
||||
- nRFMicro (`nrfmicro/nrf52840`)
|
||||
- `nrfmicro_11` -> `nrfmicro@1.1.0/nrf52840` (short: `nrfmicro@1.1/nrf52840`)
|
||||
- `nrfmicro_11_flipped` -> `nrfmicro@1.1.0/nrf52840/flipped` (short: `nrfmicro@1.1/nrf52840/flipped`)
|
||||
- `nrfmicro_13` -> `nrfmicro@1.3.0/nrf52840` (short: `nrfmicro/nrf52840`)
|
||||
- `nrfmicro_13_52833` -> `nrfmicro@1.3.0/nrf52833` (short: `nrfmicro/nrf52833`)
|
||||
- Mikoto (`mikoto`)
|
||||
- `mikoto` -> `mikoto@5.20.0` (short: `mikoto`)
|
||||
- `mikoto@6.1` -> `mikoto@6.1.0` (short: `mikoto@6`)
|
||||
- `mikoto@7.2` -> `mikoto@7.2.0` (short: `mikoto@7`)
|
||||
- XIAO RP2040 (`xiao_rp2040`)
|
||||
- `seeeduino_xiao_rp2040` -> `xiao_rp2040`
|
||||
- XIAO nRF52840/BLE (`xiao_ble`)
|
||||
- `seeeduino_xiao_ble` -> `xiao_ble`
|
||||
- BT60 (`bt60`)
|
||||
- `bt60_v1` -> `bt60@1.0.0`
|
||||
- `bt60_v2` -> `bt60@2.0.0`
|
||||
- `bt60_hs` -> `bt60_hs`
|
||||
- Planck (`planck`)
|
||||
- `planck_rev6` -> `planck`
|
||||
- BDN9 (`bdn9`)
|
||||
- `bdn9_rev2` -> `bdn9`
|
||||
- Ferris Rev2 (`ferris`)
|
||||
- `ferris_rev02` -> `ferris@2.0.0` (short: `ferris`)
|
||||
|
||||
The boards above are those which have changed in ZMK's tree, with the addition of the very popular XIAO series. For other boards in Zephyr's tree, please refer to the Zephyr documentation or source files directly.
|
||||
|
||||
## Getting The Changes
|
||||
|
||||
### User Config Repositories Using GitHub Actions
|
||||
|
||||
Existing user repositories which are currently running ZMK's `main` branch will receive the changes automatically when rebuilding.
|
||||
|
||||
Any user repositories created on or after `2025-07-03` are currently pinned to the most recent ZMK release. You will need to change over to `main` to get these changes immediately, or wait for `v0.4` and upgrade your version then.
|
||||
See the recent [blog post on pinning ZMK versions](./2025-06-20-pinned-zmk.md) for more information.
|
||||
|
||||
Likewise, if you are currently on `main` but do not wish to upgrade yet, please pin your ZMK version to `v0.3` by following the instructions in said blog post.
|
||||
|
||||
### VS Code & Docker (Dev Container)
|
||||
|
||||
If you build locally using VS Code & Docker then:
|
||||
|
||||
- Pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- Reload the project
|
||||
- If you are prompted to rebuild the remote container, click `Rebuild`
|
||||
- Otherwise, press `F1` and run `Remote Containers: Rebuild Container`
|
||||
- Once the container has rebuilt and reloaded, run `west update` to pull the updated Zephyr version and its dependencies.
|
||||
|
||||
Once the container has rebuilt, VS Code will be running the 4.1 Docker image.
|
||||
|
||||
### Local Host Development
|
||||
|
||||
The following steps will get you building ZMK locally against Zephyr 4.1:
|
||||
|
||||
- Run the updated [toolchain installation](/docs/development/local-toolchain/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
|
||||
- Install the latest version of `west` by running `pip3 install --user --update west`.
|
||||
- Pull the latest ZMK `main` with `git pull` for your ZMK checkout
|
||||
- Run `west update` to pull the updated Zephyr version and its dependencies
|
||||
|
||||
From there, you should be ready to build as normal!
|
||||
|
||||
## Moving To HWMv2
|
||||
|
||||
The move to HWMv2 has already been completed for all boards in ZMK's `main` branch. For out-of-tree boards, those need to be converted using either an automated script provided by the Zephyr project, or manually.
|
||||
|
||||
:::note
|
||||
|
||||
This _only_ applies to boards. Shields do not need any changes to account for the move to HWMv2.
|
||||
|
||||
:::
|
||||
|
||||
### Board Upgrade Script
|
||||
|
||||
The Zephyr project provides a script to automate updating a board to HWMv2. To run the script, you'll need to have a local [development setup](/docs/development/local-toolchain/setup/) ready to use. You'll need to ensure you've updated to the new ZMK version and run `west update` to ensure you've got the new Zephyr version with the script available.
|
||||
|
||||
:::note
|
||||
|
||||
The board upgrade script does _not_ work well with split designs. If upgrading a split keyboard board definition, you'll need to update it by hand.
|
||||
|
||||
:::
|
||||
|
||||
The following parameters are relevant for out-of-tree boards:
|
||||
|
||||
- `--board-root </the/path/to/the/module/` -- the full path to the module directory that contains a `boards/` directory, e.g. `/home/peter/git/my-zmk-module/`.
|
||||
- `-b <board_id>` -- The board ID to update, e.g. `tenbit`.
|
||||
- `-v <vendor_id>` -- The vendor for the board, this should be a vendor ID, or designer nickname.
|
||||
- `-g <group_id>` -- The name of the group directory under which to place the new board files. Typically this will match the vendor ID.
|
||||
- `-s <soc_id>` -- The SoC identifier, e.g. `nrf52840`, `rp2040`, `stm32f411xe`.
|
||||
|
||||
For example:
|
||||
|
||||
```sh
|
||||
$ python3 zmk/zephyr/scripts/utils/board_v1_to_v2.py \
|
||||
--board-root my-zmk-module -b my_board \
|
||||
-v my_company -g my_group -s nrf52840
|
||||
```
|
||||
|
||||
### Migrating an Out-Of-Tree Board Manually
|
||||
|
||||
The following steps can be completed manually if you encounter issues with the upgrade script, or don't have a local development setup available.
|
||||
|
||||
#### Vendor Directory
|
||||
|
||||
Boards no longer need to live in a parent directory named after the architecture of the board (.e.g `boards/arm`), and should instead be placed in a vendor/designer named directory (e.g. `boards/my_company`).
|
||||
|
||||
#### Write a `board.yml`
|
||||
|
||||
In your board's folder, next to other files such as `<your_board>.dts`, add a file called `board.yml`. This file should have the following structure:
|
||||
|
||||
```yml title="board.yml"
|
||||
board:
|
||||
name: <board-name>
|
||||
vendor: <board-vendor>
|
||||
revision:
|
||||
format: <major.minor.patch|letter|number|custom>
|
||||
default: <default-revision-value>
|
||||
exact: <true|false>
|
||||
revisions:
|
||||
- name: <revA>
|
||||
- name: <revB>
|
||||
...
|
||||
socs:
|
||||
- name: <soc-1>
|
||||
variants:
|
||||
- name: <variant-1>
|
||||
- name: <variant-2>
|
||||
variants:
|
||||
- name: <sub-variant-2-1>
|
||||
...
|
||||
- name: <soc-2>
|
||||
...
|
||||
```
|
||||
|
||||
In the above:
|
||||
|
||||
- `<board-name>` is the name of the board as specified when selecting a build target, such as `nice_nano`.
|
||||
- `<vendor-name>` is the name of the board's vendor, such as `nicekeyboards`. If you are an individual, rather than acting as an organization, please use your name/online id/similar (e.g. `zhiayang` in the case of the `mikoto`). This value should match the vendor directory name that the board definition folder is placed in the previous section.
|
||||
- `revision` defines any board revisions. See [Zephyr's overview](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#multiple-board-revisions) for more information on board revisions. If your board does not have any revisions, you can omit this section.
|
||||
- `socs` lists all SoCs that your board could have, e.g. `nrf52840` or `stm32f072xb`. If your board only has one SoC available and no variants, then the SoC can be omitted when selecting a build target, but must still be specified in this file. For an understanding of SoC variants, refer to the Zephyr documentation.
|
||||
|
||||
If you need to define multiple boards in the same `board.yml`, such as for a split keyboard, you can do so like this:
|
||||
|
||||
```yml
|
||||
boards:
|
||||
- name: <board_name_1>
|
||||
...
|
||||
- name: <board_name_2>
|
||||
...
|
||||
```
|
||||
|
||||
#### Revision adjustments
|
||||
|
||||
If, as a side effect of adding revisions, you renamed the board (e.g. `ferris_rev02` -> `ferris`), you should adjust the other places where the board name was previously -- `<board>.zmk.yml` and `<board>.yaml`. You may also need to rearrange/consolidate other Kconfig flags and devicetree nodes. See [the Zephyr documentation](https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html#multiple-board-revisions) for more details.
|
||||
|
||||
#### Adjust Kconfig files
|
||||
|
||||
##### `Kconfig.<board>`
|
||||
|
||||
Previously, your board folder will have had a file named `Kconfig.board`. This should be renamed to `Kconfig.<board>`, where `<board>` is the board name given in `board.yml`. The contents of this file will previously look something like this:
|
||||
|
||||
```title="Kconfig.board"
|
||||
config BOARD_FERRIS
|
||||
bool "Ferris rev 0.2"
|
||||
depends on SOC_STM32F072XB
|
||||
```
|
||||
|
||||
Remove the `bool` and change the `depends on` to a `select`:
|
||||
|
||||
```title="Kconfig.ferris"
|
||||
config BOARD_FERRIS
|
||||
select SOC_STM32F072XB
|
||||
```
|
||||
|
||||
If you had multiple boards specified for different SoCs, you should consolidate them to one:
|
||||
|
||||
```title="Kconfig.nrfmicro"
|
||||
config BOARD_NRFMICRO
|
||||
select SOC_NRF52840_QIAA if BOARD_NRFMICRO_NRF52840
|
||||
select SOC_NRF52840_QIAA if BOARD_NRFMICRO_NRF52840_FLIPPED
|
||||
select SOC_NRF52833_QIAA if BOARD_NRFMICRO_NRF52833
|
||||
```
|
||||
|
||||
##### `<board>_defconfig`
|
||||
|
||||
Previously, this file was used to select the board and SOC with Kconfig flags. All such selections should be removed from this file. For example, all of the below flags should be removed:
|
||||
|
||||
```
|
||||
CONFIG_SOC_SERIES_NRF52X=y
|
||||
CONFIG_SOC_NRF52833_QIAA=y
|
||||
CONFIG_SOC_NRF52840_QIAA=y
|
||||
CONFIG_BOARD_<BOARDNAME>=y
|
||||
CONFIG_SOC_SERIES_STM32F0X=y
|
||||
CONFIG_SOC_STM32F072XB=y
|
||||
```
|
||||
|
||||
#### DeviceTree changes
|
||||
|
||||
For most boards, aside from rearranging due to moving to revisions, there should be no changes necessary to the devicetree nodes. However, if your board makes use of upstream Zephyr drivers, these may have been renamed (e.g. Ferris' `microchip,mcp230xx` has been changed to `microchip,mcp23017`).
|
||||
|
||||
## General Board/Shield Changes
|
||||
|
||||
A few other changes, unrelated to the HWMv2 move, may impact out-of-tree boards/shields:
|
||||
|
||||
### Bootloader Setup
|
||||
|
||||
With the version bump, the previous method to enable `&bootloader` has been disabled. Instead, ZMK is introducing _boot retention_, which as a side effect also enables `&bootloader` for SoCs which previously didn't work with said behavior, such as the STM32F072. To set up boot retention for your board, please read through [the dedicated page](/docs/development/hardware-integration/bootloader).
|
||||
|
||||
### nRF52840 NFC Pins as GPIO
|
||||
|
||||
If your board or shield is using either of the nRF52840 NFC pins, as is often done with the XIAO nRF52840, you'll need to perform an additional update.
|
||||
|
||||
#### Remove deprecated Kconfig symbol
|
||||
|
||||
Previously, using those pins required enabling `CONFIG_NFCT_PINS_AS_GPIOS=y` in some Kconfig file. That Kconfig symbol has been removed, so remove any use of that Kconfig symbol from your board/shield.
|
||||
|
||||
#### Set up NFC GPIO devicetree
|
||||
|
||||
The following should be added to the board or shield's devicetree, e.g. in `<board>.dtsi` or in a board specific shield overlay file like `<my_shield>/boards/xiao_ble.overlay`:
|
||||
|
||||
```dts
|
||||
&uicr {
|
||||
nfct-pins-as-gpios;
|
||||
};
|
||||
```
|
||||
|
||||
### nRF52840 DC/DC Modes
|
||||
|
||||
For boards with the necessary additional hardware to enable DC/DC modes for the reg0 and/or reg1 power stages, the configuration to enable DC/DC has also moved out of Kconfig and into devicetree.
|
||||
|
||||
#### Remove Kconfig Settings
|
||||
|
||||
Usually, the DC/DC modes were enabled in the board's `Kconfig.defconfig` file, looking like:
|
||||
|
||||
```Kconfig
|
||||
config BOARD_ENABLE_DCDC
|
||||
bool "Enable DCDC mode"
|
||||
select SOC_DCDC_NRF52X
|
||||
default y
|
||||
depends on (BOARD_MY_BOARD)
|
||||
|
||||
config BOARD_ENABLE_DCDC_HV
|
||||
bool "High voltage DCDC converter"
|
||||
select SOC_DCDC_NRF52X_HV
|
||||
default n
|
||||
depends on (BOARD_MY_BOARD)
|
||||
```
|
||||
|
||||
Remove the lines from the file that look like above, or remove the `Kconfig.defconfig` file entirely if that is the only content contained therein.
|
||||
|
||||
#### Add DC/DC setup to devicetree
|
||||
|
||||
The DC/DC mode is now enabled for the `®0` and `®1` devicetree nodes, depending on which stage you want to use in that mode.
|
||||
|
||||
For a high voltage board, where the necessary inductor is connected to the `DCCH` pin, enable the following in the board's `.dts` file:
|
||||
|
||||
```dts
|
||||
®0 {
|
||||
status = "okay";
|
||||
};
|
||||
```
|
||||
|
||||
For both high voltage and non-HV boards, where the necessary inductor is connected to the `DCC` pin, enable the following in the board's `.dts` file:
|
||||
|
||||
```dts
|
||||
®1 {
|
||||
regulator-initial-mode = <NRF5X_REG_MODE_DCDC>;
|
||||
};
|
||||
```
|
||||
|
||||
### RP2040 Board Adjustments
|
||||
|
||||
A few small tweaks are required for custom/out-of-tree RP2040 based boards:
|
||||
|
||||
#### Clock control
|
||||
|
||||
RP2040 boards now require clock control enabled to use several peripherals, including USB.
|
||||
|
||||
The following should be added to the board's `<board>_defconfig` file:
|
||||
|
||||
```dts
|
||||
CONFIG_CLOCK_CONTROL=y
|
||||
```
|
||||
|
||||
#### Base devicetree changes
|
||||
|
||||
The location for the base set of devicetree these boards need to include has changed. In the board's `<board>.dts` file, replace:
|
||||
|
||||
```dts
|
||||
#include <rpi_pico/rp2040.dtsi>
|
||||
```
|
||||
|
||||
with
|
||||
|
||||
```dts
|
||||
#include <raspberrypi/rpi_pico/rp2040.dtsi>
|
||||
```
|
||||
|
||||
Next, any fixed clock node needs to be removed:
|
||||
|
||||
```dts
|
||||
xtal_clk: xtal-clk {
|
||||
compatible = "fixed-clock";
|
||||
clock-frequency = <12000000>;
|
||||
#clock-cells = <0>;
|
||||
};
|
||||
```
|
||||
|
||||
And the following added, to set up the core device hardware properly:
|
||||
|
||||
```dts
|
||||
&timer {
|
||||
status = "okay";
|
||||
};
|
||||
|
||||
&rtc {
|
||||
clocks = <&clocks RPI_PICO_CLKID_CLK_RTC>;
|
||||
status = "okay";
|
||||
};
|
||||
|
||||
&vreg {
|
||||
regulator-always-on;
|
||||
regulator-allowed-modes = <REGULATOR_RPI_PICO_MODE_NORMAL>;
|
||||
};
|
||||
```
|
||||
|
||||
Lastly, an additional property must be added to the `chosen` node to supplement the existing properties there:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
chosen {
|
||||
...
|
||||
zephyr,flash-controller = &ssi;
|
||||
...
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### LED Strip Kconfig Changes
|
||||
|
||||
If your board or shield uses RGB underglow, the following Kconfig flag which was previously enabled should now be removed:
|
||||
|
||||
```
|
||||
CONFIG_WS2812_STRIP=y
|
||||
```
|
||||
|
||||
If this is the only SPI device your shield uses, also remove the Kconfig flag enabling SPI (assuming it is present). It will be automatically enabled.
|
||||
|
||||
### Cirque Pinnacle Input Driver
|
||||
|
||||
Upstream Zephyr now contains a driver for the popular small Cirque Pinnacle trackpads. To transition to the new upstream driver, instead of the [out-of-tree module](https://github.com/petejohanson/cirque-input-module), some small adjustments are needed.
|
||||
|
||||
#### Remove module references
|
||||
|
||||
Often, the out-of-tree module is referenced from the `west.yml` in user's repos. The entry pointing to the module should be removed from your `projects` list there. If building locally, be sure you are not adding the module directory to the `ZMK_EXTRA_MODULES` CMake parameter.
|
||||
|
||||
#### Devicetree changes
|
||||
|
||||
The properties for the upstream driver can be found [here](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/input/cirque%2Cpinnacle-i2c.html#dtbinding-cirque-pinnacle-i2c). The following changes are required when migrating:
|
||||
|
||||
- The `dr-gpios` property in out-of-tree module is named `data-ready-gpios`, so renaming the property is required.
|
||||
- Instead of an opt-out `no-taps` property to disable taps, you can enable primary taps with `primary-tap-enable`.
|
||||
- The `sleep` property is now named `sleep-mode-enable`.
|
||||
- Use `invert-x`/`invert-y` instead of `x-invert`/`y-invert`.
|
||||
- Use `swap-xy` instead of `rotate-90`.
|
||||
|
||||
## Other Changes
|
||||
|
||||
LVGL was updated to 9.3.0, which comes with breaking API changes. If you are using custom widgets or displays from a module, these will likely need fixing. See the [LVGL changelog](https://docs.lvgl.io/master/CHANGELOG.html#v9-3-0-3-june-2025) for details.
|
||||
|
||||
## Board Extensions
|
||||
|
||||
Zephyr has formalized the concept of "board extensions", allowing modules/applications to extend boards that are defined elsewhere. If using a board from the upstream Zephyr project that ZMK hasn't yet extended with default settings, e.g. enabling the `CONFIG_ZMK_USB` symbol, users can add their own extensions to their modules under the `<board_root>/boards/extensions/<board_dir_name>/` directory. See https://github.com/zmkfirmware/zmk/tree/main/app/boards/extensions for the extensions that ZMK has added.
|
||||
|
||||
## Zephyr Upgrade Instructions
|
||||
|
||||
Should you encounter any other issues with custom or out-of-tree Zephyr code, consider consulting the following Zephyr upgrade guides:
|
||||
|
||||
- [3.7 Upgrade](https://docs.zephyrproject.org/4.1.0/releases/migration-guide-3.7.html)
|
||||
- [4.1 Upgrade](https://docs.zephyrproject.org/4.1.0/releases/migration-guide-4.1.html)
|
||||
|
||||
## Thanks!
|
||||
|
||||
Thanks to all the testers who have helped verify ZMK functionality on the newer Zephyr version.
|
||||
|
||||
## Future
|
||||
|
||||
Once a ZMK version based on Zephyr 4.1 is released, we'll be working towards updating Zephyr even further, to try to catch up with the latest actual Zephyr release. This will likely mean a jump to the upcoming Zephyr 4.3. As part of that work, some other semi-disruptive changes will be required, including:
|
||||
|
||||
- Removing ZMK's use of the deprecated, and now removed, `kscan` APIs in favor of the newer matrix input API. ZMK already supports the matrix input API, but has not yet converted our existing drivers to that API. Advanced users looking to test can try leveraging the upstream Zephyr drivers today to test that functionality, but that is _not_ officially supported and is likely to have bugs or untested side effects.
|
||||
- Move the new USB stack, that includes better High-Speed USB support.
|
||||
|
||||
[nmunnich]: https://github.com/nmunnich
|
||||
[petejohanson]: https://github.com/petejohanson
|
||||
@@ -41,7 +41,7 @@ Host support for multiple battery levels is undefined. It appears that in most o
|
||||
|
||||
### Devicetree
|
||||
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
|
||||
|
||||
| Property | Type | Description |
|
||||
| ------------- | ---- | --------------------------------------------- |
|
||||
@@ -55,7 +55,7 @@ Driver for reading the voltage of a battery using an ADC connected to a voltage
|
||||
|
||||
Applies to: `compatible = "zmk,battery-voltage-divider"`
|
||||
|
||||
See [Zephyr's voltage divider documentation](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/iio/afe/voltage-divider.html).
|
||||
See [Zephyr's voltage divider documentation](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/iio/afe/voltage-divider.html).
|
||||
|
||||
## nRF VDDH Battery Sensor
|
||||
|
||||
|
||||
@@ -403,8 +403,8 @@ Applies to: `compatible = "zmk,behavior-input-two-axis"`
|
||||
| Property | Type | Description | Default |
|
||||
| ----------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| `#binding-cells` | int | Must be `<1>` | |
|
||||
| `x-input-code` | int | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245) for generated input events for the X-axis. | |
|
||||
| `y-input-code` | int | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245) for generated input events for the Y-axis. | |
|
||||
| `x-input-code` | int | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L258) for generated input events for the X-axis. | |
|
||||
| `y-input-code` | int | The [relative event code](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L258) for generated input events for the Y-axis. | |
|
||||
| `trigger-period-ms` | int | How many milliseconds between generated input events based on the current speed/direction. | 16 |
|
||||
| `delay-ms` | int | How many milliseconds to delay any processing or event generation when first pressed. | 0 |
|
||||
| `time-to-max-speed-ms` | int | How many milliseconds it takes to accelerate to the curren max speed. | 0 |
|
||||
|
||||
@@ -53,21 +53,21 @@ You must also configure the driver for your display. ZMK provides the following
|
||||
|
||||
- [IL0323](https://github.com/zmkfirmware/zmk/blob/main/app/module/drivers/display/Kconfig.il0323)
|
||||
|
||||
Zephyr provides several display drivers as well. Search for the name of your display in [Zephyr's Kconfig options](https://docs.zephyrproject.org/3.5.0/kconfig.html) documentation.
|
||||
Zephyr provides several display drivers as well. Search for the name of your display in [Zephyr's Kconfig options](https://docs.zephyrproject.org/4.1.0/kconfig.html) documentation.
|
||||
|
||||
## Devicetree
|
||||
|
||||
See the Devicetree bindings for your display. Here are the bindings for common displays:
|
||||
|
||||
- [IL0323](https://github.com/zmkfirmware/zmk/blob/main/app/module/dts/bindings/display/gooddisplay%2Cil0323.yaml)
|
||||
- [SSD1306 (i2c)](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/display/solomon,ssd1306fb-i2c.html)
|
||||
- [SSD1306 (spi)](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/display/solomon,ssd1306fb-spi.html)
|
||||
- [SSD1306 (i2c)](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/display/solomon,ssd1306fb-i2c.html)
|
||||
- [SSD1306 (spi)](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/display/solomon,ssd1306fb-spi.html)
|
||||
|
||||
A full list of drivers provided by Zephyr can be found in [Zephyr's Devicetree bindings index](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings.html).
|
||||
A full list of drivers provided by Zephyr can be found in [Zephyr's Devicetree bindings index](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings.html).
|
||||
|
||||
### Chosen nodes
|
||||
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
|
||||
|
||||
| Property | Type | Description |
|
||||
| ----------------- | ---- | -------------------------------------------------------------------------------------------------------- |
|
||||
|
||||
@@ -37,14 +37,14 @@ ZMK will search for config files in:
|
||||
|
||||
...where `<board>` is the name of the board and `<module>` is the root directory of any [included module](../features/modules.mdx). These files describe the hardware of the board.
|
||||
|
||||
ZMK will search the board folder for the following config files _in addition_ to [Zephyr board-defining files](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html#create-your-board-directory):
|
||||
ZMK will search the board folder for the following config files _in addition_ to [Zephyr board-defining files](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#create-your-board-directory):
|
||||
|
||||
- `<board>.conf` (Kconfig)
|
||||
- `<board>.keymap` (Devicetree, keyboards with onboard controllers only)
|
||||
|
||||
Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in board folders.
|
||||
|
||||
For more documentation on creating and configuring a new board, see [Zephyr's board porting guide](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html#write-kconfig-files).
|
||||
For more documentation on creating and configuring a new board, see [Zephyr's board porting guide](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#write-kconfig-files).
|
||||
|
||||
### Shield Folder
|
||||
|
||||
@@ -57,14 +57,14 @@ When building with a shield, ZMK will search for config files in:
|
||||
|
||||
...where `<shield>` is the name of the shield and `<module>` is the root directory of any [included module](../features/modules.mdx). These files describe the hardware of the shield that the board is plugged into.
|
||||
|
||||
ZMK will search the shield folder for the following config files _in addition_ to [Zephyr shield-defining files](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#shield-porting-and-configuration):
|
||||
ZMK will search the shield folder for the following config files _in addition_ to [Zephyr shield-defining files](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html#shield-porting-and-configuration):
|
||||
|
||||
- `<shield>.conf` (Kconfig)
|
||||
- `<shield>.keymap` (Devicetree)
|
||||
|
||||
Shared config files (excluding any `_left` or `_right` suffix) are not currently supported in shield folders.
|
||||
|
||||
For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/hardware-integration/new-shield.mdx) guide.
|
||||
For more documentation on creating and configuring a new shield, see [Zephyr's shield documentation](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html) and [ZMK's new keyboard shield](../development/hardware-integration/new-shield.mdx) guide.
|
||||
|
||||
## Kconfig Files
|
||||
|
||||
@@ -82,7 +82,7 @@ Files ending with `_defconfig` use the same syntax as `.conf` files. They set th
|
||||
|
||||
The list of available settings is determined by various files in ZMK whose names start with `Kconfig`. Note that options are _not_ prefixed with `CONFIG_` in these files.
|
||||
|
||||
See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html) for more details on Kconfig files.
|
||||
See [Zephyr's Kconfig documentation](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html) for more details on Kconfig files.
|
||||
|
||||
:::tip
|
||||
|
||||
@@ -139,7 +139,7 @@ Devicetree files look like this:
|
||||
|
||||
Devicetree properties apply to specific nodes in the tree instead of globally. The properties that can be set for each node are determined by `.yaml` files in ZMK in the various `dts/bindings` folders.
|
||||
|
||||
See [Zephyr's Devicetree guide](https://docs.zephyrproject.org/3.5.0/build/dts/index.html) for more details on Devicetree files.
|
||||
See [Zephyr's Devicetree guide](https://docs.zephyrproject.org/4.1.0/build/dts/index.html) for more details on Devicetree files.
|
||||
|
||||
:::tip
|
||||
|
||||
@@ -166,7 +166,7 @@ The part before the colon, `kscan0`, is a label. This is optional, and it provid
|
||||
The `compatible` property indicates what type of node it is. Search this documentation for the text inside the quotes to see which properties the node
|
||||
supports. You can also search ZMK for a file whose name is the value of the `compatible` property with a `.yaml` file extension.
|
||||
|
||||
To set a property, see below for examples for common property types, or see [Zephyr's Devicetree documentation](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#writing-property-values) for more details on the syntax for properties.
|
||||
To set a property, see below for examples for common property types, or see [Zephyr's Devicetree documentation](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#writing-property-values) for more details on the syntax for properties.
|
||||
|
||||
To change a property for an existing node, first find the node you want to change and find its label. Next, outside of any other node, write an ampersand (`&`)
|
||||
followed by the node's label, an opening curly brace (`{`), one or more new property values, a closing curly brace (`}`), and a semicolon (`;`).
|
||||
|
||||
@@ -25,7 +25,7 @@ If the debounce press/release values are set to any value other than `-1`, they
|
||||
|
||||
### Devicetree
|
||||
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
|
||||
|
||||
| Property | Type | Description |
|
||||
| ---------------------- | ---- | ---------------------------------------------------------------------- |
|
||||
@@ -81,7 +81,7 @@ Definition file: [zmk/app/module/dts/bindings/kscan/zmk,kscan-gpio-direct.yaml](
|
||||
| `toggle-mode` | bool | Use toggle switch mode | n |
|
||||
| `wakeup-source` | bool | Mark this kscan instance as able to wake the keyboard | n |
|
||||
|
||||
Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`:
|
||||
Assuming the switches connect each GPIO pin to the ground, the [GPIO flags](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/gpio.html#api-reference) for the elements in `input-gpios` should be `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)`:
|
||||
|
||||
```dts
|
||||
kscan0: kscan {
|
||||
@@ -151,7 +151,7 @@ The `diode-direction` property must be one of:
|
||||
| `"row2col"` | Diodes point from rows to columns (cathodes are connected to columns) |
|
||||
| `"col2row"` | Diodes point from columns to rows (cathodes are connected to rows) |
|
||||
|
||||
Given the `diode-direction`, the [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `row-` and `col-gpios` should be set appropriately.
|
||||
Given the `diode-direction`, the [GPIO flags](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/gpio.html#api-reference) for the elements in `row-` and `col-gpios` should be set appropriately.
|
||||
The output pins (e.g. columns for `col2row`) should have the flag `GPIO_ACTIVE_HIGH`, and input pins (e.g. rows for `col2row`) should have the flags `(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)`:
|
||||
|
||||
```dts
|
||||
@@ -204,7 +204,7 @@ Define the transform with a [matrix transform](layout.md#matrix-transform). The
|
||||
For example, in `RC(5,0)` power flows from the 6th pin in `gpios` to the 1st pin in `gpios`.
|
||||
Exclude all positions where the row and column are the same as these pairs will never be triggered, since no pin can be both input and output at the same time.
|
||||
|
||||
The [GPIO flags](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html#api-reference) for the elements in `gpios` should be `GPIO_ACTIVE_HIGH`, and interrupt pins set in `interrupt-gpios` should have the flags `(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)`.
|
||||
The [GPIO flags](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/gpio.html#api-reference) for the elements in `gpios` should be `GPIO_ACTIVE_HIGH`, and interrupt pins set in `interrupt-gpios` should have the flags `(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)`.
|
||||
|
||||
## Composite Driver
|
||||
|
||||
|
||||
@@ -79,7 +79,7 @@ The `*_START` settings only determine the initial backlight state. Any changes y
|
||||
|
||||
### Devicetree
|
||||
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
|
||||
Applies to: [`/chosen` node](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes)
|
||||
|
||||
| Property | Type | Description |
|
||||
| --------------- | ---- | -------------------------------------------- |
|
||||
@@ -87,7 +87,7 @@ Applies to: [`/chosen` node](https://docs.zephyrproject.org/3.5.0/build/dts/intr
|
||||
|
||||
See the Zephyr devicetree bindings for LED drivers:
|
||||
|
||||
- [gpio-leds](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/led/gpio-leds.html)
|
||||
- [pwm-leds](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/led/pwm-leds.html)
|
||||
- [gpio-leds](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/led/gpio-leds.html)
|
||||
- [pwm-leds](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/led/pwm-leds.html)
|
||||
|
||||
See the [backlight hardware integration page](../development/hardware-integration/lighting/backlight.mdx) for examples of the properties that must be set to enable backlighting.
|
||||
|
||||
@@ -3,7 +3,7 @@ title: Persistent Settings
|
||||
sidebar_label: Settings
|
||||
---
|
||||
|
||||
ZMK uses [Zephyr's settings subsystem](https://docs.zephyrproject.org/3.5.0/services/settings/index.html) to store certain runtime settings in the "storage" partition of the controller's flash memory.
|
||||
ZMK uses [Zephyr's settings subsystem](https://docs.zephyrproject.org/4.1.0/services/settings/index.html) to store certain runtime settings in the "storage" partition of the controller's flash memory.
|
||||
These settings will be saved after certain events and loaded on boot.
|
||||
For instance, bond information for [paired Bluetooth hosts](../features/bluetooth.md) are stored in this partition so that users do not need to pair to each device again after the controller loses power.
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Definition file: [zmk/app/Kconfig](https://github.com/zmkfirmware/zmk/blob/main/
|
||||
|
||||
:::info
|
||||
|
||||
Because ZMK enables [the Zephyr setting](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_DEVICE_NAME_DYNAMIC) that allows for runtime modification of the device BT name,
|
||||
Because ZMK enables [the Zephyr setting](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_BT_DEVICE_NAME_DYNAMIC) that allows for runtime modification of the device BT name,
|
||||
changing `CONFIG_ZMK_KEYBOARD_NAME` requires [clearing the stored settings](./settings.md#clearing-persisted-settings) on the controller in order to take effect.
|
||||
|
||||
:::
|
||||
@@ -93,7 +93,7 @@ By default USB Boot protocol support is disabled, however certain situations suc
|
||||
|
||||
### Bluetooth
|
||||
|
||||
See [Zephyr's Bluetooth stack architecture documentation](https://docs.zephyrproject.org/3.5.0/connectivity/bluetooth/bluetooth-arch.html)
|
||||
See [Zephyr's Bluetooth stack architecture documentation](https://docs.zephyrproject.org/4.1.0/connectivity/bluetooth/bluetooth-arch.html)
|
||||
for more information on configuring Bluetooth.
|
||||
|
||||
| Config | Type | Description | Default |
|
||||
@@ -120,6 +120,13 @@ Note that `CONFIG_BT_MAX_CONN` and `CONFIG_BT_MAX_PAIRED` should be set to the s
|
||||
| `CONFIG_ZMK_USB_LOGGING` | bool | Enable USB CDC ACM logging for debugging | n |
|
||||
| `CONFIG_ZMK_LOG_LEVEL` | int | Log level for ZMK debug messages | 4 |
|
||||
|
||||
### Double Tap To Bootloader
|
||||
|
||||
| Config | Type | Description | Default |
|
||||
| ------------------------------------------ | ---- | ------------------------------------------------------------------- | --------------------------- |
|
||||
| `CONFIG_ZMK_DBL_TAP_BOOTLOADER` | bool | Enable the double-tap to enter bootloader functionality | y if STM32 or RP2040/RP2350 |
|
||||
| `CONFIG_ZMK_DBL_TAP_BOOTLOADER_TIMEOUT_MS` | int | Duration (in ms) to wait for a second reset to enter the bootloader | 500 |
|
||||
|
||||
## Snippets
|
||||
|
||||
:::danger
|
||||
@@ -132,7 +139,7 @@ The only way to restore functionality after that is to re-flash the bootloader.
|
||||
Re-flashing a bootloader built without the SoftDevice will require firmware built with these snippets.
|
||||
:::
|
||||
|
||||
[Snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html) are a way to save common configuration separately when it applies to multiple different applications.
|
||||
[Snippets](https://docs.zephyrproject.org/4.1.0/build/snippets/index.html) are a way to save common configuration separately when it applies to multiple different applications.
|
||||
|
||||
Enable snippets by adding `snippet: <snippet>` to your `build.yaml` for the appropriate board:
|
||||
|
||||
|
||||
@@ -70,7 +70,7 @@ What properties a node may have varies drastically. Of the standard properties,
|
||||
|
||||
#### Property types
|
||||
|
||||
These are some of the property types you will see most often when working with ZMK. [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/3.5.0/build/dts/bindings.html) provides more detailed information and a full list of types.
|
||||
These are some of the property types you will see most often when working with ZMK. [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/4.1.0/build/dts/bindings.html) provides more detailed information and a full list of types.
|
||||
|
||||
##### bool
|
||||
|
||||
@@ -124,14 +124,14 @@ Example: `property = <&none &mo 1>;`
|
||||
|
||||
Values can also be split into multiple blocks, e.g. `property = <&none>, <&mo 1>;`
|
||||
|
||||
See the documentation for "phandle-array" in [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/3.5.0/build/dts/bindings.html)
|
||||
See the documentation for "phandle-array" in [Zephyr's Devicetree bindings documentation](https://docs.zephyrproject.org/4.1.0/build/dts/bindings.html)
|
||||
for more details on how parameters are associated with nodes.
|
||||
|
||||
##### GPIO array
|
||||
|
||||
This is just a phandle array. The documentation lists this as a different type to make it clear which properties expect an array of GPIOs.
|
||||
|
||||
Each item in the array should be a label for a GPIO node (the names of which differ between hardware platforms) followed by an index and configuration flags. See [Zephyr's GPIO documentation](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/gpio.html) for a full list of flags. Phandles and labels will be explained in more detail in a [later section](#labels-and-phandles).
|
||||
Each item in the array should be a label for a GPIO node (the names of which differ between hardware platforms) followed by an index and configuration flags. See [Zephyr's GPIO documentation](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/gpio.html) for a full list of flags. Phandles and labels will be explained in more detail in a [later section](#labels-and-phandles).
|
||||
|
||||
Example:
|
||||
|
||||
@@ -187,7 +187,7 @@ properties:
|
||||
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).
|
||||
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/4.1.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.
|
||||
|
||||
@@ -260,7 +260,7 @@ A devicetree is almost always constructed from multiple files. These files are g
|
||||
|
||||
- `.dtsi` files, which exist exclusively to be included via the C preprocessor (their contents get "pasted" at the location of the `#include` command) and are not used by the build sytem otherwise.
|
||||
- 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_](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](hardware-integration/index.mdx#what-is-a-shield) or [snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html). 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.
|
||||
- Any number of `.overlay` files. These files can come from various sources, such as [shields](hardware-integration/index.mdx#what-is-a-shield) or [snippets](https://docs.zephyrproject.org/4.1.0/build/snippets/index.html). 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.
|
||||
|
||||
#### Merging and overwriting nodes
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
## Kconfig Symbol Enablement
|
||||
|
||||
Three Kconfig symbols need to be enabled for this feature to work, namely `RETAINED_MEM`, `RETENTION`, and `RETENTION_BOOT_MODE`. Typically, this is done by `imply`ing the symbols for the board symbol in the `Kconfig.<board>`, file, e.g.:
|
||||
|
||||
```dts
|
||||
config BOARD_TOFU65
|
||||
select SOC_RP2040
|
||||
imply RETAINED_MEM
|
||||
imply RETENTION
|
||||
imply RETENTION_BOOT_MODE
|
||||
```
|
||||
|
||||
By using `imply` at the board level, users of the board can choose to override the setting and disable the feature if they so choose.
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
title: Adafuit nRF52 Bootloader
|
||||
sidebar_label: Adafuit nRF52
|
||||
---
|
||||
|
||||
import BaseConfig from "./_base-config.md";
|
||||
|
||||
The [Adafruit nRF52 Bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader/) is a [magic value type bootloader](./index.mdx#magic-value-bootloaders), with some extra setup used to integrate with it.
|
||||
|
||||
<BaseConfig />
|
||||
|
||||
## Magic Value Type Kconfig
|
||||
|
||||
In addition to the core Kconfig symbols already set up, one additional Kconfig choice needs to be set, e.g. in `Kconfig.defaults` for the board:
|
||||
|
||||
```
|
||||
choice ZMK_BOOTMODE_MAGIC_VALUE_BOOTLOADER_TYPE
|
||||
default ZMK_BOOTMODE_MAGIC_VALUE_BOOTLOADER_TYPE_ADAFRUIT_NRF52
|
||||
|
||||
endchoice
|
||||
```
|
||||
|
||||
This ensures the correct magic value is stored in the retained memory.
|
||||
|
||||
## Devicetree Simple Include
|
||||
|
||||
A simple shared file can be included in your board's devicetree to set up the retained memory and retention nodes. Near the top of your file, add an include for `common/nordic/nrf52840_uf2_boot_mode.dtsi`, e.g.:
|
||||
|
||||
```dts
|
||||
/dts-v1/;
|
||||
|
||||
#include <nordic/nrf52840_qiaa.dtsi>
|
||||
#include <common/nordic/nrf52840_uf2_boot_mode.dtsi>
|
||||
```
|
||||
|
||||
## Devicetree Manual Changes
|
||||
|
||||
### GPREGRET Setup
|
||||
|
||||
Nordic nRF52840 has a dedicated register that can be used to store data to persist across resets. Zephyr has a retained mem driver over this register, so we'll add the boot mode retention to that existing node:
|
||||
|
||||
```dts
|
||||
&gpregret1 {
|
||||
adafruit_boot_retention: retention@0 {
|
||||
compatible = "zephyr,retention";
|
||||
status = "okay";
|
||||
reg = <0x0 0x1>;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Magic Value Mapper
|
||||
|
||||
Next, we'll set up our mapping retained mem driver, which will map from the Zephyr boot mode values to the values the bootloader is looking for:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
magic_mapper {
|
||||
compatible = "zmk,bootmode-to-magic-mapper";
|
||||
status = "okay";
|
||||
|
||||
#address-cells = <1>;
|
||||
#size-cells = <1>;
|
||||
|
||||
boot_retention: retention@0 {
|
||||
compatible = "zephyr,retention";
|
||||
status = "okay";
|
||||
reg = <0x0 0x1>;
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Chosen Node Properties
|
||||
|
||||
Finally, we'll assign two `chosen` properties for the two nodes that have been defined:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
chosen {
|
||||
zephyr,boot-mode = &boot_retention;
|
||||
zmk,magic-boot-mode = &adafruit_boot_retention;
|
||||
};
|
||||
```
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Bootloader Integration
|
||||
sidebar_label: Bootloader
|
||||
---
|
||||
|
||||
:::info
|
||||
The information on this page is only relevant for **boards**, not **shields**.
|
||||
:::
|
||||
|
||||
The `&bootloader` behavior requires properly set up [boot mode](https://docs.zephyrproject.org/4.1.0/services/retention/index.html#boot-mode) support to function properly. The behavior operates by setting the boot mode, resetting, and then relies on an SoC/bootloader specific early init hook to enter the bootloader when the boot mode is found to have been set.
|
||||
|
||||
Most of the SoCs actively supported by ZMK rely on a generic retained memory driver to store the boot mode between restarts, and additional configuration is required when using a second stage bootloader like the [Adafruit nRF52 Bootloader](https://github.com/adafruit/Adafruit_nRF52_Bootloader/) or [tinyuf2](https://github.com/adafruit/tinyuf2).
|
||||
|
||||
## Magic Value Bootloaders
|
||||
|
||||
Most "second stage" bootloaders will enter bootloader mode on startup when a specific magic value is found in a specific reserved location in memory. For those bootloaders, an extra mapping layer is used to map the Zephyr "bootloader mode" retained value to the magic value expected by the bootloader.
|
||||
|
||||
The following bootloaders of this type are supported, see those pages for details on the additional configuration needed:
|
||||
|
||||
- [Adafruit nRF52](./adafruit-nrf52.mdx)
|
||||
- [TinyUF2](./tinyuf2.mdx)
|
||||
- [SAMD21 UF2](./samd21-uf2.mdx)
|
||||
|
||||
## Jump-To Bootloaders
|
||||
|
||||
Several SoCs use bootloaders that can be directly jumped to from early init code in the firmware. For these situations, the only setup required is a a [retained mem](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/retained_mem.html) instance that can retain the set boot mode after the reset, in order for the early initailization code to check the value and then jump to the bootloader.
|
||||
|
||||
The following bootloaders of this type are supported, see those pages for details on the additional configuration needed:
|
||||
|
||||
- [RP2040/RP2350](./rp2.mdx)
|
||||
- [STM32](./stm32.mdx)
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: RP2040/RP2350 Bootloader
|
||||
sidebar_label: RP2040/RP2350
|
||||
---
|
||||
|
||||
import BaseConfig from "./_base-config.md";
|
||||
|
||||
The RP2040/RP2350 Bootloader is a [jump-to type bootloader](./index.mdx#jump-to-bootloaders), with some extra setup used to integrate with it.
|
||||
|
||||
By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../../config/system.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOTSEL pin.
|
||||
|
||||
<BaseConfig />
|
||||
|
||||
## Simple Include
|
||||
|
||||
A simple shared file can be included in your board's devicetree to set up the necessary retained memory and retention nodes. Near the top of your file, add an include for `arm/raspberrypi/rp2040-boot-mode-retention.dtsi`, e.g.:
|
||||
|
||||
```dts
|
||||
/dts-v1/;
|
||||
|
||||
#include <raspberrypi/rpi_pico/rp2040.dtsi>
|
||||
#include <arm/raspberrypi/rp2040-boot-mode-retention.dtsi>
|
||||
```
|
||||
|
||||
## Manual Changes
|
||||
|
||||
The include mentioned above can be performed manually, if you so choose.
|
||||
|
||||
First, we'll shrink the SRAM node, from the front, to create a 4-byte area that won't have anything placed in it by the normal Zephyr linking process:
|
||||
|
||||
```dts
|
||||
&sram0 {
|
||||
reg = <0x20000004 ((DT_SIZE_K(264)) - 4)>;
|
||||
};
|
||||
```
|
||||
|
||||
Next, we'll define a _new_ 4-byte RAM region for that reserved space, and within that region, set up a Zephyr retained RAM node. Within that node, we'll create the actual retention _value_ that is used:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
sram@20000000 {
|
||||
compatible = "zephyr,memory-region", "mmio-sram";
|
||||
reg = <0x20000000 0x4>;
|
||||
zephyr,memory-region = "RetainedMem";
|
||||
status = "okay";
|
||||
|
||||
retainedmem {
|
||||
compatible = "zephyr,retained-ram";
|
||||
status = "okay";
|
||||
#address-cells = <1>;
|
||||
#size-cells = <1>;
|
||||
boot_mode: retention@0 {
|
||||
compatible = "zephyr,retention";
|
||||
status = "okay";
|
||||
reg = <0x0 0x1>;
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Finally, we'll assign that new retention value node to the `zephyr,boot-mode` chosen property:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
chosen {
|
||||
zephyr,boot-mode = &boot_mode;
|
||||
};
|
||||
};
|
||||
```
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: SAMD21 UF2 Bootloader
|
||||
sidebar_label: SAMD21
|
||||
---
|
||||
|
||||
import BaseConfig from "./_base-config.md";
|
||||
|
||||
The [SAMD21 UF2 Bootloader](https://github.com/adafruit/uf2-samdx1) is a [magic value type bootloader](./index.mdx#magic-value-bootloaders), with some extra setup used to integrate with it.
|
||||
|
||||
<BaseConfig />
|
||||
|
||||
## Adjust The Existing RAM node
|
||||
|
||||
We'll first adjust the SRAM to ensure Zephyr does not overwrite the memory location the bootloader inspect to determine if it should enter bootloader mode:
|
||||
|
||||
```dts
|
||||
&sram0 {
|
||||
reg = <0x20000000 0x7FFC>;
|
||||
};
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- The `0x20000000` address is the address of the RAM for the target. This is nearly always `0x20000000`.
|
||||
- The exact value of `0x7FFC` will depend on the total RAM on the target. The value should be the total RAM, minus 4-bytes, in hex.
|
||||
|
||||
## Add a new memory region node with retainer RAM
|
||||
|
||||
```dts
|
||||
/ {
|
||||
sram@20007FFC {
|
||||
compatible = "zephyr,memory-region", "mmio-sram";
|
||||
reg = <0x20007FFC 0x4>;
|
||||
zephyr,memory-region = "RetainedMem";
|
||||
status = "okay";
|
||||
|
||||
retainedmem {
|
||||
compatible = "zephyr,retained-ram";
|
||||
status = "okay";
|
||||
#address-cells = <1>;
|
||||
#size-cells = <1>;
|
||||
|
||||
magic_retention: retention@0 {
|
||||
compatible = "zephyr,retention";
|
||||
status = "okay";
|
||||
reg = <0x0 0x4>;
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- The node `sram@20007FFC` and the corresponding `reg` property values are obtained by adding the base RAM address (.e.g. `0x20000000`) to the shrunk RAM size (e.g. `0x7FFC`) to get the new start address for the area of reserved RAM.
|
||||
- The magic values are 32-bits (4 bytes), so the second `reg` size value is `0x4`.
|
||||
|
||||
## Magic Mapper node
|
||||
|
||||
Next, we'll set up our mapping retained mem driver, which will map from the Zephyr boot mode values to the values the bootloader is looking for:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
magic_mapper {
|
||||
compatible = "zmk,bootmode-to-magic-mapper";
|
||||
status = "okay";
|
||||
|
||||
#address-cells = <1>;
|
||||
#size-cells = <1>;
|
||||
|
||||
boot_retention: retention@0 {
|
||||
compatible = "zephyr,retention";
|
||||
status = "okay";
|
||||
reg = <0x0 0x1>;
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Assign Chosen Properties
|
||||
|
||||
Finally, we'll assign two `chosen` properties for the two nodes that have been defined:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
chosen {
|
||||
zephyr,boot-mode = &boot_retention;
|
||||
zmk,magic-boot-mode = &magic_retention;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Magic Value Type Kconfig
|
||||
|
||||
Lastly, one Kconfig choice needs to be set, e.g. in `Kconfig.defaults` for the board:
|
||||
|
||||
```
|
||||
choice ZMK_BOOTMODE_MAGIC_VALUE_BOOTLOADER_TYPE
|
||||
default ZMK_BOOTMODE_MAGIC_VALUE_BOOTLOADER_TYPE_ADAFRUIT_BOSSA
|
||||
|
||||
endchoice
|
||||
```
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: STM32 ROM Bootloader
|
||||
sidebar_label: STM32 ROM
|
||||
toc_max_heading_level: 3
|
||||
---
|
||||
|
||||
import BaseConfig from "./_base-config.md";
|
||||
|
||||
The [STM32 ROM Bootloader](https://www.st.com/resource/en/application_note/an2606-stm32-microcontroller-system-memory-boot-mode-stmicroelectronics.pdf) is a [jump-to type bootloader](./index.mdx#jump-to-bootloaders), with some extra setup used to integrate with it.
|
||||
|
||||
By default, when integrating this bootloader, a ["double tap reset to enter the bootloader"](../../../config/system.md#double-tap-to-bootloader) feature will be enabled, to help with designs that do not easily expose a BOOT pin.
|
||||
|
||||
<BaseConfig />
|
||||
|
||||
## Adjust Existing SRAM Node
|
||||
|
||||
First, we'll adjust the existing SRAM node to shrink it by one byte so Zephyr will not interfere with the retained mem:
|
||||
|
||||
```dts
|
||||
/* Reduce SRAM0 usage by 1 byte to account for non-init area */
|
||||
&sram0 {
|
||||
reg = <0x20000000 0x3FFF>;
|
||||
};
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- The `0x20000000` address is the address of the RAM for the target. This is nearly always `0x20000000`
|
||||
- The exact value of `0x3FFF` will depend on the total RAM on the target. The value should be the total RAM, minus 1-bytes, in hex
|
||||
|
||||
## New Memory Region & Nested Retained Mem
|
||||
|
||||
```dts
|
||||
/ {
|
||||
sram@20003FFF {
|
||||
compatible = "zephyr,memory-region", "mmio-sram";
|
||||
reg = <0x20003FFF 0x1>;
|
||||
zephyr,memory-region = "RetainedMem";
|
||||
status = "okay";
|
||||
|
||||
retainedmem {
|
||||
compatible = "zephyr,retained-ram";
|
||||
status = "okay";
|
||||
#address-cells = <1>;
|
||||
#size-cells = <1>;
|
||||
|
||||
retention0: retention@0 {
|
||||
compatible = "zephyr,retention";
|
||||
status = "okay";
|
||||
reg = <0x0 0x1>;
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- The node `sram@20003FFF` and the corresponding `reg` property values are obtained by adding the base RAM address (.e.g. `0x20000000`) to the shrunk RAM size (e.g. `0x3FFF`) to get the new start address for the area of reserved RAM.
|
||||
|
||||
## Chosen Boot Mode Node
|
||||
|
||||
Finally, we'll set a chosen property to select the created retention node:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
chosen {
|
||||
zephyr,boot-mode = &retention0;
|
||||
};
|
||||
};
|
||||
```
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: TinyUF2 Bootloader
|
||||
sidebar_label: TinyUF2
|
||||
---
|
||||
|
||||
import BaseConfig from "./_base-config.md";
|
||||
|
||||
The [TinyUF2 Bootloader](https://github.com/adafruit/tinyuf2) is a [magic value type bootloader](./index.mdx#magic-value-bootloaders), with some extra setup used to integrate with it.
|
||||
|
||||
<BaseConfig />
|
||||
|
||||
## Adjust The Existing RAM node
|
||||
|
||||
For TinyUF2, we'll first adjust the SRAM to ensure Zephyr does not overwrite the memory location the bootloader inspect to determine if it should enter bootloader mode:
|
||||
|
||||
```dts
|
||||
&sram0 {
|
||||
reg = <0x20000000 0x1FFFC>;
|
||||
};
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- The `0x20000000` address is the address of the RAM for the target. This is nearly always `0x20000000`
|
||||
- The exact value of `0x1FFFC` will depend on the total RAM on the target. The value should be the total RAM, minus 4-bytes, in hex
|
||||
|
||||
## Add a New Memory Region Node with Retainer RAM
|
||||
|
||||
```dts
|
||||
/ {
|
||||
sram@2001FFFC {
|
||||
compatible = "zephyr,memory-region", "mmio-sram";
|
||||
reg = <0x2001FFFC 0x4>;
|
||||
zephyr,memory-region = "RetainedMem";
|
||||
status = "okay";
|
||||
|
||||
retainedmem {
|
||||
compatible = "zephyr,retained-ram";
|
||||
status = "okay";
|
||||
#address-cells = <1>;
|
||||
#size-cells = <1>;
|
||||
|
||||
magic_retention: retention@0 {
|
||||
compatible = "zephyr,retention";
|
||||
status = "okay";
|
||||
reg = <0x0 0x4>;
|
||||
};
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
Note:
|
||||
|
||||
- The node `sram@2001FFFC` and the corresponding `reg` property values are obtained by adding the base RAM address (.e.g. `0x20000000`) to the shrunk RAM size (e.g. `0x1FFFC`) to get the new start address for the area of reserved RAM.
|
||||
- The magic values in TinyUF2 are 32-bits (4 bytes), so the second `reg` size value is `0x4`.
|
||||
|
||||
## Magic Mapper node
|
||||
|
||||
Next, we'll set up our mapping retained mem driver, which will map from the Zephyr boot mode values to the values the bootloader is looking for:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
magic_mapper {
|
||||
compatible = "zmk,bootmode-to-magic-mapper";
|
||||
status = "okay";
|
||||
|
||||
#address-cells = <1>;
|
||||
#size-cells = <1>;
|
||||
|
||||
boot_retention: retention@0 {
|
||||
compatible = "zephyr,retention";
|
||||
status = "okay";
|
||||
reg = <0x0 0x1>;
|
||||
};
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Assign Chosen Properties
|
||||
|
||||
Finally, we'll assign two `chosen` properties for the two nodes that have been defined:
|
||||
|
||||
```dts
|
||||
/ {
|
||||
chosen {
|
||||
zephyr,boot-mode = &boot_retention;
|
||||
zmk,magic-boot-mode = &magic_retention;
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Magic Value Type Kconfig
|
||||
|
||||
Lastly, one Kconfig choice needs to be set, e.g. in `Kconfig.defaults` for the board:
|
||||
|
||||
```
|
||||
choice ZMK_BOOTMODE_MAGIC_VALUE_BOOTLOADER_TYPE
|
||||
default ZMK_BOOTMODE_MAGIC_VALUE_BOOTLOADER_TYPE_TINYUF2
|
||||
|
||||
endchoice
|
||||
```
|
||||
@@ -23,7 +23,7 @@ These core architectural elements are defined per-keyboard, and _where_ they are
|
||||
## Boards & Shields
|
||||
|
||||
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.
|
||||
Also see the Zephyr documentation on [boards](https://docs.zephyrproject.org/3.5.0/glossary.html#term-board) and [shields](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html).
|
||||
Also see the Zephyr documentation on [boards](https://docs.zephyrproject.org/4.1.0/glossary.html#term-board) and [shields](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html).
|
||||
|
||||
### What is a "board"?
|
||||
|
||||
@@ -84,9 +84,9 @@ In that directory you'll have the following files, where there can be multiples
|
||||
└── <keyboard_name>.zmk.yml
|
||||
```
|
||||
|
||||
These files include [base Kconfig files](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html):
|
||||
These files include [base Kconfig files](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html):
|
||||
|
||||
- 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.board` file that defines the toplevel [Kconfig](https://docs.zephyrproject.org/4.1.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`](../../config/system.md#general) to a value, for the product name to be used for USB/BLE info,
|
||||
- Setting [`ZMK_USB`](../../config/system.md#usb) and/or [`ZMK_BLE`](../../config/system.md#bluetooth) for the default values for which HID transport(s) to enable by default
|
||||
@@ -101,7 +101,7 @@ These files include [base Kconfig files](https://docs.zephyrproject.org/3.5.0/bu
|
||||
- `<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 [chosen](https://docs.zephyrproject.org/4.1.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 `<keyboard_name>.keymap` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs.
|
||||
|
||||
And other miscellaneous ones:
|
||||
@@ -109,7 +109,7 @@ And other miscellaneous ones:
|
||||
- A `board.cmake` file with CMake directives for how to flash to the device.
|
||||
- A `<keyboard_name>.zmk.yml` file containing [metadata](hardware-metadata-files.md) for the keyboard.
|
||||
|
||||
See Zephyr's [board porting guide](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html) for information on creating a new board.
|
||||
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.
|
||||
|
||||
[^1]:
|
||||
@@ -142,8 +142,8 @@ These files include [base Kconfig files](new-shield.mdx#base-kconfig-files):
|
||||
[Devicetree files](../../config/index.md#devicetree-files):
|
||||
|
||||
- A `<shield_name>.overlay` file which is a devicetree overlay file[^1], containing definitions including but not limited to:
|
||||
- Kscan, matrix transform and physical layout devicetree nodes as described above, where the kscan node uses the interconnect [nexus node](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#gpio-nexus-nodes) aliases such as `&pro_micro` for GPIO pins.
|
||||
- A [chosen](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including at least the `zmk,physical-layout` property, referring to the defined node.
|
||||
- Kscan, matrix transform and physical layout devicetree nodes as described above, where the kscan node uses the interconnect [nexus node](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html#gpio-nexus-nodes) aliases such as `&pro_micro` for GPIO pins.
|
||||
- A [chosen](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including at least the `zmk,physical-layout` property, referring to the defined node.
|
||||
- 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.
|
||||
|
||||
And other miscellaneous ones:
|
||||
|
||||
@@ -61,7 +61,7 @@ The high level steps are:
|
||||
Many of the above files will differ depending on whether your keyboard is a unibody or is [split into multiple parts](../../features/split-keyboards.md).
|
||||
|
||||
After adding ZMK support for a basic shield using this guide, check the sidebar for guides on adding any additional features (such as encoders) that your keyboard has.
|
||||
It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing.
|
||||
It may be helpful to review the upstream [shields documentation](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html#shields) to get a proper understanding of the underlying system before continuing.
|
||||
|
||||
## New ZMK Module Repository
|
||||
|
||||
@@ -106,7 +106,7 @@ mkdir boards/shields/<keyboard_name>
|
||||
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.
|
||||
:::
|
||||
|
||||
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`.
|
||||
There are two required [Kconfig](https://docs.zephyrproject.org/4.1.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`.
|
||||
|
||||
<SplitTabs></SplitTabs>
|
||||
|
||||
|
||||
@@ -9,13 +9,13 @@ import InterconnectTabs from "@site/src/components/interconnect-tabs";
|
||||
import Metadata from "@site/src/data/hardware-metadata.json";
|
||||
|
||||
:::info
|
||||
This page exists to provide a guide to [Pin Control](https://docs.zephyrproject.org/3.5.0/hardware/pinctrl/index.html#pin-control) for ZMK users and designers. Refer to [Zephyr's page on Pin Control](https://docs.zephyrproject.org/3.5.0/hardware/pinctrl/index.html#pin-control) for elaboration and more details on any of the points raised here.
|
||||
This page exists to provide a guide to [Pin Control](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-control) for ZMK users and designers. Refer to [Zephyr's page on Pin Control](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-control) for elaboration and more details on any of the points raised here.
|
||||
:::
|
||||
|
||||
A basic keyboard design as introduced in the [new shield guide](./new-shield.mdx) only uses its pins for the keyboard matrix. Many keyboard designs make use of advanced components or functionality, such as displays or shift registers. This results in the keyboard making use of communication protocols such as (but not limited to) SPI, I2C, or UART. Configuring pins for the usage of advanced functionality such as drivers for the previously named protocols is referred to as "Pin Control".
|
||||
|
||||
:::warning
|
||||
The details of pin control can vary from vendor to vendor. An attempt was made to be as general as possible, but it isn't possible to cover all possible cases. The approaches for the nRF52840 and RP2040 MCUs/SoCs are documented in their entirety below. For other MCUs/SoCs, please refer to the [Zephyr documentation](https://docs.zephyrproject.org/3.5.0/index.html) and the examples and other files found in-tree of [ZMK](https://github.com/zmkfirmware/zmk/tree/main/app/boards) and [ZMK's fork of Zephyr](https://github.com/zmkfirmware/zephyr).
|
||||
The details of pin control can vary from vendor to vendor. An attempt was made to be as general as possible, but it isn't possible to cover all possible cases. The approaches for the nRF52840 and RP2040 MCUs/SoCs are documented in their entirety below. For other MCUs/SoCs, please refer to the [Zephyr documentation](https://docs.zephyrproject.org/4.1.0/index.html) and the examples and other files found in-tree of [ZMK](https://github.com/zmkfirmware/zmk/tree/main/app/boards) and [ZMK's fork of Zephyr](https://github.com/zmkfirmware/zephyr).
|
||||
:::
|
||||
|
||||
## Boards, Shields, and Modules
|
||||
@@ -110,7 +110,7 @@ All of your configuration will happen by adjusting the `pinctrl` node. Changes a
|
||||
Within said node, you will configure one or more child nodes for the buses. You will want to define the child nodes according to the instructions in the `pinctrl.yaml` file.
|
||||
The child nodes that you define should be named appropriately. The common naming schema is `usageNumber_state`. For example, `uart0_default`.
|
||||
|
||||
Child nodes are (generally, there are [exceptions](https://docs.zephyrproject.org/3.5.0/hardware/pinctrl/index.html#pin-configuration)) expected to contain one or more subnodes typically named "groupX". These are for grouping together pins that should be assigned the same state, such as enabling an internal pull-up.
|
||||
Child nodes are (generally, there are [exceptions](https://docs.zephyrproject.org/4.1.0/hardware/pinctrl/index.html#pin-configuration)) expected to contain one or more subnodes typically named "groupX". These are for grouping together pins that should be assigned the same state, such as enabling an internal pull-up.
|
||||
Below are some examples of SPI child nodes for the nRF52840 and the RP2040. Further examples are contained within the comments of the respecting `pinctrl.yaml` files.
|
||||
|
||||
<Tabs
|
||||
@@ -281,7 +281,7 @@ Once you have defined your node, you make use of it by further adjusting the nod
|
||||
};
|
||||
```
|
||||
|
||||
You would then want to make any adjustments to the node that are necessary, for example adjusting the clock speed. See the Zephyr API documentation for your `compatible` property to see the available properties for customisation. It is recommended to read through the [description of important properties](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#dt-important-props), potentially with the addition of [this blog post](https://interrupt.memfault.com/blog/practical_zephyr_dt#zephyrs-dts-skeleton-and-addressing) if `#address-cells` is confusing you.
|
||||
You would then want to make any adjustments to the node that are necessary, for example adjusting the clock speed. See the Zephyr API documentation for your `compatible` property to see the available properties for customisation. It is recommended to read through the [description of important properties](https://docs.zephyrproject.org/4.1.0/build/dts/intro-syntax-structure.html#dt-important-props), potentially with the addition of [this blog post](https://interrupt.memfault.com/blog/practical_zephyr_dt#zephyrs-dts-skeleton-and-addressing) if `#address-cells` is confusing you.
|
||||
|
||||
For SPI specifically, you would create a child node within your SPI bus for each device making use of the SPI bus.
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ toc_max_heading_level: 2
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
ZMK's pointing device support builds upon the Zephyr [input API](https://docs.zephyrproject.org/3.5.0/services/input/index.html) to offer pointing/mouse functionality with various hardware.
|
||||
ZMK's pointing device support builds upon the Zephyr [input API](https://docs.zephyrproject.org/4.1.0/services/input/index.html) to offer pointing/mouse functionality with various hardware.
|
||||
A limited number of input drivers are available in the Zephyr version currently used by ZMK, but additional drivers can be found in [external modules](../../features/modules.mdx) for a variety of hardware.
|
||||
|
||||
Pointing devices are also supported on split peripherals, with some additional configuration using the [input split device](../../config/pointing.md#input-split).
|
||||
@@ -42,17 +42,17 @@ This node should always be set up in the `.overlay`/`.dts` file for the keyboard
|
||||
<SplitTabs>
|
||||
<TabItem value="unibody">
|
||||
|
||||
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml), a node like following would be added to the `.overlay`/`.dts` file for the keyboard, like `<keyboard>.overlay`:
|
||||
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml), a node like following would be added to the `.overlay`/`.dts` file for the keyboard, like `<keyboard>.overlay`:
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="central">
|
||||
|
||||
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on a central part, a node like following would be added to the `.overlay`/`.dts` file for the central part of the keyboard, like `<central>.overlay`:
|
||||
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on a central part, a node like following would be added to the `.overlay`/`.dts` file for the central part of the keyboard, like `<central>.overlay`:
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="peripheral">
|
||||
|
||||
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on one of the peripheral parts, a node like following would be added to the `.overlay`/`.dts` file for that peripheral part, like `<peripheral>.overlay`:
|
||||
For example, if setting up an [SPI device](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/dts/bindings/spi/spi-device.yaml) on one of the peripheral parts, a node like following would be added to the `.overlay`/`.dts` file for that peripheral part, like `<peripheral>.overlay`:
|
||||
|
||||
</TabItem>
|
||||
</SplitTabs>
|
||||
@@ -264,7 +264,7 @@ As an example, you could enhance the listener defined in the previous section wi
|
||||
## Configuration Setting
|
||||
|
||||
If your keyboard hardware includes a pointing device by default, you can enable the [`ZMK_POINTING` config](../../config/pointing.md#general) in your keyboard definition.
|
||||
You can do that in your [`Kconfig.defconfig` file](new-shield.mdx#kconfigdefconfig), where you can also enable the config for the communication protocol (e.g. [SPI](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_SPI), [I2C](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/i2c.html#configuration-options)) used by the pointing device:
|
||||
You can do that in your [`Kconfig.defconfig` file](new-shield.mdx#kconfigdefconfig), where you can also enable the config for the communication protocol (e.g. [SPI](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_SPI), [I2C](https://docs.zephyrproject.org/4.1.0/hardware/peripherals/i2c.html#configuration-options)) used by the pointing device:
|
||||
|
||||
<SplitTabs>
|
||||
<TabItem value="unibody">
|
||||
|
||||
@@ -75,7 +75,7 @@ For this approach, you will need to make sure that the [soft off behavior](../..
|
||||
|
||||
### GPIO key
|
||||
|
||||
Zephyr's basic [GPIO Key](https://docs.zephyrproject.org/3.5.0/build/dts/api/bindings/input/gpio-keys.html) concept is used to configure the soft off GPIO pin.
|
||||
Zephyr's basic [GPIO Key](https://docs.zephyrproject.org/4.1.0/build/dts/api/bindings/input/gpio-keys.html) concept is used to configure the soft off GPIO pin.
|
||||
{/* secrettabs hides this tab selector. GPIO key changes its "orientation" between simple pin and matrix integrated. */}
|
||||
|
||||
<Tabs
|
||||
@@ -97,7 +97,7 @@ Zephyr's basic [GPIO Key](https://docs.zephyrproject.org/3.5.0/build/dts/api/bin
|
||||
|
||||
GPIO keys are defined using child nodes under the `gpio-keys` compatible node. Each child needs just one property defined:
|
||||
|
||||
- The `gpios` property should be a [phandle-array](https://docs.zephyrproject.org/3.5.0/build/dts/phandles.html#zero-or-more-nodes-with-metadata-phandle-array-type) with a fully defined GPIO pin and with the correct pull up/down and active high/low flags set.
|
||||
- The `gpios` property should be a [phandle-array](https://docs.zephyrproject.org/4.1.0/build/dts/phandles.html#zero-or-more-nodes-with-metadata-phandle-array-type) with a fully defined GPIO pin and with the correct pull up/down and active high/low flags set.
|
||||
|
||||
<Tabs
|
||||
groupId="advanced-methods"
|
||||
|
||||
@@ -21,7 +21,7 @@ If this is not done, you will encounter errors such as: `ERROR: source directory
|
||||
## Building
|
||||
|
||||
Building a particular keyboard is done using the
|
||||
[`west build`](https://docs.zephyrproject.org/3.5.0/develop/west/build-flash-debug.html#building-west-build)
|
||||
[`west build`](https://docs.zephyrproject.org/4.1.0/develop/west/build-flash-debug.html#building-west-build)
|
||||
command. Its usage slightly changes depending on if your build is for a keyboard
|
||||
with an onboard MCU or one that uses an MCU board add-on.
|
||||
|
||||
@@ -32,7 +32,7 @@ with an onboard MCU or one that uses an MCU board add-on.
|
||||
]}>
|
||||
<TabItem value="onboardMcu">
|
||||
Keyboards with onboard MCU chips are simply treated as the
|
||||
[board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html)
|
||||
[board](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html)
|
||||
as far as Zephyr™ is concerned.
|
||||
|
||||
Given the following:
|
||||
@@ -49,9 +49,9 @@ with an onboard MCU or one that uses an MCU board add-on.
|
||||
</TabItem>
|
||||
<TabItem value="addonMcu">
|
||||
ZMK treats keyboards that take an MCU addon board as
|
||||
[shields](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html),
|
||||
[shields](https://docs.zephyrproject.org/4.1.0/hardware/porting/shields.html),
|
||||
and treats the smaller MCU board as the true
|
||||
[board](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html).
|
||||
[board](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html).
|
||||
|
||||
Given the following:
|
||||
|
||||
@@ -94,7 +94,7 @@ west build -d <build_dir>
|
||||
:::
|
||||
|
||||
You can also add permanent CMake arguments to `west build` by using the
|
||||
[`west config`](https://docs.zephyrproject.org/3.5.0/develop/west/config.html#west-config-cmd)
|
||||
[`west config`](https://docs.zephyrproject.org/4.1.0/develop/west/config.html#west-config-cmd)
|
||||
command. These are invoked whenever a new build system is generated. To add
|
||||
permanent arguments, set the `build.cmake-args` configuration option.
|
||||
|
||||
@@ -198,7 +198,7 @@ west flash
|
||||
|
||||
## Multi-CPU and Dual-Chip Bluetooth Boards
|
||||
|
||||
Zephyr supports running the Bluetooth host and controller on separate processors. In such a configuration, ZMK always runs on the host processor, but you may need to build and flash separate firmware for the controller. Zephyr provides sample code which can be used as the controller firmware for Bluetooth HCI over [RPMsg](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_rpmsg/README.html), [SPI](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_spi/README.html), [UART](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_uart/README.html), and [USB](https://docs.zephyrproject.org/3.5.0/samples/bluetooth/hci_usb/README.html). See [Zephyr's Bluetooth Stack Architecture documentation](https://docs.zephyrproject.org/3.5.0/connectivity/bluetooth/bluetooth-arch.html) for more details.
|
||||
Zephyr supports running the Bluetooth host and controller on separate processors. In such a configuration, ZMK always runs on the host processor, but you may need to build and flash separate firmware for the controller. Zephyr provides sample code which can be used as the controller firmware for Bluetooth HCI over [RPMsg](https://docs.zephyrproject.org/4.1.0/samples/bluetooth/hci_rpmsg/README.html), [SPI](https://docs.zephyrproject.org/4.1.0/samples/bluetooth/hci_spi/README.html), [UART](https://docs.zephyrproject.org/4.1.0/samples/bluetooth/hci_uart/README.html), and [USB](https://docs.zephyrproject.org/4.1.0/samples/bluetooth/hci_usb/README.html). See [Zephyr's Bluetooth Stack Architecture documentation](https://docs.zephyrproject.org/4.1.0/connectivity/bluetooth/bluetooth-arch.html) for more details.
|
||||
|
||||
The following documentation shows how to build and flash ZMK for boards that use a dual-chip configuration.
|
||||
|
||||
|
||||
@@ -73,13 +73,17 @@ export const WinTermTabs = (props) => (
|
||||
|
||||
## 1. Install Zephyr Dependencies
|
||||
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
Open Zephyr's [Getting Started Guide](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html) and follow the instructions under these sections:
|
||||
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-dependencies)
|
||||
- [Select and Update OS](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html#select-and-update-os)
|
||||
- [Install Dependencies](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html#install-dependencies)
|
||||
|
||||
:::info
|
||||
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu.
|
||||
Zephyr's [Install Linux Host Dependencies](https://docs.zephyrproject.org/4.1.0/develop/getting_started/installation_linux.html) page may be of use for users of Linux distributions which are not based on Ubuntu.
|
||||
:::
|
||||
|
||||
:::warning
|
||||
Some optional Zephyr modules, like `libmetal`, are not compatible with CMake v4, so we recommend installing the latest CMake v3 release when installing the Zephyr dependencies.
|
||||
:::
|
||||
|
||||
## 2. Source Code
|
||||
@@ -99,7 +103,7 @@ cd zmk
|
||||
## 3. Get Zephyr and install Python dependencies
|
||||
|
||||
:::note
|
||||
These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialized for ZMK.
|
||||
These steps are very similar to Zephyr's [Get Zephyr and install Python dependencies](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html#get-zephyr-and-install-python-dependencies) instructions, but specialized for ZMK.
|
||||
:::
|
||||
|
||||
<EnvTabs>
|
||||
@@ -191,22 +195,16 @@ west update
|
||||
This step pulls down quite a bit of tooling, be patient!
|
||||
:::
|
||||
|
||||
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
|
||||
6. Export a [Zephyr CMake package](https://docs.zephyrproject.org/4.1.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
```
|
||||
|
||||
7. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
|
||||
7. Install the additional Zephyr dependencies using `west`:
|
||||
|
||||
```sh
|
||||
pip install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
If you are going to build firmware with [ZMK Studio](../../../features/studio.md), also install `requirements-extras.txt` dependencies:
|
||||
|
||||
```sh
|
||||
pip install -r zephyr/scripts/requirements-extras.txt
|
||||
west packages pip --install
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
@@ -286,7 +284,7 @@ west update
|
||||
This step pulls down quite a bit of tooling, be patient!
|
||||
:::
|
||||
|
||||
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
|
||||
3. Export a [Zephyr CMake package](https://docs.zephyrproject.org/4.1.0/build/zephyr_cmake_package.html#cmake-pkg). This allows CMake to automatically load boilerplate code required for building Zephyr applications.
|
||||
|
||||
```sh
|
||||
west zephyr-export
|
||||
@@ -295,47 +293,29 @@ west zephyr-export
|
||||
<Tabs groupId="operating-systems" queryString defaultValue="ubuntu" className="secrettabs">
|
||||
<TabItem value="ubuntu" label="Ubuntu">
|
||||
|
||||
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
|
||||
4. Install the additional Zephyr dependencies using `west`:
|
||||
|
||||
```sh
|
||||
pip3 install --user -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
If you are going to build firmware with [ZMK Studio](../../../features/studio.md), also install `requirements-extras.txt` dependencies:
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements-extras.txt
|
||||
west packages pip --install
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="win" label="Windows">
|
||||
|
||||
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`:
|
||||
4. Install the additional Zephyr dependencies using `west`:
|
||||
|
||||
```sh
|
||||
pip install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
If you are going to build firmware with [ZMK Studio](../../../features/studio.md), also install `requirements-extras.txt` dependencies:
|
||||
|
||||
```sh
|
||||
pip install -r zephyr/scripts/requirements-extras.txt
|
||||
west packages pip --install
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="mac" label="Mac OS">
|
||||
4. Install the additional dependencies found in Zephyr's `requirements-base.txt`.
|
||||
4. Install the additional Zephyr dependencies using `west`:
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements-base.txt
|
||||
```
|
||||
|
||||
If you are going to build firmware with [ZMK Studio](../../../features/studio.md), also install `requirements-extras.txt` dependencies:
|
||||
|
||||
```sh
|
||||
pip3 install -r zephyr/scripts/requirements-extras.txt
|
||||
west packages pip --install
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
@@ -345,7 +325,7 @@ pip3 install -r zephyr/scripts/requirements-extras.txt
|
||||
|
||||
## 4. Install Zephyr SDK
|
||||
|
||||
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/3.5.0/develop/getting_started/index.html#install-zephyr-sdk).
|
||||
Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.zephyrproject.org/4.1.0/develop/getting_started/index.html#install-zephyr-sdk).
|
||||
|
||||
### OS-Specific Notes
|
||||
|
||||
@@ -360,7 +340,7 @@ Return to Zephyr's Getting Started Guide and [Install Zephyr SDK](https://docs.z
|
||||
<TabItem value="raspberryos">
|
||||
#### Install cross-compile toolchain
|
||||
|
||||
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/3.5.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
|
||||
Because Raspberry OS runs on the same architecture (but different ABI) as ARM keyboard MCUs, the operating system's installed [cross compilers](https://docs.zephyrproject.org/4.1.0/develop/toolchains/other_x_compilers.html) can be used to target the different ABI. Building for non-ARM MCUs has not been tested.
|
||||
|
||||
First, the cross compiler should be installed:
|
||||
|
||||
@@ -368,7 +348,7 @@ First, the cross compiler should be installed:
|
||||
sudo apt install gcc-arm-none-eabi
|
||||
```
|
||||
|
||||
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/3.5.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
|
||||
Next, we'll configure Zephyr with some [environment variables](https://docs.zephyrproject.org/4.1.0/develop/env_vars.html#env-vars) needed to find the cross compiler. Create a file named `~/.zephyrrc` if it doesn't exist, and add these lines to it:
|
||||
|
||||
```sh
|
||||
export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
|
||||
|
||||
@@ -10,7 +10,7 @@ sidebar_label: ZMK Module Creation
|
||||
- Modules containing drivers
|
||||
- Modules containing other features, such as visual effects
|
||||
|
||||
See also Zephyr's [page on modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html).
|
||||
See also Zephyr's [page on modules](https://docs.zephyrproject.org/4.1.0/develop/modules.html).
|
||||
|
||||
:::tip
|
||||
For open source hardware designs, it can be convenient to use [Git submodules](https://github.blog/open-source/git/working-with-submodules/) to have the ZMK module also be a Git submodule of the repository hosting the hardware design.
|
||||
@@ -71,13 +71,13 @@ Next, you need to define the options to build your module. These also go into `z
|
||||
- `settings` is a child property containing additional child properties, two of which are particularly relevant:
|
||||
- `board_root` points to the parent directory of a `boards` directory, which contains additional board/shield definitions.
|
||||
- `dts_root` points to the parent directory of a `dts` directory, which contains additional devicetree bindings.
|
||||
- `snippet_root` points to the parent directory of a `snippets` directory, which contains [snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html).
|
||||
- `snippet_root` points to the parent directory of a `snippets` directory, which contains [snippets](https://docs.zephyrproject.org/4.1.0/build/snippets/index.html).
|
||||
|
||||
See the `zephyr/module.yml` found in the template for a usage example.
|
||||
|
||||
### Dependencies
|
||||
|
||||
If `zephyr/module.yml` has anything listed under `depends`, then you should also define a [west manifest](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html) file. While the `zephyr/module.yml` file defines _which_ modules your module depends on, the west manifest file defines _where_ said modules are found. This then allows automatic tooling to fetch the modules when building firmware. If `depends` is not present in `zephyr/module.yml`, then this file (named `west.yml` in the template) should be removed.
|
||||
If `zephyr/module.yml` has anything listed under `depends`, then you should also define a [west manifest](https://docs.zephyrproject.org/4.1.0/develop/west/manifest.html) file. While the `zephyr/module.yml` file defines _which_ modules your module depends on, the west manifest file defines _where_ said modules are found. This then allows automatic tooling to fetch the modules when building firmware. If `depends` is not present in `zephyr/module.yml`, then this file (named `west.yml` in the template) should be removed.
|
||||
|
||||
It is recommended that you place the manifest file at the root of your module, though you can place it elsewhere. Be sure to note in your `README.md` that your module uses dependencies, so that users import these correctly.
|
||||
Below is an example `west.yml` file for a user that would be using your module, with the necessary `import` field if the module has dependencies:
|
||||
@@ -126,7 +126,7 @@ The below table reminds of the purpose of each of these files and folders, if yo
|
||||
| `Kconfig` | Kconfig file for the module |
|
||||
| `include/` | Folder for C header files |
|
||||
| `src/` | Folder for C source files |
|
||||
| `snippets/` | Folder for [snippets](https://docs.zephyrproject.org/3.5.0/build/snippets/index.html) |
|
||||
| `snippets/` | Folder for [snippets](https://docs.zephyrproject.org/4.1.0/build/snippets/index.html) |
|
||||
|
||||
Note that the `include` and `src` folders are not mandated by the module system, and all of these can be positioned anywhere in your module's filetree if you adjust the `zephyr/module.yml` accordingly. The `west.yml` file is not commonly present in any of the types.
|
||||
|
||||
|
||||
@@ -39,8 +39,8 @@ Before developing new behaviors, developers should have a working knowledge of t
|
||||
The following resources are provided for those seeking further understanding:
|
||||
|
||||
- [Embedded Linux Wiki - Device Tree Usage](https://elinux.org/Device_Tree_Usage)
|
||||
- [Zephyr Devicetree API](https://docs.zephyrproject.org/3.5.0/build/dts/api/api.html)
|
||||
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/3.5.0/kernel/drivers/index.html)
|
||||
- [Zephyr Devicetree API](https://docs.zephyrproject.org/4.1.0/build/dts/api/api.html)
|
||||
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/4.1.0/kernel/drivers/index.html)
|
||||
|
||||
:::
|
||||
|
||||
@@ -174,7 +174,7 @@ See [Behavior Metadata](#behavior-metadata) for more information.
|
||||
#### `properties` (Optional)
|
||||
|
||||
These are additional variables required to configure a particular instance of a behavior.
|
||||
More information can be found in [ZMK's Devicetree primer](./devicetree.md) or [Zephyr's own documentation on Devicetree bindings](https://docs.zephyrproject.org/3.5.0/build/dts/bindings-syntax.html#properties).
|
||||
More information can be found in [ZMK's Devicetree primer](./devicetree.md) or [Zephyr's own documentation on Devicetree bindings](https://docs.zephyrproject.org/4.1.0/build/dts/bindings-syntax.html#properties).
|
||||
|
||||
### Behavior Source Files (`.c`)
|
||||
|
||||
@@ -497,8 +497,8 @@ We will review the components from the [behavior source templates](#behavior-sou
|
||||
Developing drivers for behaviors in ZMK makes extensive use of the Zephyr Devicetree API and Device Driver Model.
|
||||
Links to the Zephyr Project Documentation for both of these concepts can be found below:
|
||||
|
||||
- [Zephyr Devicetree API](https://docs.zephyrproject.org/3.5.0/build/dts/api/api.html)
|
||||
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/3.5.0/kernel/drivers/index.html)
|
||||
- [Zephyr Devicetree API](https://docs.zephyrproject.org/4.1.0/build/dts/api/api.html)
|
||||
- [Zephyr Device Driver Model](https://docs.zephyrproject.org/4.1.0/kernel/drivers/index.html)
|
||||
|
||||
:::
|
||||
|
||||
@@ -672,7 +672,7 @@ The API struct's metadata-specific fields are shown below.
|
||||
`BEHAVIOR_DT_INST_DEFINE` is a special ZMK macro which uses Zephyr's `DEVICE_DT_INST_DEFINE` macro to define the driver instance, before adding it to a list of ZMK behaviors so that can be found by the function `zmk_behavior_get_binding()`.
|
||||
|
||||
:::info
|
||||
For more information on this function, refer to [Zephyr's documentation on the Device Driver Model](https://docs.zephyrproject.org/3.5.0/kernel/drivers/index.html#c.DEVICE_DT_INST_DEFINE).
|
||||
For more information on this function, refer to [Zephyr's documentation on the Device Driver Model](https://docs.zephyrproject.org/4.1.0/kernel/drivers/index.html#c.DEVICE_DT_INST_DEFINE).
|
||||
:::
|
||||
|
||||
The example `BEHAVIOR_DT_INST_DEFINE` call can be left as is with the first parameter, the instance number, equal to `0` for behaviors that only require a single instance (e.g. external power, backlighting, accessing layers).
|
||||
@@ -730,7 +730,7 @@ The **fourth** argument of `BEHAVIOR_DT_INST_DEFINE` can be set to `NULL` instea
|
||||
#### Optional: Configuration pointers
|
||||
|
||||
The configuration `struct` stores the properties declared from the behavior's `.yaml` for **each new instance** of the behavior.
|
||||
As seen in the `#define KP_INST(n)` of the hold-tap example, the configuration `struct`, `behavior_<name_of_behavior>_config_##n`, for each instance number, `n`, can be initialized using the [Zephyr Devicetree Instance-based APIs](https://docs.zephyrproject.org/3.5.0/build/dts/api/api.html#instance-based-apis),
|
||||
As seen in the `#define KP_INST(n)` of the hold-tap example, the configuration `struct`, `behavior_<name_of_behavior>_config_##n`, for each instance number, `n`, can be initialized using the [Zephyr Devicetree Instance-based APIs](https://docs.zephyrproject.org/4.1.0/build/dts/api/api.html#instance-based-apis),
|
||||
which extract the values from the `properties` of each instance of the [devicetree binding](#devicetree-bindings-yaml) from a user's keymap or [predefined use-case `.dtsi` files](#optional-defining-common-use-cases-for-the-behavior-dtsi) stored in `app/dts/behaviors/`.
|
||||
We illustrate this further by comparing the [`#define KP_INST(n)` from the hold-tap driver](#invoking-behavior_dt_inst_define) and the [`properties` of the hold-tap devicetree binding](#devicetree-bindings-yaml).
|
||||
The config structure instances should always be declared `const`
|
||||
|
||||
@@ -41,7 +41,7 @@ west build -b nice_nano_v2 -S zmk-usb-logging -- -DSHIELD="corne_left"
|
||||
|
||||
### Additional Config
|
||||
|
||||
Logging can be further configured using Kconfig described in [the Zephyr documentation](https://docs.zephyrproject.org/3.5.0/services/logging/index.html).
|
||||
Logging can be further configured using Kconfig described in [the Zephyr documentation](https://docs.zephyrproject.org/4.1.0/services/logging/index.html).
|
||||
For instance, setting `CONFIG_LOG_PROCESS_THREAD_STARTUP_DELAY_MS` to a large value such as `8000` might help catch issues that happen near keyboard
|
||||
boot, before you can connect to view the logs.
|
||||
|
||||
@@ -103,7 +103,7 @@ From there, you should see the various log messages from ZMK and Zephyr, dependi
|
||||
|
||||
Standard boards such as the nice!nano and Seeed Studio XIAO family have the necessary configuration for logging already added, however if you are developing your own standalone board you may wish to add the ability to use USB logging in the future.
|
||||
|
||||
To do so, you need to follow the upstream Zephyr [`cdc-acm-console` snippet requirements](https://docs.zephyrproject.org/3.5.0/snippets/cdc-acm-console/README.html#requirements) steps.
|
||||
To do so, you need to follow the upstream Zephyr [`cdc-acm-console` snippet requirements](https://docs.zephyrproject.org/4.1.0/snippets/cdc-acm-console/README.html#requirements) steps.
|
||||
|
||||
Usually, this just requires ensuring that the USB node has been tagged with the `zephyr_udc0` label, e.g.
|
||||
|
||||
|
||||
@@ -7,10 +7,10 @@ sidebar_label: FAQs
|
||||
|
||||
As a best-in-class RTOS, Zephyr™ brings many [benefits](https://www.zephyrproject.org/benefits) to ZMK, such as:
|
||||
|
||||
- A _single_ platform [supporting](https://docs.zephyrproject.org/3.5.0/boards/index.html) many architectures, processors and boards.
|
||||
- A _single_ platform [supporting](https://docs.zephyrproject.org/4.1.0/boards/index.html) many architectures, processors and boards.
|
||||
- Optimization for low-powered, small memory footprint devices.
|
||||
- Powerful hardware abstraction and configuration using [DeviceTree](https://docs.zephyrproject.org/3.5.0/build/dts/index.html) and [Kconfig](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html).
|
||||
- A BLE stack that periodically obtains [qualification](https://docs.zephyrproject.org/3.5.0/connectivity/bluetooth/bluetooth-qual.html) listings, making it easier for final products to obtain qualification from the Bluetooth® SIG.
|
||||
- Powerful hardware abstraction and configuration using [DeviceTree](https://docs.zephyrproject.org/4.1.0/build/dts/index.html) and [Kconfig](https://docs.zephyrproject.org/4.1.0/build/kconfig/index.html).
|
||||
- A BLE stack that periodically obtains [qualification](https://docs.zephyrproject.org/4.1.0/connectivity/bluetooth/bluetooth-qual.html) listings, making it easier for final products to obtain qualification from the Bluetooth® SIG.
|
||||
- Multi-processor support, which is critical for power efficiency in upcoming MCUs.
|
||||
- Permissive licensing with its Apache 2.0 open source [license](https://www.apache.org/licenses/LICENSE-2.0).
|
||||
- A buzzing developer [community](https://github.com/zephyrproject-rtos/zephyr) including many leading [embedded technology](https://www.zephyrproject.org/project-members) companies.
|
||||
@@ -37,7 +37,7 @@ ZMK uses the MIT [license](https://github.com/zmkfirmware/zmk/blob/main/LICENSE)
|
||||
|
||||
ZMK has the potential to run on any platform supported by Zephyr™. However, it’s impractical for the ZMK contributors to test all possible hardware.
|
||||
|
||||
The Zephyr™ [documentation](https://docs.zephyrproject.org/3.5.0/boards/index.html) describes which hardware is currently natively supported by the Zephyr™ platform. _Similar documentation covering which keyboards have been integrated into ZMK is currently being planned._
|
||||
The Zephyr™ [documentation](https://docs.zephyrproject.org/4.1.0/boards/index.html) describes which hardware is currently natively supported by the Zephyr™ platform. _Similar documentation covering which keyboards have been integrated into ZMK is currently being planned._
|
||||
|
||||
### Does ZMK compile for AVR?
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ sidebar_label: Modules
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
ZMK makes use of [Zephyr modules](https://docs.zephyrproject.org/3.5.0/develop/modules.html) to include additional source code or configuration files into its build. You can think of them as similar to plugins or themes. The most common uses of this feature are:
|
||||
ZMK makes use of [Zephyr modules](https://docs.zephyrproject.org/4.1.0/develop/modules.html) to include additional source code or configuration files into its build. You can think of them as similar to plugins or themes. The most common uses of this feature are:
|
||||
|
||||
- Building firmware for a keyboard external to ZMK's tree
|
||||
- Adding functionality to ZMK, such as a driver or a behavior
|
||||
@@ -27,11 +27,11 @@ The shift to using modules for keyboards is a relatively recent one, and not all
|
||||
|
||||
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:
|
||||
|
||||
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).
|
||||
1. Find the URL base (the parent URL) for the module and add it as an entry to the [remotes](https://docs.zephyrproject.org/4.1.0/develop/west/manifest.html#remotes).
|
||||
2. Add the module as an entry to the [projects](https://docs.zephyrproject.org/4.1.0/develop/west/manifest.html#projects).
|
||||
Aside from the mandatory `name`, `remote`, and the commonly used `revision` properties, take note of the `import` property under `projects`. Some modules may have other modules as dependencies. This property allows the specifying of an additional west manifest file found in the tree of the module, which will automatically import all dependencies.
|
||||
|
||||
For more information on `west.yml`, see [West Manifests](https://docs.zephyrproject.org/3.5.0/develop/west/manifest.html).
|
||||
For more information on `west.yml`, see [West Manifests](https://docs.zephyrproject.org/4.1.0/develop/west/manifest.html).
|
||||
|
||||
#### Examples
|
||||
|
||||
|
||||
@@ -176,7 +176,7 @@ To allow ZMK Studio to be used with a keyboard, the keyboard will need to have a
|
||||
- The [new shield guide](../development/hardware-integration/new-shield.mdx), informing you how to select a physical layout once defined
|
||||
- The corresponding [configuration page](../config/layout.md#physical-layout), for reference
|
||||
|
||||
To use the `studio-rpc-usb-uart` snippet, the keyboard also needs to be configured to allow CDC-ACM console snippets (this is also used for [USB logging](../development/usb-logging.mdx)). If your keyboard is a composite keyboard, consisting of an in-tree board and a shield, then you can skip this step as the board will already be configured properly. Relevant information on that can be found [in the Zephyr documentation](https://docs.zephyrproject.org/3.5.0/snippets/cdc-acm-console/README.html).
|
||||
To use the `studio-rpc-usb-uart` snippet, the keyboard also needs to be configured to allow CDC-ACM console snippets (this is also used for [USB logging](../development/usb-logging.mdx)). If your keyboard is a composite keyboard, consisting of an in-tree board and a shield, then you can skip this step as the board will already be configured properly. Relevant information on that can be found [in the Zephyr documentation](https://docs.zephyrproject.org/4.1.0/snippets/cdc-acm-console/README.html).
|
||||
|
||||
Firmware with ZMK Studio enabled require significantly more RAM. Some MCUs, such as the STM32F072 series, will require fine tuning of various settings in order to reduce the RAM consumption enough for a Studio enabled build to fit.
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ Below table lists major features/capabilities currently supported in ZMK, as wel
|
||||
| [Low Power Mode (VCC Shutoff) for Peripherals](keymaps/behaviors/power.md) | ✅ |
|
||||
| Improved Power Handling for Multiple Peripherals | 🚧 |
|
||||
| [Battery Level Reporting](features/battery.md) | ✅ |
|
||||
| [Support for a Wide Range of 32-bit Microcontrollers](https://docs.zephyrproject.org/3.5.0/boards/index.html) | ✅ |
|
||||
| [Support for a Wide Range of 32-bit Microcontrollers](https://docs.zephyrproject.org/4.1.0/boards/index.html) | ✅ |
|
||||
| Support for AVR/8-bit Chips | ❌ |
|
||||
|
||||
</Column>
|
||||
|
||||
@@ -76,6 +76,6 @@ The behaviors input processor uses a `compatible` property of `"zmk,input-proces
|
||||
|
||||
### User Properties
|
||||
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_KEY` for key/button events. The default value if omitted is `INPUT_EV_KEY`.
|
||||
- `codes` - The specific codes of the given type to capture, e.g. [button event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L180). This list must be the same length as the `bindings` property.
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_KEY` for key/button events. The default value if omitted is `INPUT_EV_KEY`.
|
||||
- `codes` - The specific codes of the given type to capture, e.g. [button event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L188). This list must be the same length as the `bindings` property.
|
||||
- `bindings` - The bindings to trigger when an event with the corresponding code is processed.
|
||||
|
||||
@@ -59,5 +59,5 @@ The code mapper input processor uses a `compatible` property of `"zmk,input-proc
|
||||
|
||||
### User Properties
|
||||
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events and `INPUT_EV_KEY` for key/button events.
|
||||
- `map` - The specific codes of the given type to map, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245). This list must be an even number of entries which is processed as a list of pairs of codes. The first code in the pair is the source code, and the second is the code to map it to.
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events and `INPUT_EV_KEY` for key/button events.
|
||||
- `map` - The specific codes of the given type to map, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L258). This list must be an even number of entries which is processed as a list of pairs of codes. The first code in the pair is the source code, and the second is the code to map it to.
|
||||
|
||||
@@ -73,5 +73,5 @@ The scaler input processor uses a `compatible` property of `"zmk,input-processor
|
||||
|
||||
### User Properties
|
||||
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events.
|
||||
- `codes` - The specific codes within the given type to scale, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to scale. Usually, this is `INPUT_EV_REL` for relative events.
|
||||
- `codes` - The specific codes within the given type to scale, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L258)
|
||||
|
||||
@@ -70,6 +70,6 @@ The transform input processor uses a `compatible` property of `"zmk,input-proces
|
||||
|
||||
### User Properties
|
||||
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to transform. Usually, this is `INPUT_EV_REL` for relative events.
|
||||
- `x-codes` - The specific X codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
|
||||
- `y-codes` - The specific Y codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v3.5.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L245)
|
||||
- `type` - The [type](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L25) of events to transform. Usually, this is `INPUT_EV_REL` for relative events.
|
||||
- `x-codes` - The specific X codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L258)
|
||||
- `y-codes` - The specific Y codes within the given type to transform, e.g. [relative event codes](https://github.com/zmkfirmware/zephyr/blob/v4.1.0%2Bzmk-fixes/include/zephyr/dt-bindings/input/input-event-codes.h#L258)
|
||||
|
||||
@@ -7,7 +7,7 @@ description: Troubleshooting issues when compiling ZMK firmware.
|
||||
## CMake Error
|
||||
|
||||
An error along the lines of `CMake Error at (zmk directory)/zephyr/cmake/generic_toolchain.cmake:64 (include): include could not find load file:` during firmware compilation indicates that the Zephyr Environment Variables are not properly defined.
|
||||
For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/3.5.0/build/zephyr_cmake_package.html).
|
||||
For more information, see [Zephyr's CMake Package](https://docs.zephyrproject.org/4.1.0/build/zephyr_cmake_package.html).
|
||||
|
||||
## West Build Errors
|
||||
|
||||
|
||||
@@ -77,7 +77,7 @@ For connectivity problems caused by hardware, please see [the appropriate sectio
|
||||
|
||||
Some devices and operating systems may have additional restrictions that they require be met before allowing a bluetooth peripheral to pair with them. If your keyboard is visible to your host but you are having issues trouble connecting or no input is registered, this might be the cause. Some of ZMK's [experimental bluetooth settings](../config/bluetooth.md) may suffice to resolve the issue. In particular:
|
||||
|
||||
- Disabling PHY 2Mbps ([`CONFIG_BT_CTLR_PHY_2M=n`](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_CTLR_PHY_2M)) helps to pair and connect for certain wireless chipset firmware versions, particularly on Windows (Realtek and Intel chips) and older Intel Macs with Broadcom chipsets.
|
||||
- Disabling PHY 2Mbps ([`CONFIG_BT_CTLR_PHY_2M=n`](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_BT_CTLR_PHY_2M)) helps to pair and connect for certain wireless chipset firmware versions, particularly on Windows (Realtek and Intel chips) and older Intel Macs with Broadcom chipsets.
|
||||
- Enabling passkey entry ([`CONFIG_ZMK_BLE_PASSKEY_ENTRY=y`](../config/bluetooth.md)) helps for certain Windows computers (work-managed ones in particular). This may also manifest in not sending keystrokes.
|
||||
|
||||
### Issues With Dual Boot Setups
|
||||
@@ -95,7 +95,7 @@ For the `nRF52840`, the flag to set to use the internal oscillator is:
|
||||
CONFIG_CLOCK_CONTROL_NRF_K32SRC_RC=y
|
||||
```
|
||||
|
||||
Other microcontrollers may have similar configuration options [found in the Zephyr documentation](https://docs.zephyrproject.org/3.5.0/search.html?q=CONFIG_CLOCK_CONTROL&check_keywords=yes&area=default). Do note that not all microcontrollers allow for the use of an internal oscillator, though.
|
||||
Other microcontrollers may have similar configuration options [found in the Zephyr documentation](https://docs.zephyrproject.org/4.1.0/search.html?q=CONFIG_CLOCK_CONTROL&check_keywords=yes&area=default). Do note that not all microcontrollers allow for the use of an internal oscillator, though.
|
||||
|
||||
## Issues While Connected
|
||||
|
||||
@@ -107,7 +107,7 @@ Some users may experience a poor connection between the keyboard and the host. T
|
||||
CONFIG_BT_CTLR_TX_PWR_PLUS_8=y
|
||||
```
|
||||
|
||||
For the `nRF52840`, the value `PLUS_8` can be set to any multiple of four between `MINUS_20` and `PLUS_8`. The default value for this config is `0`, but if you are having connection issues it is recommended to set it to `PLUS_8` because the power consumption difference is negligible. For more information on changing the transmit power of your BLE device, please refer to [the Zephyr docs.](https://docs.zephyrproject.org/3.5.0/kconfig.html#CONFIG_BT_CTLR_TX_PWR)
|
||||
For the `nRF52840`, the value `PLUS_8` can be set to any multiple of four between `MINUS_20` and `PLUS_8`. The default value for this config is `0`, but if you are having connection issues it is recommended to set it to `PLUS_8` because the power consumption difference is negligible. For more information on changing the transmit power of your BLE device, please refer to [the Zephyr docs.](https://docs.zephyrproject.org/4.1.0/kconfig.html#CONFIG_BT_CTLR_TX_PWR)
|
||||
|
||||
:::info
|
||||
This setting can also improve the connection strength between the keyboard halves for split keyboards.
|
||||
|
||||
@@ -157,6 +157,22 @@ module.exports = {
|
||||
"development/hardware-integration/soft-off-setup",
|
||||
"development/hardware-integration/pointing",
|
||||
"development/hardware-integration/battery",
|
||||
{
|
||||
type: "category",
|
||||
label: "Bootloader",
|
||||
link: {
|
||||
type: "doc",
|
||||
id: "development/hardware-integration/bootloader/index",
|
||||
},
|
||||
collapsed: true,
|
||||
items: [
|
||||
"development/hardware-integration/bootloader/adafruit-nrf52",
|
||||
"development/hardware-integration/bootloader/tinyuf2",
|
||||
"development/hardware-integration/bootloader/samd21-uf2",
|
||||
"development/hardware-integration/bootloader/rp2",
|
||||
"development/hardware-integration/bootloader/stm32",
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "category",
|
||||
label: "Lighting",
|
||||
|
||||
Reference in New Issue
Block a user