⌨ QMK 键盘开发指南

汇总基于 QMK 固件开发自定义键盘的核心知识：主控芯片选型、Bootloader 与刷写工具链、RGB / OLED / 编码器 / MIDI 等常用外设的硬件接线与固件配置。面向键盘 DIY 爱好者，基于 QMK 官方文档与实践经验整理。

🧠 一、主控芯片选型对比

以下对比涵盖 STM32 原厂及国产 APM32 替代型号。关键指标：内核架构、主频、Flash/SRAM、ADC、USB 规格、封装、QMK 默认晶振频率及参考价格。

选型对比总表（25 款芯片）

表格横向可滚动。✔ = QMK 默认支持；◐ = 需适配。注意：本表只判断「能不能编译、跑不跑得动」，没判断「能不能 USB 刷」——后者看芯片 ROM DFU 的 VID:PID 在不在 QMK / Toolbox 名单里，见 兼容芯片能否直接烧。

参考价格为 2026-10 散片单买口径（如 F405RGT6 立创 1+ ¥36.6 / 100+ ¥27.5、F411CET6 立创 1+ ¥14.0），同规格 APM32 约为 ST 一半价。
为什么 ST 推荐立创商城：小批量直接买立创现货散价——淘宝散片来源不透明，很多不知道是哪年的老片子，甚至可能是二手翻新片，翻车风险高；立创现货可追溯、散价也公道。
为什么 APM32 在淘宝「联科芯」买而不在立创：作者长期在该店购买，已向极海官方确认其为代理，货源可靠、价格实在——顺便算是给他们打个广告。
行情随时浮动，下单前以实时查询为准；标 ⚠ 的价格为倒挂 / 不适用口径，不要照它下单。

推荐 & 建议

📌 QMK 官方芯片支持速查（晶振 × 预设主频 × 容量覆盖）

下表逐板提取自 QMK 官方源码（platforms/chibios/boards/*/configs/board.h 与 configs/mcuconf.h）。「预设 / 标称」= 不改任何官方配置直接编译得到的实际 SYSCLK 与芯片标称主频。晶振列是 QMK 预设写死的频率——板载晶振与它不符时 PLL 会跑飞或锁不上，这正是 F405（12MHz）与 F407 / F411（8MHz）混用时的经典坑。「容量覆盖」列逐个后缀写明能否直接编译：官方板级只带一个容量的链接脚本，更大容量需按列内说明另配文件。APM32 官方零支持、借用对应 STM32 板级时，晶振与容量规则跟随所借配置（如 APM32F405RGT6 = 12MHz + xG 直接满配）。

「满速」= QMK 预设即达芯片标称主频。容量后缀速记：C=256KB、E=512KB、G=1MB（F103 系列为 8=64K、B=128K、C=256K、E=512K、G=1M）；封装后缀 C=48 脚、R=64 脚、V=100 脚。「直用」= 官方板级自带的链接脚本容量正好覆盖，rules.mk 不用加任何东西；「需另配 / 需显式」= 要加一行 MCU_LDSCRIPT 或自建脚本文件。自建板级（APM32 / F103 xC·xE·xG / F407xG 等）时，晶振与 PLL 需自行对齐后再算 SYSCLK。

📌 「兼容 STM32」的芯片能不能直接烧？看 DFU 的 VID:PID

QMK 能认的 DFU 档位是一张封闭的表（stm32-dfu / apm32-dfu / at32-dfu / wb32-dfu / gd32v-dfu / stm32duino / tinyuf2 / rp2040 …），QMK Toolbox 更是只对它内置了设备类的那几个 VID:PID 生效。所以其它品牌哪怕号称「引脚与寄存器全兼容」，能不能直接烧只取决于一件事：它的 ROM bootloader 报出来的 VID:PID 落在不在名单里。

# rules.mk —— 借 stm32-dfu 这一档，但把 ID 换成实际芯片的
MCU = STM32F103
BOOTLOADER = stm32-dfu
DFU_ARGS = -d 1234:5678 -a 0 -s 0x08000000:leave
DFU_SUFFIX_ARGS = -v 1234 -p 5678

# 两个变量在 QMK 里都是 ?= 定义，rules.mk 里写了就优先用自己的
# 之后只能：qmk flash -kb xxx -km xxx（Toolbox 依然认不出设备）

🚀 二、起步：环境搭建与第一个键盘工程

本篇为纯新手路线：从空电脑到编译出第一个能刷进键盘的固件。章节框架已就位，正文逐步补全。

2.1 QMK MSYS 安装与 qmk setup框架 · 正文待补

2.2 创建键盘工程：目录结构与各文件职责框架 · 正文待补

2.3 第一次编译与刷写框架 · 正文待补

⚙️ 三、快速配置向导

下拉选择实际型号后，页面会同时给出 keyboard.json 和 rules.mk：前者唯一声明 processor / bootloader，后者只保留板级、链接脚本等其余设置，避免同一选项在两个文件中重复定义。

⚙️ F103 / E103 配置

QMK 的“主控型号”与“板级配置”不是一一对应的。

以 F103 / E103 为例：

• board/board.h、configs/mcuconf.h：负责内核、时钟和外设配置
• 链接脚本 *.ld：决定固件可使用的 Flash、SRAM 以及程序起始地址
• 使用 stm32duino 时：程序从 0x08002000 开始，前 8KB 留给 Bootloader

qmk_firmware/platforms/chibios/boards/STM32_F103_STM32DUINO/
├─ board/board.h       # F103 板级定义、8MHz 外部晶振、USB 引脚
├─ board/board.c       # 启动时钟初始化、Bootloader 标志
├─ configs/mcuconf.h   # PLL、总线分频、USB/SPI 等外设开关
└─ ld/
   ├─ STM32F103x6_stm32duino.ld  # 32KB Flash / 10KB RAM
   ├─ STM32F103x8_stm32duino.ld  # 64KB Flash / 20KB RAM
   └─ STM32F103xB_stm32duino.ld  # 128KB Flash / 20KB RAM

没有对应配置文件时如何新建

最稳妥的方法：

1. 复制同目录下现有的 STM32F103xB_stm32duino.ld
2. 只修改 Flash 和 SRAM 容量定义
3. 不要直接修改公共文件 stm32duino_bootloader_common.ld，因为多个容量脚本都会引用它

/* 例如 STM32F103RET6：使用 stm32duino，保留 8KB Bootloader */
f103_flash_size = 512k;
f103_ram_size = 64k;

/* 下面这行保持不变 */
INCLUDE stm32duino_bootloader_common.ld

将文件保存为键盘目录的 ld/STM32F103xE_stm32duino.ld，然后在键盘的 rules.mk 中指定：

MCU = STM32F103
BOOTLOADER = stm32duino
MCU_LDSCRIPT = STM32F103xE_stm32duino

如果是 RCT6，将容量改为 256k / 48k 并使用 xC；如果是 RGT6，改为 1m / 96k 并使用 xG。APM32E103CET6 和 APM32E103RET6 都是 512KB Flash，但 SRAM 应按实际芯片数据手册填写为 128KB，不能照抄 STM32F103RET6 的 64KB。

APM32E103 全频率配置（实验性）

APM32E103 的“完整容量”和“全频率”是两个独立目标：

• 完整容量模式：新建匹配容量的链接脚本，使用 512KB Flash / 128KB SRAM；主频仍为当前配置的 72MHz。
• 全频率模式：在完整容量基础上，还要修改时钟初始化、Flash 等待周期、USB 48MHz 时钟以及必要的 MCU/HAL 启动配置。

后续适配时需要重点检查以下文件：

键盘目录/
├─ rules.mk                         # MCU、Bootloader、链接脚本选择
├─ ld/APM32E103xE_stm32duino.ld    # 512KB Flash / 128KB SRAM
├─ board/board.h                    # 外部晶振频率和板级定义
├─ config/mcuconf.h                 # PLL、AHB/APB、USB 时钟
└─ board/apm32_clock.c              # 如 HAL 默认初始化不足，增加专用时钟初始化

不能只把 PLL 倍频从 9 改成更大的数值。目标主频必须同时满足 APM32E103 数据手册的系统时钟、AHB/APB、Flash 等待周期和 USB 时钟要求；每次修改后都应通过 USB 枚举、键盘扫描、定时器、长时间运行和复位启动测试。

因此，在完整测试完成前，教程和配置向导应将该方案标记为：

APM32E103 全频率模式：实验性，尚未完成完整测试
当前已验证模式：F103 兼容配置，72MHz

无 Bootloader 直接烧录

无 Bootloader 时不能继续使用上面的 *_stm32duino.ld，因为它们都从 0x08002000 开始。应复制该文件并把链接脚本中的 Flash 区域改为：

flash0 (rx) : org = 0x08000000, len = 512k

同时删除或绕开 BOOTLOADER = stm32duino 的自动选择逻辑，并通过 ST-Link 等 SWD 工具把完整固件烧录到 0x08000000。Bootloader 是否存在不会改变 F103 的 72MHz 时钟；时钟仍由 board/board.h 和 configs/mcuconf.h 控制。

⚙️ STM32F4 配置

QMK 对 STM32F4 的配置由三部分共同决定：

• board/ 和 configs/mcuconf.h：板级定义、MCU 外设和时钟配置
• common/ld/*.ld：Flash、SRAM 地址及容量
• 实际开发板晶振：必须与 board.h 中的 STM32_HSECLK 一致

// rules.mk — APM32F405RGT6 示例（APM32F411CET6 同理，MCU 换 STM32F411）
MCU = STM32F405
BOARD = GENERIC_STM32_F405XG
MCU_LDSCRIPT = STM32F405xG
BOOTLOADER = apm32-dfu

F4 常用配置文件位置

qmk_firmware/platforms/chibios/boards/
├─ GENERIC_STM32_F401XC/configs/mcuconf.h
├─ GENERIC_STM32_F405XG/configs/mcuconf.h
├─ GENERIC_STM32_F407XE/configs/mcuconf.h
├─ GENERIC_STM32_F411XE/configs/mcuconf.h
└─ GENERIC_STM32_F446XE/configs/mcuconf.h

qmk_firmware/platforms/chibios/boards/common/ld/
├─ STM32F401xC.ld / STM32F401xE.ld
├─ STM32F405xG.ld / STM32F407xE.ld
└─ STM32F411xC.ld / STM32F411xE.ld / STM32F446xE.ld

官方原版核对（GitHub master）： boards 目录只有上面 5 个 GENERIC 板级（另有 BLACKPILL_STM32_F401 / F411 开发板配置），common/ld 里各脚本另有 *_tinyuf2.ld 变体（TinyUF2 引导用）。官方没有 STM32F407xG.ld，也没有 GENERIC_STM32_F401XE / GENERIC_STM32_F407XG 板级目录和任何 APM32 板级——需要 F401xE 独立板级、F407xG 或 APM32 支持时都得自建（板级目录 = board/configs/ld 三件套，不只是链接脚本）。本站提供自建脚本下载：STM32F407xG.ld（F407VGT6 用，1MB Flash，QMK 默认只有 512KB 的 xE）。

F4 在 rules.mk 中显式选择容量

# 例如 STM32F401E：512KB Flash / 96KB SRAM
MCU = STM32F401
MCU_LDSCRIPT = STM32F401xE

# 例如 STM32F411C：256KB Flash / 128KB SRAM
MCU = STM32F411
MCU_LDSCRIPT = STM32F411xC

🔋 四、USB 硬件设计（F1 / F4 全系列）

这一章解决一个很具体的问题：自己画一块键盘板，USB 那几根线到底怎么接。之所以不能只给一套图，是因为各系列的 USB 控制器根本不是同一代东西——F1 没有内置 D+ 上拉，1.5K 电阻必须外接；F4 内置了，外接反而违规。同一张图抄错系列，轻则枚举时好时坏，重则电脑连"未知设备"都不弹。

下面按「先分类 → F1 体系 → F4 体系 → 其余芯片 → 自检清单」的顺序讲，每条结论都给依据（芯片手册、ST 应用笔记、QMK 源码或上游 issue），不做"据说"式的口口相传。QMK 与自研固件对硬件的要求完全一致，一份 PCB 通吃。

4.1 一页速查：你的芯片属于哪一类

先在这张表里找到自己用的芯片，再去对应小节看细节。「D+ 1.5K 上拉」这一列是整章最容易出事的地方，也是不同系列之间最硬的一条分界线。

「直连」= D+ / D- 直接走到 USB 座，不串任何电阻；「内置」= 上拉在芯片内部、由固件使能，外部再画一颗就是并联。

4.2 STM32F1 体系（F103 / APM32E103 / F303）

F1 是这批芯片里唯一必须手工补一颗 1.5K 电阻的系列，也是最多人栽跟头的地方——因为大量教程是照着 F4 写的，看到"1.5K 上拉"顺手就删了。

为什么 F1 的 1.5K 必须外接

USB 全速设备靠 D+ 被 1.5K 上拉到 3.3V 来告诉主机"我插上了、我是全速设备"，主机检测到这个电平才开始枚举。F103 的 USB 外设没有这颗内部电阻，ST 官方应用笔记 DM00296349《Introduction to USB hardware and PCB guidelines》 的对照表写得很直白：F102 / F103 一栏是「1.5 kΩ resistor must be added」，而 F0、F3、F4 各栏是「Embedded」。

漏了它的症状非常干脆：板子上电、固件在跑、串口能打印，电脑端毫无反应——连"未知 USB 设备"都不弹，因为主机压根没检测到插入事件。不是驱动问题、不是固件问题、不是线的问题，就是少了一颗电阻。

标准接法：D+ 经 1.5K 到 3.3V

# F103 最小 USB 接法（总线供电）
USB 座 VBUS ──────────────→ LDO → 3.3V
USB 座 D-   ──────────────→ PA11 (USB_DM)
USB 座 D+   ───┬──────────→ PA12 (USB_DP)
               └─[ 1.5kΩ ]─→ 3.3V      # 这颗不能省
USB 座 GND  ──────────────→ GND

注意电阻接的是 3.3V，不是 VBUS 的 5V。接 5V 一方面把 D+ 抬到超出 USB 规范的电平，另一方面在 MCU 未上电、USB 已插入时会经 IO 反向灌电（back-powering），板子会出现"没供电但 LED 微亮"之类的怪现象。

要不要用 GPIO 控制这颗上拉？有些设计在 D+ 与 3.3V 之间串一个三极管/MOS，由 GPIO 控制通断，好处是固件可以"自己拔插自己"强制主机重新枚举。代价很实在：进了 bootloader，GPIO 回到复位态，上拉就断了——而现成的 stm32duino bootloader 并不会接管你这个自定义引脚，于是 DFU 枚举不出来，直接变砖。所以：做键盘就老实硬接 3.3V，需要重新枚举拔一次线，别为省一次插拔引入一类新故障。

时钟：8MHz 晶振 + USB 固定 1.5 分频

F103 的 USB 需要精确的 48MHz，路径是死的：外部 8MHz → PLL ×9 = 72MHz → USB 预分频 ÷1.5 = 48MHz。这条链上任何一环不对（晶振不是 8MHz、PLL 倍频改了、误用了内部 HSI），USB 就完全不工作，而 CPU 看起来一切正常，非常迷惑。

所以 F103 板子的晶振不能省、不能换频率。APM32E103 是对标 F103 的增强型，时钟树一致，同样按 8MHz 设计；USB 控制器沿用同一套方案，按 F103 的画法外接 1.5K 最稳妥（若极海新版数据手册标注了内置上拉，以手册为准）。

F1 特有的两个坑

• USB 与 CAN 共享 512 字节专用 SRAM：F103 的 USB 包缓冲区不是普通 SRAM，和 CAN 共用一块（ST 官方表注：「cannot be used at the same time」）。键盘不用 CAN，所以无碍；若你想在同一颗片子上同时跑 USB 与 CAN，得二选一。
• F303 是"半个例外"：它同样走 USBv1 这套老控制器、同样要外部晶振，但 ST 官方表里 D+ 上拉是「Embedded」，不需要外接 1.5K。QMK 有现成板级 GENERIC_STM32_F303XC。判断依据永远是具体型号的手册，不是"F1/F3 都是老片子"这种印象。

PA9 / PA10 在 F1 上：不归 USB 管，但 bootloader 仍要管

F1 的 USB 只用 PA11（D-）/ PA12（D+），没有 VBUS 检测引脚，所以下一节那场 PA9 的 GCCFG 事故与 F1 完全无关——PA9 拿去做矩阵行/列随便用，不会有内部下拉。

但 PA10 的风险一样存在：它是 USART1_RX，而 F103 的出厂 bootloader 同样支持 USART1 烧录（AN2606）。上电检测相若 PA10 悬空乱飘，bootloader 可能误判"串口那头有人说话"而切走。做 F103 板子时给 PA10 一颗 22K 上拉到 3.3V，成本一颗 0402，能挡掉一类"时好时坏进不去 bootloader"的故障（机理详见 4.3 的 PA10 小节，与芯片系列无关）。

stm32duino 的"软重枚举"就靠这颗电阻

QMK 在 F103 上常用 stm32duino bootloader。它的 generic 版本没有 Maple 那套专用 USB 复位电路，靠的是把 PA12（D+）临时切成 GPIO 拉低一小会儿，再切回 USB 模式，让主机看到一次"拔出—插入"。前提正是 D+ 上那颗约 1.5K 的上拉——没有它，这个技巧无从谈起。这是"F1 的 1.5K 必须硬接"的第二个理由。

4.3 STM32F4 / F5 / F7 体系（OTG_FS，内置 PHY）

从 F4 开始，USB 换成了 OTG 控制器 + 片内全速 PHY：上拉、终端匹配、收发器全部集成，外部只剩"把两根线接出去"。这一节的结论对 F401 / F405 / F407 / F411 / F446、APM32F4 全系，以及 F5 / F7 通用，差异集中在 VCAP 和晶振上（见型号对齐表）。

数据线：直连，别画蛇添足

PA11 = D-、PA12 = D+（F7 等大封装型号可重映射到 PB14 / PB15），两根线直接走到 USB 座即可。片内 PHY 自带终端匹配与驱动能力，这是它与外挂 ULPI 高速 PHY（如 USB3300）最大的区别——后者才需要一堆外围。

布线建议（不是硬性规定，但照做省事）：

• D+ / D- 走差分对，尽量等长、平行、短；USB 2.0 全速对阻抗要求宽松（目标 90Ω 差分），普通两层板 1.6mm 厚度、线宽 0.2mm / 间距 0.2mm 左右就够用，不必为它上四层板。
• 差分对不要跨过地平面裂缝，也不要和其他高速信号（如 WS2812 的 DIN）长距离并行。
• USB 座尽量靠近 MCU，走线控制在几厘米内；实在要拉长，优先保证 D+/D- 不被其他信号切割。

D+ 的 1.5KΩ 上拉：芯片内部已有，外接反而违规

原理：F4 的 OTG_FS 把这颗 1.5K 电阻集成在片内 PHY 里，而且是可编程的——由 USB 内核在准备好之后才挂上（soft-connect），固件可以自己决定何时"露面"。

外接的后果：片内 1.5K 与外接 1.5K 并联约 750Ω，D+ 静态电平偏离规范。轻则主机识别时序错乱、枚举时好时坏，重则速度协商失败直接不认设备。有人外接后"能用"，是因为片内上拉在 soft-connect 之前还没挂上，属于两头都不对的巧合，不能当作可行方案。

PA9 / PA10：两根引脚、两个完全不相干的问题

搜索"F4 PA9 不能用"，会看到一大堆互相矛盾的帖子。混乱的根源是：网上把两个彼此无关的问题混成了一件。先把它们拆开，后面就都好懂了。这一节只针对 OTG 体系（F4 / F5 / F7）；F1 没有 VBUS 检测引脚，PA9 不受影响。

所以那句最常见的困惑——"我都升到最新 QMK 了，PA9 怎么还是不行"——答案通常是：那其实是 PA10 那边的问题，跟固件版本没有任何关系。

PA9（VBUS）与那场持续四年的 bug

引脚的双重身份：PA9 平时是普通 GPIO（也兼 USART1_TX），但 F4 的 OTG_FS 默认把它当作 VBUS 检测输入——用来判断 USB 线是否插上、主机是否供电。键盘都是总线供电，"插上就有电"，这个功能用不上，反而占着一根宝贵的 GPIO。

设计意图：为此 QMK 给所有 F4 板级定义了 BOARD_OTG_NOVBUSSENS，期望按参考手册置 OTG_FS_GCCFG.NOVBUSSENS = 1（"不需要 VBUS 检测"），把 PA9 释放成普通 GPIO。这个思路完全正确。

真正的 bug：ChibiOS 的 OTGv1 驱动在初始化 GCCFG 寄存器时，把 VBUSASEN、VBUSBSEN 和 NOVBUSSENS 一起置了 1。而 VBUSBSEN = 1 的含义恰恰是「PA9 作为 VBUS 检测输入启用」，并且会给它挂上内部下拉——于是 PA9 名义上被"释放"，实际仍被 USB 外设占用、呈下拉状态。

症状：PA9 做矩阵列（上拉输入）时读不到高电平，整列按键失灵；做行输出时拉高也被内部下拉拖住。2020～2024 年间，凡是把 PA9 用在矩阵里的键盘，基本都栽在这一处，而且极难自查——因为代码、接线、焊接看起来都对。

完整时间线：从首次报告到上游修复

整个过程四年多，中间无数人怀疑过自己的 PCB、排针和焊接——这也是为什么值得把这段历史留在文档里：下次再遇到"整列失灵且查不出硬件问题"，先想想是不是引脚被外设占用了。

怎么确认手上的 QMK 已经修复

问题出在这一行宏定义上，路径固定：

lib/chibios/os/hal/ports/STM32/LLD/OTGv1/hal_usb_lld.c

// 修复后：只留 NOVBUSSENS + PWRDWN，不再置 VBUSASEN / VBUSBSEN
#if defined(BOARD_OTG_NOVBUSSENS)
#define GCCFG_INIT_VALUE        (GCCFG_NOVBUSSENS | GCCFG_PWRDWN)
#else
#define GCCFG_INIT_VALUE        (GCCFG_VBUSASEN | GCCFG_VBUSBSEN | GCCFG_PWRDWN)
#endif

一条命令确认（在 qmk_firmware 根目录执行）：

grep -A3 "BOARD_OTG_NOVBUSSENS" lib/chibios/os/hal/ports/STM32/LLD/OTGv1/hal_usb_lld.c

若输出里还带着 GCCFG_VBUSBSEN，就是没修的旧版；只剩 NOVBUSSENS | PWRDWN 就是修好的。本指南核对时（2026-10），QMK 主线锁定的 ChibiOS 子模块已经是修复后的写法。

旧版 QMK 的三种绕过方式

只在维护老工程（不能升级 QMK）时才需要；新工程直接用新版即可。

现在到底怎么接（默认不用 5V）

按实际情况选一行。默认推荐第一行——PA9、PA10 各一颗 22KΩ 上拉到 3.3V，其余全部不接，5V 一根线都不进 MCU。

依据：QMK GENERIC_STM32_F411XE 板级配置定义了 BOARD_OTG_NOVBUSSENS 1，USB 内核把 VBUS 视为常有效，PA9 不参与枚举；旧版 ChibiOS 的 GCCFG 缺陷曾让它维持内部下拉，2023-04 上游修复、2024-10 起 QMK 收录。QMK F411 板级配置 · ST 社区：NOVBUSSENS 可释放 PA9

PA10：ROM Bootloader 的"接口嗅探"（与固件版本无关）

这一条和上面那场 bug 毫无关系，但症状很像——都是"电脑里看不到设备"。而且它跟 QMK 版本、跟 ChibiOS 全都无关，升到再新的固件也救不了，因为出问题的代码在芯片出厂时就烧死在 ROM 里了。对 F1 / F4 / APM32 一样成立：只要用了 ST 系或极海系的出厂 bootloader，PA10 就不能悬空。

依据：AN2606 的原文要求

ST 的 AN2606《STM32 microcontroller system memory boot mode》第 4.3 节原文：

翻译成人话：bootloader 上电后要挨个"嗅探"可用的烧录接口——USART1、USART3、CAN2、USB，谁先有动静就走谁。而那些没打算用的接口，它们的 RX 引脚必须处于确定电平（高或低都行），否则电平乱飘会被误认为"有人正在发数据"，从而把那个接口激活。

为什么偏偏是 PA10 中招

因为 PA10 正好是 USART1_RX（F1 / F4 都是）。悬空时它像一根天线，手靠近、板子受潮、甚至上电瞬间的容性耦合，都可能让它读到几个"看起来像起始位"的电平跳变。bootloader 一旦判定"串口那头有人在跟我说话"，就会切到串口烧录模式，把 USB DFU 关掉——于是你在电脑设备管理器里根本看不到 DFU 设备，连 QMK Toolbox 都刷不进去，表现为"救砖失败"。

这种失败最坑的地方是时好时坏：有人拔插十次能进一次，于是误以为是 USB 线、电脑或驱动的问题。STM32duino 社区 2022-12 的实测帖写得很直白：多块 F401 板子约 80% 概率枚举失败、报 “Device descriptor request failed”，把 PA10 拉到确定电平后稳定进 DFU。

为什么是 22K，能不能换别的值

高电平同样算"确定电平"，所以上拉、下拉都可以，关键是不能悬空。实际板子几乎都用上拉到 3.3V，因为下拉会让"USART 空闲态"看起来像线路异常，而上拉正好符合 UART 空闲为高的习惯。

• 22K（WeAct / QMK Blackpill 文档的推荐值）：噪声环境下足够"硬"，远强于板面漏电与容性耦合；又不会在 PA10 当普通 GPIO 用时干扰外部驱动，静态电流只有 ~150µA。
• 10K ～ 100K 都可用：越小越抗干扰、静态电流越大；越大越省电、抗干扰越差。22K 是这两者之间的常用折中。
• 不要省：一颗 0402 电阻的成本，换掉一整类"时好时坏、无法复现"的故障，没有任何理由省。

型号对齐：谁和谁能共用一套图

结论先给：F4 / F5 / F7 的 USB 外围接法完全相同，差异只在板级配置文件放在哪、晶振频率、以及 VCAP 接法。下表按 LQFP-64 口径整理，封装不同时引脚号以数据手册为准。

Black Pill：板子本身是好板，但「BlackPill 板级」只对 25MHz 正品成立

这块板的原创方是 WeAct Studio（微行工作室），不是无名山寨——它在国产核心板里属于做得相当用心的那类：411 用沉金 + 无铅工艺、排针镀金、25MHz 与 32.768kHz 都用金属外壳晶振、USB-C 串了防倒灌二极管、背面预留 SPI Flash 焊盘（附 USBDisk / FATFS 例程）、原理图与例程在 GitHub 同步更新（WeActStudio.MiniSTM32F4x1，2026-10 仍有提交），连出厂都预烧了自己的 HID Bootloader。官方淘宝店：shop118454188.taobao.com。

2026-10 复核的现状（依据其仓库 README 的「出售情况」与料号说明）：

所以就出现一个看着矛盾、其实很合理的结论：板子值得买、厂家也靠谱，但「BlackPill」这个名字不是一个可依赖的硬件基线——正品是 25MHz、仿板可能换 8MHz，同一个商品名买到的是两种时钟。而 QMK 的 BLACKPILL_STM32_F401 / F411 板级把 HSE 写死成 25MHz（PLL 也按 25MHz 配）。你自画板用的是 8MHz 或 12MHz，一旦顺手套上这个板级，USB 会彻底不枚举，但板子本身看起来还活着——这类故障极难往「板级选错」上想。

源码里到底写死了什么

两个板级的实现很短，问题一目了然（路径相对 QMK 根目录）：

// platforms/chibios/boards/BLACKPILL_STM32_F411/configs/config.h
#define STM32_HSECLK 25000000U   // ← 25MHz 写死在这里（外面套了 #ifndef，可被更早的 -D 覆盖）

// platforms/chibios/boards/BLACKPILL_STM32_F411/configs/mcuconf.h
STM32_PLLM_VALUE 25   STM32_PLLN_VALUE 384
STM32_PLLP_VALUE 4    STM32_PLLQ_VALUE 8

// platforms/chibios/boards/GENERIC_STM32_F411XE/configs/mcuconf.h（自画板用这个）
STM32_PLLM_VALUE 4    STM32_PLLN_VALUE 96
STM32_PLLP_VALUE 2    STM32_PLLQ_VALUE 4

两套参数各自都算得出 96MHz 主频 + 48MHz USB，但前提都是"喂给它的晶振正好是它期望的那一个"：

错配之后会怎样：USB 死，CPU 还在跑

• 板上是 8MHz，却用了 BLACKPILL 板级：8÷25=0.32MHz 送进 PLL，而 F4 要求 PLL 输入在 1～2MHz 之间。就算勉强锁上，VCO 只有 122.88MHz → 主频 30.72MHz、USB 时钟 15.36MHz（要 48MHz）。
• 板上是 25MHz，却用了 GENERIC 板级：25÷4=6.25MHz 远超上限，VCO 算到 600MHz（F411 上限 432MHz）→ PLL 根本锁不上，芯片退回内部 HSI 跑 16MHz。

两种情况的表现完全一样：板子能跑、矩阵能扫描、串口可能还有输出，但插上电脑连"未知 USB 设备"都不弹。注意这和前面 PA9 / PA10 悬空的症状一模一样——三条完全不同的根因、一个表现，这就是这类问题最难查的原因。

那到底用哪个板级

分辨自己手上是哪种，最直接的办法是看晶振丝印：BlackPill 用的是 3225 贴片晶振，表面会印 25.000 或 8.000。另一条路是拿万用表/示波器量，但没必要——丝印就在那儿。

BlackPill 板级还顺带带了一堆"开发板假设"

晶振只是最要命的一条，其它还有：

• EARLY_INIT_PERFORM_BOOTLOADER_JUMP TRUE：开机早期就尝试跳 bootloader（原板用按键触发 DFU 的那套逻辑）。
• PA0 是板载用户按键、PC13 是板载 LED（上拉到 3.3V）、A4～A7 是背面的 SPI Flash 焊盘——这些引脚在你的板子上可能正接着矩阵。
• 板载 LSE 32.768kHz、固定 USB 端点 FIFO 等参数，都是照那颗芯片的外围配的。

用在自己 PCB 上，等于"借别人的板子定义"：能跑的时候无所谓，一旦出事，你根本分不清是哪条假设在作怪。

VCAP 与供电：F405 和 F411 不能照抄

VCAP 是芯片内核稳压器的外接储能电容，漏了或值不对，芯片表现为随机死机、USB 时通时断，而且很难往这上面想。F4 这一代里，LQFP-64 的 30 / 31 / 47 三个脚在不同型号上含义完全相反，这是混板设计最容易出事的地方：

三个必须记住的差异：

• F411 / F401 的 LQFP-64 没有 PB11，不要照着 F405 的引脚图去接。
• F411 / F401 上 31 / 47 脚是 VSS，必须直接接地，不能当 VCAP 用；反过来，F405 / F407 上这两脚必须接电容——接错一个是死机，一个是短路。
• F411 / F401 的 30 脚是 VCAP，而 F405 / F407 的 30 脚是普通 GPIO。这是"一块板兼容两代"时最容易漏掉的一处，因为 30 脚在两边都是"要处理"的引脚，含义却相反。

想用一套 PCB 同时兼容 F405 和 F411（做升级款或降本款时很常见）：30 / 31 / 47 三个位置各留一组 0Ω 选择位——装 F405 时 31 / 47 接电容、30 脚按 GPIO 处理；装 F411 时 30 脚接电容、31 / 47 用 0Ω 短接到地。同时注意晶振也不同（12MHz vs 8MHz），要留两个焊盘或选可换的晶振封装。

提醒：官方文档这段已经过时

QMK 官方 WeAct Blackpill 文档至今仍写着「PA9 有内部下拉，不要用；非用不可加 ~5.1K 上拉」「PA10 加 ~22K 上拉」。前一句描述的是 2020～2023 年旧 ChibiOS 的行为，2024-10 修复后已不成立，但文档没有跟进。

于是网上大量教程、博客、甚至某些卖家的说明还停在"PA9 不能用、必须外接上拉"的年代。分辨办法很简单：看它有没有提到 ChibiOS 的 GCCFG 修复（2023-04 / 2024-10）——没提的，多半是从旧帖抄来的。本指南的结论以源码和芯片手册为准。

4.4 其余芯片：F0 / RP2040 / ATmega32U4 / H7

这几类不属 F1 也不属 F4，但都有人用，共同点是上拉已经在芯片内部，差别在晶振、串阻和电源域。

STM32F0（F042 / F072 / APM32F072）：上拉内置，晶振看型号

• D+ 上拉内置（ST 官方表标 Embedded），不需要外接 1.5K，也不需要外接三极管。
• F072 有 HSI48：内部 48MHz RC 直接供 USB，连晶振都可以不接，这是它做小键盘最大的优势（QMK 板级 GENERIC_STM32_F072XB 就是按无晶振配的）。
• F042 没有 HSI48：必须外接晶振（8MHz）经 PLL 出 48MHz，别照着 F072 省晶振——这是两兄弟最容易混的地方。
• 数据线直连，不需要串阻；F0 没有 VBUS 检测引脚，不存在 PA9 那类问题。

RP2040：唯一需要串 27Ω 的

RP2040 的 USB 1.1 控制器带片内 PHY，总线上下拉都在内部，所以不需要 1.5K 上拉；但官方数据手册明确要求 USB_DP / USB_DM 各串一颗 27Ω（串联终端，兼作阻尼），并且 USB bootloader 必须用 12MHz 晶振或 12MHz 时钟输入。这两条与 STM32 的"直连、别串阻"正好相反，照抄 ST 的图会得到一块"能跑但高速眼图很差"的板子，照抄"省晶振"则会连 UF2 都进不去。Pico 官方原理图上那两颗 27Ω 就是干这个的。

ATmega32U4：16MHz 是硬要求

上拉内置（由 USB 控制器的 DETACH 位控制），D+ / D- 直连、不串阻。但 16MHz 晶振不能省、不能换：USB 的 48MHz 由 16MHz 经 PLL 得到，晶振不对就完全不枚举。这也是为什么 Pro Micro 类板子清一色 16MHz。

STM32H723：接法同 F4，但多一个电源域

H7 的 USB 也是 OTG 体系（OTG_HS 带内置全速 PHY），D+ 上拉、PA9 / PA10 的结论与 F4 一致（QMK 板级 GENERIC_STM32_H723XG，默认 25MHz 晶振）。额外的坑在供电：H7 的 USB 收发器挂在独立的 VDD33USB 电源域上，这一路没供好，USB 就是彻底不工作——按数据手册把它接到内部 USB 稳压器输出（配去耦电容）或外部 3.3V，别想当然地认为"VDD 有电就行"。

4.5 打板前自检清单

画完原理图，对着自己那块板所属的体系逐条勾，能挡掉绝大多数"USB 不认"的返工。

4.6 参考链接

⌨ 五、键盘矩阵硬件设计框架 · 正文待补

回答"这颗 MCU 能做多大的键盘"：矩阵怎么排、二极管怎么放、引脚够不够。与「USB 硬件设计」同级，属于不画 PCB 也必须掌握的硬件常识。

💾 六、烧录 Bootloader

先分清一件事：bootloader 是「负责把固件收进芯片」的那段小程序，它和 QMK 固件是两份东西。绝大多数芯片出厂就带一份能用的，只有两族例外。

# 在 QMK MSYS 中执行
pacman -S mingw-w64-x86_64-stlink mingw-w64-x86_64-openocd

st-info --probe

st-flash --reset --format binary write <路径> 0x08000000
# 示例：
st-flash --reset --format binary write E:/QMKKeyboard/F103bootloader.bin 0x08000000

# rules.mk
MCU = STM32F103
BOOTLOADER = stm32duino

flash0  : org = 0x08002000, len = f103_flash_size - 0x2000

# 正确：stm32duino 的 alt 2，bootloader 自己决定写 0x08002000
dfu-util -a 2 -d 1EAF:0003 -D firmware.bin

# 错误：ST 系统 bootloader 的 alt 0，写死 0x08000000，F103 上会覆盖 bootloader
dfu-util -a 0 -d 0483:DF11 -s 0x08000000:leave -D firmware.bin

BKP->DR10 = RTC_BOOTLOADER_JUST_UPLOADED;
NVIC_SystemReset();

📥 七、烧录固件

Bootloader 就位（或芯片自带）之后，就是往里面灌 QMK 固件。这一步有四条路，先认清各自适合什么场合，再看细节——绝大多数人一辈子只需要第一条。

Error: File ID 314b:0106 does not match device (0483:df11 or 0483:df11)

# 编译并自动刷写（最常用）
qmk flash -kb my_keyboard -km my_keymap

# 只编译不刷写，产物在 .build/ 下
qmk compile -kb my_keyboard -km my_keymap

# 强制指定刷写器（正常不用写，QMK 会按 BOOTLOADER 自动选）
qmk flash -kb my_keyboard -km my_keymap -bl dfu-util

# 常用 -bl：avrdude(Atmel DFU/Caterina) / dfu-util(STM32) / uf2conv(RP2040/TinyUF2)

# 单板：整片擦除 → 写 bin → 校验 → 复位
STM32_Programmer_CLI.exe -c port=SWD -e all -w firmware.bin 0x08000000 -v -rst

# 只写不擦（想保留自己划的数据区时）
STM32_Programmer_CLI.exe -c port=SWD -w firmware.bin 0x08000000 -v -rst

# 批量：外面套一层循环，逐块换板即可；-rst 让每块写完自动重启进应用

# rules.mk —— F103 用 ST 系统 DFU；E103 / APM32 换成 apm32-dfu
MCU = STM32F103
BOOTLOADER = stm32-dfu

# 只编译不刷写，拿 bin 去 SWD 写
qmk compile -kb my_keyboard -km my_keymap

🔌 八、支持的功能

以下功能均列明硬件接线和 rules.mk / config.h / keymap.c 配置。完整文档见 QMK 官方文档。点击标题展开/折叠详细内容。

RGB_MATRIX_ENABLE = yes
RGB_MATRIX_DRIVER = ws2812              // 或 apa102 / is31fl3731 等

// WS2812 数据引脚
#define WS2812_DI_PIN GP0                     // RP2040 示例，或 B15(STM32)、D3(AVR)
#define RGB_MATRIX_LED_COUNT 68              // LED 总数
#define RGB_MATRIX_KEYPRESSES               // 按键触发灯效
#define RGB_MATRIX_FRAMEBUFFER_EFFECTS      // 帧缓冲特效（雨滴等）
#define RGB_MATRIX_MAXIMUM_BRIGHTNESS 150
#define RGB_MATRIX_DEFAULT_MODE RGB_MATRIX_CYCLE_ALL

// 标准指示灯
#define LED_CAPS_LOCK_PIN   B2
#define LED_NUM_LOCK_PIN    B3
#define LED_SCROLL_LOCK_PIN B4
#define LED_PIN_ON_STATE    1                // 1=高电平点亮，0=低电平点亮

bool led_update_user(led_t led_state) {
    writePin(B5, IS_LAYER_ON(1));  // Layer 1 亮灯
    return true;
}

OLED_ENABLE = yes
OLED_DRIVER = ssd1306

#define OLED_DISPLAY_128X64               // 或 OLED_DISPLAY_128X32
#define I2C_DRIVER I2CD1                   // STM32 示例
#define I2C1_SCL_PIN B6
#define I2C1_SDA_PIN B7

bool oled_task_user(void) {
    oled_write_ln(get_u8_str(get_highest_layer(layer_state), ' '), false);
    return false;
}

// rules.mk 必填：
EEPROM_DRIVER = i2c

// config.h 二选一（按实际焊接）：
//#define EEPROM_I2C_24LC256              // 24LC256 EEPROM（官方默认值）
#define EEPROM_I2C_MB85RC256V          // MB85RC256V FRAM（官方默认值）

// 写保护引脚（强烈建议定义，否则悬空时初始化/写入可能失败）：
#define EXTERNAL_EEPROM_WP_PIN C0        // 接 GPIO 写入，驱动会自动拉低使能

EEPROM_DRIVER = i2c

// 地址规划：0 号字节存初始化标志，1 号字节存音量（示例）
#define EE_MAGIC     0
#define EE_VOL       1
#define EE_MAGIC_VAL 0x5A      // 空白芯片读出为 0xFF，写入标志区分"未初始化"

void keyboard_post_init_user(void) {
    if (eeprom_read_byte((void*)EE_MAGIC) != EE_MAGIC_VAL) {
        // 首次上电：写入默认值
        eeprom_write_byte((void*)EE_MAGIC, EE_MAGIC_VAL);
        eeprom_write_byte((void*)EE_VOL, 50);
    }
    uint8_t vol = eeprom_read_byte((void*)EE_VOL);
    // 用 vol 初始化音量/亮度/层位等状态…
}

// 调整后写回；update 仅在值变化时写入，可减少磨损
void save_volume(uint8_t vol) {
    eeprom_update_byte((void*)EE_VOL, vol);
}

ANALOG_DRIVER_REQUIRED = yes      // 启用 ADC 驱动

#pragma once
#include_next <halconf.h>

// 启用 ADC HAL 驱动
#undef HAL_USE_ADC
#define HAL_USE_ADC TRUE

#pragma once
#include_next <mcuconf.h>

// 启用 ADC1 外设
#undef STM32_ADC_USE_ADC1
#define STM32_ADC_USE_ADC1 TRUE

// STM32F103 可设置 12-bit 分辨率（默认 10-bit），不用白不用
#define ADC_RESOLUTION ADC_CFGR1_RES_12BIT

// ADC 引脚定义（analogReadPin 直接用引脚名读取，无需额外配置）
// 在代码中直接用 A0, A1, B0 等引脚名调用 analogReadPin()

// analogReadPin() 返回当前引脚的 ADC 原始值
// STM32F103（12-bit）：0-4095
// RP2040（12-bit）：0-4095
// Atmega32u4（10-bit）：0-1023

void matrix_scan_user(void) {
    uint16_t val = analogReadPin(A0);   // 直接用引脚名读取
    // val 即为当前电位器位置对应的模拟值
}

// 12-bit → 7-bit 映射：右移 5 位（4096 >> 5 = 128），比乘除法快得多
uint8_t midi_val = (uint8_t)(adc_val >> 5);

// 如果电位器安装方向与 MIDI 值方向相反，用反转：
uint8_t midi_val = 0x7F - (uint8_t)(adc_val >> 5);

// 单周期 16 次过采样：噪声降为 1/4，无跨周期拖影
uint16_t oversample16(uint8_t pin) {
    uint32_t sum = 0;
    for (uint8_t i = 0; i < 16; i++) sum += analogReadPin(pin);
    return (uint16_t)(sum >> 4);
}

// 12-bit → 7-bit：右移 5 位（4096 >> 5 = 128），端点钳位
uint8_t to7bit(uint16_t v) {
    uint8_t cc = (uint8_t)(v >> 5);
    return (cc > 127) ? 127 : cc;
}

// 死区：7-bit 值真正变化才发送，静止时零毛刺
static uint8_t last_cc[NUM_SLIDERS];

void slider(void) {
    for (int i = 0; i < NUM_SLIDERS; i++) {
        uint16_t raw = oversample16(adcPins[i]);
        uint8_t cc = to7bit(raw);
        if (cc != last_cc[i]) {
            midi_send_cc(&midi_device, 2, sliders[i].midiControlNumber, cc);
            last_cc[i] = cc;
        }
    }
}

#include QMK_KEYBOARD_H
extern MidiDevice midi_device;

#define FILTER_WINDOW_SIZE 8       // 滑动平均滤波窗口大小
#define NUM_SLIDERS 10             // 推子数量
#define ADCVar 30                  // 变化阈值（12-bit 下推荐 20-40）

// 用结构体管理每个推子的所有数据
typedef struct {
    uint16_t adcReadings[FILTER_WINDOW_SIZE]; // 独立的滤波缓冲区
    uint8_t  readingIndex;
    uint32_t readingSum;
    uint16_t filteredValue;
    uint16_t lastSentValue;
    uint8_t  midiControlNumber;   // 为该推子指定 MIDI CC 编号
} SliderChannel;

// 初始化推子数组，每个推子指定不同的 CC 编号
SliderChannel sliders[NUM_SLIDERS] = {
    { {0}, 0, 0, 0, 0, 0x0A },    // CC#10
    { {0}, 0, 0, 0, 0, 0x09 },    // CC#9
    { {0}, 0, 0, 0, 0, 0x08 },    // CC#8
    { {0}, 0, 0, 0, 0, 0x07 },    // CC#7（主音量）
    { {0}, 0, 0, 0, 0, 0x06 },    // CC#6
    { {0}, 0, 0, 0, 0, 0x05 },    // CC#5
    { {0}, 0, 0, 0, 0, 0x04 },    // CC#4
    { {0}, 0, 0, 0, 0, 0x03 },    // CC#3
    { {0}, 0, 0, 0, 0, 0x02 },    // CC#2
    { {0}, 0, 0, 0, 0, 0x01 }     // CC#1
};

// 对应的 ADC 引脚数组
const uint32_t adcPins[NUM_SLIDERS] = { A0, A1, A2, A3, A4, A5, A6, A7, B0, B1 };

// 滑动平均滤波：维护一个环形缓冲区，O(1) 更新
uint16_t movingAverageFilter(SliderChannel* channel, uint16_t newReading) {
    channel->readingSum = channel->readingSum
                        - channel->adcReadings[channel->readingIndex]
                        + newReading;
    channel->adcReadings[channel->readingIndex] = newReading;
    channel->readingIndex = (channel->readingIndex + 1) % FILTER_WINDOW_SIZE;
    return (uint16_t)(channel->readingSum / FILTER_WINDOW_SIZE);
}

// 防抖判断：变化超过阈值 OR 到达端点（解决推到底/顶时抖动发不出信号）
int shouldSendMIDI(SliderChannel* channel) {
    uint16_t change = abs(channel->filteredValue - channel->lastSentValue);

    // 主要条件：变化超过阈值
    if (change >= ADCVar) return 1;

    // 辅助条件：确保能到达端点，但避免端点附近微小抖动反复发送
    // 只有上次值离端点较远、当前值非常接近端点时才触发
    if (channel->filteredValue < 5 && channel->lastSentValue > 10) return 1;     // 接近 0
    if (channel->filteredValue > 4090 && channel->lastSentValue < 4080) return 1; // 接近 4095

    return 0;
}

void slider(void) {
    for (int i = 0; i < NUM_SLIDERS; i++) {
        // 1. 读取并滤波（每个通道独立滤波器）
        uint16_t rawValue = analogReadPin(adcPins[i]);
        sliders[i].filteredValue = movingAverageFilter(&sliders[i], rawValue);

        // 2. 判断是否需要发送
        if (shouldSendMIDI(&sliders[i])) {
            // 3. 右移 5 位映射到 0-127，0x7F- 反转方向
            uint8_t midiValue = 0x7F - (sliders[i].filteredValue >> 5);
            // 4. 发送到通道 3（索引 2）
            midi_send_cc(&midi_device, 2, sliders[i].midiControlNumber, midiValue);
            sliders[i].lastSentValue = sliders[i].filteredValue;
        }
    }
}

void matrix_scan_user(void) {
    slider();
}

ENCODER_ENABLE = yes

#define ENCODERS_PAD_A { B12 }            // 第一个编码器的 A/B 引脚
#define ENCODERS_PAD_B { B13 }
#define ENCODER_RESOLUTION 4               // 每格 4 步（EC11 默认）

bool encoder_update_user(uint8_t index, bool clockwise) {
    if (clockwise) {
        tap_code(KC_VOLU);              // 顺时针：音量+
    } else {
        tap_code(KC_VOLD);              // 逆时针：音量-
    }
    return false;
}

MIDI_ENABLE = yes

// 定义高级模式，启用 midi_send_* API（自定义信号必需）
#define MIDI_ADVANCED

// 可选：调整发送力度等默认参数
#define MIDI_VELOCITY_MIN 0             // 最小力度（默认 0）
#define MIDI_VELOCITY_MAX 127           // 最大力度（默认 127）
#define MIDI_VELOCITY_DEFAULT 100       // 默认力度（默认 127）

// 声明 QMK 全局 MIDI 设备实例（自定义信号必需）
extern MidiDevice midi_device;

enum custom_keycodes {
    CAM1 = SAFE_RANGE,   // 镜头 1
    CAM2,                // 镜头 2
};

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    switch (keycode) {
        case CAM1:
            if (record->event.pressed) {
                // 按下：通道 1 发送 Note 60 (C3)，力度 127
                midi_send_noteon(&midi_device, 0, 60, 127);
            } else {
                // 松开：发送 Note Off 结束
                midi_send_noteoff(&midi_device, 0, 60, 0);
            }
            return false;
        case CAM2:
            if (record->event.pressed) {
                midi_send_noteon(&midi_device, 0, 61, 127);
            } else {
                midi_send_noteoff(&midi_device, 0, 61, 0);
            }
            return false;
    }
    return true;
}

// 8 路通道切换：Note 60-67 对应通道 1-8
enum custom_keycodes {
    CHAN1 = SAFE_RANGE,
    CHAN2, CHAN3, CHAN4,
    CHAN5, CHAN6, CHAN7, CHAN8,
};

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    // 计算偏移：CHAN1=0, CHAN2=1, ..., CHAN8=7
    if (keycode >= CHAN1 && keycode <= CHAN8) {
        uint8_t offset = keycode - CHAN1;       // 0-7
        uint8_t note   = 60 + offset;            // 60-67
        if (record->event.pressed) {
            midi_send_noteon(&midi_device, 0, note, 127);
        } else {
            midi_send_noteoff(&midi_device, 0, note, 0);
        }
        return false;
    }
    return true;
}

// 单个旋钮控制通道 1 主音量（CC 7）
static uint8_t chan1_volume = 64;   // 当前音量值（0-127）

bool encoder_update_user(uint8_t index, bool clockwise) {
    if (index == 0) { // 第一个编码器
        if (clockwise) {
            chan1_volume = (chan1_volume < 127) ? chan1_volume + 1 : 127;
        } else {
            chan1_volume = (chan1_volume > 0) ? chan1_volume - 1 : 0;
        }
        // 发送 CC 7（主音量）到通道 1
        midi_send_cc(&midi_device, 0, 7, chan1_volume);
    }
    return false;
}

// 4 路推子：编码器 0-3 分别控制通道 1-4 的音量（CC 7）
static uint8_t fader_values[4] = {64, 64, 64, 64};

bool encoder_update_user(uint8_t index, bool clockwise) {
    if (index < 4) { // 只处理前 4 个编码器
        if (clockwise) {
            fader_values[index] = (fader_values[index] < 127) ? fader_values[index] + 1 : 127;
        } else {
            fader_values[index] = (fader_values[index] > 0) ? fader_values[index] - 1 : 0;
        }
        // 发送 CC 7（主音量）到对应通道（index 0-3 对应通道 1-4）
        midi_send_cc(&midi_device, index, 7, fader_values[index]);
    }
    return false;
}

{
  "manufacturer": "YourName",
  "keyboard_name": "mykeyboard",
  "maintainer": "YourName",

  // ① 主控与 Bootloader：只在这里定义，rules.mk 里不要再写
  "processor": "STM32F411",
  "bootloader": "apm32-dfu",

  // ② 编译层：固件里要不要编入 NKRO 代码
  "features": {
    "nkro": true,
    "extrakey": true,        // 其余功能照原样保留，不要整块覆盖
    "mousekey": false
  },

  // ③ 运行时默认值：开机是否直接进 NKRO（不要这一块 = 开机 6KRO）
  "host": {
    "default": { "nkro": true }
  },

  "usb": {
    "device_version": "1.0.0",
    "pid": "0x0001",
    "vid": "0xFEED"
  },

  "matrix_pins": {
    "cols": ["B1", "B0", "A7", "A6", "A5"],
    "rows": ["B15", "A8", "B3", "A15"]
  },

  "layouts": {
    "LAYOUT": { "layout": [ /* 键位坐标，按你自己的填 */ ] }
  }
}

// 加在顶层（和 "processor" 同级）
"features": { "nkro": true },

// 只想「可切换」就到此为止；要「开机即 NKRO」再加这一段
"host": { "default": { "nkro": true } }

# 板级定义
MCU = STM32F411
BOARD = GENERIC_STM32_F411XE
MCU_LDSCRIPT = STM32F411xE
BOOTLOADER = apm32-dfu

# 编译层开关：等价于 keyboard.json 的 "features": {"nkro": true}
NKRO_ENABLE = yes

// 等价于 keyboard.json 的 "host": {"default": {"nkro": true}}
// 注意：这一行只能写在 config.h，不能写在 rules.mk（rules.mk 只认变量，不认 C 宏）
#define NKRO_DEFAULT_ON true

void send_keyboard_report(void) {
#ifdef NKRO_ENABLE
    if (host_can_send_nkro() && keymap_config.nkro) {
        send_nkro_report();
        return;
    }
#endif
    send_6kro_report();
}

bool host_can_send_nkro(void) {
    return usb_device_state_get_protocol() == USB_PROTOCOL_REPORT;
}

🧰 九、故障排查速查

按症状定位，先查最常见原因，再跳对应章节细读。本表持续补充。

📦 十、本站资源下载汇总