QMK BIOI G60 矩阵图解指南：解读 5×14 矩阵寻址、键位编号与多套布局映射

QMK BIOI G60 矩阵图解指南：解读 5×14 矩阵寻址、键位编号与多套布局映射

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

本文以 QMK 固件仓库中 keyboards/bioi/g60/matrix_diagram.md 这份矩阵图解文档为主体，完整讲解 BIOI G60（60% 键盘）的键位矩阵：如何解读图中十六进制位置编号、每个编号对应哪一行哪一列的 GPIO 引脚、不同 ANSI/ISO/Tsangan 布局变体分别占用了哪些矩阵位置，以及如何据此正确编写和校验自定义 keymap。读完本文，你可以把任意十六进制编号翻译成行×列坐标与物理按键，并理解LAYOUT_all等宏展开时参数的真实顺序。

1. 文档背景：BIOI G60 在 QMK 中的位置

BIOI G60 是一款受 Cherry G80 系列设计启发的 60% USB/蓝牙双模定制键盘（见 keyboards/bioi/g60/readme.md），由 Basic I/O Instruments（Scott Wei）维护。它在 QMK 仓库中的关键硬件与构建信息如下，全部可在 keyboards/bioi/g60/keyboard.json 中直接查证：

• 处理器：atmega32u4，bootloader 为qmk-dfu（keyboard.json#L65-L66）；
• USB 描述符：VID0x8101，PID0x6080（keyboard.json#L6-L10）；
• 特性开关：bootmagic、extrakey、command、backlight、rgblight、bluetooth均启用（keyboard.json#L11-L19）；
• keyboards/bioi/g60/rules.mk 将主频设为F_CPU = 8000000（8 MHz），并编译 keyboards/bioi/bluetooth_custom.c 作为蓝牙发送实现。

矩阵图解文档（matrix_diagram.md）的作用，是把物理键盘的每个可用键位标注上它在 QMK 键位矩阵（matrix）中的编号。对使用者而言，这张图是编写 keymap、移植布局、排查“按 A 出 S”这类行列错位问题的第一手参照物。更通用的矩阵原理可参阅仓库文档 docs/how_a_matrix_works.md 与 docs/custom_matrix.md。

值得说明的是：同目录的蓝牙版本 keyboards/bioi/g60ble/matrix_diagram.md 内容与 G60 完全一致（同为 5×14 矩阵），说明两款键盘共用同一套键位排布与矩阵拓扑。

2. 完整矩阵图解（原文档内容）

以下代码块完整继承自 keyboards/bioi/g60/matrix_diagram.md，图中每个格子内的十六进制数即该键位的矩阵编号，图右侧与图下方的标注解释了宽键与底部行在不同布局下的形态：

┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ┌───────┐ │00 │01 │02 │03 │04 │05 │06 │07 │08 │09 │0A │0B │0C │0D │49 │ │0D │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤ └─┬─────┤ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │ │ │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤ ┌──┴┐2D │ ISO Enter │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 │3D │3C │ │3D │47 │3C │ 1.75u/1u/1u RShift ├────┼───┴┬──┴─┬─┴───┴───┴───┴───┴───┴───┴───┬┴──┬┴──┬┴──┬───┼───┤ └──────┴───┴───┘ │40 │41 │42 │45 │4A │4B │48 │4C │4D │ └────┴────┴────┴────────────────────────┴───┴───┴───┴───┴───┘ ┌────────┐ ┌─────────────┐ │30 │ 2.25u LShift │3D │ 2.75u RShift └────────┘ └─────────────┘ ┌────┬────┬────┬────────────────────────┬────┬────┬────┬────┐ │40 │41 │42 │45 │4A │4B │4C │4D │ Standard └────┴────┴────┴────────────────────────┴────┴────┴────┴────┘ ┌─────┬───┬─────┬───────────────────────────┬─────┬───┬─────┐ │40 │41 │42 │45 │4B │4C │4D │ Tsangan/WKL/HHKB └─────┴───┴─────┴───────────────────────────┴─────┴───┴─────┘

图中信息可以拆解为三类：

