企业官网建设流程全解析

QMK 矩阵坐标图解：4pplet waffling80（Rev A/B）TKL 键盘矩阵图完全解读

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

本篇技术指南以 QMK 固件仓库中 keyboards/4pplet/waffling80/matrix_diagram.md 为核心，系统解读 4pplet waffling80 这款 TKL（Tenkeyless）PCB 的矩阵坐标图：从两位坐标编码规则、六个物理分区，到 Standard / Tsangan(WKL) / Tsangan Split Space 三种底部配列变体，再到与 info.json 中LAYOUT_all及 16 个社区配列的一一对应关系。读完本文，你将能独立读懂任何 QMK 键盘的 matrix_diagram 文档，并能利用矩阵坐标排查按键失效、自定义键位映射，以及正确选择与你的键帽配列匹配的 LAYOUT 宏。

waffling80 与矩阵图：一张图看懂整块 PCB

waffling80 是 4pplet 推出的 TKL 机械键盘 PCB，根据 keyboards/4pplet/waffling80/readme.md 的描述，它是一块"试图实现 a87 兼容性、支持不同轴体与多种配列选项"的 PCB；而 Rev A 与 Rev B 版本（见 rev_a/readme.md）进一步扩展为"a87 与 a88 兼容"。仓库内共维护三个可独立编译的目标：rev_a、rev_b与rev_b_ansi（对应目录见 rev_a、rev_b、rev_b_ansi）。

matrix_diagram.md正是这块 PCB 的"接线图"——它用 ASCII 艺术图标注出每一个物理键位所对应的矩阵坐标。在 QMK 中，矩阵坐标[row, col]直接决定了固件如何扫描按键：每一行对应一条行扫描线，每一列对应一条列扫描线，键位按下即相当于该行该列交叉点导通。因此这张图是理解 waffling80 固件映射、排查"某个键不响应"问题的第一手资料，也是从矩阵层面区分 F13 行（a88 风格）与标准行（a87 风格）两种顶部配列的关键依据。

矩阵图编码规则：两位坐标 = [row, col]

waffling80 的矩阵图使用两位数字/字母组合表示矩阵坐标，例如20、67、B7。其规则为：

• 第一位（0–9、A、B）表示矩阵行号（row）；
• 第二位（0–7）表示矩阵列号（col）；
• 与 info.json 中每个键位的"matrix": [row, col]字段一一对应。

例如，Esc 在图中标注为00，对应 info.json 中的{"label": "Esc", "matrix": [0, 0], ...}；F13 标注为16，对应{"label": "F13", "matrix": [1, 6], ...}；Pause 标注为37，对应{"label": "Pause", "matrix": [3, 7], ...}。理解了这一规则，整张图就可以翻译成一张"键位 → 矩阵坐标"的对照表。

整个矩阵共使用12 行 × 8 列（行号 0–11，其中 A、B 表示 10、11；列号 0–7），构成一个最多容纳 96 个物理位置的扫描网格，为多配列支持预留了充足空间。

分区逐一解读：六块区域的矩阵坐标

顶部行：F13 行与标准行（a88 / a87 双布局）

矩阵图第一行展示了 F13 变体（a88 风格）的顶部键位：

┌───┐┌───┬───┬───┬───┐┌───┬───┬───┬───┐┌───┬───┬───┬───┐┌───┐┌───┬───┬───┐ │00 ││10 │01 │11 │02 ││12 │03 │13 │04 ││14 │05 │15 │06 ││16 ││07 │17 │37 │ F13 Row └───┘└───┴───┴───┴───┘└───┴───┴───┴───┘└───┴───┴───┴───┘└───┘└───┴───┴───┘

其中00=Esc，10=F1，01=F2，11=F3，02=F4，12=F5，03=F6，13=F7，04=F8，14=F9，05=F10，15=F11，06=F12，16=F13，07=Print Screen，17=Scroll Lock，37=Pause，共 17 个键位，与 info.json 中LAYOUT_all（F13 变体）的顶部行完全吻合。

第二行则是无 F13 的标准 TKL 顶部行（a87 风格）：

