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

QMK 键盘矩阵图完全解读以 CannonKeys Crinmatrix_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直接回答了三个关键问题矩阵规模多大—— 从图上可数出 5 行、18 列共 90 个矩阵交点哪些物理位置没有独立键位—— 例如第二行的1D位置被 2u Backspace 占用而空缺同一键位在不同配列下如何复用矩阵坐标—— 例如 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: COL2ROWcols数组有18 个元素对应矩阵的 18 列列号 017rows数组有5 个元素对应矩阵的 5 行行号 04diode_direction为COL2ROW说明二极管方向为列 → 行即扫描时逐行读列。因此矩阵坐标的完整写法是[row, col]行号 04列号 017。在 matrix_diagram.md 中坐标被压缩成两字符记号例如0D表示第 0 行、第 13 列D是十六进制 134E表示第 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 个格子从00Esc到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 │ └──────┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴────────┘20Caps Lock1.75u、21~2BA~ 各字母键图中右侧单独标注了ISO Enter示意区域当使用 ISO 配列时回车的 L 形大键会占据2C与2D两个矩阵位置2E是 ANSI 配列下的 1.25u 回车键。对照 keyboard.json 的LAYOUT定义可以验证#键位于[2, 12]即2CANSI Enter 位于[2, 14]即2E而 ISO 布局LAYOUT_tkl_nofrow_iso中 Enter 使用[2, 14]且带w: 1.25, h: 2的纵向尺寸。这意味着ISO Enter 与 ANSI 的#键在矩阵上共享列 122C区域二者物理互斥图中用虚线框明确标出了这一点。3.4 右侧功能区独立的 0F / 1F / 3G / 4F 列主区右侧是三颗一组的导航/编辑键列图中以┌───┬───┬───┐独立框出┌───┬───┬───┐ ┌───┬───┬───┐ │0F │0G │0H │ │1F │1G │1H │ └───┴───┴───┘ └───┴───┴───┘ ┌───┐ │3G │ ↑ ┌───┬───┬───┐ │4F │4G │4H │ ← ↓ → └───┴───┴───┘第一行右侧0FInsert、0GHome、0HPage Up第二行右侧1FDelete、1GEnd、1HPage 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 │ └────┴────┴────┴────────────────────────┴────┴────┴────┴────┘即40Ctrl 1.25u、41GUI 1.25u、42Alt 1.25u、45Space 6.25u、4AAlt、4BFn、4CGUI、4ECtrl。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 行图纸坐标JSON matrix 字段键位备注00[0, 0]Esc也是 Bootmagic 复位键位见 readme01~09[0, 1]~[0, 9]1 ~ 90A~0C[0, 10]~[0, 12]0、-、0D[0, 13]Backspace2u占用 1D 纵向空间0E[0, 14]0F / 0G / 0H[0, 15] / [0, 16] / [0, 17]Insert / Home / PgUp10[1, 0]Tab1.5u11~1C[1, 1]~[1, 12]Q ~ ]无 1D1E[1, 14]\1.5u1F / 1G / 1H[1, 15] / [1, 16] / [1, 17]Del / End / PgDn同样的对应关系贯穿全部 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.jsonUSB VID/PID0xCA04/0x0012、处理器STM32F072、Bootloaderstm32-dfu、背光A6引脚、6 级亮度、支持呼吸、Caps Lock 指示灯F1低电平点亮、NKRO、Bootmagic 等特性开关config.h背光 PWM 驱动配置BACKLIGHT_PWM_DRIVER PWMD3、通道 1、PAL 模式 1rules.mkDFU_SUFFIX_ARGS -v FFFF -p FFFF用于兼容 APM32 等替代主控的 DFU 校验。七、小结把矩阵图变成你的开发工具一张 matrix_diagram.md 的价值在于它是矩阵坐标、物理键位、键帽尺寸、配列差异四类信息的唯一交汇点。对 Crin 而言从图中你可以直接得出矩阵为5 行 × 18 列与matrix_pins的 5 个 row 引脚、18 个 col 引脚一一对应2u Backspace0D造成第二行1D空缺写 keymap 时该行少填一个键码ISO Enter会复用2C/2D两个位置ANSI 下2C是#右侧功能区使用独立的列 15~170F~4H且2F、2H无键底排支持标准 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考