嵌入式固件驱动开发硬件开发【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址https://gitcode.com/GitHub_Trending/qm/qmk_firmware点击查看免费下载matrix_diagram.md是 QMK Firmware 仓库中 Compensator 键盘的矩阵位置参考图它以一张 ASCII 图示的方式把整块键盘每一个物理按键标注为唯一的位置标签并额外标出了 2U 数字键盘键、2.25U/2.75U 大 Shift、10U 空格与分裂空格等特殊键位的落点。阅读本文后你将能够一眼读懂 Compensator 的位置标签规则行组 列位编号把标签与keyboard.json中的 8×16 矩阵坐标、keymap.c中LAYOUT()的参数顺序一一对上并据此安全地定制键位、解读默认固件行为。一、Compensator 键盘与这份矩阵图的作用根据 keyboards/compensator/readme.md 的介绍Compensator 是一块40% 配列的键盘其特点是10U 空格支持同时提供分裂空格选项两块数字键盘左右各一两个导航簇左右各一两列 XT 功能键列左右两端各两枚 F 键主控为ATMEGA32U4支持VIA由于按键数量庞大官方说明需要两套键帽才能填满。在 QMK 生态中矩阵图matrix diagram是键盘固件开发者常备的键位地图。对于 Compensator 这种 120 个物理按键、左右完全对称的怪胎配列单凭keyboard.json里的坐标数组很难直观地看见哪颗键在哪。matrix_diagram.md正是为了解决这个问题而存在它把整块键盘画成一张带标签的图让维护者与玩家可以快速定位任意键位。二、矩阵图阅读规则位置标签体系在展开整张图之前先说明它的标签编码规则这是读懂一切的前提每个标签形如XY两个字符第一个字符是行组号取值范围0–3对应键盘从下往上看……不实际是从上往下的四行物理键区图中共四行按键带第二个字符是列位号取值范围0–9以及A–V其中A10、B11 …… 依此类推V31即每行最多 32 个列位因此标签0M 第 0 行、列位 22标签3C 第 3 行、列位 12。关键点标签的列位号是该视觉行内的顺序编号并不是keyboard.json中的矩阵列号。这一点可以从keyboard.json的LAYOUT数组得到验证——例如第 0 视觉行的 32 个键其矩阵坐标交替来自矩阵行 0 与矩阵行 4见下文第五节。也就是说标签与LAYOUT()宏的参数顺序一一对应keymap.c中LAYOUT(...)的第 N 个参数就是本行第 N 个位置标签对应的键。三、完整矩阵图以下为 keyboards/compensator/matrix_diagram.md 的原始图示原样保留┌───────┐┌───────────────┐┌───────────┐┌───────────────────────────────────────────────────────────┐┌───────────┐┌───────────────┐┌───────┐ │00 │01 ││02 │03 │04 │05 ││06 │07 │08 ││09 │0A │0B │0C │0D │0E │0F │0G │0H │0I │0J │0K │0L │0M ││0N │0O │0P ││0Q │0R │0S │0T ││0U │0V │ ├───┼───┤├───┼───┼───┼───┤├───┼───┼───│├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤├───┼───┼───│├───┼───┼───┼───┤├───┼───┤ │10 │11 ││12 │13 │14 │15 ││16 │17 │18 ││19 │1A │1B │1C │1D │1E │1F │1G │1H │1I │1J │1K │1L ││1M │1N │1O ││1P │1Q │1R │1S ││1T │1U │ ├───┼───┤├───┼───┼───┼───┤└───┼───┼───┘├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┤└───┼───┼───┘├───┼───┼───┼───┤├───┼───┤ │20 │21 ││22 │23 │24 │25 │ │26 │ │27 │28 │29 │2A │2B │2C │2D │2E │2F │2G │2H │2I │2J │2K │ │1L │ │2M │2N │2O │2P ││2Q │2R │ ├───┼───┤├───┼───┼───┼───┤┌───┼───┼───┐├────┴┬──┴┬──┴──┬┴───┴───┴───┴───┴───┴───┴──┬┴───┴┬───┬─┴───┤┌───┼───┼───┐├───┼───┼───┼───┤├───┼───┤ │31 │32 ││33 │34 │35 │36 ││37 │38 │39 ││3A │ │3B │3C │3D │ │3E ││3F │3G │3H ││3I │3J │3K │3L ││30 │31 │ └───┴───┘└───┴───┴───┴───┘└───┴───┴───┘└─────┘ └─────┴───────────────────────────┴─────┘ └─────┘└───┴───┴───┘└───┴───┴───┴───┘└───┴───┘ ┌───────┐ ┌────────┐ ┌──────────┐ ┌───────┐ 2u Numpad Zero │36 │ │27 │ 2.25u LShift 2.75u RShift │2J │ │3I │ 2u Numpad Zero └───────┘ └────────┘ └──────────┘ └───────┘ ┌───┐ ┌───────────────────────────────────────┐ ┌───┐ │ │ 2u │3C │ 10u Space │ │ 2u │02 │ Numpad └───────────────────────────────────────┘ │0T │ Numpad │ │ Plus │ │ Plus ├───┤ ┌─────────┐┌─────┐┌─────────┐ 2.75 1.5 ├───┤ │ │ 2u |3C ||3C ||3C | 2.75 Split │ │ 2u │33 │ Numpad └─────────┘└─────┘└─────────┘ Spacebar │3L │ Numpad │ │ Enter │ │ Enter └───┘ └───┘四、逐区解读一张图看懂整个配列结合默认键位 keymaps/default/keymap.c 第 23 行的注释/* Base - XT:Num:Nav:Alphas:Nav:Num:Xt*/可以把整张图按左右对称的七段结构拆解4.1 左右 XT 列功能键列每行最外侧两键属于 XT 列位置标签默认键位说明00/0U、0VKC_F1/KC_F1、KC_F2第 0 行左右两端10/1T、1UKC_F3/KC_F3、KC_F4第 1 行左右两端20/2Q、2RKC_F5/KC_F5、KC_F6第 2 行左右两端31/30、31KC_F7/KC_F7、KC_F8第 3 行左右两端图中共有四个独立的XT 键区左 2 右 2这正是 readme 中所说的2 XT columns。4.2 双数字键盘Num两块数字键盘各占 4 列左侧数字键盘标签02–05、12–15、22–25、33–36默认依次为PPLS / P7 / P8 / P9、PMNS / P4 / P5 / P6、PENT / P1 / P2 / P3、PMNS / PDOT / P0 / P00右侧数字键盘标签0Q–0T、1P–1S、2M–2P、3I–3L默认依次为P7 / P8 / P9 / PPLS、P4 / P5 / P6 / PMNS、P1 / P2 / P3 / PENT、P00 / P0 / PDOT / PMNS。注意左右数字键盘的布局是镜像对称的左侧PPLS在左上、右侧PPLS在右上这点在改键时最容易踩坑。4.3 双导航簇Nav左侧导航簇06 / 07 / 08INS / HOME / PGUP、16 / 17 / 18DEL / END / PGDN、(空) / 26 / (空)NO / UP / NO、37 / 38 / 39LEFT / DOWN / RIGHT右侧导航簇0N / 0O / 0P、1M / 1N / 1O、2K / (空) / 1L / (空) / 2M中的中间段、3F / 3G / 3H默认键位与左侧镜像对应INS / HOME / PGUP、DEL / END / PGDN、NO / UP / NO、LEFT / DOWN / RIGHT。图上细节提示第 2 行右侧导航簇的中间一枚键在图中写成了1L与本行其他2x前缀标签不一致从序列规律和默认键位该处为KC_UP即第 2 行第 24 个LAYOUT参数看这里更可能是2L的笔误。阅读时请结合行内序列与键位顺序判断。4.4 主键区Alphas主键区横跨四行、14 列标签09–0M、19–1L、27–2J、3A–3E一带默认键位为标准的 QWERTY 字母区TAB / Q / W / E / R / T / Y / U / I / O / P / [ / ] / BSPCCAPS / A / S / D / F / G / H / J / K / L / ; / / EnterLSFT / \ / Z / X / C / V / B / N / M / , / . / / / RSFT。4.5 底部特殊键位图注重点矩阵图最核心的价值在于用底部注释标出了所有非标准尺寸的键位位置标签尺寸默认键位图注说明02/0T2U 高KC_PPLS/KC_PPLS2U Numpad Plus数字键盘加号33/3L2U 高KC_PMNS/KC_PMNS2U Numpad Enter数字键盘回车位36/3I2U 高KC_P00自定义宏2U Numpad Zero数字键盘 0272.25U 宽KC_LSFT2.25u 左 Shift2J2.75U 宽KC_RSFT2.75u 右 Shift3C10U 宽KC_SPC10u 空格整条3B3C3D2.75U 1.5U 2.75UKC_SPC×32.75 1.5 2.75 分裂空格图注明确给出了空格区的两种装配方案10U 单空格一条 10U 空格键帽覆盖3C位置2.75 1.5 2.75合计 7U 的三个键位被整条空格覆盖或按需取舍分裂空格在3C区域拆成2.75U 1.5U 2.75U三段。在默认键位中3A1.5UKC_LCTL与3E1.5UKC_LCTL之间依次为KC_LALT、KC_SPC×3、KC_LALT图注省略了这两枚 Alt 的标签图中为空白但从keyboard.json的宽度定义与keymap.c的参数顺序可以确定它们的位置。五、位置标签与真实矩阵坐标keyboard.json 中的 8×16 矩阵矩阵图给的是视觉标签而固件真正使用的是矩阵坐标。打开 keyboards/compensator/keyboard.json 可以看到硬件层面的定义processor: atmega32u4, bootloader: atmel-dfu, matrix_pins: { rows: [B2, F5, F7, F1, B3, F4, F6, F0], cols: [B0, D4, B7, C7, C6, B6, B5, B4, D7, D6, B1, D5, D3, D2, D1, D0] }, diode_direction: COL2ROW由此可以得到三个硬件事实矩阵规模为8 行 × 16 列 128 个坐标位而实际按键为 120 个存在 8 个空余坐标二极管方向为COL2ROW行列引脚如上所列全部直接映射到 ATMEGA32U4 的 GPIO视觉上的 4 行键区每行都横跨两块矩阵行第 0 视觉行 矩阵行 0 与 4、第 1 视觉行 矩阵行 1 与 5、第 2 视觉行 矩阵行 2 与 6、第 3 视觉行 矩阵行 3 与 7。这一规律可以直接从LAYOUT数组验证例如第 0 视觉行的坐标序列是[0,0],[0,1],[4,0],[4,1],[0,2],[0,3],[4,2],[4,3]…——标签00对应矩阵[0,0]标签02却对应矩阵[4,0]。因此矩阵图标签 ≠ 矩阵坐标二者需要通过LAYOUT数组的顺序换算。keyboard.json还定义了与矩阵直接相关的功能参数bootmagic.matrix [0, 5]Bootmagic 触发键位于矩阵[0,5]即第 0 行第 5 列默认键位为KC_P9indicators.caps_lock E6Caps Lock 指示灯接在 E6 引脚dynamic_keymap.layer_count 3动态键位图支持 3 层配合 VIA 在运行时切换features中启用了bootmagic、mousekey、extrakeynkro为关闭状态。六、默认键位从矩阵图到 keymap.c默认固件位于 keyboards/compensator/keymaps/default/keymap.c它用LAYOUT(...)按先第 0 行 32 键、再第 1 行 31 键、第 2 行 32 键、第 3 行 25 键的顺序定义了三层键位中的前两层第 0 层Base完整映射见上一节逐区解读两枚 2U 数字键盘零位被绑定为自定义键码KC_P00第 1 层MO(1)通过KC_LSFT旁边的MO(1)第 2 行标签2K进入主要提供 F 键KC_F1–KC_F12、KC_NUM与音量控制KC_VOLU/KC_VOLD。KC_P00是默认键位中唯一的自定义键码定义于SAFE_RANGE之上其处理逻辑位于process_record_user()case KC_P00: tap_code(KC_P0); tap_code(KC_P0); return false;也就是说按下 2U 数字键盘零位会连续发送两次KC_P0等效于在数字键盘上快速输入00——这正是 Compensator 为数字输入场景设计的双零技巧也是阅读本文后你可以在自己的键位里复用的模式。七、实践如何用矩阵图定制键位与排查问题结合本文讲解的标签体系定制键位的标准流程如下定位目标键在矩阵图中找到你想改的键记下标签例如想改右侧数字键盘的00键位其标签是3I第 3 行、列位 18确定 LAYOUT 参数序号3I的列位I18即该键是本行LAYOUT()的第 18 个参数从 0 计数若需要矩阵坐标再到keyboard.json的LAYOUT数组里按顺序查出[matrix_row, matrix_col]修改键位编辑keymap.c中对应行的LAYOUT(...)参数或通过 VIA 在运行时写入readme 明确说明该键盘支持 VIA编译烧录make compensator:default烧录时先将 PCB 接入电脑并确认被识别按住 PCB 背面的物理复位键进入 bootloader 模式bootloader 类型为atmel-dfu见keyboard.json随后用 QMK Toolbox 或命令行完成烧录make compensator:keymap:flash排查提示当某个按键行为异常时可以利用矩阵图反查——先确认该键的标签再到keyboard.json核对对应矩阵坐标的引脚与二极管方向COL2ROW即可快速判断是硬件走线问题还是键位映射问题。另外要注意图中1L疑似2L笔误与第 3 行末尾30 / 31序列上应为3M / 3N两处标注瑕疵查阅时以行内标签顺序为准。八、总结matrix_diagram.md虽然只是一张 ASCII 图却是 Compensator 这块40% 怪胎键盘最直接的键位索引它定义了行组 列位的位置标签体系0–3行组、0–9/A–V列位标注了 2U 数字键盘键、2.25U/2.75U 大 Shift、10U 空格与2.75 1.5 2.75分裂空格的全部落点。结合 keyboard.json 的 8×16 矩阵、COL2ROW 引脚定义与 keymap.c 的默认键位任何开发者都可以在这张图的指引下快速完成 Compensator 的键位定制、问题排查与二次开发。赞分享嵌入式固件驱动开发硬件开发【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址https://gitcode.com/GitHub_Trending/qm/qmk_firmware点击查看免费下载相关推荐QMK 矩阵图解读实战AEBoards Constellation Rev3 的硬件矩阵与键位映射全解析QMK 矩阵图解读实战AEBoards Constellation Rev3 的硬件矩阵与键位映射全解析 导读 本篇以 QMK 固件仓库中 AEBoards嵌入式固件驱动开发硬件开发QMK 矩阵图解读AKB OGR 键盘的 5×18 扫描矩阵、键位坐标与多布局映射实战QMK 矩阵图解读AKB OGR 键盘的 5×18 扫描矩阵、键位坐标与多布局映射实战 本篇技术指南以 QMK 固件仓库中 AKB OGR 键盘的矩阵图文档嵌入式固件驱动开发硬件开发QMK 键盘矩阵图解CannonKeys Aella 的 6×16 行列扫描布局与键位映射实战QMK 键盘矩阵图解CannonKeys Aella 的 6×16 行列扫描布局与键位映射实战 导读 本篇文章围绕 QMK Firmware 仓库中 Cann嵌入式固件驱动开发硬件开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK 固件 Compensator 键盘矩阵图全解析：位置标签、特殊键位与 8×16 矩阵映射实战指南
嵌入式固件驱动开发硬件开发【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址https://gitcode.com/GitHub_Trending/qm/qmk_firmware点击查看免费下载matrix_diagram.md是 QMK Firmware 仓库中 Compensator 键盘的矩阵位置参考图它以一张 ASCII 图示的方式把整块键盘每一个物理按键标注为唯一的位置标签并额外标出了 2U 数字键盘键、2.25U/2.75U 大 Shift、10U 空格与分裂空格等特殊键位的落点。阅读本文后你将能够一眼读懂 Compensator 的位置标签规则行组 列位编号把标签与keyboard.json中的 8×16 矩阵坐标、keymap.c中LAYOUT()的参数顺序一一对上并据此安全地定制键位、解读默认固件行为。一、Compensator 键盘与这份矩阵图的作用根据 keyboards/compensator/readme.md 的介绍Compensator 是一块40% 配列的键盘其特点是10U 空格支持同时提供分裂空格选项两块数字键盘左右各一两个导航簇左右各一两列 XT 功能键列左右两端各两枚 F 键主控为ATMEGA32U4支持VIA由于按键数量庞大官方说明需要两套键帽才能填满。在 QMK 生态中矩阵图matrix diagram是键盘固件开发者常备的键位地图。对于 Compensator 这种 120 个物理按键、左右完全对称的怪胎配列单凭keyboard.json里的坐标数组很难直观地看见哪颗键在哪。matrix_diagram.md正是为了解决这个问题而存在它把整块键盘画成一张带标签的图让维护者与玩家可以快速定位任意键位。二、矩阵图阅读规则位置标签体系在展开整张图之前先说明它的标签编码规则这是读懂一切的前提每个标签形如XY两个字符第一个字符是行组号取值范围0–3对应键盘从下往上看……不实际是从上往下的四行物理键区图中共四行按键带第二个字符是列位号取值范围0–9以及A–V其中A10、B11 …… 依此类推V31即每行最多 32 个列位因此标签0M 第 0 行、列位 22标签3C 第 3 行、列位 12。关键点标签的列位号是该视觉行内的顺序编号并不是keyboard.json中的矩阵列号。这一点可以从keyboard.json的LAYOUT数组得到验证——例如第 0 视觉行的 32 个键其矩阵坐标交替来自矩阵行 0 与矩阵行 4见下文第五节。也就是说标签与LAYOUT()宏的参数顺序一一对应keymap.c中LAYOUT(...)的第 N 个参数就是本行第 N 个位置标签对应的键。三、完整矩阵图以下为 keyboards/compensator/matrix_diagram.md 的原始图示原样保留┌───────┐┌───────────────┐┌───────────┐┌───────────────────────────────────────────────────────────┐┌───────────┐┌───────────────┐┌───────┐ │00 │01 ││02 │03 │04 │05 ││06 │07 │08 ││09 │0A │0B │0C │0D │0E │0F │0G │0H │0I │0J │0K │0L │0M ││0N │0O │0P ││0Q │0R │0S │0T ││0U │0V │ ├───┼───┤├───┼───┼───┼───┤├───┼───┼───│├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤├───┼───┼───│├───┼───┼───┼───┤├───┼───┤ │10 │11 ││12 │13 │14 │15 ││16 │17 │18 ││19 │1A │1B │1C │1D │1E │1F │1G │1H │1I │1J │1K │1L ││1M │1N │1O ││1P │1Q │1R │1S ││1T │1U │ ├───┼───┤├───┼───┼───┼───┤└───┼───┼───┘├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┤└───┼───┼───┘├───┼───┼───┼───┤├───┼───┤ │20 │21 ││22 │23 │24 │25 │ │26 │ │27 │28 │29 │2A │2B │2C │2D │2E │2F │2G │2H │2I │2J │2K │ │1L │ │2M │2N │2O │2P ││2Q │2R │ ├───┼───┤├───┼───┼───┼───┤┌───┼───┼───┐├────┴┬──┴┬──┴──┬┴───┴───┴───┴───┴───┴───┴──┬┴───┴┬───┬─┴───┤┌───┼───┼───┐├───┼───┼───┼───┤├───┼───┤ │31 │32 ││33 │34 │35 │36 ││37 │38 │39 ││3A │ │3B │3C │3D │ │3E ││3F │3G │3H ││3I │3J │3K │3L ││30 │31 │ └───┴───┘└───┴───┴───┴───┘└───┴───┴───┘└─────┘ └─────┴───────────────────────────┴─────┘ └─────┘└───┴───┴───┘└───┴───┴───┴───┘└───┴───┘ ┌───────┐ ┌────────┐ ┌──────────┐ ┌───────┐ 2u Numpad Zero │36 │ │27 │ 2.25u LShift 2.75u RShift │2J │ │3I │ 2u Numpad Zero └───────┘ └────────┘ └──────────┘ └───────┘ ┌───┐ ┌───────────────────────────────────────┐ ┌───┐ │ │ 2u │3C │ 10u Space │ │ 2u │02 │ Numpad └───────────────────────────────────────┘ │0T │ Numpad │ │ Plus │ │ Plus ├───┤ ┌─────────┐┌─────┐┌─────────┐ 2.75 1.5 ├───┤ │ │ 2u |3C ||3C ||3C | 2.75 Split │ │ 2u │33 │ Numpad └─────────┘└─────┘└─────────┘ Spacebar │3L │ Numpad │ │ Enter │ │ Enter └───┘ └───┘四、逐区解读一张图看懂整个配列结合默认键位 keymaps/default/keymap.c 第 23 行的注释/* Base - XT:Num:Nav:Alphas:Nav:Num:Xt*/可以把整张图按左右对称的七段结构拆解4.1 左右 XT 列功能键列每行最外侧两键属于 XT 列位置标签默认键位说明00/0U、0VKC_F1/KC_F1、KC_F2第 0 行左右两端10/1T、1UKC_F3/KC_F3、KC_F4第 1 行左右两端20/2Q、2RKC_F5/KC_F5、KC_F6第 2 行左右两端31/30、31KC_F7/KC_F7、KC_F8第 3 行左右两端图中共有四个独立的XT 键区左 2 右 2这正是 readme 中所说的2 XT columns。4.2 双数字键盘Num两块数字键盘各占 4 列左侧数字键盘标签02–05、12–15、22–25、33–36默认依次为PPLS / P7 / P8 / P9、PMNS / P4 / P5 / P6、PENT / P1 / P2 / P3、PMNS / PDOT / P0 / P00右侧数字键盘标签0Q–0T、1P–1S、2M–2P、3I–3L默认依次为P7 / P8 / P9 / PPLS、P4 / P5 / P6 / PMNS、P1 / P2 / P3 / PENT、P00 / P0 / PDOT / PMNS。注意左右数字键盘的布局是镜像对称的左侧PPLS在左上、右侧PPLS在右上这点在改键时最容易踩坑。4.3 双导航簇Nav左侧导航簇06 / 07 / 08INS / HOME / PGUP、16 / 17 / 18DEL / END / PGDN、(空) / 26 / (空)NO / UP / NO、37 / 38 / 39LEFT / DOWN / RIGHT右侧导航簇0N / 0O / 0P、1M / 1N / 1O、2K / (空) / 1L / (空) / 2M中的中间段、3F / 3G / 3H默认键位与左侧镜像对应INS / HOME / PGUP、DEL / END / PGDN、NO / UP / NO、LEFT / DOWN / RIGHT。图上细节提示第 2 行右侧导航簇的中间一枚键在图中写成了1L与本行其他2x前缀标签不一致从序列规律和默认键位该处为KC_UP即第 2 行第 24 个LAYOUT参数看这里更可能是2L的笔误。阅读时请结合行内序列与键位顺序判断。4.4 主键区Alphas主键区横跨四行、14 列标签09–0M、19–1L、27–2J、3A–3E一带默认键位为标准的 QWERTY 字母区TAB / Q / W / E / R / T / Y / U / I / O / P / [ / ] / BSPCCAPS / A / S / D / F / G / H / J / K / L / ; / / EnterLSFT / \ / Z / X / C / V / B / N / M / , / . / / / RSFT。4.5 底部特殊键位图注重点矩阵图最核心的价值在于用底部注释标出了所有非标准尺寸的键位位置标签尺寸默认键位图注说明02/0T2U 高KC_PPLS/KC_PPLS2U Numpad Plus数字键盘加号33/3L2U 高KC_PMNS/KC_PMNS2U Numpad Enter数字键盘回车位36/3I2U 高KC_P00自定义宏2U Numpad Zero数字键盘 0272.25U 宽KC_LSFT2.25u 左 Shift2J2.75U 宽KC_RSFT2.75u 右 Shift3C10U 宽KC_SPC10u 空格整条3B3C3D2.75U 1.5U 2.75UKC_SPC×32.75 1.5 2.75 分裂空格图注明确给出了空格区的两种装配方案10U 单空格一条 10U 空格键帽覆盖3C位置2.75 1.5 2.75合计 7U 的三个键位被整条空格覆盖或按需取舍分裂空格在3C区域拆成2.75U 1.5U 2.75U三段。在默认键位中3A1.5UKC_LCTL与3E1.5UKC_LCTL之间依次为KC_LALT、KC_SPC×3、KC_LALT图注省略了这两枚 Alt 的标签图中为空白但从keyboard.json的宽度定义与keymap.c的参数顺序可以确定它们的位置。五、位置标签与真实矩阵坐标keyboard.json 中的 8×16 矩阵矩阵图给的是视觉标签而固件真正使用的是矩阵坐标。打开 keyboards/compensator/keyboard.json 可以看到硬件层面的定义processor: atmega32u4, bootloader: atmel-dfu, matrix_pins: { rows: [B2, F5, F7, F1, B3, F4, F6, F0], cols: [B0, D4, B7, C7, C6, B6, B5, B4, D7, D6, B1, D5, D3, D2, D1, D0] }, diode_direction: COL2ROW由此可以得到三个硬件事实矩阵规模为8 行 × 16 列 128 个坐标位而实际按键为 120 个存在 8 个空余坐标二极管方向为COL2ROW行列引脚如上所列全部直接映射到 ATMEGA32U4 的 GPIO视觉上的 4 行键区每行都横跨两块矩阵行第 0 视觉行 矩阵行 0 与 4、第 1 视觉行 矩阵行 1 与 5、第 2 视觉行 矩阵行 2 与 6、第 3 视觉行 矩阵行 3 与 7。这一规律可以直接从LAYOUT数组验证例如第 0 视觉行的坐标序列是[0,0],[0,1],[4,0],[4,1],[0,2],[0,3],[4,2],[4,3]…——标签00对应矩阵[0,0]标签02却对应矩阵[4,0]。因此矩阵图标签 ≠ 矩阵坐标二者需要通过LAYOUT数组的顺序换算。keyboard.json还定义了与矩阵直接相关的功能参数bootmagic.matrix [0, 5]Bootmagic 触发键位于矩阵[0,5]即第 0 行第 5 列默认键位为KC_P9indicators.caps_lock E6Caps Lock 指示灯接在 E6 引脚dynamic_keymap.layer_count 3动态键位图支持 3 层配合 VIA 在运行时切换features中启用了bootmagic、mousekey、extrakeynkro为关闭状态。六、默认键位从矩阵图到 keymap.c默认固件位于 keyboards/compensator/keymaps/default/keymap.c它用LAYOUT(...)按先第 0 行 32 键、再第 1 行 31 键、第 2 行 32 键、第 3 行 25 键的顺序定义了三层键位中的前两层第 0 层Base完整映射见上一节逐区解读两枚 2U 数字键盘零位被绑定为自定义键码KC_P00第 1 层MO(1)通过KC_LSFT旁边的MO(1)第 2 行标签2K进入主要提供 F 键KC_F1–KC_F12、KC_NUM与音量控制KC_VOLU/KC_VOLD。KC_P00是默认键位中唯一的自定义键码定义于SAFE_RANGE之上其处理逻辑位于process_record_user()case KC_P00: tap_code(KC_P0); tap_code(KC_P0); return false;也就是说按下 2U 数字键盘零位会连续发送两次KC_P0等效于在数字键盘上快速输入00——这正是 Compensator 为数字输入场景设计的双零技巧也是阅读本文后你可以在自己的键位里复用的模式。七、实践如何用矩阵图定制键位与排查问题结合本文讲解的标签体系定制键位的标准流程如下定位目标键在矩阵图中找到你想改的键记下标签例如想改右侧数字键盘的00键位其标签是3I第 3 行、列位 18确定 LAYOUT 参数序号3I的列位I18即该键是本行LAYOUT()的第 18 个参数从 0 计数若需要矩阵坐标再到keyboard.json的LAYOUT数组里按顺序查出[matrix_row, matrix_col]修改键位编辑keymap.c中对应行的LAYOUT(...)参数或通过 VIA 在运行时写入readme 明确说明该键盘支持 VIA编译烧录make compensator:default烧录时先将 PCB 接入电脑并确认被识别按住 PCB 背面的物理复位键进入 bootloader 模式bootloader 类型为atmel-dfu见keyboard.json随后用 QMK Toolbox 或命令行完成烧录make compensator:keymap:flash排查提示当某个按键行为异常时可以利用矩阵图反查——先确认该键的标签再到keyboard.json核对对应矩阵坐标的引脚与二极管方向COL2ROW即可快速判断是硬件走线问题还是键位映射问题。另外要注意图中1L疑似2L笔误与第 3 行末尾30 / 31序列上应为3M / 3N两处标注瑕疵查阅时以行内标签顺序为准。八、总结matrix_diagram.md虽然只是一张 ASCII 图却是 Compensator 这块40% 怪胎键盘最直接的键位索引它定义了行组 列位的位置标签体系0–3行组、0–9/A–V列位标注了 2U 数字键盘键、2.25U/2.75U 大 Shift、10U 空格与2.75 1.5 2.75分裂空格的全部落点。结合 keyboard.json 的 8×16 矩阵、COL2ROW 引脚定义与 keymap.c 的默认键位任何开发者都可以在这张图的指引下快速完成 Compensator 的键位定制、问题排查与二次开发。赞分享嵌入式固件驱动开发硬件开发【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址https://gitcode.com/GitHub_Trending/qm/qmk_firmware点击查看免费下载相关推荐QMK 矩阵图解读实战AEBoards Constellation Rev3 的硬件矩阵与键位映射全解析QMK 矩阵图解读实战AEBoards Constellation Rev3 的硬件矩阵与键位映射全解析 导读 本篇以 QMK 固件仓库中 AEBoards嵌入式固件驱动开发硬件开发QMK 矩阵图解读AKB OGR 键盘的 5×18 扫描矩阵、键位坐标与多布局映射实战QMK 矩阵图解读AKB OGR 键盘的 5×18 扫描矩阵、键位坐标与多布局映射实战 本篇技术指南以 QMK 固件仓库中 AKB OGR 键盘的矩阵图文档嵌入式固件驱动开发硬件开发QMK 键盘矩阵图解CannonKeys Aella 的 6×16 行列扫描布局与键位映射实战QMK 键盘矩阵图解CannonKeys Aella 的 6×16 行列扫描布局与键位映射实战 导读 本篇文章围绕 QMK Firmware 仓库中 Cann嵌入式固件驱动开发硬件开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考