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

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-2021Ten Key MirroredR1.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维护者 cest73aka fire-h0und主控atmega32u4bootloader 为 halfkaykeyboard.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、D0keyboard.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 010→ row 1、col 0A1→ row A即第 11 行对应 D0 引脚、col 199→ 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]}对应图中的01keyboard.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 图的分区阅读整张图可以拆成四个功能区顶部功能键区row 0 / row 1左侧 4 格00 10 01 11为 Fn、Print Screen、Scroll Lock、Pause中间的02是独立 Esc12 03 13 04、14 15 05 06、16 07 17 08依次对应 F1–F12右侧18 09为 Home 与 Page Up。左侧镜像数字键盘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 NumPlus80、91是两个 2u 键Left NumEnter / Right NumEnter底部A0、A1组成 2u NumZero。主键区row 2–10中间 15 列标准 60% 的字母与符号排布含 2u Backspace、ISO Enter78与68组合、2.25u LShift82等异形键。底部行row AA2 A3 A4 A5 A6 A7 A8 A9 99 79对应 Ctrl、GUI、Alt、Space6.25u、Alt、Menu、Ctrl 与方向键 ← ↓ →即 WKL 风格底排。4.2 列共享的排布特征矩阵扫描的特点是同一列的多个按键共享一条列走线。从图中可以看到典型的列对结构例如345与356同在 col 4/5 附近244与257同在 row 2268与369…… 这种交错排布使得 11 行 × 10 列即可覆盖全部按键而无需为每个按键单独分配引脚。这也是6 与 7 列互换这一缺陷能够被固件轻松吸收的原因——见后文。五、从矩阵图到键位映射与 LAYOUT_all 的对应矩阵图的最终价值在于它决定了 keymaps/default/keymap.c 中LAYOUT_all(...)每个键码应当填写的位置。下表抽取了几组具有代表性的对应关系坐标来自 keyboard.json 的LAYOUT_all与矩阵图物理按键矩阵图编号布局数据 matrix默认键码default keymapFn00[0, 0]MO(1)Print Screen10[1, 0]KC_PSCREsc02[0, 2]KC_ESCF112[1, 2]KC_F1F203[0, 3]KC_F2F514[1, 4]KC_F5数字键 635[3, 5]KC_6数字键 725[2, 5]KC_7Tab主区42[4, 2]KC_TAB左 CtrlA2[10, 2]KC_LCTL右方向 →79[7, 9]KC_RGHT以功能键区为例对照 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编号357 键被映射到 row 2 / col 5编号25——这正是修正后的真实接线状态原本互换的两列在坐标层面被对调吸收从而让键码输出恢复正常。矩阵图文档所呈现的就是修正完成后的最终矩阵任何基于该图编写的键位都不会再出现错位。6.3 通用方法论矩阵坐标即硬件契约从这一案例可以提炼出 QMK 中处理类似缺陷的通用流程确认症状按键输出与键帽标识不一致或某两列键位整体对调定位阅读matrix_diagram.md或自行用 LED/万用表逐列扫描找出真实的矩阵坐标修正修改keyboard.json布局数据中对应键的matrix坐标或直接修改keymaps/*/keymap.c中的键码顺序使其匹配真实走线验证重新编译刷写逐键测试。matrix_pinskeyboard.json中的列引脚顺序D1..D7, F0, F1, F4与diode_direction的取值共同决定了坐标编号的物理含义排查时必须一并核对。七、把矩阵图用在实战中7.1 编写自定义键位自定义 keymap 时建议按如下顺序工作打开矩阵图确定目标按键的两位编号在 keyboard.json 的layouts中找到对应的matrix坐标条目在keymaps/你的keymap/keymap.c中用LAYOUT_all/LAYOUT_ansi_split_bs/LAYOUT_iso_split_bs之一按坐标顺序填写键码使用 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考