feat(blog): Add Zephyr 3.0 upgrade post.
This commit is contained in:
Peter Johanson
Pete Johanson
parent
f4fb5c6fba
commit
b4db1b893b
|
|
@ -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
|
||||
Loading…
Reference in New Issue