Skip to content

Converters

This page documents the automated process for converting keyboards to use drop-in replacement controllers. This process is designed to be easy to use and can be completed in a few simple steps.

Supported Converters

The following converters are available at this time:

FromTo
promicroproton_c
promicrokb2040
promicrosparkfun_pm2040
promicroblok
promicrobit_c_pro
promicrostemcell
promicrobonsai_c4
promicrorp2040_ce
promicroelite_pi
promicrohelios
promicroliatris
promicroimera
promicromichi
elite_cstemcell
elite_crp2040_ce
elite_celite_pi
elite_chelios
elite_cliatris

Overview

Each converter category is broken down by its declared pin compatibility. This ensures that only valid combinations are attempted. You can generate the firmware by appending -e CONVERT_TO=<target> to your compile/flash command. For example:

sh
qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c

You can also add the same CONVERT_TO=<target> to your keymap's rules.mk, which will accomplish the same thing.

TIP

If you get errors about PORTB/DDRB, etc not being defined, you'll need to convert the keyboard's code to use the GPIO Controls that will work for both ARM and AVR. This shouldn't affect the AVR builds at all.

Conditional Configuration

Once a converter is enabled, it exposes the CONVERT_TO_<target_uppercase> flag that you can use in your code with #ifdefs, For example:

c
#ifdef CONVERT_TO_PROTON_C
    // Proton C code
#else
    // Pro Micro code
#endif

Pin Compatibility

To ensure compatibility, provide validation, and enable future workflows, a keyboard should declare its pin compatibility. For legacy reasons, this is currently assumed to be promicro. The following pin compatibility interfaces are currently defined:

Pin CompatibilityNotes
promicroIncludes RX/TX LEDs
elite_cIncludes bottom row pins, no LEDs

To declare the base for conversions, add this line to your keyboard's rules.mk:

makefile
PIN_COMPATIBLE = elite_c

Pro Micro

If a board currently supported in QMK uses a Pro Micro (or compatible board), the supported alternative controllers are:

DeviceTarget
Proton Cproton_c
Adafruit KB2040kb2040
SparkFun Pro Micro - RP2040sparkfun_pm2040
Blokblok
Bit-C PRObit_c_pro
STeMCellstemcell
customMK Bonsai C4bonsai_c4
Elite-Pielite_pi
0xCB Helioshelios
Liatrisliatris
Imeraimera
Michimichi

Converter summary:

TargetArgumentrules.mkCondition
proton_c-e CONVERT_TO=proton_cCONVERT_TO=proton_c#ifdef CONVERT_TO_PROTON_C
kb2040-e CONVERT_TO=kb2040CONVERT_TO=kb2040#ifdef CONVERT_TO_KB2040
sparkfun_pm2040-e CONVERT_TO=sparkfun_pm2040CONVERT_TO=sparkfun_pm2040#ifdef CONVERT_TO_SPARKFUN_PM2040
blok-e CONVERT_TO=blokCONVERT_TO=blok#ifdef CONVERT_TO_BLOK
bit_c_pro-e CONVERT_TO=bit_c_proCONVERT_TO=bit_c_pro#ifdef CONVERT_TO_BIT_C_PRO
stemcell-e CONVERT_TO=stemcellCONVERT_TO=stemcell#ifdef CONVERT_TO_STEMCELL
bonsai_c4-e CONVERT_TO=bonsai_c4CONVERT_TO=bonsai_c4#ifdef CONVERT_TO_BONSAI_C4
rp2040_ce-e CONVERT_TO=rp2040_ceCONVERT_TO=rp2040_ce#ifdef CONVERT_TO_RP2040_CE
elite_pi-e CONVERT_TO=elite_piCONVERT_TO=elite_pi#ifdef CONVERT_TO_ELITE_PI
helios-e CONVERT_TO=heliosCONVERT_TO=helios#ifdef CONVERT_TO_HELIOS
liatris-e CONVERT_TO=liatrisCONVERT_TO=liatris#ifdef CONVERT_TO_LIATRIS
imera-e CONVERT_TO=imeraCONVERT_TO=imera#ifdef CONVERT_TO_IMERA
michi-e CONVERT_TO=michiCONVERT_TO=michi#ifdef CONVERT_TO_MICHI

Proton C

The Proton C only has one on-board LED (C13), and by default, the TXLED (D5) is mapped to it. If you want the RXLED (B0) mapped to it instead, add this line to your config.h:

c
#define CONVERT_TO_PROTON_C_RXLED

The following defaults are based on what has been implemented for STM32 boards.

FeatureNotes
AudioEnabled
RGB LightingDisabled
BacklightForces task driven PWM until ARM can provide automatic configuration
USB Host (e.g. USB-USB converter)Not supported (USB host code is AVR specific and is not currently supported on ARM)
Split keyboardsPartial - heavily dependent on enabled features

Adafruit KB2040

The following defaults are based on what has been implemented for RP2040 boards.

FeatureNotes
RGB LightingEnabled via PIO vendor driver
BacklightForces task driven PWM until ARM can provide automatic configuration
USB Host (e.g. USB-USB converter)Not supported (USB host code is AVR specific and is not currently supported on ARM)
Split keyboardsPartial via PIO vendor driver - heavily dependent on enabled features

SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi

Feature set is identical to Adafruit KB2040.

STeMCell

Feature set currently identical to Proton C. There are two versions of STeMCell available, with different pinouts:

  • v1.0.0
  • v2.0.0 (pre-release v1.0.1, v1.0.2) Default official firmware only supports v2.0.0 STeMCell.

STeMCell has support to swap UART and I2C pins to enable single-wire uart communication in STM chips. The following additional flags has to be used while compiling, based on the pin used for split communication:

Split PinCompile flags
D3-e STMC_US=yes
D2Not needed
D1-e STMC_IS=yes
D0Not needed

Bonsai C4

The Bonsai C4 only has one on-board LED (B2), and by default, both the Pro Micro TXLED (D5) and RXLED (B0) are mapped to it. If you want only one of them mapped, you can undefine one and redefine it to another pin by adding these line to your config.h:

c
#undef B0
// If VBUS detection is unused, we can send RXLED to the Vbus detect pin instead
#define B0 PAL_LINE(GPIOA, 9)

RP2040 Community Edition - Elite-Pi, Helios, and Liatris

Feature set is identical to Adafruit KB2040. VBUS detection is enabled by default for superior split keyboard support. For more information, refer to the Community Edition pinout docs.

Elite-C

If a board currently supported in QMK uses an Elite-C, the supported alternative controllers are:

DeviceTarget
STeMCellstemcell
Elite-Pielite_pi
0xCB Helioshelios
Liatrisliatris

Converter summary:

TargetArgumentrules.mkCondition
stemcell-e CONVERT_TO=stemcellCONVERT_TO=stemcell#ifdef CONVERT_TO_STEMCELL
rp2040_ce-e CONVERT_TO=rp2040_ceCONVERT_TO=rp2040_ce#ifdef CONVERT_TO_RP2040_CE
elite_pi-e CONVERT_TO=elite_piCONVERT_TO=elite_pi#ifdef CONVERT_TO_ELITE_PI
helios-e CONVERT_TO=heliosCONVERT_TO=helios#ifdef CONVERT_TO_HELIOS
liatris-e CONVERT_TO=liatrisCONVERT_TO=liatris#ifdef CONVERT_TO_LIATRIS

STeMCell {#stemcell}_elite

Identical to Pro Micro - STeMCell with support for the additional bottom row of pins.

RP2040 Community Edition

Identical to Pro Micro - RP2040 Community Edition with support for the additional bottom row of pins.