QMK Firmware 2024-08-25 版本变更全解析VIA 键位图迁移、Key Override 签名变更与传感器固件上传调整【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware2024 年 8 月的 QMK 固件是一次以清理与重组为主线的维护性发布但其中包含若干要求用户动手修改的破坏性变更Breaking ChangesVIA 启用键位图整体迁出 QMK 仓库、Key Override 在keymap.c中的声明签名变更、SparkFun Pro Micro RP2040 转换器更名以及 ADNS9800 / PMW33xx 传感器固件 ROM 上传改为显式 opt-in。本文完整解读该周期变更文档 docs/ChangeLog/20240825.md 的全部核心内容并结合当前仓库源码逐项佐证帮助你在升级固件后正确迁移键位图、修正编译错误并理解每项变更背后的动机。本周期定位一次大规模代码清理与重组发布变更文档开篇即说明2024 年 8 月的维护发布中绝大多数 PR 都是对既有功能与代码的清理或重组而非新增功能。从完整变更清单的结构可以印证这一点——Relocate VIA logicMigrate ... to DD (Data Driven)Refactor 类条目占了键盘相关变更的相当比例。本周期最有影响力的单一事项是QMK 仓库中不再保留任何via启用via-enabled的键位图——它们已全部迁移至由 VIA 团队维护的 External Userspace 外部仓库。今后向qmk_firmware提交的 PR 一律不得包含via键位图应改投 VIA 团队的外部 Userspace 仓库。如果你使用 VIA 协议在固件中做运行时键位编辑这是本周期最重要的变更后文VIA 键位图迁移一节会展开说明迁移路径与注意事项。变更要求用户行动键盘代码库更名以下三个键盘的名称在本周期发生变更。一个重要的好消息是使用 External Userspace 构建时历史键盘名称依然被视为有效——如果你已经在用 External Userspace仓库内的键位图目录不需要移动旧键盘名新键盘名dnworks/9973dnworks/tkl87maple_computing/lets_split_eh/ehmaple_computing/lets_split_ehplanck/ez/basezsa/planck_ez/base在当前仓库中可以直接验证这些新路径的存在keyboards/dnworks/tkl87、keyboards/maple_computing/lets_split_eh、keyboards/zsa/planck_ez 目录均已就位。值得注意的命名逻辑lets_split_eh去掉了多余的eh子目录层级对应变更清单中 Remove DEFAULT_FOLDER from maple_computing/lets_split_ehPR #24054Planck EZ 则从独立目录 keyboards/planck该目录仍承载主 Planck 键盘的各硬件版本如rev1–rev7、rev7等整体迁入了 ZSA 厂牌目录 keyboards/zsa 下的planck_ezPR #23917 Move Planck EZ to ZSA vendor folder。按厂商归组更符合 QMK 键盘目录的组织惯例。对于主仓库in-repo构建的用户这三个旧名称对应的构建路径在升级后需要按新名称重新组织或改用qmkCLI 重新生成键位图。SparkFun Pro Micro RP2040 转换器更名RP2040 平台的 SparkFun Pro Micro RP2040 转换器名称由promicro_rp2040变更为sparkfun_rp2040PR #24192旧名称新名称promicro_rp2040sparkfun_rp2040更名动机是消除歧义市面上存在大量以 ProMicro RP2040 命名的克隆板它们与正主 SparkFun Pro Micro RP2040 的引脚兼容性并不相同克隆板应当使用rp2040_ce转换选项。从构建系统角度看转换器名称直接参与 Make 变量推导builddefs/converters.mk 中CONVERT_TO变量通过 glob 匹配$(PLATFORM_PATH)/*/converters/$(PIN_COMPATIBLE)_to_$(CONVERT_TO)/目录来定位转换器定义匹配成功后注入-DCONVERT_TO_NAME、-DCONVERTER_TARGETname、-DCONVERTER_ENABLED等编译宏并包含该目录下的converter.mk匹配失败则直接触发 Converting to ... not possible 的灾难性错误。因此转换器的字符串名称是构建入口的一等公民——一旦更名键位图config.h中CONVERT_TO的取值就必须同步更新否则构建会在早期中止。Key Override 的keymap.c签名变更为了让 Key Override 接入键位图内省keymap introspection系统本周期调整了 Key Override 的数据结构约定。如果你在自己的keymap.c中使用了 Key Override必须做两处修改把列表类型从指向指针数组的指针 NULL 哨兵改为直接声明指针数组同时移除NULL结尾项。变更前const key_override_t **key_overrides (const key_override_t *[]){ my_override_1, my_override_2, NULL };变更后const key_override_t *key_overrides[] { my_override_1, my_override_2, };为什么这样改原写法中key_overrides是const key_override_t **二级指针数组长度只能依赖NULL哨兵值线性扫描确定改为直接的const key_override_t *[]数组后长度可由sizeof在编译期确定框架无需哨兵即可安全遍历——这正是把它接入内省系统的前提。同一套内省机制在本周期还扩展到了 Tap DancePR #24049 Tap dance introspection。从源码结构看Key Override 的处理当前位于 quantum/process_keycode/process_key_override.h 所在的键码处理流程中内省使框架能在运行时枚举用户定义了哪些 Key Override / Tap Dance从而支撑不依赖编译期固定数量的新特性例如同期合入的动态宏回调PR #24142 Dynamic macro callbacks。如果你没有使用 Key Override此项变更对你是无感的。ADNS9800 与 PMW33xx 传感器固件上传改为 opt-in由于许可兼容性存在歧义QMK 将 ADNS9800 与 PMW33xx 系列指点设备传感器滚轮/轨迹球常见型号的固件 ROM 上传临时改为 opt-in并计划最终移除。历史上这些固件是默认包含并自动上传的本周期起默认不再上传。变更文档同时说明QMK 团队已对各型号传感器逐一测试传感器在不重新上传固件的情况下似乎仍可正常工作传感器片内自带固件但这一验证并非 100% 穷尽。如果你的传感器在升级后停止工作请通过官方渠道联系 QMK 团队反馈。要在自己的构建中重新启用固件上传在键位图的config.h中添加对应宏定义传感器宏定义ADNS9800#define ADNS9800_UPLOAD_SROMPMW33xx#define PMW33XX_UPLOAD_SROM对应的驱动源码位于 drivers/sensors/adns9800.c 与 drivers/sensors/pmw33xx_common.cPMW33xx 系列另有pmw3320.c、pmw3325.c、pmw3360.c、pmw3389.c等分型号驱动均位于 drivers/sensors 目录。弃用通知Deprecation Notices按 弃用策略中的通知期限规定本周期发布了两项较大条目的弃用通知VIA 键位图迁归 VIA 团队管理上一个变更周期见 docs/ChangeLog/20240526.md 的 Migration of VIA keymaps to VIA team control 一节QMK 团队已预告via键位图将移交给 VIA 团队。截至本周期所有via启用的键位图应改向 VIA 团队维护的外部 Userspace 仓库提交 PR任何针对qmk_firmware的既有或新开 PR都会在被要求移除其中via启用的键位图后才被接受。仓库侧的落地动作见完整变更清单末条Remove all via-enabled keymaps, includingviaPR #24322此前还有一批 Relocate ... VIA logic 的 PR#24006、#24008、#24009、#24011、#24016先把 m256wh、winry315、m256ws、work_louder、xelus/pachi/rgb/rev2 等键盘的 VIA 专属逻辑从主仓库剥离。ADNS9800 与 PMW33xx 传感器固件 ROM 移除预告如前述QMK 与这些传感器历史上传的固件 blob 之间存在许可兼容问题。本通知明确告知用户这些固件 blob 几乎可以确定会在下一个 breaking changes 合并中被彻底移除。文档再次强调移除对设备功能似乎没有不利影响片内固件已足够若传感器失效请联系 QMK 团队。完整变更清单Full changelist以下为本周期变更文档给出的完整条目按原文分组完整继承便于逐项对照自己的构建是否受影响。CoreEEPROM无必要则不擦除新增eeprom_driver_format抽象层PR #18332生成 keymap 数据驱动键码到头文件PR #20273[wear_leveling] efl 更新PR #22489GC9xxx LCD 家族驱动GC9107 与 GC9A01PR #23091[build_test] 当DEBUG 0时设置CONSOLE_ENABLEyesPR #23097增强重叠鼠标键控制PR #23341APA102API 重构PR #23355[WIP] 为 SPI start/stop 引入总线获取/释放语义PR #23439新增 Farsi 键位 extrasPR #23650更新键盘自定义 matrix 中的原子 GPIO 宏PR #23796Pixel Fractal 灯效检查 LED 标志PR #23881为 tinyuf2 添加 STM32F405RG ld 脚本PR #23885SPI flash API 清理新增异步擦除能力PR #23894为新的 RGB Matrix 与 Underglow 键码添加process_keycode处理PR #23896将 VIA 与 STM32 L0/L1 EEPROM 实现解耦PR #23901规范化鼠标键码PR #23975移除已弃用的led_set_userPR #23979ADNS9800 与 PMW33XX 的 SROM 上传改为 opt-inPR #24001重命名编码器引脚宏定义PR #24003调整 ChibiOS 上挂起条件判断顺序PR #24020Tap Dance 内省PR #24049允许覆写get_hardware_id()PR #24051对齐 LUFA 挂起逻辑PR #24055新增 Key Override 内省支持PR #24120动态宏回调PR #24142promicro_rp2040转换器更名PR #24192重构 starlight RGB matrix 灯效PR #24202重构 riverflow RGB matrix 主循环PR #24203CLI移除键盘级 keymap 模板处理PR #24234keymap 生成的若干小调整PR #24240Keyboards重构 ncr80/r2PR #22670实现数据驱动的摇杆PR #22947新增键盘Whitefacemountain AmpersandPR #23437、TRKeyboard TRK1PR #23642、boardsource/the_qPR #23782、bear_face/v3PR #24032dnworks/9973更名为dnworks/tkl87PR #23692更新 Underglow 键码PR #23765BastardKB移除遗留板tbkPR #23818更新 ZSA MoonlanderPR #23911Planck EZ 迁入 ZSA 厂牌目录PR #23917大批量迁移到数据驱动DDSPLIT_HAND_PINPR #23924、SERIAL_DRIVERPR #23925、两块键盘的 RGB Matrix 布局PR #23963、多个led_update_kb实现PR #23980 / #23981 / #23983 / #23985、半双工SERIAL_USART_TX_PINPR #24143、split.soft_serial_pin迁到split.serial.pin的三批 O-ZPR #24146/ 0-HPR #24155/ H-OPR #24185移除split.transport.protocolserialPR #24191、移除无意义的RGB_MATRIX_LED_COUNTPR #24133、移除MASTER_LEFT实例PR #24163各键盘 VIA 逻辑外迁m256whPR #24006、winry315PR #24008、m256wsPR #24009、work_louderPR #24011、xelus/pachi/rgb/rev2PR #24016杂项清理与重构atreusPR #24010、hs60/v1拆分 ANSI/ISO 版本PR #24136、EC Type-K 更名PR #24180、matrix_scan_kb使用方式重构PR #24200、消除#include ../default/keymap.c用法PR #24215、移除键盘级QK_BOOT实现PR #24231、opendeck/32PR #24233、printedpadPR #24236、orthocodePR #24237重构、移除冗余 RGB Matrix 关机钩子PR #24238移除handwired/pytest/has_templatePR #24232移除所有 via 启用键位图包括via本身PR #24322Keyboard fixes修复 dogtag 的info.jsonPR #23520splitkb/kyria 移除键盘级CONVERT_TOPR #23857mt/mt84 修复PR #23883Planck rev7 编码器修复并支持ENCODER_MAP_ENABLEPR #23967handwired/swiftrax/bumblebee布局名修复PR #24064boardsource/the_q RGB matrix 坐标修复PR #24086两批回调未正确实现的键盘修复PR #24092、PR #24116移除对housekeeping_task_user的重复调用PR #24201handwired/dactyl_minidox修复PR #24253修复 zsa/moonlander 在DYNAMIC_MACRO_ENABLE下的构建失败PR #24316OthersLED 驱动从 LED/RGB Matrix 文档页抽取 LED 驱动文档PR #23630实现数据驱动的串口驱动PR #23923移除被跳过的 schema 文件PR #23987更新 RGBLightUnderglow键码命名PR #23999Bugs修复 arm_atsam 上的 NKRO 与鼠标仿真PR #23945强制dump_lines()始终使用 Unix 换行符PR #23954修复 home 链接PR #24068升级自查清单结合以上变更升级固件后建议按下列顺序自查是否使用 VIA 运行时键位编辑是则把键位图迁往 VIA 团队维护的 External Userspace 仓库主仓库构建中删除 via 相关键位图构建目标键盘是否在更名表中dnworks/9973、maple_computing/lets_split_eh/eh、planck/ez/base三个旧名需要换名External Userspace 用户可豁免是否在keymap.c声明了 Key Override按新签名改写并删掉NULL结尾构建是否基于 RP2040 板克隆板确认使用rp2040_ceSparkFun Pro Micro RP2040 正主板将CONVERT_TO从promicro_rp2040改为sparkfun_rp2040是否内置 ADNS9800 / PMW33xx 滚轮或轨迹球升级后若传感器失效先在config.h加回ADNS9800_UPLOAD_SROM或PMW33XX_UPLOAD_SROM验证并向 QMK 团队反馈。以上所有变更的原始依据均出自 docs/ChangeLog/20240825.md涉及弃用流程的读者可进一步阅读 docs/support_deprecation_policy.md 了解 QMK 的破坏性变更通知机制涉及外部键位图组织的可阅读 docs/newbs_external_userspace.md。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考