QMK nein 九键宏键盘（40percentclub/nein）完全指南：硬件、矩阵与固件配置实战

QMK nein 九键宏键盘（40percentclub/nein）完全指南：硬件、矩阵与固件配置实战

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

导读

nein 是 40% Keyboards 社区（di0ib）发布的一款 3×3 正交布局（Ortholinear）9 键宏键盘（Macropad），在 QMK 固件仓库中以keyboards/40percentclub/nein/目录完整收录。本文以该键盘的 readme.md 为骨架，结合 keyboard.json 数据驱动配置与 default 键位源码，系统讲解 nein 的硬件特性、PCB 引脚矩阵映射、编译烧录流程、默认键位功能，并深入数据驱动配置（Data-Driven Configuration）的底层原理，帮助你从零开始构建、自定义并烧录属于自己的 nein 固件。

1. nein 键盘概览：9 键也能高效工作

nein 是一款结构极其简洁的 9 键宏键盘：3 行 × 3 列的正交阵列，整体尺寸与布局非常适合作为媒体控制、导航或自定义宏触发面板。

其核心硬件特性如下：

• 按键规模：9 颗按键，采用正交 3×3 布局；
• 主控方案：以 Pro Micro 为核心，兼容各种尺寸/引脚定义的 Pro Micro 变体（官方文档原文表述为“can fit any of the various different sized variations of Pro Micro”）；
• PCB 项目归属：nein PCB 由 40% Keyboards 社区设计，原始项目主页为 nein project on 40% Keyboards；
• 固件维护：键盘维护人为 QMK Community，硬件支持对象为 nein PCB；
• 矩阵方案：无需行列扫描二极管网络的直接引脚矩阵（Direct Pin Matrix），9 颗按键各自独占一个 GPIO，见 keyboard.json 中的matrix_pins.direct定义。

在 QMK 仓库中，nein 归属于keyboards/40percentclub/（40% Keyboards）目录，该目录下还收录了 gherkin、nori、ut47、4pack、4x4、5x5 等众多 40% 社区键盘，见 40percentclub 目录说明。nein 的完整键盘定义只包含 3 个文件：

• keyboard.json—— 数据驱动配置（硬件、USB、布局、特性开关）；
• keymaps/default/keymap.c—— 默认键位映射；
• readme.md—— 键盘使用与编译说明。

这正是当前 QMK 新版“数据驱动配置”架构的典型形态：硬件定义全部收敛进 JSON，C 代码只需保留键位逻辑。

2. 硬件与矩阵原理：Direct Pin Matrix 怎么接线

2.1 直接引脚矩阵结构

传统键盘通常采用“行-列扫描”矩阵以节省引脚，但 nein 只有 9 个键，因此直接为每个按键分配一个独立引脚。从 keyboard.json 可以清楚看到映射关系：

"matrix_pins": { "direct": [ ["F4", "F5", "F6"], ["F7", "B1", "B3"], ["B2", "B6", "B5"] ] }

这 9 个引脚按照“外层数组=行、内层数组=列”的二维结构组织，与LAYOUT_ortho_3x3布局中的matrix坐标一一对应：

工作原理：在直接矩阵模式下，每个按键的一端接对应 GPIO（并通常通过内部上拉电阻拉高），另一端接地。当按键按下时，该引脚电平被拉低，QMK 的矩阵扫描代码直接读取对应引脚状态即可判定按键事件，无需逐行逐列扫描。这种方案的优势是扫描逻辑简单、支持任意按键组合无冲突（NKRO 天然友好），代价是引脚占用随按键数量线性增长——对 9 键的 nein 而言完全可行。

2.2 Pro Micro 兼容性说明

nein 的development_board字段声明为"promicro"（keyboard.json），该字段在 keyboard.jsonschema 中有明确的枚举约束，可选值包括promicro、elite_c、proton_c、kb2040、promicro_rp2040、blackpill_f401、blackpill_f411等主流主控。

开发者无需为每个 Pro Micro 变体单独编写完整的开发板配置——QMK 在 defaults.hjson 中为promicro提供了默认的引脚映射、pin_compatible: "promicro"兼容声明等预设值，键盘配置继承这些默认值即可。这也是 nein 的 readme 强调“可以适配各种不同尺寸 Pro Micro 变体”的技术基础。

