ZMK 键盘项目初始化

引导用户完成 ZMK (Zephyr Mechanical Keyboard) 固件项目的创建、配置、编译和烧录。

适用场景

• 创建新的 ZMK 蓝牙/有线键盘项目
• 为已有键盘 PCB 添加 ZMK shield 定义
• 搭建 ZMK 本地开发环境并编译固件

前置条件

• 目标 MCU 为 32 位 ARM（nRF52840/nRF52832/RP2040/STM32 等），ZMK 不支持 AVR
• 系统已安装基本工具链（cmake、ninja、dtc、gperf、python3、arm-none-eabi-gcc）
• 如需烧录：J-Link 已连接 或 板卡支持 UF2 拖拽烧录

Step 1: 环境检测

> ZMK 基于 Zephyr v4.1+，要求 Python >= 3.10。系统自带 Python 3.9 可能不满足要求。

并行检测以下组件：

cmake --version | head -1
ninja --version
dtc --version | head -1
gperf --version | head -1
python3 --version
arm-none-eabi-gcc --version | head -1

J-Link 检测（含非标准路径）：

JLINK_PATH=""
candidates="$(
  which JLinkExe 2>/dev/null
  echo "/Applications/SEGGER/JLink/JLinkExe"
  find /Applications/SEGGER -name 'JLinkExe' -maxdepth 3 2>/dev/null
  find "$HOME/tools" -name 'JLinkExe' -maxdepth 5 2>/dev/null
)"
while IFS= read -r p; do
  [ -n "$p" ] && [ -x "$p" ] && JLINK_PATH="$p" && break
done <<< "$candidates"
echo "JLinkExe: ${JLINK_PATH:-NOT_FOUND}"

Python 版本要求（⚠️ 关键）

Zephyr v4.1 要求 Python >= 3.10。如果系统 Python < 3.10：

# macOS
brew install python@3.12
# 创建 venv（⚠️ Homebrew Python 不允许全局 pip install，必须用 venv）
cd <zmk_dir>
python3.12 -m venv .venv
source .venv/bin/activate
pip install west
pip install -r zephyr/scripts/requirements-base.txt

> ⚠️ Homebrew Python PEP 668 限制：Homebrew 安装的 Python 3.12 不允许直接 pip3 install（报错 externally-managed-environment）。必须创建 venv 后在 venv 内安装包。

Step 2: 克隆 ZMK 仓库并初始化 Workspace

cd <project_parent_dir>
git clone https://github.com/zmkfirmware/zmk.git
cd zmk

# 初始化 Zephyr workspace（⚠️ 必须取消 ZEPHYR_BASE 环境变量）
unset ZEPHYR_BASE
west init -l app/
west update                    # 下载 Zephyr + 模块，约 4-5GB，需较长时间

# 导出 CMake 包
source .venv/bin/activate      # 如使用 venv
west zephyr-export

# 安装 Python 依赖
pip install -r zephyr/scripts/requirements-base.txt

> ⚠️ NCS 冲突：如果系统已安装 nRF Connect SDK，.zshrc 中的 source zephyr-env.sh 会设置 ZEPHYR_BASE 指向 NCS。ZMK 需要自己的 Zephyr fork，编译前必须 unset ZEPHYR_BASE。

> ⚠️ west update 网络失败 — 必须重试！：部分模块可能因网络超时失败。如果后续启用 BLE（CONFIG_ZMK_BLE=y），需要 mbedtls 模块。模块不全会导致 Kconfig 警告 MBEDTLS has direct dependencies 0 with value n 并中止编译。遇到此问题需重新运行 west update 直到所有模块下载成功。失败的模块不会自动重试，必须完整重新 west update。
>
> 如何判断是否需要重试：查看 west update 输出末尾是否有 ERROR: update failed for projects: ...。如果有，重新运行 west update。

Step 3: 确认硬件配置

通过 AskUserQuestion 与用户交互确认：

3.1 芯片型号

• nRF52840（最常用，USB + BLE）
• nRF52832（BLE，无 USB）
• RP2040
• STM32
• 其他

3.2 开发板/控制器

• nice!nano（ZMK 最流行，nRF52840 + UF2 bootloader + 锂电池充电）
• nRF52840 DK
• Pro Micro RP2040
• 自定义板

