企业官网建设流程全解析

QMK Firmware 中的 Southern Breeze Rev1：分体键盘的矩阵配置、USB 描述与默认键位全解析

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

本文以 QMK Firmware 仓库中 AfternoonLabs 厂商的 Southern Breeze Rev1 分体键盘为对象，基于 readme.md 与 keyboard.json 的完整配置，逐层拆解这款 6×4 正交分体键盘的矩阵引脚、split 串口/ handedness 配置、bootmagic 设置、布局坐标几何以及默认三层层键位映射，帮助读者掌握在 QMK 数据驱动配置体系中描述一款分体键盘的完整方法。

键盘定位与硬件概述

Southern Breeze Rev1 是一款分体（split）正交列错位（column-staggered）键盘，按 readme 的描述：

• 每侧主键区为6×4 键位（6 列 × 4 行），双半合计 48 键；
• 左侧额外配有6 键宏区（上下两排各 3 键，与主键区错开半格）、4 个方向键（UP / LEFT / DOWN / RIGHT）；
• 每侧拇指区为4 键拇指簇（共 8 键）；
• 全键盘共66 键= 48（主键区）+ 6（宏簇）+ 4（方向键）+ 8（拇指簇）。

仓库中该键盘的 maintainer 为 Eithan Shavit，支持的硬件是 Breeze Rev1 PCB，硬件状态标注为 "Coming soon"。它隶属于 keyboards/afternoonlabs 厂商目录，与同目录下的 breeze、gust、oceanbreeze、summer_breeze 等同族机型共享厂商 VID。

构建方式

在配好 QMK 构建环境后，编译该键盘默认键位的命令为：

make afternoonlabs/southern_breeze/rev1:default

即键盘路径:键位名的通用形式。构建环境的搭建可参考 构建环境入门、Docker 方式 或 make 构建指南，首次接触 QMK 的读者可从 新手指引 入手。

keyboard.json：数据驱动配置逐项解读

rev1/keyboard.json 是该键盘的 QMK 数据驱动配置文件（格式说明见 info.json 参考），以下按字段分组解读。

基本信息与 USB 描述符

{ "keyboard_name": "Southern Breeze", "manufacturer": "AfternoonLabs", "url": "afternoonlabs.com/breeze", "maintainer": "eithanshavit", "usb": { "vid": "0x616C", "pid": "0x0005", "device_version": "0.0.1" }, "processor": "atmega32u4", "bootloader": "caterina" }

• 主控为atmega32u4，烧录器为caterina（ATmega32U4 的经典 DFU 方案，配合 QMK 的QK_BOOT键码或 bootmagic 进入 DFU 模式）；
• USB VID 为厂商注册的0x616C，PID0x0005、设备版本0.0.1标识了这款 Breeze 系列中的具体机型。

功能开关（features）

"features": { "bootmagic": true, "mousekey": false, "extrakey": false, "console": true }

板级默认开启bootmagic（开机按住指定键进入 DFU）与console（串口调试控制台），关闭 mousekey 与 extrakey。需要注意：默认键位目录的 rules.mk 会在该键位层面重新打开这两项（见后文"构建选项"一节），因此最终固件中 MOUSEKEY / EXTRAKEY 实际是启用的——这正是 QMK 三层配置（板级keyboard.json→ 键位rules.mk→ 命令行覆盖）的典型体现。

矩阵引脚与二极管方向

"matrix_pins": { "cols": ["B2", "D1", "D0", "D4", "C6", "D7", "E6", "B4", "B5"], "rows": ["F4", "F5", "F6", "F7", "B1"] }, "diode_direction": "COL2ROW"

• 每半侧为5 行 × 9 列的矩阵（行 F4–F7、B1，列 B2/D1/D0/D4/C6/D7/E6/B4/B5），配合 split 后逻辑矩阵为 10 行 × 9 列，共 90 个矩阵单元，其中 66 个被实际键位使用；
• 二极管方向为COL2ROW（列接行，列线为扫描线、行线读回）。由于 32u4 只有 5 根行线却对应逻辑上的 10 行，从配置结构看，远端（右手）半侧的矩阵是通过 split 串行通道复用同名引脚描述的，这也是 QMK 分体配置中 matrix_pins 只列出一套引脚的惯用写法。

分体（split）配置

"split": { "enabled": true, "handedness": { "pin": "B3" }, "serial": { "pin": "D2" } }

• handedness.pin = B3：每半侧各引出一根 handedness 线并在 PC 端接地，固件通过该引脚电平判断自己是左半还是右半（按 QMK 约定，低电平为左半）；
• serial.pin = D2：两半之间走I2C 串行通道（atmega32u4 上 D2 即 SDA 引脚），远端矩阵扫描结果经该通道回传，无需第二颗 MCU。

这套"单 MCU + I2C + handedness"的组合是 QMK 分体键盘最省料的硬件方案之一。

