qmk-keychron-q3-colemak-dh/docs/feature_converters.md

Converters

Since many drop-in replacement controllers now exist, we've done our best to make them easy to use in existing designs.

This page documents the handy automated process for converting keyboards.

Supported Converters

Currently the following converters are available:

From	To
promicro	proton_c
promicro	kb2040
promicro	promicro_rp2040
promicro	blok
promicro	bit_c_pro
promicro	stemcell
promicro	bonsai_c4

See below for more in depth information on each converter.

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:

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.

?> 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:

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

Pro Micro

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

Device	Target
Proton C	proton_c
Adafruit KB2040	kb2040
SparkFun Pro Micro - RP2040	promicro_rp2040
Blok	blok
Bit-C PRO	bit_c_pro
STeMCell	stemcell
customMK Bonsai C4	bonsai_c4

Converter summary:

Target	Argument	rules.mk	Condition
proton_c	-e CONVERT_TO=proton_c	CONVERT_TO=proton_c	#ifdef CONVERT_TO_PROTON_C
kb2040	-e CONVERT_TO=kb2040	CONVERT_TO=kb2040	#ifdef CONVERT_TO_KB2040
promicro_rp2040	-e CONVERT_TO=promicro_rp2040	CONVERT_TO=promicro_rp2040	#ifdef CONVERT_TO_PROMICRO_RP2040
blok	-e CONVERT_TO=blok	CONVERT_TO=blok	#ifdef CONVERT_TO_BLOK
bit_c_pro	-e CONVERT_TO=bit_c_pro	CONVERT_TO=bit_c_pro	#ifdef CONVERT_TO_BIT_C_PRO
stemcell	-e CONVERT_TO=stemcell	CONVERT_TO=stemcell	#ifdef CONVERT_TO_STEMCELL
bonsai_c4	-e CONVERT_TO=bonsai_c4	CONVERT_TO=bonsai_c4	#ifdef CONVERT_TO_BONSAI_C4

Proton C :id=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.

Feature	Notes
Audio	Enabled
RGB Lighting	Disabled
Backlight	Forces 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 keyboards	Partial - heavily dependent on enabled features

Adafruit KB2040 :id=kb2040

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

Feature	Notes
RGB Lighting	Enabled via PIO vendor driver
Backlight	Forces 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 keyboards	Partial via PIO vendor driver - heavily dependent on enabled features

SparkFun Pro Micro - RP2040, Blok, and Bit-C PRO :id=promicro_rp2040

Currently identical to Adafruit KB2040.

STeMCell :id=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 Pin	Compile flags
D3	-e STMC_US=yes
D2	Not needed
D1	-e STMC_IS=yes
D0	Not needed

Bonsai C4 :id=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)

No peripherals are enabled by default at this time, but example code to enable SPI, I2C, PWM, and Serial communications can be found here