3.3 键盘布局

• 自定义矩阵（行列数）
• 已有布局（Corne、Sofle、Kyria 等）

3.4 外设功能（多选）

• 编码器
• I2C OLED/LCD 屏幕
• RGB 灯效
• 电池电量检测
• 外设电源控制（VCC shutoff）
• 状态按钮/LED
• UART 调试串口

Step 4: 确定引脚分配

Pro Micro 引脚布局（nice!nano 等）

> ⚠️ D11/D12 在 nice!nano v2 上不可用，分配引脚时需避开。

ZMK 中的 Pro Micro 节点与总线别名

ZMK 定义了 &pro_micro connector 和标准总线别名：
- &pro_micro_i2c → &i2c0（I2C 总线，pinctrl 映射到 D2/D3 即 P0.17/P0.20）
- &pro_micro_spi → &spi1（SPI 总线，pinctrl 映射到 D14/D15/D16）
- &pro_micro_serial → &uart0（UART，pinctrl 映射到 D0/D1 即 P0.08/P0.06）

> ⚠️ I2C 和 UART 引脚不冲突：pro_micro_i2c 使用 D2/D3，pro_micro_serial 使用 D0/D1。可以同时启用 I2C OLED 和 UART 调试串口。

在 shield dtsi 中引用引脚：<&pro_micro 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)> 表示 D7。

Step 5: 创建用户配置目录结构

config/
├── build.yaml                                # CI 构建配置
└── boards/
    └── shields/
        └── <keyboard_name>/
            ├── <keyboard_name>.zmk.yml       # Shield 元数据（⚠️ 必须）
            ├── <keyboard_name>.overlay       # Shield 主 overlay（⚠️ 必须，否则 shield 不被发现）
            ├── <keyboard_name>.dtsi          # 硬件定义（被 overlay include）
            ├── <keyboard_name>.conf          # ⚠️ Shield Kconfig 配置（启用 USB/BLE/UART 等）
            ├── <keyboard_name>.keymap        # 键盘映射
            ├── Kconfig.shield                # Shield 声明
            ├── Kconfig.defconfig             # Shield 默认配置
            └── boards/
                └── <board_name>.overlay      # 板级特定 overlay（⚠️ 文件名匹配不可靠，见下方说明）

⚠️ 关键文件说明

Step 6: 编写 Shield 定义文件

6.1 <keyboard_name>.zmk.yml

file_format: "1"
id: <keyboard_name>
name: <Display Name>
type: shield
url: ""
requires: [pro_micro]        # 或其他 interconnect
exposes: [i2c_oled]          # 可选
features:
  - keys
  - display                  # 如有屏幕
  - encoder                  # 如有编码器

6.2 Kconfig.shield

# SPDX-License-Identifier: MIT

config SHIELD_<KEYBOARD_NAME_UPPER>
    def_bool $(shields_list_contains,<keyboard_name>)

6.3 Kconfig.defconfig

# SPDX-License-Identifier: MIT

if SHIELD_<KEYBOARD_NAME_UPPER>

config ZMK_KEYBOARD_NAME
    default "<Keyboard Name>"

# ⚠️ 不要在此定义 ZMK 内部符号的 type（如 ZMK_ENCODER），
# 只设置 default 值。ZMK_ENCODER 通过 DTS 自动启用。

if ZMK_DISPLAY
config I2C
    default y
config SSD1306
    default y
endif

endif

6.4 <keyboard_name>.conf（⚠️ 关键 — 启用 USB/BLE/UART）

> ⚠️ ZMK 新版 board defconfig 不自动加载 ZMK_USB/ZMK_BLE！
>
> ZMK 存在两套 board 定义：app/module/boards/（新格式，defconfig 中没有 ZMK_USB/ZMK_BLE）和 app/boards/（旧格式，defconfig 中有）。Zephyr v4.1 优先加载 module 目录的 defconfig，导致 USB 和 BLE 未启用。
>
> 必须在 <keyboard_name>.conf 中显式启用！

# <keyboard_name>.conf - Shield 配置

# USB HID（⚠️ 必须！不启用则 USB 无法识别设备）
CONFIG_ZMK_USB=y

