企业官网建设流程全解析

QMK 键盘矩阵图完全解读：cest73 TKM-2021 的 matrix_diagram 坐标体系与 6/7 列交换 Bug 修复

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

本篇技术指南以 QMK 固件仓库中 cest73/tkm 的 matrix_diagram.md 为核心，系统讲解 QMK 键盘矩阵图（matrix diagram）的阅读方法、坐标编号规则，以及该文档背后记录的 TKM-2021（Ten Key Mirrored）R1.03 批次 PCB 布线缺陷——数字键 6 与 7 所在列被互换的问题，并说明固件层是如何修正它的。读完本文，你将掌握"矩阵坐标 → 物理按键 → 键位映射"三者之间的对应关系，能够独立读懂任意一款 QMK 键盘的矩阵图，并在遇到接线错误或 PCB 设计缺陷时，通过修改布局定义完成固件级修复。

一、matrix_diagram.md 是什么

在 QMK 仓库中，matrix_diagram.md是一类广泛存在的惯例性文档，通常与readme.md、keyboard.json放在同一键盘目录下，用来以 ASCII 图的形式记录 PCB 上"物理按键与矩阵扫描坐标"的对应关系。类似文档还可见于 1upkeyboards/pi60、adpenrose/akemipad 等众多键盘目录，属于键盘维护者向用户交代硬件事实的标准做法。

对于 cest73/tkm 而言，这份文档不仅是一张普通接线图，它同时承担着一个特殊使命：记录并呈现 R1.03 批次 PCB 上 6 与 7 列互换缺陷被固件修正之后的真实矩阵状态。因此它既是排查问题的依据，也是理解固件坐标分配的唯一权威来源。

二、TKM-2021 键盘硬件背景

在进入矩阵图之前，先补充必要的硬件事实（均来自仓库文件）：

• 键盘名称：TKM 2021 R1.03，制造商 cest73，维护者 cest73（aka fire-h0und）；
• 主控：atmega32u4，bootloader 为 halfkay（keyboard.json），子板采用 Teensy 2.0；
• 矩阵规模：11 行 × 10 列。列走线接 D1、D2、D3、D4、D5、D6、D7、F0、F1、F4；行走线接 B0、B1、B2、B3、B4、B5、B6、B7、C6、C7、D0（keyboard.json）；
• 二极管方向：COL2ROW（列驱动、行读取），这是键盘.json 中diode_direction字段的取值（keyboard.json）；
• 布局：提供LAYOUT_all、LAYOUT_ansi_split_bs、LAYOUT_iso_split_bs三套布局宏，分别对应全键位、ANSI 分裂退格、ISO 分裂退格三种物理配列；
• 硬件卖点：左侧数字键盘（Left Numpad）并做了镜像（Mirrored）设计，为鼠标留出更大的活动空间。

这份键盘的独特之处在于：数字小键盘被整体搬到了主键区左侧，且镜像排布，矩阵图正是揭示这一复杂排布的最好入口。

三、矩阵图坐标编号规则：先读行，再读列

矩阵图使用两位编号标记每个按键在扫描矩阵中的位置，规则为：

第一位 = 行号（row） 第二位 = 列号（col）

其中行号采用十六进制书写（0–9、A），列号采用十进制（0–9）。例如：

• 00→ row 0、col 0；
• 10→ row 1、col 0；
• A1→ row A（即第 11 行，对应 D0 引脚）、col 1；
• 99→ row 9、col 9。

将编号与 keyboard.json 中的matrix_pins对照，可以看到行号 0–A 依次对应行走线 B0、B1、B2、B3、B4、B5、B6、B7、C6、C7、D0，列号 0–9 依次对应列走线 D1、D2、D3、D4、D5、D6、D7、F0、F1、F4，共 11×10 = 110 个矩阵交点，与图中所占格数一致。

该规则同样可以用LAYOUT_all布局数据交叉验证：{"label": "Fn", "matrix": [0, 0]}对应图中的00，{"label": "Print Screen", "matrix": [1, 0]}对应图中的10，{"label": "Scroll Lock", "matrix": [0, 1]}对应图中的01（keyboard.json），三者完全吻合，证明"第一位行、第二位列"的读法无误。

四、TKM-2021 完整矩阵图（原图）

原文档提供的矩阵图如下，图中每个格子的两位编号即对应键的[row, col]坐标；标注在侧边的文字（如 2u Backspace、ISO Enter、2.25u LShift、WKL）用于说明特殊尺寸与异形配列键位：

