I'm happy to announce that we have completed the [work](https://github.com/zmkfirmware/zmk/pull/1143) to upgrade ZMK to [Zephyr 3.0](https://docs.zephyrproject.org/3.0.0/releases/release-notes-3.0.html)!
[petejohanson] did the upgrade work to adjust ZMK for the Zephyr changes.
- Moving to Zephyr's UF2 build integration that was submitted upstream by [petejohanson]
- Additional `color-mapping` property needed for ws2812 LED strep devicetree nodes
- Zephyr core API changes, including delayed work, USB/HID
- Adjust for pinctrl changes on stm32
- Fixes for power management and log formatter changes
## Getting The Changes
Use the following steps to update to the latest tooling in order to properly use the new ZMK changes:
### User Config Repositories Using GitHub Actions
Existing user config repositories using Github Actions to build will pull down Zephyr 3.0 automatically, however to build properly, the repository needs to be updated to use the `stable` Docker image tag for the build:
- Open `.github/workflows/build.yml` in your editor/IDE
- Change `zmkfirmware/zmk-build-arm:2.5` to `zmkfirmware/zmk-build-arm:stable` wherever it is found
If you created your user config repository a while ago, you may find that your `build.yml` file instead references
a `zephyr-west-action-arm` custom GitHub Action instead. In this case, the upgrade is not as direct. We suggest that
instead you [re-create your config repository](/docs/user-setup) to get an updated setup using the new automation
approach.
:::
### 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 3.0 Docker image.
### Local Host Development
The following steps will get you building ZMK locally against Zephyr 3.0:
- Run the updated [toolchain installation](/docs/development/setup#toolchain-installation) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
- 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!
## Board/Shield Changes
The following changes have [already been completed](https://github.com/zmkfirmware/zmk/pull/1143/commits) for all boards/shields in ZMK `main` branch. For existing or new PRs, or out of tree boards, the following changes are necessary to properly work with the latest changes.
Zephyr's WS2812 `led_strip` driver added a new required property. When adding [underglow](/docs/features/underglow#adding-rgb-underglow-to-a-board) to a board, you now must also add the additional include `#include <dt-bindings/led/led.h>` at the top of your devicetree file, and add a `color-mapping` property like:
reg = <0>; /* ignored, but necessary for SPI bindings */
spi-max-frequency = <4000000>;
/* WS2812 */
chain-length = <10>; /* number of LEDs */
spi-one-frame = <0x70>;
spi-zero-frame = <0x40>;
color-mapping = <LED_COLOR_ID_GREEN
LED_COLOR_ID_RED
LED_COLOR_ID_BLUE>;
};
```
:::note
Standard WS2812 LEDs use a wire protocol where the bits for the colors green, red, and blue values are sent in that order.
If your board/shield uses LEDs that require the data sent in a different order, the `color-mapping` property ordering should be changed to match.
:::
### Display Selection
Zephyr moved to using a `chosen` node named `zephyr,display` to select the display device to be used with LVGL, the underlying display library we use.
For example, for a shield with:
```
&pro_micro_i2c {
status = "okay";
oled: ssd1306@3c {
compatible = "solomon,ssd1306fb";
reg = <0x3c>;
label = "SSD1306";
width = <128>;
height = <32>;
segment-offset = <0>;
page-offset = <0>;
display-offset = <0>;
multiplex-ratio = <31>;
com-invdir;
segment-remap;
com-sequential;
prechargep = <0x22>;
};
};
```
You would add a `chosen` node like:
```
/ {
chosen {
zephyr,display = &oled;
};
};
```
### USB Logging
Zephyr unified the way the console/logging device is selected, removing the hacks that special-cased the USB CDC ACM output.
Now, the CDC ACM device is configured in the devicetree as well. To ensure that USB logging properly works with custom board definitions,
two sections of the `<board>.dts` file need updating.
Underneath the USB device, add the CDC ACM node:
```
&usbd {
status = "okay";
cdc_acm_uart: cdc_acm_uart {
compatible = "zephyr,cdc-acm-uart";
label = "CDC_ACM_0";
};
};
```
Then, an additional `chosen` node (near the top of the file) will mark the CDC ACM device as the console:
```
/ {
chosen {
...
zephyr,console = &cdc_acm_uart;
};
...
};
```
### UF2 Builds
Previously, to get ZMK to build a UF2 image to flash to a given board required adding a `CMakeLists.txt` file that added a custom post build command.
Now, the only thing necessary to have Zephyr build a UF2 is to add the following to your `<board>_defconfig` file:
```
CONFIG_BUILD_OUTPUT_UF2=y
```
If updating an existing board, be sure to remove the previous `CMakeLists.txt` file to avoid generating the UF2 twice during a `west build`.
For more details on the implementation, see [zephyr#31066](https://github.com/zephyrproject-rtos/zephyr/pull/31066).
### STM32 Clock Configuration
Clock configuration moved to devicetree as well, out of the Kconfig files. Here is a sample config for a board that uses the HSI for the PLL source:
```
&clk_hsi {
status = "okay";
};
&pll {
prediv = <1>;
mul = <12>;
clocks = <&clk_hsi>;
status = "okay";
};
&rcc {
clocks = <&pll>;
clock-frequency = <DT_FREQ_M(72)>;
ahb-prescaler = <1>;
apb1-prescaler = <2>;
};
```
After adding the nodes, be sure to remove the clock/PLL related configuration from the `<board>_defconfig` file.
## Seeeduino XIAO
The Seeed(uino) XIAO has gained in popularity for use on smaller boards, and gained more traction with the release of the new XIAO BLE board,
powered by the popular nRF52840 SoC. As part of the 3.0 update, we've also more fully integrated the XIAO and XIAO BLE to make it easier to
build keyboard (shields) using either controller.
## Future Hardware
One of the exciting items that's one step closer as part of this work is [support for Raspberry Pi Pico/RP2040](https://github.com/zmkfirmware/zmk/issues/1085).
With Zephyr 3.0 merged, this start the process for getting those controllers/chips supported by ZMK. Follow the issue to keep track of progress.
This will also enable us to support the XIAO compatible Adafruit Qt Py RP2040 and XIAO RP2040.
## Thanks!
Thanks to all the testers who have helped verify ZMK functionality on the newer Zephyr version.
