Artemis Paragon Hotswap 矩阵坐标图全解：从 PCB 物理矩阵到 QMK 布局映射

Artemis Paragon Hotswap 矩阵坐标图全解：从 PCB 物理矩阵到 QMK 布局映射

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

本指南以 QMK 仓库中 Artemis Paragon Hotswap 键盘的矩阵图文档为核心，逐一解读图中每个矩阵坐标（如00、1E、3D）的含义，并结合keyboard.json中的引脚配置、四种 ANSI 布局定义、旋转编码器设置与默认键位实现，帮你建立"PCB 走线 → 矩阵坐标 → 布局宏 → 键位功能"的完整映射认知。读完本文，你既能准确读懂这类矩阵图，也能据此排查键位错乱、自定义布局与接入旋转编码器。

矩阵图：PCB 物理布局坐标总览

原文档以纯 ASCII 图的形式呈现了 Paragon Hotswap 板子的完整矩阵布局，是理解该键盘物理走线的第一手资料。图中每个格子内的两位数即矩阵坐标，格式为"行 + 列"（十六进制列号），原图完整继承如下：

┌───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┐ │00 │ │02 │03 │04 │05 │ │06 │07 │08 │09 │ │0A │0B │0C │0D │ │Rot│ └───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┘ ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ ┌───────┐ │10 │11 │12 │13 │14 │15 │16 │17 │18 │19 │1A │1B │1C │1D │1E │1F │ │1E │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┼───┤ └───────┘ │20 │21 │22 │23 │24 │25 │26 │27 │28 │29 │2A │2B │2C │2D │2F │ ├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┼───┤ │30 │31 │32 │33 │34 │35 │36 │37 │38 │39 │3A │3B │3D │3F │ ├──────┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┼───┤ │40 │42 │43 │44 │45 │46 │47 │48 │49 │4A │4B │4C │4D │4F │ ├────┬───┴┬──┴─┬─┴───┴───┴───┴───┴───┴──┬┴───┴┬──┴──┬───┼───┼───┤ │50 │52 │53 │56 │5A │5B │5C │5D │5F │ └────┴────┴────┴────────────────────────┴─────┴─────┴───┴───┴───┘ ┌─────┬─────┬───────────────────────────┬─────┬─────┐ │50 │52 │56 │5A │5B │ WKL └─────┴─────┴───────────────────────────┴─────┴─────┘

从图上看，Paragon Hotswap 采用6 行（row 0～5）× 16 列（col 0～15）的矩阵规模，物理上位于右上角的旋转编码器（Rot）不占用矩阵行列，而是独立接入。

解读矩阵图：行列坐标约定

矩阵图中每个格子内的坐标是两位十六进制数，遵循"第一位是行号，第二位是列号"的约定：

• 行号取十进制数字0～5，对应 6 个行索引；
• 列号取十六进制0～F，对应 16 个列索引，因此0A、0B、0C、0D实际是列 10～13，1F是第 1 行第 15 列。

对照图中各行的实际键位可以看到典型的 75% / 紧凑全尺寸布局形态：

图中特意用合并格子与注释标注了两个特殊键：右侧1E可装配2u Backspace（对应注释），3D为加宽的回车键；底行下方还单独画了一行WKL变体，说明同一块 PCB 支持两种不同的底行配列（详见后文）。

从矩阵图到引脚：matrix_pins 硬件对应

矩阵坐标只是逻辑编号，真正把坐标落到 MCU 引脚上的配置位于 hotswap/keyboard.json：

"matrix_pins": { "cols": ["F7", "F6", "F5", "F4", "F1", "F0", "C7", "E6", "B0", "B3", "B6", "B5", "B4", "D7", "D4", "D6"], "rows": ["D2", "D1", "D0", "B2", "B1", "C6"] }

数组下标即矩阵索引：rows[0] = D2对应 row 0，cols[0] = F7对应 col 0，以此类推。例如图中00（Esc 键）就是 row 0 / col 0，由D2与F7两个引脚构成的交叉点检测。结合 info.json 中的"diode_direction": "COL2ROW"可知，该 PCB 二极管方向为列→行，QMK 会在每个扫描周期内拉低行、读列。

以下是完整的行列引脚对照（下标即坐标中的行列号）：

主控为atmega32u4（见 info.json），因此全部引脚均为 AVR 平台命名。排查"某个键无反应"或"键位错乱"时，即可用这张表反向定位到具体 MCU 引脚进行硬件测量。

布局族：四种 ANSI 布局与 LAYOUT_all

矩阵图描述的是物理存在性，而 hotswap/keyboard.json 的layouts字段则定义了逻辑上可用的键位排列。Hotswap 版一共声明了四种 ANSI 布局：

布局名中的rwkl指 rotary + WKL，即带旋转编码器且支持 WKL 底行的含义。每种布局的layout数组中，"matrix": [r, c]即矩阵坐标，x/y为可视化坐标，w为键宽（1 单位 = 1u）：