# 蓝牙 BLE（⚠️ 必须！不启用则蓝牙不可见）
# 注意：BLE 依赖 mbedtls 模块，west update 必须完整成功
CONFIG_ZMK_BLE=y

# UART 调试串口（可选，TX=P0.06/D1, RX=P0.08/D0, 115200 baud）
CONFIG_SERIAL=y
CONFIG_NRFX_UARTE0=y
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y
CONFIG_PRINTK=y

# 日志
CONFIG_LOG=y
CONFIG_LOG_DEFAULT_LEVEL=4

> ⚠️ UART 驱动配置：仅设置 CONFIG_SERIAL=y 和 CONFIG_UART_CONSOLE=y 不够。nRF 平台还需要 CONFIG_NRFX_UARTE0=y 启用底层 UART 驱动，否则 SERIAL_HAS_DRIVER 为 n，UART_CONSOLE 依赖不满足会被静默禁用。

6.5 <keyboard_name>.overlay / .dtsi

#include <dt-bindings/zmk/matrix_transform.h>

/ {
    chosen {
        zmk,kscan = &kscan0;
        zmk,matrix_transform = &default_transform;
        zephyr,display = &oled;          /* 如有显示屏 */
    };

    default_transform: keymap_transform_0 {
        compatible = "zmk,matrix-transform";
        columns = <3>;
        rows = <2>;
        map = <
            RC(0,0) RC(0,1) RC(0,2)
            RC(1,0) RC(1,1) RC(1,2)
        >;
    };

    kscan0: kscan {
        compatible = "zmk,kscan-gpio-matrix";
        wakeup-source;
        debounce-press-ms = <5>;          /* ⚠️ 不是 debounce-period-ms（已废弃） */
        debounce-release-ms = <5>;
        diode-direction = "col2row";      /* 或 "row2col" */

        row-gpios
            = <&pro_micro 7 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>
            , <&pro_micro 8 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)>;

        col-gpios
            = <&pro_micro 9 GPIO_ACTIVE_HIGH>
            , <&pro_micro 10 GPIO_ACTIVE_HIGH>
            , <&pro_micro 5 GPIO_ACTIVE_HIGH>;
    };

    /* 编码器 */
    sensors: sensors {
        compatible = "zmk,keymap-sensors";
        sensors = <&encoder_0>;
        triggers-per-rotation = <2>;
    };

    encoder_0: encoder_0 {
        compatible = "alps,ec11";         /* ⚠️ 必须声明 compatible */
        a-gpios = <&pro_micro 15 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
        b-gpios = <&pro_micro 14 (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;
        steps = <80>;
        status = "okay";
    };

    /* 状态按钮（gpio-keys 必须是容器+子节点结构） */
    buttons: buttons {
        compatible = "gpio-keys";
        status_button: status_button {
            gpios = <&pro_micro 4 GPIO_ACTIVE_LOW>;
            zephyr,code = <0x0c>;
        };
    };
};

/* I2C OLED（使用 Pro Micro 标准 I2C 节点） */
&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>;
        segment-remap;                    /* ⚠️ 不带值，不是 = <1> */
        com-invdir;
        com-sequential;
        inversion-on;
        prechargep = <0x22>;              /* ⚠️ 属性名是 prechargep，不是 precharge-period */
    };
};

/* UART 调试串口（⚠️ 放在 shield 主 .overlay 中，不要放在 boards/<board>.overlay 中） */
&uart0 {
    status = "okay";                       /* 板卡 DTS 默认 disabled，必须启用 */
};

/ {
    chosen {
        zephyr,console = &uart0;           /* ⚠️ 必须设置 console 指向 */
        zephyr,shell-uart = &uart0;
    };
};

> ⚠️ UART 启用必须放在 shield 主 .overlay 中：board-specific overlay（boards/<board_name>.overlay）的文件名匹配在 Zephyr v4.1 新 board 模型下不可靠（board 名从 nice_nano_nrf52840_zmk 变为 nice_nano + qualifier nrf52840），导致 overlay 不被加载。将 &uart0 { status = "okay"; } 和 chosen 放在 shield 主 .overlay 中可确保生效。

6.6 <keyboard_name>.keymap

#include <behaviors.dtsi>                 /* ⚠️ 必须！定义 &kp &bt &out 等行为 */
#include <dt-bindings/zmk/keys.h>
#include <dt-bindings/zmk/bt.h>
#include <dt-bindings/zmk/outputs.h>

