mirror of
https://github.com/zmkfirmware/zmk.git
synced 2026-03-20 04:55:20 -05:00
refactor(core): Adjust our approach for upstream Zephyr boards (#3145)
refactor(core): Adjust our approach for upstream Zephyr boards Move to using proper HWMv2 board extensions https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#board-extensions for extending upstream Zephyr boards for use with ZMK. With this change, using upstream Zephyr board IDs directly, e.g. `seeeduino_xiao` will be stock versions as found upstream. To use a board variant that is tuned for ZMK use, use the `zmk` variant, e.g. `seeeduino_xiao//zmk` which is shorthand for `seeeduino_xiao/samd21g18a/zmk`. refactor(boards): Move to ZMK specific variants for the nRFMicro board For consistency, adjust the nRFMicro board definition to offer a "vanilla" Zephyr board, and then ZMK variants, e.g. `nrfmicro/nrf52840/zmk`. refactor(boards): Move to ZMK specific variant for the bluemicro840 board For consistency, adjust the bluemicro840 board definition to offer a "vanilla" Zephyr board, and then ZMK variant, e.g. `bluemicro840//zmk`. refactor(boards): Make tofu65 to ZMK variant by default Make the standard Tofu65 board ID be `tofu65/rp2040/zmk` or `tofu65//zmk` by shorthand. refactor(boards): Move BDN9 to ZMK variant by default Make the standard BDN9 board ID be `bdn9/stm32f072xb/zmk` or `bdn9//zmk` by shorthand. refactor(boards): Move Puchi BLE to ZMK variant by default Make the standard Puchi BLE board ID be `puchi_ble/nrf52840/zmk` or `puchi_ble//zmk` by shorthand. refactor(boards): Move Adv360 Pro to ZMK variant by default Make the standard Adv360 Pro board ID be `adv360pro_left/nrf52840/zmk` or `adv360pro_left//zmk` by shorthand and for right as well. refactor(boards): Move nRF52840 M2 to ZMK variant by default Make the standard nRF52840 M2 board ID be `nrf52840_m2/nrf52840/zmk` or `nrf52840_m2//zmk` by shorthand. refactor(boards): Move Pillbug to ZMK variant by default Make the standard Pillbug board ID be `pillbug/nrf52840/zmk` or `pillbug//zmk` by shorthand. refactor(boards): Move s40nc to ZMK variant by default Make the standard s40nc board ID be `s40nc/nrf52840/zmk` or `s40nc//zmk` by shorthand. refactor(boards): Move nice!60 to ZMK variant by default Make the standard nice!60 board ID be `nice60/nrf52840/zmk` or `nice60//zmk` by shorthand. refactor(boards): Move planck to ZMK variant by default Make the standard planck board ID be `planck/stm32f303xc/zmk` or `planck//zmk` by shorthand. refactor(boards): Move preonic to ZMK variant by default Make the standard preonic board ID be `preonic/stm32f303xc/zmk` or `preonic//zmk` by shorthand. refactor(boards): Move ferris to ZMK variant by default Make the standard ferris board ID be `ferris/stm32f072xb/zmk` or `ferris//zmk` by shorthand. refactor(boards): Move Proton-C to ZMK variant by default Make the standard Proton-C board ID be `proton_c/stm32f303xc/zmk` or `proton_c//zmk` by shorthand. refactor(boards): Move Corneish Zen to ZMK variant by default Make the standard Corneish Zen board ID be `corneish_zen_left/nrf52840/zmk` or `corneish_zen_left//zmk` by shorthand and for right as well. refactor(boards): Move nice!nano to ZMK variant by default Make the standard nice!nano board ID be `nice_nano/nrf52840/zmk` or `nice_nano//zmk` by shorthand. refactor(boards): Move mikoto to ZMK variant by default Make the standard mikoto board ID be `mikoto/nrf52840/zmk` or `mikoto//zmk` by shorthand. refactor(boards): Move Polarity Works boards to ZMK variants Make the standard Polarity Works board IDs be `zmk` variants. doc: Update docs/blog post to reference ZMK variants * Update Zephyr 4.1 blog post to mention ZMK variants * Add note to hardware support page about variants docs: Fix up shield board overlays for new board IDs Adjust our documentation to properly use the correct qualified board overlay file names that match our new board conventions.
This commit is contained in:
Pete Johanson
GitHub
@@ -8,6 +8,14 @@ We're happy to announce that after a long wait, ZMK's `main` branch is now runni
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
:::note
|
||||
|
||||
The following changes have been made since this blog post was originally published:
|
||||
|
||||
- The [move to `zmk` variants by default](https://github.com/zmkfirmware/zmk/pull/3145) for ZMK boards was documented.
|
||||
|
||||
:::
|
||||
|
||||
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](https://docs.zephyrproject.org/4.1.0/boards/index.html#boards).
|
||||
@@ -61,6 +69,12 @@ The following steps will get you building ZMK locally against Zephyr 4.1:
|
||||
|
||||
From there, you should be ready to build as normal!
|
||||
|
||||
## ZMK Board Variant
|
||||
|
||||
The new Zephyr version includes a [standard mechanism for extending boards](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#board-extensions) 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](https://docs.zephyrproject.org/4.1.0/hardware/porting/board_porting.html#board-terminology) 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.
|
||||
|
||||
@@ -11,7 +11,7 @@ See the documentation page on [pin control](../pinctrl.mdx) for detailed informa
|
||||
|
||||
Shields written for boards which support RGB underglow should add a `boards/` folder underneath the shield folder. Inside this `boards/` folder, create a `<board>.overlay` for any of the boards the shield can be used with. Place all hardware-specific configurations in these `.overlay` files.
|
||||
|
||||
For example: the `kyria` shield has a [`boards/nice_nano.overlay`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/boards/nice_nano.overlay) and a [`boards/nrfmicro_13.overlay`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/boards/nrfmicro_13.overlay), which configure a WS2812 LED strip for the `nice_nano` and `nrfmicro_13` boards respectively.
|
||||
For example: the `kyria` shield has a [`boards/nice_nano_nrf52840_zmk.overlay`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/boards/nice_nano_nrf52840_zmk.overlay) and a [`boards/nrfmicro_nrf52840_zmk_1_3_0.overlay`](https://github.com/zmkfirmware/zmk/blob/main/app/boards/shields/kyria/boards/nrfmicro_nrf52840_zmk_1_3_0.overlay), which configure a WS2812 LED strip for the `nice_nano/nrf52840/zmk` and `nrfmicro@1.3.0/nrf52840/zmk` boards respectively.
|
||||
|
||||
### nRF52-Based Boards
|
||||
|
||||
|
||||
@@ -27,9 +27,8 @@ Pin control is always defined for a _board_, never for a shield:
|
||||
```plaintext
|
||||
boards/shields/sofle/
|
||||
├── boards/
|
||||
│ ├── nice_nano.overlay
|
||||
│ ├── nrfmicro_11.overlay
|
||||
│ └── nrfmicro_13.overlay
|
||||
│ ├── nice_nano_nrf52840_zmk.overlay
|
||||
│ ├── nrfmicro_nrf52840_zmk_1_3_0.overlay
|
||||
└── <sofle shield defining files>
|
||||
```
|
||||
Note that you will need to define a separate overlay _for each_ of the boards to be used with the shield.
|
||||
|
||||
@@ -44,6 +44,12 @@ With the solid technical foundation of Zephyr™ RTOS, ZMK can support a wide di
|
||||
including but not limited to Nordic nRF52, Raspberry Pi RP2040/RP2350, most ST STM32 MCUs, and Microchip SAMD21.
|
||||
That being said, there are specific [boards / shields](development/hardware-integration/index.mdx#boards--shields) that have been implemented and tested by the ZMK contributors, listed below.
|
||||
|
||||
:::note
|
||||
|
||||
With the [upgrade to Zephyr 4.1](/blog/2025/12/09/zephyr-4-1#zmk-board-variant), the ZMK project has moved all in-tree boards to use a `zmk` [board variant](https://docs.zephyrproject.org/4.1.0/glossary.html#term-variant), for consistency when distinguishing from stock boards that are actually in upstream Zephyr.
|
||||
|
||||
:::
|
||||
|
||||
<HardwareList items={Metadata} />
|
||||
|
||||
{/* prettier-ignore */}
|
||||
|
||||
Reference in New Issue
Block a user