读懂 QMK 键盘矩阵图以 CannonKeys Balance 为例【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读本文以 QMK 固件仓库中 CannonKeys Balance 键盘的矩阵接线图为线索系统讲解 QMK 键盘矩阵Matrix的编号规则、物理接线与固件配置之间的对应关系。通过本文你将掌握如何读懂一张 ASCII 矩阵图、如何将图中的行列坐标与 keyboard.json 中的matrix_pins、layouts定义互相印证并知道在排查按键失灵、自行飞线或理解 PCB 走线时如何利用这张图。本文全部内容基于当前 QMK 仓库中 CannonKeys Balance 的实际文件可直接对照源码验证。什么是矩阵图CannonKeys 的硬件文档惯例机械键盘的按键并不是每个都独占一个 MCU 引脚而是按行Row× 列Col组成矩阵通过二极管防止串扰由固件逐行逐列扫描。因此理解每个物理键位对应哪个(row, col)坐标是进行固件调试、硬件排障和 DIY 焊接的前提。在 QMK 仓库的keyboards/cannonkeys/目录下CannonKeys 为其绝大多数键盘都维护了一张matrix_diagram.md矩阵图包括 balance、instant60、onyx、serenity、vector 等 27 款这已成为该厂商在仓库内公开硬件信息的固定惯例。Balance 的矩阵图位于 keyboards/cannonkeys/balance/matrix_diagram.md全图用 ASCII 字符绘制直接标注了每个键帽对应的矩阵坐标。Balance 矩阵图全貌以下是原图完整内容未作任何删减┌───┐ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐│0F │┌───┬───┬───┬───┐ ┌───────┐ │00 │01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │0E │└───┘│0G │0H │0I │0J │ │0D │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤┌───┐├───┼───┼───┼───┤ └─┬─────┤ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D ││1F ││1G │1H │1I │1J │ │ │ 2.25u ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤├───┤├───┼───┼───┼───┤ ┌──┴┐2D │ ISO Enter LShift │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2D ││2F ││2G │2H │2I │2J │ │2C │ │ ┌────────┐ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────────┤└───┘├───┼───┼───┼───┤ └───┴────┘ │30 │ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3C │┌───┐│3G │3H │3I │3J │ └────────┘ ├────┼───┼───┴┬──┴───┴───┴───┴───┴───┴───┴───┴┬──┴─┬─┴─┬────┬───┘│3F │└───┼───┼───┼───┤ │40 │41 │42 │46 │4A │4B │4C │┌───┼───┼───┐│4H │4I │4J │ └────┴───┴────┴───────────────────────────┴────┴───┴────┘│4D │4F │4G │└───┴───┴───┘ └───┴───┴───┘ ┌─────┬───┬─────┬───────────────────────────┬─────┬─────┐ │40 │41 │42 │46 │4B │4C │ RWKL └─────┴───┴─────┴───────────────────────────┴─────┴─────┘ ┌─────┬───┬─────┬────────────────────────┬────┬────┬────┐ │40 │41 │42 │46 │4A │4B │4C │ └─────┴───┴─────┴────────────────────────┴────┴────┴────┘从图中可以立刻读出三个信息层次矩阵规模Balance 采用5 行 × 20 列的矩阵坐标编号为行号 列号的组合如00表示第 0 行第 0 列。键位分区左侧是 60% 主键区右上角独立标注0F的位置是旋转编码器旋钮再右侧是0G–0J起的一整块数字小键盘区。布局标注图中用文字标出了2.25u LShift、2u Backspace、ISO Enter、RWKL等大键位与特殊布局的矩阵位置。编号规则十六进制坐标如何与固件对应图中使用的列编号为0–9、A–J这是十六进制风格的编号A10、B11……J19共 20 列恰好与 keyboard.json 中matrix_pins.cols的 20 个引脚一一对应matrix_pins: { cols: [B11, B10, B2, B1, B0, A7, A6, A5, A4, A3, A2, A1, F1, C15, B3, C14, C13, B9, B8, B7], rows: [B4, A15, A14, A0, F0] }, diode_direction: COL2ROW也就是说矩阵坐标中的列序号直接对应cols数组的索引行序号对应rows数组的索引。例如图中左下角40第 4 行第 0 列即代表rows[4] F0与cols[0] B11的交叉点。同时diode_direction: COL2ROW表明该键盘的二极管负极接行、正极接列这是固件扫描矩阵时判断方向的关键配置QMK 的配置说明可参见 docs/reference_info_json.md。如果自行飞线或更换 PCB 时二极管方向装反就需要把该值改为ROW2COL。分区块解读从图到硬件主键区第 0–4 行第 0 行00Esc→01–09数字 1–9→0A0→0B-→0C→0DBackspace→0EDelete。图中右侧专门标注了2u Backspace指0D这个位置在 ANSI 大退格布局下使用 2u 键帽。第 1 行10Tab→11–1AQ 到 ]→1B、1C、1D等。第 2 行20Caps Lock1.75u→21–2BA 到 →2DEnter。注意图中2C与2D相邻绘制并标注ISO Enter对应 ISO 布局下带高度h: 2的竖排回车键——在 keyboard.json 的LAYOUT_iso中该键定义为{label: Enter, matrix: [2, 13], x: 13.75, y: 1.25, w: 1.25, h: 2}。第 3 行左侧单独画出30大键帽并标注2.25u LShift主键区30起依次为 Z、X、C……至3C右 Shift 区域。第 4 行40Ctrl→41GUI/Win→42Alt→46Space7u→4A右 Alt→4BFn→4C右 Ctrl。旋转编码器0F矩阵图在0E右侧单独框出0F这正是 keyboard.json 中定义的旋转编码器KNOBencoder: { rotary: [ {pin_a: B5, pin_b: B6, resolution: 2} ] }编码器不占用行列矩阵引脚而是接在 B5/B6 两个独立引脚上resolution: 2表示每步触发 2 个脉冲。在默认键位中它被映射为KC_MPLY播放/暂停参见 keymaps/default/keymap.c。数字小键盘区0G–0J、1G–1J、2G–2J、3G–3J、4H–4J矩阵图右上角用三列竖排的方式画出了完整的小键盘0GNum Lock→0H/→0I*→0J-下面依次是 7/8/9/、4/5/6/、1/2/3/Enter最后一行是4H0→4I.→4JEnter。这与 keyboard.json 的LAYOUT_all中[0,16]–[4,19]的定义一一对应。指示灯配置中num_lock: B14也正是指向这块小键盘区域的 Num Lock 状态灯。底部行变体RWKL 等矩阵图底部用两行独立示意了第 4 行的不同键位组合一行只列40/41/42/46/4B/4C并标注 RWKL另一行列全40/41/42/46/4A/4B/4C。这表示 Balance 的底行存在是否保留 4A右 Alt等不同的装配变体焊盘共用同一矩阵位置仅键帽与固件映射不同——这也是为什么 keyboard.json 需要同时提供LAYOUT_all、LAYOUT_ansi、LAYOUT_ansi_split_bs、LAYOUT_iso、LAYOUT_iso_split_bs五种布局宏来覆盖这些变体。从矩阵图到 keymap坐标如何变成按键矩阵图与固件之间最直接的桥梁是 keyboard.json 中的layouts定义。以LAYOUT_all为例每个键位条目都带有matrix: [row, col]字段{label: Esc, matrix: [0, 0], x: 0, y: 0.25}, {label: Backspace, matrix: [0, 13], x: 13, y: 0.25}, {label: Space, matrix: [4, 6], x: 3.5, y: 4.25, w: 7},图中的00就是这里的[0, 0]图中的46就是[4, 6]7u 空格。默认键位 keymaps/default/keymap.c 正是按照LAYOUT_all的顺序逐键填写键值[_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_DEL, KC_MPLY, KC_NUM, KC_PSLS, KC_PAST, KC_PMNS, ... KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT, KC_P0, KC_PDOT, KC_PENT ),注意最后一行的KC_MPLY正是矩阵图0F处的旋钮编码器而KC_NUM, KC_PSLS, KC_PAST, KC_PMNS对应0G–0J小键盘区。ISO 用户则可参考 keymaps/default_iso/keymap.c其中用KC_NUHS、KC_NUBS补齐了 ISO 布局特有的键位矩阵位置与图中的 ISO Enter2D/2C 区域标注吻合。矩阵图的实战用途按键失灵排查当某个按键无响应时先在矩阵图中找到它的(row, col)坐标再用万用表或短接法检查对应行列引脚与二极管可快速定位是键帽、轴体还是 PCB 走线的问题。DIY 飞线参考矩阵图相当于一张逻辑走线图自行焊接或维修时可对照图中坐标与matrix_pins的引脚顺序确认每一根线的去向。固件配置核对改键位、新增布局变体时以矩阵图为准核对keyboard.json中的matrix字段与 keymap 中的键值顺序是否一致避免行列错位。理解二极管方向结合diode_direction: COL2ROW与 PCB 实物确认二极管方向与固件配置一致防止幽灵按键或整行整列失灵。小结CannonKeys Balance 的矩阵图虽然只是一张 ASCII 图但它完整承载了物理键位 → 矩阵坐标 → 固件配置这条链路的关键信息5 行 20 列的十六进制坐标与 keyboard.json 的matrix_pins、layouts严格对应编码器、小键盘区、底行变体等特殊部分也都有明确标注。读懂这张图就等于同时读懂了这块键盘的硬件接线与 QMK 固件的数据结构是后续进行键位定制与故障排查的基础。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
读懂 QMK 键盘矩阵图：以 CannonKeys Balance 为例
读懂 QMK 键盘矩阵图以 CannonKeys Balance 为例【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读本文以 QMK 固件仓库中 CannonKeys Balance 键盘的矩阵接线图为线索系统讲解 QMK 键盘矩阵Matrix的编号规则、物理接线与固件配置之间的对应关系。通过本文你将掌握如何读懂一张 ASCII 矩阵图、如何将图中的行列坐标与 keyboard.json 中的matrix_pins、layouts定义互相印证并知道在排查按键失灵、自行飞线或理解 PCB 走线时如何利用这张图。本文全部内容基于当前 QMK 仓库中 CannonKeys Balance 的实际文件可直接对照源码验证。什么是矩阵图CannonKeys 的硬件文档惯例机械键盘的按键并不是每个都独占一个 MCU 引脚而是按行Row× 列Col组成矩阵通过二极管防止串扰由固件逐行逐列扫描。因此理解每个物理键位对应哪个(row, col)坐标是进行固件调试、硬件排障和 DIY 焊接的前提。在 QMK 仓库的keyboards/cannonkeys/目录下CannonKeys 为其绝大多数键盘都维护了一张matrix_diagram.md矩阵图包括 balance、instant60、onyx、serenity、vector 等 27 款这已成为该厂商在仓库内公开硬件信息的固定惯例。Balance 的矩阵图位于 keyboards/cannonkeys/balance/matrix_diagram.md全图用 ASCII 字符绘制直接标注了每个键帽对应的矩阵坐标。Balance 矩阵图全貌以下是原图完整内容未作任何删减┌───┐ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐│0F │┌───┬───┬───┬───┐ ┌───────┐ │00 │01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │0E │└───┘│0G │0H │0I │0J │ │0D │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤┌───┐├───┼───┼───┼───┤ └─┬─────┤ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D ││1F ││1G │1H │1I │1J │ │ │ 2.25u ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤├───┤├───┼───┼───┼───┤ ┌──┴┐2D │ ISO Enter LShift │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2D ││2F ││2G │2H │2I │2J │ │2C │ │ ┌────────┐ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────────┤└───┘├───┼───┼───┼───┤ └───┴────┘ │30 │ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3C │┌───┐│3G │3H │3I │3J │ └────────┘ ├────┼───┼───┴┬──┴───┴───┴───┴───┴───┴───┴───┴┬──┴─┬─┴─┬────┬───┘│3F │└───┼───┼───┼───┤ │40 │41 │42 │46 │4A │4B │4C │┌───┼───┼───┐│4H │4I │4J │ └────┴───┴────┴───────────────────────────┴────┴───┴────┘│4D │4F │4G │└───┴───┴───┘ └───┴───┴───┘ ┌─────┬───┬─────┬───────────────────────────┬─────┬─────┐ │40 │41 │42 │46 │4B │4C │ RWKL └─────┴───┴─────┴───────────────────────────┴─────┴─────┘ ┌─────┬───┬─────┬────────────────────────┬────┬────┬────┐ │40 │41 │42 │46 │4A │4B │4C │ └─────┴───┴─────┴────────────────────────┴────┴────┴────┘从图中可以立刻读出三个信息层次矩阵规模Balance 采用5 行 × 20 列的矩阵坐标编号为行号 列号的组合如00表示第 0 行第 0 列。键位分区左侧是 60% 主键区右上角独立标注0F的位置是旋转编码器旋钮再右侧是0G–0J起的一整块数字小键盘区。布局标注图中用文字标出了2.25u LShift、2u Backspace、ISO Enter、RWKL等大键位与特殊布局的矩阵位置。编号规则十六进制坐标如何与固件对应图中使用的列编号为0–9、A–J这是十六进制风格的编号A10、B11……J19共 20 列恰好与 keyboard.json 中matrix_pins.cols的 20 个引脚一一对应matrix_pins: { cols: [B11, B10, B2, B1, B0, A7, A6, A5, A4, A3, A2, A1, F1, C15, B3, C14, C13, B9, B8, B7], rows: [B4, A15, A14, A0, F0] }, diode_direction: COL2ROW也就是说矩阵坐标中的列序号直接对应cols数组的索引行序号对应rows数组的索引。例如图中左下角40第 4 行第 0 列即代表rows[4] F0与cols[0] B11的交叉点。同时diode_direction: COL2ROW表明该键盘的二极管负极接行、正极接列这是固件扫描矩阵时判断方向的关键配置QMK 的配置说明可参见 docs/reference_info_json.md。如果自行飞线或更换 PCB 时二极管方向装反就需要把该值改为ROW2COL。分区块解读从图到硬件主键区第 0–4 行第 0 行00Esc→01–09数字 1–9→0A0→0B-→0C→0DBackspace→0EDelete。图中右侧专门标注了2u Backspace指0D这个位置在 ANSI 大退格布局下使用 2u 键帽。第 1 行10Tab→11–1AQ 到 ]→1B、1C、1D等。第 2 行20Caps Lock1.75u→21–2BA 到 →2DEnter。注意图中2C与2D相邻绘制并标注ISO Enter对应 ISO 布局下带高度h: 2的竖排回车键——在 keyboard.json 的LAYOUT_iso中该键定义为{label: Enter, matrix: [2, 13], x: 13.75, y: 1.25, w: 1.25, h: 2}。第 3 行左侧单独画出30大键帽并标注2.25u LShift主键区30起依次为 Z、X、C……至3C右 Shift 区域。第 4 行40Ctrl→41GUI/Win→42Alt→46Space7u→4A右 Alt→4BFn→4C右 Ctrl。旋转编码器0F矩阵图在0E右侧单独框出0F这正是 keyboard.json 中定义的旋转编码器KNOBencoder: { rotary: [ {pin_a: B5, pin_b: B6, resolution: 2} ] }编码器不占用行列矩阵引脚而是接在 B5/B6 两个独立引脚上resolution: 2表示每步触发 2 个脉冲。在默认键位中它被映射为KC_MPLY播放/暂停参见 keymaps/default/keymap.c。数字小键盘区0G–0J、1G–1J、2G–2J、3G–3J、4H–4J矩阵图右上角用三列竖排的方式画出了完整的小键盘0GNum Lock→0H/→0I*→0J-下面依次是 7/8/9/、4/5/6/、1/2/3/Enter最后一行是4H0→4I.→4JEnter。这与 keyboard.json 的LAYOUT_all中[0,16]–[4,19]的定义一一对应。指示灯配置中num_lock: B14也正是指向这块小键盘区域的 Num Lock 状态灯。底部行变体RWKL 等矩阵图底部用两行独立示意了第 4 行的不同键位组合一行只列40/41/42/46/4B/4C并标注 RWKL另一行列全40/41/42/46/4A/4B/4C。这表示 Balance 的底行存在是否保留 4A右 Alt等不同的装配变体焊盘共用同一矩阵位置仅键帽与固件映射不同——这也是为什么 keyboard.json 需要同时提供LAYOUT_all、LAYOUT_ansi、LAYOUT_ansi_split_bs、LAYOUT_iso、LAYOUT_iso_split_bs五种布局宏来覆盖这些变体。从矩阵图到 keymap坐标如何变成按键矩阵图与固件之间最直接的桥梁是 keyboard.json 中的layouts定义。以LAYOUT_all为例每个键位条目都带有matrix: [row, col]字段{label: Esc, matrix: [0, 0], x: 0, y: 0.25}, {label: Backspace, matrix: [0, 13], x: 13, y: 0.25}, {label: Space, matrix: [4, 6], x: 3.5, y: 4.25, w: 7},图中的00就是这里的[0, 0]图中的46就是[4, 6]7u 空格。默认键位 keymaps/default/keymap.c 正是按照LAYOUT_all的顺序逐键填写键值[_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_DEL, KC_MPLY, KC_NUM, KC_PSLS, KC_PAST, KC_PMNS, ... KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT, KC_P0, KC_PDOT, KC_PENT ),注意最后一行的KC_MPLY正是矩阵图0F处的旋钮编码器而KC_NUM, KC_PSLS, KC_PAST, KC_PMNS对应0G–0J小键盘区。ISO 用户则可参考 keymaps/default_iso/keymap.c其中用KC_NUHS、KC_NUBS补齐了 ISO 布局特有的键位矩阵位置与图中的 ISO Enter2D/2C 区域标注吻合。矩阵图的实战用途按键失灵排查当某个按键无响应时先在矩阵图中找到它的(row, col)坐标再用万用表或短接法检查对应行列引脚与二极管可快速定位是键帽、轴体还是 PCB 走线的问题。DIY 飞线参考矩阵图相当于一张逻辑走线图自行焊接或维修时可对照图中坐标与matrix_pins的引脚顺序确认每一根线的去向。固件配置核对改键位、新增布局变体时以矩阵图为准核对keyboard.json中的matrix字段与 keymap 中的键值顺序是否一致避免行列错位。理解二极管方向结合diode_direction: COL2ROW与 PCB 实物确认二极管方向与固件配置一致防止幽灵按键或整行整列失灵。小结CannonKeys Balance 的矩阵图虽然只是一张 ASCII 图但它完整承载了物理键位 → 矩阵坐标 → 固件配置这条链路的关键信息5 行 20 列的十六进制坐标与 keyboard.json 的matrix_pins、layouts严格对应编码器、小键盘区、底行变体等特殊部分也都有明确标注。读懂这张图就等于同时读懂了这块键盘的硬件接线与 QMK 固件的数据结构是后续进行键位定制与故障排查的基础。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
