企业官网建设流程全解析

QMK 矩阵图全解析：CannonKeys Reverie Solderable 的 5×15 矩阵寻址与布局变体

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

本文以 QMK 固件仓库中 CannonKeys Reverie 可焊接版（solderable）的矩阵示意图（matrix_diagram.md）为骨架，结合该键盘的info.json、keyboard.json与默认 keymap 源码，逐格讲解"矩阵坐标 → 物理键位 → 布局宏"的对应关系。读完本文，你将掌握如何阅读 QMK 键盘仓库中的 ASCII 矩阵图、如何将图中行+列十六进制编号映射到引脚与LAYOUT宏参数，以及 Reverie 支持的全部 8 种 65% 布局变体（ANSI/ISO × 分裂退格 × Blocker/Tsangan）是如何在矩阵层面对齐的。

文档定位：这张矩阵图要解决什么问题

QMK 中每个键盘目录下的matrix_diagram.md是一份纯文本的"物理接线索引图"，它回答一个核心问题：PCB 上每一颗物理按键，在固件的行×列矩阵中到底占据哪个坐标。对于像 Reverie 这样同时支持多种配列（ANSI/ISO、标准退格/分裂退格、Blocker/Tsangan 底部行）的可焊接 PCB，同一矩阵位置在不同配列下可能承担不同角色，这张图就是固件开发者与配列维护者的共同参照。

Reverie 系列 PCB 位于 keyboards/cannonkeys/reverie，包含 solderable（可焊接）与 hotswap（热插拔）两个子目录，本文聚焦 solderable 版。

原始矩阵图全文

下面完整保留该文档的核心内容（原图逐字引用）：

┌───────┐ 2u Backspace │0D │ └───────┘ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │00 │01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │2C │0E │ ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┼───┤ ┌─────┐ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1E │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┼───┤ ┌──┴┐2D │ ISO Enter │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2D │2E │ │1D │ │ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┼───┤ └───┴────┘ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3C │3D │3E │ ├────┴┬──┴┬──┴──┬┴───┴───┴──┬┴──┬┴───┴───┴──┬┴───┴┬─┬───┼───┼───┤ │40 │41 │42 │45 │46 │49 │4B │ │4C │4D │4E │ └─────┴───┴─────┴───────────┴───┴───────────┴─────┘ └───┴───┴───┘ ┌────────┐ │30 │ 2.25u LShift └────────┘ ┌─────┬───┬─────┬───────────────────────────┬─────┐ │40 │41 │42 │46 │4B │ Blocker Tsangan └─────┴───┴─────┴───────────────────────────┴─────┘ ┌────┬────┬────┬────────────────────────┬────┬────┐ │40 │41 │42 │46 │4A │4B │ Blocker └────┴────┴────┴────────────────────────┴────┴────┘

如何解读坐标：行号 + 十六进制列号

Reverie 的矩阵图采用 QMK 社区惯例的"行号（十进制）+ 列号（十六进制）"双字符编号：

• 首个数字 = 行号：0～4，共 5 行；
• 第二个字符 = 列号：0～E（十六进制），即 0～14，共 15 列。

因此00表示第 0 行第 0 列，0E表示第 0 行第 14 列，4E表示第 4 行第 14 列。全矩阵共 5 × 15 = 75 个矩阵位置，但并非所有位置都会在每一种配列中同时出现（见下文"共享矩阵位置的配列切换"）。

图中标注的特殊键位

原图用旁注文字标出了三处关键物理特征，它们是理解整张图的门槛：

此外，第 0 行中混入的2C（即坐标 [2,12]，第 2 行第 12 列）是**分裂退格（Split Backspace）**的右半部分——当不启用分裂退格时，0D以 2u 宽度占据 x=13～15 的位置，2C在物理上不存在或空闲；启用分裂退格时，0D收缩为 1u、2C独立成键。这与 keyboard.json 中LAYOUT_65_ansi_blocker_split_bs将[2, 12]放在x: 14（倒数第二个键位）的定义完全吻合。

从矩阵图到真实硬件：info.json 中的引脚分配

矩阵图上的坐标编号并非随意约定，而是直接对应 info.json 中的matrix_pins定义。Reverie solderable 使用 RP2040 主控，5 行 15 列的引脚分配如下：

同时info.json声明"diode_direction": "COL2ROW"，即二极管方向为"列→行"：扫描时列驱动、行读取。这与矩阵图的阅读方向一致——固件以"行优先"遍历（keymaps[][MATRIX_ROWS][MATRIX_COLS]），每个键的矩阵坐标就是[行][列]。

硬件接线提示：如果要自行飞线/检修 Reverie solderable 的某颗按键，先在矩阵图中定位其坐标，再查上表得到行列 GPIO，即可用万用表或 QMK 的矩阵调试功能定位故障。

从矩阵图到布局宏：keyboard.json 的 layouts 定义

QMK 采用数据驱动配置（data-driven configuration）：keyboard.json 的layouts字段逐键给出matrix: [行, 列]与物理坐标x / y / w / h（单位 u），构建系统据此自动生成LAYOUT_*宏。

以全键位布局LAYOUT_all为例，其定义与矩阵图逐格对应：

• 第 0 行：[0,0]～[0,14]，其中[0,13]（即0D）在非分裂退格配列中带"w": 2；
• ISO 回车：[1,13]（1D）为 x=12.75 的单键，[2,13]（2D）声明为"x": 13.75, "y": 1, "w": 1.25, "h": 2——高度 2u、从 y=1 纵向贯穿到 y=2，正是图中1D+2D拼出的 ISO Enter 形状；
• 第 3 行：[3,0]带"w": 2.25，即图中标注的 2.25u LShift；
• 第 4 行：[4,0]、[4,1]、[4,2]各 1.25u（40/41/42），空格区由[4,5]（2.25u）+[4,6]（1.25u）+[4,9]（2.75u）拼合，[4,10]、[4,11]各 1.25u，最后[4,12]～[4,14]为方向键。