{ "matrix": [1, 14], "x": 13, "y": 1.5, "w": 2 } // LAYOUT_ansi_rwkl 中的 2u Backspace { "matrix": [3, 13], "x": 12.75, "y": 3.5, "w": 2.25 } // 2.25u 回车

LAYOUT_ansi_rwkl中[1,14]（即图中1E）被声明为w: 2的 2u 键，与矩阵图右侧 "2u Backspace" 注释一一对应；而split_bs变体则把1D与1E分别声明为两个 1u 退格键。同级目录的 info.json 还定义了一个容量最大的LAYOUT_all，并设置别名LAYOUT → LAYOUT_all（见 info.json），它额外包含了矩阵图中未标注的[3,12]、[5,4]、[5,8]等坐标，用于支撑更复杂的底行/回车拆分配置。

旋转编码器：Rot 位与 encoder 配置

矩阵图右上角的Rot是唯一的旋转编码器位。硬件接线定义在 hotswap/keyboard.json：

"encoder": { "rotary": [ { "pin_a": "D3", "pin_b": "D5", "resolution": 2 } ] }

即编码器 A、B 相分别接D3、D5，resolution: 2表示每 2 个脉冲计为一步。软件侧，默认键位通过 rules.mk 开启ENCODER_MAP_ENABLE = yes，并在 keymap.c 中定义映射：

#if defined(ENCODER_MAP_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { [0] = { ENCODER_CCW_CW(KC_VOLU, KC_VOLD) } }; #endif

ENCODER_CCW_CW(KC_VOLU, KC_VOLD)分别绑定逆时针（CCW）与顺时针（CW）动作，默认配置为旋钮控制系统音量增减。若想改成页面滚动或自定义功能，直接替换这两个键码即可。

底行变体：标准布局与 WKL 布局

矩阵图最下方单独绘制了一行 WKL 底行，这是理解该键盘底行灵活性最直观的片段。对照两种底行的坐标差异：

WKL（Win Key Less，无 Windows 键）底行只有 5 个键位：50、52、56、5A、5B，对应 LAYOUT_ansi_wkl 中[5,0]（w:1.5）、[5,2]（w:1.5）、[5,6]（w:7）、[5,10]（w:1.5）、[5,11]（w:1.5）；而标准底行则在其基础上多出53、5C、5D等键位。硬件同一块 PCB 通过不同的轴体安装即可切换两种风格，软件侧只需选用对应布局名。

与 Soldered 版矩阵图的对照

同一键盘的焊接版（Soldered）也维护了一份矩阵图 soldered/matrix_diagram.md，与本文主题直接相关，对照阅读可以更清楚地看出热插拔板省略掉的矩阵坐标：

• Soldered 版底行绘制了50、52、53、54、56、58、5A、5B、5C、5D、5F共 11 个键位，比 Hotswap 版图多出54、58两个坐标，分别对应LAYOUT_all中的[5,4]（2.25u）与[5,8]（2.75u），可用于拆分布局；
• Soldered 版在回车行标注了3C/3D的 ISO Enter 示意，而 Hotswap 版图未标注3C（即[3,12]）。

两版图与 info.json 的LAYOUT_all相互印证，可以推断：Paragon PCB 物理上保留了比 Hotswap 矩阵图展示的更多可选矩阵点，LAYOUT_all是这些可能性的"全集"。

实战：如何用矩阵图排查问题与自定义键位

1. Bootmagic 复位与坐标00

readme.md 中说明的第一种进 bootloader 方式是 Bootmagic：按住矩阵 (0,0) 键（即图中00，物理左上角 Esc）再插入 USB。这正是矩阵图最直接的应用——用坐标定位复位键。

2. 编译与烧录

仓库 readme.md 给出了标准构建命令：

make artemis/paragon/hotswap:default # 编译默认键位 make artemis/paragon/hotswap:default:flash # 编译并烧录

3. 自定义键位时对照坐标

默认键位 keymap.c 使用LAYOUT_all宏，按"行分组、坐标从左到右"的顺序填键码。例如首行KC_ESC, KC_F1, ..., KC_F12对应 row 0 的00、02～0D；KC_GRV, KC_1, ...对应 row 1 的10起。当你想修改某个按键时，先在矩阵图中找到它的坐标，再去LAYOUT_all的对应槽位（或改用的LAYOUT_ansi_*布局）替换键码即可；若矩阵图与LAYOUT_all坐标不一致（如3C、54、58），说明该位仅在拆分配列下可用，需同步选用split_bs等对应布局。

总而言之，这份矩阵图是打通 Paragon Hotswap "电路走线—矩阵坐标—QMK 布局"三层的钥匙：读懂它，你就能熟练地在四种 ANSI 布局间切换、自由调整旋转编码器功能，并快速定位键位异常。

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