QMK 键盘固件实战CannonKeys Serenity F13 TKL 编译、刷写与源码解析【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK 固件仓库中 CannonKeys Serenity一款搭载 STM32F072CBT6 的 F13 十键无冲突布局 TKL 键盘的官方说明文档为骨架结合仓库内的数据驱动配置、键位源码与底层 ChibiOS 配置系统讲解该键盘从构建环境准备、固件编译、刷写到 Bootloader 进入方式的完整流程并深入剖析其矩阵、背光、RGB、指示灯与多布局支持的实现细节。读完本文你既能开箱即用地为 Serenity 编译并刷写固件也能以此为范例理解 QMK 数据驱动键盘的配置与底层原理。键盘与硬件概览CannonKeys Serenity 是一把“令人平静的 F13 TKL”键盘由 HoodrowThrillson 设计固件维护者 Andrew Kannan仓库用户名 awkannan硬件支持型号为STM32F072CBT6由 CannonKeys 发售。从仓库中的 keyboard.json 可以看到官方登记的核心标识信息配置项值说明keyboard_nameSerenity键盘名称manufacturerCannon Keys制造商maintainerawkannan固件维护者processorSTM32F072主控型号bootloaderstm32-dfu引导程序类型vid / pid0xCA04 / 0x0017USB 标识device_version0.0.1设备版本号diode_directionCOL2ROW二极管方向列→行Serenity 的独特之处在于功能区比标准 TKL 多出一颗F13按键键盘整体遵循 18 列 × 6 行的矩阵布局完整矩阵示意可参见 matrix_diagram.md其中标注了 2u 退格、ISO 回车、2.25u 左 Shift、2.75u 右 Shift 以及 Tsangan/WKL 底排等可选配列。构建环境准备在编译任何 QMK 固件之前需要先完成构建环境toolchain、依赖库等的搭建。官方仓库在docs/目录下提供了完整的新手引导完全从零开始的入门路径Complete Newbs Guide构建工具链安装说明见docs/下 newbs_building_firmware.md 与 getting_started_make_guide.md刷写与进入引导模式的一般性指引flashing.md环境就绪后即可在本仓库根目录下直接使用make命令构建 Serenity 固件。编译固件原文档给出的编译示例为make cannonkeys/serenity:default其中cannonkeys/serenity是键盘在keyboards/目录下的路径default是键位方案keymap名。该命令会读取键盘目录下的 keyboard.json数据驱动配置与keymaps/default/keymap.c编译生成对应.bin/.hex固件。如果你的键位方案位于keymaps/下的其他子目录例如自定义的mykeymap只需替换目标名make cannonkeys/serenity:mykeymap刷写固件编译后直接烧录到主控的示例命令make cannonkeys/serenity:default:flashmake 键盘:键位:flash会在编译完成后自动进入刷写流程。Serenity 使用STM32 DFU引导程序因此刷写依赖主控进入 DFU 模式rules.mk中还保留了 DFU 后缀参数# Wildcard to allow APM32 MCU DFU_SUFFIX_ARGS -v FFFF -p FFFF从注释可见该配置通过将 DFU 后缀的 vendor/product 通配为FFFF从而兼容 APM32 系列的替代 MCU此为源码注释明示的意图。三种进入 Bootloader 的方式原文档明确指出Serenity 可以通过以下三种方式进入 BootloaderDFU 模式Bootmagic 复位按住矩阵 (0,0) 位置的按键通常是左上角第一颗键或 Esc的同时插入 USB 线。该功能由 keyboard.json 中features: { bootmagic: true }开启对应 QMK 的 Bootmagic 特性可在上电瞬间完成复位进入引导模式。物理复位按键将 PCB 背面的 boot 拨码开关拨到“1”然后按下复位键。这是最稳妥的硬件级方式。键位中的复位键码在默认键位_FN1层中T 键位置已映射为QK_BOOT按下即可直接进入 DFU 模式见下文键位分析。数据驱动配置解析keyboard.jsonSerenity 属于 QMK 的>matrix_pins: { cols: [B1, B2, B10, B11, B12, B14, A8, A9, A10, A3, B0, A2, A1, A7, A0, B4, B6, B7], rows: [A15, B3, B5, A4, A5, F1] }配合diode_direction: COL2ROW即二极管阳极接列、阴极接行这是 QMK 扫描矩阵的标准接法。功能特性开关features: { bootmagic: true, extrakey: true, mousekey: true, nkro: true, backlight: true, rgblight: true }bootmagic开机 Bootmagic 复位能力extrakey系统/媒体扩展键支持mousekey鼠标键支持nkro全键无冲N-Key Rolloverbacklight单色背光rgblightRGB 灯效。背光Backlightbacklight: { breathing: true, levels: 15, pin: A6 }背光由 A6 引脚 PWM 驱动支持呼吸效果亮度共 15 级。底层 PWM 的具体配置位于 config.h#define BACKLIGHT_PWM_DRIVER PWMD3 #define BACKLIGHT_PWM_CHANNEL 1 #define BACKLIGHT_PAL_MODE 1即背光使用定时器 3PWMD3的第 1 通道输出 PWM。对应的 mcuconf.h 中显式启用了该定时器#undef STM32_PWM_USE_TIM3 #define STM32_PWM_USE_TIM3 TRUERGB 灯效RGBLIGHTrgblight: { led_count: 12, hue_steps: 24, saturation_steps: 16, brightness_steps: 16, animations: { alternating: true, breathing: true, christmas: true, knight: true, rainbow_mood: true, rainbow_swirl: true, rgb_test: true, snake: true, static_gradient: true, twinkle: true } }, ws2812: { pin: B15 }板载 12 颗 WS2812 灯珠数据线接 B15色相 24 档、饱和度 16 档、亮度 16 档预置 10 种官方动画alternating、breathing、christmas、knight、rainbow_mood、rainbow_swirl、rgb_test、snake、static_gradient、twinkle均已在数据驱动层开启。WS2812 的底层驱动同样由 config.h 指定为 SPI 模式#define WS2812_SPI_DRIVER SPID2 #define WS2812_SPI_MOSI_PAL_MODE 0 #define WS2812_SPI_SCK_PAL_MODE 0 #define WS2812_SPI_SCK_PIN B13对应 mcuconf.h 启用了 SPI2#undef STM32_SPI_USE_SPI2 #define STM32_SPI_USE_SPI2 TRUE而 halconf.h 则统一开启了 PWM 与 SPI 两个 HAL 模块#define HAL_USE_PWM TRUE #define HAL_USE_SPI TRUE至此形成完整链路halconf.h/mcuconf.h负责在 ChibiOS HAL 层启用 TIM3 与 SPI2 →config.h将背光绑定到 PWMD3/通道 1、将灯带绑定到 SPID2 → 上层由 keyboard.json 声明亮度档位、动画集等用户可见参数。指示灯Indicatorsindicators: { caps_lock: B9, scroll_lock: F0, on_state: 0 }大小写锁定指示灯接 B9、滚动锁定指示灯接 F0on_state: 0表示指示灯为低电平点亮共阳接法。布局支持与社区配列Serenity 除内部完整配列LAYOUT_all外还在community_layouts中登记了四种社区标准配列community_layouts: [ tkl_f13_ansi, tkl_f13_ansi_split_bs_rshift, tkl_f13_iso, tkl_f13_iso_split_bs_rshift ]这四种配列分别对应仓库 layouts/community 下的tkl_f13_ansi标准 ANSI2u 退格、2.25u/2.75u 大 Shifttkl_f13_ansi_split_bs_rshiftANSI 分裂退格Backspace 拆成 Bksp/Del与分裂右 Shift多出一颗 Fntkl_f13_isoISO 回车配列tkl_f13_iso_split_bs_rshiftISO 分裂退格与右 Shift。从 keyboard.json 的布局数据可见各配列的关键差异ANSI 版回车为 2.25u 横条、ISO 版回车为 1.25u×2u 的 L 形w: 1.25, h: 2ISO 版在 [3,12] 处多出#键等。这些布局均复用同一矩阵通过键帽配列映射完成切换方便玩家在 ANSI/ISO 与分裂退格之间自由改造。默认键位分析与 Fn 层默认键位位于 keymaps/default/keymap.c使用LAYOUT_all完整配列定义了两个层_BASE默认层与_FN1功能层。基础层_BASE要点主键区为标准 ANSI 布局字母区、数字区、导航区齐全F13 位置矩阵 [0,14]被映射为KC_MPLY媒体播放/暂停这是 Serenity 默认键位的特色之一右 Shift 右侧多出一颗KC_TRNS透明键为分裂右 Shift 预留底排为 Ctrl / GUI / Alt 6.25u 空格 Alt / Fn / GUI / Ctrl 的对称布局。功能层_FN1通过MO(1)进入集中了灯光与媒体控制[_FN1] LAYOUT_all( KC_TRNS, ..., UG_TOGG, UG_NEXT, UG_HUED, UG_HUEU, UG_SATD, UG_SATU, UG_VALD, UG_VALU, ..., ... QK_BOOT, ..., BL_TOGG, BL_DOWN, BL_UP, KC_VOLU, KC_VOLD, KC_MPLY, KC_MNXT, ... );具体功能归纳如下功能键码说明RGB 开关UG_TOGG打开/关闭 RGB 灯效RGB 模式切换UG_NEXT循环切换动画模式色相调节UG_HUED/UG_HUEU色相减/加共 24 档饱和度调节UG_SATD/UG_SATU饱和度减/加共 16 档亮度调节UG_VALD/UG_VALURGB 亮度减/加共 16 档背光开关BL_TOGG开关 PWM 背光背光亮度BL_DOWN/BL_UP背光减/加共 15 级进入 BootloaderQK_BOOT直接进入 DFU 模式第三种复位方式媒体控制KC_MPLY/KC_MNXT/KC_VOLD/KC_VOLU播放、下一曲、音量减/加值得注意的是功能层在 F 区为 RGB 与背光控制预留了连续按键位且默认键位同时依赖extrakey媒体键与mousekey特性与 keyboard.json 中声明的特性开关一一对应。自定义键位入门如需自定义键位可在keyboards/cannonkeys/serenity/keymaps/下新建目录例如keymaps/mine/创建自己的keymap.c以 默认键位 为模板修改按键映射随后执行make cannonkeys/serenity:mine编译通过后再以:flash后缀烧录。若自定义键位需要用到 ANSI/ISO 等不同配列可改用对应的社区布局宏如LAYOUT_tkl_f13_ansi定义于 keyboard.json 的layouts字段。小结CannonKeys Serenity 是理解 QMK 数据驱动键盘的绝佳案例硬件描述全部收敛于 keyboard.json背光/RGB 的底层外设使能在 config.h、halconf.h 与 mcuconf.h 中完成键位与层逻辑则由 keymap.c 承载。无论是按官方命令直接编译刷写还是在此基础上研究 F13 TKL 的矩阵、灯光与多配列实现这份键盘目录都是值得对照阅读的完整样例。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考