QMK 固件实战40percentclub nori 模块化 4×12 键盘配置与移植解析【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwarenori 是由 di0ib 设计的 40% 模块化键盘使用 3 块 4×4 矩阵小板拼成 4×12 全键阵列以 Arduino Pro Micro 为开发板。本篇技术指南以 QMK 仓库中的 nori 键盘文档 为主线结合其 keyboard.json、rules.mk 与 默认键位 源码系统讲解 nori 的硬件矩阵设计、引脚资源分配、背光/WS2812B 扩展方案以及固件编译与键位定制方法读完即可独立完成 nori 的固件编译、刷写与个性化改造。nori 是什么模块化 4×12 矩阵键盘nori 属于 40percentclub 系列开源键盘项目该系列还包括 Gherkin、Foobar、Tomato 等 40% 与格子布局键盘。从文档定义看nori 是一个4 行 × 12 列4×12全格子矩阵键盘其核心设计思路是模块化键盘整体由3 块可独立焊接的 4×4 矩阵小板拼接而成每块小板承载 16 个按键3 块共 48 键最终构成完整的 4×12 布局。这种模块化设计带来两个显著收益组装灵活每块 4×4 小板可以独立焊接、独立测试降低整体焊接与排查难度规模可扩展理论上可串联更多 4×4 小板组成不同尺寸的键盘但受主控引脚数量限制。在 QMK 仓库中nori 的布局同时支持 4×4、4×8、4×12 三种矩阵形态这一点在 keyboard.json 的layouts字段中有完整定义LAYOUT_ortho_4x416 键、LAYOUT_ortho_4x832 键与LAYOUT_ortho_4x1248 键。而官方默认键位keymaps/default/keymap.c实际使用的是完整的LAYOUT_ortho_4x12全尺寸布局。兼容性说明layouts/community/ortho_4x12/readme.md中登记的社区通用布局LAYOUT_ortho_4x12可直接复用于 nori这意味着 QMK 中所有采用该布局的键位文件都能轻松迁移到 nori 上。硬件设计Pro Micro 的引脚资源分配nori 的固件定义明确使用Arduino Pro MicroATmega32U4作为主控这在 keyboard.json 的development_board: promicro字段中确认。Pro Micro 是 QMK 生态中非常普及的开发板仓库根目录development_board选项中的标准板型之一拥有原生 USB 能力便于直连电脑刷写与使用。为什么只能接 3 块 4×4 小板而不是 4 块文档给出的解释非常明确Pro Micro 可用的数据引脚数量有限。标准 4 块板需要 4 行 16 列 20 个矩阵引脚而 nori 在只使用 3 块板时矩阵规模为 4 行 × 12 列 16 个引脚正好落在 Pro Micro 的资源范围内。实际矩阵接线在 keyboard.json 中记录如下类别引脚列cols12 个F4、F5、F6、F7、B1、B3、B2、B6、D4、C6、D7、E6行rows4 个D3、D2、D1、D0二极管方向COL2ROW矩阵采用COL2ROW列到行二极管方向即二极管阳极接列线、阴极接行线这是多数 QMK 键盘的标准接线方式扫描时按列驱动、按行读取。两个剩余引脚的妙用文档重点强调B5 → 背光电路nori 参考了同系列 Gherkin同样在 keyboards/40percentclub 目录下的做法用 B5 引脚驱动单色背光电路。对应到固件配置即 keyboard.json 中backlight.pin: B5B4 → WS2812B 灯带预留B4 引脚被预留给 WS2812B 可寻址 RGB 灯带扩展固件中通过ws2812.pin: B4声明。这意味着用户可以在不修改 PCB 走线的前提下自行加装灯带并启用 RGB 功能。引脚分配背后的实现证据QMK 的矩阵扫描会根据matrix_pins中声明的行列 GPIO 自动初始化。nori 的 12 列引脚全部取自 Pro Micro 的可用 I/OF 口、B 口、D 口、C 口、E 口这种分配保证了 16 个矩阵引脚 2 个扩展引脚B4、B5的总需求与 ATmega32U4 的引脚资源匹配——这从源码结构上印证了文档所述3 块板 2 个预留引脚的设计上限。固件特性矩阵backlight、rgblight 与 WS2812B 的协同在 keyboard.json 的features字段中nori 默认启用了 7 项 QMK 核心特性特性说明bootmagic启动时按住指定键进入 Bootmagic 配置如切换默认层、交换按键等mousekey支持鼠标按键模拟方向键组合模拟鼠标移动/点击extrakey启用额外 HID 键码多媒体、系统控制键command启用 QMK Command 调试/配置模式nkro支持 N 键无冲突N-Key Rollover多键同时按下不丢键backlight单色背光驱动引脚为 B5rgblightRGB 背光底层使用 WS2812 协议驱动其中rgblight部分的参数配置非常完整体现了官方固件的开箱即用设计rgblight: { saturation_steps: 8, brightness_steps: 8, led_count: 10, animations: { breathing: true, rainbow_mood: true, rainbow_swirl: true, snake: true, knight: true, christmas: true, static_gradient: true, rgb_test: true, alternating: true, twinkle: true } }led_count: 10表示 RGB 灯珠数量预设为 10 颗若自行加装灯带需要按实际灯珠数修改saturation_steps与brightness_steps为 8对应每按一次调节键如RGB_SAD/RGB_VAI的步进档位动画列表一次性启用了 10 种官方 RGBligh 动画效果呼吸、彩虹情绪、彩虹漩涡、贪吃蛇、骑士、圣诞、静态渐变、RGB 测试、交替、闪烁无需额外写代码即可在键位中使用RGB_MODE_*切换。需要特别说明的是backlight 与 rgblight 在 nori 上并存的设计B5 驱动的单色背光与 B4 预留的 WS2812B 灯带分别占用不同引脚两者互不冲突。这正是文档中一个引脚做 Gherkin 式背光、另一个留给 WS2812B思路的固件落地。音频为何关闭nori 的 rules.mk 只有一行关键声明# Disable unsupported hardware AUDIO_SUPPORTED no即硬件上不支持音频输出无蜂鸣器/音频电路固件显式关闭音频特性。这与默认键位中保留的AU_ON/AU_OFF键形成对照由于音频被禁用这两个键在实际固件中不产生音效保留它们更多是为了与 QMK 通用键位模板保持一致。同时keymaps/default/config.h 中定义了DEFAULT_LAYER_SONGSQWERTY/COLEMAK/DVORAK 三种默认层切换提示音说明该配置属于音频特性的一部分在 nori 上同样不会生效。编译与刷写一条命令构建固件nori 的官方 README 给出的构建方式与 QMK 标准流程完全一致。在配置好构建环境后QMK 官方文档中的 build environment setup 与 make guide 步骤在 QMK 仓库根目录执行make 40percentclub/nori:default该命令会编译keyboards/40percentclub/nori键盘目录下keymaps/default键位对应的固件输出.hexAVR 平台固件文件之后即可使用 QMK 工具箱或qmk flash刷写至 Pro Micro。固件元信息在 keyboard.json 中定义为键盘名The nori Keyboard厂商manufacturerdi0ib设计者维护者maintainerqmkUSB VID/PID0x4025/0x0A0C设备版本4.4.4刷写后系统会识别为 VID0x4025、PID0x0A0C的键盘设备。自定义键位的构建方式QMK 支持两种个性化路径在仓库内新增键位目录复制keymaps/default为keymaps/你的名字/修改其中的keymap.c后执行make 40percentclub/nori:你的名字使用社区通用布局由于 nori 登记了ortho_4x4与ortho_4x12两个 community layout任何基于LAYOUT_ortho_4x12的社区键位文件见 layouts/community/ortho_4x12/readme.md都能直接套用到 nori 上方便在类似格子键盘之间迁移键位。默认键位深度解析六层布局与三态层切换nori 的官方默认键位keymaps/default/keymap.c是 40% 键盘键位设计的典型范例充分展示了如何在 48 键的小尺寸上承载完整功能。它定义了6 个层层名称用途0_QWERTY主字母层QWERTY 布局1_COLEMAK备用 Colemak 布局2_DVORAK备用 Dvorak 布局3_LOWER数字行、符号与功能键层4_RAISE数字行、符号层与 LOWER 互补5_ADJUST系统功能层Bootloader、布局切换、AG 交换等主层设计要点QWERTY 主层第 0 层完整继承了标准 60% 键盘的字母区排布并通过底层补齐修饰键| Tab | Q | W | E | R | T | Y | U | I | O | P | Bksp | | Esc | A | S | D | F | G | H | J | K | L | ; | | |Shift| Z | X | C | V | B | N | M | , | . | / | Enter| |Adjust|Ctrl|Alt|GUI|Lower| Space |Raise|←|↓|↑|→ |空格键被拆成 3 个位置左右空格 中间的RAISE/LOWER层切换键形成对称的空格即层切换设计方向键直接放在主层最右侧 4 键KC_LEFT、KC_DOWN、KC_UP、KC_RGHT无需切换层即可使用第 0 层左下角ADJUST使用MO(_ADJUST)临时层切换按住即可进入系统功能层。层切换机制宏与三态层键位文件顶部用宏简化了层切换键的定义#define LOWER MO(_LOWER) #define RAISE MO(_RAISE) #define ADJUST MO(_ADJUST) #define QWERTY PDF(_QWERTY) #define COLEMAK PDF(_COLEMAK) #define DVORAK PDF(_DVORAK)MO(x)是临时层切换按住进入该层、松开返回PDF(x)是QK_DEF_LAYER默认层切换的别名永久切换默认层用于在 QWERTY/Colemak/Dvorak 之间做持久切换。层切换的核心逻辑在文件末尾的钩子函数中实现layer_state_t layer_state_set_user(layer_state_t state) { return update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST); }这是 QMK 经典的tri-layer三层联动模式当_LOWER与_RAISE同时按住时自动进入_ADJUST层松开任一层则退回。这个函数与 quantum 目录下update_tri_layer_state的通用实现对接是 40% 键盘用两层符号层组合出第三层系统功能层的标准化做法。LOWER / RAISE 层符号与功能键的拆分_LOWER与_RAISE分别承载不同符号集LOWER 层上档符号~ ! # $ % ^ * ( )、_ { } |、F1–F12 全功能键以及 ISO 键盘的S(KC_NUHS)/S(KC_NUBS)适配RAISE 层数字行1 2 3 4 5 6 7 8 9 0、- [ ] \、F1–F12以及 ISO 的KC_NUHS/KC_NUBS两层的右下角都放了一组媒体控制键KC_MNXT下一曲、KC_VOLD音量-、KC_VOLU音量、KC_MPLY播放/暂停——这正是extrakey特性提供的能力。ADJUST 层系统与布局切换同时按住 LOWER RAISE 进入的_ADJUST层包含QK_BOOT一键进入 Bootloader方便重新刷写固件QWERTY/COLEMAK/DVORAK三种布局的永久切换对应DEFAULT_LAYER_SONGS中的三首提示音定义AG_NORM/AG_SWAPCmd/Alt 键交换开关macOS 与 Windows 键位习惯切换AU_ON/AU_OFF音频开关nori 硬件无音频详见上文 rules.mk 说明。从 nori 看 40% 键盘的通用设计范式nori 虽然是一款小众的模块化键盘但其固件定义完整呈现了 40% 键盘的三条通用范式对其他同尺寸键盘的移植与定制有直接参考价值引脚即资源矩阵规模、背光、RGB 灯带都受主控可用引脚约束。nori 用 16 个矩阵引脚 2 个预留引脚B4/B5设计恰好用满 Pro Micro 的 I/O 预算这是任何矩阵键盘硬件设计的核心权衡层即功能48 键无法容纳全尺寸键盘的全部按键必须依靠 LOWER/RAISE/ADJUST 多层 tri-layer 联动来折叠符号、功能键与系统操作布局即兼容通过登记community_layouts与提供多尺寸 layout让同一键盘在 QMK 生态中拥有最大的键位复用性。如果你正准备为 nori 编写自己的键位建议从 keymaps/default/keymap.c 复制一份开始保留 tri-layer 骨架与 ADJUST 层的QK_BOOT按需增删符号层内容再用make 40percentclub/nori:你的键位名验证编译——这套流程同样适用于 40percentclub 系列下的其他键盘如 Gherkin。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考