QMK 键盘固件解析：Ghoul TKL —— Filco TKL 现代化替换 PCB 的构建、刷写与配置指南

QMK 键盘固件解析：Ghoul TKL —— Filco TKL 现代化替换 PCB 的构建、刷写与配置指南

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

Ghoul TKL 是 chillKB 推出的一款面向 Filco TKL 客制化替换 PCB，在本仓库中以 QMK 官方键盘的形式完整落地，配套源码位于 keyboards/chill/ghoul。本指南围绕该键盘的固件实现，讲解如何构建与刷写固件、通过三种方式进入 Bootloader，并逐项剖析keyboard.json数据驱动配置、默认键位以及 PWM 背光与指示灯在 STM32F072 平台上的底层实现。读完本文，你将能够独立完成 Ghoul TKL 固件的编译烧录、理解其矩阵与布局定义，并在此基础上进行键位二次定制。

硬件定位与项目背景

根据 键盘 README 的描述，Ghoul TKL 是一块 Filco TKL 键盘的现代化替换 PCB，核心卖点包括：

• PCB 安装（PCB-mount）稳定器支持：相比原厂 Filco 的钢板安装稳定器，PCB 安装稳定器在更换键帽与手感调校上更灵活；

• 多种流行替代布局：通过 QMK 的社区布局（community layouts）机制，一块 PCB 即可覆盖多种主流 TKL 键位方案；

• 轴体背光灯珠（In-switch backlight LEDs）支持：可为每个轴位提供 PWM 驱动的背光。

• 键盘维护者（Maintainer）：chillKB

• 硬件支持：Ghoul TKL PCB

• 控制器：STM32F072（ARM Cortex-M0 系列，见 keyboard.json）

构建与刷写：两条核心命令

在完成 QMK 构建环境准备后（参考仓库中的 构建环境说明 与 Make 指南，新手可从 Complete Newbs Guide 起步），编译默认键位固件的命令为：

make chill/ghoul:default

刷写固件到键盘的命令为：

make chill/ghoul:default:flash

其中chill/ghoul是键盘的 QMK 目标名（对应keyboards/chill/ghoul目录），:default是键位目标（对应keymaps/default），:flash指示 QMK 在编译完成后自动调用刷写工具。由于该键盘的 Bootloader 类型为stm32-dfu（见 keyboard.json），刷写流程会使用 STM32 的 DFU 协议（如 dfu-util）完成固件烧录。更通用的刷写说明可参见 flashing 指南。

进入 Bootloader 的三种方式

Bootloader 是刷写固件的入口。Ghoul TKL 提供了三条进入路径，任选其一即可：

1. Bootmagic reset（魔术复位）：按住左上角按键（通常为 Esc）的同时插入 USB 线缆。该功能由keyboard.json中features.bootmagic开启；
2. 物理复位按钮：按住 PCB 背面的 Boot 按钮，再轻按 Reset 按钮；
3. 键位触发：如果当前键位中包含QK_BOOT键码，按下该键即可复位进入 Bootloader。默认键位未直接放置QK_BOOT，但读者可依据 keymap 文档 自行将任意键映射为QK_BOOT。

其中方式 1 是 QMK 的 Bootmagic 特性（可通过键位或配置关闭），方式 2 依赖 PCB 上的实体按键，方式 3 则适合在固件已经可用时免开壳刷写。

keyboard.json：数据驱动的硬件描述

Ghoul TKL 的硬件信息全部集中在 keyboard.json 中，采用 QMK 的>"diode_direction": "COL2ROW", "matrix_pins": { "cols": ["A10", "A9", "A8", "B15", "B14", "B13", "B12", "B11", "B10", "B2", "B1", "B0", "A6", "A5", "A15", "A1", "A0"], "rows": ["B7", "B9", "B8", "A7", "A4", "A3"] }

• 采用COL2ROW扫描方向：列（COL）作为驱动输出、行（ROW）作为读入；
• 矩阵规模为6 行 × 17 列（6 个 row 引脚、17 个 col 引脚），共可容纳 102 个物理键位，为 TKL（约 87–88 键）及各替代布局留足余量。

背光与指示灯

"backlight": { "driver": "pwm", "pin": "B3" }, "indicators": { "caps_lock": "B4", "on_state": 0, "scroll_lock": "B6" }

• 背光采用PWM 驱动，输出引脚为B3，可对轴体灯珠做无级亮度调节；
• Caps Lock 指示灯接B4、Scroll Lock 接B6，on_state: 0表示低电平点亮（即引脚输出 0 时 LED 亮起）。

USB 标识与控制器

"usb": { "device_version": "1.0.0", "pid": "0xFC87", "vid": "0xC01D" }, "processor": "STM32F072", "bootloader": "stm32-dfu"

• VID 为0xC01D、PID 为0xFC87、设备版本号1.0.0，用于操作系统识别设备；
• 主控为 STM32F072，Bootloader 类型stm32-dfu，配合make chill/ghoul:default:flash即可完成 DFU 烧录。

特性开关

"features": { "backlight": true, "bootmagic": true, "extrakey": true, "mousekey": true, "nkro": true }

backlight启用背光、bootmagic启用魔术复位、extrakey提供多媒体/系统键支持（默认键位中的音量与媒体键依赖它）、mousekey启用鼠标键、nkro启用 N 键无冲（对游戏用户尤其重要）。

布局系统：一个 PCB 覆盖四种 TKL 方案

keyboard.json中声明了 4 个社区布局（community layouts）：

tkl_ansi tkl_ansi_split_bs_rshift tkl_ansi_tsangan tkl_ansi_tsangan_split_bs_rshift

