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.

You can generate the firmware by appending -e CONVERT_TO=<target> to your compile/flash command. For example:

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

You can also configure this within your keymap to accomplish the same thing.

::: tip If you get build errors, you will need to convert the keyboard's code to be compatible with the converter feature, or provide additional keymap configuration. :::

Supported Converters

Each converter category is broken down by its declared pin compatibility. This ensures that only valid combinations are attempted.

The following converters are available at this time:

Configuration

Configuring a converter to use can be done by adding one of the following lines to your keymaps's configuration:

:::::tabs

==== keymap.json

{
    "version": 1,
    "keyboard": "keebio/bdn9/rev1",
    "keymap": "keebio_bdn9_rev1_layout_2025-05-20",
    "converter": "proton_c", // [!code focus]
    "layout": "LAYOUT",
}

==== rules.mk

CONVERT_TO = proton_c

:::::

::: tip If you get build errors, you will need to convert the keyboard's code to be compatible with the converter feature, or provide additional keymap configuration. :::

Pro Micro Converters

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

Proton C {#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:

#define CONVERT_TO_PROTON_C_RXLED

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

Adafruit KB2040 {#kb2040}

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

SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi {#sparkfun_pm2040}

Feature set is identical to Adafruit KB2040.

STeMCell {#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:

Bonsai C4 {#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:

#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 {#rp2040_ce}

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.

Svlinky {#svlinky}

Feature set is a pro micro equivalent of the RP2040 Community Edition, except that two of the analog GPIO have been replaced with digital only GPIO. These two were moved to the FPC connector to support the VIK specification. This means that if you are expecting analog support on all 4 pins as provided on a RP2040 Community Edition pinout, you will not have that. Please see the Svlinky github page for more details.

Elite-C Converters

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

STeMCell {#stemcell_elite}

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

RP2040 Community Edition {#rp2040_ce_elite}

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

Advanced Topics

Keyboard Configuration

To configure a keyboard to allow the converter feature, add the following line to your keyboard's .json configuration:

{
    "maintainer": "QMK",
    "development_board": "promicro", // [!code focus]
    "diode_direction": "COL2ROW",
}

See the pin compatibility for more information.

Additional Requirements {#keyboard-req}

Keyboards must use the platform agnostic abstractions provided by QMK. This includes:

• Use of GPIO Controls.

Additional Keymap Configuration {#keymap-add}

While effort has been made to make converters as compatible as possible, sometimes additional platform specific configuration is required.

For example, enabling hardware peripherals by adding a keymap level mcuconf.h with something like the following:

#pragma once

#include_next <mcuconf.h>

#undef RP_SIO_USE_UART0
#define RP_SIO_USE_UART0 TRUE

You can find details on how to configure drivers on their respective pages.

Alternatively, you may have to disable incompatible features. For example:

:::::tabs

==== keymap.json

{
    "version": 1,
    "keyboard": "keebio/bdn9/rev1",
    "keymap": "keebio_bdn9_rev1_layout_2025-05-20",
    "converter": "proton_c",
    "config": { // [!code focus]
        "features": { // [!code focus]
            "audio": false // [!code focus]
        }
    }
    "layout": "LAYOUT",
}

==== rules.mk

AUDIO_ENABLE = no

:::::

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:

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

Pin Compatibility {#pin_compatible}

To ensure compatibility, provide validation, and power future workflows, a keyboard should declare its pin compatibility. This ensures that only valid combinations are attempted.

::: tip Note This will already be configured for you if are using the promicro development board preset. :::

To declare the base interface for conversions, add the following line to your keyboard's configuration:

{
    "maintainer": "QMK",
    "development_board": "elite_c", // [!code focus]
    "pin_compatible": "elite_c", // [!code focus]
    "diode_direction": "COL2ROW",
}

The above example, configures a keyboard for a default of elite_c while allowing any of the elite_c converter targets.

The framework then allows mapping of pins from <PIN_COMPATIBLE> to converter <target>.

::: warning Mapped pins should adhere strictly to the defined interface, any extras present on the hardware should be ignored. :::

Available Pin Compatibility

:::::tabs

==== promicro

::: info Notes: Includes LEDs - these may be mapped to unused/unavailable pins when not present. :::

==== elite_c

::: info Notes: Includes bottom row pins, no LEDs. :::

:::::