此外，QMK 还提供 Pro Micro 的替代主控转换机制（CONVERT_TO）：例如 promicro_to_promicro_rp2040 转换定义 显示，CONVERT_TO=promicro_rp2040已弃用，当前应按硬件实际类型改用CONVERT_TO=sparkfun_pm2040或CONVERT_TO=rp2040_ce。这类转换器可让你把原本基于 AVR Pro Micro 的键盘固件直接编译到 Arm 主控上，进一步印证了“兼容多种 Pro Micro 变体”的可行性。

3. 数据驱动配置详解：keyboard.json 逐项解析

nein 没有传统意义上的config.h/rules.mk（新架构下硬件配置已迁移至 JSON），完整配置如下：

{ "keyboard_name": "The nein Keyboard", "manufacturer": "di0ib", "url": "http://www.40percent.club/2019/04/nein.html", "maintainer": "qmk", "usb": { "vid": "0x4025", "pid": "0x9999", "device_version": "99.9.9" }, "development_board": "promicro", "features": { "bootmagic": true, "extrakey": true, "mousekey": true, "nkro": true }, "qmk": { "locking": { "enabled": true, "resync": true } }, "matrix_pins": { "direct": [ ["F4", "F5", "F6"], ["F7", "B1", "B3"], ["B2", "B6", "B5"] ] }, "layouts": { "LAYOUT_ortho_3x3": { "layout": [ {"x": 0, "y": 0, "matrix": [0, 0]}, {"x": 1, "y": 0, "matrix": [0, 1]}, {"x": 2, "y": 0, "matrix": [0, 2]}, {"x": 0, "y": 1, "matrix": [1, 0]}, {"x": 1, "y": 1, "matrix": [1, 1]}, {"x": 2, "y": 1, "matrix": [1, 2]}, {"x": 0, "y": 2, "matrix": [2, 0]}, {"x": 1, "y": 2, "matrix": [2, 1]}, {"x": 2, "y": 2, "matrix": [2, 2]} ] } } }

各字段含义与影响如下：

• keyboard_name/manufacturer/url/maintainer：键盘显示名称、制造商（di0ib）、项目主页与维护者标识，编译和 USB 枚举时会使用到这些元数据；
• usb：VID 为0x4025、PID 为0x9999、设备版本99.9.9。注意这是一组示意的自定义标识，若与他人键盘冲突可自行修改；
• development_board：声明采用 Pro Micro 开发板，编译器据此自动继承对应的引脚布局与启动配置；
• features：编译期功能开关——
  • bootmagic: true启用 Bootmagic（按住指定键上电即可进入刷写模式等快捷操作）；
  • extrakey: true启用多媒体/系统按键支持（nein 默认键位中的KC_MUTE、KC_MPLY、KC_STOP、KC_MPRV、KC_MNXT都依赖它）；
  • mousekey: true启用鼠标按键支持；
  • nkro: true启用 N-Key Rollover（全键无冲突），让 9 键同时按下也能被准确识别；
• qmk.locking：启用按键锁定（Locking）支持并将resync置真，用于配合QK_LOCK类键码的锁定/解除同步行为；
• matrix_pins.direct：直接矩阵引脚映射，见上一节；
• layouts.LAYOUT_ortho_3x3：定义 9 键的物理布局，每个条目用x/y坐标描述按键在键盘上的位置，用matrix: [行, 列]关联到具体矩阵坐标。这是 QMK 可视化布局与键位 C 代码之间的桥梁。

4. 默认键位映射：媒体控制 + 方向导航

nein 的默认键位保存在 keymaps/default/keymap.c，核心代码如下：

#include QMK_KEYBOARD_H const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [0] = LAYOUT_ortho_3x3( KC_MUTE, KC_HOME, KC_MPLY, MO(1), KC_UP, KC_END, KC_LEFT, KC_DOWN, KC_RGHT ), [1] = LAYOUT_ortho_3x3( QK_BOOT, _______, KC_STOP, _______, _______, _______, KC_MPRV, _______, KC_MNXT ), };

4.1 Layer 0（默认层）：媒体 + 光标

这一层把 9 键设计为“媒体控制 + 光标导航”面板：最上排是静音/播放等媒体键，下两排是完整的方向键与 Home/End 跳转键，非常适合影音播放或文档编辑场景。

4.2 Layer 1（按住 MO(1) 进入）：刷写入口 + 媒体扩展

Layer 1 通过 Layer 0 中央的MO(1)临时层切换触发（按住生效，松开恢复）。值得关注的是QK_BOOT：它被放在 Layer 1 的 (0,0) 位置，即左上角第一个键，与bootmagic功能叠加后，你可以通过“按住QK_BOOT所在键（或按 Bootmagic 约定）上电/复位”快速进入刷写模式，为后续固件更新提供了硬件级与固件级的双保险。_______（透明键）表示该位置沿用下层（Layer 0）的键码，未显式定义的位置全部继承默认层行为。

