QMK Converters 转换器完全指南为键盘无缝更换兼容主控【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读本指南基于 QMK Firmware 官方文档docs/feature_converters.md编写系统讲解 QMK 的Converters转换器自动化机制——它允许你在不修改键盘固件源码的前提下把原本基于 Pro Micro、Elite-C 等 AVR 主控的键盘一键切换到 Proton C、RP2040 系列如 KB2040、Elite-Pi、Liatris等性能更强的替代主控。读完本文你将掌握通过命令行或 keymap 配置触发转换、理解转换的底层编译机制MCU/BOARD/BOOTLOADER 覆盖与引脚映射、根据目标主控调整外设驱动以及为键盘声明pin compatibility以解锁更多转换组合。Converters 是什么Converters转换器是 QMK 内置的一套自动化构建管线当你在编译/刷写命令中附加-e CONVERT_TOtarget时构建系统会读取键盘配置中声明的pin_compatible引脚兼容基类如promicro/elite_c在对应平台目录如 platforms/chibios/converters下寻找promicro_to_target或elite_c_to_target的转换定义目录应用该目录下的converter.mk覆盖 MCU、BOARD、BOOTLOADER 及默认外设驱动并通过_pin_defs.h提供 AVR 引脚名到目标平台引脚的映射注入CONVERT_TO_TARGET等编译宏供固件代码做条件编译。整个过程无需改动键盘本身的矩阵、键位布局等代码只需几行配置即可完成。快速上手如何触发一次转换方式一命令行参数最常用在任意编译或刷写命令后追加-e CONVERT_TOtarget即可。例如把 Keebio BDN9 rev1 转换为 Proton Cqmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TOproton_c方式二keymap 配置在 keymap 的keymap.json中声明converter字段或在rules.mk中写入CONVERT_TO效果与命令行参数一致{ version: 1, keyboard: keebio/bdn9/rev1, keymap: keebio_bdn9_rev1_layout_2025-05-20, converter: proton_c, layout: LAYOUT }CONVERT_TO proton_c从源码看QMK CLI 的 lib/python/qmk/cli/generate/rules_mk.py 会把 keymap.json 中的converter字段生成一行CONVERT_TO target写入生成的rules.mk随后由构建系统统一处理。提示如果遇到构建错误通常需要把键盘代码改造成与转换器兼容使用平台无关抽象或在 keymap 中补充额外的平台相关配置。当前支持的转换器清单转换器按声明的pin compatibility引脚兼容性分类只有合法的组合才会被尝试转换。构建系统在 builddefs/converters.mk 中通过$(wildcard $(PLATFORM_PATH)/*/converters/$(PIN_COMPATIBLE)_to_$(CONVERT_TO)/)查找转换目录找不到匹配目录时直接抛出Converting from ... to ... not possible!的致命错误从机制上保证组合有效性。从 Pro Micro 转换FromTopromicroproton_cpromicrokb2040promicrosparkfun_pm2040promicroblokpromicrobit_c_propromicrostemcellpromicrobonsai_c4promicrorp2040_cepromicroelite_pipromicroheliospromicroliatrispromicroimerapromicromichipromicrosvlinky从 Elite-C 转换FromToelite_cstemcellelite_crp2040_ceelite_celite_pielite_chelioselite_cliatrisPro Micro 系列转换详解如果一块键盘使用 Pro Micro或其兼容板作为主控QMK 支持转换为下列替代控制器。表中同时给出了 CLI 参数、rules.mk写法以及代码中可用的条件编译宏设备TargetCLI Argumentrules.mk条件宏Proton Cproton_c-e CONVERT_TOproton_cCONVERT_TOproton_c#ifdef CONVERT_TO_PROTON_CAdafruit KB2040kb2040-e CONVERT_TOkb2040CONVERT_TOkb2040#ifdef CONVERT_TO_KB2040SparkFun Pro Micro - RP2040sparkfun_pm2040-e CONVERT_TOsparkfun_pm2040CONVERT_TOsparkfun_pm2040#ifdef CONVERT_TO_SPARKFUN_PM2040Blokblok-e CONVERT_TOblokCONVERT_TOblok#ifdef CONVERT_TO_BLOKBit-C PRObit_c_pro-e CONVERT_TObit_c_proCONVERT_TObit_c_pro#ifdef CONVERT_TO_BIT_C_PROSTeMCellstemcell-e CONVERT_TOstemcellCONVERT_TOstemcell#ifdef CONVERT_TO_STEMCELLcustomMK Bonsai C4bonsai_c4-e CONVERT_TObonsai_c4CONVERT_TObonsai_c4#ifdef CONVERT_TO_BONSAI_C4RP2040 Community Editionrp2040_ce-e CONVERT_TOrp2040_ceCONVERT_TOrp2040_ce#ifdef CONVERT_TO_RP2040_CEElite-Pielite_pi-e CONVERT_TOelite_piCONVERT_TOelite_pi#ifdef CONVERT_TO_ELITE_PI0xCB Helioshelios-e CONVERT_TOheliosCONVERT_TOhelios#ifdef CONVERT_TO_HELIOSLiatrisliatris-e CONVERT_TOliatrisCONVERT_TOliatris#ifdef CONVERT_TO_LIATRISImeraimera-e CONVERT_TOimeraCONVERT_TOimera#ifdef CONVERT_TO_IMERAMichimichi-e CONVERT_TOmichiCONVERT_TOmichi#ifdef CONVERT_TO_MICHISvlinkysvlinky-e CONVERT_TOsvlinkyCONVERT_TOsvlinky#ifdef CONVERT_TO_SVLINKYProton C {#proton_c}Proton C 板载 LED 只有一颗C13默认将 Pro Micro 的 TXLEDD5映射到该 LED。若希望改用 RXLEDB0映射在config.h中加入#define CONVERT_TO_PROTON_C_RXLED对应的底层实现在 platforms/chibios/converters/promicro_to_proton_c/_pin_defs.h当定义CONVERT_TO_PROTON_C_RXLED时D5映射到GPIOC, 14、B0映射到GPIOC, 13否则D5映射到GPIOC, 13即板载 LEDB0映射到GPIOC, 14。以下是基于 STM32 平台实现的功能默认值特性说明Audio默认启用RGB Lighting默认禁用Backlight强制使用任务驱动 PWMsoftware PWM直到 ARM 平台支持自动配置USB Host例如 USB-USB 转换器不支持USB Host 代码为 AVR 专有目前不适用于 ARMSplit keyboards部分支持——高度依赖已启用的功能对应的 converter.mk 将MCU设为STM32F303、BOARD设为QMK_PROTON_C、BOOTLOADER设为stm32-dfu并默认启用AUDIO_ENABLE、使用bitbang版 WS2812 驱动。Adafruit KB2040 {#kb2040}基于 RP2040 平台实现的功能默认值特性说明RGB Lighting默认启用通过PIOvendor 驱动实现Backlight强制使用任务驱动 PWM直到 ARM 平台支持自动配置USB Host例如 USB-USB 转换器不支持USB Host 代码为 AVR 专有目前不适用于 ARMSplit keyboards部分支持通过PIOvendor 驱动——高度依赖已启用的功能其 converter.mk 将MCU设为RP2040、BOARD设为QMK_PM2040、BOOTLOADER设为rp2040并默认使用vendor版串行驱动与 WS2812 驱动、software版背光驱动。SparkFun Pro Micro - RP2040、Blok、Bit-C PRO 与 Michi {#sparkfun_pm2040}功能集与 Adafruit KB2040 完全一致。值得注意的差异点Bit-C PRO 的 converter.mk 额外注入-DRP2040_FLASH_W25X10CL用于告知 QMK 使用其正确的二级引导加载器W25X10CL 闪存芯片Blok 则使用独立的QMK_BLOK板定义见 converter.mk。STeMCell {#stemcell}功能集当前与 Proton C 相同。STeMCell 存在两种引脚排布版本v1.0.0v2.0.0预发布版本 v1.0.1、v1.0.2官方固件默认只支持 v2.0.0 版本。STeMCell 支持交换 UART 与 I2C 引脚从而在 STM32 芯片上实现单线 UART 分体通信。根据分体通信所用引脚编译时需附加对应标志分体引脚编译标志D3-e STMC_USyesD2无需D1-e STMC_ISyesD0无需底层实现在 platforms/chibios/converters/promicro_to_stemcell/converter.mkSTMC_USyes注入-DSTEMCELL_UART_SWAPSTMC_ISyes注入-DSTEMCELL_I2C_SWAP在 elite_c_to_stemcell/_pin_defs.h 中这些宏会交换 D3/D2 与 D1/D0 的引脚映射。Bonsai C4 {#bonsai_c4}Bonsai C4 板载 LED 只有一颗B2默认将 Pro Micro 的 TXLEDD5与 RXLEDB0都映射到它。若只想映射其中一颗可在config.h中取消定义另一颗并重新映射#undef B0 // 若 VBUS 检测未使用可将 RXLED 发送到 Vbus 检测引脚 #define B0 PAL_LINE(GPIOA, 9)RP2040 Community Edition - Elite-Pi、Helios 与 Liatris {#rp2040_ce}功能集与 Adafruit KB2040 相同。与 KB2040 相比RP2040 CE 系列默认启用 VBUS 检测-DUSB_VBUS_PIN19U见 promicro_to_rp2040_ce/converter.mk以获得更好的分体键盘支持。更多信息参见 RP2040 Community Edition 引脚说明。该系列的引脚映射定义在 promicro_to_rp2040_ce/_pin_defs.h如 D3→0、D2→1、F4→29、D5→12、B0→13可供精确核对各引脚的实际连接关系。Svlinky {#svlinky}功能集是 RP2040 Community Edition 的 Pro Micro 等价版本但有两点差异其中两个模拟 GPIO 被替换为仅支持数字的 GPIO且这两个引脚被移到 FPC 连接器以支持 VIK 规范 同样默认启用 VBUS 检测。Elite-C 系列转换详解如果键盘使用 Elite-C 主控支持的替代控制器为设备TargetCLI Argumentrules.mk条件宏STeMCellstemcell-e CONVERT_TOstemcellCONVERT_TOstemcell#ifdef CONVERT_TO_STEMCELLRP2040 Community Editionrp2040_ce-e CONVERT_TOrp2040_ceCONVERT_TOrp2040_ce#ifdef CONVERT_TO_RP2040_CEElite-Pielite_pi-e CONVERT_TOelite_piCONVERT_TOelite_pi#ifdef CONVERT_TO_ELITE_PI0xCB Helioshelios-e CONVERT_TOheliosCONVERT_TOhelios#ifdef CONVERT_TO_HELIOSLiatrisliatris-e CONVERT_TOliatrisCONVERT_TOliatris#ifdef CONVERT_TO_LIATRISSTeMCellElite-C{#stemcell_elite}与 Pro Micro 版 STeMCell 相同并额外支持 Elite-C 的底部一排引脚对应 elite_c_to_stemcell/_pin_defs.h 中B7/D5/C7/F1/F0等定义。RP2040 Community EditionElite-C{#rp2040_ce_elite}与 Pro Micro 版 RP2040 CE 相同并额外支持底部一排引脚见 elite_c_to_rp2040_ce/converter.mk同样默认启用 VBUS 检测。进阶主题键盘侧的准备声明development_board要让键盘支持转换功能需在键盘的keyboard.json中添加development_board字段。例如 keyboards/keebio/bdn9/rev1/keyboard.json 声明了development_board: promicro{ maintainer: QMK, development_board: promicro, diode_direction: COL2ROW }使用promicro开发板预设时pin compatibility已自动配置好无需额外声明。键盘兼容性要求 {#keyboard-req}键盘代码必须使用 QMK 提供的平台无关抽象具体包括使用 GPIO Controls即gpio_*系列 API而非直接操作寄存器或特定平台的引脚宏。只有满足这一点同一份矩阵扫描、旋钮等代码才能在不同平台的引脚映射下正常工作。额外键位配置 {#keymap-add}尽管转换器已尽量做到开箱即用某些情况下仍需要平台相关的额外配置。例如在 keymap 级别添加mcuconf.h以启用硬件外设#pragma once #include_next mcuconf.h #undef RP_SIO_USE_UART0 #define RP_SIO_USE_UART0 TRUE各驱动的详细配置方式请查阅对应驱动文档页。此外可能需要禁用不兼容的功能例如{ version: 1, keyboard: keebio/bdn9/rev1, keymap: keebio_bdn9_rev1_layout_2025-05-20, converter: proton_c, config: { features: { audio: false } }, layout: LAYOUT }AUDIO_ENABLE no条件编译利用CONVERT_TO_TARGET宏一旦启用转换器构建系统会暴露CONVERT_TO_目标大写宏可在代码中用#ifdef分支处理。该宏由 builddefs/converters.mk 通过OPT_DEFS -DCONVERT_TO_$(shell echo $(CONVERT_TO) | tr [:lower:] [:upper:])注入同时注入-DCONVERTER_TARGETtarget与-DCONVERTER_ENABLED。例如#ifdef CONVERT_TO_PROTON_C // Proton C 专用代码 #else // Pro Micro 代码 #endif引脚兼容性声明 {#pin_compatible}为确保兼容、提供校验并支撑未来的工作流键盘应声明pin compatibility引脚兼容基类保证只尝试合法组合。若使用promicro开发板预设此配置已自动完成。声明转换的基类接口在键盘配置中添加{ maintainer: QMK, development_board: elite_c, pin_compatible: elite_c, diode_direction: COL2ROW }以上示例将键盘默认配置为elite_c同时允许使用任意elite_c的转换目标。构建框架随后会把PIN_COMPATIBLE如promicro的引脚映射到转换器target如kb2040的引脚定义。警告映射引脚应严格遵守已定义的接口硬件上额外存在的引脚应予以忽略。可用的引脚兼容基类promicro与elite_c是当前可用的引脚兼容基类对应的引脚定义可在 platforms/chibios/converters 下各转换目录的_pin_defs.h中查看例如 promicro_to_proton_c/_pin_defs.h。promicro包含 Pro Micro 标准引脚排布含 TXLEDD5与 RXLEDB0两颗 LED——转换到无对应 LED 的板子时这两颗 LED 会被映射到未使用/不可用的引脚。文档对应的引脚示意图为docs目录下的pin_compatible_promicro.svg当前仓库中未随文档同步收录。elite_c包含 Pro Micro 全部引脚加底部一排引脚B7、D5、C7、F1、F0不含 LED。转换机制底层原理速览整个转换流程的核心逻辑集中在 builddefs/converters.mk要点如下合法性校验若设置了CONVERT_TO先检查PIN_COMPATIBLE是否已声明再通过 wildcard 在$(PLATFORM_PATH)/*/converters/$(PIN_COMPATIBLE)_to_$(CONVERT_TO)/查找转换目录任何一步失败都会抛出明确的CATASTROPHIC_ERROR。默认值注入依次-include转换目录下的pre_converter.mk与converter.mk如上面各小节展示的 MCU/BOARD/BOOTLOADER/驱动默认值并将转换目录加入VPATH。宏注入生成CONVERT_TO_大写目标、CONVERTER_TARGET、CONVERTER_ENABLED等编译宏供固件条件编译使用。引脚重定义转换目录中的_pin_defs.h把 AVR 风格引脚名如D3、F4重新定义为目标平台的PAL_LINE(...)或数字 GPIO键盘矩阵代码无需改动即可在不同主控上工作。结语QMK Converters 把换主控从一次固件移植工程简化为一行命令或一条配置。只要键盘代码遵循平台无关的 GPIO 抽象、正确声明pin_compatible就能在 Pro Micro / Elite-C 生态与 Proton C、RP2040 CE 系列之间自由切换并借助CONVERT_TO_*宏精确控制平台差异。动手前请核对目标主控的功能默认值音频、RGB、背光、分体支持等与 STeMCell 版本/引脚交换等特殊限制即可在绝大多数场景下实现真正的即插即用。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
