QMK 矩阵图全解析:CannonKeys Reverie Solderable 的 5×15 矩阵寻址与布局变体 📅 发布时间:2026/9/19 3:41:55 👁 浏览次数: 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 社区惯例的行号十进制 列号十六进制双字符编号首个数字 行号04共 5 行第二个字符 列号0E十六进制即 014共 15 列。因此00表示第 0 行第 0 列0E表示第 0 行第 14 列4E表示第 4 行第 14 列。全矩阵共 5 × 15 75 个矩阵位置但并非所有位置都会在每一种配列中同时出现见下文共享矩阵位置的配列切换。图中标注的特殊键位原图用旁注文字标出了三处关键物理特征它们是理解整张图的门槛标注坐标含义2u Backspace0D第 0 行第 13 列标准 ANSI/ISO 配列下是 2u 宽退格键ISO Enter1D2D由1D1.25u 宽、位于 y1与2D1.25u 宽、2u 高、纵向跨越 y1 与 y2两颗物理位置共同构成 ISO 回车2.25u LShift30第 3 行第 0 列标准底部行非 ISO下为 2.25u 左 Shift此外第 0 行中混入的2C即坐标 [2,12]第 2 行第 12 列是**分裂退格Split Backspace**的右半部分——当不启用分裂退格时0D以 2u 宽度占据 x1315 的位置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 列的引脚分配如下行索引行引脚列索引十六进制列引脚0GP26000GP281GP27101GP82GP15202GP143GP16303GP134GP17404GP12505GP11606GP10707GP9808GP6909GP5A0AGP4B0BGP3C0CGP2D0DGP1E0EGP0同时info.json声明diode_direction: COL2ROW即二极管方向为列→行扫描时列驱动、行读取。这与矩阵图的阅读方向一致——固件以行优先遍历keymaps[][MATRIX_ROWS][MATRIX_COLS]每个键的矩阵坐标就是[行][列]。硬件接线提示如果要自行飞线/检修 Reverie solderable 的某颗按键先在矩阵图中定位其坐标再查上表得到行列 GPIO即可用万用表或 QMK 的矩阵调试功能定位故障。从矩阵图到布局宏keyboard.json 的 layouts 定义QMK 采用数据驱动配置data-driven configurationkeyboard.json 的layouts字段逐键给出matrix: [行, 列]与物理坐标x / y / w / h单位 u构建系统据此自动生成LAYOUT_*宏。以全键位布局LAYOUT_all为例其定义与矩阵图逐格对应第 0 行[0,0][0,14]其中[0,13]即0D在非分裂退格配列中带w: 2ISO 回车[1,13]1D为 x12.75 的单键[2,13]2D声明为x: 13.75, y: 1, w: 1.25, h: 2——高度 2u、从 y1 纵向贯穿到 y2正是图中1D2D拼出的 ISO Enter 形状第 3 行[3,0]带w: 2.25即图中标注的 2.25u LShift第 4 行[4,0]、[4,1]、[4,2]各 1.25u40/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 Tsangan401.5u411u421.5u467u 空格4B1.5u即 1.5-1-1.5 7u 空格 1.5u 的 Tsangan/WKL 风格底部行Blocker401.25u411.25u421.25u466.25u 空格4A1.25u4B1.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/目录复用的配列全部围绕矩阵图上的同一套坐标展开配列名说明65_ansi_blockerANSI、2u 退格、标准 Blocker 底部行65_ansi_blocker_split_bsANSI、分裂退格启用2C65_ansi_blocker_tsanganANSI、Tsangan 底部行65_ansi_blocker_tsangan_split_bsANSI、Tsangan 分裂退格65_iso_blockerISO启用1D/2D回车与 1.25u 左 Shift65_iso_blocker_split_bsISO 分裂退格65_iso_blocker_tsanganISO Tsangan 底部行65_iso_blocker_tsangan_split_bsISO Tsangan 分裂退格观察keyboard.json各布局定义可以发现一个规律变体之间只有三处矩阵位置发生角色切换——0D2u 退格 ↔ 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 的原因。实战用矩阵图校验与编写 keymapReverie solderable 的默认键位位于 keymaps/default/keymap.c其_BASE层使用LAYOUT_all宏[_BASE] LAYOUT_all( QK_GESC, KC_1, KC_2, ..., KC_BSPC, KC_DEL, KC_HOME, // 第 0 行000D、2C 后的 0E KC_TAB, KC_Q, KC_W, ..., KC_BSLS, KC_END, // 第 1 行101E KC_CAPS, KC_A, KC_S, ..., KC_ENT, KC_PGUP, // 第 2 行202E KC_LSFT, KC_BSLS, KC_Z, ..., KC_RSFT, KC_UP, KC_PGDN, // 第 3 行303E KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_SPC, KC_SPC, KC_RALT, MO(_FN1), KC_LEFT, KC_DOWN, KC_RIGHT // 第 4 行 )编写自定义 keymap 时的核对步骤在矩阵图中找到目标物理按键的坐标如右上角 Delete 是0E确认该坐标在所选LAYOUT_*中的语义宽度、是否为共享位置如0D/2C、1D/2D对照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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考