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/module/boards/keycapsss/puchi_ble/CMakeLists.txt

@@ -0,0 +1,3 @@
+zephyr_library()
+zephyr_library_sources(pinmux.c)
+zephyr_library_include_directories(${ZEPHYR_BASE}/drivers)

app/module/boards/keycapsss/puchi_ble/Kconfig

@@ -0,0 +1,3 @@
+# Copyright (c) 2022 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+

app/module/boards/keycapsss/puchi_ble/Kconfig.defconfig

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+if BOARD_PUCHI_BLE
+
+config BOARD
+    default "puchi_ble"
+
+if USB_DEVICE_STACK
+
+config USB_NRFX
+    default y
+
+endif # USB_DEVICE_STACK
+
+endif # BOARD_PUCHI_BLE

app/module/boards/keycapsss/puchi_ble/Kconfig.puchi_ble

@@ -0,0 +1,10 @@
+# Puchi-BLE board configuration
+
+# Copyright (c) 2026 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+config BOARD_PUCHI_BLE
+    select SOC_NRF52840_QIAA
+    imply RETAINED_MEM
+    imply RETENTION
+    imply RETENTION_BOOT_MODE

app/module/boards/keycapsss/puchi_ble/arduino_pro_micro_pins.dtsi

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+
+/ {
+    pro_micro: connector {
+        compatible = "arduino-pro-micro";
+        #gpio-cells = <2>;
+        gpio-map-mask = <0xffffffff 0xffffffc0>;
+        gpio-map-pass-thru = <0 0x3f>;
+        gpio-map
+            = <0 0 &gpio0 8 0>      /* D0 */
+            , <1 0 &gpio0 6 0>      /* D1 */
+            , <2 0 &gpio0 15 0>     /* D2 */
+            , <3 0 &gpio0 17 0>     /* D3 */
+            , <4 0 &gpio0 20 0>     /* D4/A6 */
+            , <5 0 &gpio0 13 0>     /* D5 */
+            , <6 0 &gpio0 24 0>     /* D6/A7 */
+            , <7 0 &gpio0 9 0>      /* D7 */
+            , <8 0 &gpio0 10 0>     /* D8/A8 */
+            , <9 0 &gpio1 6 0>      /* D9/A9 */
+            , <10 0 &gpio1 11 0>    /* D10/A10 */
+            , <16 0 &gpio0 28 0>    /* D16 */
+            , <14 0 &gpio0 3 0> /* D14 */
+            , <15 0 &gpio1 13 0>    /* D15 */
+            , <18 0 &gpio0 2 0> /* D18/A0 */
+            , <19 0 &gpio0 29 0>    /* D19/A1 */
+            , <20 0 &gpio0 31 0>    /* D20/A2 */
+            , <21 0 &gpio0 30 0>    /* D21/A3 */
+            ;
+    };
+
+    pro_micro_a: connector_a {
+        compatible = "arduino-pro-micro";
+        #gpio-cells = <2>;
+        gpio-map-mask = <0xffffffff 0xffffffc0>;
+        gpio-map-pass-thru = <0 0x3f>;
+        gpio-map
+            = <0 0 &gpio0 2 0>  /* D18/A0 */
+            , <1 0 &gpio0 29 0> /* D19/A1 */
+            , <2 0 &gpio0 31 0> /* D20/A2 */
+            , <3 0 &gpio0 30 0> /* D21/A3 */
+            , <6 0 &gpio0 20 0> /* D4/A6 */
+            , <7 0 &gpio0 24 0> /* D6/A7 */
+            , <8 0 &gpio0 10 0> /* D8/A8 */
+            , <9 0 &gpio1 6 0>  /* D9/A9 */
+            , <10 0 &gpio1 11 0>    /* D10/A10 */
+            ;
+    };
+};
+
+
+pro_micro_d: &pro_micro {};
+pro_micro_i2c: &i2c0 {};
+pro_micro_spi: &spi0 {};
+pro_micro_serial: &uart0 {};

app/module/boards/keycapsss/puchi_ble/board.cmake

@@ -0,0 +1,6 @@
+# Copyright (c) 2022 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+board_runner_args(nrfjprog "--nrf-family=NRF52" "--softreset")
+include(${ZEPHYR_BASE}/boards/common/uf2.board.cmake)
+include(${ZEPHYR_BASE}/boards/common/nrfjprog.board.cmake)

app/module/boards/keycapsss/puchi_ble/board.yml

@@ -0,0 +1,5 @@
+board:
+  name: puchi_ble
+  vendor: keycapsss
+  socs:
+    - name: nrf52840

app/module/boards/keycapsss/puchi_ble/pinmux.c

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <zephyr/kernel.h>
+#include <zephyr/device.h>
+#include <zephyr/init.h>
+#include <zephyr/drivers/gpio.h>
+#include <zephyr/sys/sys_io.h>
+#include <zephyr/devicetree.h>
+
+static int pinmux_puchi_ble_init(void) {
+#if CONFIG_BOARD_PUCHI_BLE
+    const struct device *p0 = DEVICE_DT_GET(DT_NODELABEL(gpio0));
+#if CONFIG_BOARD_PUCHI_BLE_CHARGER
+    gpio_pin_configure(p0, 5, GPIO_OUTPUT);
+    gpio_pin_set(p0, 5, 0);
+#else
+    gpio_pin_configure(p0, 5, GPIO_INPUT);
+#endif
+#endif
+    return 0;
+}
+
+SYS_INIT(pinmux_puchi_ble_init, APPLICATION, CONFIG_APPLICATION_INIT_PRIORITY);

