Peter Johanson
3 years ago
committed by
Pete Johanson
1 changed files with 219 additions and 0 deletions
@ -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