QMK 固件中的 Viper/Eagle REP 键盘DFU 刷写、Bootmagic 与源码配置全解析【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本篇技术指南以 QMK Firmware 仓库中keyboards/4pplet/eagle_viper_rep键盘固件为主体完整讲解这块兼容 Viper/Eagle V2、V3 的替代 PCB 的目录结构、硬件配置matrix、背光、RGB、编译命令、DFU Bootloader 刷写流程以及 Bootmagic Lite 备用引导方式并结合源码逐项解析其指示灯与层指示实现。读完本文你将掌握如何在 QMK 生态中为 Rev A / Rev B 两个版本编译、刷写固件并能独立阅读键盘固件的配置与底层驱动代码。键盘概述一块为 Viper/Eagle 设计的替代 PCB根据keyboards/4pplet/eagle_viper_rep/readme.md的说明Viper/Eagle REP 是一块面向 Viper 与 Eagle V2、V3 键盘的替代 PCBA alternative PCB for Viper and Eagle V2 and V3由 4pplet作者 Stefan Sundin见各源文件版权声明如 rev_a.c维护。仓库中该键盘固件明确列出Keyboard Maintainer: 4ppletHardware Supported: Viper/Eagle REP Rev A 与 Rev B从目录结构上看该键盘按硬件版本拆分为两个独立固件目标详见下文固件目录结构二者共用一个顶层 readme同时在rev_a/、rev_b/各自目录下也各有一份 readme说明各自版本的编译与刷写要点。固件目录结构keyboards/4pplet/eagle_viper_rep/ ├── readme.md # 顶层说明硬件支持、编译、DFU 与 Bootmagic ├── rev_a/ # Rev A 固件 │ ├── readme.md │ ├── keyboard.json # 数据驱动的键盘配置matrix、features、layouts │ ├── config.h # PWM 背光、WS2812、指示灯引脚等宏 │ ├── halconf.h / mcuconf.h / chconf.h # ChibiOS 与 MCU 层配置 │ ├── rules.mk # 构建规则DFU suffix 通配 │ ├── rev_a.c / rev_a.h │ ├── matrix_diagram.md │ └── keymaps/default/keymap.c └── rev_b/ # Rev B 固件结构与 Rev A 对应两个版本在硬件引脚、背光与指示灯实现上存在差异详见文末对照表但整体构建方式一致。核心硬件配置解析keyboard.jsonQMK 新式键盘固件采用>matrix_pins: { cols: [A0, B1, B0, A4, B5, B4, B3], rows: [A2, A1, B8, A10, C15, A15, B7, B6, C14, C13] }10 行 7 列共提供 70 个矩阵位置足以覆盖 60% 配列并兼容分裂 Backspace、分裂右 Shift、ISO 回车等特殊键位参考 matrix_diagram.md 中 00~96 的矩阵编号示意。特性开关Featuresfeatures块声明了固件启用的功能模块features: { bootmagic: true, mousekey: true, extrakey: true, console: true, command: true, nkro: true, backlight: true, rgblight: true }其中bootmagic: true对应 readme 中Bootmagic lite is enabled by default的说明是无需拆机即可进入刷写模式的硬件基础nkro提供全键无冲backlight与rgblight分别对应 PCB 上的 PWM 背光与 16 颗 WS2812 底灯。背光与 RGB 配置Rev A 的背光与 RGB 配置同样集中在keyboard.jsonbacklight: { pin: A3, levels: 10, breathing: true }, rgblight: { saturation_steps: 8, brightness_steps: 8, led_count: 16, animations: { breathing: true, rainbow_mood: true, rainbow_swirl: true, snake: true, knight: true, christmas: true, static_gradient: true, rgb_test: true, alternating: true, twinkle: true } }, ws2812: { pin: A7, driver: spi }要点解读背光PWM 引脚 A3亮度档位 10 级支持呼吸效果RGB 底灯共 16 颗 WS2812 LED饱和度/亮度调节步进均为 8预设了 10 种动画呼吸、彩虹流动、彩虹旋转、贪吃蛇、骑士、圣诞、静态渐变、测试、交替、闪烁WS2812 驱动方式Rev A 使用SPI 驱动WS2812driver: spi这对应 config.h 中的底层宏WS2812_SPI_DRIVER SPID1、WS2812_SPI_SCK_PIN A5。QMK 扩展配置qmk: { locking: { enabled: true, resync: true } }locking开启后支持键盘锁定Caps Lock/Num Lock/Scroll Lock 状态锁定并在锁定状态变化时自动重同步。底层驱动与构建规则config.h 与 rules.mk数据驱动配置之外Rev A 的 config.h 承担底层硬件细节/* 背光 PWM */ #define BACKLIGHT_PWM_DRIVER PWMD2 #define BACKLIGHT_PWM_CHANNEL 4 /* 底灯 SPI */ #define WS2812_SPI_DRIVER SPID1 #define WS2812_SPI_MOSI_PAL_MODE 0 #define WS2812_SPI_SCK_PIN A5 #define WS2812_SPI_SCK_PAL_MODE 0 /* 指示灯引脚 */ #define LOCK_LIGHTS TRUE #define DISPLAY_LAYERS TRUE #define CAPS_PIN B2 #define NUM_PIN B12 #define SCROLL_PIN B13 #define LAYER_1 B14 #define LAYER_2 B15 #define LAYER_3 A8 #define LAYER_4 A9 #define LAYER_5 B9LOCK_LIGHTS与DISPLAY_LAYERS是两个功能开关宏直接控制 rev_a.c 中指示灯逻辑是否生效LAYER_1~LAYER_5五个引脚用于显示当前激活层与dynamic_keymap.layer_count: 5呼应rules.mk 中有一行值得注意的构建规则# Wildcard to allow APM32 MCU DFU_SUFFIX_ARGS -p FFFF -v FFFF该行将 DFU 后缀的 PID/VID 设为通配符允许同一固件也兼容 APM32 系列 MCU即允许 APM32 替代芯片被识别刷写。状态指示灯与层指示的源码实现rev_a.crev_a.c 是该键盘唯一的板级 C 实现通过重写 QMK 的回调函数驱动两类指示灯锁定状态灯board_init()先把 CAPS/SCROLL/NUM 三个引脚配置为带上拉的输入随后led_update_kb()在锁定状态变化时将对应引脚切换为输出并拉低点亮未锁定时恢复为输入上拉熄灭bool led_update_kb(led_t led_state) { bool res led_update_user(led_state); if(res LOCK_LIGHTS) { if(led_state.caps_lock){ gpio_set_pin_output(CAPS_PIN); gpio_write_pin(CAPS_PIN, 0); } else gpio_set_pin_input_high(CAPS_PIN); /* scroll_lock / num_lock 同理 */ } return res; }层指示灯layer_state_set_kb()调用用户回调后通过setLayerLed()依据get_highest_layer(state)的结果点亮对应LAYER_n引脚实现当前处于第几层就亮第几颗灯的效果setLayerLed的声明位于 rev_a.h。这套实现是典型的 QMK 键盘板级 LED 模式可作为自定义指示灯逻辑的参考范本。默认键位keymaps/default/keymap.c默认键位位于 rev_a/keymaps/default/keymap.c使用LAYOUT_all布局定义了两层第 0 层主层标准 60% ANSI 排列右上角为\KC_BSLS后接KC_GRV右 Shift 侧为MO(1)层切换键底排为Ctrl / Win / Alt / Space / 无 / Alt / Win / Ctrl第 1 层功能层Esc 位映射为QK_BOOT可直接重启进 DFU 刷写模式数字行映射 F1~F12WASD 区域映射方向键其余键位用KC_TRNS透传。注意第 1 层的键位定义遵循LAYOUT_all的顺序若自定义键位时换用其他LAYOUT_60_*布局需同步调整行内键位个数。支持的社区布局Community Layoutsrev_a/keyboard.json的community_layouts声明了 9 种 60% 社区布局方便用户共享键位ANSI 系列60_ansi、60_ansi_split_bs_rshift、60_ansi_tsangan、60_ansi_tsangan_split_bs_rshiftHHKB60_hhkbISO 系列60_iso、60_iso_split_bs_rshift、60_iso_tsangan、60_iso_tsangan_split_bs_rshift同时通过layout_aliases提供别名兼容layout_aliases: { LAYOUT_60_tsangan_hhkb: LAYOUT_60_ansi_tsangan_split_bs_rshift }layouts块内则完整定义了LAYOUT_all与各LAYOUT_60_*的键位物理坐标与矩阵映射配合 matrix_diagram.md 的 ASCII 示意图标注了 2u Backspace、2.25u 左 Shift、2.75u 右 Shift、ISO Enter、Tsangan/HHKB 底排等关键尺寸可以直观理解各布局之间的差异。编译固件阅读顶层 readme.md编译示例为需先完成 QMK 构建环境配置参见 Complete Newbs Guide 与 Make 指南make 4pplet/eagle_viper_rep/rev_a:defaultRev B 对应make 4pplet/eagle_viper_rep/rev_b:default命令格式为make 键盘路径:键位名4pplet/eagle_viper_rep/rev_a指向固件目录含版本子目录default指向keymaps/default/下的键位。若需一并烧录可改用make 4pplet/eagle_viper_rep/rev_a:default:flash详细刷写流程参见 Flashing Guide。构建环境搭建与常见问题可参考 Newbs 构建固件 与 FAQ: Build。进入 DFU Bootloader 刷写Rev A 与 Rev B 的顶层/子目录 readme 给出了完全相同的物理按键引导方式Press and hold the button on the keyboard (the small one on the same side as the MCU) for more than 1 second. The keyboard will then enter bootloader (DFU) mode and its ready to flash the firmware.操作要点按住 PCB 上MCU 同侧的小按钮超过 1 秒键盘进入 DFUDevice Firmware Upgrade模式等待刷写固件注意若按住时间不足键盘只会执行普通复位若想不刷固件直接退出 DFU 模式拔掉 USB 再重新插入即可readme 原文提示 dissconnect the keyboard from your PC and reconnect it。由于主控为 STM32F072 且bootloader配置为stm32-dfu进入该模式后系统会枚举出 DFU 设备之后即可使用 QMK Toolbox 或make ...:flash烧录固件。Bootmagic Lite预刷固件下的备用引导如果键盘已经刷写过固件还有一条无需按钮的替代路径Rev A拔下键盘 USB同时按住Spacebar B插入 USB 等待一秒后松开按键Rev B见 rev_b/readme.md拔下键盘 USB同时按住Esc 键插入 USB 等待一秒后松开。这就是 Bootmagic Lite——QMK 提供的按键组合触发机制。它之所以可用正是因为keyboard.json中features.bootmagic默认开启Bootmagic lite is enabled by default。其原理是在上电阶段扫描指定矩阵位置Rev A 为 Spacebar 与 B 的组合位置Rev B 为 Esc 位置一旦检测到按下便强制进入 Bootloader从而省去拆机按复位键的麻烦。Rev A 与 Rev B 差异对照综合两个版本的 readme、keyboard.json 与 config.h整理差异如下对比项Rev ARev BUSB PID0x00070x0010device_version0.0.10.0.2背光 PWM 引脚A3A6背光 PWM 驱动PWMD2 / 通道 4PWMD3 / 通道 1背光亮度档位10 级6 级WS2812 引脚A7SPI 驱动SCKA5A8普通 GPIO 方式Caps/Num/Scroll 灯config.h 定义CAPS_PINB2 等keyboard.jsonindicators定义caps_lockB1 等层指示灯引脚LAYER_3A8、LAYER_4A9、LAYER_5B9LAYER_3B0、LAYER_4B9、LAYER_5A9Bootmagic 组合键Spacebar BEscfeatures.consoletrue未启用两者共同点包括STM32F072 主控、stm32-dfu引导、10×7 矩阵列引脚不同、16 颗 RGB、5 层动态键位、相同的动画集等。仓库内延伸阅读以下文件是理解该键盘固件的完整素材可继续深入顶层说明keyboards/4pplet/eagle_viper_rep/readme.md硬件配置Rev Arev_a/keyboard.json底层驱动宏Rev Arev_a/config.h板级逻辑实现rev_a/rev_a.c默认键位rev_a/keymaps/default/keymap.c矩阵示意rev_a/matrix_diagram.md构建规则rev_a/rules.mkRev B 硬件配置rev_b/keyboard.json【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考