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_TO=<target>时，构建系统会：
- 读取键盘配置中声明的
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_TO=<target>即可。例如把 Keebio BDN9 rev1 转换为 Proton C：
qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_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 转换
| From | To |
|---|---|
promicro | proton_c |
promicro | kb2040 |
promicro | sparkfun_pm2040 |
promicro | blok |
promicro | bit_c_pro |
promicro | stemcell |
promicro | bonsai_c4 |
promicro | rp2040_ce |
promicro | elite_pi |
promicro | helios |
promicro | liatris |
promicro | imera |
promicro | michi |
promicro | svlinky |
从 Elite-C 转换
| From | To |
|---|---|
elite_c | stemcell |
elite_c | rp2040_ce |
elite_c | elite_pi |
elite_c | helios |
elite_c | liatris |
Pro Micro 系列转换详解
如果一块键盘使用 Pro Micro（或其兼容板）作为主控，QMK 支持转换为下列替代控制器。表中同时给出了 CLI 参数、rules.mk写法，以及代码中可用的条件编译宏：
| 设备 | Target | CLI Argument | rules.mk | 条件宏 |
|---|---|---|---|---|
| Proton C | proton_c | -e CONVERT_TO=proton_c | CONVERT_TO=proton_c | #ifdef CONVERT_TO_PROTON_C |
| Adafruit KB2040 | kb2040 | -e CONVERT_TO=kb2040 | CONVERT_TO=kb2040 | #ifdef CONVERT_TO_KB2040 |
| SparkFun Pro Micro - RP2040 | sparkfun_pm2040 | -e CONVERT_TO=sparkfun_pm2040 | CONVERT_TO=sparkfun_pm2040 | #ifdef CONVERT_TO_SPARKFUN_PM2040 |
| Blok | blok | -e CONVERT_TO=blok | CONVERT_TO=blok | #ifdef CONVERT_TO_BLOK |
| Bit-C PRO | bit_c_pro | -e CONVERT_TO=bit_c_pro | CONVERT_TO=bit_c_pro | #ifdef CONVERT_TO_BIT_C_PRO |
| STeMCell | stemcell | -e CONVERT_TO=stemcell | CONVERT_TO=stemcell | #ifdef CONVERT_TO_STEMCELL |
| customMK Bonsai C4 | bonsai_c4 | -e CONVERT_TO=bonsai_c4 | CONVERT_TO=bonsai_c4 | #ifdef CONVERT_TO_BONSAI_C4 |
| RP2040 Community Edition | rp2040_ce | -e CONVERT_TO=rp2040_ce | CONVERT_TO=rp2040_ce | #ifdef CONVERT_TO_RP2040_CE |
| Elite-Pi | elite_pi | -e CONVERT_TO=elite_pi | CONVERT_TO=elite_pi | #ifdef CONVERT_TO_ELITE_PI |
| 0xCB Helios | helios | -e CONVERT_TO=helios | CONVERT_TO=helios | #ifdef CONVERT_TO_HELIOS |
| Liatris | liatris | -e CONVERT_TO=liatris | CONVERT_TO=liatris | #ifdef CONVERT_TO_LIATRIS |
| Imera | imera | -e CONVERT_TO=imera | CONVERT_TO=imera | #ifdef CONVERT_TO_IMERA |
| Michi | michi | -e CONVERT_TO=michi | CONVERT_TO=michi | #ifdef CONVERT_TO_MICHI |
| Svlinky | svlinky | -e CONVERT_TO=svlinky | CONVERT_TO=svlinky | #ifdef CONVERT_TO_SVLINKY |
Proton C {#proton_c}
Proton C 板载 LED 只有一颗（C13），默认将 Pro Micro 的 TXLED（D5）映射到该 LED。若希望改用 RXLED（B0）映射，在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（即板载 LED），B0映射到GPIOC, 14。
以下是基于 STM32 平台实现的功能默认值：
| 特性 | 说明 |
|---|---|
| Audio | 默认启用 |
| RGB Lighting | 默认禁用 |
| Backlight | 强制使用任务驱动 PWM（software PWM），直到 ARM 平台支持自动配置 |
| USB Host（例如 USB-USB 转换器） | 不支持（USB Host 代码为 AVR 专有，目前不适用于 ARM） |
| Split 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 专有，目前不适用于 ARM） |
| Split 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.0
- v2.0.0（预发布版本 v1.0.1、v1.0.2）
官方固件默认只支持 v2.0.0 版本。
STeMCell 支持交换 UART 与 I2C 引脚，从而在 STM32 芯片上实现单线 UART 分体通信。根据分体通信所用引脚，编译时需附加对应标志：
| 分体引脚 | 编译标志 |
|---|---|
| D3 | -e STMC_US=yes |
| D2 | 无需 |
| D1 | -e STMC_IS=yes |
| D0 | 无需 |
底层实现在 platforms/chibios/converters/promicro_to_stemcell/converter.mk：STMC_US=yes注入-DSTEMCELL_UART_SWAP，STMC_IS=yes注入-DSTEMCELL_I2C_SWAP；在 elite_c_to_stemcell/_pin_defs.h 中，这些宏会交换 D3/D2 与 D1/D0 的引脚映射。
Bonsai C4 {#bonsai_c4}
Bonsai C4 板载 LED 只有一颗（B2），默认将 Pro Micro 的 TXLED（D5）与 RXLED（B0）都映射到它。若只想映射其中一颗，可在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_PIN=19U，见 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 主控，支持的替代控制器为：
| 设备 | Target | CLI Argument | rules.mk | 条件宏 |
|---|---|---|---|---|
| STeMCell | stemcell | -e CONVERT_TO=stemcell | CONVERT_TO=stemcell | #ifdef CONVERT_TO_STEMCELL |
| RP2040 Community Edition | rp2040_ce | -e CONVERT_TO=rp2040_ce | CONVERT_TO=rp2040_ce | #ifdef CONVERT_TO_RP2040_CE |
| Elite-Pi | elite_pi | -e CONVERT_TO=elite_pi | CONVERT_TO=elite_pi | #ifdef CONVERT_TO_ELITE_PI |
| 0xCB Helios | helios | -e CONVERT_TO=helios | CONVERT_TO=helios | #ifdef CONVERT_TO_HELIOS |
| Liatris | liatris | -e CONVERT_TO=liatris | CONVERT_TO=liatris | #ifdef CONVERT_TO_LIATRIS |
STeMCell（Elite-C）{#stemcell_elite}
与 Pro Micro 版 STeMCell 相同，并额外支持 Elite-C 的底部一排引脚（对应 elite_c_to_stemcell/_pin_defs.h 中B7/D5/C7/F1/F0等定义）。
RP2040 Community Edition（Elite-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_TARGET="<target>"与-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 标准引脚排布，含 TXLED（D5）与 RXLED（B0）两颗 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），仅供参考
