企业官网建设流程全解析

QMK 键盘矩阵图完全解读：以 CannonKeys Crin（matrix_diagram.md）为例

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

本文以 QMK 固件仓库中 CannonKeys Crin 键盘的 matrix_diagram.md 为线索，讲解如何读懂一张 ASCII 键盘矩阵图、理解矩阵坐标（行 × 列）与物理键位的映射关系，并结合 keyboard.json 中的LAYOUT定义、默认键位 与引脚配置，还原一张图纸到一套可编译固件的完整链路。读完本文，你将掌握 QMK 键盘开发中"看矩阵图 → 定位坐标 → 编写 keymap"的核心技能。

一、matrix_diagram.md 是什么：一张"键盘矩阵解剖图"

在 QMK 仓库中，很多键盘目录下都附带一个matrix_diagram.md文件（如 1upkeyboards/pi60、ai03/vega 等，仓库 keyboards 目录下共有 350+ 个同类文件）。它不是给用户看的宣传图，而是给固件开发者与键位作者看的"矩阵接线解剖图"：用纯 ASCII 字符画出每个键位在电气矩阵中所占据的坐标格子。

Crin 是 CannonKeys 出品的一把 80% TKL（无 F 行）客制化键盘，主控为 STM32F072CBT6（见 readme.md）。它的矩阵图（keyboards/cannonkeys/crin/matrix_diagram.md）直接回答了三个关键问题：

1. 矩阵规模多大—— 从图上可数出 5 行、18 列，共 90 个矩阵交点；
2. 哪些物理位置没有独立键位—— 例如第二行的1D位置被 2u Backspace 占用而空缺；
3. 同一键位在不同配列下如何复用矩阵坐标—— 例如 ISO Enter 会占用2C、2D两个位置，而 ANSI 配列下2C是#键。

二、先看硬件：矩阵的"骨架"来自 matrix_pins

矩阵图的坐标不是随意编造的，它严格对应 keyboard.json 中的引脚定义：

"matrix_pins": { "cols": ["B0", "C15", "C14", "A7", "A5", "C13", "A4", "A2", "A1", "A0", "B9", "B8", "B7", "A3", "B6", "B4", "B3", "A15"], "rows": ["B11", "B10", "B2", "F0", "B5"] }, "diode_direction": "COL2ROW"

• cols数组有18 个元素，对应矩阵的 18 列（列号 0～17）；
• rows数组有5 个元素，对应矩阵的 5 行（行号 0～4）；
• diode_direction为COL2ROW，说明二极管方向为"列 → 行"，即扫描时逐行读列。

因此矩阵坐标的完整写法是[row, col]：行号 0～4，列号 0～17。在 matrix_diagram.md 中，坐标被压缩成两字符记号，例如0D表示第 0 行、第 13 列（D是十六进制 13），4E表示第 4 行、第 14 列。列号超过 9 后改用字母A~H继续编号，这是这套图纸记法的核心约定。

三、逐区解读 Crin 矩阵图

3.1 主键盘区（第一行：00 ~ 0E）

┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │00 │01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │0E │ └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘

第一行共 15 个格子，从00（Esc）到0E（` 键），其中：

• 00~0C依次是 Esc、数字 1~0、-、=；
• 0D被画成2u Backspace（图中上方标注 "2u Backspace"），占用第 13 列；
• 0E是 ` 键（ANSI 配列下 Backspace 右侧的波浪号键）。

3.2 2u Backspace 与空缺的 1D

第二行的关键在它的收尾处：

├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1E │ └─────┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴─────┘

注意：这一行从10直接跳到1E，没有1D。这是因为0D位置上的 2u Backspace 在物理上跨占了第一、二两行的纵向空间，导致第二行原本对应第 13 列的格子（1D）不存在实体按键。这是矩阵图中最重要的"负空间"信息——它告诉你 18 列矩阵并非每一列在每个物理位置都有键。

1E则是 1.5u 的\键（第 14 列）。

