QMK AMJ96 矩阵接线图深度解析：读懂 PCB 矩阵编号、可选配列与自定义扫描实现

QMK AMJ96 矩阵接线图深度解析：读懂 PCB 矩阵编号、可选配列与自定义扫描实现

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

本篇技术指南以 QMK 仓库中keyboards/amjkeyboard/amj96/matrix_diagram.md的矩阵接线图为核心，系统讲解 AMJ96 键盘 PCB 的矩阵编号规则、键位物理布局、PCB 上预留的可选配列（2u Backspace、ISO Enter、2u Numpad Plus 等），并对照仓库内的keyboard.json、config.h与matrix.c源码，揭示十六进制矩阵编号背后的扫描实现原理。读完本文，你将能够独立阅读任何 QMK 键盘的 matrix diagram，并据此修改 AMJ96 键位、核对自定义布局的矩阵坐标。

矩阵图是什么，为什么要读它

QMK 固件中，每个按键并不直接对应一个 GPIO 引脚，而是被组织成"行（row）× 列（col）"的矩阵网络。matrix_diagram.md这类文档用 ASCII 图把 PCB 上每个键位对应的矩阵坐标直观地画出来，是键位移植、自定义布局（layout）校验和排障时最重要的参考资料之一。

AMJ96 的矩阵图为 Han Chen AMJ96 这块 96 键 PCB 绘制，由 QMK 维护者 @noroadsleft 于 2024 年 1 月 19 日整理。文档开头的注释也坦承了它的局限性：PCB 上有大量可选项（尤其是底部一行），但作者始终没有找到高质量的裸 PCB 高清图来逐一确认每个可选项实际支持的矩阵点，因此图中用??标注了无法确认的坐标——这一点在阅读和使用该图时需要特别留意。

十六进制编号规则：前位是行，后位是列

矩阵图里每个键位的编号采用两位十六进制表示，其中：

• 第一个字符 = 矩阵行号（row）
• 第二个字符 = 矩阵列号（col），A~F分别对应 10~15

例如：

AMJ96 的矩阵规模为7 行 × 16 列（见 config.h 中MATRIX_ROWS 7与MATRIX_COLS 16），因此行号范围为 0~6，列号范围为 0~15（十六进制0~F）。矩阵图正是把每个物理键位标注成这样的rowcol坐标。

AMJ96 完整矩阵接线图（原文）

以下是keyboards/amjkeyboard/amj96/matrix_diagram.md中的原始矩阵图，图中右侧与底部附注了各可选配列的说明：

┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1E │1F │09 │0A │0C │ ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤ ┌───────┐ │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2C │2D │2E │2F │0B │0F │6F │ │2D │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┼───┼───┼───┼───┤ └─┬─────┤ ┌─────┐ ┌───┐ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3C │3D │3E │3F │0D │6D │ │ │ │3D │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┼───┼───┼───┼───┤ ┌──┴┐?? │ ISO Enter ┌──┴┬────┤ Split Enter │?? │ 2u Numpad Plus │40 │41 │42 │43 │44 │45 │46 │47 │48 │49 │4A │4B │4C │4D │4E │4F │6E │ │?? │ │ │?? │?? │ │ │ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┼───┼───┼───┼───┤ ┌─┴───┴────┤ └───┴────┘ ├───┤ │50 │51 │52 │53 │54 │55 │56 │57 │58 │59 │5A │5B │5C │5D │5E │5F │0E │07 │ │?? │ 2.75u │ │ ├────┼───┴┬──┴─┬─┴───┴───┴───┴───┴───┴──┬┴───┴┬──┴──┬───┼───┼───┼───┼───┼───┤ └──────────┘ RShift │?? │ 2u Numpad Enter │60 │61 │62 │63 │64 │65 │66 │68 │69 │6A │6B │6C │ │ │ └────┴────┴────┴────────────────────────┴─────┴─────┴───┴───┴───┴───┴───┴───┘ └───┘ ┌────────┐ ┌───────┐ │50 │ 2.25u LShift │?? │ 2u Numpad Zero └────────┘ └───────┘

逐行解读：矩阵坐标与物理键位的对应关系

将矩阵图与 keyboard.json 中LAYOUT_all的布局定义以及 keymaps/default/keymap.c 对照，可以逐行还原每个坐标的实际键位。

第 1 行（物理第 0 行）：功能键区 + 右上三键

