企业官网建设流程全解析

QMK 矩阵图（Matrix Diagram）深度解析：以 concreteflowers cor（saevus cor）为例

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

本文以 QMK 固件仓库中concreteflowers厂商旗下cor（saevus cor）键盘的矩阵图文档为主线，系统讲解如何阅读 QMK 键盘的 ASCII 矩阵图、如何将矩阵坐标与keyboard.json中的 layout 定义、以及 keymap 源码一一对应。读完本文，你将掌握通过矩阵图反推 PCB 矩阵行列分配、理解 2u Backspace / Blocker / Tsangan 等布局变体在矩阵中的落点，并能在自行移植或调试键盘固件时快速定位按键的矩阵位置。

一、什么是 QMK 矩阵图（Matrix Diagram）

在 QMK 中，物理按键并不是直接连接到单个 MCU 引脚，而是以矩阵（Matrix）的形式组织：若干行（Row）与若干列（Col）的交叉点各接一个按键，固件通过"行列扫描"检测按键通断。为了帮助维护者与开发者直观理解每颗按键的物理扫描位置，许多键盘目录下会附带一张纯 ASCII 绘制的矩阵图。

concreteflowers/cor的矩阵图位于 keyboards/concreteflowers/cor/matrix_diagram.md，图中每个单元格内的编号（如0E、3F）就是该按键的矩阵坐标：

• 第一位数字（0～4）表示行（Row）；
• 第二位字符（十六进制 0～F，即 0～15）表示列（Col），本图还额外出现了0G等使用G的列标识，表示第 16 列。

与 keyboard.json 的对照

cor 的矩阵规模可以在 keyboards/concreteflowers/cor/keyboard.json 中得到印证：

"matrix_pins": { "rows": ["F0", "F1", "F4", "B3", "B6"], "cols": ["F5", "F6", "F7", "C6", "C7", "B1", "B7", "B5", "B4", "D7", "D6", "D4", "D5", "D3", "D2", "D1", "D0"] }

• 5 行：F0、F1、F4、B3、B6，对应矩阵坐标行号 0～4；
• 17 列：从F5到D0共 17 个引脚，对应矩阵坐标列号 0～16（十六进制0～F共 16 列，再加第 16 列即图中的G）。

这正好解释了矩阵图右边缘出现的0G、1G、2G、3G列：它们是第 16 列（Col 16），用于放置 Delete、Page Up、Page Down、Fn 等导航/功能键。也就是说，这张图把 5×17 的矩阵完整画了出来。

二、逐行拆解矩阵图：从物理按键到矩阵坐标

矩阵图顶部标注了"2u Backspace"，右上角单独绘制了0E，而整个键盘主体共 5 行。下面结合 keyboards/concreteflowers/cor/keymaps/default/keymap.c 中的LAYOUT_ansi_blocker_split_bs调用逐行解读。

第 0 行（行坐标 0）：功能键行与 Backspace 变体

┌───────┐ 2u Backspace │0E │ └───────┘ ┌───┐┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ┌───┐ │00 ││01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │0E │0F │ │0G │

• 00：左上角按键，在默认 keymap 中是KC_F1（同时也充当 Bootmagic 复位键的默认位置，见下文）；
• 01～0D：依次为KC_ESC、KC_1…KC_0、KC_MINS、KC_EQL；
• 0E：右上角单独绘制的2u Backspace（KC_BSPC），注意0F在图中被压在该 2u 键位之下，属于"物理上被大键位覆盖"的位置；
• 0G（第 16 列）：KC_DEL。

这正好对应 keymap 第 0 行的 17 个参数：

KC_F1, KC_ESC, KC_1, ..., KC_MINS, KC_EQL, KC_BSPC, KC_BSPC, KC_DEL,

其中出现了两个KC_BSPC：这正是LAYOUT_ansi_blocker_split_bs（split Backspace，即"拆分退格"）布局的特征——把原本一体的 2u Backspace 拆成0E与0F两颗独立的 1u 按键。对照 keyboards/concreteflowers/cor/keyboard.json 中的LAYOUT_ansi_blocker_split_bs：