3.3 ISO Enter 与 2C / 2D 的复用

第三行同时展示了 ANSI 与 ISO 两种配列对矩阵坐标的不同占用：

├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤ │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2E │ └──────┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴────────┘

• 20（Caps Lock，1.75u）、21~2B（A~' 各字母键）；
• 图中右侧单独标注了"ISO Enter"示意区域：当使用 ISO 配列时，回车的 L 形大键会占据2C与2D两个矩阵位置；
• 2E是 ANSI 配列下的 1.25u 回车键。

对照 keyboard.json 的LAYOUT定义可以验证：#键位于[2, 12]（即2C），ANSI Enter 位于[2, 14]（即2E）；而 ISO 布局LAYOUT_tkl_nofrow_iso中 Enter 使用[2, 14]且带"w": 1.25, "h": 2的纵向尺寸。这意味着ISO Enter 与 ANSI 的#键在矩阵上共享列 12（2C）区域，二者物理互斥，图中用虚线框明确标出了这一点。

3.4 右侧功能区：独立的 0F / 1F / 3G / 4F 列

主区右侧是三颗一组的导航/编辑键列（图中以┌───┬───┬───┐独立框出）：

┌───┬───┬───┐ ┌───┬───┬───┐ │0F │0G │0H │ │1F │1G │1H │ └───┴───┴───┘ └───┴───┴───┘ ┌───┐ │3G │ （↑） ┌───┬───┬───┐ │4F │4G │4H │ （← ↓ →） └───┴───┴───┘

• 第一行右侧：0F（Insert）、0G（Home）、0H（Page Up）；
• 第二行右侧：1F（Delete）、1G（End）、1H（Page Down）；
• 第三行右侧只有3G（↑）；
• 第四行右侧：4F（←）、4G（↓）、4H（→）。

这些位置对应 keyboard.json 中[0, 15]~[4, 17]的坐标，即矩阵的最后三列（列 15、16、17）。功能区没有使用2F、2H等位置，因为第三行的功能键（如 PgUp/PgDn 常规位置）被整合进了主区，图上留白即为"无键"。

3.5 底排与 Tsangan / WKL 两种形态

图的最下方画出了两种底排形态，这是理解"同一块 PCB 支持多配列"的关键：

┌────────┐ ┌──────────┐ │30 │ 2.25u LShift 2.75u RShift │3D │ └────────┘ └──────────┘

标准 ANSI 底排（左）：

├────┼───┴┬──┴─┬─┴───┴───┴───┴───┴───┴──┬┴───┼───┴┬────┬┴───┤ │40 │41 │42 │45 │4A │4B │4C │4E │ └────┴────┴────┴────────────────────────┴────┴────┴────┴────┘

即：40（Ctrl 1.25u）、41（GUI 1.25u）、42（Alt 1.25u）、45（Space 6.25u）、4A（Alt）、4B（Fn）、4C（GUI）、4E（Ctrl）。

Tsangan/WKL 底排（右）：

┌─────┬───┬─────┬───────────────────────────┬─────┬───┬─────┐ │40 │41 │42 │45 │4B │4C │4E │ └─────┴───┴─────┴───────────────────────────┴─────┴───┴─────┘

即 1.5u Ctrl / 1u Win / 1.5u Alt / 7u Space / 1.5u Alt / 1u Menu / 1.5u Ctrl——这正是 keyboard.json 中LAYOUT_tkl_nofrow_ansi_tsangan等 Tsangan 布局的物理形态。两种形态复用相同的矩阵坐标（如 Space 都是45=[4, 5]），只是键帽宽度与相邻键的 x 偏移不同。

同样，30（左 Shift）与3D（右 Shift 的延伸部分）在图上方标注了2.25u LShift与2.75u RShift的键宽信息：2.25u 的左 Shift 覆盖30~31两个格子，2.75u 的右 Shift 覆盖3C~3D，所以标准 ANSI 行中31位置没有独立按键，而 ISO 配列则把31用作了\键（对照 keyboard.json 中 ISO 布局[3, 1]的|键）。

