Skip to main content
BlogNewsTop News

ZMK Firmware Update

By September 7, 2021No Comments

Written by Pete Johanson, ZMK Project Creator

This blog originally ran on Pete’s website. For more content like this, click here

I’m happy to announce that we have completed the work to upgrade ZMK to Zephyr 2.5!

A big part of this work was some major refactors and improvements by innovaker to our zmk-docker Docker image and GH Actions automation.

  • Faster build times with improved caching.
  • Integration tests which automatically verify new images.
  • PRs to the repo now build properly and run the tests as well.
  • Build images for multiple target architectures, e.g. zmk-build-riscv64, all in parallel.
  • Nightly builds to be sure we’re pulling in the latest OS/package updates, to ensure we keep our images up to date, address any reported vulnerabilities, etc.
  • Faster upgrade paths for future Zephyr SDK and Zephyr versions.

In addition, petejohanson did the upgrade work to adjust ZMK for the Zephyr changes.

  • Updated to newer devicetree/driver Zephyr API
  • Adjustment for Zephyr pinmux changes
  • Fixes for power management, LVGL, and 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 2.5 automatically, and should work, fine as is. However, to upgrade to the newer Docker image, you should:

  • Open .github/workflows/build.yml in your editor/IDE
  • Change zmkfirmware/zmk-build-arm:2.4 to zmkfirmware/zmk-build-arm:2.5 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 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 2.5 Docker image.

Local Host Development

The following steps will get you building ZMK locally against Zephyr 2.5:

  • 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!


Thanks again to innovaker for all the hard work, and to all the testers who have helped verify ZMK functionality on the newer Zephyr version.

Zephyr Project