Zephyr 4.1 is a large leap forward from our previous version of 3.5, featuring:

• Support for lots of new SoCs, boards, and shields, such as the WCH CH32V003, the Raspberry Pi Pico 2, and many many more.
• Hardware Model V2 (HWMv2), providing better support for SoCs which have multiple cores on the same chip, such as the nRF5340.
• Lots of new drivers for chips such as the nPM1300.

This was a very large undertaking, and a big congratulations and thanks to petejohanson is due for all of his hard work in making this possible.

After we have verified functionality, ironed out any major bugs, and given any third party module maintainers time to update their code, we will be releasing ZMK v0.4 as the first version to include this Zephyr version update.

All out-of-tree keyboards will need to be updated to use HWMv2. If you maintain such a keyboard, you can find instructions on doing so below.

Switching To the Previous Release​

Some readers may be coming here because the above changes have broken their builds. ZMK uses a formal release process that allows users to build against a specific release, instead of following the unstable/development version found in the main branch. However, since this is a relatively new process, many users may still be tracking main.

For all users, except those willing to accept periodic breaks they need to track down, we highly recommend pinning your ZMK version. Doing so will allow you to avoid any issues related to the Zephyr upgrade, and allow you to choose when to upgrade to a future ZMK release when you are ready.

Getting The Changes​

User Config Repositories Using GitHub Actions​

Existing user repositories that have revision: main in their west.yml will receive the changes automatically when rebuilding.

Any user repositories created on or after 2025-07-03 are currently pinned to the most recent ZMK release. You will need to change over to main to get these changes immediately, or wait for v0.4 and upgrade your version then. See the recent blog post on pinning ZMK versions for more information.

Likewise, if you are currently on main but do not wish to upgrade yet, please pin your ZMK version to v0.3 by following the instructions in said blog post.

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 4.1 Docker image.

Local Host Development​

The following steps will get you building ZMK locally against Zephyr 4.1:

• Run the updated toolchain installation 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 --upgrade west in a virtual environment, or add the --user flag if west is installed globally: pip3 install --user --upgrade 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
• Run west packages pip --install to update required Python packages

From there, you should be ready to build as normal!

ZMK Board Variant​

The new Zephyr version includes a standard mechanism for extending boards found in Zephyr (like the Seeeduino XIAO, or Raspberry Pi Pico) with new variants that include additional configuration/defaults that are relevant to the application. This also means the original "stock" board can still be used as is, if consumers don't want to use those customizations for any reason.

As a result, all board definitions found in the ZMK tree now must be used with a zmk variant. For example, the previous board ID of adv360pro_left would now be adv360pro_left/nrf52840/zmk, which can be shortened to adv360pro_left//zmk since there's only one SoC on the board.

Board Revisions​

As part of this change, ZMK is now using board/shield revisions, rather than duplicate board/shield definitions. This means that instead of having e.g. nice_nano, and nice_nano_v2, we only have nice_nano, which by default points to the 2.0.0 revision. To point to the original Nice!Nano V1, you would need to use nice_nano@1.0.0 where you would have previously used nice_nano. Of course, you could also put nice_nano@2.0.0 if you wished to make that explicit, instead of merely replacing nice_nano_v2 with nice_nano. Some boards, such as the nrfmicro, also have additional board qualifiers such as the choice between multiple SoCs. Board qualifiers must always be specified, and do not have defaults. See Zephyr's overview for more information on board qualifiers. The below table provides an overview of some of the differences in in-tree boards we have in ZMK, and how they are selected in the new build system. The shorthand shows the minimum needed to build with a specific board, taking into account defaults.

• nice!nano (nice_nano)
  • nice_nano -> nice_nano@1.0.0 (short: nice_nano@1)
  • nice_nano_v2 -> nice_nano@2.0.0 (short: nice_nano)
• nRFMicro (nrfmicro/nrf52840)
  • nrfmicro_11 -> nrfmicro@1.1.0/nrf52840 (short: nrfmicro@1.1/nrf52840)
  • nrfmicro_11_flipped -> nrfmicro@1.1.0/nrf52840/flipped (short: nrfmicro@1.1/nrf52840/flipped)
  • nrfmicro_13 -> nrfmicro@1.3.0/nrf52840 (short: nrfmicro/nrf52840)
  • nrfmicro_13_52833 -> nrfmicro@1.3.0/nrf52833 (short: nrfmicro/nrf52833)
• Mikoto (mikoto)
  • mikoto -> mikoto@5.20.0 (short: mikoto)
  • mikoto@6.1 -> mikoto@6.1.0 (short: mikoto@6)
  • mikoto@7.2 -> mikoto@7.2.0 (short: mikoto@7)
• XIAO RP2040 (xiao_rp2040)
  • seeeduino_xiao_rp2040 -> xiao_rp2040
• XIAO nRF52840/BLE (xiao_ble)
  • seeeduino_xiao_ble -> xiao_ble
• BT60 (bt60)
  • bt60_v1 -> bt60@1.0.0
  • bt60_v2 -> bt60@2.0.0
  • bt60_hs -> bt60_hs
• Planck (planck)
  • planck_rev6 -> planck
• BDN9 (bdn9)
  • bdn9_rev2 -> bdn9
• Ferris Rev2 (ferris)
  • ferris_rev02 -> ferris@2.0.0 (short: ferris)
• Corne-ish Zen (corneish_zen)
  • corneish_zen_v2_left -> corneish_zen_left@2.0.0 (short: corneish_zen_left)
  • corneish_zen_v2_right -> corneish_zen_right@2.0.0 (short: corneish_zen_right)
  • corneish_zen_v1_left -> corneish_zen_left@1.0.0 (short: corneish_zen_left@1)
  • corneish_zen_v1_right -> corneish_zen_right@1.0.0 (short: corneish_zen_right@1)

The boards above are those which have changed in ZMK's tree, with the addition of the very popular XIAO series. For other boards in Zephyr's tree, please refer to the Zephyr documentation or source files directly.

Moving To HWMv2​

The move to HWMv2 has already been completed for all boards in ZMK's main branch. For out-of-tree boards, those need to be converted using either an automated script provided by the Zephyr project, or manually.

Board Upgrade Script​

The Zephyr project provides a script to automate updating a board to HWMv2. To run the script, you'll need to have a local development setup ready to use. You'll need to ensure you've updated to the new ZMK version and run west update to ensure you've got the new Zephyr version with the script available.

The following parameters are relevant for out-of-tree boards:

• --board-root </the/path/to/the/module/ -- the full path to the module directory that contains a boards/ directory, e.g. /home/peter/git/my-zmk-module/.
• -b <board_id> -- The board ID to update, e.g. tenbit.
• -v <vendor_id> -- The vendor for the board, this should be a vendor ID, or designer nickname.
• -g <group_id> -- The name of the group directory under which to place the new board files. Typically this will match the vendor ID.
• -s <soc_id> -- The SoC identifier, e.g. nrf52840, rp2040, stm32f411xe.

For example:

$ python3 zmk/zephyr/scripts/utils/board_v1_to_v2.py \
    --board-root my-zmk-module -b my_board \
    -v my_company -g my_group -s nrf52840

Migrating an Out-Of-Tree Board Manually​

The following steps can be completed manually if you encounter issues with the upgrade script, or don't have a local development setup available.

Vendor Directory​

Boards no longer need to live in a parent directory named after the architecture of the board (.e.g boards/arm), and should instead be placed in a vendor/designer named directory (e.g. boards/my_company).

Write a board.yml​

In your board's folder, next to other files such as <your_board>.dts, add a file called board.yml. This file should have the following structure:

board:
  name: <board-name>
  vendor: <board-vendor>
  revision:
    format: <major.minor.patch|letter|number|custom>
    default: <default-revision-value>
    exact: <true|false>
    revisions:
    - name: <revA>
    - name: <revB>
      ...
  socs:
  - name: <soc-1>
    variants:
    - name: <variant-1>
    - name: <variant-2>
      variants:
      - name: <sub-variant-2-1>
        ...
  - name: <soc-2>
    ...

In the above:

• <board-name> is the name of the board as specified when selecting a build target, such as nice_nano.
• <vendor-name> is the name of the board's vendor, such as nicekeyboards. If you are an individual, rather than acting as an organization, please use your name/online id/similar (e.g. zhiayang in the case of the mikoto). This value should match the vendor directory name that the board definition folder is placed in the previous section.
• revision defines any board revisions. See Zephyr's overview for more information on board revisions. If your board does not have any revisions, you can omit this section.
• socs lists all SoCs that your board could have, e.g. nrf52840 or stm32f072xb. If your board only has one SoC available and no variants, then the SoC can be omitted when selecting a build target, but must still be specified in this file. For an understanding of SoC variants, refer to the Zephyr documentation.

If you need to define multiple boards in the same board.yml, such as for a split keyboard, you can do so like this:

boards:
 - name: <board_name_1>
   ...
 - name: <board_name_2>
   ...

Revision adjustments​

If, as a side effect of adding revisions, you renamed the board (e.g. ferris_rev02 -> ferris), you should adjust the other places where the board name was previously -- <board>.zmk.yml and <board>.yaml. You may also need to rearrange/consolidate other Kconfig flags and devicetree nodes. See the Zephyr documentation for more details.

Adjust Kconfig files​

Kconfig.<board>​

Previously, your board folder will have had a file named Kconfig.board. This should be renamed to Kconfig.<board>, where <board> is the board name given in board.yml. The contents of this file will previously look something like this:

config BOARD_FERRIS
    bool "Ferris rev 0.2"
    depends on SOC_STM32F072XB

Remove the bool and change the depends on to a select:

config BOARD_FERRIS
    select SOC_STM32F072XB

If you had multiple boards specified for different SoCs, you should consolidate them to one:

config BOARD_NRFMICRO
    select SOC_NRF52840_QIAA if BOARD_NRFMICRO_NRF52840
    select SOC_NRF52840_QIAA if BOARD_NRFMICRO_NRF52840_FLIPPED
    select SOC_NRF52833_QIAA if BOARD_NRFMICRO_NRF52833

<board>_defconfig​

Previously, this file was used to select the board and SOC with Kconfig flags. All such selections should be removed from this file. For example, all of the below flags should be removed:

CONFIG_SOC_SERIES_NRF52X=y
CONFIG_SOC_NRF52833_QIAA=y
CONFIG_SOC_NRF52840_QIAA=y
CONFIG_BOARD_<BOARDNAME>=y
CONFIG_SOC_SERIES_STM32F0X=y
CONFIG_SOC_STM32F072XB=y

DeviceTree changes​

