From b4db1b893be1f51476a44b8ec8bd36ab6cbc3a0f Mon Sep 17 00:00:00 2001 From: Peter Johanson Date: Wed, 9 Mar 2022 04:44:20 +0000 Subject: [PATCH] feat(blog): Add Zephyr 3.0 upgrade post. --- docs/blog/2022-04-02-zephyr-3-0.md | 219 +++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 docs/blog/2022-04-02-zephyr-3-0.md diff --git a/docs/blog/2022-04-02-zephyr-3-0.md b/docs/blog/2022-04-02-zephyr-3-0.md new file mode 100644 index 00000000..19785790 --- /dev/null +++ b/docs/blog/2022-04-02-zephyr-3-0.md @@ -0,0 +1,219 @@ +--- +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 + +:::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#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. + +### 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 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 = ; +}; +``` + +:::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 `.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 `_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 = ; + ahb-prescaler = <1>; + apb1-prescaler = <2>; +}; +``` + +After adding the nodes, be sure to remove the clock/PLL related configuration from the `_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