ZMK 对 MoErgo Glove80 的板级支持深度解析：板定义、矩阵扫描与固件配置实战

固件嵌入式智能硬件蓝牙【免费下载链接】zmkZMK Firmware Repository项目地址https://gitcode.com/gh_mirrors/zm/zmk点击查看免费下载MoErgo Glove80 是一款基于 nRF52840 的无线分体人体工学键盘本篇文章以 app/boards/moergo/glove80/readme.md 为核心骨架结合仓库中完整的板定义源码DTS 设备树、Kconfig 默认配置、默认键位图与构建脚本系统讲解 ZMK 主分支是如何支持 Glove80 的。读完本文你将掌握 Glove80 板定义的文件结构、左右半区矩阵变换的实现方式、RGB 灯效与背光的底层配置以及如何在主分支 ZMK 与 MoErgo 官方定制固件之间做出正确的选型决策。一、板级支持概览主分支 ZMK 与 MoErgo 定制固件的关系Glove80 是 MoErgo 推出的无线分体键盘其板定义位于仓库 app/boards/moergo/glove80 目录下为 ZMK 提供了完整的键盘支持。需要特别强调的是MoErgo 生态存在两套固件路径主分支 ZMK本文所在仓库提供了 Glove80 的完整板定义官方声明主分支 ZMK 预期可以在 Glove80 上良好运行原文mainline ZMK is expected to work well with Glove80。MoErgo 定制版 ZMKMoErgo 在开源社区维护了一份定制版 ZMK额外提供 RGB 状态指示灯等功能并会定期合并主分支的最新改动但不保证始终与主分支完全同步。在支持责任上存在明确分工MoErgo 官方只对其定制版固件提供技术支持而 ZMK 社区无法直接为 MoErgo 的定制 fork 提供支持。这意味着如果你使用主分支 ZMK 编译 Glove80 固件遇到问题时可以向 ZMK 社区求助如果你使用 MoErgo 定制固件或其在线配置器生成的固件则应联系 MoErgo 官方。MoErgo 还提供在线布局配置器与固件构建服务基于其定制 fork用户无需搭建本地编译环境即可生成固件。对于希望深度定制键位、使用最新 ZMK 特性或参与开发的用户本仓库的板定义则是进行本地构建的基础。二、板定义文件结构一个板两个兄弟目标Glove80 是分体键盘ZMK 的板定义采用了共享板 左右半区兄弟目标的组织方式。从 glove80.zmk.yml 可以清晰看到这一点file_format: 1 id: glove80 name: Glove80 type: board arch: arm url: https://www.moergo.com/ features: - keys - underglow - backlight - studio outputs: - usb - ble siblings: - glove80_lh - glove80_rhtype: board这是完整的板定义而非 shield 扩展板arch: arm对应 Cortex-M 架构features声明支持按键、RGB 底灯underglow、背光backlight以及 ZMK Studiooutputs同时支持 USB 与 BLE 两种输出siblings声明左右两个兄弟目标glove80_lh左手与glove80_rh右手分体键盘的每一半都有独立的固件构建目标。在构建时glove80_lh与glove80_rh是用户实际选择的目标。目录中还保留了旧的 glove80.yamltype: mcu其中列出了 nRF52840 平台支持的外设adc、usb_device、ble、ieee802154、pwm、watchdog、gpio、i2c、spi 等可作为硬件能力清单参考。整个目录的核心文件分工如下文件作用glove80.dtsi左右手共享的设备树SoC 头文件、矩阵变换、kscan、分区表、时钟/外设使能glove80-layouts.dtsi物理布局physical layout定义glove80_lh.dts / glove80_rh.dts左右手各自的设备树GPIO 映射、LED、背光、电池、EXT 连接器glove80_lh-pinctrl.dtsi / glove80_rh-pinctrl.dtsi左右手的引脚控制pinctrl配置glove80.keymap默认键位图三层DEFAULT / LOWER / MAGICglove80_lh_defconfig / glove80_rh_defconfig左右手的 Kconfig 默认配置glove80.zmk.yml / glove80.yaml板级元数据board.cmake烧录器支持nrfjprog 与 UF2CMakeLists.txt / usb_serial_number.c板级源码与 USB 序列号逻辑三、硬件平台与设备树总览nRF52840 UF2 启动Glove80 的核心 SoC 是 Nordic nRF52840。在共享设备树 glove80.dtsi 的开头可以看到/dts-v1/; #include nordic/nrf52840_qiaa.dtsi #include common/nordic/nrf52840_uf2_boot_mode.dtsinrf52840_qiaa是带 1MB Flash / 256KB RAM 的 QFAA 封装型号nrf52840_uf2_boot_mode.dtsi引入 UF2 启动模式支持对应 defconfig 中的CONFIG_BUILD_OUTPUT_UF2y与 UF2 Family ID0x9807B007见 glove80_lh_defconfig。设备树的chosen节点完成了 ZMK 关键组件的挂载chosen { zmk,kscan kscan0; zmk,physical-layout physical_layout0; zephyr,code-partition code_partition; zephyr,sram sram0; zephyr,flash flash0; };Flash 分区表glove80.dtsi将 1MB Flash 划分为 SoftDevice 分区0x00000–0x26000、代码分区0x26000–0xc6000供应用固件使用、存储分区0xec000–0xf4000供 NVS 设置存储使用与引导分区0xf4000–0x100000。此外reg1启用了 DCDC 稳压模式NRF5X_REG_MODE_DCDC以提升能效adc、gpiote、gpio0、gpio1、usbd均被显式使能。四、矩阵扫描与物理布局6 行 × 14 列的映射艺术Glove80 拥有 80 余个按键底层扫描矩阵为 6 行 × 14 列但物理按键排布并非矩形因此需要矩阵变换matrix transform将扫描坐标重映射为物理位置。共享设备树中定义了matrix_transform0glove80.dtsimatrix_transform0: keymap_transform_0 { compatible zmk,matrix-transform; columns 14; rows 6; map RC(0,0) RC(0,1) RC(0,2) RC(0,3) RC(0,4) RC(0,9) RC(0,10) RC(0,11) RC(0,12) RC(0,13) RC(1,0) RC(1,1) RC(1,2) RC(1,3) RC(1,4) RC(1,5) RC(1,8) RC(1,9) RC(1,10) RC(1,11) RC(1,12) RC(1,13) ... RC(4,0) ... RC(0,6) RC(1,6) RC(2,6) RC(2,7) RC(1,7) RC(0,7) RC(4,8) ... RC(5,0) ... RC(3,6) RC(4,6) RC(5,6) RC(5,7) RC(4,7) RC(3,7) RC(5,9) ... ; };观察这段映射可以发现两个关键点拱形布局中间行第 6、7 列区域只出现在最下方两行形成 Glove80 标志性的弓形人体工学排布行序重排底部两行中央的拇指簇使用了RC(0,6)、RC(1,6)等高位行号说明拇指键在物理矩阵中分布在不同行通过 transform 统一归位。glove80-layouts.dtsi定义了physical_layout0物理布局并在共享设备树中通过physical_layout0 { transform matrix_transform0; };将其与矩阵变换绑定从而支持 ZMK 的物理布局感知特性如 Studio。扫描方式定义在kscan0节点glove80.dtsikscan0: kscan { compatible zmk,kscan-gpio-matrix; wakeup-source; diode-direction col2row; debounce-press-ms 4; debounce-release-ms 20; };diode-direction col2row二极管方向为列到行确定扫描驱动方式按下去抖 4ms、释放去抖 20ms按压与释放采用不对称去抖以兼顾响应速度与稳定性wakeup-source允许键盘在睡眠状态下被按键唤醒。具体的 GPIO 行/列分配在左右手各自的 .dts 中完成。以左手 glove80_lh.dts 为例kscan0 { row-gpios gpio0 26 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) // LH ROW1 , gpio0 5 (GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN) // LH ROW2 ... col-gpios gpio1 8 GPIO_ACTIVE_HIGH // LH COL6 , ... };行 GPIO 使用GPIO_ACTIVE_HIGH | GPIO_PULL_DOWN内部下拉列 GPIO 使用GPIO_ACTIVE_HIGH这与col2row二极管方向一致。五、左右半区实现col-offset与兄弟目标的差异ZMK 中分体键盘的左右半区通常共享同一个矩阵变换右手的列号整体偏移。右手设备树 glove80_rh.dts 中只用了三行注释加一行配置就完成了镜像/* For right hand, the columns are offset by 7 */ matrix_transform0 { col-offset 7; };即左手的物理布局列范围为 0–6右手整体偏移 7 列使左右半区共享同一份RC()映射描述。这是 ZMK 分体键盘的惯用技巧——左右两半用同一 keymapZMK 在右半区编译时自动把所有物理列号加上col-offset。除矩阵外左右手的主要差异集中在 GPIO 引脚分配对比 glove80_lh.dts 与 glove80_rh.dts 可以看到行/列 GPIO 的具体引脚号、以及 EXT 连接器moergo,glove80-ext的 gpio-map 引脚对应均不同但结构完全对称。左右手各自的 pinctrlglove80_lh-pinctrl.dtsi、glove80_rh-pinctrl.dtsi分别为 SPIWS2812 灯带、PWM背光与 UART 提供 default/sleep 两套引脚状态。六、LED 灯效与背光SPI 驱动的 WS2812 与 PWM 背光Glove80 的 RGB 底灯通过 SPI 总线驱动 WS2812 灯带实现这在左右手设备树中是一致的以 glove80_lh.dts 为例spi3 { compatible nordic,nrf-spim; status okay; pinctrl-0 spi3_default; pinctrl-1 spi3_sleep; pinctrl-names default, sleep; led_strip: ws28120 { compatible worldsemi,ws2812-spi; reg 0; /* ignored, but necessary for SPI bindings */ spi-max-frequency 4000000; chain-length 40; /* 40 keys have underglow at the moment */ spi-one-frame 0x70; spi-zero-frame 0x40; color-mapping LED_COLOR_ID_GREEN LED_COLOR_ID_RED LED_COLOR_ID_BLUE; }; };chain-length 40当前每半区有 40 个按键带底灯spi-one-frame/spi-zero-frameWS2812 通过 SPI 时序编码 1/0 位这是SPI 模拟 WS2812的标准做法color-mappingWS2812 的物理通道顺序为 G-R-B需要在软件层重映射pinctrl 提供 default/sleep 两态睡眠时释放 SPI 引脚以省电。chosen节点中zmk,underglow led_strip;将其挂载为 ZMK 的 RGB 底灯。RGB 灯带由EXT_POWERzmk,ext-power-generic控制供电节点名特意保留为 EXT_POWER 以兼容旧版用户设置control-gpios左右手分别指向 WS2812 的使能引脚并带 100ms 初始化延时。背光方面back_led_backlight是一个 PWM LEDglove80_lh.dtsback_led_backlight: pwmleds { compatible pwm-leds; pwm_led_0 { pwms pwm0 0 PWM_USEC(20) PWM_POLARITY_NORMAL; }; };这是一颗电源指示灯defconfig 注释中明确说明目前它被用作 USB 连接状态指示灯见下节。七、固件默认配置解析defconfig 逐项解读左右手各有独立的 Kconfig 默认配置glove80_lh_defconfig右手版本基本一致以下是关键配置项的解读基础能力与设备标识CONFIG_ZMK_USBy CONFIG_ZMK_BLEy CONFIG_ZMK_KEYBOARD_NAMEGlove80 Left CONFIG_USB_DEVICE_PID0x27db CONFIG_USB_DEVICE_VID0x16c0 CONFIG_USB_DEVICE_MANUFACTURERMoErgo CONFIG_USB_DEVICE_SNmoergo.com:GLV80-0123456789ABCDEF CONFIG_BT_DIS_PNP_PID0x27db CONFIG_BT_DIS_PNP_VID0x16c0 CONFIG_BT_DIS_MANUFMoErgo CONFIG_BT_DIS_MODELGlove80同时启用 USB 与 BLE 输出USB VID/PID0x16c0 / 0x27db与 BLE PNP 信息保持一致出厂序列号格式固定为moergo.com:GLV80-...。值得注意的是CONFIG_USB_DEVICE_SN是写死的默认值而板目录下的 usb_serial_number.c 通过 CMakeLists.txt 编译进固件负责生成更合理的 USB 序列号逻辑。系统与无线优化CONFIG_BT_CTLR_TX_PWR_PLUS_8y # 蓝牙发射功率 8dBm CONFIG_BT_GATT_ENFORCE_SUBSCRIPTIONn # 规避 Windows 电池通知 bug CONFIG_ARM_MPUy # 启用 MPU 内存保护 CONFIG_CLOCK_CONTROL_NRF_K32SRC_XTALy # 使用 32kHz 外部晶振构建产物与存储CONFIG_BUILD_OUTPUT_UF2y CONFIG_BUILD_OUTPUT_UF2_FAMILY_ID0x9807B007 CONFIG_USE_DT_CODE_PARTITIONy CONFIG_NVSy CONFIG_SETTINGS_NVSy CONFIG_FLASHy固件产物包含 UF2 格式配合 board.cmake 中的uf2.board.cmake与nrfjprog.board.cmake--nrf-familyNRF52 --softreset既支持拖拽式 UF2 烧录也支持 nrfjprog 命令行烧录。RGB 底灯配置含重要安全约束CONFIG_ZMK_RGB_UNDERGLOWy CONFIG_ZMK_RGB_UNDERGLOW_EXT_POWERy CONFIG_ZMK_RGB_UNDERGLOW_ON_STARTn CONFIG_ZMK_RGB_UNDERGLOW_BRT_STEP4 CONFIG_ZMK_RGB_UNDERGLOW_BRT_MIN4 CONFIG_ZMK_RGB_UNDERGLOW_BRT_MAX80 CONFIG_ZMK_RGB_UNDERGLOW_EFF_START3 CONFIG_ZMK_RGB_UNDERGLOW_HUE_START285 CONFIG_ZMK_RGB_UNDERGLOW_SAT_START75 CONFIG_ZMK_RGB_UNDERGLOW_BRT_START16defconfig 中以大写注释给出了硬件级安全警告CONFIG_ZMK_RGB_UNDERGLOW_BRT_MAX禁止配置超过 80超过 80% 亮度会增大电流并可能损坏电脑官方声明超过该值即视为保修失效。默认启动亮度为 16约 20%起始色相 285偏紫饱和度 75起始效果索引 3。背光电源指示灯CONFIG_ZMK_BACKLIGHTy CONFIG_ZMK_BACKLIGHT_ON_STARTy CONFIG_ZMK_BACKLIGHT_BRT_START5 CONFIG_ZMK_BACKLIGHT_AUTO_OFF_IDLEy CONFIG_ZMK_BACKLIGHT_AUTO_OFF_USBy背光被用作 USB 连接指示空闲时自动关闭、USB 连接时自动关闭逻辑由AUTO_OFF_USB与配套源码实现配合 glove80.dtsi 中zmk,backlight back_led_backlight的挂载。HID 兼容性修正CONFIG_ZMK_HID_CONSUMER_REPORT_USAGES_BASICy注释明确指出完整的双字节 Consumer 报告在部分操作系统尤其是 macOS存在兼容性问题因此使用更基础的单字节 usage 空间。调试选项CONFIG_ZMK_USB_LOGGING/CONFIG_ZMK_RTT_LOGGING默认关闭调试相关的CONFIG_DEBUG、CONFIG_ZMK_SPLIT_BLE_PERIPHERAL_STACK_SIZE1300等均被注释供开发者按需开启。八、默认键位图三层布局与 Tap-Dance 层切换Glove80 的默认键位图在 glove80.keymap 中定义左右手的目标 keymapglove80_lh.keymap、glove80_rh.keymap只是简单#include glove80.keymap确保左右手使用完全一致的键位定义配合上文col-offset完成镜像。默认键位图包含三个层default_layer第 0 层标准 QWERTY 布局顶部是 F1–F10 与/-主键区字母与数字最下方一行左右各有 6 键拇指簇左右内侧分别是LOWER使用 tap-dance、BSPC/DEL、LALT/RALT、RET/SPACE等lower_layer第 1 层媒体键C_BRI_DN亮度减、C_BRI_UP亮度加、C_PREV/C_NEXT/C_PP播放控制、C_MUTE/C_VOL_DN/C_VOL_UP音量控制、导航键HOME/END/PG_UP/PG_DN、数字小键盘KP_N1…KP_N0、KP_ENTER、KP_DOT等以及CAPS、INS、PSCRN、SLCKmagic_layer第 2 层系统与灯效控制——BT_CLR清除蓝牙配对、bt_0–bt_3切换蓝牙 profile、out OUT_USB切换输出、bootloader进入引导模式、sys_reset软复位以及一整套 RGB 控制RGB_SPI/RGB_SAI/RGB_HUI/RGB_BRI/RGB_TOG/RGB_SPD/RGB_SAD/RGB_HUD/RGB_BRD/RGB_EFF。该键位图还演示了两个值得借鉴的 ZMK 技巧Tap-Dance 层键layer_td将LOWER键配置为 tap-dance——单次点击或长按是mo LOWER临时层再次点击则是to LOWER锁定层layer_td: tap_dance_0 { compatible zmk,behavior-tap-dance; #binding-cells 0; tapping-term-ms 200; bindings mo LOWER, to LOWER; };蓝牙 profile 宏bt_0–bt_3通过宏把切换输出到 BLE 选择蓝牙 profile打包成一个按键动作bt_0: bt_profile_macro_0 { compatible zmk,behavior-macro; #binding-cells 0; bindings out OUT_BLE, bt BT_SEL 0; };键位图头部的 ASCII 注释以可视化方式标注了每行按键的实际物理位置这对理解 6×14 矩阵变换后的最终布局非常有帮助。九、构建与烧录从源码到 UF2 固件Glove80 板定义作为 ZMK 主仓库的一部分用户可以按 ZMK 标准的 west 工作流进行本地构建。板级构建配置要点左右手是两个独立目标构建时分别选择glove80_lh与glove80_rh默认配置即同时启用 USB 与 BLE并生成 UF2 固件Family ID0x9807B007board.cmake 声明了两种烧录途径UF2 拖拽烧录进入 UF2 引导模式后把固件拖入磁盘与nrfjprog--nrf-familyNRF52 --softreset适合 J-Link 调试器若修改了键位或配置只需重新编译对应半区目标并烧录左右手必须烧录各自对应的固件。需要注意的是主分支 ZMK 的板定义与 MoErgo 定制固件的配置存在差异例如定制版额外实现 RGB 状态指示因此不应混用主分支编译产物与 MoErgo 在线配置器产物。十、选型建议与支持边界综合以上分析选择固件路径时可以参考以下结论使用主分支 ZMK功能完整、与最新 ZMK 特性同步且glove80.zmk.yml中声明支持 ZMK Studio 等特性适用于想要深度定制、跟随 ZMK 主线迭代的用户。技术支持渠道为 ZMK 社区。使用 MoErgo 定制固件拥有官方专属功能如 RGB 状态指示灯与在线配置器适合偏好官方开箱体验的用户。技术支持由 MoErgo 官方提供且定制 fork 可能滞后于主分支。社区支持边界ZMK 社区不对 MoErgo 定制 fork 提供支持这一点是 readme 中明确的官方立场。本文所引用的全部技术细节矩阵映射、GPIO 分配、defconfig 参数、默认键位图等均直接来自 app/boards/moergo/glove80 目录下的真实源码开发者可以以此为起点进一步阅读 app/dts/behaviors 与 app/src 了解底层行为实现或在本地按上述流程编译属于自己的 Glove80 固件。赞分享固件嵌入式智能硬件蓝牙【免费下载链接】zmkZMK Firmware Repository项目地址https://gitcode.com/gh_mirrors/zm/zmk点击查看免费下载相关推荐QMK AMJ96 矩阵接线图深度解析读懂 PCB 矩阵编号、可选配列与自定义扫描实现QMK AMJ96 矩阵接线图深度解析读懂 PCB 矩阵编号、可选配列与自定义扫描实现 本篇技术指南以 QMK 仓库中 keyboards/amjkeyboa嵌入式固件驱动开发硬件开发QMK 固件之 AMJ9696 键键盘的硬件配置、矩阵扫描与刷写实战指南QMK 固件之 AMJ9696 键键盘的硬件配置、矩阵扫描与刷写实战指南 AMJ96 是一款 96 键1800 紧凑全尺寸客制化键盘采用阳极氧化铝外壳、嵌入式固件驱动开发硬件开发QMK 固件中的 ASH-1800 键盘支持硬件配置、矩阵映射与固件构建实战QMK 固件中的 ASH 1800 键盘支持硬件配置、矩阵映射与固件构建实战 ASH 1800 是 QMK Firmware 仓库中一款以低成本 G80/G8嵌入式固件驱动开发硬件开发上一篇Powerlevel10k 终极配置指南5分钟打造专业级终端美化下一篇Gorgonia深度学习框架终极指南Go语言AI开发的快速上手秘籍创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考