企业官网建设流程全解析

4pplet Waffling60 Rev D ISO 矩阵布线图解读：QMK 键位矩阵编号与 ISO 布局变体实战指南

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

本文以 QMK 固件仓库中 keyboards/4pplet/waffling60/rev_d_iso/matrix_diagram.md 为核心，系统解读 Waffling60 Rev D ISO 版本的键位矩阵布线（Matrix Wiring）图，说明行/列编号规则、ISO 回车与 2u 退格等特殊键位在矩阵中的坐标，以及 Tsangan/WKL/HHKB、10u 空格等底部配列变体。读完本文，你将掌握如何阅读 QMK 键盘的矩阵布线图、如何将图中坐标与 keyboard.json 中的matrix字段一一对应，以及如何据此编写或修改键位映射。

一、文档定位：矩阵布线图在 QMK 键盘开发中的作用

在 QMK 中，每个按键并不直接对应一个 GPIO 引脚，而是通过"行（Row）× 列（Col）"矩阵方式扫描。matrix_diagram.md正是用于描述 PCB 上每个物理按键落在矩阵中哪个坐标的示意图，它是连接硬件走线与固件keyboard.json中matrix坐标的桥梁。

Waffling60 是 4pplet 设计的 60% MX 轴键盘 PCB（热插拔与焊接版均有），Rev D ISO 是其中的 ISO（国际标准）配列版本。其固件配置位于仓库 keyboards/4pplet/waffling60/rev_d_iso/ 目录，构建命令为：

make 4pplet/waffling60/rev_d_iso:default

二、矩阵编号规则：行号与列号如何解读

Rev D ISO 的矩阵布线图以"行号 + 列号"的两位十六进制标识每个按键，例如00、1D、2D、3D、4D等。其编号规则为：

• 第一位数字表示行号（Row）：Rev D ISO 共有 5 行，行号取值为0、1、2、3、4；
• 第二位字符表示列号（Col）：共 14 列，列号取值为0–9与A–D（十六进制，A=10、B=11、C=12、D=13）；
• 因此每个按键坐标形如[row, col]，例如0D表示第 0 行、第 13 列。

这一编号在 keyboard.json 中得到印证：其matrix_pins定义了 14 个列引脚（B2、A4、A3、A2、F1、F0、C15、C14、C13、B9、B8、B7、A15、B3）与 5 个行引脚（B14、A9、B6、B5、B4），即一个 5 行 × 14 列、共 70 个矩阵节点的扫描矩阵。由于配置中diode_direction为COL2ROW，列引脚作为信号线、行引脚作为扫描线。控制核心为 STM32F072（ARM 架构 MCU），引导加载程序为stm32-dfu。

三、完整矩阵布线图（ISO 主配列）

下图为 Rev D ISO 的主配列矩阵布线图（摘自 matrix_diagram.md）：

┌───────┐ 2u Backspace │1D │ └───────┘ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │00 │01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │1D │ ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┐2D │ │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2C │ │ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┴┬───┤ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3C │3D │ ├────┴┬──┴┬──┴──┬┴───┴───┴──┬┴──┬┴───┴───┴──┬┴───┴┬───┬─┴───┤ │40 │41 │42 │44 │46 │48 │4B │4C │4D │ └─────┴───┴─────┴───────────┴───┴───────────┴─────┴───┴─────┘

3.1 各区块坐标逐行对照

结合 keyboard.json 中的LAYOUT_all定义，可将图中坐标与物理键位逐一对应：

图中出现"跳号"的键位（如第 4 行缺少43、45、47、49、4A）属于正常现象：keyboard.json的LAYOUT_all中直接以[4, 4]、[4, 6]、[4, 8]等坐标跳过未使用的矩阵节点，说明这些矩阵位置没有实际按键或仅用于其他配列变体。

3.2 ISO 配列的矩阵特征

相比 ANSI 配列，ISO 配列在矩阵图上有三个典型特征：

1. ISO 回车（Enter）占用独立矩阵节点2D：该键为倒 L 形大键，图中用竖排的│2D │标出，横跨第 2 行与第 3 行之间；
2. 第 3 行多出一个 ISO 专用键：位于左 Shift 右侧的< >（ISO 反斜杠）键位，坐标为31，对应固件键码KC_NUBS；
3. 2u 退格：主配列下 Backspace 为 2u 宽度，横跨两个矩阵坐标0D与1D，其中1D是额外占用的行 1 节点，这正是图中右上角单独框出1D的原因。

在 keymaps/default/keymap.c 中可以看到这套矩阵的实际使用：默认层[0]以LAYOUT_all(...)宏初始化，第 0 行末尾依次填入KC_NO（对应0D）与KC_BSPC（对应1D），第 3 行KC_NUBS后紧跟 Z 键——与矩阵图中31节点的位置完全吻合；而 Fn 层[1]在1D位置对应KC_DEL、0D位置为KC_TRNS，2D位置的 ISO 回车在两层均为KC_ENT。

四、底部配列变体：Tsangan / WKL / HHKB 与 10u 空格