/* 启用编码器 */
&encoder_0 {
    status = "okay";
};

&sensors {
    sensors = <&encoder_0>;
};

/ {
    keymap {
        compatible = "zmk,keymap";

        default_layer {
            display-name = "Default";
            bindings = <
                &kp Q    &kp W    &kp E
                &kp A    &kp S    &kp D
            >;
            /* ⚠️ 用 &inc_dec_kp（不是 &inc_kp） */
            sensor-bindings = <&inc_dec_kp C_VOLUME_UP C_VOLUME_DOWN>;
        };
    };
};

6.7 boards/<board_name>.overlay

> ⚠️ board-specific overlay 文件名匹配不可靠：Zephyr v4.1 新 board 模型将 nice_nano_v2 改为 nice_nano + qualifier。board-specific overlay 文件名 nice_nano_nrf52840_zmk.overlay 可能不被加载。建议将所有配置放在 shield 主 .overlay 中，不依赖 board-specific overlay。

/* 板级 overlay，通常只需 include shield 主 dtsi */
#include "<keyboard_name>.dtsi"

6.8 build.yaml

build:
  - board: nice_nano             # ⚠️ 不是 nice_nano_v2
    shield: <keyboard_name>
    artifact-name: <keyboard_name>-nice_nano

Step 7: 编译

> ⚠️ 编译命令使用 board qualifier 格式：-b nice_nano/nrf52840，不要用 -b nice_nano -DBOARD_REV=2.0.0。旧格式会导致 board defconfig 中的 ZMK_USB/ZMK_BLE 不被加载。

cd <zmk_dir>
source .venv/bin/activate        # 如使用 venv
unset ZEPHYR_BASE                # ⚠️ 必须！避免使用 NCS 的 Zephyr

cd app
west build -b nice_nano/nrf52840 -- \
  -DSHIELD=<keyboard_name> \
  -DZMK_CONFIG=<absolute_path_to_config>

⚠️ 验证关键配置（编译后必须检查）

编译成功后，检查 .config 确认 USB/BLE/UART 已启用：

grep -E "CONFIG_ZMK_USB|CONFIG_ZMK_BLE|CONFIG_BT[^_]|CONFIG_USB_DEVICE_HID|CONFIG_NRFX_UARTE0|CONFIG_UART_CONSOLE" build/zephyr/.config

期望输出：

CONFIG_ZMK_USB=y
CONFIG_ZMK_BLE=y
CONFIG_BT=y
CONFIG_USB_DEVICE_HID=y
CONFIG_NRFX_UARTE0=y          # 如启用 UART
CONFIG_UART_CONSOLE=y          # 如启用 UART

如果看到 # CONFIG_ZMK_USB is not set，说明 .conf 文件未被加载或配置有误。

编译常见错误与解决方案

编译成功标志

Wrote 544768 bytes to zmk.uf2

输出文件：
- build/zephyr/zmk.uf2 — UF2 格式（拖拽烧录用）
- build/zephyr/zmk.hex — Intel HEX 格式（J-Link 烧录用，内含 0x26000 偏移地址）
- build/zephyr/zmk.elf — ELF 格式（调试用）

Step 8: 烧录

⚠️ 烧录前：备份全片 Flash（强烈建议）

> J-Link 全片擦除 (erase) 会删除 bootloader（0x0-0x26000）！
> 烧录前先用 J-Link 备份完整 flash，以便误操作后恢复：

cat > /tmp/backup.jlink << 'EOF'
device nRF52840_xxAA
if SWD
speed 4000
connect
savebin <backup_path>/nrf52840_flash_backup.bin, 0, 0x100000
exit
EOF
"$JLINK_PATH" -NoGui 1 -CommanderScript /tmp/backup.jlink

方式 A: UF2 拖拽烧录（需要 bootloader 完好）

1. 双击 RESET 按钮进入 bootloader
2. 设备显示为 USB 存储设备
3. 复制 build/zephyr/zmk.uf2 到该存储设备
4. 设备自动重启

方式 B: J-Link 安全烧录（保留 bootloader，推荐）

> hex 文件内含地址信息（0x26000 起），J-Link loadfile 会自动处理偏移，无需手动指定地址。
>
> ⚠️ 必须使用范围擦除 erase 0x26000, 0xDA000，不要用全片 erase！

