feat(blog): Add Zephyr 3.0 upgrade post.
This commit is contained in:
Peter Johanson
Pete Johanson
parent
f4fb5c6fba
commit
b4db1b893b
1 changed files with 219 additions and 0 deletions
219
docs/blog/2022-04-02-zephyr-3-0.md
Normal file
219
docs/blog/2022-04-02-zephyr-3-0.md
Normal file
|
|
@ -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 a new issue