┌───┬───┬───┬───┐ ┌───┐ ┌───┬───┬───┬───┐┌───┬───┬───┬───┐┌───┬───┬───┬───┐ ┌───┬───┐ │00 │10 │01 │11 │ │02 │ │12 │03 │13 │04 ││14 │15 │05 │06 ││16 │07 │17 │08 │ │18 │09 │ └───┴───┴───┴───┘ └───┘ └───┴───┴───┴───┘└───┴───┴───┴───┘└───┴───┴───┴───┘ └───┴───┘ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ┌───┐ ┌───────┐ │20 │30 │21 │31 │ │22 │32 │23 │33 │24 │34 │35 │25 │26 │36 │27 │37 │28 │19 │38 │ │29 │ │38 │ 2u Backspace ├───┼───┼───┼───┤ ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ ├───┤ └─┬─────┤ │40 │50 │41 │51 │ │42 │52 │43 │53 │44 │54 │55 │45 │46 │56 │47 │57 │48 │58 │ │49 │ │ │ ├───┼───┼───┼───┤ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤ ├───┤ ┌──┴┐78 │ ISO Enter │60 │70 │61 │71 │ │62 │72 │63 │73 │64 │74 │75 │65 │66 │76 │67 │77 │78 │ │69 │ │68 │ │ ├───┼───┼───┼───┤ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┘ ├───┤ └───┴────┘ │39 │90 │81 │91 │ │82 │92 │83 │93 │84 │94 │95 │85 │86 │96 │87 │97 │88 │┌───┐│89 │ ├───┼───┼───┼───┤ ├────┼───┼───┴┬──┴───┴───┴───┴───┴───┴─┬─┴─┬─┴─┬─┴──┬───┘│98 │└───┘ │80 │A0 │59 │A1 │ │A2 │A3 │A4 │A5 │A6 │A7 │A8 │┌───┼───┼───┐ └───┴───┴───┴───┘ └────┴───┴────┴────────────────────────┴───┴───┴────┘│A9 │99 │79 │ └───┴───┴───┘ ┌───────┬───────┐ ┌────────┐ │A0 │A1 │ │82 │ 2.25u LShift └───────┴───────┘ └────────┘ Left Right ┌─────┬─────┬───────────────────────────┬─────┬─────┐ 2u NumZero │A2 │A4 │A5 │A6 │A8 │ WKL └─────┴─────┴───────────────────────────┴─────┴─────┘

4.1 图的分区阅读

整张图可以拆成四个功能区：

1. 顶部功能键区（row 0 / row 1）：左侧 4 格00 10 01 11为 Fn、Print Screen、Scroll Lock、Pause；中间的02是独立 Esc；12 03 13 04、14 15 05 06、16 07 17 08依次对应 F1–F12；右侧18 09为 Home 与 Page Up。
2. 左侧镜像数字键盘（row 0–10，最左侧 4 列）：这是 TKM 的特色区。从上到下依次为- * / Num Lock、+ 9 8 7、= 6 5 4、Tab 3 2 1、Enter . , 0；最外列40、51是两个 2u 键（Left NumPlus / Right NumPlus），80、91是两个 2u 键（Left NumEnter / Right NumEnter），底部A0、A1组成 2u NumZero。
3. 主键区（row 2–10，中间 15 列）：标准 60%+ 的字母与符号排布，含 2u Backspace、ISO Enter（78与68组合）、2.25u LShift（82）等异形键。
4. 底部行（row A）：A2 A3 A4 A5 A6 A7 A8 A9 99 79对应 Ctrl、GUI、Alt、Space（6.25u）、Alt、Menu、Ctrl 与方向键 ← ↓ →，即 WKL 风格底排。

4.2 列共享的排布特征

矩阵扫描的特点是同一列的多个按键共享一条列走线。从图中可以看到典型的"列对"结构：例如34（5）与35（6）同在 col 4/5 附近，24（4）与25（7）同在 row 2，26（8）与36（9）…… 这种交错排布使得 11 行 × 10 列即可覆盖全部按键，而无需为每个按键单独分配引脚。这也是"6 与 7 列互换"这一缺陷能够被固件轻松吸收的原因——见后文。

五、从矩阵图到键位映射：与 LAYOUT_all 的对应

矩阵图的最终价值在于：它决定了 keymaps/default/keymap.c 中LAYOUT_all(...)每个键码应当填写的位置。下表抽取了几组具有代表性的对应关系（坐标来自 keyboard.json 的LAYOUT_all与矩阵图）：

以功能键区为例，对照 keymap.c 第一行：

MO(1), KC_PSCR, KC_SCRL, KC_PAUS, KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5,

在矩阵图上，这些键码依次落在00 10 01 11、02、12 03 13 04、14…… 编号与键码一一呼应。这意味着：当你拿到一张新的矩阵图，就可以直接按图编写 LAYOUT 键码，无需重新猜测接线。

同理，default_ansi_split_bs/keymap.c 与 default_iso_split_bs/keymap.c 分别使用LAYOUT_ansi_split_bs与LAYOUT_iso_split_bs，它们与LAYOUT_all共享同一套物理矩阵坐标，差异仅在于键帽规格与异形键组合方式（如 ISO 回车占据78、68两格，ANSI 则为单格回车）。

六、R1.03 PCB 的 6/7 列互换 Bug 与固件级修复

