feature_converters.md (16415B)
1 # Converters 2 3 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. 4 5 You can generate the firmware by appending `-e CONVERT_TO=<target>` to your compile/flash command. For example: 6 7 ```sh 8 qmk flash -c -kb keebio/bdn9/rev1 -km default -e CONVERT_TO=proton_c 9 ``` 10 11 You can also configure this within your [keymap](#keymap) to accomplish the same thing. 12 13 ::: tip 14 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. 15 ::: 16 17 ## Supported Converters 18 19 Each converter category is broken down by its declared `pin compatibility`. This ensures that only valid combinations are attempted. 20 21 The following converters are available at this time: 22 23 | From | To | 24 |------------|-------------------| 25 | `promicro` | `proton_c` | 26 | `promicro` | `kb2040` | 27 | `promicro` | `sparkfun_pm2040` | 28 | `promicro` | `blok` | 29 | `promicro` | `bit_c_pro` | 30 | `promicro` | `stemcell` | 31 | `promicro` | `bonsai_c4` | 32 | `promicro` | `rp2040_ce` | 33 | `promicro` | `elite_pi` | 34 | `promicro` | `helios` | 35 | `promicro` | `liatris` | 36 | `promicro` | `imera` | 37 | `promicro` | `michi` | 38 | `promicro` | `svlinky` | 39 | `elite_c` | `stemcell` | 40 | `elite_c` | `rp2040_ce` | 41 | `elite_c` | `elite_pi` | 42 | `elite_c` | `helios` | 43 | `elite_c` | `liatris` | 44 45 ## Configuration 46 47 Configuring a converter to use can be done by adding one of the following lines to your keymaps's configuration: 48 49 :::::tabs 50 51 ==== keymap.json 52 53 ```json [keymap.json] 54 { 55 "version": 1, 56 "keyboard": "keebio/bdn9/rev1", 57 "keymap": "keebio_bdn9_rev1_layout_2025-05-20", 58 "converter": "proton_c", // [!code focus] 59 "layout": "LAYOUT", 60 } 61 ``` 62 63 ==== rules.mk 64 65 ```makefile 66 CONVERT_TO = proton_c 67 ``` 68 69 ::::: 70 71 ::: tip 72 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. 73 ::: 74 75 ## Pro Micro Converters 76 77 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: 78 79 | Device | Target | CLI Argument | `rules.mk` | Condition | 80 |------------------------------------------------------------------------------------------|-------------------|---------------------------------|------------------------------|-------------------------------------| 81 | [Proton C](https://qmk.fm/proton-c/) | `proton_c` | `-e CONVERT_TO=proton_c` | `CONVERT_TO=proton_c` | `#ifdef CONVERT_TO_PROTON_C` | 82 | [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040) | `kb2040` | `-e CONVERT_TO=kb2040` | `CONVERT_TO=kb2040` | `#ifdef CONVERT_TO_KB2040` | 83 | [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` | 84 | [Blok](https://boardsource.xyz/store/628b95b494dfa308a6581622) | `blok` | `-e CONVERT_TO=blok` | `CONVERT_TO=blok` | `#ifdef CONVERT_TO_BLOK` | 85 | [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` | 86 | [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` | `-e CONVERT_TO=stemcell` | `CONVERT_TO=stemcell` | `#ifdef CONVERT_TO_STEMCELL` | 87 | [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` | 88 | [RP2040 Community Edition](#rp2040_ce) | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` | 89 | [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` | 90 | [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` | 91 | [Liatris](https://splitkb.com/products/liatris) | `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` | 92 | [Imera](https://splitkb.com/products/imera) | `imera` | `-e CONVERT_TO=imera` | `CONVERT_TO=imera` | `#ifdef CONVERT_TO_IMERA` | 93 | [Michi](https://github.com/ci-bus/michi-promicro-rp2040) | `michi` | `-e CONVERT_TO=michi` | `CONVERT_TO=michi` | `#ifdef CONVERT_TO_MICHI` | 94 | [Svlinky](https://github.com/sadekbaroudi/svlinky) | `svlinky` | `-e CONVERT_TO=svlinky` | `CONVERT_TO=svlinky` | `#ifdef CONVERT_TO_SVLINKY` | 95 96 ### Proton C {#proton_c} 97 98 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`: 99 100 ```c 101 #define CONVERT_TO_PROTON_C_RXLED 102 ``` 103 104 The following defaults are based on what has been implemented for STM32 boards. 105 106 | Feature | Notes | 107 |--------------------------------------------|----------------------------------------------------------------------------------------------------------------| 108 | [Audio](features/audio) | Enabled | 109 | [RGB Lighting](features/rgblight) | Disabled | 110 | [Backlight](features/backlight) | Forces [task driven PWM](features/backlight#software-pwm-driver) until ARM can provide automatic configuration | 111 | USB Host (e.g. USB-USB converter) | Not supported (USB host code is AVR specific and is not currently supported on ARM) | 112 | [Split keyboards](features/split_keyboard) | Partial - heavily dependent on enabled features | 113 114 ### Adafruit KB2040 {#kb2040} 115 116 The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040) boards. 117 118 | Feature | Notes | 119 |--------------------------------------------|----------------------------------------------------------------------------------------------------------------| 120 | [RGB Lighting](features/rgblight) | Enabled via `PIO` vendor driver | 121 | [Backlight](features/backlight) | Forces [task driven PWM](features/backlight#software-pwm-driver) until ARM can provide automatic configuration | 122 | USB Host (e.g. USB-USB converter) | Not supported (USB host code is AVR specific and is not currently supported on ARM) | 123 | [Split keyboards](features/split_keyboard) | Partial via `PIO` vendor driver - heavily dependent on enabled features | 124 125 ### SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi {#sparkfun_pm2040} 126 127 Feature set is identical to [Adafruit KB2040](#kb2040). 128 129 ### STeMCell {#stemcell} 130 131 Feature set currently identical to [Proton C](#proton_c). 132 There are two versions of STeMCell available, with different pinouts: 133 - v1.0.0 134 - v2.0.0 (pre-release v1.0.1, v1.0.2) 135 Default official firmware only supports v2.0.0 STeMCell. 136 137 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: 138 139 | Split Pin | Compile flags | 140 |-----------|---------------| 141 | D3 | -e STMC_US=yes| 142 | D2 | Not needed | 143 | D1 | -e STMC_IS=yes| 144 | D0 | Not needed | 145 146 ### Bonsai C4 {#bonsai_c4} 147 148 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`: 149 150 ```c 151 #undef B0 152 // If VBUS detection is unused, we can send RXLED to the Vbus detect pin instead 153 #define B0 PAL_LINE(GPIOA, 9) 154 ``` 155 156 ### RP2040 Community Edition - Elite-Pi, Helios, and Liatris {#rp2040_ce} 157 158 Feature set is identical to [Adafruit KB2040](#kb2040). VBUS detection is enabled by default for superior split keyboard support. For more information, refer to the [Community Edition pinout](platformdev_rp2040#rp2040_ce) docs. 159 160 ### Svlinky {#svlinky} 161 162 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. 163 164 ## Elite-C Converters 165 166 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: 167 168 | Device | Target | CLI Argument | `rules.mk` | Condition | 169 |----------------------------------------------------------------------------------|-------------|---------------------------|------------------------|-------------------------------| 170 | [STeMCell](https://github.com/megamind4089/STeMCell) | `stemcell` | `-e CONVERT_TO=stemcell` | `CONVERT_TO=stemcell` | `#ifdef CONVERT_TO_STEMCELL` | 171 | [RP2040 Community Edition](#rp2040_ce_elite) | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` | 172 | [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` | 173 | [0xCB Helios](https://keeb.supply/products/0xcb-helios) | `helios` | `-e CONVERT_TO=helios` | `CONVERT_TO=helios` | `#ifdef CONVERT_TO_HELIOS` | 174 | [Liatris](https://splitkb.com/products/liatris) | `liatris` | `-e CONVERT_TO=liatris` | `CONVERT_TO=liatris` | `#ifdef CONVERT_TO_LIATRIS` | 175 176 ### STeMCell {#stemcell_elite} 177 178 Identical to [Pro Micro - STeMCell](#stemcell) with support for the additional bottom row of pins. 179 180 ### RP2040 Community Edition {#rp2040_ce_elite} 181 182 Identical to [Pro Micro - RP2040 Community Edition](#rp2040_ce) with support for the additional bottom row of pins. 183 184 ## Advanced Topics 185 186 ### Keyboard Configuration 187 188 To configure a keyboard to allow the converter feature, add the following line to your keyboard's `.json` configuration: 189 190 ```json [keyboard.json] 191 { 192 "maintainer": "QMK", 193 "development_board": "promicro", // [!code focus] 194 "diode_direction": "COL2ROW", 195 } 196 ``` 197 198 See the [pin compatibility](#pin_compatible) for more information. 199 200 #### Additional Requirements {#keyboard-req} 201 202 Keyboards must use the platform agnostic abstractions provided by QMK. This includes: 203 204 * Use of [GPIO Controls](drivers/gpio). 205 206 ### Additional Keymap Configuration {#keymap-add} 207 208 While effort has been made to make converters as compatible as possible, sometimes additional platform specific configuration is required. 209 210 For example, enabling hardware peripherals by adding a keymap level `mcuconf.h` with something like the following: 211 ```c 212 #pragma once 213 214 #include_next <mcuconf.h> 215 216 #undef RP_SIO_USE_UART0 217 #define RP_SIO_USE_UART0 TRUE 218 ``` 219 220 You can find details on how to configure drivers on their respective pages. 221 222 Alternatively, you may have to disable incompatible features. For example: 223 224 :::::tabs 225 226 ==== keymap.json 227 228 ```json [keymap.json] 229 { 230 "version": 1, 231 "keyboard": "keebio/bdn9/rev1", 232 "keymap": "keebio_bdn9_rev1_layout_2025-05-20", 233 "converter": "proton_c", 234 "config": { // [!code focus] 235 "features": { // [!code focus] 236 "audio": false // [!code focus] 237 } 238 } 239 "layout": "LAYOUT", 240 } 241 ``` 242 243 ==== rules.mk 244 245 ```makefile 246 AUDIO_ENABLE = no 247 ``` 248 249 ::::: 250 251 ### Conditional Configuration 252 253 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: 254 255 ```c 256 #ifdef CONVERT_TO_PROTON_C 257 // Proton C code 258 #else 259 // Pro Micro code 260 #endif 261 ``` 262 263 ### Pin Compatibility {#pin_compatible} 264 265 To ensure compatibility, provide validation, and power future workflows, a keyboard should declare its `pin compatibility`. This ensures that only valid combinations are attempted. 266 267 ::: tip Note 268 This will already be configured for you if are using the `promicro` development board preset. 269 ::: 270 271 To declare the base interface for conversions, add the following line to your keyboard's configuration: 272 273 ```json [keyboard.json] 274 { 275 "maintainer": "QMK", 276 "development_board": "elite_c", // [!code focus] 277 "pin_compatible": "elite_c", // [!code focus] 278 "diode_direction": "COL2ROW", 279 } 280 ``` 281 282 The above example, configures a keyboard for a default of `elite_c` while allowing any of the `elite_c` converter targets. 283 284 The framework then allows mapping of pins from `<PIN_COMPATIBLE>` to converter `<target>`. 285 286 ::: warning 287 Mapped pins should adhere strictly to the defined interface, any extras present on the hardware should be ignored. 288 ::: 289 290 #### Available Pin Compatibility 291 292 :::::tabs 293 294 ==== promicro 295 296  297 298 <!-- ```svgbob 299 pins 300 .-------------. LEDs 301 | | _|_ _|_ 302 D3 -+-O | \ /B0 \ /D5 303 D2 -+-O | -+- -+- 304 | | | | 305 | | 306 D1 -+-O O-+- F4 307 D0 -+-O O-+- F5 308 D4 -+-O O-+- F6 309 C6 -+-O O-+- F7 310 D7 -+-O O-+- B1 311 E6 -+-O O-+- B3 312 B4 -+-O O-+- B2 313 B5 -+-O O-+- B6 314 | | 315 '---+-+-+-+-+---' 316 ``` --> 317 318 ::: info Notes: 319 Includes LEDs - these may be mapped to unused/unavailable pins when not present. 320 ::: 321 322 ==== elite_c 323 324  325 326 <!-- ```svgbob 327 pins 328 .-------------. 329 | | 330 D3 -+-O | 331 D2 -+-O | 332 | | 333 | | 334 D1 -+-O O-+- F4 335 D0 -+-O O-+- F5 336 D4 -+-O O-+- F6 337 C6 -+-O O-+- F7 338 D7 -+-O O-+- B1 339 E6 -+-O O-+- B3 340 B4 -+-O O-+- B2 341 B5 -+-O O O O O O O-+- B6 342 | | | | | | | 343 '---+-+-+-+-+---' 344 + + + + + 345 B D C F F 346 7 5 7 1 0 347 ``` --> 348 349 ::: info Notes: 350 Includes bottom row pins, no LEDs. 351 ::: 352 353 :::::