refactor(core): Adjust our approach for upstream Zephyr boards

[petejohanson]

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.

I've updated a few docs as part of this to note the variant change:

• https://deploy-preview-3145--zmk.netlify.app/blog/2025/12/09/zephyr-4-1#zmk-board-variant
• https://deploy-preview-3145--zmk.netlify.app/docs/hardware

PR check-list

• Branch has a clean commit history
• Additional tests are included, if changing behaviors/core code that is testable.
• Proper Copyright + License headers added to applicable files (Generally, we stick to "The ZMK Contributors" for copyrights to help avoid churn when files get edited)
• Pre-commit used to check formatting of files, commit messages, etc.
• Includes any necessary documentation changes.

[nmunnich]

Re: discussion on user clarity: do you think it might make sense to introduce //zmk variants for our in-tree boards which are also interconnects, and use the base version as something that matches what Zephyr would accept?

So we would have

• boards which are also keyboards, name without //zmk
• interconnect boards without tweaks, regardless of being in Zephyr or ZMK name without //zmk
• interconnect boards with tweaks, name always with //zmk

[petejohanson]

Re: discussion on user clarity: do you think it might make sense to introduce //zmk variants for our in-tree boards which are also interconnects, and use the base version as something that matches what Zephyr would accept?

I have been debating this internally for quite some time now. There guiding principles, as I see them, for this discussion, should be:

