QMK 矩阵图解读实战：AEBoards Constellation Rev3 的硬件矩阵与键位映射全解析

QMK 矩阵图解读实战：AEBoards Constellation Rev3 的硬件矩阵与键位映射全解析

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

导读

本篇以 QMK 固件仓库中 AEBoards Constellation Rev3 的矩阵图 为核心，结合同目录下的 keyboard.json、默认键位 keymap.c 以及 rev1/rev2 的对照资料，系统讲解如何读懂一张键盘矩阵图、矩阵编号与真实 GPIO 引脚的对应关系，以及矩阵坐标如何通过layouts定义映射到物理键位。读完本文，你将掌握 QMK 键盘矩阵图的阅读方法、matrix_pins与diode_direction的配置原理，并能独立排查"按键错位/失灵"类问题。

一、矩阵图原貌：Rev3 的 5×15 硬件矩阵

AEBoards Constellation 是一款 gasket 结构的 65% 键盘（由 Xelus22 维护，详见 readme.md）。Rev3 的 matrix_diagram.md 用一张 ASCII 图直观呈现了 PCB 上每个按键的矩阵坐标：

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

这张图的信息量远超"长得像键盘"本身，它是理解固件配置的钥匙：

• 5 行、15 列，构成完整的 5×15 扫描矩阵，所有按键的矩阵坐标都落在[0..4] × [0..14]范围内；
• 每个格子内的两位编号是行号 + 列号的十六进制拼接：例如0D表示第 0 行、第 13 列（矩阵坐标[0, 13]），2D表示第 2 行、第 13 列（[2, 13]）；
• 上图顶部特别标注的0D是2u Backspace（2u 退格键）——这是该 PCB 最具辨识度的特性之一；
• 图中有两处刻意留空的坐标：第 3 行的3B（[3, 11]）和第 4 行的4B（[4, 11]），说明这两列在对应行上没有实际键位，属于物理矩阵的"空位"。

二、矩阵编号规则：如何把图上的坐标翻译成固件坐标

QMK 的矩阵坐标统一写作[row, col]。matrix_diagram 图中的两位数编号采用 "行在十位、列在个位" 的紧凑写法，但在本仓库的 5 行 15 列矩阵下，个位超过 9 时使用十六进制字母（A=10、B=11、C=12、D=13、E=14）。例如：

值得注意的是2D（[2, 13]）出现在第一行（y=0）的位置上：这正是split backspace（分裂退格）的体现——2D在物理上位于顶行的\位置，但矩阵坐标属于第 2 行第 13 列。这一细节说明"图上位置"与"矩阵坐标"并不必然一一对应，矩阵编号表达的是电气扫描位置而非键帽几何位置。

三、矩阵编号与 GPIO 引脚的对应：keyboard.json 的 matrix_pins

矩阵图的坐标体系与 rev3/keyboard.json 中声明的引脚一一对应：

"matrix_pins": { "cols": ["E6", "D5", "B2", "B3", "D3", "F6", "F7", "C7", "C6", "B6", "B5", "B4", "D7", "D6", "D4"], "rows": ["B0", "B1", "F0", "F1", "F4"] }, "diode_direction": "COL2ROW"

• cols数组有15 个元素，索引 0~14 分别对应矩阵列 0~14，也就是图上每个坐标的"个位/字母"：列 0 接E6，列 13 接D6（0D/2D的列），列 14 接D4；
• rows数组有5 个元素，索引 0~4 对应矩阵行 0~4：行 0 接B0，行 4 接F4；
• diode_direction为COL2ROW，表示二极管从列指向行（列线为输出、行线为输入），这与绝大多数直列扫描 PCB 一致，决定了底层矩阵扫描函数的读取方向。

把图上坐标与引脚拼接起来，例如坐标[0, 13]（2u Backspace）就意味着"行 0（B0）× 列 13（D6）"的交叉点；坐标[2, 13]（split 布局的\）则是"行 2（F0）× 列 13（D6）"。同一列、不同行的关系解释了为什么0D与2D共用一条列线D6——这正是矩阵扫描节省 I/O 的核心。

四、从矩阵到键位：layouts 定义如何引用矩阵坐标

矩阵坐标本身不含键位语义，键位语义由keyboard.json的layouts块赋予。Rev3 声明了两个布局：

• LAYOUT_65_ansi_rwkl：标准 65% + 右移功能区（right winkeyless 风格）布局；
• LAYOUT_65_ansi_rwkl_split_bs：在上一布局基础上把 2u Backspace 分裂为\+ Backspace，并通过layout_aliases提供了LAYOUT_all别名，指向此布局。

每个键位条目由"matrix": [row, col]和"x"/"y"（键帽几何坐标）、可选的"w"（键宽）组成。以 split 布局顶行为例：

{"matrix": [0, 13], "x": 13, "y": 0}, // \ 键（matrix [0,13]） {"matrix": [2, 13], "x": 14, "y": 0}, // Backspace（matrix [2,13]） {"matrix": [0, 14], "x": 15, "y": 0} // Home

