QMK 固件实战：4pplet waffling80 Rev B TKL 键盘的编译、DFU 刷写与指示灯定制

QMK 固件实战4pplet waffling80 Rev B TKL 键盘的编译、DFU 刷写与指示灯定制【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本篇技术指南围绕 QMK Firmware 仓库中 keyboards/4pplet/waffling80/rev_b/readme.md 所定义的 waffling80 Rev B 键盘展开完整讲解其硬件规格、固件构建命令、STM32 DFU 刷写流程并结合仓库源码剖析其矩阵配置、Bootmagic 复位机制与基于 WS2812 的 Caps Lock / Scroll Lock RGB 指示灯实现。读完本文你可以独立完成该键盘的固件编译与刷写并能读懂其keyboard.json、rules.mk与底层led_update_kb指示灯逻辑进而举一反三地迁移到其他 QMK 键盘。waffling80 是什么面向 a87/a88 兼容的 TKL 客制化 PCBwaffling80 是 4pplet 设计的一款TKLTenkeyless无数字区PCB其设计目标是尝试兼容a87 与 a88两种常见客制化壳体的螺丝孔位与内部空间同时提供多种开关类型与配列选项对应仓库中的rev_a、rev_b、rev_b_ansi三个版本。其 Rev B 版本的固件支持信息记录于 keyboards/4pplet/waffling80/readme.md 与 keyboards/4pplet/waffling80/rev_b/readme.md。键盘维护者Maintainer4ppletStefan Sundin受支持的硬件waffling80 全系Rev A / Rev B / Rev B ANSI主控芯片STM32F072详见下文keyboard.json从仓库结构看三个版本的固件目录各自独立均包含自己的keyboard.json、config.h、rules.mk与.c源码keyboards/4pplet/waffling80/ ├── keymaps/default/keymap.c # 默认键位 ├── rev_a/ # Rev A标准 87 键配列 ├── rev_b/ # Rev BF13 2u Backspace 等多配列 ├── rev_b_ansi/ # Rev B ANSI ├── info.json # 厂商/VID/社区配列声明 └── matrix_diagram.md # 矩阵接线图编译固件从构建环境到产物生成Rev B 的官方编译示例在完成 QMK 构建环境搭建之后为make 4pplet/waffling80/rev_b:default该命令的组成可拆解为三部分组成部分含义4pplet/waffling80/rev_b键盘目标路径对应keyboards/4pplet/waffling80/rev_b/目录default要编译的 keymap 名称对应keymaps/default/make调用仓库根目录 Makefile 驱动的 QMK 构建系统同为 waffling80 家族的另外两个版本使用类似命令make 4pplet/waffling80/rev_a:default make 4pplet/waffling80/rev_b_ansi:default如果你是 QMK 新手可先阅读仓库内 docs/newbs.md完整入门指南与 docs/getting_started_make_guide.mdMake 命令详解完成环境准备构建系统本身基于 builddefs/build_keyboard.mk 等规则文件组织键盘编译流程。硬件定义逐项解析keyboard.json 与 rules.mkRev B 的硬件定义完全由数据驱动配置Data-Driven Configuration承载核心文件是 keyboards/4pplet/waffling80/rev_b/keyboard.json其关键字段如下{ keyboard_name: waffling80 Rev B, usb: { pid: 0x000F, device_version: 0.0.2 }, features: { bootmagic: true, mousekey: true, extrakey: true, nkro: true, rgblight: true }, rgblight: { saturation_steps: 8, brightness_steps: 8, led_count: 2 }, ws2812: { pin: A8 }, matrix_pins: { cols: [B2, B1, B0, A7, A6, A3, B9, B8], rows: [B13, B12, A5, A4, A2, A1, F0, C15, C13, C14, F1, A0] }, diode_direction: COL2ROW, processor: STM32F072, bootloader: stm32-dfu }各字段的技术含义usb.pid与device_versionUSB 产品 ID 为0x000F固件版本为0.0.2VID 统一在 keyboards/4pplet/waffling80/info.json 中声明为0x4444。features开启 Bootmagic、鼠标键mousekey、多媒体/系统键extrakey、NKRO 全键无冲与 RGB 灯效。其中bootmagic: true是下文“按住 Esc 进 DFU”能生效的前提。rgblight与ws2812RGB 灯珠数量为2 颗挂在 PA8 引脚WS2812 数据线饱和度与亮度各 8 级步进。这两颗灯珠正是用来做 Caps Lock / Scroll Lock 指示灯的见第五节。matrix_pins/diode_direction8 列 × 12 行矩阵二极管方向为COL2ROW。全部引脚基于 STM32F072 的 GPIO 命名A1~A7、B0~B13、C13~C15、F0/F1具体按键与矩阵坐标的对应关系可对照 keyboards/4pplet/waffling80/matrix_diagram.md 中的接线图。processor/bootloader主控为 STM32F072引导加载程序为stm32-dfu即通过 USB DFU 协议刷写。Rev B 的 keyboards/4pplet/waffling80/rev_b/rules.mk 内容非常精简只有一行# Wildcard to allow APM32 MCU DFU_SUFFIX_ARGS -p FFFF -v FFFF其作用是放宽 DFU 后缀检查vendor/product 均使用通配符FFFF从而允许使用APM32 等引脚兼容的国产替代 MCU烧录同一份固件若主控确为 STM32则此设置不影响正常刷写。此外keyboards/4pplet/waffling80/rev_b/config.h 定义了WS2812_EXTERNAL_PULLUP告诉 QMK 的 WS2812 驱动外部电路已提供上拉电阻无需在驱动内部再启用内部上拉。进入 BootloaderDFU的两种方式Rev B 文档给出了两条进入 DFU 的路径方式一硬件复位进 DFU适用于所有情况按住 PCB 背面的 reset-header复位排针几秒钟键盘即进入 DFU 模式此时可刷写固件。方式二Bootmagic 热键进 DFU适用于固件已预刷写的板子拔下键盘 USB 线按住 Esc 键的同时插入 USB等待约一秒钟后再松开按键键盘即进入 DFU。方式二的原理正是keyboard.json中bootmagic: true所启用的Bootmagic Lite机制键盘上电瞬间读取矩阵状态若检测到指定按键被按住则跳过正常启动流程并进入 Bootloader。Rev A 的对应热键是Spacebar B见 keyboards/4pplet/waffling80/rev_a/readme.md而 Rev B / Rev B ANSI 统一为Esc 键见 keyboards/4pplet/waffling80/rev_b_ansi/readme.md。这是两款文档在复位细节上的主要差异组装或维修时请注意区分。进入 DFU 后即可使用 QMK 提供的烧写流程刷入编译产物make ...:default:flash前提是系统已安装支持 stm32-dfu 的刷写工具。配列系统与默认键位LAYOUT_all 与社区配列waffling80 在 keyboards/4pplet/waffling80/info.json 中声明了16 种社区配列community layouts涵盖 ANSI/ISO、是否带 F13、是否拆分 Backspace/右 Shift、是否 Tsangan/WKL 底排等组合tkl_ansi, tkl_ansi_split_bs_rshift, tkl_ansi_tsangan, tkl_ansi_tsangan_split_bs_rshift, tkl_f13_ansi, tkl_f13_ansi_split_bs_rshift, tkl_f13_ansi_tsangan, tkl_f13_ansi_tsangan_split_bs_rshift, tkl_iso, tkl_iso_split_bs_rshift, tkl_iso_tsangan, tkl_iso_tsangan_split_bs_rshift, tkl_f13_iso, tkl_f13_iso_split_bs_rshift, tkl_f13_iso_tsangan, tkl_f13_iso_tsangan_split_bs_rshift同时定义了全配列宏LAYOUT_all包含 F13 行、2u Backspace、额外 Fn 键等是默认 keymap 使用的布局。默认键位文件 keyboards/4pplet/waffling80/keymaps/default/keymap.c 定义了 0/1 两层第 0 层主层标准 TKL 键位字母区为标准 ANSI 排布数字行末端是 F13 行Backspace 为 2u 大键底排右侧有MO(1)功能键底部额外两个MO(1)对应“alps dual action switches”ALPS 双动开关的扩展触点。第 1 层功能层几乎全为KC_TRNS透传仅左上角Esc 位置映射为QK_BOOT即在系统运行中按Fn(右下角 MO(1)) Esc也能直接复位进 DFU——这是第三种无需拔线的软件复位方式[1] LAYOUT_all( QK_BOOT, KC_TRNS, ...LAYOUT_all的矩阵坐标到物理位置的映射定义在 keyboards/4pplet/waffling80/info.json 的layouts段中例如Esc对应矩阵[0, 0]、F1对应[1, 0]等配合 keyboards/4pplet/waffling80/matrix_diagram.md 可清晰还原整张键盘的走线。源码级解析用 WS2812 双灯实现 Caps / Scroll Lock 指示Rev B 最有特色的源码是 keyboards/4pplet/waffling80/rev_b/rev_b.c它通过重写led_update_kb()将 2 颗 WS2812 灯珠复用为状态指示灯#ifndef CAPS_LOCK_ENABLE # define CAPS_LOCK_ENABLE 1 #endif #ifndef SCROLL_LOCK_ENABLE # define SCROLL_LOCK_ENABLE 1 #endif // If colors are defined, they will be static. If not defined, color for indicators can be set in VIA. //#define CAPS_LOCK_COLOR HSV_GREEN //#define SCROLL_LOCK_COLOR HSV_GREEN bool led_update_kb(led_t led_state) { bool res led_update_user(led_state); if (SCROLL_LOCK_ENABLE res) { if (led_state.scroll_lock) { #ifdef SCROLL_LOCK_COLOR rgblight_sethsv_at(SCROLL_LOCK_COLOR, 0); #else rgblight_sethsv_at(rgblight_get_hue(), rgblight_get_sat(), rgblight_get_val(), 0); #endif } else { rgblight_sethsv_at(HSV_OFF, 0); } } if (CAPS_LOCK_ENABLE res) { if (led_state.caps_lock) { #ifdef CAPS_LOCK_COLOR rgblight_sethsv_at(CAPS_LOCK_COLOR, 1); #else rgblight_sethsv_at(rgblight_get_hue(), rgblight_get_sat(), rgblight_get_val(), 1); #endif } else { rgblight_sethsv_at(HSV_OFF, 1); } } return res; }这段代码的运行机制挂钩点QMK 的led_update_kb()在 Caps Lock / Num Lock / Scroll Lock 状态变化时被调用必须先调用led_update_user()并保留其返回值res以保证用户层回调链不被破坏。双灯分工第0号灯珠指示Scroll Lock第1号灯珠指示Caps Lock正好对应rgblight.led_count: 2的硬件配置rgblight_sethsv_at(hsv, index)按索引设置单颗灯珠颜色HSV_OFF表示熄灭。两种取色模式若定义CAPS_LOCK_COLOR/SCROLL_LOCK_COLOR如HSV_GREEN指示灯为固定色若未定义则取当前 RGB 全局色调rgblight_get_hue/sat/val指示灯颜色跟随用户设置的灯效主题——注释说明此时颜色可直接通过VIA在运行时调整。可裁剪性CAPS_LOCK_ENABLE/SCROLL_LOCK_ENABLE两个宏默认值为 1允许在编译期单独关闭某颗指示灯功能适合在固件空间紧张或不需要某颗灯时按需裁剪。小结与后续阅读本文以 keyboards/4pplet/waffling80/rev_b/readme.md 为主线完整覆盖了 waffling80 Rev B 的编译命令、两种 DFU 进 Bootloader 方法并通过 keyboard.json、rules.mk、keymap.c 与 rev_b.c 还原了其数据驱动硬件定义、Bootmagic 复位原理与 RGB 指示灯实现。进一步阅读可参考keyboards/4pplet/waffling80/matrix_diagram.md完整矩阵接线图keyboards/4pplet/waffling80/info.json16 种社区配列与全配列定义docs/newbs.mdQMK 完整入门指南docs/getting_started_make_guide.mdMake 命令与刷写说明【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考