QMK 键盘矩阵图解析：ALF DC60 的 5×15 矩阵坐标与 60% 布局变体对照指南

QMK 键盘矩阵图解析ALF DC60 的 5×15 矩阵坐标与 60% 布局变体对照指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware矩阵图Matrix Diagram是 QMK 键盘移植中最容易被忽略、却最能体现 PCB 硬件与固件映射关系的文档它以 ASCII 图形记录“矩阵坐标 → 物理键位 → 布局变体”三者之间的对应关系。本文以 keyboards/alf/dc60/matrix_diagram.md 为蓝本结合同目录下的 keyboard.json 与 keymaps/default/keymap.c完整讲解 ALF DC60 这块 60% PCB 的矩阵结构并说明如何借助矩阵图编写键位、选择布局变体、核对矩阵扫描配置。读完本文你将掌握 QMK 矩阵坐标的读写方法并能独立为一个陌生 60% PCB 还原、验证其矩阵图。矩阵图在 QMK 开发中的角色QMK 固件并不直接认识“Esc 键”或“空格键”它认识的只有矩阵坐标键盘 PCB 上的按键按“行 × 列”排列MCU 通过扫描行列交叉点判断哪个按键被按下固件再把坐标翻译成键值。因此任何一块新键盘进入 QMK 的第一步就是确定其矩阵布局并把它写进 keyboard.json 的layouts中。DC60 的矩阵图由 QMK 维护者 noroadsleft 于 2023-11-21 整理作者在文档开头明确标注Most of these are best-guess. I was using photos I found on ZFrontier as a reference and I dont have the PCB on-hand.即该图基于 ZFrontier 上的实物照片推测而成并非对照 PCB 实物测量。这一“best-guess”声明意味着图中绝大多数坐标与 keyboard.json 一致但个别宽键如 2u Backspace、ISO Enter的内部定位仍需以实物为准下文会具体指出。DC60 矩阵概览5 行 × 15 列从矩阵图可以读出 DC60 的硬件矩阵规模行Row0 ~ 4共 5 行列Col0 ~ E共 15 列坐标命名行列的十六进制写法如00表示第 0 行第 0 列0E表示第 0 行第 14 列。这与 keyboard.json 中的硬件定义完全吻合matrix_pins: { cols: [B5, D0, D1, D2, D3, D4, D5, D6, D7, C6, C7, F4, F5, F6, F7], rows: [B0, B1, B2, B3, B4] }, diode_direction: COL2ROW即 15 根列线B5、D0~D7、C6、C7、F4~F7与 5 根行线B0~B4二极管方向为COL2ROW列驱动、行读取。矩阵图的每一格坐标最终都会以matrix: [row, col]的形式出现在 keyboard.json 的布局定义中例如{label: Esc, matrix: [0, 0], ...}、{label: 1, matrix: [0, 1], ...}。完整矩阵图以下是 matrix_diagram.md 的完整矩阵图原文原样保留┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ┌───────┐ │00 │01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │0E │ │0D │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ └─┬─────┤ │10 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1E │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤ ┌──┴┐2D │ ISO Enter │20 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2C │2D │ │1E │ │ └──────┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴────────┘ └───┴────┘ ------------------------ SHIFT ROWS ------------------------- ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3C │3D │3E │ └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘ ┌───────┐ │30 │ 2u LShift └───────┘ ┌────┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬──────┬───┬───┐ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3D │3E │ └────┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴──────┴───┴───┘ ┌────────┐ ┌───┬──────────┐ │30 │ 2.25u LShift │3B │3D │ 1u/2.75u RShift └────────┘ └───┴──────────┘ ┌───┬──────┬───┐ │3B │3D │3E │ 1u/1.75u/1u RShift └───┴──────┴───┘ ------------------------ BOTTOM ROWS ------------------------ ┌────┬────┬────┬──────────┬────┬────────┬───┬───┬───┬───┬───┐ │40 │42 │43 │45 │47 │48 │4A │4B │4C │4D │4E │ └────┴────┴────┴──────────┴────┴────────┴───┴───┴───┴───┴───┘ ┌────┬────┬────┬────────────────────────┬────┬────┬────┬────┐ │40 │42 │43 │47 │4A │4B │4D │4E │ Standard └────┴────┴────┴────────────────────────┴────┴────┴────┴────┘ ┌─────┬───┬─────┬───────────────────────────┬─────┬───┬─────┐ │40 │42 │43 │47 │4B │4D │4E │ Tsangan/WKL/HHKB └─────┴───┴─────┴───────────────────────────┴─────┴───┴─────┘从图中可以读出几个关键事实矩阵第 1 行与第 2 行都没有11、21两列字母区起始于12/22底排只有40、42、43、45、47、48、4A、4B、4C、4D、4E这些坐标参与映射。这些“空洞”是 60% 配列中宽键跨列的结果——一个 2u 键帽会覆盖两个相邻矩阵坐标从而“吃掉”一个列坐标。顶部行2u Backspace 与 60 键配列矩阵图顶部行的关键信息是右侧的0D标注标准配列下0D第 0 行第 13 列与0E第 0 行第 14 列合并为 2u Backspace在 LAYOUT_all 中这两个坐标被定义为两个并排的Backspace键{label: Backspace, matrix: [0, 13], x: 13, y: 0}, {label: Backspace, matrix: [0, 14], x: 14, y: 0}注意这里的x分别为 13 与 14表示两个 1u 键位用户可以在键位图中将二者合并为一个 2u 键w: 2这正是 LAYOUT_60_ansi 中Backspace的做法matrix: [0, 13], w: 2。默认键位图 keymaps/default/keymap.c 则通过LAYOUT_all同时给出两个KC_BSPC由用户在键帽层面决定是否合并。顶部行的0A、0B、0C依次对应-、、Backspace前的常规位置00~09对应Esc与数字键 1~0与 LAYOUT_all 的坐标逐一对应。字母区与 ISO Enter1E 与 2D 的 L 形组合第二行10系列与第三行20系列组成字母区。矩阵图右侧单独绘制了 ISO Enter 的组成1E第 1 行第 14 列与2D第 2 行第 13 列共同构成ISO 回车的 L 形1E位于回车上方、兼作 ISO 配列中的#~键2D是回车本体标准 ANSCI 配列则把2D作为Enter2.25u1E用作\反斜杠。在 keyboard.json 的LAYOUT_60_iso中可以找到对应实现{label: #, matrix: [1, 14], x: 12.75, y: 2}, {label: Enter, matrix: [2, 13], x: 13.75, y: 1, w: 1.25, h: 2}其中 Enter 使用w: 1.25, h: 2描述其 L 形跨行占据的物理空间。这就是矩阵图中1E/2D两块拼图在数据驱动配置中的落地方式——矩阵图描述“坐标怎么接”keyboard.json 描述“键帽怎么摆”。Shift 行变体从 15 键标准行到 2u / 2.25u 左 Shift矩阵图用单独一节SHIFT ROWS绘制第 3 行30系列的四种可能形态完整 15 键行30~3E全部使用1u 键帽的 15 键标准行2u LShift30单独占用两个键位宽度此时31坐标不单独出键右侧仍为完整 1u 键序列2.25u LShift30占据 2.25u配合两种右 Shift 方案3B1u3D2.75u→ 经典 2.25u/2.75u 非对称 Shift3B1u3D1.75u3E1u→ 带 Fn/方向键的三段式右 Shift。对照 LAYOUT_60_ansi左 Shift 为matrix: [3, 0], w: 2.25右 Shift 为matrix: [3, 13], w: 2.75即图中的“2.25u LShift 1u/2.75u RShift”方案而默认键位图使用的 LAYOUT_all 中30与31是两个独立 1u 键默认键位图里31被设置为第二个KC_LSFT并把3C空出、用3D↑与3EMO(1)实现方向键与 Fn 层——对应图中“1u/1.75u/1u”三段式右 Shift 的变体思路。底排变体Standard 与 Tsangan / WKL / HHKB矩阵图最后绘制了底排40系列的三种配置这是 60% 键盘区分“通用性”的关键变体使用的坐标特征全坐标版40 42 43 45 47 48 4A 4B 4C 4D 4E三段空格、含4C右下角 1u等完整拆分能力Standard40 42 43 47 4A 4B 4D 4E1.25u×3 6.25u 空格 1.25u×4通用 ANSI 底排Tsangan / WKL / HHKB40 42 43 47 4B 4D 4E7u 空格两侧各 1.5u Win/Alt右 1u 修饰键HHKB 风格在 keyboard.json 的LAYOUT_all中45与48被定义为两个额外的Space1u/2.25u4C是 1u 的4C位默认键位图中未使用这正是全坐标版底排的存在意义给用户最大的键帽自由度。而 LAYOUT_60_ansi 只保留40、42、43、47、4A、4B(菜单键)、4D、4E其中47直接以w: 6.25定义成标准空格对应 Standard 底排4B在 WKL 配列中则被LAYOUT_all之外的布局按需映射。需要说明的是当前仓库 keyboard.json 声明了 5 个社区布局60_ansi、60_ansi_arrow、64_ansi、60_iso、64_iso其中 Tsangan/WKL/HHKB 底排暂未单列为社区布局但矩阵层面40/42/43/47/4B/4D/4E的物理存在完全支持可在LAYOUT_all基础上自行组合键帽。矩阵图与键盘配置的对应关系将矩阵图与仓库实际配置对照可以得到完整的“图 ↔ 码”映射矩阵规模图 5 行 × 15 列 ↔ keyboard.json 的 5 个 row 引脚、15 个 col 引脚扫描方向diode_direction: COL2ROW↔ 矩阵图隐含的“列扫行读”电气结构QMK 在 quantum/matrix_common.c 中根据该字段决定行列扫描与读键逻辑从源码结构看COL2ROW与ROW2COL分支分别处理行/列驱动方向坐标图中每个AB↔LAYOUT_*中的matrix: [A, B]宽键拆分图中 2u Backspace、ISO Enter、2.25u LShift、7u 空格等跨列键 ↔w/h物理尺寸字段与多个相邻矩阵坐标的合并。默认键位图 keymaps/default/keymap.c 直接以LAYOUT_all编写包含 64 个按键60 键 4 方向键这也解释了为何社区布局中同时存在60_ansi与64_ansi同一矩阵下去掉方向键即 60 配列保留方向键即 64 配列。如何验证矩阵图QMK 调试与键位测试由于矩阵图属于 “best-guess” 推测落地前务必验证。QMK 提供两种验证路径编译与烧录前提已按 docs/newbs_getting_started.md 搭建环境make alf/dc60:default该命令由 readme.md 给出若使用 QMK CLI可执行qmk compile -kb alf/dc60 -km default。矩阵调试DC60 的 keyboard.json 启用了console: true可在固件中加入矩阵调试后通过make alf/dc60:default:flash烧录并用 QMK Toolbox / 串口观察keyboard_report与矩阵扫描输出debug_matrix逐个按压按键核对实际触发的[row, col]是否与矩阵图一致。凡与图不符的坐标应以实测为准修正 keyboard.json 的布局定义。小结ALF DC60 的矩阵图是一份典型的 QMK “硬件坐标说明书”它用 5×15 的十六进制坐标完整交代了 2u Backspace、ISO Enter、2u/2.25u 左 Shift、三段式右 Shift 以及 Standard / Tsangan / WKL / HHKB 底排的全部组合可能。结合 keyboard.json 的引脚与布局定义、keymaps/default/keymap.c 的键位示例即可读懂任意 60% PCB 的矩阵结构并快速上手编写自己的键位图。需要记住的是矩阵图终究是“图”最终权威永远是 PCB 实物与烧录后的实测结果。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考