QMK 固件中的 LvL Type-01/80（rev_hs01）：TKL 键盘的编译、刷写与硬件配置解析-酒店常州论坛

QMK 固件中的 LvL Type-01/80（rev_hs01）：TKL 键盘的编译、刷写与硬件配置解析

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

本篇技术指南以 QMK Firmware 仓库中 keyboards/artifact/lvl/rev_hs01 的官方说明为主体，结合该键盘的keyboard.json、config.h、rules.mk与默认键位等源码文件，系统讲解 LvL Type-01/80 这款 STM32F072CB 主控的标准 TKL PCB 如何在 QMK 中完成编译、进入刷写模式、烧录固件，以及其矩阵、指示灯与 RGB 灯带的底层硬件配置。读完本文，你将能够独立完成该键盘（以及同一 LvL 系列）的固件编译与刷写流程，并理解 QMK>make artifact/lvl/rev_hs01:default

该命令的语义是make <keyboard>:<keymap>：artifact/lvl/rev_hs01为键盘路径，default为默认键位（位于 keymaps/default/keymap.c）。编译产物（.hex/.bin固件文件）会输出在 QMK 构建目录中，供后续刷写使用。

2.3 默认键位内容

默认键位使用LAYOUT_tkl_ansi_tsangan布局宏，定义了完整的 TKL ANSI + Tsangan 底排键位（左 1.5U Ctrl/Win/Alt、7U 空格、右侧 1.5U Alt/App/Ctrl），导航区为 Ins/Home/PgUp、Del/End/PgDn、方向键集群：

[0] = LAYOUT_tkl_ansi_tsangan( /* Base */ KC_ESC, KC_F1, KC_F2, ..., KC_PSCR, KC_SCRL, KC_PAUS, KC_GRV, KC_1, ..., KC_INS, KC_HOME, KC_PGUP, KC_TAB, KC_Q, ..., KC_DEL, KC_END, KC_PGDN, KC_CAPS, KC_A, ..., KC_LSFT, ..., KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_RALT, KC_APP, KC_RCTL, KC_LEFT, KC_DOWN, KC_RGHT)

完整键位可见 keymaps/default/keymap.c。如需自定义键位，可按 QMK 惯例在keymaps/<name>/keymap.c新建目录后执行make artifact/lvl/rev_hs01:<name>。

三、进入刷写模式（Reset / DFU 模式）

该键盘的主控为 STM32F072CB，bootloader 为stm32-dfu（见 keyboard.json）。与 AVR 键盘常见的RESET键码不同，LvL Type-01/80 官方推荐的进入刷写模式方法是硬件层面的「通电时序」：

拔掉 USB 线（Unplug）；
按住键盘上的Escape（ESC）键不放；
插入 USB 线（Plug In）；
再次拔掉 USB 线（Unplug）；
松开 Escape 键。

此时键盘即停留在 DFU 引导模式，等待固件写入。整个流程本质上是利用 STM32 的 Boot0 强制启动逻辑：上电瞬间保持某个 GPIO 为低电平（ESC 键所在列被拉低），即可让芯片进入 DFU Bootloader，而非运行已烧录的应用程序。

四、刷写固件：CLI 一键式与 QMK Toolbox

进入 DFU 模式后，即可烧录编译好的固件。官方推荐两种方式：

4.1 命令行一键刷写

在仓库根目录执行：

make artifact/lvl/rev_hs01:<keymap>:flash

其中<keymap>可以是default，即：

make artifact/lvl/rev_hs01:default:flash

该命令会自动调用dfu-util（或 QMK 配置的默认刷写工具）烧录刚编译出的固件，并等待设备进入 DFU 模式后写入。

4.2 QMK Toolbox 图形化刷写

如果不习惯命令行，也可以使用 QMK Toolbox：先在刷写工具中加载编译产物固件文件，随后按第三节的时序让键盘进入 DFU 模式，Toolbox 检测到STM32 DFU设备后点击 Flash 即可完成写入。

五、硬件配置深度解析（源码级）

readme 只给出了用法，而硬件如何被 QMK 识别与驱动，则完整记录在 keyboard.json 与配套头文件中。理解这些字段，有助于排查按键失灵、指示灯异常、RGB 灯不亮等问题。

5.1 主控、USB 标识与 Bootloader

"processor": "STM32F072", "bootloader": "stm32-dfu", "usb": { "device_version": "0.0.1", "pid": "0x4C56", "vid": "0x8968" }

processor：指定编译目标为 STM32F072（Cortex-M0 内核），决定使用 ARM/ChibiOS 构建链路；
bootloader：stm32-dfu说明通过 USB DFU 协议刷写；
vid/pid：0x8968:0x4C56 为设备 USB 标识（由 Yiancar-Designs 分配），系统据此识别设备。

5.2 矩阵扫描配置

