QMK 矩阵图Matrix Diagram深度解析以 concreteflowers corsaevus cor为例【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK 固件仓库中concreteflowers厂商旗下corsaevus 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就是该按键的矩阵坐标第一位数字04表示行Row第二位字符十六进制 0F即 015表示列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对应矩阵坐标行号 0417 列从F5到D0共 17 个引脚对应矩阵坐标列号 016十六进制0F共 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 复位键的默认位置见下文010D依次为KC_ESC、KC_1…KC_0、KC_MINS、KC_EQL0E右上角单独绘制的2u BackspaceKC_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_bssplit 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 标注完全一致。第 13 行字母区与修饰键├───┤├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ ├───┤ │10 ││11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1F │ │1G │行 110F211Tab1.5u12~1DQ W E R T Y U I O P [ ]1F反斜杠\1.5u1GPage Up行 220F321Caps Lock1.75u22~2CA S D F G H J K L ; 2EEnter2.25u2GPage Down行 330F431左 Shift2.25u33~3CZ X C V B N M , . /3D右 Shift1.75u3F↑3GFn。注意图中行 3 的32被左 Shift 的大键位覆盖、3E被右 Shift 覆盖而右侧3F↑与3GFn被画成两列堆叠的形态。默认 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%最具特色的部分40F5最左的宏列键41Ctrl1.25u、42GUI、43Alt对应KC_LCTL、KC_LGUI、KC_LALT47Space6.25u跨越 4D4A 的物理宽度4B右 Alt、4C右 Ctrl4E←、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 种 layoutLayout 名称Backspace底行风格layout_aliasesLAYOUT_ansi_blocker2u标准 1.25u 六键—LAYOUT_ansi_blocker_split_bs拆分两颗 1u标准 1.25u 六键LAYOUT_all指向它LAYOUT_ansi_blocker_tsangan2uTsangan1.5u 键位—LAYOUT_ansi_blocker_tsangan_split_bs拆分Tsangan—其中layout_aliases把LAYOUT_all映射到LAYOUT_ansi_blocker_split_bs因此默认 keymap 才能直接以LAYOUT_ansi_blocker_split_bs(...)编写见 keymaps/default/keymap.c。将这三种信息对照阅读就能验证矩阵图每一个格子的含义矩阵图给出物理扫描坐标如0E、4Gkeyboard.json的layouts给出每个坐标对应的键帽标签、宽度与位置如matrix: [0, 14], w: 2keymap.c给出每个坐标实际绑定的键码如KC_BSPC、MO(1)。四、利用矩阵图进行固件调试与开发1. 验证矩阵扫描方向COL2ROWcor 在 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 columnkeyboards/concreteflowers/cor/readme.md。从矩阵图可以直观看到最左侧00/10/20/30/40一列是独立的 F 键宏列F1F5第 16 列G列承载 Delete / Page Up / Page Down / Fn 等右缘功能键底行47Space与其左侧 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 TKLkeyboards/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 Backspace0E0F支持拆分 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
QMK 矩阵图（Matrix Diagram）深度解析：以 concreteflowers cor（saevus cor）为例
QMK 矩阵图Matrix Diagram深度解析以 concreteflowers corsaevus cor为例【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK 固件仓库中concreteflowers厂商旗下corsaevus 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就是该按键的矩阵坐标第一位数字04表示行Row第二位字符十六进制 0F即 015表示列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对应矩阵坐标行号 0417 列从F5到D0共 17 个引脚对应矩阵坐标列号 016十六进制0F共 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 复位键的默认位置见下文010D依次为KC_ESC、KC_1…KC_0、KC_MINS、KC_EQL0E右上角单独绘制的2u BackspaceKC_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_bssplit 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 标注完全一致。第 13 行字母区与修饰键├───┤├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ ├───┤ │10 ││11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1F │ │1G │行 110F211Tab1.5u12~1DQ W E R T Y U I O P [ ]1F反斜杠\1.5u1GPage Up行 220F321Caps Lock1.75u22~2CA S D F G H J K L ; 2EEnter2.25u2GPage Down行 330F431左 Shift2.25u33~3CZ X C V B N M , . /3D右 Shift1.75u3F↑3GFn。注意图中行 3 的32被左 Shift 的大键位覆盖、3E被右 Shift 覆盖而右侧3F↑与3GFn被画成两列堆叠的形态。默认 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%最具特色的部分40F5最左的宏列键41Ctrl1.25u、42GUI、43Alt对应KC_LCTL、KC_LGUI、KC_LALT47Space6.25u跨越 4D4A 的物理宽度4B右 Alt、4C右 Ctrl4E←、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 种 layoutLayout 名称Backspace底行风格layout_aliasesLAYOUT_ansi_blocker2u标准 1.25u 六键—LAYOUT_ansi_blocker_split_bs拆分两颗 1u标准 1.25u 六键LAYOUT_all指向它LAYOUT_ansi_blocker_tsangan2uTsangan1.5u 键位—LAYOUT_ansi_blocker_tsangan_split_bs拆分Tsangan—其中layout_aliases把LAYOUT_all映射到LAYOUT_ansi_blocker_split_bs因此默认 keymap 才能直接以LAYOUT_ansi_blocker_split_bs(...)编写见 keymaps/default/keymap.c。将这三种信息对照阅读就能验证矩阵图每一个格子的含义矩阵图给出物理扫描坐标如0E、4Gkeyboard.json的layouts给出每个坐标对应的键帽标签、宽度与位置如matrix: [0, 14], w: 2keymap.c给出每个坐标实际绑定的键码如KC_BSPC、MO(1)。四、利用矩阵图进行固件调试与开发1. 验证矩阵扫描方向COL2ROWcor 在 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 columnkeyboards/concreteflowers/cor/readme.md。从矩阵图可以直观看到最左侧00/10/20/30/40一列是独立的 F 键宏列F1F5第 16 列G列承载 Delete / Page Up / Page Down / Fn 等右缘功能键底行47Space与其左侧 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 TKLkeyboards/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 Backspace0E0F支持拆分 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