bootmagic 键位

"bootmagic": { "matrix": [0, 5] }

bootmagic 被绑定在矩阵位置[0, 5]——对应左半主键区第一行第 4 颗物理键，即默认键位中的ESC键。上电时按住它即进入 Caterina DFU 模式，便于硬件层面的救砖刷写。

布局几何：LAYOUT 坐标解读

keyboard.json 的layouts.LAYOUT定义了 66 个键的 1u 网格坐标（渲染参考 布局特性文档），关键几何特征如下：

• 主键区列错位：每半侧 6 列的 x 间距为 1，但 y 值随行、列呈 0 / 0.125 / 0.25 / 0.375 等阶梯变化，例如左半第 0 行各键 y 依次为0.375, 0.375, 0.375, 0.375, 0.125, 0, 0.125, 0.25——中间列下沉、两侧抬升，形成典型的 column-stagger 弧线；
• 左右镜像：右半侧所有键位于 x = 13–18 区间，y 与左半严格对称，中央留 x = 9.25–12.75 的分体间隙；
• 拇指簇为 2u 宽键：4 颗拇指键使用"h": 2（横向跨度 2），且外侧两颗带旋转角"r": 30/"r": -30，使其随拇指区边缘斜向排布，例如：

{"matrix": [4, 0], "x": 9.5, "y": 3.75, "h": 2, "r": 30}, {"matrix": [9, 0], "x": 11.75, "y": 3.75, "h": 2, "r": -30}

• 宏簇与方向键的错位摆放：左半的 6 键宏簇占据矩阵 [0,6..8] 与 [1,6..8]，x = 0–2、y 略高于主键区；方向键中KC_UP单独置于 [2,7]（x=1），KC_LEFT/KC_DOWN/KC_RIGHT则排在 [3,8..6]，构成一个 1×1 + 1×3 的方向键簇。

这套坐标同时服务于 QMK Configurator 的可视化布局渲染与键盘布局图生成。

默认键位：三层结构与拇指区映射

默认键位 keymap.c 定义_MAIN、_LOWER、_RAISE三层，左右各一颗 MO 键切换：

enum layer_names { _MAIN, _LOWER, _RAISE }; #define LOWER MO(_LOWER) #define RAISE MO(_RAISE)

MAIN 层

• 左半：6 键宏簇默认是MINS EQL GRV / LBRC RBRC BSLS（供用户改写为宏），主键区为类 QWERTY 排布，方向键UP（行 2 左侧）、LEFT DOWN RIGHT（行 3 左侧）；
• 右半：纯主键区，右上角是DEL；
• 拇指簇（左 4 + 右 4）：

KC_LCTL, KC_LALT, KC_LGUI, KC_SPC, KC_ENT, RAISE, LOWER, XXXXXXX

即左手 Ctrl/Alt/Gui/Space，右手 Enter/RAISE/LOWER，最右一颗预留为空（XXXXXXX）。

LOWER 层

只占用左侧宏簇与主键区第一行开头：MUTE / VOLD / VOLU（音量控制，依赖 EXTRAKEY）以及QK_BOOT——放在 ESC 的键位上，按下即重启进入 DFU，与 board 级 bootmagic（[0,5]）形成"按键刷写 + 开机刷写"的双保险：

KC_MUTE, KC_VOLD, KC_VOLU, QK_BOOT, _______, ...

RAISE 层

把右半主键区整体变为数字小键盘：顶行PEQL PSLS PAST PMNS、P7 P8 P9 PPLS、P4 P5 P6、P1 P2 P3，拇指区再补P0 / PDOT；左半全部为_______（透明键），保持 MAIN 层行为。

构建选项：键位级 rules.mk

default/rules.mk 覆盖了 board 级默认值并开启优化：

LTO_ENABLE = yes # 链接期优化，体积换功能空间 MOUSEKEY_ENABLE = yes # 允许映射鼠标控制键 EXTRAKEY_ENABLE = yes # 允许音频 & 系统控制键 COMMAND_ENABLE = yes # 调试与配置命令（配合 board 级 console） NKRO_ENABLE = yes # 无限制全键无冲

其中COMMAND_ENABLE与 keyboard.json 中的console: true配套：固件内置的 debug console 提供layer、matrix、bootmagic等运行时命令，可用 USB 串口控制台在线调试层状态与矩阵读数。LTO 注释也说明了动机——编译略慢，但换来的 .hex 体积缩减让小容量 AVR 能装下更多功能。

小结与延伸阅读

• 配置文件：rev1/keyboard.json、rev1/readme.md
• 默认键位：keymaps/default/keymap.c、keymaps/default/rules.mk
• 配置体系：数据驱动配置、info.json 参考、键位映射、层特性
• 同厂商其它机型（共享 VID0x616C的 Breeze 家族）：keyboards/afternoonlabs

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