gitbot/qmk_firmware
0
0
Fork 0
mirror of https://github.com/qmk/qmk_firmware.git synced 2025-07-27 11:31:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rework converter docs

Browse Source
This commit is contained in:
zvecr 2025-06-29 07:54:22 +01:00
parent 711b109246
commit f16b38c7a3
3 changed files with 366 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

322
docs/feature_converters.md
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. 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 ## 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: The following converters are available at this time:
| From | To | | From | To |
@ -28,86 +42,56 @@ The following converters are available at this time:
| `elite_c` | `helios` | | `elite_c` | `helios` |
| `elite_c` | `liatris` | | `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 ==== keymap.json
qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c
```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. ==== rules.mk
::: 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`:
```makefile ```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 | ## Pro Micro Converters
|------------------------------------------------------------------------------------------|-------------------|
| [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` |
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 | | Device | Target | CLI Argument | `rules.mk` | Condition |
|-------------------|---------------------------------|------------------------------|-------------------------------------| |------------------------------------------------------------------------------------------|-------------------|---------------------------------|------------------------------|-------------------------------------|
| `proton_c` | `-e CONVERT_TO=proton_c` | `CONVERT_TO=proton_c` | `#ifdef CONVERT_TO_PROTON_C` | | [Proton C](https://qmk.fm/proton-c/) | `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` | | [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040) | `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` | | [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` | `-e CONVERT_TO=blok` | `CONVERT_TO=blok` | `#ifdef CONVERT_TO_BLOK` | | [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622) | `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` | | [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` | `-e CONVERT_TO=stemcell` | `CONVERT_TO=stemcell` | `#ifdef CONVERT_TO_STEMCELL` | | [STeMCell](https://github.com/megamind4089/STeMCell) | `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` | | [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_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` | | [RP2040 Community Edition](#rp2040_ce) | `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` | | [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` |
| `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` | | [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` |
| `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` | | [Liatris](https://splitkb.com/products/liatris) | `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` |
| `imera` | `-e CONVERT_TO=imera` | `CONVERT_TO=imera` | `#ifdef CONVERT_TO_IMERA` | | [Imera](https://splitkb.com/products/imera) | `imera` | `-e CONVERT_TO=imera` | `CONVERT_TO=imera` | `#ifdef CONVERT_TO_IMERA` |
| `michi` | `-e CONVERT_TO=michi` | `CONVERT_TO=michi` | `#ifdef CONVERT_TO_MICHI` | | [Michi](https://github.com/ci-bus/michi-promicro-rp2040) | `michi` | `-e CONVERT_TO=michi` | `CONVERT_TO=michi` | `#ifdef CONVERT_TO_MICHI` |
| `svlinky` | `-e CONVERT_TO=svlinky` | `CONVERT_TO=svlinky` | `#ifdef CONVERT_TO_SVLINKY` | | [Svlinky](https://github.com/sadekbaroudi/svlinky) | `svlinky` | `-e CONVERT_TO=svlinky` | `CONVERT_TO=svlinky` | `#ifdef CONVERT_TO_SVLINKY` |
### Proton C {#proton_c} ### 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. The following defaults are based on what has been implemented for STM32 boards.
| Feature | Notes | | Feature | Notes |
|----------------------------------------------|------------------------------------------------------------------------------------------------------------------| |--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| [Audio](features/audio) | Enabled | | [Audio](features/audio) | Enabled |
| [RGB Lighting](features/rgblight) | Disabled | | [RGB Lighting](features/rgblight) | Disabled |
| [Backlight](features/backlight) | Forces [task driven PWM](features/backlight#software-pwm-driver) until ARM can provide automatic configuration | | [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. The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040) boards.
| Feature | Notes | | Feature | Notes |
|----------------------------------------------|------------------------------------------------------------------------------------------------------------------| |--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| [RGB Lighting](features/rgblight) | Enabled via `PIO` vendor driver | | [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 | | [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) | | 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. 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 | | Device | Target | CLI Argument | `rules.mk` | Condition |
|----------------------------------------------------------------------------------|-------------------| |----------------------------------------------------------------------------------|-------------|---------------------------|------------------------|-------------------------------|
| [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` | | [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` | `-e CONVERT_TO=stemcell` | `CONVERT_TO=stemcell` | `#ifdef CONVERT_TO_STEMCELL` |
| [Elite-Pi](https://keeb.io/products/elite-pi-usb-c-pro-micro-replacement-rp2040) | `elite_pi` | | [RP2040 Community Edition](#rp2040_ce_elite) | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` |
| [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` | | [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` |
| [Liatris](https://splitkb.com/products/liatris) | `liatris` | | [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: ### STeMCell {#stemcell_elite}
| 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
Identical to [Pro Micro - STeMCell](#stemcell) with support for the additional bottom row of pins. Identical to [Pro Micro - STeMCell](#stemcell) with support for the additional bottom row of pins.
### RP2040 Community Edition {#rp2040_ce_elite} ### RP2040 Community Edition {#rp2040_ce_elite}
Identical to [Pro Micro - RP2040 Community Edition](#rp2040_ce) with support for the additional bottom row of pins. 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.
:::
:::::

61
docs/public/pin_compatible_elite_c.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 6.4 KiB

61
docs/public/pin_compatible_promicro.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB