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 05× 16 列col 015的矩阵规模物理上位于右上角的旋转编码器Rot不占用矩阵行列而是独立接入。解读矩阵图行列坐标约定矩阵图中每个格子内的坐标是两位十六进制数遵循第一位是行号第二位是列号的约定行号取十进制数字05对应 6 个行索引列号取十六进制0F对应 16 个列索引因此0A、0B、0C、0D实际是列 10131F是第 1 行第 15 列。对照图中各行的实际键位可以看到典型的 75% / 紧凑全尺寸布局形态行图中坐标对应功能区块row 000、02~0D缺01功能键 F1F12 及右上角编码器位Rotrow 110~1F共 16 键数字区 字母首行1E可作 2u 退格row 220~2D、2F缺2ETab 与字母 QWER 行row 330~3B、3D、3F缺3C、3ECaps 与字母 ASDF 行3D为 2.25u 回车row 440~4C、4D、4F缺4EShift 与字母 ZXCV 行row 550、52、53、56、5A~5F底行含大空格56图中特意用合并格子与注释标注了两个特殊键右侧1E可装配2u Backspace对应注释3D为加宽的回车键底行下方还单独画了一行WKL变体说明同一块 PCB 支持两种不同的底行配列详见后文。从矩阵图到引脚matrix_pins 硬件对应矩阵坐标只是逻辑编号真正把坐标落到 MCU 引脚上的配置位于 hotswap/keyboard.jsonmatrix_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 0cols[0] F7对应 col 0以此类推。例如图中00Esc 键就是 row 0 / col 0由D2与F7两个引脚构成的交叉点检测。结合 info.json 中的diode_direction: COL2ROW可知该 PCB 二极管方向为列→行QMK 会在每个扫描周期内拉低行、读列。以下是完整的行列引脚对照下标即坐标中的行列号行列0123456789101112131415colsF7F6F5F4F1F0C7E6B0B3B6B5B4D7D4D6rowsD2D1D0B2B1C6----------主控为atmega32u4见 info.json因此全部引脚均为 AVR 平台命名。排查某个键无反应或键位错乱时即可用这张表反向定位到具体 MCU 引脚进行硬件测量。布局族四种 ANSI 布局与 LAYOUT_all矩阵图描述的是物理存在性而 hotswap/keyboard.json 的layouts字段则定义了逻辑上可用的键位排列。Hotswap 版一共声明了四种 ANSI 布局布局名特点LAYOUT_ansi_rwklANSI 右上角编码器rotary WKLLAYOUT_ansi_rwkl_split_bs同上但退格键拆分为两个 1u 键LAYOUT_ansi_wklANSI WKL 底行 一体式退格LAYOUT_ansi_wkl_split_bsANSI WKL 底行 拆分退格布局名中的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.jsonencoder: { rotary: [ { pin_a: D3, pin_b: D5, resolution: 2 } ] }即编码器 A、B 相分别接D3、D5resolution: 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) } }; #endifENCODER_CCW_CW(KC_VOLU, KC_VOLD)分别绑定逆时针CCW与顺时针CW动作默认配置为旋钮控制系统音量增减。若想改成页面滚动或自定义功能直接替换这两个键码即可。底行变体标准布局与 WKL 布局矩阵图最下方单独绘制了一行 WKL 底行这是理解该键盘底行灵活性最直观的片段。对照两种底行的坐标差异键位标准底行WKL 底行左 Ctrl5050左 Win/GUI5252左 Alt53—合并进 WKL 对称边空格566.25u567u右 Alt/菜单等5A、5B5A、5BWKLWin 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 复位与坐标00readme.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、020DKC_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考