zmk/docs/blog/2022-04-02-zephyr-3-0.md

---
title: "Zephyr 3.0 Update"
author: Pete Johanson
author_title: Project Creator
author_url: https://gitlab.com/petejohanson
author_image_url: https://www.gravatar.com/avatar/2001ceff7e9dc753cf96fcb2e6f41110
tags: [firmware, zephyr, core]
---

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
- Locate and delete the lines for the DTS output step, which is no longer needed:

  ```yaml
  - name: ${{ steps.variables.outputs.display-name }} DTS File
    if: ${{ always() }}
    run: |
      if [ -f "build/zephyr/${{ matrix.board }}.pre.tmp" ]; then cat -n build/zephyr/${{ matrix.board }}.pre.tmp; fi
      if [ -f "build/zephyr/zephyr.dts" ]; then cat -n build/zephyr/zephyr.dts; fi
  ```

:::note

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) 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.

### RGB Underglow

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:

```dts
led_strip: ws2812@0 {
  compatible = "worldsemi,ws2812-spi";

  /* SPI */
  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:

```dts
&pro_micro_i2c {
  status = "okay";

  oled: ssd1306@3c {
    compatible = "solomon,ssd1306fb";
    reg = <0x3c>;
    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:

```dts
/ {
  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:

```dts
&usbd {
  status = "okay";
  cdc_acm_uart: cdc_acm_uart {
    compatible = "zephyr,cdc-acm-uart";
  };
};
```

Then, an additional `chosen` node (near the top of the file) will mark the CDC ACM device as the console:

```dts
/ {
  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:

```ini
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:

```dts
&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.

[petejohanson]: https://github.com/petejohanson

## Article Updates

- 12/2023: Removed the deprecated `label` property from code snippets.