JLINK_PATH="<JLinkExe 路径>"
cat > /tmp/flash.jlink << 'EOF'
device nRF52840_xxAA
if SWD
speed 4000
connect
erase 0x26000, 0xDA000
loadfile <path>/build/zephyr/zmk.hex
r
g
exit
EOF
"$JLINK_PATH" -NoGui 1 -CommanderScript /tmp/flash.jlink

> 分区布局（nice!nano v2 / nRF52840）：
> | 地址范围 | 内容 | 大小 |
> |---|---|---|
> | 0x000000 - 0x025FFF | UF2 Bootloader | 152KB |
> | 0x026000 - 0x0D9FFF | ZMK 应用固件 | ~728KB |
> | 0x0DA000 - 0x0EBFFF | 应用保留区 | ~72KB |
> | 0x0EC000 - 0x0F3FFF | Storage (NVS) | 32KB |
> | 0x0F4000 - 0x0FFFFF | Boot partition | 48KB |

方式 C: J-Link 全片擦录（⚠️ 会删除 bootloader）

> 仅在需要完全重刷时使用。烧录后需单独恢复 bootloader。

cat > /tmp/flash.jlink << 'EOF'
device nRF52840_xxAA
if SWD
speed 4000
connect
erase
loadfile <path>/build/zephyr/zmk.hex
r
g
exit
EOF

Bootloader 恢复（误删后修复）

如果 bootloader 被误删，从备份恢复：

cat > /tmp/restore.jlink << 'EOF'
device nRF52840_xxAA
if SWD
speed 4000
connect
erase
loadbin <backup_path>/nrf52840_flash_backup.bin, 0
r
g
exit
EOF
"$JLINK_PATH" -NoGui 1 -CommanderScript /tmp/restore.jlink

恢复后再用安全烧录方式烧录 ZMK 固件。

方式 D: west flash

cd <zmk_dir>/app
west flash --runner jlink

Step 9: 验证

9.1 基本验证

1. 烧录后设备自动复位运行
2. 通过 USB 连接电脑，应识别为 HID 键盘（名称为 ZMK_KEYBOARD_NAME 设置的值）
3. 蓝牙搜索应能发现设备
4. 按键测试：矩阵中的按键应输出对应字符
5. 编码器测试：旋转应触发音量增减
6. OLED 测试：屏幕应显示 ZMK 默认状态画面

9.2 串口调试验证

如启用了 UART 调试串口：
- 连接 USB-TTL 适配器：TX→P0.08 (D0), RX→P0.06 (D1), GND→GND
- 波特率 115200，8N1
- 上电后应看到 ZMK 日志输出

# macOS
screen /dev/tty.usbserial* 115200
# Linux
screen /dev/ttyUSB* 115200

9.3 无输出排查

如果 USB 不识别 / 蓝牙不可见 / 串口无输出，按以下顺序排查：

1. 检查 .config：grep -E "CONFIG_ZMK_USB|CONFIG_ZMK_BLE|CONFIG_NRFX_UARTE0|CONFIG_UART_CONSOLE" build/zephyr/.config
2. 检查设备树：grep "status" build/zephyr/zephyr.dts | grep -E "uart|usb" — uart0 应为 okay
3. 检查 chosen：grep "console" build/zephyr/zephyr.dts — 应有 zephyr,console = &uart0
4. 确认固件在芯片中：J-Link 读 0x26000 处向量表，第一个 word 应为有效栈指针（0x2000xxxx）

完成标志

• [x] ZMK 仓库克隆 + west update 完整成功（所有模块）
• [x] Shield 定义文件全部创建且格式正确
• [x] <keyboard_name>.conf 中启用 CONFIG_ZMK_USB=y + CONFIG_ZMK_BLE=y
• [x] west build 编译成功，生成 zmk.uf2 / zmk.hex
• [x] .config 中确认 ZMK_USB/ZMK_BLE/BT/USB_DEVICE_HID 均为 =y
• [x] 固件烧录到设备并运行（安全擦录，保留 bootloader）
• [x] 设备识别为 HID 键盘 / BLE 可发现

速查：ZMK 新版关键变更（vs 旧版/文档）