Zephyr 3.0 Update

I'm happy to announce that we have completed the work to upgrade ZMK to Zephyr 3.0!

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:

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

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:

&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:

/ {
  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";
  };
};

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.

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

Article Updates

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