QMK 矩阵接线图深度解析ADPenrose AkemiPad 数字小键盘的 6×5 矩阵、2u 键位与旋钮编码器布局【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读本文以 keyboards/adpenrose/akemipad/matrix_diagram.md 为骨架完整解读 ADPenrose AkemiPad 数字小键盘Numpad的开关矩阵接线图如何在 6 行 × 5 列的矩阵网格中表达 1u 键、纵向 2u 键Numpad Plus / Enter、横向 2u 键Numpad Zero以及独立于矩阵的旋钮编码器。读完本文你将掌握 QMK 矩阵坐标行列编号的读写方法理解keyboard.json中matrix_pins、diode_direction、layouts与矩阵图的对应关系并能据此定位键位、排查按键失灵或错位问题。1. 文档定位一张图说清整块键盘的接线地图QMK 固件中键盘固件并不直接感知键帽上的字符而是把按键组织成行Row× 列Col的电气矩阵通过逐行扫描读取每个交叉点的通断。matrix_diagram.md就是 AkemiPad 的这张接线地图——它用 ASCII 字符画直观标注了每个物理按键在矩阵中的坐标行号列号两位数字是理解该键盘 keyboard.json 中矩阵配置、以及各层 keymap 中LAYOUT_all/LAYOUT_numpad调用顺序的第一手资料。AkemiPad 是一款由 ProMicroATmega 系列驱动的数字小键盘见 readme.md支持多种布局、旋钮编码器、压电蜂鸣器、OLED 与逐键 RGB。读懂矩阵图是后续自定义键位、布局和灯效的前提。2. 矩阵图原貌与逐区解读matrix_diagram.md的原始内容如下完整继承原样呈现┌───┬───┬───┬───┐ │00 │01 │02 │03 │ └───┴───┴───┴───┘ ┌───┬───┬───┬───┐ │10 │11 │12 │13 │ ├───┼───┼───┼───┤ ┌───┐ │20 │21 │22 │23 │ │ │ ├───┼───┼───┼───┤ │23 │ 2u Numpad Plus │30 │31 │32 │33 │ │ │ ├───┼───┼───┼───┤ ├───┤ │40 │41 │42 │43 │ │ │ ┌───┐├───┼───┼───┼───┤ │43 │ 2u Numpad Enter Encoder ─ │54 ││50 │51 │52 │53 │ │ │ └───┘└───┴───┴───┴───┘ └───┘ ┌───────┐ │50 │ 2u Numpad Zero └───────┘图中每个格子内的两位数字即矩阵坐标第一位是行号Row第二位是列号Col。例如00表示第 0 行第 0 列53表示第 5 行第 3 列。整张图可以拆成四块来看区域坐标说明主键区4 列 × 5 行 底部行行 0~4 的00~43、底部50~53数字区与功能键共 24 个 1u 键位右侧纵向 2u 键232u Numpad Plus、432u Numpad Enter各占 2 行高度但只对应一个矩阵坐标底部横向 2u 键502u Numpad Zero占 2 列宽度同样只对应一个矩阵坐标旋钮编码器54位于底部左侧不占用矩阵行列单独接线2.1 主键区的物理含义结合 keymaps/default/keymap.c 中LAYOUT_all的调用顺序可以一一对应出主键区的键帽职能行 000→MO(1)、01→MO(2)、02→MO(3)、03→KC_DELDelete行 110→KC_NUMNum Lock、11→KC_PSLS/、12→KC_PAST*、13→KC_PMNS-行 220→KC_P7、21→KC_P8、22→KC_P9、23→KC_PPLS行 330→KC_P4、31→KC_P5、32→KC_P6、33→KC_PPLS行 440→KC_P1、41→KC_P2、42→KC_P3、43→KC_PENTEnter行 550→KC_P0、51→KC_P0、52→KC_PDOT.、53→KC_PENT、54→KC_MUTE静音注意一个细节在LAYOUT_all这种全 1u布局里行 2 与行 3 各有一个独立的 1u矩阵[2,3]、[3,3]行 4 与行 5 各有一个 1u Enter矩阵[4,3]、[5,3]底部50、51是两个 1u0。这与右侧/底部 2u 键的合并表达方式形成了鲜明对比正是下节要讲的核心。3. 从图示到电气配置matrix_pins 与 COL2ROW矩阵图上的行列编号在 keyboard.json 中被翻译成实际的 MCU 引脚matrix_pins: { cols: [D3, D2, F5, F6, B2], rows: [D4, D7, E6, B6, B4, B5] }, diode_direction: COL2ROW从源码结构看这套配置与矩阵图完全吻合6 个行引脚D4, D7, E6, B6, B4, B5对应图上的行 0~55 个列引脚D3, D2, F5, F6, B2对应图上的列 0~4COL2ROW表示二极管方向为列驱动、行读取即列引脚输出扫描信号、行引脚读取按键状态这是 QMK 中两种标准接法之一另一种是ROW2COL。接线方向与二极管方向不匹配时会出现按键错乱或完全无法识别因此矩阵图 该配置是一对必须同步校验的组合。QMK 关于矩阵扫描的基础原理可进一步参考 docs/how_a_matrix_works.md 与 docs/understanding_qmk.md。对于需要自定义行列映射的场景可参考 docs/custom_matrix.md 了解自定义矩阵驱动的扩展点。4. 2u 键在矩阵中的表示一个坐标 布局尺寸物理上的 2u 大键在电气矩阵中只占用一个交叉点一颗轴只有一路通断信号它变大的部分完全由布局文件中的尺寸参数w宽度、h高度表达。这一点在矩阵图中体现为右侧的 2u Plus 标注为23、2u Enter 标注为43、底部 2u Zero 标注为50——它们各自的格子只写了一个坐标而不是覆盖范围内的所有坐标。在 keyboard.json 的LAYOUT_numpad中这三个键的定义分别是{label: , matrix: [2, 3], x: 4.25, y: 2.25, h: 2}, {label: Enter, matrix: [4, 3], x: 4.25, y: 4.25, h: 2}, {label: 0, matrix: [5, 0], x: 1.25, y: 5.25, w: 2}逐个拆解2u Numpad Plus矩阵坐标[2,3]图中23h: 2使其在视觉上纵向跨越行 2、行 3 两个键位的高度。电气上它仍只有[2,3]一个触点2u Numpad Enter矩阵坐标[4,3]图中43h: 2纵向跨越行 4、行 52u Numpad Zero矩阵坐标[5,0]图中50w: 2横向跨越列 0、列 1 两个键位的宽度。而LAYOUT_all则给出了同一矩阵的全 1u版本把[2,3]、[3,3]拆成两个把[4,3]、[5,3]拆成两个 Enter把[5,0]、[5,1]拆成两个0。两套布局共用同一份矩阵接线这正是多布局支持的底层原因——矩阵图不变变的只是布局 JSON 里对同一坐标的尺寸描述与 keymap 的调用方式。配套的 keymaps/default/keymap.c 使用LAYOUT_all24 1 个 1u 键位keymaps/default_numpad/keymap.c 使用LAYOUT_numpad带 2u 键读者可以对照两个文件体会同一矩阵两种装法的差异。5. 旋钮编码器图中标54矩阵之外的特殊成员矩阵图底部左侧画着一个Encoder ─ 54的独立方框。这里的54表示编码器在网格坐标系中位于第 5 行第 4 列的位置但编码器并不是矩阵成员——它不像普通按键那样通过行列扫描读取而是由固件直接读取两根正交信号引脚A/B 相来判断旋转方向与步数。keyboard.json 中的证据encoder: { rotary: [ {pin_a: B1, pin_b: B3} ] }注意对比矩阵列引脚是D3, D2, F5, F6, B2行引脚是D4, D7, E6, B6, B4, B5而编码器使用B1 / B3——三者互不重叠印证了编码器独立接线的设计。固件侧两个官方 keymap 都启用了编码器映射功能rules.mk 中ENCODER_MAP_ENABLE yes并在encoder_map中定义了四个层级的旋转动作#if defined(ENCODER_MAP_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] { [0] { ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, // 层 0音量减 / 音量加 [1] { ENCODER_CCW_CW(RM_HUED, RM_HUEU) }, // 层 1RGB 色相减 / 加 [2] { ENCODER_CCW_CW(RM_SATD, RM_SATU) }, // 层 2RGB 饱和度减 / 加 [3] { ENCODER_CCW_CW(RM_VALD, RM_VALU) } // 层 3RGB 亮度减 / 加 }; #endif其中ENCODER_CCW_CW是 QMK 提供的宏按逆时针动作、顺时针动作的顺序依次传入两个键码。从源码结构看这四层分别对应 keymap 中的层 0数字键层、层 1音乐/灯效层、层 2、层 3配合MO(1)、MO(2)、MO(3)临时层切换键使用。旋钮编码器机制的通用文档可参见 docs/feature_encoders.md。6. 矩阵坐标在固件中的三处实际用途6.1 keymap 中的键位定义LAYOUT_all/LAYOUT_numpad宏的参数顺序由 keyboard.json 中layouts数组的条目顺序决定而每个条目的matrix字段标明其矩阵坐标。自定义键位时只要按图索骥——对照矩阵图找到目标键的坐标再在对应布局宏的相同位置填入键码即可。6.2 Bootmagic 复位键readme.md 明确说明该键盘支持Bootmagic 复位按住矩阵坐标(0,0)的按键即矩阵图左上角的00通常是 Esc / 左上角键再插入 USB 即可进入 bootloader。这正是矩阵图 坐标在刷机流程中的直接应用另外两种进入 bootloader 的方式是 PCB 背面的物理复位键快速按两次与 keymap 中映射的QK_BOOT键码见 keymaps/default/keymap.c 层 3 的[0] QK_BOOT。6.3 RGB 灯效的 LED 坐标矩阵坐标同样贯穿到 RGB 配置中。keyboard.json 的rgb_matrix.layout数组为每颗 LED 指定了matrix坐标与屏幕像素坐标x/y例如{matrix: [2, 4], x: 224, y: 30}、{matrix: [4, 4], x: 224, y: 56}对应 2u 大键区域的 LED 位置。从源码结构看layout数组会按不同物理布局定义不同的 LED 坐标集合这也是官方 keymap 的 readme 中提示不同布局各有独立 LED 位置、建议使用 via 类 keymap 以正确点亮灯珠的原因见 keymaps/default/readme.md 的免责声明。RGB 灯效部分启用了cycle_left_right与cycle_up_down两种动画对应 keymap 层 1 中的CK_DOWN/CK_UP等控制键码。7. 实践如何利用矩阵图排查与自定义结合上述分析矩阵图在日常使用中的价值可以归纳为三个可操作的场景键位自定义想改某颗键的功能先在矩阵图中找到它的坐标如想改7键坐标是[2,0]再在 keymaps/default/keymap.c 的LAYOUT_all(...)对应参数位置替换键码保存后执行make adpenrose/akemipad:default编译、make adpenrose/akemipad:default:flash刷写见 readme.md。矩阵错位排查若按下某键却触发相邻键位优先核对 PCB 上二极管方向是否与keyboard.json的diode_direction: COL2ROW一致若整行/整列失效则检查对应行列引脚行D4/D7/E6/B6/B4/B5列D3/D2/F5/F6/B2的焊接与通路。布局切换同一块 PCB 支持LAYOUT_all全 1u与LAYOUT_numpad2u Plus / Enter / Zero两种物理装法二者共享同一矩阵接线仅需在 keymap 中改用对应的布局宏即可无需改硬件。结语matrix_diagram.md虽只是一张 ASCII 图却是连接 AkemiPad 硬件接线、keyboard.json电气配置与 keymap 键位逻辑的枢纽。本文通过行列坐标、2u 键的单坐标 尺寸参数表达、编码器的独立接线以及 LED 与 Bootmagic 对矩阵坐标的复用完整还原了这张矩阵图的全部信息并给出了可直接落地的排查与自定义方法。后续若需了解 QMK 矩阵扫描与布局系统的更多细节可继续阅读 docs/how_a_matrix_works.md、docs/keymap.md 与 docs/feature_encoders.md。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考