QMK Obliterated75 矩阵图详解从键位到行列扫描、引脚映射与布局宏【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文围绕 QMK 固件仓库中 CannonKeys Obliterated75 键盘的矩阵图文档 matrix_diagram.md 展开完整解读这张 6×16 键位矩阵图的含义与特殊键位标注并结合 keyboard.json 中的行列引脚映射、config.h 中的外设配置与 keymap.c 的键位定义说明矩阵图如何指导你编写布局宏、定位键位以及排查扫描问题。一、原始矩阵图Obliterated75 的 6 行 × 16 列矩阵图是 QMK 键盘移植中最关键的图纸之一它把每一个物理键或占位点映射到一个行×列的十六进制坐标上。Obliterated75 的完整矩阵图如下继承自 matrix_diagram.md┌───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┐ │00 │ │01 │02 │03 │04 │ │06 │07 │08 │09 │ │0A │0B │0C │0D │ │0F │ └───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┘ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ┌───────┐ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1E │1F │ │1D │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┼───┤ └─┬─────┤ │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2C │2D │2F │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┼───┤ ┌──┴┐3D │ ISO Enter │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3D │3F │ │3C │ │ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┼───┤ └───┴────┘ │40 │41 │42 │43 │44 │45 │46 │47 │48 │49 │4A │4B │4C │4D │4F │ ├────┼───┴┬──┴─┬─┴───┴───┴───┴───┴───┴──┬┴───┼───┴┬─┬───┼───┼───┤ │50 │51 │52 │56 │5A │5B │ │5C │5D │5F │ └────┴────┴────┴────────────────────────┴────┴────┘ └───┴───┴───┘ ┌────────┐ │40 │ 2.25u LShift └────────┘ ┌─────┬───┬─────┬───────────────────────────┬─────┐ │50 │51 │52 │56 │5B │ Blocker Tsangan └─────┴───┴─────┴───────────────────────────┴─────┘如何读取这张图每个格子里的十六进制数是矩阵坐标第一位是行号00–5F 中的 0–5共 6 行第二位是列号0–F共 16 列。例如2A表示第 2 行第 10 列4F表示第 4 行第 15 列。图中共 6 行第 0 行是功能键行第 1 行是数字行第 2–4 行是主键区第 5 行是底行。并非每个行列交叉点都有物理按键——空缺位置如第 0 行的 05、0E第 2 行的 2E第 4 行的 4C第 5 行空格下方的 53–55、57–59、5E在 PCB 上没有独立按键这些点在 keyboard.json 的布局定义中同样被留空。逐行解读行覆盖的列对应按键参照 default 键位空缺列000–04、06–0D、0FEsc、F1–F4、F5–F8、F9–F12、Del05、0E110–1F16 键全满、1–0、-、、Backspace(2u)、Del、Ins无220–2D、2FTab、Q–P、[、]、\、Del2E330–3B、3C(隐藏)、3D、3FCaps、A–L、;、、#(ISO)、Enter、PgUp无440–4B、4D、4FLShift、#、Z–/、↑、PgDn4C550、51、52、56(6.25u 宽)、5A–5D、5FCtrl、Gui、Alt、Space、Fn、Ctrl、←、↓、→53–55、57–59、5E图中四处特殊标注的含义1D2u BackspaceBackspace 物理上是 2u 宽键横跨第 13、14 列两个矩阵点。在 keyboard.json 的LAYOUT_ansi_blocker中Backspace定义为matrix: [1, 13]且w: 2即从矩阵点 (1,13) 出发、横向覆盖 2 格而LAYOUT_all则把 (1,14) 单独用作 Delete 键。3DISO Enter 与隐藏键3CEnter 键矩阵点 (3,13)下方藏着一个 ISO 布局专用矩阵点 (3,12)3C。在LAYOUT_iso_blocker中该点被映射为#键而 Enter 键标注为y: 2.25, h: 2纵跨两行——这正是 ISO 键盘矮回车造型在矩阵上的实现方式。402.25u LShift左 Shift 为 2.25u 宽键但只占用 1 个矩阵点 (4,0)在 keyboard.json 的LAYOUT_ansi_blocker中以w: 2.25描述其物理宽度。56Blocker Tsangan空格键空格是一个 6.25u 的超宽键标签写在矩阵点 (5,6) 上实际物理范围横跨第 3 至第 9 列其下方的 53–55、57–59 列位置没有独立按键。二、矩阵图与引脚映射keyboard.json 是唯一事实源Obliterated75 的目录中没有传统的obliterated75.c矩阵定义文件行列信息完全由 keyboard.json 的数据驱动配置生成。矩阵图中的每个行列坐标最终都落到具体的 MCU 引脚上matrix_pins: { cols: [A5, B10, A3, A2, B0, A9, C13, B9, B8, B7, B6, B5, B4, B3, A15, A14], rows: [A13, B12, B11, B14, A8, A1] }, diode_direction: COL2ROW,引自 keyboard.json结合矩阵图可以读出以下事实列引脚顺序即列号顺序矩阵图第 0 列对应引脚A5第 1 列对应B10……第 15 列0F/1F/2F/3F/4F/5F所在列对应A14。也就是说图中最右侧那一列 Delete/PgUp/PgDn/→ 键全部走A14这根列线。行引脚顺序即行号顺序第 0 行功能键行走A13第 5 行底行走A1。二极管方向为 COL2ROW列线经二极管连向行线QMK 扫描时按此方向驱动列、读取行。若你在排查按某个键却触发邻键的问题应先对照矩阵图确认两个键是否共享同一列线再检查该列二极管焊反或短路。NKRO 支持keyboard.json 的features中声明了nkro: true、console: true、command: true因此烧录后可以用 QMK 控制台实时观察矩阵扫描结果把实际点亮的行列坐标与本文矩阵图逐一核对这是验证矩阵图的直接手段。该键盘使用STM32F072CBT6处理器见 readme.md 的 Hardware Supported 说明bootloader 为stm32-dfuUSB 描述符为 VID0xCA04、PID0x0B75。三、从矩阵图到布局宏LAYOUT_all 与 Blocker 变体矩阵图给出的是物理点位而键位文件使用布局宏把点位排成一行行的键数组。keymaps/default/keymap.c 中const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [_BASE] LAYOUT_all( KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_DEL, KC_GRV, 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_INS, ... ),第一行 14 个参数依次填到00 01 02 03 04 06 07 08 09 0A 0B 0C 0D 0F——注意矩阵图中 05、0E 空缺所以这里只写 14 个键而不是 16 个第二行 16 个参数正好填满10–1FKC_BSPC/KC_DEL/KC_INS落在1D/1E/1F最后一行只有 9 个参数对应底行实际存在的 9 个点位50 51 52 56 5A 5B 5C 5D 5F。keyboard.json 为此键盘定义了 5 个布局宏LAYOUT_all标准 ANSI 全功能、LAYOUT_ansi_blockerBackspace 为 2u、无独立 Delete/Insert 区分、LAYOUT_ansi_blocker_split_bs、LAYOUT_iso_blocker与LAYOUT_iso_blocker_split_bs。它们的差别正是矩阵图标注的直接反映布局宏关键差异矩阵点LAYOUT_all(1,13)Backspace、(1,14)Delete、(1,15)Insert(3,13)Enter 普通 1.25uLAYOUT_ansi_blocker(1,13)Backspace 宽 2uw: 2(1,14) 留空(3,13)Enter 宽 2.25uLAYOUT_iso_blocker(3,12)3C用作#键(3,13)Enter 纵跨两行h: 2还原 ISO 矮回车如果你要写新键位先查矩阵图确认目标键的行列号再在对应布局宏的对应行、对应顺序位置填入 keycode顺序不能错位——这是矩阵图最核心的实战用途。四、外设配置矩阵之外的行列邻居矩阵图只覆盖按键扫描而同一块 PCB 上还有背光与 RGB 灯它们的配置可参考 config.h#define BACKLIGHT_PWM_DRIVER PWMD3 #define BACKLIGHT_PWM_CHANNEL 1 #define BACKLIGHT_PAL_MODE 1 #define WS2812_SPI_DRIVER SPID2 #define WS2812_SPI_MOSI_PAL_MODE 0 #define WS2812_SPI_SCK_PAL_MODE 0 #define WS2812_SPI_SCK_PIN B13背光PWM 输出硬件引脚为A6keyboard.json 中backlight.pin6 级亮度并支持呼吸效果default 键位的_FN1层使用了BL_UP/BL_DOWN/BL_TOGG/BL_BRTG控制它。WS2812 灯带20 颗 LEDrgblight.led_count数据脚B15通过 SPISPID2驱动而非普通位带输出keyboard.json 中ws2812.driver声明为spi与 config.h 的WS2812_SPI_DRIVER定义相呼应。_FN1层还使用了UG_TOGG/UG_NEXT等 RGB 快捷键定义见 keycodes 常量表。另外 rules.mk 中DFU_SUFFIX_ARGS -v FFFF -p FFFF是通配写法注释说明是为了兼容 APM32 MCU意味着 dfu-util 烧录时不做严格的 VID/PID 匹配。五、构建与验证用 make 命令落地这张矩阵图按照 readme.md 的说明在配置好 QMK 构建环境后make cannonkeys/obliterated75:default即编译 default 键位keymaps/default/keymap.c。由于 keyboard.json 开启了console与command特性烧录后可以通过 QMK 控制台执行矩阵扫描相关命令把每个键按下后报告的行/列与本文第一节的矩阵图逐点比对按 Esc 应报告第 0 行A13、第 0 列A5按最右列的 PgDn/→ 等键应报告第 15 列A14若某键报告的列与图中不符优先检查该列二极管与 COL2ROW 方向是否一致。小结Obliterated75 的矩阵图 用 6×16 的十六进制坐标完整刻画了这块 75% 键盘的物理键位2u Backspace 跨 (1,13)(1,14)、ISO 隐藏键 (3,12)、6.25u 空格横跨第 5 行中段等标注都与其 keyboard.json 布局宏的w/h字段一一对应。掌握矩阵坐标 → 行/列引脚 → 布局宏参数顺序这条链路后你就可以独立完成该键盘的键位编写、布局变体选择ANSI/ISO Blocker与扫描故障定位config.h 则补充了背光 PWM 与 WS2812 SPI 两条外设通路构成了这张键盘完整的硬件-固件映射关系。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK Obliterated75 矩阵图详解：从键位到行列扫描、引脚映射与布局宏
QMK Obliterated75 矩阵图详解从键位到行列扫描、引脚映射与布局宏【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文围绕 QMK 固件仓库中 CannonKeys Obliterated75 键盘的矩阵图文档 matrix_diagram.md 展开完整解读这张 6×16 键位矩阵图的含义与特殊键位标注并结合 keyboard.json 中的行列引脚映射、config.h 中的外设配置与 keymap.c 的键位定义说明矩阵图如何指导你编写布局宏、定位键位以及排查扫描问题。一、原始矩阵图Obliterated75 的 6 行 × 16 列矩阵图是 QMK 键盘移植中最关键的图纸之一它把每一个物理键或占位点映射到一个行×列的十六进制坐标上。Obliterated75 的完整矩阵图如下继承自 matrix_diagram.md┌───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┐ │00 │ │01 │02 │03 │04 │ │06 │07 │08 │09 │ │0A │0B │0C │0D │ │0F │ └───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┘ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ┌───────┐ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1E │1F │ │1D │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┼───┤ └─┬─────┤ │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2C │2D │2F │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┼───┤ ┌──┴┐3D │ ISO Enter │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3D │3F │ │3C │ │ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┼───┤ └───┴────┘ │40 │41 │42 │43 │44 │45 │46 │47 │48 │49 │4A │4B │4C │4D │4F │ ├────┼───┴┬──┴─┬─┴───┴───┴───┴───┴───┴──┬┴───┼───┴┬─┬───┼───┼───┤ │50 │51 │52 │56 │5A │5B │ │5C │5D │5F │ └────┴────┴────┴────────────────────────┴────┴────┘ └───┴───┴───┘ ┌────────┐ │40 │ 2.25u LShift └────────┘ ┌─────┬───┬─────┬───────────────────────────┬─────┐ │50 │51 │52 │56 │5B │ Blocker Tsangan └─────┴───┴─────┴───────────────────────────┴─────┘如何读取这张图每个格子里的十六进制数是矩阵坐标第一位是行号00–5F 中的 0–5共 6 行第二位是列号0–F共 16 列。例如2A表示第 2 行第 10 列4F表示第 4 行第 15 列。图中共 6 行第 0 行是功能键行第 1 行是数字行第 2–4 行是主键区第 5 行是底行。并非每个行列交叉点都有物理按键——空缺位置如第 0 行的 05、0E第 2 行的 2E第 4 行的 4C第 5 行空格下方的 53–55、57–59、5E在 PCB 上没有独立按键这些点在 keyboard.json 的布局定义中同样被留空。逐行解读行覆盖的列对应按键参照 default 键位空缺列000–04、06–0D、0FEsc、F1–F4、F5–F8、F9–F12、Del05、0E110–1F16 键全满、1–0、-、、Backspace(2u)、Del、Ins无220–2D、2FTab、Q–P、[、]、\、Del2E330–3B、3C(隐藏)、3D、3FCaps、A–L、;、、#(ISO)、Enter、PgUp无440–4B、4D、4FLShift、#、Z–/、↑、PgDn4C550、51、52、56(6.25u 宽)、5A–5D、5FCtrl、Gui、Alt、Space、Fn、Ctrl、←、↓、→53–55、57–59、5E图中四处特殊标注的含义1D2u BackspaceBackspace 物理上是 2u 宽键横跨第 13、14 列两个矩阵点。在 keyboard.json 的LAYOUT_ansi_blocker中Backspace定义为matrix: [1, 13]且w: 2即从矩阵点 (1,13) 出发、横向覆盖 2 格而LAYOUT_all则把 (1,14) 单独用作 Delete 键。3DISO Enter 与隐藏键3CEnter 键矩阵点 (3,13)下方藏着一个 ISO 布局专用矩阵点 (3,12)3C。在LAYOUT_iso_blocker中该点被映射为#键而 Enter 键标注为y: 2.25, h: 2纵跨两行——这正是 ISO 键盘矮回车造型在矩阵上的实现方式。402.25u LShift左 Shift 为 2.25u 宽键但只占用 1 个矩阵点 (4,0)在 keyboard.json 的LAYOUT_ansi_blocker中以w: 2.25描述其物理宽度。56Blocker Tsangan空格键空格是一个 6.25u 的超宽键标签写在矩阵点 (5,6) 上实际物理范围横跨第 3 至第 9 列其下方的 53–55、57–59 列位置没有独立按键。二、矩阵图与引脚映射keyboard.json 是唯一事实源Obliterated75 的目录中没有传统的obliterated75.c矩阵定义文件行列信息完全由 keyboard.json 的数据驱动配置生成。矩阵图中的每个行列坐标最终都落到具体的 MCU 引脚上matrix_pins: { cols: [A5, B10, A3, A2, B0, A9, C13, B9, B8, B7, B6, B5, B4, B3, A15, A14], rows: [A13, B12, B11, B14, A8, A1] }, diode_direction: COL2ROW,引自 keyboard.json结合矩阵图可以读出以下事实列引脚顺序即列号顺序矩阵图第 0 列对应引脚A5第 1 列对应B10……第 15 列0F/1F/2F/3F/4F/5F所在列对应A14。也就是说图中最右侧那一列 Delete/PgUp/PgDn/→ 键全部走A14这根列线。行引脚顺序即行号顺序第 0 行功能键行走A13第 5 行底行走A1。二极管方向为 COL2ROW列线经二极管连向行线QMK 扫描时按此方向驱动列、读取行。若你在排查按某个键却触发邻键的问题应先对照矩阵图确认两个键是否共享同一列线再检查该列二极管焊反或短路。NKRO 支持keyboard.json 的features中声明了nkro: true、console: true、command: true因此烧录后可以用 QMK 控制台实时观察矩阵扫描结果把实际点亮的行列坐标与本文矩阵图逐一核对这是验证矩阵图的直接手段。该键盘使用STM32F072CBT6处理器见 readme.md 的 Hardware Supported 说明bootloader 为stm32-dfuUSB 描述符为 VID0xCA04、PID0x0B75。三、从矩阵图到布局宏LAYOUT_all 与 Blocker 变体矩阵图给出的是物理点位而键位文件使用布局宏把点位排成一行行的键数组。keymaps/default/keymap.c 中const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [_BASE] LAYOUT_all( KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_DEL, KC_GRV, 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_INS, ... ),第一行 14 个参数依次填到00 01 02 03 04 06 07 08 09 0A 0B 0C 0D 0F——注意矩阵图中 05、0E 空缺所以这里只写 14 个键而不是 16 个第二行 16 个参数正好填满10–1FKC_BSPC/KC_DEL/KC_INS落在1D/1E/1F最后一行只有 9 个参数对应底行实际存在的 9 个点位50 51 52 56 5A 5B 5C 5D 5F。keyboard.json 为此键盘定义了 5 个布局宏LAYOUT_all标准 ANSI 全功能、LAYOUT_ansi_blockerBackspace 为 2u、无独立 Delete/Insert 区分、LAYOUT_ansi_blocker_split_bs、LAYOUT_iso_blocker与LAYOUT_iso_blocker_split_bs。它们的差别正是矩阵图标注的直接反映布局宏关键差异矩阵点LAYOUT_all(1,13)Backspace、(1,14)Delete、(1,15)Insert(3,13)Enter 普通 1.25uLAYOUT_ansi_blocker(1,13)Backspace 宽 2uw: 2(1,14) 留空(3,13)Enter 宽 2.25uLAYOUT_iso_blocker(3,12)3C用作#键(3,13)Enter 纵跨两行h: 2还原 ISO 矮回车如果你要写新键位先查矩阵图确认目标键的行列号再在对应布局宏的对应行、对应顺序位置填入 keycode顺序不能错位——这是矩阵图最核心的实战用途。四、外设配置矩阵之外的行列邻居矩阵图只覆盖按键扫描而同一块 PCB 上还有背光与 RGB 灯它们的配置可参考 config.h#define BACKLIGHT_PWM_DRIVER PWMD3 #define BACKLIGHT_PWM_CHANNEL 1 #define BACKLIGHT_PAL_MODE 1 #define WS2812_SPI_DRIVER SPID2 #define WS2812_SPI_MOSI_PAL_MODE 0 #define WS2812_SPI_SCK_PAL_MODE 0 #define WS2812_SPI_SCK_PIN B13背光PWM 输出硬件引脚为A6keyboard.json 中backlight.pin6 级亮度并支持呼吸效果default 键位的_FN1层使用了BL_UP/BL_DOWN/BL_TOGG/BL_BRTG控制它。WS2812 灯带20 颗 LEDrgblight.led_count数据脚B15通过 SPISPID2驱动而非普通位带输出keyboard.json 中ws2812.driver声明为spi与 config.h 的WS2812_SPI_DRIVER定义相呼应。_FN1层还使用了UG_TOGG/UG_NEXT等 RGB 快捷键定义见 keycodes 常量表。另外 rules.mk 中DFU_SUFFIX_ARGS -v FFFF -p FFFF是通配写法注释说明是为了兼容 APM32 MCU意味着 dfu-util 烧录时不做严格的 VID/PID 匹配。五、构建与验证用 make 命令落地这张矩阵图按照 readme.md 的说明在配置好 QMK 构建环境后make cannonkeys/obliterated75:default即编译 default 键位keymaps/default/keymap.c。由于 keyboard.json 开启了console与command特性烧录后可以通过 QMK 控制台执行矩阵扫描相关命令把每个键按下后报告的行/列与本文第一节的矩阵图逐点比对按 Esc 应报告第 0 行A13、第 0 列A5按最右列的 PgDn/→ 等键应报告第 15 列A14若某键报告的列与图中不符优先检查该列二极管与 COL2ROW 方向是否一致。小结Obliterated75 的矩阵图 用 6×16 的十六进制坐标完整刻画了这块 75% 键盘的物理键位2u Backspace 跨 (1,13)(1,14)、ISO 隐藏键 (3,12)、6.25u 空格横跨第 5 行中段等标注都与其 keyboard.json 布局宏的w/h字段一一对应。掌握矩阵坐标 → 行/列引脚 → 布局宏参数顺序这条链路后你就可以独立完成该键盘的键位编写、布局变体选择ANSI/ISO Blocker与扫描故障定位config.h 则补充了背光 PWM 与 WS2812 SPI 两条外设通路构成了这张键盘完整的硬件-固件映射关系。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考