QMK 固件中的 AKB Vero 矩阵图全解析：5×15 矩阵坐标与 HHKB 配列实现

QMK 固件中的 AKB Vero 矩阵图全解析：5×15 矩阵坐标与 HHKB 配列实现

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

AKB Vero 是一款采用 HHKB 经典配列思路设计的 60% 机械键盘，以 6U 空格和不对称 blocker 还原 HHKB 的经典手感。本篇指南以 matrix_diagram.md 为核心，逐格讲解 Vero 的矩阵图（Matrix Diagram）坐标系统、各行列坐标与物理按键的对应关系，并结合 keyboard.json 与仓库内 5 份默认键位映射源码，说明 QMK 固件如何通过矩阵坐标驱动 ANSI、ISO、6U 空格、分裂空格等多种配列。读完本文，你将能独立读懂任何 QMK 键盘的矩阵图，并理解从矩阵坐标到实际键位配置的完整链路。

矩阵图原图：AKB Vero 的完整布线

matrix_diagram.md的核心内容即下图——它用 ASCII 字符绘制了 Vero PCB 的 5 行 × 15 列矩阵与物理按键的对应关系。图中的00～4E是矩阵坐标，第一位数字表示行（Row），第二位表示列（Col），采用十六进制计数（0～9、A～E）。

┌───────┐ 2u Backspace │0D │ └───────┘ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │00 │01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │0E │ ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ ┌─────┐ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤ ┌──┴┐2D │ │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2D │ │2C │ │ ├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┤ └───┴────┘ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3C │3D │ ISO Enter └────┴┬──┴┬──┴──┬┴───┴───┴──┬┴───┴───┴──┬┴───┴┬──┴┬─────┴───┘ │41 │42 │45 │47 │4A │4B │ └───┴─────┴───────────┴───────────┴─────┴───┘ ┌────────┐ ┌──────────┐ │30 │ 2.25u LShift 2.75u RShift │3C │ └────────┘ └──────────┘ ┌───┬─────┬───────────────────────┬─────┬───┐ │41 │42 │47 │4A │4B │ 6u Space └───┴─────┴───────────────────────┴─────┴───┘

从图中可以直接读出 Vero 的矩阵规模：5 行（Row 0～4）× 15 列（Col 0～E），最大容量 75 个矩阵交叉点，实际布线覆盖约 64 键的 60% 布局外加若干可切换配列的多余触点。

矩阵坐标系统：行号与列号的编码规则

在 QMK 中，矩阵坐标写作[row, col]或如本图所示的两位十六进制串。以 Vero 为例：

• 第一位数字 = 行号：0～4，对应matrix_pins.rows数组中的下标；
• 第二位数字/字母 = 列号：0～9、A～E（十进制 10～14），对应matrix_pins.cols数组中的下标；
• 0D表示第 0 行、第 13 列；4B表示第 4 行、第 11 列，依此类推。

这一坐标与 keyboard.json 中layouts每个键位条目的"matrix": [row, col]字段一一对应。例如数字行第一个键定义为{"label": "Esc", "matrix": [0, 0]}，即矩阵坐标00；右下角的 Fn 键定义为{"label": "Fn", "matrix": [3, 13]}，即坐标3D。

行坐标分布一览

物理键位与矩阵坐标的映射

数字行与退格键（Row 0）