分别对应：

此外还定义了一个便捷别名：

"layout_aliases": { "LAYOUT_all": "LAYOUT_tkl_ansi_split_bs_rshift" }

即LAYOUT_all实际指向LAYOUT_tkl_ansi_split_bs_rshift，这一“全兼容”布局在矩阵层面对所有物理焊盘做了完整映射，是默认键位的载体。

每个布局都以 JSON 数组描述键的物理位置：matrix字段给出该键对应的行/列坐标，x/y给出以 1u 为单位的物理坐标，w/h表示键帽宽度/高度。例如LAYOUT_tkl_ansi中空格行：

{"matrix": [5, 6], "x": 3.75, "y": 5.5, "w": 6.25}

表示 6.25u 空格；而 Tsangan 布局则改为：

{"matrix": [5, 6], "x": 4, "y": 5.5, "w": 7}

即 7u 空格。这种声明式布局让社区内的 TKL 键位方案可以跨键盘直接复用。

默认键位解析

默认键位文件位于 keymaps/default/keymap.c，使用LAYOUT_all定义了两个功能层：

层 0（默认层）：标准 ANSI TKL 布局，F 区、编辑区、方向键齐全；值得注意的是第二行存在KC_BSPC, KC_BSPC两个退格，表明 PCB 支持分裂退格（物理上放两枚 1u 键帽）；右 Shift 位置放置了MO(1)，说明支持分裂右 Shift，将 2.25u 右 Shift 拆成 1.75u Shift 与 1u 的层切换键。底行为标准 WKL 式六键：KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, MO(1), KC_RGUI, KC_RCTL。

层 1（按住MO(1)进入）：集中了媒体与系统控制，以及背光调节：

_______, KC_VOLU, KC_VOLD, KC_MUTE, _______, KC_MPRV, KC_MPLY, KC_MSTP, KC_MNXT, ... BL_TOGG, BL_UP, BL_DOWN, ...

• 音量加减、静音、上一曲/播放/停止/下一曲等多媒体键；
• BL_TOGG（背光开关）、BL_UP/BL_DOWN（背光亮度加减）——这三枚键正是由features.backlight与 PWM 背光驱动支撑的。

_______为透传占位符，表示沿用上一层对应键位。如需深入了解层机制，可参考 feature_layers；自定义键位的写法见 keymap 文档。

底层原理：PWM 背光在 STM32F072 上的实现

除了数据驱动的keyboard.json，该键盘还保留了四个 ChibiOS/硬件配置文件，用于满足 PWM 背光对定时器的特殊要求：

config.h：背光 PWM 通道绑定

config.h 中：

#define BACKLIGHT_PWM_DRIVER PWMD2 #define BACKLIGHT_PWM_CHANNEL 2 #define BACKLIGHT_PAL_MODE 2

• BACKLIGHT_PWM_DRIVER PWMD2：使用 STM32 的 PWM 驱动 2（对应定时器 TIM2）；
• BACKLIGHT_PWM_CHANNEL 2：占用 TIM2 的第 2 通道；
• BACKLIGHT_PAL_MODE 2：B3 引脚复用为 TIM2 通道 2 输出的 alternate function 编号为 2（STM32F072 的引脚复用表）。

三者配合，将定时器输出映射到 B3 引脚，从而驱动轴体灯珠。

halconf.h 与 mcuconf.h：使能 PWM 外设并分配定时器

halconf.h 开启 ChibiOS HAL 的 PWM 模块：

#define HAL_USE_PWM TRUE

mcuconf.h 进一步分配定时器资源：

#undef STM32_PWM_USE_TIM2 #define STM32_PWM_USE_TIM2 TRUE #undef STM32_ST_USE_TIMER #define STM32_ST_USE_TIMER 14

• 显式启用TIM2供 PWM 使用（与config.h中的PWMD2对应）；
• 将系统节拍定时器（system tick）改用TIM14，从而把 TIM2 完整让渡给背光，避免定时器资源冲突。

chconf.h：系统节拍配置

chconf.h 中：

#define CH_CFG_ST_RESOLUTION 16 #define CH_CFG_ST_FREQUENCY 10000

将 ChibiOS 系统时钟节拍设为 10 kHz、计数分辨率 16 位，为键盘矩阵扫描、去抖（debounce）与背光控制提供统一的时间基准。从这套文件组合可以推断，Ghoul TKL 的背光是完全基于 STM32 硬件定时器（TIM2）的 PWM 方案，亮度调节由定时器占空比直接控制，而非软件模拟。

进阶：自定义键位与固件定制

在默认键位基础上定制，推荐做法是在 keymaps 目录下新建键位目录（例如keymaps/mine/keymap.c），随后使用：

make chill/ghoul:mine

进行编译。可参考的官方学习路径包括 newbs_building_firmware（从零构建首个固件）、feature_advanced_keycodes（进阶键码，如层切换、修饰键组合、QK_BOOT复位键）以及 ref_functions（可用函数参考）。

小结

Ghoul TKL 以一块替换 PCB 的方式，为 Filco TKL 注入了 QMK 的全部能力：make chill/ghoul:default一条命令即可产出固件，stm32-dfu与三种 Bootloader 入口保证了刷写路径的冗余；数据驱动的 keyboard.json 完整描述了矩阵、PWM 背光、指示灯与四种 TKL 社区布局，而 config.h 与 ChibiOS 配置文件则揭示了硬件定时器层面的背光实现细节。无论是直接使用、还是在其基础上二次开发键位，这份固件都是一份结构清晰、可直接上手的 TKL 移植范例。

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