{"label": "Backspace", "matrix": [0, 14], ...}, {"label": "Backspace", "matrix": [0, 15], ...}

而LAYOUT_ansi_blocker与LAYOUT_ansi_blocker_tsangan则只写一个matrix: [0, 14]且带"w": 2，即 2u Backspace——这与矩阵图顶部的 "2u Backspace" 标注完全一致。

第 1～3 行：字母区与修饰键

├───┤├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ ├───┤ │10 ││11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1F │ │1G │

• 行 1：10=F2，11=Tab（1.5u），12~1D=Q W E R T Y U I O P [ ]，1F=反斜杠\（1.5u），1G=Page Up；
• 行 2：20=F3，21=Caps Lock（1.75u），22~2C=A S D F G H J K L ; '，2E=Enter（2.25u），2G=Page Down；
• 行 3：30=F4，31=左 Shift（2.25u），33~3C=Z X C V B N M , . /，3D=右 Shift（1.75u），3F=↑，3G=Fn。

注意图中行 3 的32被左 Shift 的大键位覆盖、3E被右 Shift 覆盖，而右侧3F（↑）与3G（Fn）被画成两列堆叠的形态。默认 keymap 中对应：

KC_F4, KC_LSFT, KC_Z, ..., KC_RSFT, KC_UP, MO(1),

其中MO(1)即矩阵坐标[3, 16]的3G位置。

第 4 行：Blocker 区域与 Tsangan 布局

├───┤├────┬───┴┬──┴─┬─┴───┴───┴───┴───┴───┴──┬┴───┼───┴┬─────┘│3F │└───┘ │40 ││41 │42 │43 │47 │4B │4C │ ┌───┼───┼───┐ └───┘└────┴────┴────┴────────────────────────┴────┴────┘ │4E │4F │4G │ └───┴───┴───┘ ┌─────┬───┬─────┬───────────────────────────┬─────┐ │41 │42 │43 │47 │4C │ Blocker Tsangan └─────┴───┴─────┴───────────────────────────┴─────┘

第 4 行是 cor 作为"exploded 65% with a macro column"（带宏列的爆炸式 65%）最具特色的部分：

• 40=F5（最左的宏列键）；
• 41=Ctrl（1.25u）、42=GUI、43=Alt，对应KC_LCTL、KC_LGUI、KC_LALT；
• 47=Space（6.25u，跨越 4D～4A 的物理宽度）；
• 4B=右 Alt、4C=右 Ctrl；
• 4E=←、4F=↓、4G=→ 三颗方向键。

图下方还用一行 ASCII 单独标注了"Blocker Tsangan"布局的底行变体：41(1.5u Ctrl)、42(GUI)、43(1.5u Alt)、47(7u Space)、4C(1.5u Ctrl)。这种底行在 keyboard.json 中对应LAYOUT_ansi_blocker_tsangan与LAYOUT_ansi_blocker_tsangan_split_bs：

{"label": "Ctrl", "matrix": [4, 1], "x": 1.25, "y": 4, "w": 1.5}, {"label": "GUI", "matrix": [4, 2], "x": 2.75, "y": 4}, {"label": "Alt", "matrix": [4, 3], "x": 3.75, "y": 4, "w": 1.5}, {"label": "Space","matrix": [4, 7], "x": 5.25, "y": 4, "w": 7}, {"label": "Ctrl", "matrix": [4, 12], "x": 12.25, "y": 4, "w": 1.5}

矩阵坐标的公共部分说明：无论 layout 如何变化，41/42/43/47/4C这些按键始终复用同一矩阵坐标，变化的只是它们在 layout 中的宽度w与 X 轴位置x——这正是 QMK 中"矩阵固定、layout 可变"的典型体现。

三、矩阵图、layouts 与 keymap 的三方对应关系

cor 在 keyboards/concreteflowers/cor/keyboard.json 中定义了 4 种 layout：

其中layout_aliases把LAYOUT_all映射到LAYOUT_ansi_blocker_split_bs，因此默认 keymap 才能直接以LAYOUT_ansi_blocker_split_bs(...)编写（见 keymaps/default/keymap.c）。

