feat(blog): Add Zephyr 3.0 upgrade post.

3 years ago · b4db1b893b
1 changed files with 219 additions and 0 deletions
--- a/docs/blog/2022-04-02-zephyr-3-0.md
+++ b/docs/blog/2022-04-02-zephyr-3-0.md
@ -0,0 +1,219 @@
				@@ -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 = <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>;
+    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](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 = <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