Row 0 是唯一整行 15 列全部使用的行：00Esc、01～0A数字1～0、0B-、0C=、0D\、0E`。

矩阵图右上角特别标注了2u Backspace位于0D。对照 keyboard.json 的LAYOUT_all，0D在默认布局中映射为\（反斜杠），而LAYOUT_60_true_hhkb系列中0D才是 Backspace——这正是 HHKB 配列“退格键右移一位、顶行多出一个反引号键”的标志性差异，读者可以对比矩阵图顶行与两个布局定义的"label"字段确认。

主键区：ANSI 与 ISO 的切换点（Row 1～2）

• Row 1：10Tab（1.5u）→11～1C字母与符号 →1DBackspace（1.5u）；
• Row 2：20Ctrl（1.75u）→21～2B字母与符号 →2C#（非美式符号键）→2DEnter（ANSI 1.25u）。

矩阵图左下角单独画出了ISO Enter 结构：2C与2D两个触点共同组成 ISO 回车键（高度 2u、宽度 1.25u）。对应地，LAYOUT_60_true_hhkb_iso中 Enter 定义为"matrix": [2, 13], "w": 1.25, "h": 2，即横跨2C/2D两个矩阵点；同时 ISO 配列会在31位置安放\（KC_NUBS），这从 default_true_hhkb_iso/keymap.c 第 20～24 行可以清楚看到。

空格行：6U 空格与分裂空格（Row 4）

Row 4 是配列差异最集中的一行。矩阵图底部用两段示意分别展示了两种状态：

• 6u 空格：41Alt、42GUI（1.5u）、476u 空格、4AGUI（1.5u）、4BAlt，对应LAYOUT_60_true_hhkb中"Space"的"w": 6定义；
• 分裂空格（Split Space）：47位置被拆为45与47两个 3u 空格，对应LAYOUT_60_true_hhkb_split_space与LAYOUT_all中两个"Space"各 3u 的定义，默认键位在 default_true_hhkb_split_space/keymap.c 中写为两个KC_SPC。

此外矩阵图还标注了2.25u LShift（30）与 2.75u RShift（3C）的不对称设计：30只占 1 个矩阵点但物理宽度 2.25u，3C同理宽度 2.75u，这正是 6U 空格配列下左右 Shift 宽度不对称的物理来源。

硬件层面的矩阵实现：引脚与二极管方向

矩阵图描述的是逻辑布线，而其硬件落实在 keyboard.json 的matrix_pins字段：

"matrix_pins": { "cols": ["A13", "B3", "A15", "A14", "B0", "A7", "A6", "A5", "A4", "A3", "A2", "A1", "B7", "B6", "B5"], "rows": ["B15", "B4", "A0", "B13", "B14"] }, "diode_direction": "COL2ROW"

• rows数组含 5 个元素，恰好对应矩阵图的 5 行（B15=Row 0 ～B14=Row 4）；
• cols数组含 15 个元素，对应列0～E（A13=Col 0 ～B5=Col E）；
• diode_direction为COL2ROW，表示每个按键二极管正极接列、负极接行，QMK 扫描时逐行拉低、逐列读入，与矩阵图的行列编号严格对应。

因此矩阵图中任意坐标（如3D）都能反查出物理连接：Row 3 = 引脚B13，Col D = 引脚B6。QMK 的 Bootmagic 键（默认00，即 Esc）也是基于同样的坐标系统定位的——readme.md 中说明“按住矩阵 (0,0) 处按键（通常是左上角 Esc）再插入 USB 即可进入刷写模式”。

五种布局变体与默认键位映射

仓库中为 Vero 提供了 5 个默认键位映射，正好对应矩阵图覆盖的全部配列组合：

以最接近矩阵图 6u 主形态的 default_true_hhkb/keymap.c 为例，第 19～25 行用LAYOUT_60_true_hhkb宏按矩阵坐标逐格填键：

[0] = LAYOUT_60_true_hhkb( KC_ESC, KC_1, KC_2, ..., KC_GRV, // Row 0: 00~0E KC_TAB, KC_Q, ..., KC_BSPC, // Row 1: 10~1D KC_LCTL, KC_A, ..., KC_ENT, // Row 2: 20~2D KC_LSFT, KC_Z, ..., MO(1), // Row 3: 30~3D KC_LALT, KC_LGUI, KC_SPC, // Row 4: 41~4B KC_RGUI, KC_RALT ),

调用宏时实参的书写顺序必须与布局宏在 keyboard.json 中"layout"数组的条目顺序一致（先 Row 0 从左到右，再 Row 1……最后 Row 4），任何一个参数的错位都会导致“按键错乱”，这也是矩阵图对键位开发者最有价值的校对工具。第 2 层（[1]，由MO(1)触发）则将00映射为KC_PWR、01～0C映射为KC_F1～KC_F12，并集中放置媒体与导航键。

从矩阵图到固件构建

确认矩阵与布局无误后，即可按 readme.md 提供的方式构建与刷写。Vero 使用 STM32F411 主控与stm32-dfu引导程序：

# 编译默认键位（对应 LAYOUT_all 分裂空格 + ANSI） make antipode/vero:default # 编译 6U 空格 HHKB 键位 make antipode/vero:default_true_hhkb # 编译并直接刷写（三选一：ISO / 分裂空格 / ISO+分裂空格同理） make antipode/vero:default_true_hhkb:flash

需要注意，该板载 16MHz 晶振的时钟配置位于 board.h（STM32_HSECLK = 16000000U）与 mcuconf.h（STM32_PLLM_VALUE = 8），属于硬件级配置，不涉及矩阵图坐标，但在自行移植布局时无需改动。三种进入引导程序的方式——Bootmagic 复位、PCB 背面物理复位按钮、以及键位中的RESET键——详见 readme.md 的 Bootloader 一节。

小结

AKB Vero 的矩阵图直观呈现了一个 5×15 矩阵如何同时支撑 ANSI、ISO、6U 空格与分裂空格四类关键配列：0D在顶行兼作\/2u Backspace，2C+2D组合出 ISO 回车，45/47切换 6U 与分裂空格，30/3C落实不对称 Shift。理解这张图，就等于同时掌握了 QMK 矩阵坐标编码、keyboard.json 布局宏定义与各 默认键位 之间的映射关系，无论是校对现有键位还是基于 Vero 定制个人配列，都可以从矩阵坐标出发快速定位到对应代码。

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