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.

app/boards/seeed/seeeduino_xiao/board.yml

@@ -0,0 +1,5 @@
+board:
+  extend: seeeduino_xiao
+  variants:
+    - name: zmk
+      qualifier: samd21g18a

app/boards/seeed/seeeduino_xiao/seeeduino_xiao.zmk.yml

@@ -1,5 +1,5 @@
 file_format: "1"
-id: seeeduino_xiao
+id: seeeduino_xiao//zmk
 name: Seeed Studio XIAO SAMD21
 type: board
 arch: arm

app/boards/seeed/seeeduino_xiao/seeeduino_xiao_zmk.dts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2026 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <../boards/seeed/seeeduino_xiao/seeeduino_xiao.dts>
+

app/boards/seeed/seeeduino_xiao/seeeduino_xiao_zmk_defconfig

@@ -0,0 +1,11 @@
+# XTAL setup
+CONFIG_SOC_ATMEL_SAMD_XOSC32K=y
+CONFIG_SOC_ATMEL_SAMD_XOSC32K_AS_MAIN=y
+
+# Bootloader Setup
+CONFIG_BUILD_OUTPUT_UF2=y
+CONFIG_BOOTLOADER_BOSSA=y
+CONFIG_BOOTLOADER_BOSSA_ADAFRUIT_UF2=y
+
+# ZMK USB Transport
+CONFIG_ZMK_USB=y

app/boards/seeed/xiao_ble/board.yml

@@ -0,0 +1,5 @@
+board:
+  extend: xiao_ble
+  variants:
+    - name: zmk
+      qualifier: nrf52840

app/boards/seeed/xiao_ble/xiao_ble.zmk.yml

@@ -1,5 +1,5 @@
 file_format: "1"
-id: xiao_ble
+id: xiao_ble//zmk
 name: Seeed Studio XIAO nRF52840
 type: board
 arch: arm

app/boards/seeed/xiao_ble/xiao_ble_zmk.dts

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2021 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <../boards/seeed/xiao_ble/xiao_ble.dts>
+#include <common/nordic/nrf52840_uf2_boot_mode.dtsi>
+
+/* Add an sd_partition label for compatibility with the nosd snippet */
+sd_partition: &reserved_partition_0 { };
+
+/ {
+    chosen {
+        zmk,battery = &vbatt;
+    };
+
+    vbatt: vbatt {
+        compatible = "zmk,battery-voltage-divider";
+        io-channels = <&adc 7>;
+        power-gpios = <&gpio0 14 (GPIO_OPEN_DRAIN | GPIO_ACTIVE_LOW)>;
+        output-ohms = <510000>;
+        full-ohms = <(1000000 + 510000)>;
+    };
+};
+
+&xiao_serial { status = "disabled"; };
+
+&adc {
+    status = "okay";
+};
+
+&qspi {
+    status = "okay";
+    pinctrl-0 = <&qspi_default>;
+    pinctrl-1 = <&qspi_sleep>;
+    pinctrl-names = "default", "sleep";
+    p25q16h: p25q16h@0 {
+        compatible = "nordic,qspi-nor";
+        reg = <0>;
+        sck-frequency = <104000000>;
+        quad-enable-requirements = "S2B1v1";
+        jedec-id = [85 60 15];
+        sfdp-bfp = [
+            e5 20 f1 ff  ff ff ff 00  44 eb 08 6b  08 3b 80 bb
+            ee ff ff ff  ff ff 00 ff  ff ff 00 ff  0c 20 0f 52
+            10 d8 08 81
+        ];
+        size = <16777216>;
+        has-dpd;
+        t-enter-dpd = <3000>;
+        t-exit-dpd = <8000>;
+    };
+};

app/boards/seeed/xiao_ble/xiao_ble_zmk_defconfig

@@ -0,0 +1,30 @@
+
+# Enable MPU
+CONFIG_ARM_MPU=y
+
+# Enable hardware stack protection
+CONFIG_HW_STACK_PROTECTION=y
+
+# Enable GPIO
+CONFIG_GPIO=y
+
+CONFIG_ZMK_USB=y
+CONFIG_ZMK_BLE=y
+
+# Build UF2 by default, supported by the Adafruit nRF52 Bootloader
+CONFIG_BUILD_OUTPUT_UF2=y
+CONFIG_USE_DT_CODE_PARTITION=y
+
+# Settings Support
+CONFIG_MPU_ALLOW_FLASH_WRITE=y
+CONFIG_NVS=y
+CONFIG_SETTINGS_NVS=y
+CONFIG_FLASH=y
+CONFIG_FLASH_PAGE_LAYOUT=y
+CONFIG_FLASH_MAP=y
+
+# Bootloader Support
+CONFIG_RETAINED_MEM=y
+CONFIG_RETENTION=y
+CONFIG_RETENTION_BOOT_MODE=y
+CONFIG_ZMK_BOOTMODE_MAGIC_VALUE_BOOTLOADER_TYPE_ADAFRUIT_NRF52=y

app/boards/seeed/xiao_rp2040/board.yml

@@ -0,0 +1,5 @@
+board:
+  extend: xiao_rp2040
+  variants:
+    - name: zmk
+      qualifier: rp2040

app/boards/seeed/xiao_rp2040/xiao_rp2040.zmk.yml

@@ -1,5 +1,5 @@
 file_format: "1"
-id: xiao_rp2040
+id: xiao_rp2040//zmk
 name: Seeed Studio XIAO RP2040
 type: board
 arch: arm

app/boards/seeed/xiao_rp2040/xiao_rp2040_zmk.dts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2023 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <../boards/seeed/xiao_rp2040/xiao_rp2040.dts>
+#include <arm/raspberrypi/rp2040-boot-mode-retention.dtsi>
+
+&xiao_serial { status = "disabled"; };
+
+&code_partition {
+    reg = <0x100 (DT_SIZE_M(2) - 0x100 - DT_SIZE_K(512))>;
+};
+
+&flash0 {
+    reg = <0x10000000 DT_SIZE_M(2)>;
+
+    partitions {
+        storage_partition: partition@180000 {
+            reg = <0x180000 DT_SIZE_K(512)>;
+            read-only;
+        };
+    };
+};

app/boards/seeed/xiao_rp2040/xiao_rp2040_zmk_defconfig

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: MIT
+
+CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC=125000000
+CONFIG_RESET=y
+
+# Enable clock control by default
+CONFIG_CLOCK_CONTROL=y
+
+# Code partition needed to target the correct flash range
+CONFIG_USE_DT_CODE_PARTITION=y
+
+# Output UF2 by default, native bootloader supports it.
+CONFIG_BUILD_OUTPUT_UF2=y
+
+# Enable USB HID transport by default
+CONFIG_ZMK_USB=y
+
+# Settings Enablement
+CONFIG_MPU_ALLOW_FLASH_WRITE=y
+CONFIG_NVS=y
+CONFIG_SETTINGS_NVS=y
+CONFIG_FLASH=y
+CONFIG_FLASH_PAGE_LAYOUT=y
+CONFIG_FLASH_MAP=y
+
+
+# Bootloader support
+CONFIG_RETAINED_MEM=y
+CONFIG_RETENTION=y
+CONFIG_RETENTION_BOOT_MODE=y