这段定义与矩阵图顶部的标注完全吻合：0D与2D并列在顶行，0E收尾。而标准LAYOUT_65_ansi_rwkl中顶行则是{"matrix": [0, 13], "x": 13, "y": 0, "w": 2}——用"w": 2把[0, 13]一个矩阵坐标扩成 2u 宽，即 2u Backspace。两种物理配列共用同一套硬件矩阵，只是layouts定义不同，这正是 QMK 支持"一板多配列"的机制。

底排的映射同样印证矩阵图：[4, 5]以"w": 6.25定义为 6.25u 空格，[4, 9]、[4, 10]分别为 1.5u 的 Fn 与右 Ctrl，[4, 12]~[4, 14]为左/下/右方向键——图上45 / 49 / 4A / 4C / 4D / 4E的位置与之一一对应。矩阵图中的空位3B、4B在layouts中同样不存在对应条目。

五、把矩阵图落到键位代码：默认键位图的实战对照

默认键位 keymaps/default/keymap.c 使用LAYOUT_65_ansi_rwkl_split_bs定义键值，矩阵坐标顺序与layouts完全一致：

[0] = LAYOUT_65_ansi_rwkl_split_bs( KC_ESC, KC_1, ... KC_BSLS, KC_DEL, KC_HOME, // 顶行（含 \ 与 Del） KC_TAB, ... KC_BSPC, KC_PGUP, // 第二行（1.5u Backspace） KC_LCTL, ... KC_ENT, KC_PGDN, // 第三行（2.25u Enter） KC_LSFT, ... KC_RSFT, KC_UP, KC_END, // 第四行（1.75u 右 Shift） KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, MO(1), KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT),

对照矩阵图可以确认：

• 顶行的KC_BSLS位于[0, 13]（图上0D），KC_DEL位于[2, 13]（图上2D），KC_HOME位于[0, 14]（图上0E）；
• Fn 层（第 1 层）在MO(1)位置（矩阵[4, 9]，图上49）之上放置了QK_BOOT等键值，这与 readme.md 所述"Fn + Backspace 软复位"的复位方式一致；
• 仓库同时提供了标准布局键位 default_65_ansi_rwkl/keymap.c，使用的是 2u Backspace 的LAYOUT_65_ansi_rwkl，键位参数数量较 split 版本少一个，可直接对照体验两种配列。

当固件出现"按下 A 却输出 B"之类的错位时，排查路径就是：物理位置 → matrix_diagram 坐标 → keyboard.json 中 layouts 的 matrix 条目 → keymap.c 的键值参数顺序，四者任一处错位都会导致按键错乱，而矩阵图正是这条链路的中间枢纽。

六、跨版本视角：Rev3 与 Rev1/Rev2 的矩阵对比

仓库中保留了三代 PCB 的矩阵资料，便于对比演进：

从 rev2/keyboard.json 与 rev3/keyboard.json 的对比可以推断：三代 PCB 的矩阵拓扑保持高度一致（同为 5 行 15 列、COL2ROW、空位同为[3, 11]/[4, 11]），主要差异体现在：

1. 主控更换：Rev2 使用 STM32L422（stm32-dfu引导），Rev3 换回 atmega32u4（atmel-dfu引导）；
2. 引脚重排：Rev3 的matrix_pins全部为 AVR 引脚名（E6、B0等），与 Rev2 的 STM32 引脚（B12、A1等）完全不同——这再次说明矩阵坐标是与引脚无关的逻辑层抽象，读矩阵图时无需关心底层是哪颗 MCU；
3. 底排空格列位置：两版layouts中 6.25u 空格的矩阵坐标不同（Rev2 为[4, 8]，Rev3 为[4, 5]），反映了两版 PCB 走线的细微调整，但图上"空格键居中、两侧各 3 键"的配列形态不变。

这一对比也揭示了一个实用结论：只要矩阵拓扑（行数、列数、空位）不变，rev3 的矩阵图即可作为理解 rev1/rev2 配列的通用参考，而引脚配置必须回到各自版本的keyboard.json中核对。

七、实践清单：如何利用矩阵图完成开发与排障

结合以上分析，给出围绕矩阵图的完整实践步骤：

1. 读图定位：拿到 PCB 后，先在 matrix_diagram.md 中找到目标按键的两位编号，拆出[row, col]；
2. 核对引脚：在 rev3/keyboard.json 的matrix_pins中按索引查对应 GPIO，确认与 PCB 原理图一致；
3. 核对布局条目：在layouts中找到该matrix坐标对应的键位条目，确认x/y/w参数符合键帽尺寸；
4. 核对键位代码：打开 default/keymap.c，按LAYOUT_65_ansi_rwkl_split_bs（或 default_65_ansi_rwkl/keymap.c 的标准布局）的参数顺序核对键值；
5. 构建烧录：配置好构建环境后执行make aeboards/constellation/rev3:default编译固件，配合 Bootmagic（按住左上角键插入 USB）或 Fn+Backspace 软复位进行验证，详见 rev3/readme.md。

整套流程的关键在于：矩阵图是连接"硬件电气连接"与"固件逻辑键位"的桥梁，读懂了 Rev3 这张 5×15 矩阵图，就等于掌握了该键盘固件从引脚到键值的完整映射链路。

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