tgrosinger/zmk
1
0
Fork 0
Code Actions Packages
tgrosinger-keyboards
zmk/docs/blog/2024-02-09-zephyr-3-5.md
Nicolas Munnich 308d6bce6e
feat(docs): Improve the toolchain setup page (#2272) 
Split the toolchain setup into separate docker and native pages
and improve instructions to better refer to Zephyr docs in certain steps.
Also refactor to improve consistency and add virtualenv instructions.

---------

Co-authored-by: KemoNine <mcrosson@kemonine.info>
Co-authored-by: Cem Aksoylar <caksoylar@users.noreply.github.com>
2024-06-01 21:51:08 -07:00

144 lines
6.8 KiB
Markdown
Raw Permalink Blame History

---
title: "Zephyr 3.5 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/1995) to upgrade ZMK to [Zephyr 3.5](https://docs.zephyrproject.org/3.5.0/releases/release-notes-3.5.html)!
[petejohanson] did the upgrade work to adjust ZMK for the Zephyr changes:
- Add `west flash` support to all UF2 capable boards.
- Adjust for LVGL DTS/Kconfig changes
- Zephyr core API changes, including `CONTAINER_OF` work API changes, init priority/callback, and others
## 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.5 automatically, however if you created your user config a while ago, you may need to update it to reference our shared build configuration to leverage the correct Docker image.
1. Replace the contents of your `.github/workflows/build.yml` with:
```yaml
on: [push, pull_request, workflow_dispatch]
jobs:
build:
uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@main
```
1. If it doesn't exist already, add a new file to your repository named `build.yaml`:
```yaml
# This file generates the GitHub Actions matrix
# For simple board + shield combinations, add them
# to the top level board and shield arrays, for more
# control, add individual board + shield combinations to
# the `include` property, e.g:
#
# board: [ "nice_nano_v2" ]
# shield: [ "corne_left", "corne_right" ]
# include:
# - board: bdn9_rev2
# - board: nice_nano_v2
# shield: reviung41
#
---
```
and then update it as appropriate to build the right shields/boards for your configuration.
### 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.5 Docker image.
### Local Host Development
The following steps will get you building ZMK locally against Zephyr 3.5:
- Run the updated [toolchain installation](/docs/development/setup) steps, and once completed, remove the previously installed SDK version (optional, existing SDK should still work)
- Install the latest version of `west` by running `pip3 install --user --update west`.
- 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/1995/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.
### West Flash Support
If you have a custom board for a target that has a UF2 supporting bootloader, you can easily add support for
flashing via `west flash`. Note that using `west flash` isn't mandatory, it is merely a convenient way to automate copying to the mass storage device, which you can continue to do manually.
To add support, add a line to your board's `board.cmake` file like so:
```
include(${ZEPHYR_BASE}/boards/common/uf2.board.cmake)
```
### LVGL DTS/Kconfig Changes
Two items were changed for LVGL use for displays that may need adjusting for custom shields:
#### DPI Kconfig Rename
The old `LV_Z_DPI` Kconfig symbol was promoted to a Kconfig in upstream LVGL, and is now named `LV_DPI_DEF`. You
will need to replace this symbol in your board/shield's `Kconfig.defconfig` file.
#### SSD1306 OLED Inverse Refactor
Inverting black/white pixels has moved out of the Kconfig system and into a new DTS property. If you have a custom
shield that uses an SSD1306, you should:
- Remove any override for the `SSD1306_REVERSE_MODE` from your Kconfig files.
- Add the new `inversion-on;` boolean property to the SSD1306 node in your devicetree file.
### Maxim max17048 Sensor Driver
Upstream Zephyr has added a driver for the max17048 fuel gauge, but using the new [fuel gauge API](https://docs.zephyrproject.org/3.5.0/hardware/peripherals/fuel_gauge.html) that ZMK
does not yet consume. To avoid a conflict with the new upstream and keep our existing sensor driver, our driver has been renamed to be namespaced with a ZMK prefix. The following changes are needed for any boards using the driver:
- Change the `compatible` value for the node to be `zmk,maxim-17048`, e.g. `compatible = "zmk,maxim-max17048";`.
- If enabling the driver explicitly via Kconfig, rename `MAX17048` to the new `ZMK_MAX17048` in your `Kconfig.defconfig` or `<board>_defconfig` files.
## Upcoming Changes
Moving to Zephyr 3.5 will unblock several exciting efforts that were dependent on that Zephyr release.
### BLE Stability Improvements
Many users have reported various BLE issues with some hardware combinations, including challenges with updated
Intel drivers, and macOS general stability problems. The Zephyr 3.5 release includes many fixes for the BT host and controller portions that, combined with some small upcoming ZMK changes, have been reported to completely resolve previous issues. Further focused testing will immediately commence to fully verify the ZMK changes before
making them the default.
If you'd like to test those changes, enable `CONFIG_ZMK_BLE_EXPERIMENTAL_CONN=y` for your builds.
### Pointer Integration
The Zephyr 3.5 release includes a new [input subsystem](https://docs.zephyrproject.org/3.5.0/services/input/index.html) that we will be leveraging for our upcoming pointer support. The open PR for that work is now unblocked and further testing and code review will begin to work on getting that feature integrated into ZMK as well.
### Power Domains
Several power domain related changes are now available as well, which were a necessity for continued work on the improved peripheral power handling that's planned to supersede the existing "VCC cutoff" code that currently exists but causes problems for builds that include multiple powered peripherals like Displays + RGB.
## Thanks!
Thanks to all the testers who have helped verify ZMK functionality on the newer Zephyr version.
[petejohanson]: https://github.com/petejohanson
View Git Blame Copy Permalink