将这三种信息对照阅读，就能验证矩阵图每一个格子的含义：

1. 矩阵图给出物理扫描坐标（如0E、4G）；
2. keyboard.json的layouts给出每个坐标对应的键帽标签、宽度与位置（如"matrix": [0, 14], "w": 2）；
3. keymap.c给出每个坐标实际绑定的键码（如KC_BSPC、MO(1)）。

四、利用矩阵图进行固件调试与开发

1. 验证矩阵扫描方向（COL2ROW）

cor 在 keyboard.json 中声明了"diode_direction": "COL2ROW"，即行接扫描输出、列接扫描输入。配合 5 行 17 列的matrix_pins，你可以直接对照矩阵图检查：行引脚F0/F1/F4/B3/B6与列引脚F5…D0的交叉点是否与图中格子一一对应。若某个按键在图中存在、但matrix_pins中找不到对应引脚，说明接线或配置不一致。

2. 理解宏列与"爆炸式"布局

readme 将 cor 描述为 "An exploded 65% with a macro column"（keyboards/concreteflowers/cor/readme.md）。从矩阵图可以直观看到：

• 最左侧00/10/20/30/40一列是独立的 F 键宏列（F1～F5）；
• 第 16 列（G列）承载 Delete / Page Up / Page Down / Fn 等右缘功能键；
• 底行47（Space）与其左侧 3 键、右侧 2 键之间存在空隙，即 "blocker"（阻隔块）风格。

3. 定位 Bootmagic 复位键

根据 keyboards/concreteflowers/cor/readme.md 的说明，Bootmagic 复位方式为"按住左上角键并插入 USB"。结合矩阵图，左上角即00位置（矩阵坐标[0, 0]），对应默认 keymap 的KC_F1键位。这在移植或复刻该 PCB 时非常有用：只要矩阵图中00的位置不变，Bootmagic 的默认行为就不受影响。

4. 为新变体编写 keymap 的参考依据

若你要为 cor 添加新的布局变体（例如 ISO 回车、7u 空格等），矩阵图是判断"哪些矩阵坐标尚未被占用"的最佳工具。例如图中0F、32、3E等位置被大键位覆盖但坐标仍保留在 layout 中（拆分 Backspace 时0F就会被启用为第二颗 Backspace），新增变体时可以复用它而不必修改矩阵引脚定义。

五、同类键盘的矩阵规模参照

同厂商的 cor TKL（keyboards/concreteflowers/cor_tkl/readme.md）采用了相同的矩阵设计思路：同样是 5 行 17 列、COL2ROW，只是处理器换为 RP2040、引脚改为GP0…GP29（见 keyboards/concreteflowers/cor_tkl/keyboard.json）。这说明 5×17 的"带宏列"矩阵是 concreteflowers 家族（cor / cor TKL）共用的硬件基础，矩阵图所展示的坐标体系可以平滑迁移到同一厂商的其他型号上。

六、小结

matrix_diagram.md虽然只是一张 ASCII 图，但它浓缩了 cor 键盘的完整矩阵拓扑：

• 5 行 17 列，与keyboard.json的matrix_pins完全吻合；
• 左上角00同时是 Bootmagic 复位键；
• 0E支持 2u Backspace，0E+0F支持拆分 Backspace；
• 底行41/42/43/47/4B/4C支持标准与 Tsangan 两种 Blocker 风格，且两种风格共享矩阵坐标；
• 第 16 列（G列）承载右缘 Delete / 翻页 / Fn / 方向键。

阅读 QMK 键盘源码时，将矩阵图、keyboard.json的layouts与keymaps/*/keymap.c三者对照，是理解任意键盘固件结构最有效的方法。本文涉及的 cor 键盘可通过以下命令编译与刷写固件（需先完成 QMK 构建环境配置）：

# 编译默认 keymap make concreteflowers/cor:default # 编译并刷写（进入 bootloader 后执行） make concreteflowers/cor:default:flash

刷写前可通过 Bootmagic（按住00左上角键插入 USB）或 PCB 背面的物理复位按钮进入 bootloader。

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