M docs/_summary.md => docs/_summary.md +2 -1
@@ 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)
A docs/feature_converters.md => docs/feature_converters.md +95 -0
@@ 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).
R docs/proton_c_conversion.md => docs/platformdev_proton_c.md +18 -32
@@ 1,46 1,32 @@
-# Converting a board to use the Proton C
+# 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.
+The Proton C is an Arm STM32F303xC based drop-in replacement for the Pro Micro.
-## Automatic Conversion
+<img src="https://i.imgur.com/GdsN1Rdh.jpg" alt="Proton C" />
-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:
+#### Features
- make 40percentclub/mf68:default CTPC=yes
+* 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
-You can add the same argument to your keymap's `rules.mk`, which will accomplish the same thing.
+## Warnings
-This exposes the `CONVERT_TO_PROTON_C` flag that you can use in your code with `#ifdef`s, like this:
+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.
-```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.
+So far, it appears that this is only an issue on the Gherkin PCBs, but other PCBs may be affected in this way.
-| 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 |
+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 `CTPC=yes`, you need to change the `MCU` line in `rules.mk`:
+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