Add converter docs (#17593)

Speed1 · Jul 8, 2022 · 345e19f · 345e19f
1 parent 81d317a
commit 345e19f
Show file tree

Hide file tree

Showing 4 changed files with 174 additions and 92 deletions.
diff --git a/docs/_summary.md b/docs/_summary.md
@@ -107,6 +107,7 @@
     * [Audio](feature_audio.md)
     * [Bluetooth](feature_bluetooth.md)
     * [Bootmagic Lite](feature_bootmagic.md)
+    * [Converters](feature_converters.md)
     * [Custom Matrix](custom_matrix.md)
     * [Digitizer](feature_digitizer.md)
     * [DIP Switch](feature_dip_switch.md)
@@ -115,7 +116,6 @@
     * [Joystick](feature_joystick.md)
     * [LED Indicators](feature_led_indicators.md)
     * [MIDI](feature_midi.md)
-    * [Proton C Conversion](proton_c_conversion.md)
     * [PS/2 Mouse](feature_ps2_mouse.md)
     * [Split Keyboard](feature_split_keyboard.md)
     * [Stenography](feature_stenography.md)
@@ -167,6 +167,7 @@
       * [Selecting an MCU](platformdev_selecting_arm_mcu.md)
       * [Early initialization](platformdev_chibios_earlyinit.md)
       * [Raspberry Pi RP2040](platformdev_rp2040.md)
+      * [Proton C](platformdev_proton_c.md)
 
   * QMK Reference
     * [Contributing to QMK](contributing.md)

diff --git a/docs/feature_converters.md b/docs/feature_converters.md
@@ -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).
diff --git a/docs/platformdev_proton_c.md b/docs/platformdev_proton_c.md
@@ -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.
diff --git a/docs/proton_c_conversion.md b/docs/proton_c_conversion.md