1. 主体网格：5 行 14 列的主矩阵，编号从00到4D；
2. 右侧挂接的“特殊键”：0D（2u Backspace）、2D（ISO Enter 下半部分）、3C（Fn）、3D（1.75u 右 Shift 主体）、47（上方向键）、49（右端 ` 键）等，它们的物理位置不在“行尾”，而是被绘制在对应行列附近以便阅读；
3. 图下方三种底部行形态：标注30（2.25u 左 Shift）与3D（2.75u 右 Shift）的尺寸，并给出底部行在 Standard 布局（40 41 42 45 4A 4B 4C 4D）与 Tsangan/WKL/HHKB 布局（40 41 42 45 4B 4C 4D）下的键位序列差异。

3. 十六进制编号的解码规则：编号 = 行×16 + 列

读懂这张图的核心是编号规则。BIOI G60 的矩阵是5 行（ROWS 0–4）× 14 列（COLS 0–13，十六进制0D），每个位置编号就是“行号（高 4 位）×16 + 列号（低 4 位）”，与 QMK 中MATRIX_ROWS/MATRIX_COLS的寻址方式一致：

图中出现的“越界”编号47、48、49同样是4×16+7/8/9，即第 4 行（底部行）的列 7/8/9，只是它们在物理上被排布到别处，这是 60% 布局压缩底部行时的典型做法：

• 49：画在数字行最右侧，物理位置是右上角的 `（反引号）键；
• 47：画在3C与3D上方，物理位置是右 Shift 左侧的上方向键；
• 48：底部行中4B与4C之间，物理位置是左方向键。

矩阵的行列方向与 GPIO 分配可在 keyboards/bioi/g60/keyboard.json#L29-L33 中核对：

• diode_direction为COL2ROW（列驱动、行读取）；
• 14 根列引脚依次为F6, F7, B3, C7, C6, B6, B5, D5, B4, D7, D6, D4, D1, D0（即列 0–13 的物理引脚顺序）；
• 5 根行引脚依次为E6, B0, F1, F5, F4（即行 0–4）。

这意味着：如果你用万用表或调试工具测到“列引脚 C7 被拉低后行引脚 F1 出现电平”，对应的就是编号12（第 1 行第 2 列，即 W 键）。这个推理链是矩阵图解之外的第二层保障。

4. 各布局变体与矩阵位置的占用关系

keyboards/bioi/g60/keyboard.json#L70-L572 定义了 7 个布局宏，每个键都带"matrix": [行, 列]坐标。把它们与图解编号对照，可以得到“哪些编号被哪个布局使用”的完整答案：

几点关键结论（均可在 JSON 的matrix字段逐一验证）：

1. **49（键）只在带右上角键的布局中出现**：LAYOUT_all与两套 arrow 布局；ISO 布局因右上角被 ISO Enter 占用而不使用该位置（ISO 变体中2D的 Enter 定义带"h": 2`，从数字行右侧向下跨两行）；
2. 31（NUBS 位置）在 ANSI 的 split-backspace 布局中空闲——这些布局里左 Shift 加宽到 2.25u（"w": 2.25），直接覆盖了第 3 行第 1 列的按键位置；而在LAYOUT_all与 ISO 布局中它是独立的 1u 键；
3. 底部行的 Tsangan/WKL/HHKB 变体放弃4A（右 Alt 位置），仅保留40 41 42 45 4B 4C 4D共 7 键，与图解最下方一行的标注完全一致；
4. 45恒为 6.25u（arrow/all/标准布局）或 7u（Tsangan 布局）的空格键，其两侧矩阵位置43/44/46在任何布局中都不作键位使用——这就是图解底部行里42与45之间大片留白的原因。

5. 实战验证：默认 keymap 中 LAYOUT_all 的参数顺序

理解图解的最终目的是写出正确的 keymap。以默认 keymap keyboards/bioi/g60/keymaps/default/keymap.c#L22-L27 的 Base Layer 为例：

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_GRV, KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_UP, MO(1), KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, KC_RGUI, KC_LEFT, KC_APP, KC_RCTL),

对照LAYOUT_all在 keyboard.json#L71-L145 中的matrix坐标，可以确认LAYOUT_all的参数展开顺序并不是严格的列号递增，而是遵循如下顺序（这也是自定义 keymap 时最容易出错的地方）：

1. 第 0 行：00→0D（15 个键），行末追加49（` 键，矩阵 [4,9]）；
2. 第 1 行：10→1D（14 个键）；
3. 第 2 行：20→2B（12 个键），再2C（NUHS，矩阵 [2,12]），最后2D（Enter，矩阵 [2,13]）；
4. 第 3 行：30（LShift）、31（NUBS）、32→3B（Z 到 /），然后顺序是3D（RShift，[3,13]）、47（↑，[4,7]）、3C（Fn，[3,12]）——注意 Fn 排在第 3 行参数的最末位，而不是紧随 / 键之后；
5. 第 4 行：40、41、42、45（空格）、4A（右 Alt）、4B（右 GUI）、48（←，[4,8]）、4C（App，[4,12]）、4D（右 Ctrl）。

