ZMK固件本地构建与烧录指南

ZMK固件本地构建与烧录指南

zmk ZMK Firmware Repository 项目地址: https://gitcode.com/gh_mirrors/zm/zmk

前言

ZMK是一款开源的键盘固件项目，基于Zephyr™实时操作系统开发。本文将详细介绍如何在本地环境中构建和烧录ZMK固件，适用于各种键盘硬件配置。

准备工作

在开始构建前，请确保：

1. 已完成ZMK开发环境的搭建
2. 已正确克隆ZMK代码仓库
3. 已安装所有必要的工具链

构建流程

进入构建目录

所有构建操作都必须在app/子目录下执行：

cd app

注意：在其他目录执行构建会导致CMake报错，提示找不到CMakeLists.txt文件。

构建命令基础

根据键盘MCU的不同配置，构建命令有所区别：

内置MCU的键盘

这类键盘直接作为Zephyr的"board"目标构建。例如构建Planck(rev6)键盘：

west build -b planck_rev6

使用扩展MCU板的键盘

这类键盘被视为Zephyr的"shield"，而MCU板才是真正的"board"。例如构建使用Proton-C MCU板的Kyria键盘：

west build -b proton_c -- -DSHIELD=kyria_left

CMake参数详解

ZMK使用CMake作为构建系统，可以通过--传递额外参数：

west build -b planck_rev6 -- -DCONFIG_ZMK_SLEEP=y

永久性CMake参数

使用west config设置永久参数：

west config build.cmake-args -- -DSHIELD=kyra_left

多参数设置：

west config build.cmake-args \
  -- "-DSHIELD=kyra_left -DZMK_CONFIG=/path/to/zmk-config"

纯净构建

当切换构建目标时，建议使用纯净构建：

west build -p -b nice_nano_v2 -- -DSHIELD=kyria_left

分体式键盘构建

分体键盘需要分别构建左右两部分：

# 构建左半部分
west build -d build/left -b nice_nano_v2 -- -DSHIELD=kyria_left

# 构建右半部分
west build -d build/right -b nice_nano_v2 -- -DSHIELD=kyria_right

后续构建可简化为：

west build -d build/left

使用外部模块

支持加载外部开发模块：

west build -b nice_nano_v2 -- -DSHIELD=vendor_shield \
  -DZMK_EXTRA_MODULES="/path/to/module1;/path/to/module2"

自定义配置构建

使用自定义配置目录构建：

west build -b nice_nano -- -DSHIELD=kyria_left \
  -DZMK_CONFIG="/path/to/zmk-config/config"

烧录方法

UF2文件烧录

构建生成的UF2文件位于：

• 单键盘：build/zephyr/zmk.uf2
• 分体键盘：build/left|right/zephyr/zmk.uf2

将UF2文件复制到键盘的USB存储设备根目录即可自动烧录。

DFU模式烧录

对于支持DFU的设备：

west flash

多核处理器特殊配置

nRF5340开发板

网络核心固件构建：

cd zephyr/samples/bluetooth/hci_rpmsg
west build -b nrf5340dk_nrf5340_cpunet
west flash

应用核心固件按常规方法构建。网络核心固件仅在Zephyr版本升级时需要更新。

常见问题解答

Q：构建时报错找不到CMakeLists.txt怎么办？ A：确保在app/目录下执行构建命令。

Q：如何提高后续构建速度？ A：使用-d参数指定构建目录，避免重复解析所有依赖。

Q：分体键盘如何管理构建？ A：为左右半部分别创建构建目录，如build/left和build/right。

Q：自定义配置不生效怎么办？ A：检查-DZMK_CONFIG参数是否指向正确的config目录，路径需为绝对路径。

通过本文的详细指导，您应该能够顺利完成ZMK固件的本地构建和烧录工作。对于特殊硬件配置或高级功能，建议参考Zephyr官方文档获取更深入的技术细节。

zmk ZMK Firmware Repository 项目地址: https://gitcode.com/gh_mirrors/zm/zmk