这是本份矩阵图文档存在的核心原因。原文档开篇即说明：

Due to a nasty PCB layout bug the R1.03 board has "6" and "7" keyboard columns swapped.

而 readme.md 补充了背景：作者在长时间核对原理图后，发现首批 PCB 在布板过程中把 6 与 7 的列接线弄反了；幸运的是，这个问题可以在固件侧轻松修正（原文："Luckily it was trivial to fix in the firmware section"）。

6.1 缺陷的影响

若按 PCB 原设计，"6" 与 "7" 两列的物理走线被互换，会导致：

• 按物理 6 键时，扫描矩阵上报的却是 col 对应 7 的位置；
• 按物理 7 键时，上报的却是 6 的位置；
• 如果不做处理，键位输出将与键帽标识错位，甚至导致同一列相邻键互相"串位"。

6.2 固件中的修正方式

修复不涉及任何硬件改动，只需在布局定义中把 6、7 两键的矩阵坐标按互换后的真实接线填写。查看 keyboard.json 的LAYOUT_all：

{"label": "6", "matrix": [3, 5], ...}, {"label": "7", "matrix": [2, 5], ...},

以及与之相邻的：

{"label": "5", "matrix": [3, 4], ...}, {"label": "8", "matrix": [2, 6], ...},

可以看到 6 键被映射到 row 3 / col 5（编号35），7 键被映射到 row 2 / col 5（编号25）——这正是修正后的真实接线状态：原本互换的两列在坐标层面被"对调"吸收，从而让键码输出恢复正常。矩阵图文档所呈现的，就是修正完成后的最终矩阵，任何基于该图编写的键位都不会再出现错位。

6.3 通用方法论：矩阵坐标即"硬件契约"

从这一案例可以提炼出 QMK 中处理类似缺陷的通用流程：

1. 确认症状：按键输出与键帽标识不一致，或某两列键位整体对调；
2. 定位：阅读matrix_diagram.md或自行用 LED/万用表逐列扫描，找出真实的矩阵坐标；
3. 修正：修改keyboard.json布局数据中对应键的matrix坐标（或直接修改keymaps/*/keymap.c中的键码顺序），使其匹配真实走线；
4. 验证：重新编译刷写，逐键测试。

matrix_pins（keyboard.json）中的列引脚顺序D1..D7, F0, F1, F4与diode_direction的取值共同决定了坐标编号的物理含义，排查时必须一并核对。

七、把矩阵图用在实战中

7.1 编写自定义键位

自定义 keymap 时，建议按如下顺序工作：

1. 打开矩阵图，确定目标按键的两位编号；
2. 在 keyboard.json 的layouts中找到对应的matrix坐标条目；
3. 在keymaps/<你的keymap>/keymap.c中，用LAYOUT_all/LAYOUT_ansi_split_bs/LAYOUT_iso_split_bs之一按坐标顺序填写键码；
4. 使用 QMK CLI 编译：

qmk compile -kb cest73/tkm -km default

刷写时注意：本键盘以 Teensy 2.0 作为子板（bootloaderhalfkay），只需按下 Teensy 上的复位按钮即可进入刷写模式（见 readme.md）。

7.2 排查接线问题

如果你手中的是首批 R1.03 之前的样片、或自行焊接的版本，矩阵图可以作为排查依据：

• 某键无响应 → 检查该键编号对应行列的引脚通路与二极管方向；
• 某列键位整体错位 → 对照矩阵图与matrix_pins顺序，判断是硬件接线问题还是布局坐标填写问题；
• 相邻键互相触发 → 优先怀疑二极管方向（本项目为 COL2ROW）与共列走线。

7.3 理解仓库中的同类文档

QMK 仓库中大量键盘目录都包含matrix_diagram.md，其作用与本例一致：记录矩阵坐标与物理键的对应关系，方便用户阅读 keymap、排查故障。例如 1upkeyboards/pi60 的矩阵图 用0D、2F、4F等编号标注了包含旋转编码器在内的全部键位；adpenrose/akemipad 的矩阵图 则展示了数字小键盘的 2u 键坐标。掌握 TKM-2021 这份图的读法后，可以无差别迁移到这些同类文档上。

八、总结

cest73/tkm 的 matrix_diagram.md 虽然篇幅短小，但承载了三层信息：一是 TKM-2021 全键盘 11×10 矩阵的完整坐标档案；二是"6 与 7 列互换"这一 R1.03 PCB 布线缺陷的公开记录；三是固件完成修正后的事实基准。结合 keyboard.json 中的matrix_pins、diode_direction与布局宏，以及 default keymap，你可以：

• 一眼读懂任意两位编号对应的物理按键与引脚；
• 依据坐标直接编写或修改 keymap；
• 掌握"固件修正硬件缺陷"的标准操作，即通过交换矩阵坐标吸收 PCB 布线错误。

对于任何基于 TKM-2021 进行定制或故障排查的开发者，这份矩阵图都是必须首先阅读的文档。

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