• Clean expectation setting for users of ZMK, that is as intuitive as possible, and as well documented/supported by tooling as possible where things are less intuitive.
• Promote flexibility and re-use (e.g. right now it's hard to build a Zephyr sample for something like the nice!60, since the ZMK specific headers, etc cause problems) that allows boards to be used very flexibly, we can easily use upstream boards for various users without random things dragged in that break things, etc.
• Minimizing breakage, or at least consolidating it into one release (we're already going to have this with the planned v0.4, so further refactors in main to satisfy the first two bullets are worth it now, IMHO)

So we would have

* boards which are also keyboards, name without //zmk

So... If we do this, we perpetuate the existing challenges here, where you can't flash basic Zephyr samples to our "keyboard boards" from ZMK, without hacking apart the .dts files temporarily. Not a huge deal, but if we're putting in this effort, it might be worth improving this. I find this useful for targetted "get this display working" or "test the RGB" or "verify this sensor".

* interconnect boards without tweaks, regardless of being in Zephyr or ZMK name without //zmk

Define "tweaks" here. At a minimum, we usually have the following changes that differ from upstream:

• Enabling one or more HID transports.
• Defining settings storage (many upstream boards do this, but not all, and many of those do so with an MCUBoot style partition setup) in devicetree and enabling related Kconfig OOTB for those boards.
• (Newer) Bootloader/retained boot mode setup by default.

* interconnect boards with tweaks, name always with //zmk

If we do this, I think we may introduce confusing for users, surrounding when and when not to use a zmk variant specifier.

Appreciate you helping brainstorm and nail this down!

[nmunnich]

I 100% agree with the guiding principles.

So... If we do this, we perpetuate the existing challenges here, where you can't flash basic Zephyr samples to our "keyboard boards" from ZMK, without hacking apart the .dts files temporarily. Not a huge deal, but if we're putting in this effort, it might be worth improving this. I find this useful for targetted "get this display working" or "test the RGB" or "verify this sensor".

I could certainly be convinced to have //zmk variants for all of our boards, so that we could flash Zephyr samples to them. My concern here is mainly around out-of-tree boards. I think for boards which are also interconnects, we can generally be convinced to add them in-tree of ZMK, if Zephyr does not accept them already, so my expectation is that out-of-tree boards are mostly just keyboards. Considering how much chaos and inconsistency there already is around out-of-tree boards, I see some value in keeping the expected definition for such boards simpler. I could really go either way, though.

Define "tweaks" here.

Essentially what you listed, though we also usually disable the UART node. I see an extra benefit of the separation as making it much easier to upstream boards to Zephyr since the definition has already been written, if a board gains popularity/prominence enough that it would be accepted.

If we do this, I think we may introduce confusing for users, surrounding when and when not to use a zmk variant specifier.

I actually see the opposite: End users would be taught "If you have a board+shield combo, your board always has a //zmk at the end", without needing to look things up. The finer details would be more for advanced users.

[petejohanson]

I 100% agree with the guiding principles.

So... If we do this, we perpetuate the existing challenges here, where you can't flash basic Zephyr samples to our "keyboard boards" from ZMK, without hacking apart the .dts files temporarily. Not a huge deal, but if we're putting in this effort, it might be worth improving this. I find this useful for targetted "get this display working" or "test the RGB" or "verify this sensor".

I could certainly be convinced to have //zmk variants for all of our boards, so that we could flash Zephyr samples to them. My concern here is mainly around out-of-tree boards. I think for boards which are also interconnects, we can generally be convinced to add them in-tree of ZMK, if Zephyr does not accept them already, so my expectation is that out-of-tree boards are mostly just keyboards. Considering how much chaos and inconsistency there already is around out-of-tree boards, I see some value in keeping the expected definition for such boards simpler. I could really go either way, though.

Having tried this just the past couple days while playing with my stm32c0pad prototype, I can definitely say that having a "Zephyr compatible" based board for it was really helpful, and that adding a zmk variant was not a significant additional effort.

Not that I think we should expect everyone to do this with every board definition, but it might be nice to document it as an option for folks to follow.

Not sure how best to communicate this to users though? For sure, listing the //zmk variant in the .zmk.yml files is a good first start, with integration with the ZMK CLI helping here.

Define "tweaks" here.

Essentially what you listed, though we also usually disable the UART node. I see an extra benefit of the separation as making it much easier to upstream boards to Zephyr since the definition has already been written, if a board gains popularity/prominence enough that it would be accepted.

👍

If we do this, I think we may introduce confusing for users, surrounding when and when not to use a zmk variant specifier.

I actually see the opposite: End users would be taught "If you have a board+shield combo, your board always has a //zmk at the end", without needing to look things up. The finer details would be more for advanced users.

I think my only real concern here, is where we draw the line for "accepting boards that support some interconnect", if we want to have that really be consistent/enforced.... The lemon controllers ? Halcyon? How about the tenth random RP2040 board we theoretically support? I'd love to have some planning around what that really looks like.

I do think that your proposed "user expectation" does seem like it would be nice to get to. How do we do so?

[nmunnich]

Not that I think we should expect everyone to do this with every board definition, but it might be nice to document it as an option for folks to follow.

Not sure how best to communicate this to users though? For sure, listing the //zmk variant in the .zmk.yml files is a good first start, with integration with the ZMK CLI helping here.

I do think that your proposed "user expectation" does seem like it would be nice to get to. How do we do so?

Proposed plan:

• All in-tree boards get a //zmk variant
• We introduce a Kconfig flag that gets set in the variants (CONFIG_ZMK?). During build time we have the ZMK app check for this flag and throw a warning in the build process, something like "You are building ZMK firmware with a board that is missing ZMK-specific tweaks. You may experience some unexpected behavior. Have you checked if there is a <your_board>//zmk variant of your board?"
• The blog post and docs are updated to have //zmk everywhere, and we add a "patch note" to the blog post
• Probably we should adjust our supported hardware script to list boards which don't have in-tree shields as well.
• We add a "New board" page under hardware integration, which essentially states "Go to Zephyr and follow their instructions exactly to create a Zephyr board. <before continuing, here are some helpful Zephyr sample apps that you can flash to your board to ensure things are working at this point> Then return here for instructions on making a //zmk variant of your board with ZMK-specific tweaks allowing for Studio etc. If your board is a keyboard, once you've made the //zmk variant, take guidance (but don't follow exactly) the steps in the new shield guide to add a kscan etc."

I think my only real concern here, is where we draw the line for "accepting boards that support some interconnect", if we want to have that really be consistent/enforced.... The lemon controllers ? Halcyon? How about the tenth random RP2040 board we theoretically support? I'd love to have some planning around what that really looks like.

I edited this reply to open #3172 for this discussion instead, for better organisation.

[petejohanson]

Proposed plan:

* All in-tree boards get a //zmk variant

Including "complete keyboards", that only ever are used with ZMK? We refactor so they can be used with Zephyr directly with the "stock" variant?

[caksoylar]

It seems that (some?) board extensions are currently broken on main:

> west build -b sparkfun_pro_micro_rp2040 -d build/rp2040-test -- -DSHIELD=naked60
> grep CONFIG_ZMK_USB build/rp2040-test/zephyr/.config
# CONFIG_ZMK_USB is not set

@carrefinho also reported that board extensions are not applied on all boards whose name starts with vendor name, like adafruit_kb2040, boardsource_blok.

Do we want to fix that or get this in quicker?

[petejohanson]

It seems that (some?) board extensions are currently broken on main:

> west build -b sparkfun_pro_micro_rp2040 -d build/rp2040-test -- -DSHIELD=naked60
> grep CONFIG_ZMK_USB build/rp2040-test/zephyr/.config
# CONFIG_ZMK_USB is not set

@carrefinho also reported that board extensions are not applied on all boards whose name starts with vendor name, like adafruit_kb2040, boardsource_blok.

Do we want to fix that or get this in quicker?

We'll fix that here. Anyone with issues can pin to v0.3 in the meantime.

[petejohanson]

Ok, I've just pushed fixes for the nRFMicro to create a "vanilla" board definition for it in the app/module/ directory, that's completely ZMK-free, and then use the same HWMv2 extension approach to add ZMK variants.

With this. you can now do:

west build -p -d build/nrfmicro_hello_world -b nrfmicro/nrf52840 samples/hello_world -- -DBOARD_ROOT=/home/peter/git/zmk/app/module

from within the Zephyr repo. I'm not sure that this whole process is completely necessary for every in-tree keyboard board, e.g. nice!60, I think there we would only have the /zmk variant for those living in their existing location in app/boards/.

[joelspadin]

Leftover debug code

[joelspadin]

What directory are all these includes relative to?

[joelspadin]

Is having two variants with the same name okay?

[joelspadin]

On most of the other boards, the ZMK-specific configs were pulled out into a board extension. Was putting these in the base board definition here intentional?

[nmunnich]

Building this one with the tester I get

CMake Warning at /workspaces/zmk/zephyr/cmake/modules/dts.cmake:425 (message):
  dtc raised one or more warnings:

  /workspaces/zmk/app/build/zephyr/zephyr.dts:39.26-42.5: Warning
  (simple_bus_reg): /soc/memory@20000000: simple-bus unit address format
  error, expected "20000004"

Doesn't occur on the non //zmk version. No idea about the effects, haven't delved deep at all. Seems to apply to some of the others as well