四、从矩阵图到 LAYOUT 定义：坐标对照表

matrix_diagram.md 与 keyboard.json 中的LAYOUT是同一张图的两面：图纸负责"人可读"，JSON 负责"机可读"。下面是主区第一、二行的完整对照（LAYOUT定义见 keyboard.json 第 49~132 行）：

同样的对应关系贯穿全部 5 行：2E=[2, 14]、3E=[3, 14]（Fn）、45=[4, 5]（Space）……读者可以把图纸当作"坐标字典"，在写键位时快速查出某个物理键对应哪个[row, col]。

五、图纸如何落地：LAYOUT_all 宏与默认 keymap

矩阵图最终服务于键位编写。Crin 的默认键位 keymaps/default/keymap.c 使用LAYOUT_all宏（layout_aliases中LAYOUT_all指向LAYOUT），逐键填充矩阵坐标：

[_BASE] = LAYOUT_all( KC_ESC, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, KC_GRV, KC_INS, KC_HOME, KC_PGUP, KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_DEL, KC_END, KC_PGDN, ...

注意每行键码的数量与顺序与矩阵图中该行的格子完全一致：

• 第 0 行 18 个键码（00~0E + 0F/0G/0H）；
• 第 1 行 17 个键码（10~1C + 1E + 1F/1G/1H，跳过 1D）；
• 第 4 行 11 个键码（40、41、42、45、4A、4B、4C、4E、4F、4G、4H）。

这正是"读图 → 定位坐标 → 填键码"的实操示范：一旦你在矩阵图上标出某个物理键的坐标，就能在LAYOUT_all(...)的参数列表里按行号顺序找到它的位置并替换成任意键码。另外，默认键位把QK_BOOT放在_FN1层的第一个键位（00），这与 readme.md 中第三种进入刷机模式的方法（"Keycode in layout: Press the key mapped toQK_BOOT"）直接对应。

六、矩阵图之外的配套信息

要把 Crin 跑起来，还需要关注同一目录下的其他文件：

• readme.md：构建命令make cannonkeys/crin:default，以及三种进入 Bootloader 的方式（Bootmagic 复位、背板拨码开关 + 复位键、QK_BOOT键码）；
• keyboard.json：USB VID/PID（0xCA04/0x0012）、处理器STM32F072、Bootloaderstm32-dfu、背光（A6引脚、6 级亮度、支持呼吸）、Caps Lock 指示灯（F1，低电平点亮）、NKRO、Bootmagic 等特性开关；
• config.h：背光 PWM 驱动配置（BACKLIGHT_PWM_DRIVER PWMD3、通道 1、PAL 模式 1）；
• rules.mk：DFU_SUFFIX_ARGS = -v FFFF -p FFFF，用于兼容 APM32 等替代主控的 DFU 校验。

七、小结：把矩阵图变成你的开发工具

一张 matrix_diagram.md 的价值在于它是矩阵坐标、物理键位、键帽尺寸、配列差异四类信息的唯一交汇点。对 Crin 而言，从图中你可以直接得出：

1. 矩阵为5 行 × 18 列，与matrix_pins的 5 个 row 引脚、18 个 col 引脚一一对应；
2. 2u Backspace（0D）造成第二行1D空缺，写 keymap 时该行少填一个键码；
3. ISO Enter会复用2C/2D两个位置，ANSI 下2C是#；
4. 右侧功能区使用独立的列 15~17（0F~4H），且2F、2H无键；
5. 底排支持标准 ANSI 与 Tsangan/WKL 两种形态，坐标相同、键宽不同。

掌握了这套读图方法，无论面对仓库里哪一块键盘的matrix_diagram.md，你都能在几秒钟内还原出它的矩阵结构，并直接对照keyboard.json的LAYOUT与keymap.c开始编写属于自己的键位方案。

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