3 posts tagged with "core"

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
  

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";
  label = "WS2812";

  /* 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>;
};

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.

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.

As preparation for completing the work to upgrade ZMK to Zephyr 3.0, users with user config repositories who wish to avoid future build failures with their GitHub Actions workflows can take steps to adjust their repositories now.

GitHub Actions needs to use our latest Docker image to ensure continued compatibility with the ZMK codebase on Zephyr 3.0 (and beyond). You should:

• 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

Once the changes are committed and pushed, the build will run as expected.

A future blog post will outline the complete Zephyr 3.0 changes once that work is finalized.

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

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

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.