10~1F共 16 键对应功能键行（Esc + F1~F12 + PrtSc + Pause + Insert），右侧09、0A、0C三个坐标则落在矩阵第 0 行，对应右上角的 Delete、PgUp、PgDn。注意这里出现了一个典型特征：同一物理行上的键可以来自不同的矩阵行（行 1 与行 0 混用），这正是矩阵接线与物理排布解耦的体现。

第 2 行（物理第 1 行）：数字键行 + 退格区域

20~2F（16 键）为\``、1~0、-、=、Backspace 及一个XXXXXXX空位；右侧0B、0F、6F分别是 Num Lock、Num/、Num-。其中2D被图注标记为 **2u Backspace** 选项的坐标——使用大退格键时该键宽度扩展到 2u，并取消2E` 位置（详见后文布局对比）。

第 3 行（物理第 2 行）：Tab 起始，1.5u Tab / 1.5u 反斜杠

30~3F共 16 键，其中30（Tab）宽度 1.5u、3D（\）宽度 1.5u；右侧0D、6D分别为\上方右数第二键与 Num+的上半键。图注中ISO Enter对应的坐标被标为3D一带的??。

第 4 行（物理第 3 行）：Caps Lock 起始，2.25u 左 Shift

40~4F共 16 键，40（Caps Lock）1.75u、4C（Enter）2.25u；右侧6E是 Num+的下半键。图注中的Split Enter与2u Numpad Plus均以??标注——即把4C拆成两个键、或把6D+6E合并为 2u 加号键时对应的矩阵点尚未确认。

第 5 行（物理第 4 行）：Shift 行 + 方向键 + 小键盘上部

50~5F共 16 键：50（左 Shift）1.25u、5C（右 Shift）1.75u，5D/5E/5F对应 ↑、Num 1、Num 2；右侧0E、07为 Num 3 与 Num Enter。图注同时给出了该行两种可选项：2.25u 左 Shift（50拓宽为 2.25u，需在底部行调整）与2.75u 右 Shift（??）。

第 6 行（物理第 5 行）：底部行 + 小键盘下部

60、61、62为三个 1.25u 键（Ctrl、Win、Alt），63为 6.25u 空格，64、65为 1.5u 右 Alt 与 Fn，66、68~6C对应 Num 0、Num.、Num Enter、Num 0 区域。注意本行没有67——矩阵第 6 行第 7 列在布局中未被使用，与07（[0,7]，Num Enter）形成对照。图注中的2u Numpad Enter与2u Numpad Zero同样以??标注。

为什么会有??：PCB 可选项与已确认坐标的边界

维护者在文档注释中明确说明：AMJ96 的 PCB 预留了大量可选项（包括底部一行的多种宽度组合），但由于缺乏清晰的裸 PCB 照片，部分可选项的实际矩阵点无法确认。因此阅读该图时应区分两类信息：

• 已确认坐标：主键区（10~6C的常规排布）与部分可选项（2D的 2u Backspace、3D的 ISO Enter 区域），这些与keyboard.json的布局定义完全吻合；
• 未确认坐标：图注中以??表示的项目（Split Enter、2.75u RShift、2u Numpad Plus / Enter / Zero），在 keyboard.json 的现有布局中也找不到对应条目——若需要启用这些配列，必须以实物 PCB 实测为准，不能仅凭图注推断。

与 keyboard.json 布局定义对照

keyboard.json共定义了三个布局（layout），并提供了别名LAYOUT→LAYOUT_all：

1. LAYOUT_all：全键位布局，19 键顶行 + 19 键数字行 + 18 键 Tab/字母行 + 17 键 Caps/字母行 + 18 键 Shift 行 + 12 键底部行，小键盘+拆为6D、6E两键，Num Enter 拆为0E、07两键——这正是矩阵图主图的默认形态。
2. LAYOUT_96_ansi_rwkl_split_num_plus_enter：数字行2D扩为 2u（对应图中"2u Backspace"注记），并移除2E。
3. LAYOUT_96_ansi_rwkl_split_bs_num_plus_enter：数字行保留2D、2E、2F三键（即分体 Backspace），右侧小键盘区域仍为拆分形态。

对比三个布局可见：矩阵坐标始终不变，变化的是每个坐标对应的键宽（w字段）与键位数量。这也解释了矩阵图存在的意义——坐标是硬件的映射，布局是固件的解释。图中09/0A/0C、0B/0F/6F、0D/6D等"非连续"坐标正是各布局右侧小键盘与导航区在不同物理行上的落点。

底层原理：自定义矩阵扫描 matrix.c

AMJ96 未使用 QMK 通用矩阵驱动，而是通过 rules.mk 中的CUSTOM_MATRIX = yes与SRC += matrix.c引入了自研扫描代码，全部实现在 matrix.c 中。

列引脚分配（源码注释，见 matrix.c）：

col: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 pin: F7 F6 F5 F4 F1 F0 E6 D7 D6 D5 D1 D0 B7 B6 B0 C7

行解码方式：矩阵的 7 个行并非每行一个引脚，而是由B3、B2、B1 三个引脚以二进制译码生成（见 matrix.c 的select_row()）：row & (1<<0)写入 B3、row & (1<<1)写入 B2、row & (1<<2)写入 B1。三根引脚可组合出 8 个行地址，实际使用 7 个（MATRIX_ROWS 7）。这种"行译码"方案可以大幅节省 I/O，也是该矩阵图上0x/6x行坐标含义的物理来源。

扫描与去抖：matrix_scan()逐行选中后延时 30µs 再读取列值（源码注释明确说明"没有这个等待会读到不稳定的值"），列电平取反后按位拼成 16 位列状态；随后执行 5ms（DEBOUNCE 5，matrix.c）的去抖计数，只有去抖稳定后的状态才写入生效矩阵。另外matrix_init()中还有一段针对 D7 的// 85 REST上拉处理（matrix.c），而 D7 同时出现在列引脚表的第 7 列，属于该 PCB 的既有接线特征。

二极管方向：config.h中定义DIODE_DIRECTION COL2ROW（config.h），即二极管阳极在列、阴极在行，这也与read_cols()中"按下时读到低电平、取反后置位"的读取逻辑自洽。

实操：利用矩阵图修改 AMJ96 键位

拿到矩阵图后，最常见的用途是编写或修改键位。以默认键位 keymaps/default/keymap.c 为例：

[0] = LAYOUT_all( KC_ESC, KC_F1, ..., KC_PGDN, // 对应 10~1F 与 09/0A/0C KC_GRV, KC_1, ..., KC_PMNS, // 对应 20~2F 与 0B/0F/6F ... );

每个键位参数按LAYOUT_all的坐标顺序（即矩阵图的阅读顺序）依次给出。当你需要：

• 确认某键坐标：先在矩阵图中定位该键的 hex 编号，再到keyboard.json对应布局中核对matrix字段；
• 使用 2u Backspace：改用LAYOUT_96_ansi_rwkl_split_num_plus_enter并在键位表中减少一个参数（2E位被合并）；
• 排查按键错乱：用matrix_print()（matrix.c）输出 7×16 的实时矩阵状态，与矩阵图坐标逐位比对，可快速定位接线或键位映射错误。

编译与烧录命令（参见 readme.md）：

make amjkeyboard/amj96:default # 编译 make amjkeyboard/amj96:default:flash # 编译并烧录（atmel-dfu 引导）

注意事项与已知限制

1. LED 支持有限：readme.md明确注明 in-switch（轴体灯）与 underglow（灯带）LED当前不受支持，尽管keyboard.json中启用了rgblight并配置了 16 颗 WS2812（引脚 D3）；
2. ??坐标不可直接使用：图注中 Split Enter、2.75u RShift、2u Numpad Plus/Enter/Zero 等可选项的矩阵点未确认，启用前务必以实物测量或厂商资料为准；
3. 未使用的矩阵点：从布局与矩阵图对照可推断，08（第 0 行第 8 列）与67（第 6 行第 7 列）等位置在现有布局中未被占用，可作为自定义扩展的候选点（仅推断，需硬件验证）；
4. 矩阵图的知识产权边界：该图是维护者依据已知信息整理的参考文档，标注了不确定性，属于"尽力而为"的辅助资料，正式开发时应以keyboard.json的布局定义为准。

总结

AMJ96 的矩阵接线图看似只是一张 ASCII 编号图，实则是连接硬件接线、矩阵扫描与固件布局三者的枢纽：rowcol十六进制编号直接对应MATRIX_ROWS × MATRIX_COLS的扫描网络，图右侧与底部的注记揭示了 PCB 预留的可选配列，而??标记则提醒读者——在缺少实物照片佐证时，文档的置信度边界在哪里。结合 matrix.c 的行译码扫描实现与 keyboard.json 的多布局定义，你可以把这张图真正用起来：读图、对坐标、改键位、查排障，一步到位。

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