从源码结构可以推断：default 键位刻意把媒体键分散到两层——Layer 0 承担高频操作（播放/暂停、静音），Layer 1 承担低频操作（停止、上一曲、下一曲、进刷写模式），体现“一层高频、一层低频”的分层设计思路。你也可以按照同样模式自由增删层、重排按键。

5. 构建与烧录：一条命令从源码到固件

5.1 环境准备

开始编译前需先配置好 QMK 构建环境。官方推荐流程（详细步骤参见仓库内文档）：

1. 阅读 getting_started_introduction.md 了解 QMK 与固件构建的整体流程；
2. 按照 getting_started_build_tools 指引（对应仓库 Makefile 与 builddefs 目录的构建体系）安装编译器、qmkCLI 等工具；
3. 若你是 QMK 新手，可跟随 newbs.md 完整入门教程逐步操作。

5.2 编译 default 键位

在构建环境就绪后，进入仓库根目录执行：

make 40percentclub/nein:default

该命令会：

1. 解析keyboards/40percentclub/nein/keyboard.json中的硬件配置；
2. 编译keymaps/default/keymap.c的键位逻辑；
3. 链接生成可直接烧录的.hex（AVR Pro Micro）固件文件。

编译产物默认输出在build/目录下。若你希望自定义键位，可先复制 default 目录新建一个键位目录（例如keymaps/mykeymap/），修改其中的keymap.c后执行make 40percentclub/nein:mykeymap即可。

5.3 刷写固件

Pro Micro 使用 Caterina bootloader，常见烧录方式有两种：

• 使用 QMK Toolbox：进入刷写模式（通过QK_BOOT键或 Bootmagic）后，用图形化工具选择对应.hex文件点击 Flash；
• 使用命令行：qmk flash -kb 40percentclub/nein -km default，或先make 40percentclub/nein:default编译，再配合avrdude/QMK CLI 烧录。

更详细的刷写方法见 flashing.md 与 newbs_flashing.md。另外，得益于第 2 节提到的CONVERT_TO机制，若你手头只有 RP2040 等 Arm 主控，也可以参考 feature_converters.md 中的转换说明，将 nein 固件编译到替代主控上运行。

6. 常见问题与扩展建议

6.1 按键无响应或触发错误

• 检查引脚映射：确认焊接的 GPIO 与 keyboard.json 中matrix_pins.direct一致；改线后必须同步修改 JSON 并重新编译；
• 检查 Pro Micro 型号：不同变体的引脚命名（如F4、B1这类 AVR 端口名）可能不同，Arm 主控还会使用GPx命名，需按实际主控核对；
• 验证 Bootmagic：若开启了bootmagic，注意其默认触发的组合键位置，避免误触导致键位被重置。

6.2 想要更丰富的功能

• 自定义宏：QMK 支持在 keymap.c 中通过SEND_STRING等 API 编写字符串宏，9 键也能变成效率神器；
• 组合键（Combos）：参考 feature_combo.md，为 3×3 面板定义双键/三键组合触发；
• 更多层：在keymaps数组中继续追加[2]、[3]层，并用MO()、TG()、LT()等层切换键码自由组织；
• 旋钮/编码器扩展：若自行改造 PCB 增加旋转编码器，QMK 的 encoders 驱动 已原生支持，可在键位中绑定音量调节等功能。

6.3 排查编译问题

• 确保在 QMK 仓库根目录执行 make 命令，且已正确初始化子模块；
• 检查keyboard.json是否符合 keyboard.jsonschema 约束（如development_board的枚举值、usb字段格式），JSON 语法错误会直接导致编译失败；
• 若固件过大，参考 squeezing_avr.md 裁减不需要的 feature。

7. 总结

nein 是 40% 键盘生态中极具代表性的 9 键宏键盘：硬件上以 Pro Micro 为核心、直接矩阵免去二极管网络，软件上完整落地了 QMK 的数据驱动配置架构。通过 keyboard.json 可以读懂它的全部硬件定义（USB 标识、特性开关、引脚矩阵、3×3 布局），通过 default 键位 可以看到“媒体控制 + 方向导航 + 双层切换”的实用设计，而一条make 40percentclub/nein:default即可完成从配置到固件的全流程构建。无论你是想直接上手使用，还是把它当作学习 QMK 数据驱动配置与直接矩阵实现的迷你样板，nein 都是一个理想的起点。

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware