QMK Firmware 2020 年 11 月 28 日 Breaking Change 发布说明键盘迁移、核心新特性与构建流程解读【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK Firmware 每年执行四次 Breaking Change 合并流程2020 年 11 月 28 日的这次发布集中体现了向后兼容 主动演进的平衡策略一方面迁移了 Helix、Speedo、Maartenwut、Xelus 等键盘的目录结构与构建目标另一方面在核心层面引入了 16-bit 摇杆、RGB 矩阵指示器、步进音序器等新特性。本文以 docs/ChangeLog/20201128.md 为主线结合当前仓库源码逐条说明需要用户手动操作的改动、核心新增能力、底层实现原理与验证方法帮助你安全升级固件树而不破坏既有键映射。什么是 QMK 的 Breaking Change 流程QMK 将任何以不兼容或存在潜在风险的方式改变 QMK 行为的改动定义为 Breaking Change。为了给用户确定性这类改动被限制在每年四次集中合并而不是随时流入主线。这样做的直接收益是用户更新 QMK 代码树时可以预期自己的键映射不会因为日常小改动而意外失效。本次发布对应 2020 年 11 月 28 日这一批合并文档位于 docs/ChangeLog/20201128.md包含两大板块Changes Requiring User Action需要用户手动操作的改动主要是键盘目录结构迁移、构建目标改名涉及 Helix、Speedo、Maartenwut现 evyd13、Xelus 四个系列Core Changes核心改动包括问题修复、新特性增加、代码清理与 QMK 基础设施构建系统、ChibiOS 升级、CLI 工具改动。下面先从最直接影响日常构建命令的键盘迁移讲起。需要用户操作的改动键盘目录与构建目标迁移Helix 键盘构建变体精简PR #8669Helix 是本次迁移中受影响面最大的键盘。迁移的核心思路是消除构建变体的冗余命名让helix/rev1、helix/rev2与helix/pico保持稳定同时把带sc滚动轮/scratch后缀的变体按back、under、oled选项重新归位。迁移后的构建命令格式保持为make helix_build_name:keymap_name其中helix_build_name必须使用下表最右列Nov 28 2020的取值例如helix、helix/pico。2019-10-17 之前2019-10-172020-03-102020-11-28本次helix/rev1helix/rev1helix/rev1helix/rev1helix/picohelix/picohelix/picohelix/picohelix/pico/backhelix/pico/backhelix/pico/backhelix/pico/underhelix/pico/underhelix/pico/underhelix/pico/sc--helix/pico/sc/backhelix/pico/schelix/pico/sc/under--helix/rev2 (helix)helix/rev2 (helix)helix/rev2 (helix)--helix/rev2/backhelix/rev2/back--helix/rev2/back/oledhelix/rev2/back/oled( -- helix/rev2/back)helix/rev2/oledhelix/rev2/oledhelix/rev2 (helix)helix/rev2/oled/backhelix/rev2/oled/backhelix/rev2/backhelix/rev2/oled/underhelix/rev2/oled/underhelix/rev2/underhelix/rev2/sc--helix/rev2/sc/back--helix/rev2/sc/oled--helix/rev2/sc/oledbackhelix/rev2/schelix/rev2/sc/oledunder--helix/rev2/sc/under--helix/rev2/underhelix/rev2/under--helix/rev2/under/oledhelix/rev2/under/oled( -- helix/rev2/under)解读这张表的关键点helix等价于helix/rev2rev2被确立为默认修订版本直接写make helix:default即可helix/rev2作为独立构建目标在本次发布中删除。选项后缀语义收敛back底板 RGB、under底面灯、oledOLED 屏可以组合但组合顺序和冗余组合被大幅精简。例如旧目标helix/rev2/back/oled与helix/rev2/oled/back统一归并为helix/rev2/backOLED 成为该变体的默认配置同理helix/rev2/under/oled归并为helix/rev2/under。scscroll/滚动轮系列收敛helix/pico/sc与helix/rev2/sc成为该系列唯一保留目标原来带有back、under、oled、oledback等组合的多个sc变体被移除。从当前仓库目录看迁移后的结构为 keyboards/helix包含beta/、pico/、rev3/等子目录其中 keyboards/helix/pico 下有config.h、keyboard.json与keymaps/keyboards/helix/rev3 同样采用keyboard.json组织构建信息——这正是本次迁移所确立的每个构建变体一个目录 数据驱动配置形态的延续。升级动作如果你之前使用helix/rev2/sc/oledback、helix/pico/sc/under这类组合目标需要对照上表改写为对应的新目标名再执行make 新目标:keymap验证编译通过。Speedo 固件更新至 v3.0PR #10657Speedo 键盘因设计师准备发布 v3.0固件目录迁移到cozykeys/speedo/命名空间下原名称新名称speedocozykeys/speedo/v2--cozykeys/speedo/v3新增仓库当前结构印证了这一迁移keyboards/cozykeys/speedo 下存在readme.md、v2/、v3/其中 keyboards/cozykeys/speedo/v2 使用keyboard.json描述构建配置。若你此前以speedo为目标构建请改为make cozykeys/speedo/v2:keymap需要新硬件支持则用make cozykeys/speedo/v3:keymap。Maartenwut 品牌更名为 evyd13PR #10274Maartenwut 整体更名为 evyd13所有已发布的键盘随之迁移目录。完整迁移清单如下原名称新名称maartenwut/atom47/rev2evyd13/atom47/rev2maartenwut/atom47/rev3evyd13/atom47/rev3maartenwut/eon40evyd13/eon40maartenwut/eon65evyd13/eon65maartenwut/eon75evyd13/eon75maartenwut/eon87evyd13/eon87maartenwut/eon95evyd13/eon95maartenwut/gh80_1800evyd13/gh80_1800maartenwut/gh80_3700evyd13/gh80_3700maartenwut/minitomicevyd13/minitomicmaartenwut/mx5160evyd13/mx5160maartenwut/nt660evyd13/nt660maartenwut/omrontklevyd13/omrontklmaartenwut/plain60evyd13/plain60maartenwut/pockettypeevyd13/pockettypemaartenwut/quackfireevyd13/quackfiremaartenwut/solheim68evyd13/solheim68maartenwut/ta65evyd13/ta65maartenwut/wasdatevyd13/wasdatmaartenwut/wasdat_codeevyd13/wasdat_codemaartenwut/wonderlandevyd13/wonderland仓库 keyboards/evyd13 已包含上表中的atom47/、eon40/、eon65/、eon75/、eon87/、eon95/、gh80_1800/、gh80_3700/、minitomic/、mx5160/、nt660/、omrontkl/、plain60/、pockettype/、quackfire/、solheim68/、ta65/、wasdat/、wasdat_code/、wonderland/等目录与文档迁移表一一对应。升级时把键映射从旧目录整体复制到新目录即可键映射代码本身无需改动。Xelus Valor 与 Dawn60 重构PR #10512、#10584Xelus22 的 Valor 与 Dawn60 现在都要求编译时指定修订版本原名称新名称xelus/dawn60xelus/dawn60/rev1xelus/valorxelus/valor/rev1仓库中 keyboards/xelus/dawn60 下存在rev1/与rev1_qmk/子目录keyboards/xelus 下另有valor/、valor_frl_tkl/等目标均证实了修订版本目录化的落地。构建命令相应变为make xelus/dawn60/rev1:keymap与make xelus/valor/rev1:keymap。AEboards EXT65 代码库重构PR #10820EXT65 的代码库被重构为一套键映射可同时用于两个修订版本的组织方式属于代码库内部重组无需用户修改构建命令但需要重新拉取最新固件树后才能编译新键映射。核心改动问题修复本次发布包含两个值得关注的问题修复从键盘唤醒电脑后重连 USB 以恢复 USB 状态PR #10088当键盘作为唤醒源唤醒主机时主动重连 USB避免主机端 USB 状态机处于异常状态导致设备枚举失败。这属于电源管理链路上的健壮性修复对使用键盘开机的用户有直接体验改善。修复 oled_write_raw 系列函数的光标位置 bugPR #10800oled_write_raw相关函数此前在写入原始数据时存在光标位置计算错误可能导致显示内容偏移。OLED 相关的实现位于 drivers/oled修复后原始帧缓冲写入的位置语义与普通文本写入保持一致。核心改动新增特性与增强矩阵行数突破 32 限制PR #10183MATRIX_ROWS此前受限于 32 行本次发布放开该限制为大型矩阵例如超过 32 行扫描线的拼接键盘铺平道路。矩阵扫描相关代码位于 quantum/matrix.c 及 quantum/matrix.h配置项MATRIX_ROWS与MATRIX_COLS在 docs/config_options.md 中有详细说明。若键盘硬件行数超过 32升级后可移除此前不得已的分割方案。ATmega32U2 软串口支持PR #10204为 ATmega32U2 增加软串口soft serial支持用于廉价的双片拆分键盘split keyboard主从通信。串口驱动接口见 drivers/serial.h同时 PR #10706 为serial.c增加了 AT90USB 系列支持进一步扩大了软串口方案的 MCU 覆盖范围。MIDI 力度值直接控制PR #9940允许直接控制 MIDI velocity力度值而不再依赖按键扫描的隐式映射。MIDI 相关处理集中在 quantum/process_keycode 下的process_midi.c本次改动让键映射可以通过代码直接设定音符力度便于制作更细腻的 MIDI 键盘输出。摇杆 16-bit 支持PR #10439Joystick 特性升级到 16-bit 精度。从 quantum/joystick.h 可以看到摇杆轴分辨率的定义方式配置JOYSTICK_AXIS_RESOLUTION即可按需设定轴分辨率默认 8 位可提升到 16 位以获得更平滑的模拟输入并配合JOYSTICK_BUTTON_COUNT定义按键数量。对于游戏输入或模拟摇杆外设这一改动直接提升了输入精度上限。编码器分辨率可逐编码器设置PR #10259编码器encoder的分辨率即每次 detent 步进对应的脉冲数常见为 4不再要求全局统一可以按每个编码器单独配置。编码器驱动位于 drivers/encoder结合ENCODER_RESOLUTIONS配置可让同一键盘上的不同旋钮拥有不同手感与步进。鼠标键状态共享给 pointing_devicePR #10179将 mousekey 的按键状态共享给 pointing_device使轨迹球、触摸板等定点设备与鼠标键功能在状态管理上统一避免二者互斥或状态丢失。相关实现位于 quantum/pointing_device其驱动文件位于 drivers/sensors。RGB 矩阵高级/高效指示器PR #8564为 RGB 矩阵新增 advanced/efficient 指示器indicators能力允许 Caps Lock、层状态等以更高效的方式呈现在 RGB 灯效上。RGB 矩阵配置在config.h中通过RGB_MATRIX_ENABLE与驱动选择启用见下文 PR #10231 的拆分说明实现代码位于 quantum/rgb_matrix。OLED 显示更新间隔支持PR #10388新增OLED_UPDATE_INTERVAL配置项可控制 OLED 的帧更新间隔单位毫秒默认约为 10ms 的刷新节奏。降低更新间隔可节省 CPU 时间与 I²C 总线占用提高间隔则显示更流畅。OLED 驱动位于 drivers/oled屏幕状态与配置说明可参考 docs/feature_advanced_keycodes.md 之外专门的 OLED 文档。逐键 Retro TappingPR #10622Retro Tapping 支持按按键独立开启。相关宏RETRO_TAPPING_PER_KEY在 docs/config_options.md 中有记录其处理逻辑位于 quantum/action_tapping.c该文件同时处理 tapping term、ignoring mod tap 等逐键行为。开启后你可以针对特定按键设置未在 tapping term 内释放时也触发 tap 动作的行为而其他按键保持默认。背光占空比上限PR #10260新增背光占空比上限配置BACKLIGHT_LIMIT_VAL等限制 PWM 背光的最亮占空比避免背光过亮、过热或在某些硬件上损坏 LED。背光驱动位于 drivers/backlight。步进音序器特性PR #9703新增步进音序器step sequencer特性让键盘可以作为简单的音序器使用。从仓库搜索可以看到SEQUENCER_ENABLE相关代码分布在 quantum/keyboard.c、quantum/quantum.c 与 quantum/quantum.h音序器相关的按键码处理位于process_keycode中。该特性面向音乐制作场景可在键映射中启用SEQUENCER_ENABLE后使用音序器按键码编排步进。新增 add_oneshot_mods 与 del_oneshot_modsPR #10549为 One Shot 修饰键新增两个运行时函数add_oneshot_mods与del_oneshot_mods用于在运行时动态添加/删除 One Shot 修饰键便于宏或层切换逻辑中临时启用一次性 Shift、Ctrl 等。相关状态管理位于 quantum/action_util.c 与 quantum/action_util.h。Auto Shift 支持重复与提前注册PR #9826Auto Shift自动 Shift特性新增对重复按键与提前注册的支持减少快速连打时的丢字与错位问题。处理逻辑位于 quantum/process_keycode/process_auto_shift.c。核心改动清理与优化Haptic 与 solenoid 清理PR #9700统一触觉反馈与电磁阀solenoid驱动的代码结构相关驱动位于 drivers/haptic。XD75 清理PR #10524整理 XD75 键盘代码。允许显示更新在任务 tick 之间继续PR #10750对 OLED 等显示更新时序做了微调避免显示更新被严格限制在任务周期内。matrix.c 中部分 GPIO 操作改为原子操作PR #10491矩阵扫描中的 GPIO 读写改为原子操作减少中断竞争导致的扫描抖动提升高扫描率下配合DEBUG_MATRIX_SCAN_RATE观察的稳定性。合并 ATmega32U2 / ATmega16U2 / ATmega328 / ATmega328P 重复代码PR #10837减少 AVR 系列底层驱动重复相关代码分布在 platforms 与 tmk_core。移除 HD44780 相关引用PR #10735清理过时的 HD44780 LCD 引用相关 LCD 驱动位于 drivers/lcd。QMK 基础设施与内部改动本次发布的基础设施改动影响面广但多数对普通用户透明按平台构建键盘子集PR #10420构建系统支持只构建指定 MCU 平台AVR / ARM的键盘子集配合qmk compile的键盘过滤选项使用适合大规模 CI 或按目标平台批量编译的场景。EEPROM 驱动在启动时初始化PR #10438EEPROM 驱动从首次使用时初始化改为启动时初始化确保依赖 EEPROM 的特性如键映射持久化、magic 键、EEPROM数据层在生命周期内行为一致相关驱动见 drivers/eeprom。ChibiOS bootloader_jump 弱化PR #10417将 bootloader jump 函数改为 weak 定义便于各板级文件覆盖相关代码在 platforms/chibios。STM32 GPIOF/G/H/I/J/K 支持PR #10206扩展 STM32 GPIO 端口的支持范围为更大引脚数的板卡提供底层能力。milc 作为依赖引入并移除已安装版本PR #10563CLI 库 milc 改为依赖声明方式引入规范 Python CLI 依赖管理。ChibiOS 升级早期初始化转换PR #10214与配置文件迁移器PR #9952为 ChibiOS 版本升级配套的早期初始化改造与 halconf/mcuconf 配置迁移工具相关说明见 docs/chibios_upgrade_instructions.md。基于当前所选串口驱动添加宏定义PR #10716为串口驱动选择提供编译期宏供上层代码区分驱动实现。允许修改 rgblight/rgb_matrix 的输出 RGB 值PR #10638在灯效输出前提供修改 RGB 值的钩子便于自定义色彩调整。允许键盘/键映射在主循环每次迭代执行代码PR #10530为键盘/键映射提供 per-loop 钩子可执行周期性任务如状态轮询。qmk cformatPR #10767新增qmk cformat命令自动格式化 C 代码统一代码风格相关 CLI 文档见 docs/cli_commands.md。DEBUG_MATRIX_SCAN_RATE 命令行开关PR #10824新增 Make 变量可在命令行直接make ... DEBUG_MATRIX_SCAN_RATEyes开启矩阵扫描率调试输出。ChibiOS USB OTG 驱动更新PR #8893更新 ChibiOS USB 对 OTG 驱动的支持。修复 SKIP_VERSIONyes 时 version.h 写入问题PR #10972、#10974修复使用SKIP_VERSIONyes跳过版本信息时version.h仍被错误写入的问题。ledmatrix.h 重命名对齐 .c 文件PR #7949头文件名与实现文件名对齐。拆分 RGB_MATRIX_ENABLE 为 _ENABLE 与 _DRIVERPR #10231将RGB_MATRIX_ENABLE拆分为RGB_MATRIX_ENABLE启用特性与RGB_MATRIX_DRIVER选择驱动如RGB_MATRIX_DRIVER IS31FL3731使驱动选择更显式RGB 矩阵实现位于 quantum/rgb_matrix驱动文件在 drivers/led。拆分 LED_MATRIX_ENABLE 为 _ENABLE 与 _DRIVERPR #10840对 LED 矩阵采用同样的拆分方式LED 矩阵实现位于 quantum/led_matrix。升级与验证建议结合本次发布内容建议按以下步骤完成升级更新代码树拉取包含本次 Breaking Change 合并的最新 QMK 固件树。对照迁移表改写构建命令重点检查 Helixkeyboards/helix、Speedokeyboards/cozykeys/speedo、Maartenwut→evyd13keyboards/evyd13、Xeluskeyboards/xelus四类目标名按上文表格逐一替换。迁移键映射目录将被改名的键盘的keymaps目录复制到新路径如keyboards/evyd13/board/keymaps/your_name键映射内容一般无需修改。处理配置项拆分若使用 RGB 矩阵或 LED 矩阵确认config.h中已按_ENABLE/_DRIVER拆分方式填写参考 docs/config_options.md 与对应的驱动文档。验证编译对每个受影响键盘执行make 目标:keymap确认编译通过后刷写如需观测矩阵扫描性能可加DEBUG_MATRIX_SCAN_RATEyes运行。关注新增配置项如使用 OLED、RGB 矩阵、编码器、摇杆或步进音序器可参考上文所述配置项OLED_UPDATE_INTERVAL、BACKLIGHT_LIMIT_VAL、ENCODER_RESOLUTIONS、JOYSTICK_AXIS_RESOLUTION、SEQUENCER_ENABLE等按需开启。小结2020 年 11 月 28 日的 Breaking Change 发布是 QMK 在兼容性承诺与持续演进之间的一次典型实践通过集中式迁移表把 Helix 的构建变体从近二十个收敛到十余个通过品牌更名与目录重组统一了 evyd13 与 cozykeys 的命名空间同时在核心层落地了 16-bit 摇杆、逐键 Retro Tapping、OLED 更新间隔、步进音序器等一批有实感的增强。对普通用户而言升级要点集中在构建目标名的改写与_ENABLE/_DRIVER配置拆分对开发者而言PR #10231/#10840 的配置拆分、PR #10183 的矩阵行数放开与 PR #10530 的 per-loop 钩子则奠定了后续若干版本的功能基础。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考