┌───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐ ┌───┬───┬───┬───┐┌───┬───┬───┐ │00 │ │01 │11 │02 │12 │ │03 │13 │04 │14 │ │05 │15 │06 │16 ││07 │17 │37 │ └───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘ └───┴───┴───┴───┘└───┴───┴───┘

即00=Esc、01=F1、11=F2、……、16=F12、07/17/37=PrScr/ScrLk/Pause。对比可见：F13 变体与标准变体在矩阵坐标上是两套不同的映射（例如 F1 在 F13 布局中是10，在标准布局中是01），这正是 info.json 中同时定义LAYOUT_all（含 F13）与LAYOUT_tkl_ansi等无 F13 配列的原因，也是这块 PCB 兼容 a87/a88 两种壳体布局的矩阵层面体现。

数字行与 2u Backspace

第三行是数字行：

┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐┌───┬───┬───┐ ┌───────┐ │20 │30 │21 │31 │22 │32 │23 │33 │24 │34 │25 │35 │26 │36 │67 ││27 │57 │97 │ │67 │ 2u Backspace ├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤├───┼───┼───┤ └─┬─────┤

主键区依次为：20=、30=1、21=2、31=3、22=4、32=5、23=6、33=7、24=8、34=9、25=0、35=-、26==、36=\、67=Backspace；右侧导航列为27=Insert、57=Home、97=Page Up。图中还单独标注了 **2u Backspace =67**：也就是说，Backspace 位置在矩阵上固定为[6, 7]，既可以承载标准 2u 单键，也可以与36（`）组合形成 1.5u + 1u 的拆分形式——具体使用哪种，由所选 LAYOUT 宏决定（如LAYOUT_tkl_ansi使用 2u Backspace，而LAYOUT_tkl_ansi_split_bs_rshift等 split_bs 配列则使用拆分的\+ Backspace）。

主键区三行：QWERTY、大写锁定行与 Shift 行

QWERTY 行（Tab 起首）：

├───┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴───┤├───┼───┼───┤ └─┬─────┤ │40 │50 │41 │51 │42 │52 │43 │53 │44 │54 │45 │55 │46 │56 ││47 │77 │B7 │ │ │

40=Tab（1.5u）、50=Q、41=W、51=E、42=R、52=T、43=Y、53=U、44=I、54=O、45=P、55=[、46=]、56=\（1.5u）；导航列为47=Delete、77=End、B7=Page Down。

大写锁定行（Caps Lock 起首）：

├─────┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴┬──┴─────┤├───┼───┼───┤ ┌──┴┐76 │ ISO Enter │60 │70 │61 │71 │62 │72 │63 │73 │64 │74 │65 │75 │76 ││B0 │ │A2 │ │66 │ │

60=Caps Lock（1.75u）、70=A、61=S、71=D、62=F、72=G、63=H、73=J、64=K、74=L、65=;、75='、76=Enter（ANSI 2.25u 或 ISO 竖排 2u 高的上半部分）；导航列还有两个额外的B0（[11, 0]）与A2（[10, 2]）键位，它们在 info.json 中均被定义为 Fn 功能键。

Shift 行（LShift 起首）：

├────┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴────┬───┤└───┼───┼───┘ └───┴────┘ │80 │90 │81 │91 │82 │92 │83 │93 │84 │94 │85 │95 │86 │96 │ │87 │

80=左 Shift、90=\、81=Z、91=X、82=C、92=V、83=B、93=N、84=M、94=,、85=.、95=/、86=右 Shift、96=Fn；上方独立标注87=↑。注意 Fn 键（96）占据右 Shift 右侧的位置，这在 split right shift 配列中用于补足 1.75u 右 Shift 之后的剩余空间。

底部修饰键行与方向键

├────┼───┴┬──┴─┬─┴───┴──┬┴───┼───┴───┴──┬┴───┼───┴┬────┬┴───┤┌───┼───┼───┐ │A0 │B1 │A1 │B2 │A3 │B3 │A4 │B4 │A5 │B5 ││A6 │B6 │A7 │ └────┴────┴────┴────────┴────┴──────────┴────┴────┴────┴────┘└───┴───┴───┘

这是LAYOUT_all的完整底部行：A0=Ctrl、B1=GUI、A1=Alt、B2=Space（2.25u）、A3=Space（1.25u）、B3=Space（2.75u）、A4=Fn、B4=Alt、A5=GUI、B5=Ctrl；导航列为A6=←、B6=↓、A7=→。其中三个 Space 位置（B2/A3/B3）正是"分裂空格"（Split Space）配列的基础；而标准/Tsangan 配列则只使用其中若干位置（见下节）。

ISO Enter 的矩阵实现

矩阵图在右侧专门标注了ISO Enter：它由66（#，矩阵[6, 6]）与76（Enter，矩阵[7, 6]）共同构成——在 ISO 配列中，#键与 2 行高的竖排 Enter 共享列 6，两键在物理上呈上下叠放关系，对应 info.json 中 ISO 配列对#与 Enter（"w": 1.25, "h": 2）的定义。这也解释了为何 ANSI 与 ISO 配列必须分开定义：同一个76位置在 ANSI 下是 2.25u 横向 Enter，在 ISO 下则是 2u 高竖排 Enter 的下半段，键位宽度与高度属性完全不同。

底部配列三种变体：Standard / Tsangan(WKL) / Tsangan Split Space

矩阵图的最后三行给出了底部配列的所有合法组合，关键坐标如下：

┌────────┐ ┌──────────┐ │80 │ 2.25u LShift 2.75u RShift │86 │ └────────┘ └──────────┘

2.25u 左 Shift 与 2.75u 右 Shift：左 Shift 固定使用80（[8, 0]），右 Shift 固定使用86（[8, 6]）。当选择 2.25u/2.75u 宽度时（标准 TKL），矩阵坐标不变，仅键帽宽度变化；当选择 1.75u 右 Shift 时（split rshift），右侧多出的位置由96=Fn 填补。

┌────┬────┬────┬────────────────────────┬────┬────┬────┬────┐ │A0 │B1 │A1 │A3 │A4 │B4 │A5 │B5 │ Standard └────┴────┴────┴────────────────────────┴────┴────┴────┴────┘

• Standard（标准）：A0=Ctrl(1.25u)、B1=GUI(1.25u)、A1=Alt(1.25u)、A3=Space(6.25u)、A4=Alt(1.25u)、B4=GUI(1.25u)、A5=Menu(1.25u)、B5=Ctrl(1.25u)。即"1.25+1.25+1.25 + 6.25 空格 + 1.25×4"的经典 6.25u 空格配列，对应LAYOUT_tkl_ansi等标准配列。

┌─────┬───┬─────┬───────────────────────────┬─────┬───┬─────┐ │A0 │B1 │A1 │A3 │B4 │A5 │B5 │ Tsangan/WKL └─────┴───┴─────┴───────────────────────────┴─────┴───┴─────┘

• Tsangan / WKL：A0=Ctrl(1.5u)、B1=GUI(1u)、A1=Alt(1.5u)、A3=Space(7u)、B4=Alt(1.5u)、A5=Menu(1u)、B5=Ctrl(1.5u)。即"1.5+1+1.5 + 7u 空格 + 1.5+1+1.5"的 Tsangan 底部行，对应LAYOUT_tkl_ansi_tsangan等配列。

┌─────┬───┬─────┬───────────┬───┬───────────┬─────┬───┬─────┐ │A0 │B1 │A1 │B2 │A3 │B3 │B4 │A5 │B5 │ Tsangan/WKL Split Space └─────┴───┴─────┴───────────┴───┴───────────┴─────┴───┴─────┘

• Tsangan/WKL Split Space（分裂空格）：A0=Ctrl(1.5u)、B1=GUI(1u)、A1=Alt(1.5u)、B2=Space(2.25u)、A3=Space(1.25u)、B3=Space(2.75u)、B4=Alt(1.5u)、A5=Menu(1u)、B5=Ctrl(1.5u)。空格被拆成 2.25u + 1.25u + 2.75u 三段，这正是LAYOUT_all及LAYOUT_tkl_f13_ansi_split_space_split_bs_rshift这类配列所采用的底部结构。

从矩阵图到 info.json：LAYOUT 宏与社区配列的对应

矩阵图描述的是物理矩阵层的坐标，而 info.json 中的layouts字段把这些坐标与逻辑键位绑定起来。waffling80 共定义了一个全功能LAYOUT_all以及 16 个标准 TKL 社区配列（community_layouts）：

另外 info.json 中还保留了LAYOUT_tkl_f13_ansi_split_space_split_bs_rshift与LAYOUT_tkl_f13_iso_split_space_split_bs_rshift两个分裂空格专用配列（它们与LAYOUT_all一样包含B2/A3/B3三段空格）。这些配列名在 QMK Configurator 中直接可见，方便用户在不写代码的情况下选用。

LAYOUT_all的特殊之处在于它是唯一包含全部 96 个矩阵槽位的配列：不仅包含三键分裂空格、F13 键，还包含B0/A2两个 Fn 位与97（Page Up）等导航位，供默认键位与高级用户使用。默认键位 keymaps/default/keymap.c 正是以LAYOUT_all编写：主层（layer 0）定义了完整的 ANSI 键位并在底部行使用KC_SPC×3 填满三段空格，同时用MO(1)挂载 Fn 层；Fn 层（layer 1）除QK_BOOT（一键进 DFU）与KC_TRNS透传外全部透明。键位末尾注释 "extra keys for alps dual action switches" 表明，LAYOUT_all中多出的槽位同时服务于 Alps 双动作开关的额外触点。

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

1. 定位按键失效：若某个键按下无反应，先在矩阵图中找到该键的坐标（如 Backspace=67），再到 info.json 的对应配列中确认该坐标确实被映射、且你的 keymap 中该位置不是KC_TRNS或KC_NO。若坐标在矩阵图中存在但在所选 LAYOUT 中缺失（例如选择tkl_ansi后B2/A3三段空格只剩A3一段），说明该键属于其他配列的专属槽位。
2. 选择匹配的 LAYOUT：根据你的键帽配列——是否 F13、是否 ISO、是否 Tsangan、是否分裂空格、是否分裂 Backspace/右 Shift——在 info.json 的community_layouts中挑选对应名称的宏，可保证矩阵坐标与物理键位严格对齐。
3. 理解双布局 F 区：F13 行与标准行的矩阵坐标不同（10与01的位置互换），切勿在两种配列间混用同一份 keymap 中的 F 区顺序。
4. 检查 RGB 指示灯逻辑：Rev A/B 的 rev_a.c 与 rev_b.c 通过led_update_kb()将 Caps Lock / Scroll Lock 状态映射到 RGB 指示位（索引 0、1），默认跟随当前 HSV 值，也可通过定义CAPS_LOCK_COLOR、SCROLL_LOCK_COLOR固定颜色。这提示矩阵图中07/17（PrScr/ScrLk）区域对应的锁键状态会驱动 RGB 指示。

构建与刷写

在搭建好 QMK 构建环境后，可按 readme.md 提供的命令分别编译三个硬件目标：

make 4pplet/waffling80/rev_a:default make 4pplet/waffling80/rev_b:default make 4pplet/waffling80/rev_b_ansi:default

进入 DFU 刷写模式有两种方式：

• Rev A：轻触 PCB 背面的物理复位键，或短接标有 RESET 的复位排针；若已刷入预编译固件，可拔线后同时按住Spacebar 与 B，插线等待约 1 秒再松开。
• Rev B：按住 PCB 背面复位排针数秒；若已刷入固件，可拔线后按住Esc，插线等待约 1 秒再松开（详见 rev_b/readme.md）。

进入 DFU 后即可使用make ...:flash或 QMK Toolbox 烧录固件。

小结

waffling80 的矩阵图本质上是"物理矩阵 → 逻辑键位"的桥梁：两位坐标XY对应[row=X, col=Y]；顶部 F13/标准双布局、2u Backspace（67）、ISO Enter（66+76）、三段分裂空格（B2/A3/B3）以及 Standard / Tsangan / Tsangan Split Space 三种底部行，共同构成了这块 PCB 兼容 a87/a88、覆盖 ANSI/ISO 与 F13 的全部配列空间。将矩阵图与 info.json、默认 keymap 对照阅读，即可完整掌握这块 PCB 的扫描结构，为固件定制与问题排查提供最底层的依据。

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