★ FEATURED ARTICLE 固件嵌入式智能硬件蓝牙【免费下载链接】zmkZMK Firmware Repository项目地址https://gitcode.com/gh_mirrors/zm/zmk点击查看免费下载在完成默认固件刷写验证之后绝大多数 ZMK 用户的第一件事就是定制自己的键位映射与固件功能。ZMK 与其它键盘固件的核心差异在于它将个人键盘配置从主固件源码仓库中彻底分离出来放入一个独立的zmk-config配置仓库。本文将以 docs/docs/customization.md 为骨架完整讲解zmk-config仓库的结构、keyboard.conf固件选项、keyboard.keymap键位映射、如何推送触发云端构建、如何刷写更新以及如何通过build.yaml同时构建多把键盘并穿插仓库源码与配置佐证帮助你真正掌握这套配置与固件解耦的工作流。为什么需要独立的 zmk-config 配置仓库在 初始安装教程 中你通过 ZMK CLI 创建了一个名为zmk-config的 GitHub 仓库。这个仓库是一个独立于主zmk固件仓库的文件系统与主固件仓库协同工作来构建你想要的固件。采用独立配置仓库的核心优势在于工作组件与个人设置分离ZMK 固件中稳定工作的组件固件源码、驱动、行为定义等保存在主仓库而你的个人键盘设置键位、功能开关等保存在zmk-config互不干扰极大减少配置过程中对文件的操作量。无需在电脑上长期保存一份最新的 ZMK 源码只要把配置推送到 GitHubGitHub Actions 就会在云端自动完成构建让刷写固件变得非常容易。默认情况下zmk-config仓库包含两个文件keyboard.conf—— 固件构建选项Kconfig 配置keyboard.keymap—— 键位映射Devicetree 配置此外配置仓库还可以扩展出boards/目录用于存放多把键盘board/shield的 keymap 与配置突破默认键盘设定的限制。关于这套目录约定的完整机制可以进一步参考 配置总览文档。理解配置文件的查找路径与覆盖优先级在动手编辑之前先理解 ZMK 如何定位并合并配置文件这会直接影响你自定义的生效范围。根据 docs/docs/config/index.md 的说明ZMK 会按以下顺序在多处查找配置用户配置文件夹最高优先级构建使用zmk-config时ZMK 会在zmk-config/config文件夹下查找name.conf与name.keymap其中name在使用 shield 时是 shield 名称否则是 board 名称。这些文件如果存在会覆盖 board 或 shield 文件夹中定义的任何配置如果不存在则使用默认配置和/或默认 keymap。Board 文件夹app/boards/vendor/board仓库内置、zmk-config/boards/vendor/board、module/boards/vendor/board模块提供这些文件描述板子的硬件。board 文件夹额外支持board.conf与board.keymap仅带板载控制器的键盘。Shield 文件夹app/boards/shields/shield、zmk-config/boards/shields/shield、module/boards/shields/shield描述 shield 硬件同样支持shield.conf与shield.keymap。值得注意的细节对于分体键盘你可以使用不带_left/_right后缀的单个文件同时配置两侧。例如corne.conf与corne.keymap会同时作用于corne_left和corne_right如果存在共享配置文件任何左右侧单独的文件都会被忽略。不过共享配置文件目前不支持用于 board 文件夹和 shield 文件夹。所有配置都是编译期生效的修改任何设置后必须重新构建固件并刷写改动才会生效。通过keyboard.conf调整固件构建选项安装脚本会创建一个config/keyboard.conf文件让你添加额外的配置选项来控制固件中构建哪些功能。用文本编辑器打开该文件就可以看到各种可注释/取消注释的配置项从而修改固件的构建方式。.conf文件使用的是 Kconfig 语法是每行一个CONFIG_XYZvalue赋值的纯文本文件。例如 配置总览 中给出的示例CONFIG_ZMK_SLEEPy CONFIG_EC11y CONFIG_EC11_TRIGGER_GLOBAL_THREADyKconfig 支持三种值类型类型说明示例booly表示启用n表示禁用CONFIG_FOOyint整数CONFIG_FOO42string用双引号包裹的文本CONFIG_FOOfoo从源码结构看可用的配置项由 ZMK 中名称以Kconfig开头的各类文件决定注意这些文件中选项不带CONFIG_前缀。例如在 app/Kconfig 中可以找到ZMK_BLE、ZMK_BLE_PASSKEY_ENTRY等蓝牙相关选项在 app/Kconfig.defaults 中定义了大量默认配置。分体键盘相关选项如CONFIG_ZMK_SPLIT、CONFIG_ZMK_SPLIT_ROLE_CENTRAL在 app/boards/kinesis/adv360pro/Kconfig.defconfig 等板级Kconfig.defconfig文件中也可以看到具体用法。常见的实战配置示例包括# 启用分体键盘支持 CONFIG_ZMK_SPLITy # 开启低功耗睡眠 CONFIG_ZMK_SLEEPy提示如果修改 Kconfig 设置后遇到问题可以在构建过程中检查最终的配置集合ZMK 会输出合并后的配置来诊断问题详见 构建问题排查。更多该文件的配置细节请参阅 Configuration 文档。定制keyboard.keymap键位映射完成基本配置后你可以在config/keyboard.keymap中找到 keymap 文件并从这里开始定制。ZMK 采用声明式的 Devicetree 语法来定义 keymap这份声明式配置同时定义了按键映射、映射中使用的 behaviors行为以及某些功能的配置。一个完整的 keymap 文件通常包含以下要素参考 Keymaps 文档Includes文件顶部两行通常为#include behaviors.dtsi #include dt-bindings/zmk/keys.h前者引入 ZMK 中所有可用 behaviors 的节点这样kp才能引用名为kp的 key press 行为后者引入所有键码如A、N1、C_PLAY与修饰键如LSHIFT的宏定义。根节点其余 keymap 节点都嵌套在 Devicetree 根节点/ { ... };内。keymap 节点节点名称本身不重要但必须带有compatible zmk,keymap属性才会被 ZMK 使用。层Layers每个层包含一个bindings属性每个键位一个行为绑定可选sensor-bindings每个传感器一个绑定目前仅编码器和display-name供 ZMK Studio 与层状态显示组件使用。层按出现在 keymap 节点中的顺序编号第一个是层0。仓库中现成的完整示例可以直接参考例如 corne.keymap 的默认层/ { keymap { compatible zmk,keymap; default_layer { display-name Default Layer; bindings kp TAB kp Q kp W kp E kp R kp T kp Y kp U kp I kp O kp P kp BSPC kp LCTRL kp A kp S kp D kp F kp G kp H kp J kp K kp L kp SEMI kp SQT kp LSHFT kp Z kp X kp C kp V kp B kp N kp M kp COMMA kp DOT kp FSLH kp ESC kp LGUI mo 1 kp SPACE kp RET mo 2 kp RALT ; }; }; };行为绑定时还可以携带最多两个参数。例如kp A中的A实际是原始 HID 键码的宏定义而 mod-tap 绑定mt LSHIFT D中第一个参数是按住时使用的修饰键集合第二个参数是点按时发送的键码。了解 keymap 的完整结构请参阅 Keymaps 文档想探索更多键盘的默认 keymap可以浏览 app/boards 目录例如 kyria.keymap、lily58.keymap。本地构建 zmk-configwest build 与 ZMK_CONFIG虽然推送 GitHub 触发云端构建是最常用的方式但你也可以在本机直接使用自己的zmk-config文件夹构建固件。根据 本地工具链构建与刷写文档在west build命令中加入-DZMK_CONFIG绝对路径即可——注意该路径必须指向zmk-config文件夹内部名为config的文件夹west build -b nice_nano//zmk -- -DSHIELDkyria_left \ -DZMK_CONFIGC:/Users/myUser/Documents/Github/zmk-config/config如果 keymap 改动只需要更新中央侧见下一节本地构建分体键盘时还可以用-d参数为左右两侧建立独立构建目录避免互相覆盖west build -d build/left -b nice_nano//zmk -- -DSHIELDkyria_left west build -d build/right -b nice_nano//zmk -- -DSHIELDkyria_right推送变更git 提交与 GitHub Actions 自动构建完成任何想要的修改后你应该提交这些变更并推送到 GitHub。推送会触发一次新的 GitHub Actions 任务来构建你的固件构建完成后即可下载。zmk cd # 进入配置仓库目录 git add . git commit -m Describe your changes git push如果不熟悉 Git可以先了解 Git 基础操作再执行上述步骤。另一种选择是在本地电脑上构建固件按照 工具链设置 与 构建说明 操作后者包含使用 zmk-config 文件夹构建的具体指引。刷写你的修改普通键盘按照与之前相同的刷写步骤刷写更新后的固件即可。分体键盘如果只是更新 keymap通常只需要重新刷写中央central侧一般是左侧。这是因为 keymap 的处理主要发生在中央侧——分体键盘中由中央侧接收来自外围peripheral侧的按键位置与传感器事件运行 keymap 逻辑将其转换为 HID 事件如键码再通过 USB 或蓝牙与主机通信见 分体键盘文档。不过要记住如果修改的是需要应用到所有部件的配置文件那么所有部件都需要重新刷写涉及分体功能本身的 ZMK 改动也可能需要如此。分体配对问题的排查如果左右两侧无法配对例如更换了中央/外围角色或更换了某一侧的控制器需要给两侧控制器都刷写 settings reset 固件来清除存储的配对信息。具体做法是在zmk-config的build.yaml中追加一个settings_resetshield 构建项例如include: - board: nice_nano shield: corne_left - board: nice_nano shield: corne_right - board: nice_nano shield: settings_reset推送后从最新一次 GitHub Actions 构建下载固件会看到额外的settings_reset固件文件然后按 连接问题排查文档 中的步骤逐一刷写即可。注意该过程会清除所有设置蓝牙 profile、输出选择、RGB 灯效颜色等。构建更多键盘build.yaml 与多键盘配置文件组织你可以在zmk-config文件夹中通过修改build.yaml让 GitHub Actions 同时构建多把键盘。build.yaml中的每个条目指定一个 board 与一个 shield或直接指定带板载控制器的 board。假设初始设置时你已配置了 Corne shield nice!nano现在想再加入一把 Lily58 shield nice!nano v2。下面是一个能够完成这一目标的示例build.yamlinclude: - board: nice_nano1 shield: corne_left - board: nice_nano1 shield: corne_right - board: nice_nano shield: lily58_left - board: nice_nano shield: lily58_right注意这里nice_nano1表示 nice!nano v1nice_nano表示 nice!nano v2两把键盘可以共存于同一个配置仓库中。除了更新build.yaml还需要把 Lily58 的 shield 文件一并加入zmk-config内的config子文件夹与你的 Corne 文件放在一起例如corne.conf corne.keymap lily58.conf lily58.keymap这样每次推送都会同时触发两把键盘左右两侧的构建下载固件包后按左右侧分别刷写即可。小结围绕zmk-config配置仓库ZMK 为用户提供了一条完整、低门槛的定制链路结构清晰keyboard.confKconfig与keyboard.keymapDevicetree两个文件分别控制固件选项与键位映射且支持boards/目录与多键盘组织构建灵活既可以 git 推送触发 GitHub Actions 云端构建也可以本地west build -DZMK_CONFIG指定配置目录刷写精准分体键盘更新 keymap 时只需刷中央侧结合settings_reset固件可解决配对故障扩展容易通过build.yaml追加条目即可让同一配置仓库同时服务多把键盘。这套配置与固件解耦的设计正是 ZMK 相比传统键盘固件更易上手、更便于长期维护的核心所在。深入实践时建议配合 配置总览、Keymaps 文档 与 分体键盘文档 一起阅读形成完整知识闭环。赞分享固件嵌入式智能硬件蓝牙【免费下载链接】zmkZMK Firmware Repository项目地址https://gitcode.com/gh_mirrors/zm/zmk点击查看免费下载相关推荐ZMK打造你的终极定制化键盘固件指南ZMK打造你的终极定制化键盘固件指南 在键盘定制化领域 ZMK开源键盘固件 正成为越来越多DIY爱好者的首选解决方案。这款基于Zephyr RTOS的固件不固件嵌入式智能硬件蓝牙ZMK开源键盘固件打造你的专属定制键盘指南ZMK开源键盘固件打造你的专属定制键盘指南 你是否曾经因为找不到完全符合自己使用习惯的键盘而烦恼或者想要一个能够随心所欲调整布局的智能输入设备ZMK开源键固件嵌入式智能硬件蓝牙ZMK免费开源键盘固件的完整配置指南ZMK免费开源键盘固件的完整配置指南 想要打造完全自定义的机械键盘ZMK开源键盘固件为你提供了终极解决方案。基于Zephyr RTOS构建ZMK不仅完全免固件嵌入式智能硬件蓝牙上一篇CANN/GE ONNX内存模型解析接口下一篇Spotube终极指南如何免费享受高品质音乐流媒体服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