For most boards, aside from rearranging due to moving to revisions, there should be no changes necessary to the devicetree nodes. However, if your board makes use of upstream Zephyr drivers, these may have been renamed (e.g. Ferris' microchip,mcp230xx has been changed to microchip,mcp23017).

General Board/Shield Changes​

A few other changes, unrelated to the HWMv2 move, may impact out-of-tree boards/shields:

Bootloader Setup​

With the version bump, the previous method to enable &bootloader has been disabled. Instead, ZMK is introducing boot retention, which as a side effect also enables &bootloader for SoCs which previously didn't work with said behavior, such as the STM32F072. To set up boot retention for your board, please read through the dedicated page.

nRF52840 NFC Pins as GPIO​

If your board or shield is using either of the nRF52840 NFC pins, as is often done with the XIAO nRF52840, you'll need to perform an additional update.

Remove deprecated Kconfig symbol​

Previously, using those pins required enabling CONFIG_NFCT_PINS_AS_GPIOS=y in some Kconfig file. That Kconfig symbol has been removed, so remove any use of that Kconfig symbol from your board/shield.

Set up NFC GPIO devicetree​

The following should be added to the board or shield's devicetree, e.g. in <board>.dtsi or in a board specific shield overlay file like <my_shield>/boards/xiao_ble.overlay:

&uicr {
        nfct-pins-as-gpios;
};

nRF52840 DC/DC Modes​

For boards with the necessary additional hardware to enable DC/DC modes for the reg0 and/or reg1 power stages, the configuration to enable DC/DC has also moved out of Kconfig and into devicetree.

Remove Kconfig Settings​

Usually, the DC/DC modes were enabled in the board's Kconfig.defconfig file, looking like:

config BOARD_ENABLE_DCDC
    bool "Enable DCDC mode"
    select SOC_DCDC_NRF52X
    default y
    depends on (BOARD_MY_BOARD)

config BOARD_ENABLE_DCDC_HV
    bool "High voltage DCDC converter"
    select SOC_DCDC_NRF52X_HV
    default n
    depends on (BOARD_MY_BOARD)

Remove the lines from the file that look like above, or remove the Kconfig.defconfig file entirely if that is the only content contained therein.

Add DC/DC setup to devicetree​

The DC/DC mode is now enabled for the &reg0 and &reg1 devicetree nodes, depending on which stage you want to use in that mode.

For a high voltage board, where the necessary inductor is connected to the DCCH pin, enable the following in the board's .dts file:

&reg0 {
    status = "okay";
};

For both high voltage and non-HV boards, where the necessary inductor is connected to the DCC pin, enable the following in the board's .dts file:

&reg1 {
    regulator-initial-mode = <NRF5X_REG_MODE_DCDC>;
};

RP2040 Board Adjustments​

A few small tweaks are required for custom/out-of-tree RP2040 based boards:

Clock control​

RP2040 boards now require clock control enabled to use several peripherals, including USB.

The following should be added to the board's <board>_defconfig file:

CONFIG_CLOCK_CONTROL=y

Base devicetree changes​

The location for the base set of devicetree these boards need to include has changed. In the board's <board>.dts file, replace:

#include <rpi_pico/rp2040.dtsi>

with

#include <raspberrypi/rpi_pico/rp2040.dtsi>

Next, any fixed clock node needs to be removed:

    xtal_clk: xtal-clk {
        compatible = "fixed-clock";
        clock-frequency = <12000000>;
        #clock-cells = <0>;
    };

And the following added, to set up the core device hardware properly:

&timer {
    status = "okay";
};

&rtc {
    clocks = <&clocks RPI_PICO_CLKID_CLK_RTC>;
    status = "okay";
};

&vreg {
    regulator-always-on;
    regulator-allowed-modes = <REGULATOR_RPI_PICO_MODE_NORMAL>;
};

Lastly, an additional property must be added to the chosen node to supplement the existing properties there:

/ {
    chosen {
        ...
        zephyr,flash-controller = &ssi;
        ...
    };
};

LED Strip Kconfig Changes​

If your board or shield uses RGB underglow, the following Kconfig flag which was previously enabled should now be removed:

CONFIG_WS2812_STRIP=y

If this is the only SPI device your shield uses, also remove the Kconfig flag enabling SPI (assuming it is present). It will be automatically enabled.

Cirque Pinnacle Input Driver​

Upstream Zephyr now contains a driver for the popular small Cirque Pinnacle trackpads. To transition to the new upstream driver, instead of the out-of-tree module, some small adjustments are needed.

Remove module references​

Often, the out-of-tree module is referenced from the west.yml in user's repos. The entry pointing to the module should be removed from your projects list there. If building locally, be sure you are not adding the module directory to the ZMK_EXTRA_MODULES CMake parameter.

Devicetree changes​

The properties for the upstream driver can be found here. The following changes are required when migrating:

• The dr-gpios property in out-of-tree module is named data-ready-gpios, so renaming the property is required.
• Instead of an opt-out no-taps property to disable taps, you can enable primary taps with primary-tap-enable.
• The sleep property is now named sleep-mode-enable.
• Use invert-x/invert-y instead of x-invert/y-invert.
• Use swap-xy instead of rotate-90.

Other Changes​

LVGL was updated to 9.3.0, which comes with breaking API changes. If you are using custom widgets or displays from a module, these will likely need fixing. See the LVGL changelog for details.

Board Extensions​

Zephyr has formalized the concept of "board extensions", allowing modules/applications to extend boards that are defined elsewhere. If using a board from the upstream Zephyr project that ZMK hasn't yet extended with default settings, e.g. enabling the CONFIG_ZMK_USB symbol, users can add their own extensions to their modules under the <board_root>/boards/extensions/<board_dir_name>/ directory. See https://github.com/zmkfirmware/zmk/tree/main/app/boards/extensions for the extensions that ZMK has added.

Zephyr Upgrade Instructions​

Should you encounter any other issues with custom or out-of-tree Zephyr code, consider consulting the following Zephyr upgrade guides:

• 3.7 Upgrade
• 4.1 Upgrade

Thanks!​

Thanks to all the testers who have helped verify ZMK functionality on the newer Zephyr version.

Future​

Once a ZMK version based on Zephyr 4.1 is released, we'll be working towards updating Zephyr even further, to try to catch up with the latest actual Zephyr release. This will likely mean a jump to the upcoming Zephyr 4.3. As part of that work, some other semi-disruptive changes will be required, including:

• Removing ZMK's use of the deprecated, and now removed, kscan APIs in favor of the newer matrix input API. ZMK already supports the matrix input API, but has not yet converted our existing drivers to that API. Advanced users looking to test can try leveraging the upstream Zephyr drivers today to test that functionality, but that is not officially supported and is likely to have bugs or untested side effects.
• Move the new USB stack, that includes better High-Speed USB support.

ZMK Versioning -- The 'what' and the 'why'​

Around 6 months ago, ZMK began using versioning. Prior to this point, all ZMK users ran their firmware off of main. This meant that users would always get the latest and greatest changes whenever they built new firmware, but on occasion there would be breaking changes in main that resulted in user confusion.

Avoiding this user confusion became a limiting factor when it came to making changes. Zephyr, the RTOS that ZMK is based off of, made some breaking changes in version 3.6. Hence ZMK has been stuck on Zephyr 3.5 for over 1.5 years, while Zephyr has already moved on to version 4.1. Asking when ZMK will upgrade is a frequent question we get asked, as the new version comes with plenty of improvements and drivers for newer, exciting hardware.

With versioning now in place, users can pin their ZMK configuration to a particular version. This prevents sudden breaking changes from happening without user opt-in and frees ZMK contributors to make breaking changes more frequently, as is necessary.

ZMK's Versioning System​

ZMK follows the Semantic Versioning standard. Versions are vX.Y.Z. ZMK uses release branches and tags: Every major or minor version bump, a new branch and tag are created. The tag points to the latest patch version. For example, when releasing v0.2.0 the branch v0.2-branch and tag v0.2 were created. When patches are made, such as for v0.2.1, the branch and tag are updated to point to v0.2.1 instead of v0.2.0. This way, users can receive non-breaking security and bug fixes without needing to bump their version.

Whenever ZMK releases a major version with breaking changes, a proper changelog will be provided detailing the major changes from the previous version, along with clear instructions on how to upgrade and fix any breaking changes.

To Pin or Not To Pin​

For casual users of ZMK, pinning your version is recommended. Unpinned ZMK configurations are mainly suitable for those more heavily involved or interested in ZMK development. Moving forward, if you are on the main branch of ZMK you will be considered a (highly valued) tester, rather than a user.

To ensure that you still update your ZMK version regularly and get the latest and greatest features that interest you, I would recommend setting up notifications about new releases. You can do so on the GitHub repository:

How To Pin Your ZMK Version​

To pin your ZMK version, you need to edit two files:

West Manifest​

You need to edit the config/west.yml file in your zmk-config repository. The config folder also contains your keymaps, and is located next to the build.yaml file defining which keyboards are built in the first place.

Your west.yml should look something like this (example without modules shown for simplicity):

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: main
      import: app/west.yml
  self:
    path: config

Simply edit the line revision to point to the release tag instead of main. At the time of writing, the latest release is v0.2, making your west.yml look something like this:

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: v0.2
      import: app/west.yml
  self:
    path: config

See that main has changed to v0.2 on the 8th line.

GitHub Action​

You need to edit .github/workflows/build.yml in your zmk-config. Again, we are simply replacing main with the latest release tag (v0.2 at time of writing):

name: Build ZMK firmware
on: [push, pull_request, workflow_dispatch]

jobs:
  build:
    uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@main

Your file's contents should look identical to the above. Replace with the below:

name: Build ZMK firmware
on: [push, pull_request, workflow_dispatch]

jobs:
  build:
    uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@v0.2

The change occurred on the last line.

Version Bumping​

If in the future you wish to upgrade your ZMK's version, simply change the tag in both of these files. For example, change from v0.1 to v0.2.

The following contributors were able to attend the sync:

• petejohanson
• caksoylar
• nmunnich

joelspadin was also able to comment on the meeting notes after the meeting. The notes have been adjusted accordingly.

Meeting Notes​

Meeting Purpose​

• Purpose of meeting is to sync up, discuss blockers, talk about big picture work.
• Meeting notes should be published on the webpage, while the meetings themselves are private.

Pete's Summary​

• Starting a new job Mon. 2025-03-03. Reduced time for ZMK, but more freedom to work on what Pete wants/ZMK needs.
• Two main ZMK-contracts need to be finished:
  • Pointer work. Basically good to go, just needs 2721 to be tested and verified as as fix. Then ZMK release v0.2 will happen. (This has already happened at time of publishing these notes)
  • Wired split work. Separated into parts:
    • UART full duplex, PR 2766. What's there seems very solid, barring some final touchups. Should have v0.2 released prior to merging this. (This has already happened at time of publishing these notes)
    • Half-duplex with a single wire. To be a separate PR, but framework should be good for when that happens. To work on after UART full duplex is merged.
    • Runtime dynamic switching between wired and wireless split using a GPIO as sense pin for wired.
• After contracts finish, look at versioning again. Better documentation, defaults, workflow improvements, etc.
• More Studio work is also on the cards. Studio work will continue, but slowly.
  • Hoping for help from community around UI/UX, in particular clarity around saving edited keymaps would be good.
  • Want to add runtime property modification next, allowing for e.g. changing hold-tap flavors in Studio.
• Investigate zmk-cli a bit; Pete has not investigated this enough and wants to get a solid overview of it.

Nick's summary:​

• Trying to make combo PR feasible (allows combo triggers inside behaviors, enabling e.g. tap-only combos)
  • Adding behavior_state_changed event has a precursor (see 573, 532)
    • Requires deleting ZMK_BEHAVIOR_TRANSPARENT
    • Requires some refactoring/investigating of sensors/encoders, as they rely on ZMK_BEHAVIOR_TRANSPARENT
• Locking PR, needs review. Same with 2811.
• RP2040-Zero board definition matches upstream, acts as a temporary board definition until we update Zephyr (introduced to Zephyr in 4.1)
• Parameterised mod-morph and tap-dance
  • Question: Do we move hold-tap over to the same system?
    • Plan after discussion is to add a second hold-tap compatible and move over to it, to avoid breaking existing keymaps.
• Config index page and "Customising ZMK" docs overhaul, making them more visible and easier to understand.

Cem's summary:​

• Keymap recipes has been shelved for the time being. Prefer to have better examples in the behavior pages themselves, e.g. timeless homerow mods as an example under hold-tap.
• Hold-tap page needs overhauling. (This has already happened at time of publishing these notes)
• New behavior guide needs overhauling and should be aimed towards modules.
• 2758 needs a review and merge. (This has already happened at time of publishing these notes)

Other Discussion:​

ZMK-CLI:​

• It is likely time to rip the bandaid off and switch over to it, getting rid of the old setup script.
• CLI has some flaws that may need improvement (e.g. around modules), but is already much better than the existing script.
• New shield guide should be adjusted to take advantage of ZMK-CLI's templates.
• Joel requests issues be opened talking about points to improve on.

zmk-locales:​

• Should be moved under zmkfirmware organisation
  • Should do the same for zmk-locales-generator, and maybe figure out a way to set up a GH action that makes it send PRs to zmk-locales.
    • Move first, make these adjustments afterwards
  • Documenting them in list of keycodes page with a locale selector would be ideal, but complex
    • Refer people to headers directly in the docs for the time being
• Runtime locale changing would be preferred, but would also be a lot of work.
  • zmk-locales could be viewed as a (semi-permanent) bandaid until such a time

Modules:​

• Need to find the right balance between overloading contributers and overfragmentation
• ZMK module collection https://github.com/nmunnich/zmk-module-collection seems like a good way to go forward
  • Main concerns:
    • Need to handle breaking changes elegantly, informing users which module is to blame for the new version not working
    • Need to have tests for modules (can assume keyboard works if it builds, what about other stuff?)
    • Maintainability
      • Hopefully have more volunteers from the community to look at modules and verify them, should be much easier than reviewing PRs
      • Automated tests
      • Add an "experimental" group tag for unverified modules
  • Despite concerns, plenty of upsides. Seems like the best way forwards, and it is worth putting more time into.
  • Some upsides:
    • Very easy for users to add modules, particularly ones that depend on other modules
    • Automated testing and notification for module owners
    • Better discoverability
    • Versioning parity between the collection and ZMK itself to allow for easy upgrades
  • Likely will want to introduce "RC" releases, to allow module owners the time to fix any issues with their module before an actual release
  • Likely will only accept keyboards and drivers initially, until better tooling and systems are in place, given they are easier to validate

Minor notes:​

• Documenting BLE tests would be useful
• Need new display and lighting systems at some point
• Zephyr upgrade was not discussed in this meeting
• Would be good to give some extra priority to PRs from new contributors, to help motivate them.
• Would be nice to have another SOTF at some point. Doing a full commit overview is unfeasible at this point, but touching on the major issues seems doable.

ZMK Studio provides runtime keymap functionality for ZMK powered devices, allowing you to make changes without the need to flash new firmware. It is a combination of major firmware enhancements paired with a new frontend application for interacting with your keyboard.

The app is available for compatible browsers, and as an installable desktop application for Linux, macOS, and Windows.

Gratitude​

I'm extremely grateful for everyone who has helped make this release possible, which includes testers, code reviewers/contributors, including Nick-Munnich, joelspadin, and caksoylar, as well as the collection of vendors who have directly sponsored my work on the project, allowing it to come to fruition much faster than it would have taken me to do in my spare time.

Vendor Sponsors​

The following sponsors were instrumental in making ZMK Studio possible by sponsoring my work on the firmware and frontend application:

Platinum Level

Gold+ Level

Gold Level

Silver Level

Bronze Level

Additional Level

Using ZMK Studio​

To use ZMK Studio, you need to have a firmware for your keyboard with the feature enabled, as well as a small keymap change to add an unlock key. See Building with ZMK Studio and ZMK Studio keymap changes for more details.

See Accessing ZMK Studio for more details on the browser and desktop options for using the ZMK Studio application. Note: Depending on your browser, operating system, and app vs website selection, you may be limited to connecting over USB. See the previous link for details.

In-Tree Supported Keyboards​

The following in-tree keyboards have been updated to support ZMK Studio. If your keyboard is supported by an external module/config, check with the maintainer to see if support has been added.

• Advantage 360 Pro
• Corneish Zen
• Glove80
• nice!60
• BT60 V1 Hotswap
• BT60 V2
• BT65
• BT75 V1
• Boardsource 3x4 Macropad
• Boardsource 5x12
• Contra
• Corne
• Cradio/Sweep
• CRBN Featherlight
• Hummingbird
• Jian
• Jiran
• Jorne
• Kyria Rev3
• Kyria
• Lily58
• Lotus58
• MakerDiary m60
• QAZ
• REVIUNG41
• Sofle
• splitkb.com Aurora Corne
• splitkb.com Aurora Lily58
• splitkb.com Aurora Sofle
• splitkb.com Aurora Sweep
• ZMK Uno

Next Steps​

The ZMK Studio MVP is truly that, a "minimum viable product". It establishes the core firmware functionality and frontend application infrastructure in order to validate the technology, prove the approaches, and get initial core features into user's hands as early as possible.

There are many ZMK features that are not yet possible to update in ZMK Studio. For a better understanding of where ZMK Studio is today, and where we are headed, please have a look at the ZMK Studio capabilities table.

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:

   on: [push, pull_request, workflow_dispatch]
   
   jobs:
     build:
       uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@main
   

2. If it doesn't exist already, add a new file to your repository named build.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 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 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 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 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.

In this installment, we are highlighting two projects (and a bonus one!) from Joel Spadin, a member of the core ZMK team.

The first one is ZMK Tools, a handy Visual Studio Code extension to ease working with ZMK configurations, and the second is ZMK Locale Generator, a tool to help users that use non-US English keyboard locales in their operating systems.

In the rest of the post we leave it to Joel to introduce and explain the motivations of his ZMK-related projects. Stay tuned for future installments in the series!

ZMK Tools​

ZMK Tools is an extension for Visual Studio Code that helps with editing a ZMK user config repo or a fork of ZMK. I originally created it to add some code completion in .keymap files, but then I realized that with the web version of VS Code, I could also let you set up a user config repo and build firmware, much like the user setup script, except without downloading a single thing.

User Config Setup in Browser​

Here is how you can use ZMK Tools to get started with writing a ZMK keymap entirely within your browser. More detailed instructions can be found on the ZMK Tools README.

1. Open the ZMK config template repo on GitHub.
2. Click the Use this template button and follow the instructions to create your own repo.
   • If you don't see this button, make sure you're signed in to GitHub first.
   • You can name the repo anything you want, but "zmk-config" is the conventional name.
3. From the GitHub page for your new repo, press . (period) and it will re-open the repo in github.dev.
4. Press Ctrl + P and enter the following to install the ZMK Tools extension:

   ext install spadin.zmk-tools
   

5. Press Ctrl + Shift + P and run the ZMK: Add Keyboard command.
6. Follow the prompts to select a keyboard. ZMK Tools will copy the default keymap for that keyboard if you don't already have one, and it will automatically add it to your build.yaml file so GitHub will build it for you.

You can then edit your .keymap and .conf files. Once you're done:

1. Click the Source Control tab on the side bar.
2. Hover over the header for the Changes list and click the + (Stage All Changes) button.
3. Write a commit message and click Commit & Push to push your changes to GitHub.

GitHub will start building the new firmware. To check the results:

1. Use your browser's back button to go back to your repo's GitHub page.
2. Click the Actions tab at the top of the page.
3. Click the latest build (it should show the commit message you entered earlier). If it's still in progress, wait for it to finish.
4. If the build was successful, go to the Artifacts section and click firmware to download the firmware. If it failed, check the error and go back to github.dev to fix it.

Keymap Code Completion​

ZMK Tools also provides some basic code completion in .keymap files. It will suggest any of ZMK's built-in behaviors inside bindings and sensor-bindings properties, and it will automatically add the necessary headers.

For example, with the cursor at the end of line 6 in the following keymap...

/ {
    keymap {
        compatible = "zmk,keymap";
        default_layer {
            bindings = <
                &
            >;
        };
    };
};

...it will suggest things such as &kp, &mo, etc., and upon entering one, it will recognize that #include <behaviors.dtsi> is missing and add it to the top of the keymap:

#include <behaviors.dtsi>
/ {
    keymap {
        compatible = "zmk,keymap";
        default_layer {
            bindings = <
                &kp
            >;
        };
    };
};

Press space after &kp, and it will suggest all of ZMK's key codes. Upon entering one, it will again recognize that #include <dt-bindings/zmk/keys.h> is missing and add it too:

#include <behaviors.dtsi>
#include <dt-bindings/zmk/keys.h>
/ {
    keymap {
        compatible = "zmk,keymap";
        default_layer {
            bindings = <
                &kp A
            >;
        };
    };
};

This can be very helpful for making sure you spelled key codes correctly and included all the correct headers.

Future Work​

Unfortunately, all the code completion info currently comes from a config file baked into the extension, so it won't pick up any custom behaviors or key code aliases you've defined. I'd like to make that work eventually, but it's a much more difficult problem to solve.

ZMK Tools will discover all the boards/shields from both ZMK and your user config repo. With some recent changes in ZMK to allow pulling in features from other Zephyr modules, it's now possible to use board/shields defined in other repos, but ZMK Tools doesn't know about this yet. I'd like to support this too, but making it work in the web version of the extension will be challenging.

ZMK Locale Generator​

ZMK's key codes follow the HID specification, and many key codes indicate the position of a key on US keyboard layout, not the key's function. If your operating system is set to a different keyboard locale, then the character each key types won't necessarily line up with the key code name. For example, on a German "QWERTZ" layout, &kp Y will type Z and &kp Z will type Y, so you have to write your layout as if it were QWERTY instead. Other layouts can be even more confusing!

ZMK Locale Generator is another tool I made to help with this. It reads CLDR keyboard layouts and generates #defines to alias key codes to names that make sense in other locales. To use it, first go to the latest release and download the header that matches the locale you use. Next, copy it into the same folder as your keymap and #include it:

#include "keys_de.h"

/ {
    ...
};

If you open the header file in a text editor, you'll see that it contains many of the standard ZMK key codes, except they are prefixed by the locale code. Depending on the locale, it may also define key codes for special characters specific to that locale, e.g. DE_A_UMLAUT for "ä" and DE_SZ for "ß". If you use these in your keymap, then ZMK will send the correct key codes to type those characters.

#include "keys_de.h"

/ {
    keymap {
        compatible = "zmk,keymap";
        default_layer {
            bindings = <
                &kp DE_Q &kp DE_W &kp DE_E &kp DE_R &kp DE_T &kp DE_Z ...
            >;
        };
    }
};

I should note that, as a native English speaker and typer, I don't use any of this myself! I just saw that many people were asking for help with this, and I realized I could automate a solution. If you find something that isn't generated correctly, please file an issue or PR a fix on GitHub.

Keyboard Latency Testing​

The last project I want to mention is a tool for testing keyboard latency. It requires only a Raspberry Pi, an optocoupler IC, a resistor, and some wire. If you've ever wondered how ZMK's latency compares to other keyboards, you can check the results here!

I don't have a very large collection of keyboards though, so the data is pretty limited so far. If you want to try it on your own keyboard, see the instructions on the keyboard latency tester README, and please send me a PR with your results!

About Me​

I got a degree in electrical engineering but promptly became a software engineer instead. I still like tinkering with electronics though, so I discovered ZMK when I was making wireless macropad with a nice!nano, and I became a regular contributor after that. I use mostly larger keyboards with standard layouts and rarely use anything more complicated than momentary layers, so I've mostly focused on improving core features and tooling.

The keyboards I regularly use are a Ducky One 2 TKL that I leave at work, a Freebird TKL[^1], a custom wireless numpad, and a Yamaha CP4.

[^1] Running QMK, but I have designs to make a wireless PCB for it someday...

In the rest of the post we leave it to urob to introduce and explain the motivations of the project, and various ways it can be used to help maintain ZMK keymaps. Stay tuned for future installments in the series!

Overview​

Loosely speaking the nodefree repo -- more on the name later -- is a collection of helper functions that simplify configuring keymap files. Unlike the graphical keymap editor covered in the previous spotlight post, it is aimed at users who edit and maintain directly the source code of their keymap files.

The provided helpers fall into roughly one of three categories:

1. Helpers that eliminate boilerplate, reduce the complexity of keymaps, and improve readability.
2. Helpers that improve portability of "position-based" properties such as combos.
3. Helpers that define international and other unicode characters.

The reminder of this post details each of these three categories.

Eliminating Boilerplate​

In ZMK, keymaps are configured using so-called Devicetree files. Devicetree files define a collection of nested nodes, whereas each node in turn specifies a variety of properties through which one can customize the keymap.

For example, the following snippet sets up a mod-morph behavior that sends . ("dot") when pressed by itself and sends : ("colon") when shifted:

/ {
    behaviors {
        dot_colon: dot_colon_behavior {
            compatible = "zmk,behavior-mod-morph";
            #binding-cells = <0>;
            bindings = <&kp DOT>, <&kp COLON>;
            mods = <(MOD_LSFT|MOD_RSFT)>;
        };
    };
};

Adding this snippet to the keymap will create a new node dot_colon_behavior (nested underneath the behaviors and root / nodes), and assigns it four properties (compatible, #binding-cells, etc). Here, the crucial properties are bindings and mods, which spell out the actual functionality of the new behavior. The rest of the snippet (including the nested node-structure) is boilerplate.

The idea of the nodefree repo is to use C preprocessor macros to improve readability by eliminating as much boilerplate as possible. Besides hiding redundant behavior properties from the user, it also automatically creates and nests all required behavior nodes, making for a "node-free" and less error-prone user experience (hence the name of the repo).

For example, using ZMK_BEHAVIOR, one of the repo's helper functions, the above snippet simplifies to:

ZMK_BEHAVIOR(dot_colon, mod_morph,
    bindings = <&kp DOT>, <&kp COLON>;
    mods = <(MOD_LSFT|MOD_RSFT)>;
)

For complex keymap files, the gains from eliminating boilerplate can be enormous. To provide a benchmark, consider my personal config, which uses the nodefree repo to create various behaviors, set up combos, and add layers to the keymap. Without the nodefree helpers, the total size of my keymap would have been 41 kB. Using the helper macros, the actual size is instead reduced to a more sane 12 kB.¹

Simplifying "Position-based" Behaviors​

In ZMK, there are several features that are position-based. As of today, these are combos and positional hold-taps, with behaviors like the "Swapper" and Leader key currently developed by Nick Conway in pull requests also utilizing them.

Configuring these behaviors involves lots of key counting, which can be cumbersome and error-prone, especially on larger keyboards. It also reduces the portability of configuration files across keyboards with different layouts.

To facilitate configuring position-based behaviors, the nodefree repo comes with a community-maintained library of "key-position labels" for a variety of popular layouts. The idea is to provide a standardized naming convention that is consistent across different keyboards. For instance, the labels for a 36-key layout are as follows:

    ╭─────────────────────┬─────────────────────╮
    │ LT4 LT3 LT2 LT1 LT0 │ RT0 RT1 RT2 RT3 RT4 │
    │ LM4 LM3 LM2 LM1 LM0 │ RM0 RM1 RM2 RM3 RM4 │
    │ LB4 LB3 LB2 LB1 LB0 │ RB0 RB1 RB2 RB3 RB4 │
    ╰───────╮ LH2 LH1 LH0 │ RH0 RH1 RH2 ╭───────╯
            ╰─────────────┴─────────────╯

The labels are all of the following form:

• L/R for Left/Right side
• T/M/B/H for Top/Middle/Bottom and tHumb row.
• 0/1/2/3/4 for the finger position, counting from the inside to the outside

The library currently contains definitions for 17 physical layouts, ranging from the tiny Osprette to the large-ish Glove80. While some of these layouts contain more keys than others, the idea behind the library is that keys that for all practical purposes are in the "same" location share the same label. That is, the 3 rows containing the alpha keys are always labeled T/M/B with LM1 and RM1 defining the home position of the index fingers. For larger boards, the numbers row is always labeled N. For even larger boards, the function key row and the row below B are labeled C and F (mnemonics for Ceiling and Floor), etc.

Besides sparing the user from counting keys, the library also makes it easy to port an entire, say, combo configuration from one keyboard to the next by simply switching layout headers.

Unicode and International Keycodes​

The final category of helpers is targeted at people who wish to type international characters without switching the input language of their operation system. To do so, the repo comes with helper functions that can be used to define Unicode behaviors.

In addition, the repo also ships with a community-maintained library of language-files that define Unicode behaviors for all relevant characters in a given language. For instance, after loading the German language file, one can add &de_ae to the keymap, which will send ä/Ä when pressed or shifted.

About Me​

My path to ZMK and programmable keyboards started in the early pandemic, when I built a Katana60 and learned how to touch-type Colemak. Soon after I purchased a Planck, which turned out to be the real gateway drug for me.

Committed to making the best out of the Planck's 48 keys, I have since discovered my love for tinkering with tiny layouts and finding new ways of squeezing out a bit more ergonomics. Along the way, I also made the switch from QMK to ZMK, whose "object-oriented" approach to behaviors I found more appealing for complex keymaps.²

These days I mostly type on a Corne-ish Zen and are waiting for the day when I will finally put together the Hypergolic that's been sitting on my desk for months. My current keymap is designed for 34 keys, making liberal use of combos and timerless homerow mods to make up for a lack of keys.

In the rest of the post we leave it to Nick himself to introduce the project, detail his goals and motivation in developing such a tool, and talk about the future of the project. Stay tuned for future installments in the series!

What is Keymap Editor?​

Keymap Editor is a web based graphical editor for ZMK keymaps. It provides a visual way to manage the contents of your keymap and if nothing else offers two critical features:

1. Automatic formatting of the keymap file, so that bindings arrays remain readable
2. Searchable behaviors, keycodes, commands, etc, so you won't have to remember if it's LCTL or LCTRL (I just had to double check myself and I guessed wrong, apparently)

What can Keymap Editor do?​

• Render devicetree keymaps using pre-defined, auto-generated, or side-loadable keyboard layouts
• Integrate with a GitHub repo to streamline firmware builds, or FileSystem/Clipboard if you'd still rather build locally
• Edit combos, behaviors, macros, conditional layers and rotary encoder bindings
• Manage references: moving a layer or renaming a behavior will look for references throughout your keymap and update them.

But check back regularly, because I update pretty often. A recent significant achievement was enabling parameterized macros and tying it in with my existing parameter type resolution so, yeah, you can finally create that reusable macro combining bluetooth profile selection with RGB backlight colour. Or use it for an actual useful thing, even. (See also: Using Parameterized Macros in Keymap Editor)

My goals are, broadly:

• Treat code as a first-class entity: as long as ZMK keymaps are described in devicetree code then an editor needs to produce readable devicetree code.
• Flexibly support ZMK features: use of any ZMK keymap feature should theoretically be achievable within the app. In some cases this can mean more initial setup (See also: my thoughts on implementing "autoshift") but having that foundation makes its easier to add shortcuts and niceties — something I do quite often now.
• Don't get in the way of not-yet-supported features: If a new ZMK feature is released and the app isn't able to add it natively, you can always edit your keymap file directly. While the app may not recognize the new features, further changes through the app should not break your keymap.

History of Keymap Editor​

When I started writing Keymap Editor I had a handwired Dactyl variant running QMK. Manually editing keymap code was fine, but keeping things readable was important to me, and automating that was the best way to ensure consistency. Programmatically modifying source code was beyond me at the time so the first version persisted keymap data in JSON and spat out formatted versions of both the JSON and C keymaps.

After switching to ZMK I added a few more features, I guess as a pandemic project, and then gradually migrated from generating a templated keymap file to manipulating devicetree syntax directly, and that has made a big difference in adding new ZMK features.

Why am I doing this?​

It started out as a useful tool for me. I shared it with the ZMK community and gained a little traction, and then apparently quite a bit of traction — turns out it's useful for a lot of people.

I'm a software developer because I enjoy building things. Much of my day-to-day work isn't user facing, so seeing how helpful the keymap editor has been for people in the ZMK community is a big motivator to keep improving it.

Future plans​

Runtime updates​

Streamlining the keymap update process is probably top of mind for most users, but that involves a really big firmware feature, and I'm the wrong person to tackle it.

That said, once there's a protocol I would absolutely be down to integrate it as an additional keymap source. Being able to pull data directly from the keyboard should unlock a lot of possibilities and ease some of the constraints imposed by using devicetree code as a medium.

Simplifying behavior use​

I think a lot of people would like to see the concept of behaviors abstracted away for new users and to prompt them with

• "When the key is tapped...",
• "When the key is held...",
• "When the key is double-tapped..." and so on.

Users who are less familiar with ZMK's behaviors and how they are composed may find these prompts to be more intuitive, and their answers could be mapped to an appropriate combination of behaviors managed internally by an editor.

Uh, what else?​

This has been long enough already, if you're looking for a feature I haven't mentioned don't assume I won't add it. Feel free to make feature requests on the GitHub repo, and I'd be happy to discuss it!

About Me And My Keebs​

I like computers and write software. Many in this field enjoy using mechanical keyboards for their feel or aesthetics, but what piqued my interest was the Dactyl keyboard. I think, ergonomics aside, I'm more interested in the DIY/maker aspect than the collecting of keyboards and switches.

So I made a Dactyl, and then I made another Dactyl and I made a third Dactyl that isn't interesting enough to photograph, but now I'm using ZMK so I left room for 18650 cells.

That last Dactyl (with MX browns and a cheap blank XDA keycap set) serves me well the eight or so hours a day I'll spend at my desk, but I also spend a good deal of time computing on my couch where I'll use... my Macbook's built-in keyboard.

In case that's not surprising enough I'll leave you with this: despite all of the work and testing I've put into the keymap editor project, I've only updated an actual keymap once in the last year.

Thank you and good night.

More information​

• Keymap Editor Wiki
• Keymap Editor Discussions
• (YouTube video) Ben Frain's overview of the Keymap Editor

This update will cover all the major activity since SOTF #5. That was over a year ago (again!), so there are many new exciting features and plenty of improvements to cover!

Recent Activity​

Here's a summary of the various major changes since last time, broken down by theme:

Keymaps/Behaviors​

Hold-tap improvements​

andrewjrae added the require-prior-idle-ms property to the hold-tap behavior in #1187 and #1387, which prevents the hold behavior from triggering if it hasn't been a certain duration since the last key press. This is a useful feature to prevent accidental hold activations during quick typing and made its way into many keymaps! The same property was added to combos as well to help prevent false combo activations.

Note that an earlier iteration of this feature was supported with the global-quick-tap property, which did not allow customizing the timeout and used the value of quick-tap-ms for it. This property is now deprecated and users are encouraged to use require-prior-idle-ms instead.

urob added the hold-trigger-on-release property in #1423. This significantly increases the usefulness of positional constraints on hold-taps, since it allows combining multiple holds such as different modifiers for home row mods usage.

Masking mods in mod-morphs​

aumuell, vrinek and urob contributed to improving the behavior of mod-morphs by masking the triggering modifiers and added keep-mods property in #1412. This unlocks more use cases for mod-morphs, since you are no longer constrained to emitting keycodes that work well with the triggering modifier keycodes.

As an example, you can now define a mod-morph that swaps ; and : so that the former is the shifted version of the latter, which wasn't previously possible:

        col_semi: colon_semicolon {
            compatible = "zmk,behavior-mod-morph";
            #binding-cells = <0>;
            bindings = <&kp COLON>, <&kp SEMI>;
            mods = <(MOD_LSFT|MOD_RSFT)>;
        };

Parameterized macros​

petejohanson added macros that can be parameterized with one or two parameters in #1232. This allows users to define macros in a more modular way and is a nice quality-of-life improvement.

As a simple example, you could define a macro that puts any keycode provided between double quotes as below, then use it like &ql A in your keymap:

        ql: quoted_letter {
            #binding-cells = <1>;
            compatible = "zmk,behavior-macro-one-param";
            bindings =
                <&kp DQT>,
                <&macro_param_1to1 &kp MACRO_PLACEHOLDER>,
                <&kp DQT>;
        };

Please see the documentation page linked above for usage and more examples.

Arbitrary behaviors on encoder rotation​

nickconway and petejohanson added sensor rotation behaviors to allow invoking arbitrary behaviors from encoders #1758. Previously encoder rotations could only invoke the key-press behavior &kp through the &inc_dec_kp binding, whereas now you can define new sensor rotation behaviors to invoke others.

(Note that currently behaviors that have "locality" such as &rgb_ug do not work as expected via encoder rotation bindings in split keyboards, due to issue #1494.)

Pre-releasing already pressed keys​

andrewjrae contributed a tweak to emitting keycodes in #1828, where rolling multiple keys that involve the same keycode now releases the keycode before sending a press event again. While this might sound like a technical distinction, it leads to more correct behavior when quickly typing sequences like += and makes the key repeat behavior work properly when it is pressed before the previous key is released.

Key toggle behavior​

cgoates added the key toggle behavior in #1278, which can be used via its &kt binding to toggle the state of a keycode between pressed and released.

Apple Globe key​

ReFil added support for the C_AC_NEXT_KEYBOARD_LAYOUT_SELECT keycode with alias GLOBE which acts as the Globe key in macOS and iOS in #1938. Note that this keycode doesn't exactly behave like a Globe key that is present on an Apple keyboard and its limitations are documented in this comment thanks to testing by SethMilliken. These limitations will be noted in the official keycodes documentation shortly.

Bug fixes and other improvements​

petejohanson, andrewjrae and okke-formsma tracked down and fixed an issue causing stuck keys when there are combos on key positions involving hold-tap behaviors in #1411. This was an elusive bug that took a lot of effort from the community to nail down and fix!

nguyendown and joelspadin tracked down and fixed a couple issues causing stuck keys with sticky keys in #1586, #1745.

okke-formsma fixed an issue allowing tap dances to be invoked by combos in #1518.

petejohanson tweaked the caps word behavior to ignore modifiers in #1330.

HelloThisIsFlo documented a bug with combos involving overlapping keys and different timeouts, produced a reproducing unit test, then proceeded to fix it in #1945.

Bluetooth and Split Improvements​

Multiple peripherals​

xudongzheng contributed to add support for more than one peripheral per keyboard in #836. This allows setups such as split keyboards with more than two halves, or enable a BLE-based "dongle mode" via a third device running ZMK that can stay connected to a computer via USB.

Note that documentation is still lacking for utilizing more than one peripheral and there will potentially be future changes in the build system to allow for more seamless configuration.

Pairing passkey requirement​

petejohanson added the option to require passkey input while pairing to new devices in #1822. Enabling this will require you to enter a six digit passcode via the number keys on your keymap and press enter when pairing to a new device, enhancing security during the pairing procedure.

Split keyboard improvements​

petejohanson contributed a fix to release held keys on peripheral disconnect #1340, which makes scenarios where a split disconnects unexpectedly less painful.

petejohanson also improved the settings_reset shield by making it clear bonds more reliably, and allow it to build for all boards in #1879.

petejohanson and xudongzheng contributed additional split connectivity improvements, via using directed advertising in #1913 and improving the robustness of central scanning in #1912.

Hardware Support​

Encoders​

petejohanson contributed a major refactor of encoder (and more generally sensor) functionality in #1039. While the documentation for these changes are still in progress, check out the dedicated blog post for more details.

This refactor paved way to implementing a long-awaited feature, encoder support in peripheral halves of split keyboards! Building upon the work by stephen in #728, petejohanson implemented support in #1841.

Direct GPIO driver​

joelspadin extended the comprehensive debouncing framework used for matrix scan driver to the direct GPIO driver in #1288.

kurtis-lew added toggle mode support for direct GPIO driver in #1305. This allows for adding toggle switches to a keyboard, by properly reading their initial state on boot and making sure the power use is efficient.

IO peripheral drivers​

petejohanson added support for the 595 shift register commonly used with smaller controllers like Seeeduino Xiaos, in #1325.

zhiayang added the driver for the MAX7318 GPIO expander in #1295.

Underglow auto-off options​

ReFil added two new RGB auto off options, one using an idle timeout and the other USB status in #1010.

nice!view support​

nicell added support for nice!view, a memory display optimized for low power use in #1462. He also contributed a custom vertically-oriented status screen that is automatically enabled when the nice_view shield is used in #1768, since the default status screen has a horizontal orientation. Please see the instructions in the nice!view README if you would like to restore the stock status screen.

E-paper display initialization​

petejohanson contributed EPD initialization improvements in #1098, which makes the keyboards using slow refresh displays such as the Corne-ish Zen much more responsive during initial boot.

Xiao BLE improvements​

Various improvements were made for the Seeeduino Xiao BLE board in #1293, d0176f36, #1545 and #1927 by petejohanson and caksoylar, enabling features necessary for ZMK and improving its power use.

Zephyr 3.2 Upgrade​

petejohanson once again contributed the massive work necessary for upgrading ZMK to Zephyr 3.2 in #1499, with review help from joelspadin and testing by the community. This Zephyr release brings with it upgrades to the display library LVGL, adds official support for the RP2040 controllers and many internal refactors to help future development. Check out the dedicated blog post for more details!

Documentation​

Configuration docs​

joelspadin, through a massive amount of work in #722, contributed a whole new section to the documentation: configuration! It enumerates the configuration options for each ZMK feature that might be relevant to users in dedicated pages, making it a very handy reference.

In addition, the overview page presents an overview of how configuration works in Zephyr in the context of ZMK, in terms of devicetree files (like the keymap files or shield overlays), and Kconfig ones (like the .conf files). It is very helpful in de-mystifying what the various files do and what syntax is expected in them.

New behavior guide​

For users or future contributors that might want to dive into writing their own ZMK behaviors, kurtis-lew wrote a useful guide on how to create new behaviors in #1268.

Tap dance and hold-tap documentation improvements​

kurtis-lew also improved the documentation for these two behaviors in #1298, by updating the diagrams to better clarify how their timings work and adding examples for scenarios that are frequently asked by users.

Battery sensor documentation​

joelspadin also added documentation for setting up battery sensors, typically required for new boards, in #868.

Shield interconnects​

petejohanson updated the new shield guide for non-Pro Micro interconnects including Xiao, Arduino Uno and Blackpill in #1607.

Bluetooth feature page​

petejohanson and caksoylar added a new Bluetooth feature page as part of #1499 and in #1818, detailing ZMK's Bluetooth implementation and troubleshooting for common problems.

In addition to the specific contributions listed above, various improvements and fixes to documentation are made by many users from the community, including but not limited to kurtis-lew, joelspadin, filterpaper, byran.tech, dxmh and caksoylar. These contributions are are all very appreciated!

Miscellaneous​

Reusable GitHub build workflow​

elagil helped switch the build workflow used by the user config repos to a reusable one in #1183 and it was further tweaked by filterpaper in #1258. This allows any changes in the workflow to be propagated automatically to users, rather than requiring them to make the updates. The build workflow can be customized by the users using input parameters if desired.

Pre-commit hooks​

joelspadin added various pre-commit hooks and added checks to the repo to run them for each commit in #1651. These hooks and resulting updates standardize formatting across devicetree and other source files, reducing busywork on both contributors and reviewers.

Zephyr usage and other refactors​

joelspadin also contributed a few refactor PRs such as #1269, #1255 and #1803, generally improving code quality and bringing the codebase in line with the latest Zephyr conventions.

petejohanson refactored the drivers structure to bring it in line with the current Zephyr conventions for out-of-tree drivers in #1919.

Updated USB polling interval default​

USB HID polling interval now defaults to 1 ms, i.e. a 1000Hz polling rate, thanks to joelspadin's tweak in #1271.

Additional display config options​

caksoylar added a couple configuration options for displays, including a setting to invert display colors in #1754 and an option to display the battery percentage for the stock status screen in #1563.

New Shields​

• Eternal keypad #1136 - halcyonCorsair
• nullbits SNAP #1319 - jaygreco
• Aurora Sweep #1504, Corne #1520, Lily58 #1553, Sofle #1864, and Helix #1873 - petejohanson
• ZMK Uno shield #1576 - petejohanson
• Waterfowl #1554 - JW2586
• Kyria Rev 3 #1627 - petejohanson
• Leeloo v2 and Leeloo-Micro #1762 - ClicketySplit
• Spaceboards Pancake #1400 - jasonhazel
• Reviung5 #1548 - zblesk

New Boards​

• RP2040 boards, including Sparkfun Pro Micro, Adafruit KB2040 and Seeeduino Xiao RP2040 were added as part of the Zephyr 3.2 upgrade in #1499 - petejohanson
• Puchi BLE #1445 - BenRoe
• nRFMicro 1.3/1.4 (nRF52833) #912 - pashutk
• nRF5340 DK #1562 - joelspadin
• PillBug #1530 - kylemccreery
• Preonic Rev 3 #1575 - jeromeOlivier
• Corne-ish Zen v2 #1498 and v1 #1593 - LOWPROKB and caksoylar
• Polarity Works CKP family of boards #1547 - ReFil

Coming Soon!​

Some items listed in the last coming soon section are still under active development and other new exciting items are in progress:

• Automatic/simple BLE profile management
• Soft off support for turning the keyboard "off" through firmware
• Improved automatic power management for devices with multiple peripherals, e.g. OLED displays and RGB LEDs
• Caps/Scroll/Num Lock LED support
• Mouse keys
• Wired split support
• More modular approach to external boards/shields, custom code, user keymaps, etc.
• More shields and boards

Statistics​

Some statistics of interest for ZMK:

• GitHub (lifetime stats)
  • 166 Contributors
  • 1256 Closed PRs
  • 1883 Stars
  • 1949 Forks
• Discord Chat
  • 8055 total registered (130% up from last SOTF!)
• Website (last 30 days)
  • 52K page views
  • 4.7K new users

Sponsorship​

While ZMK is an open source project that uses the permissive MIT license, below are opportunities for anyone who would like to show their support to the project financially.

Open Collective​

The ZMK project has an Open Collective sponsorship that has been going for two and a half years. This fund helps pay for project costs like domain registration or development of hardware such as the ZMK Uno shield. Note that donations to this fund do not pay for the work of any individual contributor directly.

Contributor sponsorships​

Project creator and lead Pete Johanson has a GitHub sponsorship set up that you can contribute to, in order to directly support his time and efforts in developing and maintaining ZMK. He has also been traveling full time while focusing on ZMK and keyboard hardware design for more than a year now! If you are curious, you can check out his blog post on deciding to embark on this adventure, in addition to his thoughts on contributor vs. project sponsorship, and sustainability of open source projects in general.

Thanks!​

As the first person to author a State Of The Firmware post besides Pete, I'd like to take the opportunity to thank him for his efforts on leading and developing ZMK, along with fostering a great community of contributors and users around it.

Also a big thank you to contributors that submit patches and perform reviews, testers that help validate changes, and users that take time out of their day to help out folks with ZMK usage on Discord channels, GitHub issues and other communities.

Article Updates​

• 12/2023: Removed the deprecated label property from code snippets.

As part of the work, backwards compatibility for existing shields has been retained, but only for a grace period to allow out-of-tree shields to move to the new approach for encoders.

Special thanks to joelspadin for the thorough code review and testing throughout the development of the refactor.

Summary of Changes​

The following items have been merged:

1. Split configuration of hardware details, and behavior configuration to allow more flexible functionality of sensors/encoders, in particular linear encoders that lack detents/"clicks" as they rotate.
2. Support for upstream Zephyr sensor drivers, including the NRFX QDEC driver that can be used on nRF52 based keyboards.
3. Sensor data handling changes that pave the way for split sensor handling easily.

Configuration Changes​

The major changes to configuration in the devicetree files relates to how the number of steps/triggers for a given encoder are set. In particular, the number of pulses/steps for a given encoder is configured first, allowing ZMK to determine the exact angular degrees of change that is represented by a single pulse on the data lines to that encoder.

Once that angular degrees mapping is completed, now independently there is a configuration setting to control how many triggers of the behavior in the keymap should occur for each full rotation of the sensor. Another way to think of this is "how many degrees of rotation results in a triggering of the sensor behavior in your keymap layer".

Splitting these two parts of the encoder configuration allows greater flexibility, and fine grained control of encoder behavior for linear encoders that don't have fixed detents.

Old Configuration​

Previously, an encoder configuration looked like:

    left_encoder: encoder_left {
        compatible = "alps,ec11";
        a-gpios = <&pro_micro 21 (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
        b-gpios = <&pro_micro 20 (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
        resolution = <4>;
    };

Here, the resolution property was used to indicate how many encoder pulses should trigger the sensor behavior one time. Next, the encoder is selected in the sensors node:

    sensors {
        compatible = "zmk,keymap-sensors";
        sensors = <&left_encoder &right_encoder>;
    };

That was the entirety of the configuration for encoders.

New Configuration​

    left_encoder: encoder_left {
        compatible = "alps,ec11";
        a-gpios = <&pro_micro 21 (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
        b-gpios = <&pro_micro 20 (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
        steps = <80>;
    };

Here, the steps property is now used to indicate how many encoder pulses there are in a single complete rotation of the encoder. Next, the encoder is selected in the sensors node as before, but an additional configuration is used to indicate how many times the encoder should trigger the behavior in your keymap per rotation:

    sensors {
        compatible = "zmk,keymap-sensors";
        sensors = <&left_encoder &right_encoder>;
        triggers-per-rotation = <20>;
    };

For tactile encoders that have detents, the triggers-per-rotation would match the number of detents on the encoder. For linear encoders, the value can be chosen to suit your needs.

Zephyr Sensor Drivers​

The configuration changes bring ZMK's code in line with how upstream Zephyr sensor drivers handle rotations. This has the added advantage of allowing us to leverage other sensor drivers. On Nordic MCUs, like nRF52840, the NRFX QDEC driver can be used, for example:

&pinctrl {
    qdec_default: qdec_default {
        group1 {
            psels = <NRF_PSEL(QDEC_A, 1, 11)>,
                    <NRF_PSEL(QDEC_B, 1, 10)>;
            bias-pull-up;
        };
    };
};

// Set up the QDEC hardware based driver and give it the same label as the deleted node.
encoder: &qdec0 {
    status = "okay";
    led-pre = <0>;
    steps = <80>;
    pinctrl-0 = <&qdec_default>;
    pinctrl-names = "default";
};

The NRFX QDEC driver has the advantage of supporting optical encoders as well, and although it polls, it does so in hardware without waking the MCU core; initial basic power profiling is promising.

Split Sensor/Encoder Support​

In addition to the refactors for splitting the configuration, the changes merged included refactors designed to simplify and move forward with the long outstanding feature of supporting encoders on the peripheral side of split keyboards. That work is planned as a follow up.

Deprecation​

The old configuration will be supported for a period of one month, and then removed, giving users a grace period to complete the migration to the new separated configuration.

Article Updates​

• 12/2023: Removed the deprecated label property from code snippets.

petejohanson did the upgrade work to adjust ZMK for the Zephyr changes, with help from Nicell on the LVGL pieces.

• Upgrade to LVGL 8.x API, and move to the new Kconfig settings.
• Tons of RP2040 work.
• Zephyr core API changes, including DTS label use changes.
• Move to pinctrl Zephyr subsystem.

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.2 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:

   on: [push, pull_request, workflow_dispatch]
   
   jobs:
     build:
       uses: zmkfirmware/zmk/.github/workflows/build-user-config.yml@main
   

2. If it doesn't exist already, add a new file to your repository named build.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.

Upgrade a manual script​

If you have a custom GitHub Actions workflow you need to maintain for some reason, you can update the workflow 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

• Locate and delete the lines for the DTS output step, which is no longer needed:

  - name: ${{ steps.variables.outputs.display-name }} DTS File
    if: ${{ always() }}
    run: |
      if [ -f "build/zephyr/${{ matrix.board }}.pre.tmp" ]; then cat -n build/zephyr/${{ matrix.board }}.pre.tmp; fi
      if [ -f "build/zephyr/zephyr.dts" ]; then cat -n build/zephyr/zephyr.dts; fi
  

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.2 Docker image.

Local Host Development​

The following steps will get you building ZMK locally against Zephyr 3.2:

• Run the updated toolchain installation 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!

Known Issues​

A few testers have reported inconsistent issues with bluetooth connections on Windows after upgrading, which can be resolved by re-pairing your keyboard by:

1. Remove the device from Windows.
2. Clear the profile on your keyboard that is associated with the Windows device by triggering &bt BT_CLR on your keymap while that profile is active.
3. Restart Windows.
4. Re-connect Windows to your keyboard.

Windows Battery Reporting Fix​

Zephyr 3.2 introduced a new Kconfig setting that can be used to work around a bug in Windows related to battery reporting. Check out our bluetooth config for the full details. The key new configuration that can be set if using Windows is:

CONFIG_BT_GATT_ENFORCE_SUBSCRIPTION=n

Keymap Changes​

Due to conflicts with new devicetree node labels added for Zephyr's reset system, the &reset behavior has been renamed to &sys_reset.

All of the in-tree keymaps have been fixed, but you may encounter build failures about duplicate names, requiring you rename the behavior reference in your keymap. Use the Keymap Upgrader and this will get fixed for you automatically.

Board/Shield Changes​

The following changes have already been completed 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.

Move to pinctrl driver​

Before this change, setting up the details of pins to use them for peripherals like SPI, I2C, etc. was a mix of platform specific driver code. Zephyr has moved to the newer pinctrl system to unify the handling of pin configuration, with additional flexibility for things like low power modes for those pins, etc.

Board specific shield overlays​

The main area this affects existing shields is those with board specific overrides, e.g. <shield>/boards/seeeduino_xiao_ble.overlay, that sets up additional components on custom buses, e.g. addressable RGB LEDs leveraging the SPI MOSI pin.

nRF52 Pin Assignments​

Previously in ZMK, we relied on per-driver devicetree source properties to set the alternate pin functions for things like SPI or I2C. For example, here is the I2C bus setup as it was previously on the nice_nano board:

&i2c0 {
    compatible = "nordic,nrf-twi";
    sda-pin = <17>;
    scl-pin = <20>;
};

With the move to the pinctrl system, this setup now look like:

 &i2c0 {
    compatible = "nordic,nrf-twi";
    pinctrl-0 = <&i2c0_default>;
    pinctrl-1 = <&i2c0_sleep>;
    pinctrl-names = "default", "sleep";
 };

which references the pinctrl configuration:

&pinctrl {
       i2c0_default: i2c0_default {
               group1 {
                       psels = <NRF_PSEL(TWIM_SDA, 0, 17)>,
                               <NRF_PSEL(TWIM_SCL, 0, 20)>;
               };
       };

       i2c0_sleep: i2c0_sleep {
               group1 {
                       psels = <NRF_PSEL(TWIM_SDA, 0, 17)>,
                               <NRF_PSEL(TWIM_SCL, 0, 20)>;
                       low-power-enable;
               };
       };
};

Although slightly more verbose this allows pin configuration infrastructure to be re-used, specify other modes, like sleep, etc. in a standard way across architectures.

Out of Tree Boards/Shields​

All of the in-tree boards and shields have been upgraded, but if you maintain/use an out-of-tree board or shield that uses the converted boards and overrides pins for various buses, you may need to switch to pinctrl to match ZMK's new approach.

The approach is the following when updating a board:

1. Add an entry CONFIG_PINCTRL=y to the <board>_defconfig file in the board directory.

2. Add a new file with the naming convention <board>-pinctrl.dtsi to your board directory.

3. In the new file, add your pinctrl entries that set up different pin control configurations for whatever peripherals/buses are needed. Here's the nice!nano file as an example:

   /*
   * Copyright (c) 2022 The ZMK Contributors
   * SPDX-License-Identifier: MIT
   */
   
   &pinctrl {
           uart0_default: uart0_default {
                   group1 {
                           psels = <NRF_PSEL(UART_RX, 0, 8)>;
                           bias-pull-up;
                   };
                   group2 {
                           psels = <NRF_PSEL(UART_TX, 0, 6)>;
                   };
           };
   
           uart0_sleep: uart0_sleep {
                   group1 {
                           psels = <NRF_PSEL(UART_RX, 0, 8)>,
                                   <NRF_PSEL(UART_TX, 0, 6)>;
                           low-power-enable;
                   };
           };
   
           i2c0_default: i2c0_default {
                   group1 {
                           psels = <NRF_PSEL(TWIM_SDA, 0, 17)>,
                                   <NRF_PSEL(TWIM_SCL, 0, 20)>;
                   };
           };
   
           i2c0_sleep: i2c0_sleep {
                   group1 {
                           psels = <NRF_PSEL(TWIM_SDA, 0, 17)>,
                                   <NRF_PSEL(TWIM_SCL, 0, 20)>;
                           low-power-enable;
                   };
           };
   };
   

4. From the main <board>.dts file, add an #include "<board>-pinctrl.dtsi" to have the C-preprocessor combine the files.

5. Update the various peripheral nodes to use the new pinctrl configurations. For example, the following old configuration:

   &i2c0 {
       compatible = "nordic,nrf-twi";
       sda-pin = <15>;
       scl-pin = <17>;
   };
   

   would be changed to:

   &i2c0 {
       compatible = "nordic,nrf-twi";
       pinctrl-0 = <&i2c0_default>;
       pinctrl-1 = <&i2c0_sleep>;
       pinctrl-names = "default", "sleep";
   };
   

Because pinctrl configuration is very dependent on the specific target SoC, you will rarely need to consider it for a shield overlay that leverages a pro micro or XIAO abstraction. As noted, you're more likely to need to fix up pinctrl settings is using a board specific shield overlay, e.g. <shield>/boards/<board>.overlay to set things up.

LVGL Kconfig changes.​

With the update to LVGL 8.x, Zephyr now leverages an upstream Kconfig file for most LVGL settings. Due to this, the naming for many existing configs has been adjusted. For any configs moved upstream, the naming mostly involves a prefix change from LVGL_ to the shorter LV_. For any that are still Zephyr specific configs, they are now prefixed with LV_Z_ prefix.

If you maintain or use an out of tree board/shield with a display, the following will need to be changed in your Kconfig files:

• LVGL_VDB_SIZE -> LV_Z_VDB_SIZE
• LVGL_DPI -> LV_DPI_DEF
• LVGL_BITS_PER_PIXEL -> LV_Z_BITS_PER_PIXEL

Other than those specific examples, most other Kconfig values can simply change the LVGL_ prefix to LV_.

Raspberry Pi Pico/RP2040 Support​

This Zephyr update allows ZMK to support the new(-ish) RP2040 SoC found in the Raspberry Pi Pico.

Supported Controllers​

The following RP2040 powered controllers have board definitions for folks to test:

• Raspberry Pi Pico (rpi_pico)
• SparkFun Pro Micro RP2040 (sparkfun_pro_micro_rp2040)
• Adafruit Keyboar/KB2040 (adafruit_kb2040)
• Seeeduino XIAO RP2040 (seeeduino_xiao_rp2040)
• Adafruit Qt PY RP2040 (adafruit_qt_py_rp2040)
• BoardSource blok (boardsource_blok)
• Elite-Pi (compatible with the sparkfun_pro_micro_rp2040 board)

Upcoming Changes​

Display re-init​

Zephyr's improved power domain support is a foundation upon which we can provide a proper fix for the longstanding display re-init bug which has prevented ZMK from formally supporting our display code.

There is work still remaining to fully leverage the power domain system within ZMK to fix the bug, but upgrading Zephyr is the first necessary step.

Thanks!​

Thanks to all the testers who have helped verify ZMK functionality on the newer Zephyr version.

commit 85c8be89dea8f7a00e8efb06d38e2b32f3459935
Author: Pete Johanson <peter@peterjohanson.com>
Date:   Tue Apr 21 16:20:34 2020 -0400

    Initial work.

 .gitignore     |  1 +
 .gitmodules    |  3 +++
 CMakeLists.txt | 40 +++++++++++++++++++++++++++++++++++++++
 src/main.c     | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/zmk_lib.h  |  7 +++++++
 zephyr-rust    |  1 +
 6 files changed, 112 insertions(+)

I will never forget that commit. Not because of the code it contained (please don't look, it's not worth it!), but for what it started.

Working on ZMK has given me the opportunity to reconnect with old friends (@brixmeister was my Gentoo mentor/sponsor when I became a contributor there on my first ever OSS project, and is a current active Zephyr RTOS contributor!), make new ones, and learn so much from the amazing mechanical keyboard community.

First Keyboard​

But I'm getting ahead of myself! Back to early ZMK. I present you the first ZMK keyboard:

That first "keyboard" taught me a lot. It forced me to dust off my long forgotten, rudimentary electronics knowledge, and gave me my first taste of really combining the physical/tangible with code in a way that years of doing backend API development never had.

I was hooked.

Zephyr RTOS​

Early in my brainstorming, I knew I needed a foundation to build upon that would get me "a lot for free." I evaluated several different real-time operating systems (RTOSes) and happened upon Zephyr. It immediately ticked all the boxes I wanted:

• Robust, open source Bluetooth stack, supporting multiple SoCs. At the time, I was trying out stm32wb thanks to some interest among keyboard designers, but I also so there were other compelling choices that might be a good fit.
• An open source, non-copyleft license. I am a firm believer in F/OSS, and wanted to use a license that was as unrestricted as possible.
• Had a lot of core APIs available, so I could focus on the keyboard functionality, not the plumbing. I love tinkering, but I wanted to focus my time on the interesting bits, not infrastructure.

I'm really happy with the choice, it has served us incredibly well the past two years.

Real Keyboard​

At some point, somehow, innovaker introduced me to nicell who graciously sent me a few of the early pre-production nice!nano controllers, which I was able to get running on my Kyria. Doing so required the first split code, as well as lots of general improvements.

The day I was finally able to type on a wireless, split keyboard running ZMK was deeply momentous for me!

Onward and Upward​

We've come a long way since then, with our supported hardware, features and behaviors growing regularly.

ZMK powered keyboards are now available in group buys and in stock at various vendors; compatible controllers have been used in a wide range of builds to empower our users to free themselves from their USB/TRRS cables and move about untethered.

This progress is only possible thanks to all of the contributors who've joined me in the vision for a wireless-first world. I am so grateful for everyone who has given their time to contribute code, answer questions on our Discord server, write more documentation, and especially all the users who have trusted us to make their input devices work.

I can't wait to see what we can accomplish together in the next two years.

This update will cover all the major activity since SOTF #4. That was over a year ago, so lots to cover!

Recent Activity​

Here's a summary of the various major changes since last time, broken down by theme:

Keymaps/Behaviors​

Since last time, there have been several new powerful keymap features and behaviors added, including several asked for features, such as tap-dance and macros.

Caps Word​

petejohanson added the caps word behavior, i.e. &caps_word, in #823 that allows toggling a mode where all all alpha characters are sent to the host capitalized until a non-alpha, non-"continue list" keycode is sent. This can be useful for typing things like CONFIG_ENABLE_CAPS_WORD without having to hold down shift. This is similar in spirit to using the caps lock key, but with the added benefit of turning itself off automatically.

Key Repeat​

petejohanson added the new key repeat behavior in #1034 to allow repeating the last sent key-press again, including any modifiers that were applied to that key press. It can be added to your keymap using the simple &key_repeat reference.

Macros​

petejohanson, taking heavy inspiration on the initial work from okke-formsma, added macro support in #1168. Several common patterns are documented, but one example, changing the underglow color as you activate/deactivate a layer, looks like:

ZMK_MACRO(layer_color_macro,
  wait-ms = <0>;
  tap-ms = <0>;
  bindings
      = <&macro_press &mo 1>
      , <&macro_tap &rgb_ug RGB_COLOR_HSB(128,100,100)>
      , <&macro_pause_for_release>
      , <&macro_release &mo 1>
      , <&macro_tap &rgb_ug RGB_COLOR_HSB(300,100,50)>;
)

Tap Dance​

kurtis-lew worked diligently to add the tap-dance behavior in #1139, allowing different behaviors to be invoked based on the number of times a user taps a single key in their keymap, e.g.

/ {
    behaviors {
        td0: tap_dance_0 {
            compatible = "zmk,behavior-tap-dance";
            #binding-cells = <0>;
            tapping-term-ms = <200>;
            bindings = <&kp N1>, <&kp N2>, <&kp N3>;
        };
    };

    keymap {
        compatible = "zmk,keymap";

        default_layer {
            bindings = <
                &td0
            >;
        };
    };
};

Conditional Layers​

bcat added conditional layers in #830 as a generalized version of the common "adjust layer" pattern on smaller keyboards.

Example:

/ {
    conditional_layers {
        compatible = "zmk,conditional-layers";
        tri_layer {
            if-layers = <1 2>;
            then-layer = <3>;
        };
    };
};

Combos​

mcrosson added the layer specific combos in #661, so users can make certain combos only triggerable when the layers set for the combo are active.

This is used by the ZMK implementation of ARTSEY extensively.

Sticky Keys​

okke-formsma updated sticky keys in #1122 to add the ignore-modifiers; property; when set, sticky keys won't release when other modifiers are pressed. This allows you to combine sticky modifiers, which is popularly used with "callum-style mods".

Hold-Tap Improvements​

jmding8 added an additional positional hold-tap configuration in #835 to help certain sequences produce the expected results.

jmding8 also added an additional hold-tap flavor: tap-unless-interrupted in #1018 which works very well with the new positional hold-tap config.

okke-formsma implemented retro-tap hold-tap property in #667

okke-formsma also added quick-tap-ms hold-tap property in #655

Apple Device Compatibility Improvements​

Pairing​

petejohanson did some sleuthing and fixed a long standing problem with inconsistent pairing with macOS in [#946]](https://github.com/zmkfirmware/zmk/pull/946). With the changes, macOS more reliably pairs with ZMK devices.

Consumer (Media) Codes​

Another persistent bug that Apple users experienced was related to crashes and problems with keyboard configurations, that was traced to an issue with ZMK's HID usage that was fixed by petejohanson in #726.

Debounce Enhancements​

joelspadin applied some major enhancements to our debouncing approach to allow fine grained control of our debouncing in #888, including allowing eager debouncing which can reduce key press latency.

Split Improvements​

Behavior Locality​

The long awaited locality enhancement was finally merged by petejohanson in #547, allowing more fine grained control of where certain behaviors are invoked. Some key improvements thanks to the changes:

• RGB Underglow behaviors now run globally, so enabling/disabling RGB, changing the color, animation, etc. applies to both sides of a split properly.
• Reset/Bootloader behaviors now run wherever the key was pressed. For example, adding a &bootloader reference to the peripheral side of a split will now put that side of the split into the bootloader when pressed.

Split Connections​

petejohanson also added fixes to improve split re-connection for certain scenarios in #984, helping ensure splits properly connect when one side or the other is reset.

Hardware Support​

Backlight​

bortoz added single color backlight support in #904 for those keyboards that have it as an alternative to RGB underglow.

E-Paper Display (EPD) Driver​

petejohanson worked with LOWPROKB to add support for the E-Paper Displays (EPD) in #895 used in keyboards like the Corne-ish Zen.

nRF VDDH Battery Sensing​

joelspadin added a new sensor driver to support battery charge calculation by sensing voltage on the VDDH pin on nRF52 chips in #750, which is particularly useful for designs using "high voltage mode" with that SoC.

Miscellaneous​

Documentation​

dxmh and caksoylar have joined the ZMK organization to help with documentation, and have been doing an amazing job adding new docs, and leading reviewing docs related PRs to free other contributors up to focus on other areas. It's been an incredible addition to ZMK!

NKRO Support​

petejohanson's work on the HID foundation also included adding support for full NKRO HID in #726 that can be enabled by adding the following to your .conf file for your config:

CONFIG_ZMK_HID_REPORT_TYPE_NKRO=y

Power Profiler​

It's been live for a while, but nicell added an amazing power profiler in #312 to allow users to estimate their battery life for various hardware configurations.

Min/Max Underglow Brightness​

malinges added support for configuring min/max underglow brightness in #944 by setting the values in your .conf file as percentages of full:

CONFIG_ZMK_RGB_UNDERGLOW_BRT_MIN=20
CONFIG_ZMK_RGB_UNDERGLOW_BRT_MAX=80

This can be useful to be sure that lowering brightness doesn't set the brightness to zero, and raising the brightness doesn't consume too much power.

Zephyr 3.0​

petejohanson helped prepare and test the upgrade of ZMK to Zephyr 3.0 in #1143. The updated Zephyr release brings with it some key BLE stability fixes, as well as various other core improvements that improve ZMK. This was a huge undertaking!

New Shields​

• Contra in #633 - iangus
• Naked60 in #681 - xiushak
• Murphpad in #806 - kylemccreery
• A. Dux in #951 - dxmh
• Bat43 in #956 - dnaq
• Zodiark in #959 - Aleblazer
• Osprette in #974 - smores56
• Knob Goblin in #990 - lucasuyezu
• Redox in #1002 - toddmok
• Elephant42 in #1009 - filoxo
• Chalice in #1022 - joshajohnson
• Boardsource 5x12 in #1027 - fsargent
• Jiran in #1048 - krikun98
• keeb.io Fourier in #1056 - TheButlah
• Lotus58 in #1090 - nettema
• Clog in #1092 - smores56
• Kyria rev2 in #1112 - petejohanson
• Leeloo in #1165 - ClicketySplit
• 2% Milk in #1135 - kurtis-lew

New Boards​

• Ferris rev02 in #642 - petejohanson
• nice!60 in #810 - nicell
• nice!nano v2 in #867 - nicell
• Mikoto 520 in #985 - mrninhvn
• S40NC in #1021 - kylemccreery
• BT60 in #1029 - ReFil
• Seeeduino XIAO BLE (as part of the Zephyr 3.0 work) in #1143 - petejohanson

Board/Shield Metadata​

nicell and petejohanson worked together in #883 to settle on a metadata format that is used to document every board and shield. This now drives automatic generation of our supported hardware page and our more nuanced GH Actions automation for testing changes to ZMK.

Coming Soon!​

Some items listed in the last coming soon section are still under active development.

• RP2040 support
• Peripheral rotary encoder support
• Caps/Scroll/Num Lock LED support
• Mouse Keys
• Wired split support
• More modular approach to external boards/shields, custom code, user keymaps, etc.
• More shields and boards

Statistics​

Some statistics of interest for ZMK:

• GitHub (lifetime stats)
  • 105 Contributors
  • 791 Closed PRs
  • 849 Stars
  • 832 Forks
• Discord Chat
  • 3430 total registered
• Website (last 30 days)
  • 35.9K page views
  • 3.29K new users

Thanks!​

As we approach the two year birthday for ZMK, I am reminded of how far we have come in such a short time, in large part thanks to the amazing community that has grown around it. I am so grateful to have so many contributors, testers, and user believing in the project and helping make it a joy to work on.

Article Updates​

• 12/2023: Removed the deprecated label property from code snippets.

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

• Locate and delete the lines for the DTS output step, which is no longer needed:

  - name: ${{ steps.variables.outputs.display-name }} DTS File
    if: ${{ always() }}
    run: |
      if [ -f "build/zephyr/${{ matrix.board }}.pre.tmp" ]; then cat -n build/zephyr/${{ matrix.board }}.pre.tmp; fi
      if [ -f "build/zephyr/zephyr.dts" ]; then cat -n build/zephyr/zephyr.dts; fi
  

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 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 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 to a board, you now must also add the additional include #include <dt-bindings/led/led.h> at the top of your devicetree file, and add a color-mapping property like:

led_strip: ws2812@0 {
  compatible = "worldsemi,ws2812-spi";

  /* 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>;
};

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>;
    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";
  };
};

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.

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. 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.

Article Updates​

• 12/2023: Removed the deprecated label property from code snippets.

GitHub Actions needs to use our latest Docker image to ensure continued compatibility with the ZMK codebase on Zephyr 3.0 (and beyond). You should:

• 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

Once the changes are committed and pushed, the build will run as expected.

A future blog post will outline the complete Zephyr 3.0 changes once that work is finalized.

A big part of this work was some major refactors and improvements by innovaker to our zmk-docker Docker image and GH Actions automation.

• Faster build times with improved caching.
• Integration tests which automatically verify new images.
• PRs to the repo now build properly and run the tests as well.
• Build images for multiple target architectures, e.g. zmk-build-riscv64, all in parallel.
• Nightly builds to be sure we're pulling in the latest OS/package updates, to ensure we keep our images up to date, address any reported vulnerabilities, etc.
• Faster upgrade paths for future Zephyr SDK and Zephyr versions.

In addition, petejohanson did the upgrade work to adjust ZMK for the Zephyr changes.

• Updated to newer devicetree/driver Zephyr API
• Adjustment for Zephyr pinmux changes
• Fixes for power management, LVGL, and 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 2.5 automatically, and should work, fine as is. However, to upgrade to the newer Docker image, you should:

• Open .github/workflows/build.yml in your editor/IDE
• Change zmkfirmware/zmk-build-arm:2.4 to zmkfirmware/zmk-build-arm:2.5 wherever it is found

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 2.5 Docker image.

Local Host Development​

The following steps will get you building ZMK locally against Zephyr 2.5:

• Run the updated 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!

Thanks!​

Thanks again to innovaker for all the hard work, and to all the testers who have helped verify ZMK functionality on the newer Zephyr version.

This update will cover all the major activity since SOTF #3.

Recent Activity​

Here's a summary of the various major changes since last time, broken down by theme:

Keymaps/Behaviors​

Since last time, there have been several new powerful keymap features and behaviors added, including one of the most asked for features, combos!

Combos​

The initial combos work has landed! The amazing okke-formsma has once again delivered another powerful feature for ZMK. Combos are "position based", and are configured in a new toplevel node next to they keymap node in user's keymap files.

An example, that would send the ESC keycode when pressing both the first and second positions on your keyboard:

/ {
    combos {
        compatible = "zmk,combos";
        combo_esc {
            timeout-ms = <50>;
            key-positions = <0 1>;
            bindings = <&kp ESC>;
        };
    };
};

Sticky Keys (One-Shot Mods/Layers) Behavior​

okke-formsma also contributed the initial "sticky keys" behavior, which can be used for functionality sometimes called "one shot mods" or "one shot layers". In your keymap, this would like like:

&sk LEFT_CONTROL

for a sticky key/modifier, or:

&sl NAV

for a sticky layer.

&to Layer Behavior​

mcrosson contributed the new &to layer related behavior. This can be used to completely replace the active layer with a new one.

This is most frequently used when using multiple core base layers with different layouts, e.g. QWERTY and DVORAK, to switch between them.

Grave Escape Behavior​

okke-formsma added an implementation of the "Grave Escape" behavior, developing a more generic "mod-morph" behavior to do so. Adding

&gresc

to your keymap will send ESC when pressed on its own, but will send ` when pressed with a GUI or Shift modifier held.

RGB Underglow Color Selection​

mcrosson updated the RGB Underglow behavior to allow binding an explicit color selection to a key position.

Keymap Upgrader​

joelspadin completed the Keymap Upgrader which can be used to update your keymap to using the latest supported codes, and move away from the old deprecated codes.

If you've made keymap customizations, please make sure to run your keymaps through the upgrader, since the old deprecated codes will be removed in a future version of ZMK.

Displays​

There has been lots of work to get display support complete enough for use by end users. Although not quite ready for prime time, it is incredibly close, and we are looking forward to having the last few items completed and the feature documented!

Idle Blanking​

petejohanson added idle blanking for displays, which ensures they will go blank, and into low power mode, after a short period of inactivity from the user. This ensures we avoid burn-in for OLEDs, and helps improve battery life.

Battery and Output Widgets​

petejohanson implemented the first two complete, dynamic "widgets" for the displays for ZMK, adding a small battery indicator, which includes charging status, and a small output indicator, showing the currently active output (USB or BLE). When using BLE, the indicator also shows the active profile slot, as well as if the profile slot is open, awaiting connection from the paired host, or is actively connected to the host for that profile slot.

Highest Layer Display​

mcrosson has contributed the next display widget, showing the highest active layer in the keymap. petejohanson then added a small follow up to allow layers in keymaps to add a name property to each layer, e.g. name = "Nav"; and have that name be displayed in the widget instead of the numeric layer number.

WPM​

New contributor allymparker added our fourth widget, a words-per-minute display! This widget work also included creating the core state logic for tracking the WPM.

For now, this widget is only working on the central side of split keyboards.

Miscellaneous​

Zephyr 2.4​

innovaker is at it again with some crucial core fixes, helping prepare and test the upgrade of ZMK to Zephyr 2.4. The updated Zephyr release brings with it some key BLE stability fixes, as well as various other core improvements that improve ZMK. This was a huge undertaking!

BLE Deadlock Fixes​

petejohanson was heads down diagnosing and fixing a deadlock issue on BLE that was frustrating and plaguing many users. After finally pinpointing the underlying root cause, he developed a fix and roped in many testers on Discord to help stress test things before merging.

Central/Peripheral Selection​

Previously overriding the selection of left as central, and right as peripheral for wireless splits required making local edits to the configuration files, and maintaining them in a ZMK fork.

petejohanson updated the config files to allow users to override this in their <board>_left.conf/<board>_right.conf files in their user repos.

Improved Docker Containers​

As part of the Zephyr 2.4. prep work, innovaker, along with lots of testing and input from mcrosson, developed a brand new pair of Docker images which is now published to Docker Hub as zmkfirmware/zmk-build-arm and zmkfirmware/zmk-dev-arm.

The previously blogged VSCode + Docker integration, as well as our GH Action build automation was all moved over to the new images.

Settings Debounce​

nicell contributed settings debounce work, to help avoid unnecessary extra writes to flash when making various changes that should be saved, such as the active BLE profile, external VCC on/off, etc.

New Shields​

• Jorne & Jian in #331 - krikun98
• tidbit in #424 - mcrosson
• Helix in #429 - KingCoinless
• BFO-9000 in #472 - pbz
• CRBN in #493 - ReFil
• Eek in #529 - MangoIV

New Boards​

• BDN9 Rev2 in #557 - petejohanson

Sponsorship​

Since it's inception, quite a few users have inquired whether they could sponsor any of the contributors involved in ZMK. Although we are not intending to directly fund any individual contributors for their work on ZMK, there is good that can come from folks sponsoring ZMK.

You can see the full discussion on #497, but some items that are being considered with sponsorship funds:

• Hiring a designer to complete the logo/mascot work.
• Creating stickers to send as thank-yous to first time contributors.
• Hosting costs for GitHub Pro.
• Other hosting costs, e.g. Docker Hub.

For anyone looking to contribute, you can find the ZMK Firmware project is now set up on Open Collective.

Coming Soon!​

Some items listed in the last coming soon section are still under active development.

• A power profiler page for the website, to help users estimate their battery life for a given keyboard - Nicell
• Behavior "locality", allowing improved split usage for things like &sys_reset, and controlling external power and RGB underglow for both sides - petejohanson
• More modular approach to external boards/shields, custom code, user keymaps, etc.
• More shields and boards

Statistics​

Some statistics of interest for ZMK:

• GitHub (lifetime stats)
  • 389 Closed PRs
  • 199 Stars
  • 163 Forks
• Discord Chat
  • 702 total registered
• Website (last 30 days)
  • 11.5K page views
  • 1K new users

Thanks!​

Thanks again to the numerous contributors, testers, and users who have made working on ZMK such a pleasure!

Article Updates​

• 12/2023: The label property for keymap layers was renamed to display-name.

This update will cover all the major activity since SOTF #2. This edition comes a bit later than planned, but the amount of features and changes will hopefully make it worth it!

Recent Activity​

Here's a summary of the various major changes since last time, broken down by theme:

Keymaps/Behaviors​

Tons of activity related to keymaps, so we'll go into more detail this time.

Codes Overhaul​

innovaker completely overhauled the set of available codes for keymaps, and simultaneously has created beautiful documentation to help users visualize the codes, and also understand if they are supported on their particular operating system.

This also laid the foundation for the other keymap related changes that are now available.

Modified (Shifted) Codes​

okke-formsma added the ability to apply modifiers to a code, e.g.:

&kp LC(C)

which sends Control + c when pressed. This feature is often used on smaller keyboards to achieve "shifted keycodes", e.g. LS(N1) to send a !. To make this easier, in addition to all the normal codes, we now have defines for common shifted codes, e.g. EXCL for !, AT for @, etc.

To learn more, check out the Modifiers documentation.

Simplified Key Press Behavior​

In previous versions of ZMK, users needed to be careful to select between the &kp and &cp behaviors in their keymaps, depending on whether the particular keycode they wanted to send was in the "HID consumer page" or not. Forcing users to understand the difference and get this right was awkward and error prone.

petejohanson and innovaker have reduced this complexity. Users can now simply use &kp with all available codes and ZMK will handle sending the right events to the connected host.

Power Management​

Several important power management features have been added to ZMK, helping save power for many use cases.

BLE Battery Level Reporting​

Nicell added the necessary driver and core code to send BLE battery level notifications to hosts that support displaying them. Testing seems to show this works with Windows and GNOME, but macOS does not display the battery info.

External Power Control​

megamind4089 added a new driver and behavior to allow users to toggle (on/off) the external power supplied by boards such as the nRFMicro and nice!nano that have specialized hardware for this purpose.

With this change, you can add

&ext_power EP_TOG

to toggle (on/off) the power to external hardware like RGB underglow or OLEDs. Check out the external power control docs for more info.

Deep Sleep​

petejohanson has contributed the initial deep sleep support to ZMK. This work also included some automatic power savings by switching to PORT events on the nRF52 chips, which reduces the idle power draw, even without deep sleep. Deep sleep is currently not turned on by default, but will be soon.

Miscellaneous​

Output Selection​

joelspadin added output selection to allow selecting whether to send output over USB or BLE if both are connected. This should now help avoid having "double keypresses" when your keyboard is plugged into a host.

Bootloader Corruption Fix​

Nicell has already blogged about this, but for those that missed it, a major, and incredibly difficult to pin down bug involving corruption of the bootloader on devices using the Adafruit nRF52 bootloader has been fixed by Nicell. If you've encountered this bug, flashing the latest firmware should prevent it from reoccurring. Unfortunately, due to the nature of this fix, you will need to re-pair your keyboard with your hosts, as the fix involves changing where settings are stored in the flash of the controller.

Official USB Product ID​

petejohanson has gotten an official USB product ID assigned to the ZMK Firmware. For anyone looking to uniquely identify a USB device running the ZMK Firmware, you can match on:

• Vendor ID: 0x1d50
• Product ID: 0x615e

We are incredibly grateful that Openmoko Inc., in the wake of discontinuing the openmoko projects, has made this an option for OSS projects.

Development: Remote Docker Container Integration​

idan contributed VSCode devcontainer integration to make it easier for developers to build and develop ZMK without having to do complicated local toolchain setup and configuration. This also opens up some amazing future flexibility for things like GitHub Codespaces.

There's some follow up tweaks necessary for better supporting using this with user config repositories, which will be available soon.

New Shields​

• Reviung41 in #297 - Nicell
• Boardsource 3x4 in #296 - neegool
• NIBBLE in #292 - jaygreco
• Microdox in #245 - careyk007
• MakerDiary M60 in #233 - megamind4089
• TGX4 in #226 - mubeenkhan94
• Quefrency V1 in #216 - noar-t
• Cradio in #224 - davidphilipbarr
• Romac+ in #198 - reizero00

New Boards​

• MakerDiary nRF52840 M.2 Module in #233 - megamind4089

Testing​

There has been an amazing amount of testing from various users as we develop new features. In particular, we'd like to give a shout out to tominabox1 who has been tireless in providing detailed and thorough testing of changes as they are being developed.

Coming Soon!​

Some items listed in the last coming soon section are still under active development.

• OLED work, including battery and USB/BLE connection status - petejohanson
• One shot mod/layer behaviors - okke-formsma
• A power profiler page for the website, to help users estimate their battery life for a given keyboard - Nicell
• A keymap converter to automatically update keymaps to the new codes and use of &kp everywhere - joelspadin

Statistics​

Some statistics of interest for ZMK:

• GitHub (lifetime stats)
  • 210 Closed PRs
  • 116 Stars
  • 101 Forks
• Discord Chat
  • 363 total registered
• Website (last 30 days)
  • 8.5K page views
  • 766 new users

Thanks!​

Thanks again to the numerous contributors and users who have made working on ZMK such a pleasure!

Background​

What exactly is the "stuck in the bootloader" issue? Seemingly randomly, users' keyboards would suddenly stop working and when they would reset their keyboard they would get put into the bootloader instead of back into the firmware. This would require the user to re-flash the firmware again to get into the firmware. That wouldn't be so bad except for the fact that once this occurs, every reset would require the user to re-flash the firmware again. The only way to really fix this issue was to re-flash the bootloader itself, which is a huge pain.

Going into this, all we knew was that this issue was most likely introduced somewhere in the #133, which added Bluetooth profile management. We've had quite a few attempts at trying to recreate the issue, but we never were able to get it to happen consistently.

Diagnosing the issue​

This issue had been happening sporadically for the past month, and I finally decided to dig in to see what was going on. We started in the Discord and discussed what was common between all of the people who have experienced this issue. Everyone who had this issue reported that they did quite a bit of profile switching. This lined up with the possible connection to the Bluetooth profile management pull request.

Pinpointing the cause​

I had a hunch that this was related to the settings system. The settings system is used by profile Bluetooth switching, and the settings system works directly with the system flash. Based on this hunch, I tried spamming the RGB underglow cycle behavior on my main keyboard. Sure enough after a couple minutes, I got stuck in the bootloader. I was even able to reproduce it again.

This was an important discovery for two reasons. First, I was able to recreate the issue consistently, which meant I could set up logging and more closely monitor what the board was doing. Second, this more or less proved that it was specifically the settings system at fault. Both Bluetooth profile switching and RGB underglow cycling trigger it, and the one common piece is they save their state to settings.

Settings system overview​

To understand what's going wrong, we first need to understand how the settings system works. Here's a diagram to explain the flash space that the settings system holds for our nRF52840 based boards (nice!nano, nRFMicro, BlueMicro).

The settings flash space lives at the end of the flash of the chip. In this case it starts at 0xF8000 and is 0x8000 bytes long, which is 32KB in more comprehensible units. Then due to the chip's architecture, this flash space is broken into pages, which are 0x1000 bytes in size (4KB).

The backend that carries out the settings save and read operation in ZMK is called NVS. NVS calls these pages sectors. Due to how flash works, you can't write to the same bytes multiple times without erasing them first, and to erase bytes, you need to erase the entire sector of flash. This means when NVS writes to the settings flash if there's no erased space available for the new value, it will need to erase a sector.

Logging discoveries​

So first I enabled logging of the NVS module by adding CONFIG_NVS_LOG_LEVEL_DBG=y to my .conf file. I repeated the same test of spamming RGB underglow effect cycle and the resulting logs I got were this:

[00:00:00.000,671] <inf> fs_nvs: 8 Sectors of 4096 bytes
[00:00:00.000,671] <inf> fs_nvs: alloc wra: 3, f70
[00:00:00.000,671] <inf> fs_nvs: data wra: 3, f40
// A bunch of effect cycle spam
[00:02:34.781,188] <dbg> fs_nvs: Erasing flash at fd000, len 4096
// A bunch more effect cycle spam
[00:06:42.219,970] <dbg> fs_nvs: Erasing flash at ff000, len 4096
// A bunch more effect cycle spam
// KABOOM - bootloader issue

So at start up, we can see that the 8 sectors of 4KB are found by NVS properly, however, I wasn't sure what the second and third lines meant, but we'll get back to that. Nonetheless the next two logs from NVS showed erasing the sector at 0xFD000 and then erasing the 0xFF000 sector.

It's really odd that the third to last sector and the last sector are erased, and then shortly after the bootloader issue is hit. I really had no explanation for this behavior.

Reaching out to Zephyr​

At this point, I nor anyone else working on the ZMK project knew enough about NVS to explain what was going on here. Pete Johanson, project founder, reached out on the Zephyr Project's Slack (ZMK is built on top of Zephyr if you weren't aware). Justin B and Laczen assisted by first explaining that those alloc wra and data wra logs from earlier are showing what data NVS found at startup.

More specifically, data wra should be 0 when it first starts up on a clean flash. As we can see from my earlier logging on a clean flash I was instead getting f40. NVS is finding data in our settings sectors when they should be blank! We were then given the advice to double check our bootloader.

The Adafruit nRF52 Bootloader​

Most of the boards the contributors of ZMK use have the Adafruit nRF52 Bootloader, which allows for extremely easy flashing by dragging and dropping .uf2 files onto the board as a USB drive. Every bootloader takes up a portion of the flash, and in the README explains that the first 0x26000 is reserved for the bootloader with the nRF52840, and we've properly allocated that.

However, there isn't a full explanation of the flash allocation of the bootloader in the README. There's a possibility that the bootloader is using part of the same flash area we're using. I reached out on the Adafruit Discord, and Dan Halbert pointed me towards the linker map of the nRF52840. Let's take a look.

FLASH (rx) : ORIGIN = 0xF4000, LENGTH = 0xFE000-0xF4000-2048 /* 38 KB */

BOOTLOADER_CONFIG (r): ORIGIN = 0xFE000 - 2048, LENGTH = 2048

/** Location of mbr params page in flash. */
MBR_PARAMS_PAGE (rw) : ORIGIN = 0xFE000, LENGTH = 0x1000

/** Location of bootloader setting in flash. */
BOOTLOADER_SETTINGS (rw) : ORIGIN = 0xFF000, LENGTH = 0x1000

Here's a diagram to show this a bit better.

We've found the issue! As you can see from the red bar (representing our settings flash area), we've put the settings flash area right on top of the Adafruit bootloader's flash space. Oops!

This also shines some light on why NVS erased 0xFD000 and 0xFF000 sectors. It's possible there was no flash written to 0xFD000 because the bootloader didn't use up all of that space it has, and then there possibly weren't any bootloader settings set yet, so 0xFF000 could be used and erased by NVS too.

After erasing 0xFF000, NVS probably next erased a rather important part of the bootloader that resulted in this issue at hand. In my opinion, we're pretty lucky that it didn't delete an even more vital part of the bootloader. At least we could still get to it, so that we could re-flash the bootloader easily!

The solution​

Now that we've found the issue, we can pretty easily fix this. We'll need to move the settings flash area back so that it doesn't overlap with the bootloader. First we calculate the size of the of flash area the bootloader is using.

0x100000 (end of flash) - 0x0F4000 (start of bootloader) = 0xC000 (48KB)

So the bootloader is using the last 48KB of the flash, this means all we need to do is shift back the settings area and code space 0xC000 bytes. We'll apply this to all of the .dts files for the boards that were affected by this issue.

        code_partition: partition@26000 {
-           reg = <0x00026000 0x000d2000>;
+           reg = <0x00026000 0x000c6000>;
        };


-       storage_partition: partition@f8000 {
+       storage_partition: partition@ec000 {
-           reg = <0x000f8000 0x00008000>;
+           reg = <0x000ec000 0x00008000>;
        };

And with those changes, we should no longer run into this issue! In the process of these changes, we lost 48KB of space for application code, but we're only using around 20% of it anyways. 🎉

Article Updates​

• 12/2023: Removed the deprecated label property from code snippets.

This update will cover all the major activity since SOTF #1, preparations for the upcoming Hacktoberfest activity, and a current open call for community feedback on a ZMK mascot.

Recent Activity​

So much going on in ZMK!

• Added a new generic Hold Tap behavior in #146 which now powers mod-tap, layer-tap, etc. - okke-formsma
• BLE profile/connection management in #133 - petejohanson
• Integration tests were added to automate testing of behaviors in #131 by BrainWart & petejohanson
• Toggle layer behavior, e.g. &tog LOWER, in #98 - BrainWart
• Key fix for dropped press/release over HID #93/#96 - careyk007 & petejohanson
• Code formatting standardized using clang-format in #183 - petejohanson
• Bootloader reset behavior, e.g. &bootloader, in #116 - petejohanson
• Various bug fixes and documentation

New Shields​

• QAZ in #130 - tominabox1
• Iris in #151 - kurtis-lew
• RoMac 2.1 in #122 - bmcgavin
• Sofle in #118 - CrossR
• splitreus62 in #92 - Na-Cly

New Boards​

• DZ60RGB rev1 in #166 - Nicell
• nrfMicro in #101 - okke-formsma
• BlueMicro840 #91 - Na-Cly

Hacktoberfest Preparation​

Hacktoberfest is a yearly celebration of open source, which encourages participation in OSS, especially from new contributors.

The ZMK contributors have been busy preparing for folks to join in on the fun by contributing to ZMK!

• There is now a basic Contributing Guide to help newcomers get oriented, and get up to speed.
• The Hacktoberfest issue label will help participants discover good issues to work on. (The existing good first issue label also helps with this)

We're looking forward to the launch of Hacktoberfest!

Mascot Selection Feedback​

The ZMK project would like to settle on a mascot! We're soliciting community feedback as part of the process before a final mascot is selected.

The current mascots up for consideration are:

• Griffin
• Peregrine Falcon
• Zapata Wren
• Zorro (south american fox)

If you're interested in helping with the decision, head over to Issue #195 and add a reaction!

Coming Soon!​

There still lots of activity in ZMK, and plenty of exciting upcoming changes.

• Improved modifier infrastructure, including "shifted keycodes" - okke-formsma
• Battery percentage reporting over BLE - Nicell
• Complete defines for HID keycodes/usage IDs - innovaker
• Additional core BLE connection/bond management work - petejohanson
• Improved power management - petejohanson, Nicell
• One shot mod/layer behaviors - okke-formsma

Statistics​

Some statistics of interest for ZMK:

• GitHub
  • 115 Closed PRs
  • 64 Stars
  • 48 Forks
• Discord Chat
  • 186 total registered
• Website (last 30 days)
  • 7.4K page views
  • 474 new users

Thanks!​

Thanks again to the numerous contributors and users who have made working on ZMK such a pleasure!