Add converter docs (#17593)
This commit is contained in:
Joel Challis
GitHub
parent
81d317aa87
commit
345e19f691
@ -107,6 +107,7 @@
|
|||||||
* [Audio](feature_audio.md)
|
* [Audio](feature_audio.md)
|
||||||
* [Bluetooth](feature_bluetooth.md)
|
* [Bluetooth](feature_bluetooth.md)
|
||||||
* [Bootmagic Lite](feature_bootmagic.md)
|
* [Bootmagic Lite](feature_bootmagic.md)
|
||||||
|
* [Converters](feature_converters.md)
|
||||||
* [Custom Matrix](custom_matrix.md)
|
* [Custom Matrix](custom_matrix.md)
|
||||||
* [Digitizer](feature_digitizer.md)
|
* [Digitizer](feature_digitizer.md)
|
||||||
* [DIP Switch](feature_dip_switch.md)
|
* [DIP Switch](feature_dip_switch.md)
|
||||||
@ -115,7 +116,6 @@
|
|||||||
* [Joystick](feature_joystick.md)
|
* [Joystick](feature_joystick.md)
|
||||||
* [LED Indicators](feature_led_indicators.md)
|
* [LED Indicators](feature_led_indicators.md)
|
||||||
* [MIDI](feature_midi.md)
|
* [MIDI](feature_midi.md)
|
||||||
* [Proton C Conversion](proton_c_conversion.md)
|
|
||||||
* [PS/2 Mouse](feature_ps2_mouse.md)
|
* [PS/2 Mouse](feature_ps2_mouse.md)
|
||||||
* [Split Keyboard](feature_split_keyboard.md)
|
* [Split Keyboard](feature_split_keyboard.md)
|
||||||
* [Stenography](feature_stenography.md)
|
* [Stenography](feature_stenography.md)
|
||||||
@ -167,6 +167,7 @@
|
|||||||
* [Selecting an MCU](platformdev_selecting_arm_mcu.md)
|
* [Selecting an MCU](platformdev_selecting_arm_mcu.md)
|
||||||
* [Early initialization](platformdev_chibios_earlyinit.md)
|
* [Early initialization](platformdev_chibios_earlyinit.md)
|
||||||
* [Raspberry Pi RP2040](platformdev_rp2040.md)
|
* [Raspberry Pi RP2040](platformdev_rp2040.md)
|
||||||
|
* [Proton C](platformdev_proton_c.md)
|
||||||
|
|
||||||
* QMK Reference
|
* QMK Reference
|
||||||
* [Contributing to QMK](contributing.md)
|
* [Contributing to QMK](contributing.md)
|
||||||
|
|||||||
95
docs/feature_converters.md
Normal file
95
docs/feature_converters.md
Normal file
@ -0,0 +1,95 @@
|
|||||||
|
# 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` |
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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, so you'll need to convert the keyboard's code to use the [GPIO Controls](gpio_control.md) 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
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
| 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) | `promicro_rp2040` |
|
||||||
|
|
||||||
|
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` |
|
||||||
|
|
||||||
|
### 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 like to your `config.h`:
|
||||||
|
|
||||||
|
```c
|
||||||
|
#define CONVERT_TO_PROTON_C_RXLED
|
||||||
|
```
|
||||||
|
|
||||||
|
The following defaults are based on what has been implemented for STM32 boards.
|
||||||
|
|
||||||
|
| Feature | Notes |
|
||||||
|
|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| [Audio](feature_audio.md) | Enabled |
|
||||||
|
| [RGB Lighting](feature_rgblight.md) | Disabled |
|
||||||
|
| [Backlight](feature_backlight.md) | Forces [task driven PWM](feature_backlight.md#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) |
|
||||||
|
| [Split keyboards](feature_split_keyboard.md) | Partial - heavily dependent on enabled features |
|
||||||
|
|
||||||
|
### Adafruit KB2040 :id=kb2040
|
||||||
|
|
||||||
|
The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040.md) boards.
|
||||||
|
|
||||||
|
| Feature | Notes |
|
||||||
|
|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| [RGB Lighting](feature_rgblight.md) | Enabled via `PIO` vendor driver |
|
||||||
|
| [Backlight](feature_backlight.md) | Forces [task driven PWM](feature_backlight.md#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) |
|
||||||
|
| [Split keyboards](feature_split_keyboard.md) | Partial via `PIO` vendor driver - heavily dependent on enabled features |
|
||||||
|
|
||||||
|
### SparkFun Pro Micro - RP2040 :id=promicro_rp2040
|
||||||
|
|
||||||
|
Currently identical to [Adafruit KB2040](#kb2040).
|
||||||
77
docs/platformdev_proton_c.md
Normal file
77
docs/platformdev_proton_c.md
Normal file
@ -0,0 +1,77 @@
|
|||||||
|
# Proton C
|
||||||
|
|
||||||
|
The Proton C is an Arm STM32F303xC based drop-in replacement for the Pro Micro.
|
||||||
|
|
||||||
|
<img src="https://i.imgur.com/GdsN1Rdh.jpg" alt="Proton C" />
|
||||||
|
|
||||||
|
#### Features
|
||||||
|
|
||||||
|
* Through-hole mounted USB-C Port
|
||||||
|
* 32-bit 72MHz Cortex-M4 processor (STM32F303CCT6)
|
||||||
|
* I2C, SPI, PWM, DMA, DAC, USART, I2S
|
||||||
|
* 23x 3.3V I/O Ports
|
||||||
|
* 1x 5V output for WS2812 LED chains
|
||||||
|
* 256kB flash
|
||||||
|
* 40kB RAM
|
||||||
|
* AST1109MLTRQ speaker footprint
|
||||||
|
* Reset button
|
||||||
|
|
||||||
|
## Warnings
|
||||||
|
|
||||||
|
Some of the PCBs compatible with Pro Micro have VCC (3.3V) and RAW (5V) pins connected (shorted) on the pcb. Using the Proton C will short 5V power from USB and regulated 3.3V which is connected directly to the MCU. Shorting those pins may damage the MCU on the Proton C.
|
||||||
|
|
||||||
|
So far, it appears that this is only an issue on the Gherkin PCBs, but other PCBs may be affected in this way.
|
||||||
|
|
||||||
|
In this case, you may want to not hook up the RAW pin at all.
|
||||||
|
|
||||||
|
## Manual Conversion
|
||||||
|
|
||||||
|
To use the Proton C natively, without having to specify `CONVERT_TO=proton_c`, you need to change the `MCU` line in `rules.mk`:
|
||||||
|
|
||||||
|
```
|
||||||
|
MCU = STM32F303
|
||||||
|
BOARD = QMK_PROTON_C
|
||||||
|
```
|
||||||
|
|
||||||
|
Remove these variables if they exist:
|
||||||
|
|
||||||
|
* `BOOTLOADER`
|
||||||
|
* `EXTRA_FLAGS`
|
||||||
|
|
||||||
|
Finally convert all pin assignments in `config.h` to the stm32 equivalents.
|
||||||
|
|
||||||
|
| Pro Micro Left | Proton C Left | | Proton C Right | Pro Micro Right |
|
||||||
|
|-----------|----------|-|----------|-----------|
|
||||||
|
| `D3` | `A9` | | 5v | RAW (5v) |
|
||||||
|
| `D2` | `A10` | | GND | GND |
|
||||||
|
| GND | GND | | FLASH | RESET |
|
||||||
|
| GND | GND | | 3.3v | VCC <sup>1</sup> |
|
||||||
|
| `D1` | `B7` | | `A2` | `F4` |
|
||||||
|
| `D0` | `B6` | | `A1` | `F5` |
|
||||||
|
| `D4` | `B5` | | `A0` | `F6` |
|
||||||
|
| `C6` | `B4` | | `B8` | `F7` |
|
||||||
|
| `D7` | `B3` | | `B13` | `B1` |
|
||||||
|
| `E6` | `B2` | | `B14` | `B3` |
|
||||||
|
| `B4` | `B1` | | `B15` | `B2` |
|
||||||
|
| `B5` | `B0` | | `B9` | `B6` |
|
||||||
|
| `B0` (RX LED) | `C13` <sup>2</sup> | | `C13` <sup>2</sup> | `D5` (TX LED) |
|
||||||
|
|
||||||
|
You can also make use of several new pins on the extended portion of the Proton C:
|
||||||
|
|
||||||
|
| Left | | Right |
|
||||||
|
|------|-|-------|
|
||||||
|
| `A4`<sup>3</sup> | | `B10` |
|
||||||
|
| `A5`<sup>4</sup> | | `B11` |
|
||||||
|
| `A6` | | `B12` |
|
||||||
|
| `A7` | | `A14`<sup>5</sup> (SWCLK) |
|
||||||
|
| `A8` | | `A13`<sup>5</sup> (SWDIO) |
|
||||||
|
| `A15` | | RESET<sup>6</sup> |
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
|
||||||
|
1. On a Pro Micro VCC can be 3.3v or 5v.
|
||||||
|
2. A Proton C only has one onboard LED, not two like a Pro Micro. The Pro Micro has an RX LED on `D5` and a TX LED on `B0`.
|
||||||
|
3. `A4` is shared with the speaker.
|
||||||
|
4. `A5` is shared with the speaker.
|
||||||
|
5. `A13` and `A14` are used for hardware debugging (SWD). You can also use them for GPIO, but should use them last.
|
||||||
|
6. Short RESET to 3.3v (pull high) to reboot the MCU. This does not enter bootloader mode like a Pro Micro, it only resets the MCU.
|
||||||
@ -1,91 +0,0 @@
|
|||||||
# Converting a board to use the Proton C
|
|
||||||
|
|
||||||
Since the Proton C is a drop-in replacement for a Pro Micro we've made it easy to use. This page documents a handy automated process for converting keyboards, as well as documenting the manual process if you'd like to make use of Proton C features that aren't available on Pro Micros.
|
|
||||||
|
|
||||||
## Automatic Conversion
|
|
||||||
|
|
||||||
If a board currently supported in QMK uses a Pro Micro (or compatible board) and you want to use the Proton C, you can generate the firmware by appending `CONVERT_TO_PROTON_C=yes` (or `CTPC=yes`) to your make argument, like this:
|
|
||||||
|
|
||||||
make 40percentclub/mf68:default CTPC=yes
|
|
||||||
|
|
||||||
You can add the same argument to your keymap's `rules.mk`, which will accomplish the same thing.
|
|
||||||
|
|
||||||
This exposes the `CONVERT_TO_PROTON_C` flag that you can use in your code with `#ifdef`s, like this:
|
|
||||||
|
|
||||||
```c
|
|
||||||
#ifdef CONVERT_TO_PROTON_C
|
|
||||||
// Proton C code
|
|
||||||
#else
|
|
||||||
// Pro Micro code
|
|
||||||
#endif
|
|
||||||
```
|
|
||||||
|
|
||||||
If you get errors about `PORTB/DDRB`, etc not being defined, so you'll need to convert the keyboard's code to use the [GPIO Controls](gpio_control.md) that will work for both ARM and AVR. This shouldn't affect the AVR builds at all.
|
|
||||||
|
|
||||||
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 like to your `config.h`:
|
|
||||||
|
|
||||||
#define CONVERT_TO_PROTON_C_RXLED
|
|
||||||
|
|
||||||
## Feature Conversion
|
|
||||||
|
|
||||||
These are defaults based on what has been implemented for ARM boards.
|
|
||||||
|
|
||||||
| Feature | Notes |
|
|
||||||
|-------------------------------------|------------------------------------------------------------------------------------------------------------------|
|
|
||||||
| [Audio](feature_audio.md) | Enabled |
|
|
||||||
| [RGB Lighting](feature_rgblight.md) | Disabled |
|
|
||||||
| [Backlight](feature_backlight.md) | Forces [task driven PWM](feature_backlight.md#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) |
|
|
||||||
| [Split keyboards](feature_split_keyboard.md) | Partial - heavily dependent on enabled features |
|
|
||||||
|
|
||||||
## Manual Conversion
|
|
||||||
|
|
||||||
To use the Proton C natively, without having to specify `CTPC=yes`, you need to change the `MCU` line in `rules.mk`:
|
|
||||||
|
|
||||||
```
|
|
||||||
MCU = STM32F303
|
|
||||||
BOARD = QMK_PROTON_C
|
|
||||||
```
|
|
||||||
|
|
||||||
Remove these variables if they exist:
|
|
||||||
|
|
||||||
* `BOOTLOADER`
|
|
||||||
* `EXTRA_FLAGS`
|
|
||||||
|
|
||||||
Finally convert all pin assignments in `config.h` to the stm32 equivalents.
|
|
||||||
|
|
||||||
| Pro Micro Left | Proton C Left | | Proton C Right | Pro Micro Right |
|
|
||||||
|-----------|----------|-|----------|-----------|
|
|
||||||
| `D3` | `A9` | | 5v | RAW (5v) |
|
|
||||||
| `D2` | `A10` | | GND | GND |
|
|
||||||
| GND | GND | | FLASH | RESET |
|
|
||||||
| GND | GND | | 3.3v | VCC <sup>1</sup> |
|
|
||||||
| `D1` | `B7` | | `A2` | `F4` |
|
|
||||||
| `D0` | `B6` | | `A1` | `F5` |
|
|
||||||
| `D4` | `B5` | | `A0` | `F6` |
|
|
||||||
| `C6` | `B4` | | `B8` | `F7` |
|
|
||||||
| `D7` | `B3` | | `B13` | `B1` |
|
|
||||||
| `E6` | `B2` | | `B14` | `B3` |
|
|
||||||
| `B4` | `B1` | | `B15` | `B2` |
|
|
||||||
| `B5` | `B0` | | `B9` | `B6` |
|
|
||||||
| `B0` (RX LED) | `C13` <sup>2</sup> | | `C13` <sup>2</sup> | `D5` (TX LED) |
|
|
||||||
|
|
||||||
You can also make use of several new pins on the extended portion of the Proton C:
|
|
||||||
|
|
||||||
| Left | | Right |
|
|
||||||
|------|-|-------|
|
|
||||||
| `A4`<sup>3</sup> | | `B10` |
|
|
||||||
| `A5`<sup>4</sup> | | `B11` |
|
|
||||||
| `A6` | | `B12` |
|
|
||||||
| `A7` | | `A14`<sup>5</sup> (SWCLK) |
|
|
||||||
| `A8` | | `A13`<sup>5</sup> (SWDIO) |
|
|
||||||
| `A15` | | RESET<sup>6</sup> |
|
|
||||||
|
|
||||||
Notes:
|
|
||||||
|
|
||||||
1. On a Pro Micro VCC can be 3.3v or 5v.
|
|
||||||
2. A Proton C only has one onboard LED, not two like a Pro Micro. The Pro Micro has an RX LED on `D5` and a TX LED on `B0`.
|
|
||||||
3. `A4` is shared with the speaker.
|
|
||||||
4. `A5` is shared with the speaker.
|
|
||||||
5. `A13` and `A14` are used for hardware debugging (SWD). You can also use them for GPIO, but should use them last.
|
|
||||||
6. Short RESET to 3.3v (pull high) to reboot the MCU. This does not enter bootloader mode like a Pro Micro, it only resets the MCU.
|
|
||||||
Loading…
Reference in New Issue
Block a user