值得注意：LAYOUT_all的第 4 行并非图中"Blocker"或"Tsangan"任何一种成品配列，而是两种底部行变体的超集——40/41/42、4A、4B等位置在具体配列中由各自的LAYOUT_*决定是否启用及宽度（1.25u 或 1.5u）。这正是layout_aliases中"LAYOUT": "LAYOUT_all"存在的原因：默认 keymap 直接使用超集布局，换取对不同配列的通用性。

底部行变体：Blocker 与 Tsangan

矩阵图末尾的两行 ASCII 图分别描绘了该 PCB 支持的两种 65% 底部行形态：

• Blocker Tsangan：40（1.5u）41（1u）42（1.5u）46（7u 空格）4B（1.5u），即 1.5-1-1.5 + 7u 空格 + 1.5u 的 Tsangan/WKL 风格底部行；
• Blocker：40（1.25u）41（1.25u）42（1.25u）46（6.25u 空格）4A（1.25u）4B（1.25u），即标准 65% 带阻隔（blocker）的 6.25u 空格配列。

这两行示意图与keyboard.json中LAYOUT_65_ansi_blocker_tsangan（[4,0]1.5u、[4,1]1u、[4,2]1.5u、[4,6]7u、[4,11]1.5u）和LAYOUT_65_ansi_blocker（[4,0]/[4,1]/[4,2]各 1.25u、[4,6]6.25u、[4,10]/[4,11]各 1.25u）的定义逐一对应。

8 种 Community Layouts：矩阵不变，配列切换

solderable 版在community_layouts中声明了 8 种可被社区共享布局（layouts/目录）复用的配列，全部围绕矩阵图上的同一套坐标展开：

观察keyboard.json各布局定义可以发现一个规律：变体之间只有三处矩阵位置发生角色切换——0D（2u 退格 ↔ 1u + 启用2C）、1D/2D（普通键 ↔ ISO 回车）、第 4 行（1.25u ↔ 1.5u 组合）。其余 60 余个矩阵坐标在所有配列中保持不变。这意味着焊好同一块 solderable PCB，用户可以通过更换键帽与刷写不同LAYOUT_*的固件，在 8 种配列间切换，而矩阵接线无需改动。

作为对照，hotswap 版（keyboards/cannonkeys/reverie/hotswap/keyboard.json）的community_layouts仅含 4 个 ANSI 变体、layout_aliases指向LAYOUT_65_ansi_blocker_split_bs，与 readme.md 中"hotswap 版本不支持 ISO、布局支持较少"的描述一致——这也是 solderable 版矩阵图需要画出 ISO Enter 的原因。

实战：用矩阵图校验与编写 keymap

Reverie solderable 的默认键位位于 keymaps/default/keymap.c，其_BASE层使用LAYOUT_all宏：

[_BASE] = LAYOUT_all( QK_GESC, KC_1, KC_2, ..., KC_BSPC, KC_DEL, KC_HOME, // 第 0 行：00～0D、2C 后的 0E KC_TAB, KC_Q, KC_W, ..., KC_BSLS, KC_END, // 第 1 行：10～1E KC_CAPS, KC_A, KC_S, ..., KC_ENT, KC_PGUP, // 第 2 行：20～2E KC_LSFT, KC_BSLS, KC_Z, ..., KC_RSFT, KC_UP, KC_PGDN, // 第 3 行：30～3E KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_SPC, KC_SPC, KC_RALT, MO(_FN1), KC_LEFT, KC_DOWN, KC_RIGHT // 第 4 行 )

编写自定义 keymap 时的核对步骤：

1. 在矩阵图中找到目标物理按键的坐标（如右上角 Delete 是0E）；
2. 确认该坐标在所选LAYOUT_*中的语义（宽度、是否为共享位置，如0D/2C、1D/2D）；
3. 对照keyboard.json中该布局的键序填写 keycode，保证LAYOUT_*参数数量与定义一致。

此外，矩阵图还能辅助定位与排障：

• Bootmagic：仓库 readme.md 说明"按住矩阵 (0,0) 位置的键（通常是左上角 Esc 或 QK_GESC）再插电"即可进入刷写模式，info.json中features.bootmagic为true；
• 编译/刷写：

  make cannonkeys/reverie/solderable:default # 编译 make cannonkeys/reverie/solderable:default:flash # 编译并刷写

• 方向键与 Fn 层：_FN1层把40映射为KC_GRV、0E映射为QK_BOOT，并集中放置了背光控制键（BL_BRTG/BL_UP/BL_DOWN/BL_TOGG），对应 solderable 版 keyboard.json 中启用的背光特性（GP22、呼吸周期 5、15 级亮度）与 config.h 中的 PWM 通道配置。

小结

Reverie solderable 的矩阵图用一张 ASCII 图浓缩了整块 5×15 键盘的物理接线事实：坐标行号+十六进制列号直连info.json的引脚表，特殊位置（0D退格、1D/2DISO 回车、30左 Shift、第 4 行底部行）分别对应keyboard.json中 8 种配列的定义，而LAYOUT_all则是全部变体的超集。当你需要为该键盘新增配列、排查按键或核对固件键序时，这张图与keyboard.json是彼此印证的第一手资料。

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