用默认 keymap 逐键验证：KC_RSFT, KC_UP, MO(1)三个连续参数分别落在3D、47、3C，而下一行的KC_LEFT, KC_APP, KC_RCTL则分别落在48、4C、4D（keymap.c#L26-L27）。如果你修改 keymap 时把MO(1)写到了/键之后（即3B之后），实际效果会变成 Fn 键触发分层而 / 键失去功能——这正是图解存在的意义。

此外，LAYOUT_all每层共 66 个参数位（15+14+14+14+9），Function Layer 中未使用的键位统一以_______填充（keymap.c#L37-L49），第 1 层用到的UG_TOGG/BL_TOGG/BL_STEP等键码则依赖keyboard.json中开启的 backlight 与 rgblight 特性。

6. 矩阵之外的配套硬件配置

矩阵图解只覆盖键位扫描部分，G60 的完整硬件定义还包括以下与矩阵协同工作的配置（均在 keyboards/bioi/g60/keyboard.json 中）：

• 背光：PWM 背光引脚B7，共 12 档（"levels": 12），默认 keymap 中BL_TOGG/BL_STEP即操作此特性；
• RGB：WS2812 单线 LED 链，数据引脚B1，led_count为 8，支持 breathing、snake、knight、christmas 等 11 种动画（默认 keymap 中UG_TOGG切换模式）；
• Caps Lock 指示灯：引脚F0，on_state: 0表示低电平点亮；
• 键盘锁：keyboards/bioi/g60/config.h#L20-L22 定义了KEYBOARD_LOCK_ENABLE与MAGIC_KEY_LOCK L，配合keyboard.json中"locking": { "enabled": true, "resync": true }生效；
• 布局别名："LAYOUT_60_tsangan_hhkb": "LAYOUT_60_ansi_tsangan_split_bs_rshift"（keyboard.json#L67-L69），在 keymap 中两个名字等价。

编译时使用 keyboards/bioi/g60/readme.md 给出的命令：

make bioi/g60:default

生成的固件使用qmk-dfubootloader 烧录，烧录流程可参考仓库文档 docs/flashing.md。蓝牙版本的构建命令为make bioi/g60ble:default，其矩阵图解与本文所讲完全相同，因此第 3、4、5 节的解码方法同样适用。

7. 小结：使用矩阵图解的核对清单

• 任意编号按行 = 高 4 位、列 = 低 4 位拆解，49、47、48等“看似跳行”的编号都是第 4 行的合法位置，物理位置以图解右侧/上方挂接图为准；
• 行列方向为COL2ROW，列引脚与行引脚的顺序见keyboard.json的matrix_pins，可用于硬件级排错；
• 选择布局宏前先对照第 4 节表格确认该布局是否包含目标编号（例如需要键就必须选LAYOUT_all` 或 arrow 系列；需要 ISO Enter 必须选 ISO 系列）；
• 编写LAYOUT_all时严格按第 5 节的参数顺序落键，尤其注意第 3 行末尾3D → 47 → 3C与第 4 行4B → 48 → 4C → 4D的非顺序排列；
• 空格键（45）两侧与 Tsangan 布局中的4A等位置在多数布局中不存在，不可引用。

以上所有结论均可在 keyboards/bioi/g60/ 目录下的matrix_diagram.md、keyboard.json、keymaps/default/keymap.c、config.h、rules.mk中逐一复核。

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