matrix_diagram.md 在主体矩阵图之后，还给出了三种底部（底行）配列变体，它们是 Rev D ISO 通过热插拔或焊接跳线支持的可选配列：

┌─────┬───┬─────┬───────────────────────────┬─────┬───┬─────┐ │40 │41 │42 │46 │4B │4C │4D │ Tsangan/WKL/HHKB └─────┴───┴─────┴───────────────────────────┴─────┴───┴─────┘ ┌─────┬───┬───────────────────────────────────────┬───┬─────┐ │40 │41 │46 │4C │4D │ 10u Spacebar └─────┴───┴───────────────────────────────────────┴───┴─────┘

• Tsangan / WKL / HHKB 配列：底行变为左 Ctrl（40）、左 Win（41）、左 Alt（42）各 1.5u，中间 7u 空格（46），右侧右 Alt（4B）、右 Win（4C）、右 Ctrl（4D）各 1.5u；该配列同时意味着第 3 行的左右 Shift 均为 1.25u 或 2.25u/2.75u 的 WKL 风格（图中标注为 Tsangan/WKL/HHKB 共用）；
• 10u 空格配列：底行只保留 1.5u 的40、41与4C、4D，中间用一整根 10u 空格（46）填充，适合 HHKB 风格外壳。

这些变体与 keyboard.json 中定义的四个布局宏一一对应：LAYOUT_60_iso_tsangan_split_rshift、LAYOUT_60_iso_tsangan_split_bs_rshift、LAYOUT_60_iso_wkl_split_rshift、LAYOUT_60_iso_wkl_split_bs_rshift。以LAYOUT_60_iso_wkl_split_rshift为例，其底行只引用了矩阵节点[4, 0]、[4, 2]、[4, 6]、[4, 11]、[4, 13]，与图中 WKL 配列使用的40、42、46、4B、4D完全一致——由于没有引用41、4C，这些位置对应的 1.5u 键（左 Win、右 Win）在 WKL 配列下被省略。而LAYOUT_all（别名LAYOUT）是覆盖全部节点的主宏，用于默认键位映射。

五、从矩阵图到固件：坐标如何驱动扫描与键值

阅读矩阵布线图的价值最终体现在固件层，其数据流可以概括为：

1. 引脚映射：keyboard.json的matrix_pins将行/列引脚（如B2、B14）绑定到矩阵行列；Rev D ISO 为 5 行 × 14 列，diode_direction: COL2ROW决定二极管方向；
2. 布局宏：layouts中的每个LAYOUT_*通过"matrix": [row, col]字段，把物理按键（含宽度w、高度h信息）映射到矩阵坐标，例如 ISO 回车写为{"matrix": [2, 13], "x": 13.75, "y": 1, "w": 1.25, "h": 2}；
3. 键值数组：keymaps/default/keymap.c中以LAYOUT_all(...)按矩阵顺序填入 QMK 键码，QMK 扫描到某坐标按下后，即可索引出对应键值。

因此，当你要为 Rev D ISO 自定义键位时，只需对照本图确认目标键的矩阵坐标，在keymap.c对应槽位填入键码即可。若需调整底行配列，则应改用keyboard.json中对应的LAYOUT_60_iso_*宏（或基于LAYOUT_all自行裁剪），例如默认键位映射可参考 keymaps/default/keymap.c 中的KC_LCTL、KC_LGUI、KC_LALT、三空格KC_SPC、KC_RALT、KC_RGUI、KC_RCTL排列。

六、与其他 Rev 版本的矩阵图差异

Waffling60 系列各版本在仓库中均配有矩阵图，可作为横向参考：

• rev_e/matrix_diagram.md（Rev E 焊接版）：主配列将 2u 退格坐标标为2D（占用第 2 行列尾节点），ISO 回车为3D，并额外给出 2.25u 左 Shift/2.75u 右 Shift、Standard（6u 底行）、3U 分裂空格等更多变体；
• Rev D ISO 与 Rev E 的差异源于 PCB 走线与焊接跳线的不同，矩阵节点分配也因此不同——这正是每个版本单独维护一张矩阵图的原因。

七、总结与查阅指引

矩阵布线图是 QMK 键盘固件开发中最直接的硬件参照物。通过 Rev D ISO 的这张图，你可以：

• 快速定位任意键位（如 ISO 回车2D、2u 退格1D）的矩阵坐标；
• 理解 ISO 配列在行列矩阵中如何"额外"占用节点；
• 在 Tsangan/WKL/HHKB 与 10u 空格配列之间切换时，知道哪些矩阵节点被复用、哪些被省略；
• 结合 keyboard.json 与 keymaps/default/keymap.c 完成从布线图到实际键值的落地。

建议继续阅读仓库内的 readme.md（Rev D ISO 的构建与 DFU 刷写说明，含 Bootmagic 进入引导模式的替代方法）、rules.mk（含 APM32 MCU 兼容的 DFU 后缀参数）以及rev_e系列矩阵图，以完整掌握 Waffling60 全系列的矩阵设计思路。

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