"diode_direction": "COL2ROW", "matrix_pins": { "cols": ["A1", "B9", "A3", "A4", "A5", "A6", "A7", "B0", "B1", "B2", "B10", "B11", "B12", "B13", "B14", "B15", "A8"], "rows": ["A2", "A14", "A15", "B3", "B4", "B5"] }

采用COL2ROW（列扫描输出、行读入）方式，二极管方向为列到行；
矩阵规模为6 行 × 17 列，正好覆盖 87 键 TKL 并留出冗余；
行列均直接映射到 STM32F072 的 GPIO 引脚（PA1、PB9、PA3……），这是 QMK>"indicators": { "caps_lock": "B6", "on_state": 0 }
- Caps Lock 指示灯接在 PB6 引脚，on_state: 0表示低电平点亮（开漏/低有效）；
- 对应的板级初始化在 rev_hs01.c 中完成：led_init_ports()将 LED 引脚配置为开漏输出：
```
void led_init_ports(void) { // Set our LED pins as open drain outputs gpio_set_pin_output_open_drain(LED_CAPS_LOCK_PIN); }
```
从这里可以推断，PCB 上 Caps Lock 灯为共阳/下拉式设计，因此采用开漏输出 + 低有效点亮的组合。
5.4 板载 RGB 灯带（WS2812）
键盘带有单颗 WS2812（rgblight.led_count: 1），并使用 PWM 驱动：
```
"rgblight": { "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 }, "default": { "sat": 0 }, "led_count": 1 }, "ws2812": { "driver": "pwm", "pin": "A9" }
```
- 数据引脚为 PA9，使用pwm驱动；
- PWM 的具体硬件通道在 config.h 中指定：
```
#define WS2812_PWM_DRIVER PWMD1 #define WS2812_PWM_DMA_STREAM STM32_DMA1_STREAM5 #define WS2812_PWM_DMA_CHANNEL 5 #define WS2812_BYTE_ORDER WS2812_BYTE_ORDER_RGB
```
即使用 TIM1（PWMD1）产生 WS2812 时序信号，通过 DMA1 Stream5 搬运数据，颜色字节序为 RGB；
- 相应地，halconf.h 打开HAL_USE_PWM，mcuconf.h 打开STM32_PWM_USE_TIM1，二者共同确保 ChibiOS PWM 外设在编译期可用；
- 默认饱和度设为 0（"default": { "sat": 0 }），出厂效果为白色/无色灯效。
5.5 布局与社区布局
keyboard.json中定义了两种物理布局宏：
- LAYOUT_tkl_ansi_tsangan：ANSI 主键区 + Tsangan 底排（默认键位使用）；
- LAYOUT_tkl_ansi_wkl：ANSI + WKL（无 Win 键缺口）底排变体。
同时声明"community_layouts": ["tkl_ansi_tsangan"]，使该键盘的 Tsangan 布局可被 QMK Configurator 等社区布局系统复用。两种布局均以x/y坐标 + 键宽w精确定义了每一颗键帽的物理位置，这也是 QMK 据此生成键位图与可视化配置的基础。
5.6 DFU 固件兼容性扩展
rules.mk 中有一行特殊配置：
```
# Wildcard to allow APM32 MCU DFU_SUFFIX_ARGS = -v FFFF -p FFFF
```
dfu-suffix通常会把厂商/产品 ID 写入固件后缀以便校验；此处以通配符FFFF覆盖，从注释可以看出这是为了兼容 APM32 系列 MCU（STM32 的国产兼容替代），避免刷写校验因 ID 不符而失败。这也解释了为什么主控标注为 STM32F072CB 而固件后缀不锁定具体 VID/PID。
六、常见问题与排错建议
- 编译报错找不到 ARM 工具链：确认按 docs/getting_started_build_tools.md 完整安装依赖，并确认 ChibiOS 子模块已初始化。
- 刷写时设备无法识别：检查是否严格按第三节时序操作（拔线 → 按住 ESC → 插线 → 拔线 → 松开 ESC），并用dfu-util -l或 QMK Toolbox 确认设备处于 DFU 模式。
- Caps Lock 灯不亮：确认indicators.caps_lock对应 PB6、on_state: 0低有效；若硬件为高有效需改为on_state: 1（以实物电路为准）。
- RGB 灯无反应：确认features.rgblight已启用、ws2812引脚为 PA9，且halconf.h/mcuconf.h中的 PWM 与 TIM1 开关未被裁剪；更换按键布局不影响 RGB 行为。
七、延伸阅读
- docs/getting_started_make_guide.md：Make 命令完整语法（make <keyboard>:<keymap>与:flash后缀）；
- docs/flashing.md：各主控平台的通用刷写指南；
- docs/data_driven_config.md：keyboard.jsoncontenteditable="false">【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析