This commit is contained in:
Joel Challis 2025-07-25 21:26:58 +10:00 committed by GitHub
commit fb5b1eb713
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 366 additions and 98 deletions

View File

@ -2,8 +2,22 @@
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:
```sh
qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c
```
You can also configure this within your [keymap](#keymap) to accomplish the same thing.
::: tip
If you get build errors, you will need to convert the keyboard's code to be [compatible](#keyboard-req) with the converter feature, or provide additional [keymap](#keymap-add) 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:
| From | To |
@ -28,86 +42,56 @@ The following converters are available at this time:
| `elite_c` | `helios` |
| `elite_c` | `liatris` |
## Configuration
## Overview
Configuring a converter to use can be done by adding one of the following lines to your keymaps's configuration:
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:
:::::tabs
```sh
qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c
==== keymap.json
```json [keymap.json]
{
"version": 1,
"keyboard": "keebio/bdn9/rev1",
"keymap": "keebio_bdn9_rev1_layout_2025-05-20",
"converter": "proton_c", // [!code focus]
"layout": "LAYOUT",
}
```
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](drivers/gpio) 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 `#ifdef`s, 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 Compatibility | Notes |
|-------------------|-----------------------------------|
| `promicro` | Includes RX/TX LEDs |
| `elite_c` | Includes bottom row pins, no LEDs |
To declare the base for conversions, add this line to your keyboard's `rules.mk`:
==== rules.mk
```makefile
PIN_COMPATIBLE = elite_c
CONVERT_TO = proton_c
```
## Pro Micro
:::::
If a board currently supported in QMK uses a [Pro Micro](https://www.sparkfun.com/products/12640) (or compatible board), the supported alternative controllers are:
::: tip
If you get build errors, you will need to convert the keyboard's code to be [compatible](#keyboard-req) with the converter feature, or provide additional [keymap](#keymap-add) configuration.
:::
| Device | Target |
|------------------------------------------------------------------------------------------|-------------------|
| [Proton C](https://qmk.fm/proton-c/) | `proton_c` |
| [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040) | `kb2040` |
| [SparkFun Pro Micro - RP2040](https://www.sparkfun.com/products/18288) | `sparkfun_pm2040` |
| [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622) | `blok` |
| [Bit-C PRO](https://nullbits.co/bit-c-pro) | `bit_c_pro` |
| [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` |
| [customMK Bonsai C4](https://shop.custommk.com/products/bonsai-c4-microcontroller-board) | `bonsai_c4` |
| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi` |
| [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` |
| [Liatris](https://splitkb.com/products/liatris) | `liatris` |
| [Imera](https://splitkb.com/products/imera) | `imera` |
| [Michi](https://github.com/ci-bus/michi-promicro-rp2040) | `michi` |
| [Svlinky](https://github.com/sadekbaroudi/svlinky) | `svlinky` |
## Pro Micro Converters
Converter summary:
If a board currently supported by QMK uses a [Pro Micro](https://www.sparkfun.com/products/12640) (or compatible board), the supported alternative controllers are:
| 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` |
| `sparkfun_pm2040` | `-e CONVERT_TO=sparkfun_pm2040` | `CONVERT_TO=sparkfun_pm2040` | `#ifdef CONVERT_TO_SPARKFUN_PM2040` |
| `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` |
| `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` |
| `elite_pi` | `-e CONVERT_TO=elite_pi` | `CONVERT_TO=elite_pi` | `#ifdef CONVERT_TO_ELITE_PI` |
| `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` |
| `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` |
| `imera` | `-e CONVERT_TO=imera` | `CONVERT_TO=imera` | `#ifdef CONVERT_TO_IMERA` |
| `michi` | `-e CONVERT_TO=michi` | `CONVERT_TO=michi` | `#ifdef CONVERT_TO_MICHI` |
| `svlinky` | `-e CONVERT_TO=svlinky` | `CONVERT_TO=svlinky` | `#ifdef CONVERT_TO_SVLINKY` |
| Device | Target | CLI Argument | `rules.mk` | Condition |
|------------------------------------------------------------------------------------------|-------------------|---------------------------------|------------------------------|-------------------------------------|
| [Proton C](https://qmk.fm/proton-c/) | `proton_c` | `-e CONVERT_TO=proton_c` | `CONVERT_TO=proton_c` | `#ifdef CONVERT_TO_PROTON_C` |
| [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040) | `kb2040` | `-e CONVERT_TO=kb2040` | `CONVERT_TO=kb2040` | `#ifdef CONVERT_TO_KB2040` |
| [SparkFun Pro Micro - RP2040](https://www.sparkfun.com/products/18288) | `sparkfun_pm2040` | `-e CONVERT_TO=sparkfun_pm2040` | `CONVERT_TO=sparkfun_pm2040` | `#ifdef CONVERT_TO_SPARKFUN_PM2040` |
| [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622) | `blok` | `-e CONVERT_TO=blok` | `CONVERT_TO=blok` | `#ifdef CONVERT_TO_BLOK` |
| [Bit-C PRO](https://nullbits.co/bit-c-pro) | `bit_c_pro` | `-e CONVERT_TO=bit_c_pro` | `CONVERT_TO=bit_c_pro` | `#ifdef CONVERT_TO_BIT_C_PRO` |
| [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` | `-e CONVERT_TO=stemcell` | `CONVERT_TO=stemcell` | `#ifdef CONVERT_TO_STEMCELL` |
| [customMK Bonsai C4](https://shop.custommk.com/products/bonsai-c4-microcontroller-board) | `bonsai_c4` | `-e CONVERT_TO=bonsai_c4` | `CONVERT_TO=bonsai_c4` | `#ifdef CONVERT_TO_BONSAI_C4` |
| [RP2040 Community Edition](#rp2040_ce) | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` |
| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi` | `-e CONVERT_TO=elite_pi` | `CONVERT_TO=elite_pi` | `#ifdef CONVERT_TO_ELITE_PI` |
| [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` |
| [Liatris](https://splitkb.com/products/liatris) | `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` |
| [Imera](https://splitkb.com/products/imera) | `imera` | `-e CONVERT_TO=imera` | `CONVERT_TO=imera` | `#ifdef CONVERT_TO_IMERA` |
| [Michi](https://github.com/ci-bus/michi-promicro-rp2040) | `michi` | `-e CONVERT_TO=michi` | `CONVERT_TO=michi` | `#ifdef CONVERT_TO_MICHI` |
| [Svlinky](https://github.com/sadekbaroudi/svlinky) | `svlinky` | `-e CONVERT_TO=svlinky` | `CONVERT_TO=svlinky` | `#ifdef CONVERT_TO_SVLINKY` |
### Proton C {#proton_c}
@ -120,7 +104,7 @@ The Proton C only has one on-board LED (C13), and by default, the TXLED (D5) is
The following defaults are based on what has been implemented for STM32 boards.
| Feature | Notes |
|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
|--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| [Audio](features/audio) | Enabled |
| [RGB Lighting](features/rgblight) | Disabled |
| [Backlight](features/backlight) | Forces [task driven PWM](features/backlight#software-pwm-driver) until ARM can provide automatic configuration |
@ -132,7 +116,7 @@ The following defaults are based on what has been implemented for STM32 boards.
The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040) boards.
| Feature | Notes |
|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
|--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| [RGB Lighting](features/rgblight) | Enabled via `PIO` vendor driver |
| [Backlight](features/backlight) | Forces [task driven PWM](features/backlight#software-pwm-driver) 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) |
@ -177,31 +161,193 @@ Feature set is identical to [Adafruit KB2040](#kb2040). VBUS detection is enable
Feature set is a pro micro equivalent of the [RP2040 Community Edition](#rp2040_ce), 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](https://github.com/sadekbaroudi/vik). 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](https://github.com/sadekbaroudi/svlinky) for more details.
## Elite-C
## Elite-C Converters
If a board currently supported in QMK uses an [Elite-C](https://keeb.io/products/elite-c-low-profile-version-usb-c-pro-micro-replacement-atmega32u4), the supported alternative controllers are:
If a board currently supported by QMK uses an [Elite-C](https://keeb.io/products/elite-c-low-profile-version-usb-c-pro-micro-replacement-atmega32u4), the supported alternative controllers are:
| Device | Target |
|----------------------------------------------------------------------------------|-------------------|
| [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` |
| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi` |
| [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` |
| [Liatris](https://splitkb.com/products/liatris) | `liatris` |
| Device | Target | CLI Argument | `rules.mk` | Condition |
|----------------------------------------------------------------------------------|-------------|---------------------------|------------------------|-------------------------------|
| [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` | `-e CONVERT_TO=stemcell` | `CONVERT_TO=stemcell` | `#ifdef CONVERT_TO_STEMCELL` |
| [RP2040 Community Edition](#rp2040_ce_elite) | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` |
| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi` | `-e CONVERT_TO=elite_pi` | `CONVERT_TO=elite_pi` | `#ifdef CONVERT_TO_ELITE_PI` |
| [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` |
| [Liatris](https://splitkb.com/products/liatris) | `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` |
Converter summary:
| Target | Argument | `rules.mk` | Condition |
|-------------------|---------------------------------|------------------------------|-------------------------------------|
| `stemcell` | `-e CONVERT_TO=stemcell` | `CONVERT_TO=stemcell` | `#ifdef CONVERT_TO_STEMCELL` |
| `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` |
| `elite_pi` | `-e CONVERT_TO=elite_pi` | `CONVERT_TO=elite_pi` | `#ifdef CONVERT_TO_ELITE_PI` |
| `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` |
| `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` |
### STeMCell {#stemcell}_elite
### STeMCell {#stemcell_elite}
Identical to [Pro Micro - STeMCell](#stemcell) with support for the additional bottom row of pins.
### RP2040 Community Edition {#rp2040_ce_elite}
Identical to [Pro Micro - RP2040 Community Edition](#rp2040_ce) 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:
```json [keyboard.json]
{
"maintainer": "QMK",
"development_board": "promicro", // [!code focus]
"diode_direction": "COL2ROW",
}
```
See the [pin compatibility](#pin_compatible) for more information.
#### Additional Requirements {#keyboard-req}
Keyboards must use the platform agnostic abstractions provided by QMK. This includes:
* Use of [GPIO Controls](drivers/gpio).
### 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:
```c
#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
```json [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
```makefile
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 `#ifdef`s, For example:
```c
#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:
```json [keyboard.json]
{
"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
![promicro](/pin_compatible_promicro.svg)
<!-- ```svgbob
pins
.-------------. LEDs
| | _|_ _|_
D3 -+-O | \ /B0 \ /D5
D2 -+-O | -+- -+-
| | | |
| |
D1 -+-O O-+- F4
D0 -+-O O-+- F5
D4 -+-O O-+- F6
C6 -+-O O-+- F7
D7 -+-O O-+- B1
E6 -+-O O-+- B3
B4 -+-O O-+- B2
B5 -+-O O-+- B6
| |
'---+-+-+-+-+---'
``` -->
::: info Notes:
Includes LEDs - these may be mapped to unused/unavailable pins when not present.
:::
==== elite_c
![elite_c](/pin_compatible_elite_c.svg)
<!-- ```svgbob
pins
.-------------.
| |
D3 -+-O |
D2 -+-O |
| |
| |
D1 -+-O O-+- F4
D0 -+-O O-+- F5
D4 -+-O O-+- F6
C6 -+-O O-+- F7
D7 -+-O O-+- B1
E6 -+-O O-+- B3
B4 -+-O O-+- B2
B5 -+-O O O O O O O-+- B6
| | | | | | |
'---+-+-+-+-+---'
+ + + + +
B D C F F
7 5 7 1 0
``` -->
::: info Notes:
Includes bottom row pins, no LEDs.
:::
:::::

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 6.4 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 6.2 KiB