固件嵌入式智能硬件蓝牙【免费下载链接】zmkZMK Firmware Repository项目地址https://gitcode.com/gh_mirrors/zm/zmk点击查看免费下载本指南基于 ZMK Firmware 仓库的硬件集成文档深入讲解如何在键盘中为 Soft Off软关机状态配置一个仅用于唤醒的按键通过gpio-keys兼容节点复用矩阵 kscan 中的既有 GPIO 引脚并配合zmk,gpio-key-wakeup-trigger与zmk,soft-off-wakeup-sources节点让键盘在 Soft Off 状态下按键即可唤醒。读完本文你将掌握从 GPIO Key 定义、kscan 侧带行为sideband behavior到唤醒源注册的完整 Devicetree 配置方法并能直接套用到自己的键盘固件中。背景Soft Off 状态与唤醒需求在 ZMK 中Soft Off 是键盘进入的一种深度低功耗状态系统的大部分外设和扫描逻辑会被关闭键盘不再响应正常的按键扫描。要让键盘从 Soft Off 中恢复必须有一个在关闭流程中仍然保持配置、并带有唤醒中断能力的设备。主文档 soft-off-setup.mdx 将唤醒方案分为三类专用直连引脚Direct Pin、矩阵集成引脚Matrix Integrated Pin以及仅唤醒按键Wakeup-only Key Switch。其中仅唤醒按键方案不需要任何硬件改动只是从现有键盘中挑出一个物理按键专门用于从 Soft Off 唤醒——这正是本节要展开的主题其核心配置片段位于 includes/_gpio-key-wakeup.md。GPIO Key唤醒按键的声明基础无论采用哪种方案唤醒按键的声明都基于 Zephyr 的gpio-keys概念在一个compatible gpio-keys的父节点下每个子节点代表一个 GPIO 按键每个子节点只需定义一个gpios属性——它是一个 phandle-array 类型的完整 GPIO 引脚描述包含引脚号以及正确的上下拉pull up/down与有效电平active high/low标志。对于矩阵 kscan 场景复用矩阵中已有按键引脚的示例如下即关联文档给出的核心代码/ { keys { compatible gpio-keys; soft_off_gpio_key: soft_off_gpio_key { gpios gpio0 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN); }; }; };这里将gpio0的第 2 脚配置为高有效 下拉。需要特别强调的是该 GPIO 设置必须与 kscan 中的设置保持一致若该按键属于 direct kscan直连扫描则应写成(GPIO_ACTIVE_LOW | GPIO_PULL_UP)而示例中(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)对应的是矩阵 kscan 中 MCU 输入引脚的常规配置。选用的引脚应当是用于 Soft Off 唤醒的按键所连接的 MCU 输入引脚——对于col2row列驱动、行输入矩阵MCU 输入引脚就是行row引脚而列col引脚是 MCU 输出引脚。唤醒触发器gpio-key-wakeup-trigger 节点仅仅声明一个 GPIO Key 还不够还需要一个在 Soft Off 关闭过程中被启用的专用设备用于配置该 GPIO Key 的中断使其在按下时唤醒键盘。这一角色由zmk,gpio-key-wakeup-trigger兼容节点承担见 includes/_soft-off-waker.md/ { wakeup_scan: wakeup_scan { compatible zmk,gpio-key-wakeup-trigger; trigger soft_off_gpio_key; wakeup-source; extra-gpios gpio0 12 GPIO_ACTIVE_HIGH; }; };各属性的含义与配置要求如下完整定义见 app/dts/bindings/zmk,gpio-key-wakeup-trigger.yaml 及 docs/docs/config/power.md#gpio-key-wakeup-trigger属性类型说明triggerphandle指向用于唤醒 Soft Off 的 GPIO Key必填wakeup-sourcebool标记该设备具备唤醒键盘的能力此属性必须存在才有意义extra-gpiosGPIO array在进入 Soft Off 前需要被置为有效状态的额外 GPIO 引脚列表其中extra-gpios用于确保唤醒引脚能够正确触发。对于col2row矩阵 kscan这里填写的是与唤醒按键相关的列column引脚——它们是 MCU 输出引脚必须在休眠前保持有效状态否则行引脚上的唤醒信号无法形成完整回路。从绑定定义可以看出trigger被标记为required: true而extra-gpios是可选的 phandle-arrayOptional set of pins that should be set active before sleeping。侧带行为绕过键盘矩阵触发 Soft Offgpio-key-wakeup-trigger负责唤醒而进入Soft Off 则需要通过 kscan 侧带行为kscan sideband behavior驱动来触发。该驱动会装饰/包裹decorate/wrap一个底层 kscan 驱动使 Soft Off 行为能够带外out of band于正常 keymap 处理流程被触发。在矩阵 kscan 场景下实现方式是补充现有矩阵将额外引脚作为row-gpios/col-gpios的新增条目。以下面的既有矩阵为例见 includes/_sideband-matrix.md/ { kscan: kscan { compatible zmk,kscan-gpio-matrix; diode-direction col2row; wakeup-source; col-gpios gpio0 12 GPIO_ACTIVE_HIGH , gpio1 9 GPIO_ACTIVE_HIGH ; row-gpios gpio0 19 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) , gpio0 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) ; }; };为其补充 Soft Off 输入时只需在row-gpios末尾追加一行而无需改动矩阵变换matrix transform/ { kscan: kscan { compatible zmk,kscan-gpio-matrix; diode-direction col2row; wakeup-source; col-gpios gpio0 12 GPIO_ACTIVE_HIGH , gpio1 9 GPIO_ACTIVE_HIGH ; row-gpios gpio0 19 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) , gpio0 4 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) , gpio0 2 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) ; }; };随后用侧带行为驱动装饰该 kscan将新追加的条目映射到 Soft Off 行为/ { side_band_behavior_triggers: side_band_behavior_triggers { compatible zmk,kscan-sideband-behaviors; wakeup-source; kscan kscan; soft_off { column 0; row 2; bindings hw_soft_off; }; }; };关键点在于column与row的值必须对应新增条目的位置。上述示例中新增的是第三个 row索引 2并复用第一个 column索引 0因此soft_off子节点填写column 0、row 2。同时需要把zmk,kscanchosen 值指向新的侧带 kscan 实例/ { chosen { ... zmk,kscan side_band_behavior_triggers; ... }; };侧带驱动各属性的完整说明见 docs/docs/config/kscan.md#kscan-sideband-behavior-driver。Soft Off 行为实例与唤醒源注册hw_soft_off是side_band_behavior_triggers中bindings引用的行为实例。它需要在.overlay/.dts中显式声明用于在 keymap 之外触发进入 Soft Off见 includes/_soft-off-behavior.md/ { behaviors { hw_soft_off: hw_soft_off { compatible zmk,behavior-soft-off; #binding-cells 0; split-peripheral-off-on-press; // Turn peripheral off immediately for reliability hold-time-ms 2000; // Only turn off if the key is held for 2 seconds or longer. }; }; };最后一步是把wakeup_scan设备登记到 Soft Off 唤醒源列表中让 ZMK 的 Soft Off 流程在关闭过程中启用该设备见 soft-off-setup.mdx/ { soft_off_wakers { compatible zmk,soft-off-wakeup-sources; wakeup-sources wakeup_scan; }; };该节点的两个属性配置说明见 docs/docs/config/power.md#soft-off-wakeup-sources属性类型说明compatiblestring必须为zmk,soft-off-wakeup-sourceswakeup-sourcesphandle array指向所有需要在关闭流程中启用、以便后续唤醒键盘的设备列表官方文档还给出了一条实用提示如果将 kscan 本身加入wakeup-sources数组那么按下 kscan 中的任意按键都会唤醒键盘此时soft_off的行为本质上等同于将键盘置于深度睡眠选择这种做法的话除soft_off_wakers节点外其余内容都可以省略。方案对比矩阵 kscan 与 direct kscan 的差异为便于对照这里补充 direct kscan直连扫描场景下的等效配置其完整示例见 includes/_gpio-key-direct.md 与 includes/_sideband-wakeup-direct.mdGPIO Key 定义直连按键通常写成(GPIO_ACTIVE_LOW | GPIO_PULL_UP)按下时把引脚拉低触发而矩阵方案包括仅唤醒场景使用(GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN)由 MCU 输出脚把输入脚拉高触发。唤醒触发设备两者都使用zmk,gpio-key-wakeup-trigger但矩阵方案必须通过extra-gpios列出相关的列输出引脚保证休眠期间输出状态有效。kscan 结构direct 方案用zmk,kscan-gpio-direct配合input-keys soft_off_gpio_key构造一个只有单键的侧矩阵此时soft_off子节点的column/row均为 0矩阵方案则在既有矩阵上追加行条目并按实际位置填写坐标。侧带驱动属性direct 方案通常带auto-enable让侧带驱动自动启用单键扫描矩阵方案中侧带驱动包裹的是既有 kscan。小结与验证路径将以上各节串联矩阵 kscan 下仅唤醒按键的完整配置链路为gpio-keys节点声明按键 →zmk,gpio-key-wakeup-trigger提供唤醒中断能力含extra-gpios保持输出有效→ kscan 矩阵追加行条目并经zmk,kscan-sideband-behaviors包装、在chosen中切换为zmk,kscan→ 声明hw_soft_off行为实例触发 Soft Off →zmk,soft-off-wakeup-sources将唤醒设备登记进关闭流程。如需进一步查阅源码与配置可参考以下仓库文件主文档soft-off-setup.mdx各 include 片段位于 docs/docs/hardware-integration/includes/绑定定义zmk,gpio-key-wakeup-trigger.yaml 与 zmk,soft-off-wakeup-sources.yaml配置说明docs/docs/config/power.mdGPIO Key Wakeup Trigger、Soft Off Wakeup Sources 小节与 docs/docs/config/kscan.mdkscan-sideband-behavior-driver 小节实际使用示例ZMK 仓库中各键盘的.overlay/.dts文件中搜索soft_off_wakers、gpio-key-wakeup-trigger即可找到现成实现作为移植参考。配置完成后将固件刷入键盘触发 Soft Off 后再按下指定按键键盘应能从低功耗状态唤醒并恢复扫描若无法唤醒优先检查 GPIO 上下拉/有效电平是否与 kscan 完全一致以及extra-gpios是否覆盖了相关列输出引脚。赞分享固件嵌入式智能硬件蓝牙【免费下载链接】zmkZMK Firmware Repository项目地址https://gitcode.com/gh_mirrors/zm/zmk点击查看免费下载相关推荐Vuetify v-list 列表组件完全指南单行、双行、三行与可交互分组列表实战Vuetify v list 列表组件完全指南单行、双行、三行与可交互分组列表实战 v list 是 Vuetify 中用于展示信息的核心容器组件可容纳头像固件嵌入式智能硬件蓝牙ZMK 键盘扫描KSCAN驱动配置完全指南从矩阵、直连到组合与测试驱动ZMK 键盘扫描KSCAN驱动配置完全指南从矩阵、直连到组合与测试驱动 ZMK 固件通过键盘扫描Keyboard Scan简称 kscan驱动将物理固件嵌入式智能硬件蓝牙ZMK 固件 TG4x Shield 适配指南40% 键盘矩阵、键位分层与 RGB 灯带配置ZMK 固件 TG4x Shield 适配指南40% 键盘矩阵、键位分层与 RGB 灯带配置 TG4x 是一款采用 8×7 矩阵扫描的 40% 键盘其 ZM固件嵌入式智能硬件蓝牙上一篇FreeRouting终极指南开源PCB自动布线工具从入门到精通下一篇TodoMVC 中的 Js_of_ocaml 实战从 OCaml 字节码编译到可运行的 Todo 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考