app/module/boards/keycapsss/puchi_ble/pre_dt_board.cmake

@@ -0,0 +1,9 @@
+#
+# Copyright (c) 2026 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+#
+
+# Suppresses duplicate unit-address warning at build time for power, clock, acl and flash-controller
+# https://docs.zephyrproject.org/latest/build/dts/intro-input-output.html
+
+list(APPEND EXTRA_DTC_FLAGS "-Wno-unique_unit_address_if_enabled")

app/module/boards/keycapsss/puchi_ble/puchi_ble-pinctrl.dtsi

@@ -0,0 +1,39 @@
+/*
+ * 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, 15)>,
+                <NRF_PSEL(TWIM_SCL, 0, 17)>;
+        };
+    };
+
+    i2c0_sleep: i2c0_sleep {
+        group1 {
+            psels = <NRF_PSEL(TWIM_SDA, 0, 15)>,
+                <NRF_PSEL(TWIM_SCL, 0, 17)>;
+            low-power-enable;
+        };
+    };
+};

app/module/boards/keycapsss/puchi_ble/puchi_ble.dts

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) 2022 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/dts-v1/;
+#include <nordic/nrf52840_qiaa.dtsi>
+#include <common/nordic/nrf52840_uf2_boot_mode.dtsi>
+
+#include "arduino_pro_micro_pins.dtsi"
+#include "puchi_ble-pinctrl.dtsi"
+
+/ {
+    model = "puchi_ble";
+    compatible = "puchi_ble";
+
+    chosen {
+        zephyr,code-partition = &code_partition;
+        zephyr,sram = &sram0;
+        zephyr,flash = &flash0;
+        zmk,battery = &vbatt;
+    };
+
+    leds {
+        compatible = "gpio-leds";
+        blue_led: led_0 {
+            gpios = <&gpio1 10 GPIO_ACTIVE_HIGH>;
+        };
+    };
+
+    // Node name must match original "EXT_POWER" label to preserve user settings.
+    EXT_POWER {
+        compatible = "zmk,ext-power-generic";
+        control-gpios = <&gpio1 9 GPIO_ACTIVE_LOW>;
+    };
+
+    vbatt: vbatt {
+        compatible = "zmk,battery-voltage-divider";
+        io-channels = <&adc 2>;
+        output-ohms = <2000000>;
+        full-ohms = <(2000000 + 820000)>;
+    };
+};
+
+&adc {
+    status = "okay";
+};
+
+&gpiote {
+    status = "okay";
+};
+
+&gpio0 {
+    status = "okay";
+};
+
+&gpio1 {
+    status = "okay";
+};
+
+&i2c0 {
+    compatible = "nordic,nrf-twi";
+    pinctrl-0 = <&i2c0_default>;
+    pinctrl-1 = <&i2c0_sleep>;
+    pinctrl-names = "default", "sleep";
+};
+
+&uart0 {
+    compatible = "nordic,nrf-uarte";
+    pinctrl-0 = <&uart0_default>;
+    pinctrl-1 = <&uart0_sleep>;
+    pinctrl-names = "default", "sleep";
+};
+
+zephyr_udc0: &usbd {
+    status = "okay";
+};
+
+
+&flash0 {
+    /*
+     * For more information, see:
+     * http://docs.zephyrproject.org/latest/devices/dts/flash_partitions.html
+     */
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        sd_partition: partition@0 {
+            reg = <0x00000000 0x00026000>;
+        };
+        code_partition: partition@26000 {
+            reg = <0x00026000 0x000c6000>;
+        };
+
+        /*
+         * The flash starting at 0x000ec000 and ending at
+         * 0x000f3fff is reserved for use by the application.
+         */
+
+        /*
+         * Storage partition will be used by FCB/LittleFS/NVS
+         * if enabled.
+         */
+        storage_partition: partition@ec000 {
+            reg = <0x000ec000 0x00008000>;
+        };
+
+        boot_partition: partition@f4000 {
+            reg = <0x000f4000 0x0000c000>;
+        };
+    };
+};

app/module/boards/keycapsss/puchi_ble/puchi_ble.yaml

@@ -0,0 +1,15 @@
+identifier: puchi_ble
+name: puchi_ble
+type: mcu
+arch: arm
+toolchain:
+  - zephyr
+  - gnuarmemb
+  - xtools
+supported:
+  - adc
+  - usb_device
+  - ble
+  - ieee802154
+  - pwm
+  - watchdog

app/module/boards/keycapsss/puchi_ble/puchi_ble.zmk.yml

@@ -0,0 +1,10 @@
+file_format: "1"
+id: puchi_ble
+name: Puchi-BLE V1
+type: board
+arch: arm
+outputs:
+  - usb
+  - ble
+url: https://keycapsss.com/keyboard-parts/mcu-controller/202/puchi-ble-wireless-microcontroller
+exposes: [pro_micro]

app/module/boards/keycapsss/puchi_ble/puchi_ble_defconfig

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+# Enable MPU
+CONFIG_ARM_MPU=y
+
+# enable GPIO
+CONFIG_GPIO=y
+
+# Use pinctrl
+CONFIG_PINCTRL=y
+
+CONFIG_USE_DT_CODE_PARTITION=y
+CONFIG_BUILD_OUTPUT_UF2=y
+