QMK 固件实战：AfternoonLabs Gust 3×3 可拆式宏键盘（Rev1）硬件配置与编译指南

QMK 固件实战AfternoonLabs Gust 3×3 可拆式宏键盘Rev1硬件配置与编译指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareGust 是 AfternoonLabs 推出的一款简单小巧的 3×3 宏键盘Macro Board其特色在于底部一整行可以沿板载刻痕掰下从而在 3×3 与 2×3 两种形态之间切换。本文以 QMK Firmware 仓库中 Gust Rev1 的键盘文档 为骨架结合仓库内的 keyboard.json 数据驱动配置 与 默认键位实现 源码逐项解析其硬件矩阵、布局坐标、默认键位与编译刷写流程。读完本文你将掌握该键盘的完整固件工作方式并能够独立修改键位、添加分层功能并重新编译固件。认识 Gust一个可拆行的 3×3 宏键盘根据官方键盘文档Gust 是一个简单的3×3 共 9 键的宏键盘Macro Board底部一行可以沿 PCB 预留的刻痕直接掰下变成2×3 共 6 键的更小形态。它随 AfternoonLabs 的 Breeze 分体式键盘 作为免费赠品附送因此仓库中两者共享同一套 AfternoonLabs 键盘家族命名空间。关键硬件信息均来自 Gust Rev1 readme 与 keyboard.json项目值键盘名称Gust制造商AfternoonLabs固件维护者eithanshavit主控芯片ATMega32U4AVR 架构BootloaderCaterina矩阵结构3 列 × 3 行二极管方向 COL2ROW键位布局单个 LAYOUT9 键Gust 的 Rev1 目录下只有keyboard.json和readme.md两个文件没有传统的config.h、rules.mk等文件——这说明它是一块完全「数据驱动data-driven」配置的键盘全部硬件描述都收敛在 JSON 中由 QMK 的构建系统自动展开这正是 数据驱动配置文档 所描述的现代 QMK 键盘形态。仓库目录结构速览Gust 在仓库中的文件组织如下读者可以按图索骥逐一打开对照keyboards/afternoonlabs/gust/rev1/readme.md官方键盘文档本文骨架keyboards/afternoonlabs/gust/rev1/keyboard.jsonRev1 硬件与布局的完整数据驱动定义keyboards/afternoonlabs/gust/keymaps/default/keymap.c默认键位源码keyboards/afternoonlabs/gust/keymaps/default/readme.md默认键位说明keyboards/afternoonlabs/breeze/rev1/keyboard.json同门 Breeze 的配置可用于横向对比 VID/PID 与矩阵设计keyboard.json 深度解析Gust Rev1 的硬件自述整个 Rev1 的硬件描述都浓缩在 keyboard.json 中下面逐段拆解其含义。USB 标识VID/PID 与家族归属usb: { vid: 0x616C, pid: 0x0002, device_version: 0.0.1 }Gust 使用 VID0x616C、PID0x0002。将 VID 的两个字节拆开看0x61与0x6C恰好对应 ASCII 字符a与l即 AfternoonLabs 的缩写 AL——一个有趣的细节。对比同仓库的 Breeze Rev1 配置PID0x0001可以发现两者共享同一 VID用 PID 区分不同型号这是同一厂商旗下多款键盘的典型 USB 分配方式。功能特性开关features: { bootmagic: false, extrakey: true, mousekey: true, nkro: false }bootmagic: false关闭 Bootmagic 功能即不支持按住指定键上电进入刷写模式或执行键位交换等魔法键操作Breeze 则是true见 其配置extrakey: true启用扩展键媒体键、系统键支持编译时会接入对应 HID 上报代码这是宏键盘常用的能力mousekey: true启用鼠标键功能用键盘模拟鼠标移动与点击nkro: false关闭 N 键无冲NKRO按默认 6KRO 处理——9 键的小矩阵场景下无冲需求有限这是合理的取舍。注意Gust 没有像 Breeze 那样声明console、split、bootmagic.matrix等字段因为它是一块单体的、非分体的简单宏键盘。矩阵引脚与二极管方向matrix_pins: { cols: [D1, D2, D3], rows: [F5, F4, D0] }, diode_direction: COL2ROW3 个列引脚为D1、D2、D33 个行引脚为F5、F4、D0全部为 ATMega32U4 的 I/O 引脚COL2ROW表示二极管从列方向指向行方向即列扫描、行读入这是 QMK 矩阵扫描中最常见的接线方式。QMK 的矩阵扫描逻辑可参考仓库 quantum/matrix.c 等实现会按行列引脚周期性读取电平再结合二极管方向消隐串扰最终得到每个按键的通断状态。对于 3×3 这样的极小矩阵扫描开销几乎可以忽略。主控与 Bootloaderprocessor: atmega32u4, bootloader: caterinaGust 使用 ATMega32U4 主控Bootloader 为 CaterinaArduino Leonardo 同款方案。这意味着刷写固件时需要走 Caterina 协议例如avrdude配合-c caterina或使用 QMK Toolbox 选择对应 bootloader 选项具体刷写方法可参考仓库内的 flashing.md 指南。布局LAYOUT与可拆行设计的坐标证据layouts: { LAYOUT: { layout: [ {matrix: [0, 0], x: 0, y: 0}, {matrix: [0, 1], x: 1, y: 0}, {matrix: [0, 2], x: 2, y: 0}, {matrix: [1, 0], x: 0, y: 1}, {matrix: [1, 1], x: 1, y: 1}, {matrix: [1, 2], x: 2, y: 1}, {matrix: [2, 0], x: 0, y: 3}, {matrix: [2, 1], x: 1, y: 3}, {matrix: [2, 2], x: 2, y: 3} ] } }layout数组中的每个元素将矩阵坐标matrix: [行, 列]映射到键位图坐标x、y。仔细观察可以发现一个值得注意的设计细节第三行matrix 行索引 2的y坐标为 3而不是紧接上一行的 2。从坐标留白可以推断这个y 3的间隔正是为「掰掉底行」的机械刻痕预留的视觉间隙——即使把第三行掰掉前两行2×3 6 键依然是完整且连续的矩阵键位定义无需任何改动即可继续使用。同时该布局只定义了 9 个键位因此它既是一份 3×3 的完整布局也天然兼容 2×3 形态掰下底行后矩阵中仍被扫描的只有前两行而上层键位映射中多出来的第三行键定义不会产生任何影响。默认键位数字 19 的直通映射默认键位位于 keymaps/default/keymap.c全文非常直观#include QMK_KEYBOARD_H enum layer_names { _MAIN, }; const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { [_MAIN] LAYOUT( //┌─────────┬─────────┬─────────┐ KC_1, KC_2, KC_3, //├─────────┼─────────┼─────────┤ KC_4, KC_5, KC_6, //├─────────┼─────────┼─────────┤ KC_7, KC_8, KC_9 //└─────────┴─────────┴─────────┘ ) };代码要点#include QMK_KEYBOARD_H引入 QMK 全部键位与矩阵相关定义enum layer_names定义一个_MAIN层这是 QMK 中最常见的「单层」组织方式为将来扩展多层做好准备const uint16_t PROGMEM keymaps[...]是 QMK 的键位表标准结构键码以PROGMEM存入 Flash避免占用有限的 SRAMLAYOUT(...)宏由 keyboard.json 中的布局定义自动生成按矩阵顺序填入 9 个键码默认键位将 9 个键依次映射为KC_1KC_9与注释画出的 3×3 键位示意图一一对应。由于 keyboard.json 中声明了mousekey与extrakey即使默认键位只用了普通按键你也完全可以在此基础上加入鼠标键KC_MS_UP等或媒体键KC_MPLY、KC_VOLU等来发挥宏键盘的潜力。编译与刷写一条命令跑通默认固件官方文档给出的编译命令在配置好 QMK 构建环境之后执行make afternoonlabs/gust/rev1:default其中afternoonlabs/gust/rev1是键盘路径对应仓库 keyboards/afternoonlabs/gust/rev1:default是键位目标对应 keymaps/default。如果你是第一次接触 QMK建议按以下顺序进行搭建构建环境参考仓库内的 newbs.md 与 newbs_building_firmware.md尤其是其中的环境准备小节安装 QMK CLI 与 AVR 工具链获取固件源码本文所在的 qmk_firmware 仓库即是源码本体无需额外下载编译执行上面的make命令也可以使用 QMK CLI 的等价形式qmk compile -kb afternoonlabs/gust/rev1 -km default详见 cli.md刷写编译产物.hex文件通过 Caterina 协议写入主控具体步骤参考 flashing.md。关于 make 的更多参数如清理、组合命令、指定编译目标等可参阅仓库内的 getting_started_make_guide.md。由于 Gust 是纯数据驱动配置编译系统会从keyboard.json自动生成矩阵、引脚、布局等全部底层定义无需手工维护任何头文件。自定义键位从 9 键到你的专属宏面板Gust 作为宏键盘其核心玩法在于自由定制键位。修改方式与所有 QMK 键盘一致编辑 keymaps/default/keymap.c或新建自己的键位目录。几点实用的进阶思路均有仓库内文档对应增加层Layer仿照_MAIN再定义_FN层用MO(1)、TG(1)等层切换键码在层间切换让 9 个物理键承载更多功能详见 feature_layers.md一键宏Macros通过SEND_STRING或QK_MACRO录制长文本、快捷键序列把 Gust 变成真正的一键办公/一键游戏面板详见 feature_macros.md改键码Keycodes所有可用键码的权威列表见 keycodes.md从普通按键、媒体键到鼠标键一应俱全键位语法LAYOUT宏的填写顺序、多行布局的写法等基础语法参考 keymap.md。需要提醒的是掰下底行2×3 形态后键位代码无需任何修改因为 keyboard.json 中的矩阵与布局定义对 3×3 和 2×3 两种形态天然兼容——这也正是该键盘硬件设计的精妙之处。与 Breeze 的关系同一家族的配置对比Gust 随 Breeze 分体键盘 附送这在两份文档中均有说明。从源码层面看两者的关联非常清晰同厂商同维护者二者制造商均为 AfternoonLabsmaintainer 均为 eithanshavit同 VID 不同 PIDGust 为0x616C:0x0002Breeze 为0x616C:0x0001USB 标识体系一致主控与 Bootloader 一致都是 ATMega32U4 Caterina因此刷写流程完全通用定位互补Breeze 是带 6 键宏簇macro cluster的分体键盘而 Gust 是独立的小型宏板可视为 Breeze 生态中可分离的宏按键扩展。若你手头有 Breeze其 keyboard.json 中关于 split分体串口、左右手检测引脚的配置也是理解 QMK 分体键盘实现的绝佳示例。参考文件清单Gust Rev1 键盘文档Gust Rev1 数据驱动配置Gust 默认键位实现Gust 默认键位说明Breeze Rev1 配置家族对比相关官方指南newbs.md / newbs_building_firmware.md / flashing.md / data_driven_config.md / keymap.md / feature_layers.md / feature_macros.md【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考