Rework converter docs (#18314)

3 files changed, 369 insertions, 101 deletions

diff --git a/docs/feature_converters.md b/docs/feature_converters.md
index 06cc7b3a11..4e0a23752c 100644
--- a/docs/feature_converters.md
+++ b/docs/feature_converters.md
@@ -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.
 
+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
 
+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:
 
 | From       | To                |
@@ -28,86 +42,56 @@ The following converters are available at this time:
 | `elite_c`  | `helios`          |
 | `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
-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.
-
-::: 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.
-:::
+==== keymap.json
 
-### 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
+```json [keymap.json]
+{
+    "version": 1,
+    "keyboard": "keebio/bdn9/rev1",
+    "keymap": "keebio_bdn9_rev1_layout_2025-05-20",
+    "converter": "proton_c", // [!code focus]
+    "layout": "LAYOUT",
+}
 ```
 
-### 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`:
+==== rules.mk
 
 ```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:
-
-| 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)                   | `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:
-
-| 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`          |
-| `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`            |
-| `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`        |
-| `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`       |
-| `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`         |
-| `imera`           | `-e CONVERT_TO=imera`           | `CONVERT_TO=imera`           | `#ifdef CONVERT_TO_IMERA`           |
-| `michi`           | `-e CONVERT_TO=michi`           | `CONVERT_TO=michi`           | `#ifdef CONVERT_TO_MICHI`           |
-| `svlinky`         | `-e CONVERT_TO=svlinky`         | `CONVERT_TO=svlinky`         | `#ifdef CONVERT_TO_SVLINKY`         |
+:::::
+
+::: 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.
+:::
+
+## Pro Micro Converters
+
+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:
+
+| Device                                                                                   | Target            | CLI Argument                    | `rules.mk`                   | Condition                           |
+|------------------------------------------------------------------------------------------|-------------------|---------------------------------|------------------------------|-------------------------------------|
+| [Proton C](https://qmk.fm/proton-c/)                                                     | `proton_c`        | `-e CONVERT_TO=proton_c`        | `CONVERT_TO=proton_c`        | `#ifdef CONVERT_TO_PROTON_C`        |
+| [Adafruit KB2040](https://learn.adafruit.com/adafruit-kb2040)                            | `kb2040`          | `-e CONVERT_TO=kb2040`          | `CONVERT_TO=kb2040`          | `#ifdef CONVERT_TO_KB2040`          |
+| [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](https://boardsource.xyz/store/628b95b494dfa308a6581622)                           | `blok`            | `-e CONVERT_TO=blok`            | `CONVERT_TO=blok`            | `#ifdef CONVERT_TO_BLOK`            |
+| [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](https://github.com/megamind4089/STeMCell)                                     | `stemcell`        | `-e CONVERT_TO=stemcell`        | `CONVERT_TO=stemcell`        | `#ifdef CONVERT_TO_STEMCELL`        |
+| [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 Community Edition](#rp2040_ce)                                                   | `rp2040_ce`       | `-e CONVERT_TO=rp2040_ce`       | `CONVERT_TO=rp2040_ce`       | `#ifdef CONVERT_TO_RP2040_CE`       |
+| [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`        |
+| [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`         |
+| [Imera](https://splitkb.com/products/imera)                                              | `imera`           | `-e CONVERT_TO=imera`           | `CONVERT_TO=imera`           | `#ifdef CONVERT_TO_IMERA`           |
+| [Michi](https://github.com/ci-bus/michi-promicro-rp2040)                                 | `michi`           | `-e CONVERT_TO=michi`           | `CONVERT_TO=michi`           | `#ifdef CONVERT_TO_MICHI`           |
+| [Svlinky](https://github.com/sadekbaroudi/svlinky)                                       | `svlinky`         | `-e CONVERT_TO=svlinky`         | `CONVERT_TO=svlinky`         | `#ifdef CONVERT_TO_SVLINKY`         |
 
 ### Proton C {#proton_c}
 
@@ -119,26 +103,26 @@ 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.
 
-| Feature                                      | Notes                                                                                                            |
-|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
-| [Audio](features/audio)                    | Enabled                                                                                                          |
-| [RGB Lighting](features/rgblight)          | Disabled                                                                                                         |
+| Feature                                    | Notes                                                                                                          |
+|--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| [Audio](features/audio)                    | Enabled                                                                                                        |
+| [RGB Lighting](features/rgblight)          | Disabled                                                                                                       |
 | [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)                              |
-| [Split keyboards](features/split_keyboard) | Partial - heavily dependent on enabled features                                                                  |
+| USB Host (e.g. USB-USB converter)          | Not supported (USB host code is AVR specific and is not currently supported on ARM)                            |
+| [Split keyboards](features/split_keyboard) | Partial - heavily dependent on enabled features                                                                |
 
 ### Adafruit KB2040 {#kb2040}
 
 The following defaults are based on what has been implemented for [RP2040](platformdev_rp2040) boards.
 
-| Feature                                      | Notes                                                                                                            |
-|----------------------------------------------|------------------------------------------------------------------------------------------------------------------|
-| [RGB Lighting](features/rgblight)          | Enabled via `PIO` vendor driver                                                                                  |
+| Feature                                    | Notes                                                                                                          |
+|--------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| [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 |
-| USB Host (e.g. USB-USB converter)            | Not supported (USB host code is AVR specific and is not currently supported on ARM)                              |
-| [Split keyboards](features/split_keyboard) | Partial via `PIO` vendor driver - heavily dependent on enabled features                                          |
+| USB Host (e.g. USB-USB converter)          | Not supported (USB host code is AVR specific and is not currently supported on ARM)                            |
+| [Split keyboards](features/split_keyboard) | Partial via `PIO` vendor driver - heavily dependent on enabled features                                        |
 
-### SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi {#sparkfun_pm2040 }
+### SparkFun Pro Micro - RP2040, Blok, Bit-C PRO and Michi {#sparkfun_pm2040}
 
 Feature set is identical to [Adafruit KB2040](#kb2040).
 
@@ -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.
 
-## Elite-C
-
-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:
+## Elite-C Converters
 
-| Device                                                                           | Target            |
-|----------------------------------------------------------------------------------|-------------------|
-| [STeMCell](https://github.com/megamind4089/STeMCell)                             | `stemcell`        |
-| [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`         |
+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:
 
-Converter summary:
+| Device                                                                           | Target      | CLI Argument              | `rules.mk`             | Condition                     |
+|----------------------------------------------------------------------------------|-------------|---------------------------|------------------------|-------------------------------|
+| [STeMCell](https://github.com/megamind4089/STeMCell)                             | `stemcell`  | `-e CONVERT_TO=stemcell`  | `CONVERT_TO=stemcell`  | `#ifdef CONVERT_TO_STEMCELL`  |
+| [RP2040 Community Edition](#rp2040_ce_elite)                                     | `rp2040_ce` | `-e CONVERT_TO=rp2040_ce` | `CONVERT_TO=rp2040_ce` | `#ifdef CONVERT_TO_RP2040_CE` |
+| [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`  |
+| [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`   |
 
-| 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
+### STeMCell {#stemcell_elite}
 
 Identical to [Pro Micro - STeMCell](#stemcell) with support for the additional bottom row of pins.
 
 ### RP2040 Community Edition {#rp2040_ce_elite}
 
 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.
+:::
+
+:::::
diff --git a/docs/public/pin_compatible_elite_c.svg b/docs/public/pin_compatible_elite_c.svg
new file mode 100644
index 0000000000..cb54d9dfe4
--- /dev/null
+++ b/docs/public/pin_compatible_elite_c.svg
@@ -0,0 +1,61 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="208" height="352" class="svgbob"><style>.svgbob line, .svgbob path, .svgbob circle, .svgbob rect, .svgbob polygon {
+    stroke: black;
+    stroke-width: 2;
+    stroke-opacity: 1;
+    fill-opacity: 1;
+    stroke-linecap: round;
+    stroke-linejoin: miter;
+}
+.svgbob text {
+    white-space: pre;
+    fill: black;
+    font-family: Iosevka Fixed, monospace;
+    font-size: 14px;
+}
+.svgbob rect.backdrop {
+    stroke: none;
+    fill: white;
+}
+.svgbob .broken {
+    stroke-dasharray: 8;
+}
+.svgbob .filled {
+    fill: black;
+}
+.svgbob .bg_filled {
+    fill: white;
+    stroke-width: 1;
+}
+.svgbob .nofill {
+    fill: white;
+}
+.svgbob .end_marked_arrow {
+    marker-end: url(#arrow);
+}
+.svgbob .start_marked_arrow {
+    marker-start: url(#arrow);
+}
+.svgbob .end_marked_diamond {
+    marker-end: url(#diamond);
+}
+.svgbob .start_marked_diamond {
+    marker-start: url(#diamond);
+}
+.svgbob .end_marked_circle {
+    marker-end: url(#circle);
+}
+.svgbob .start_marked_circle {
+    marker-start: url(#circle);
+}
+.svgbob .end_marked_open_circle {
+    marker-end: url(#open_circle);
+}
+.svgbob .start_marked_open_circle {
+    marker-start: url(#open_circle);
+}
+.svgbob .end_marked_big_open_circle {
+    marker-end: url(#big_open_circle);
+}
+.svgbob .start_marked_big_open_circle {
+    marker-start: url(#big_open_circle);
+}<!--separator--></style><defs><marker id="arrow" viewBox="-2 -2 8 8" refX="4" refY="2" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><polygon points="0,0 0,4 4,2 0,0"></polygon></marker><marker id="diamond" viewBox="-2 -2 8 8" refX="4" refY="2" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><polygon points="0,2 2,0 4,2 2,4 0,2"></polygon></marker><marker id="circle" viewBox="0 0 8 8" refX="4" refY="4" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><circle cx="4" cy="4" r="2" class="filled"></circle></marker><marker id="open_circle" viewBox="0 0 8 8" refX="4" refY="4" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><circle cx="4" cy="4" r="2" class="bg_filled"></circle></marker><marker id="big_open_circle" viewBox="0 0 8 8" refX="4" refY="4" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><circle cx="4" cy="4" r="3" class="bg_filled"></circle></marker></defs><rect class="backdrop" x="0" y="0" width="208" height="352"></rect><text x="82" y="28" >pins</text><line x1="24" y1="72" x2="52" y2="72" class="solid end_marked_big_open_circle"></line><line x1="24" y1="88" x2="52" y2="88" class="solid end_marked_big_open_circle"></line><line x1="24" y1="136" x2="52" y2="136" class="solid end_marked_big_open_circle"></line><line x1="160" y1="136" x2="148" y2="136" class="solid end_marked_big_open_circle"></line><line x1="160" y1="136" x2="176" y2="136" class="solid"></line><line x1="24" y1="152" x2="52" y2="152" class="solid end_marked_big_open_circle"></line><line x1="160" y1="152" x2="148" y2="152" class="solid end_marked_big_open_circle"></line><line x1="160" y1="152" x2="176" y2="152" class="solid"></line><line x1="24" y1="168" x2="52" y2="168" class="solid end_marked_big_open_circle"></line><line x1="160" y1="168" x2="148" y2="168" class="solid end_marked_big_open_circle"></line><line x1="160" y1="168" x2="176" y2="168" class="solid"></line><line x1="24" y1="184" x2="52" y2="184" class="solid end_marked_big_open_circle"></line><line x1="160" y1="184" x2="148" y2="184" class="solid end_marked_big_open_circle"></line><line x1="160" y1="184" x2="176" y2="184" class="solid"></line><line x1="24" y1="200" x2="52" y2="200" class="solid end_marked_big_open_circle"></line><line x1="160" y1="200" x2="148" y2="200" class="solid end_marked_big_open_circle"></line><line x1="160" y1="200" x2="176" y2="200" class="solid"></line><line x1="24" y1="216" x2="52" y2="216" class="solid end_marked_big_open_circle"></line><line x1="160" y1="216" x2="148" y2="216" class="solid end_marked_big_open_circle"></line><line x1="160" y1="216" x2="176" y2="216" class="solid"></line><line x1="24" y1="232" x2="52" y2="232" class="solid end_marked_big_open_circle"></line><line x1="160" y1="232" x2="148" y2="232" class="solid end_marked_big_open_circle"></line><line x1="160" y1="232" x2="176" y2="232" class="solid"></line><line x1="24" y1="248" x2="52" y2="248" class="solid end_marked_big_open_circle"></line><line x1="68" y1="252" x2="68" y2="248" class="solid end_marked_big_open_circle"></line><line x1="84" y1="252" x2="84" y2="248" class="solid end_marked_big_open_circle"></line><line x1="100" y1="252" x2="100" y2="248" class="solid end_marked_big_open_circle"></line><line x1="116" y1="252" x2="116" y2="248" class="solid end_marked_big_open_circle"></line><line x1="132" y1="252" x2="132" y2="248" class="solid end_marked_big_open_circle"></line><line x1="160" y1="248" x2="148" y2="248" class="solid end_marked_big_open_circle"></line><line x1="160" y1="248" x2="176" y2="248" class="solid"></line><line x1="68" y1="256" x2="68" y2="296" class="solid"></line><line x1="84" y1="256" x2="84" y2="296" class="solid"></line><line x1="100" y1="256" x2="100" y2="296" class="solid"></line><line x1="116" y1="256" x2="116" y2="296" class="solid"></line><line x1="132" y1="256" x2="132" y2="296" class="solid"></line><text x="66" y="316" >B</text><text x="82" y="316" >D</text><text x="98" y="316" >C</text><text x="114" y="316" >F</text><text x="130" y="316" >F</text><text x="66" y="332" >7</text><text x="82" y="332" >5</text><text x="98" y="332" >7</text><text x="114" y="332" >1</text><text x="130" y="332" >0</text><text x="2" y="76" >D3</text><text x="2" y="92" >D2</text><text x="2" y="140" >D1</text><text x="2" y="156" >D0</text><text x="2" y="172" >D4</text><text x="2" y="188" >C6</text><text x="2" y="204" >D7</text><text x="2" y="220" >E6</text><text x="2" y="236" >B4</text><text x="2" y="252" >B5</text><text x="186" y="140" >F4</text><text x="186" y="156" >F5</text><text x="186" y="172" >F6</text><text x="186" y="188" >F7</text><text x="186" y="204" >B1</text><text x="186" y="220" >B3</text><text x="186" y="236" >B2</text><text x="186" y="252" >B6</text><g><path d="M 44,40 A 8,8 0,0,0 36,48" class="nofill"></path><line x1="44" y1="40" x2="156" y2="40" class="solid"></line><path d="M 156,40 A 8,8 0,0,1 164,48" class="nofill"></path><line x1="36" y1="48" x2="36" y2="276" class="solid"></line><line x1="164" y1="48" x2="164" y2="276" class="solid"></line><path d="M 36,276 A 4,4 0,0,0 40,280" class="nofill"></path><line x1="40" y1="280" x2="160" y2="280" class="solid"></line><path d="M 164,276 A 4,4 0,0,1 160,280" class="nofill"></path></g></svg>
\ No newline at end of file
diff --git a/docs/public/pin_compatible_promicro.svg b/docs/public/pin_compatible_promicro.svg
new file mode 100644
index 0000000000..044b265a57
--- /dev/null
+++ b/docs/public/pin_compatible_promicro.svg
@@ -0,0 +1,61 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="344" height="288" class="svgbob"><style>.svgbob line, .svgbob path, .svgbob circle, .svgbob rect, .svgbob polygon {
+    stroke: black;
+    stroke-width: 2;
+    stroke-opacity: 1;
+    fill-opacity: 1;
+    stroke-linecap: round;
+    stroke-linejoin: miter;
+}
+.svgbob text {
+    white-space: pre;
+    fill: black;
+    font-family: Iosevka Fixed, monospace;
+    font-size: 14px;
+}
+.svgbob rect.backdrop {
+    stroke: none;
+    fill: white;
+}
+.svgbob .broken {
+    stroke-dasharray: 8;
+}
+.svgbob .filled {
+    fill: black;
+}
+.svgbob .bg_filled {
+    fill: white;
+    stroke-width: 1;
+}
+.svgbob .nofill {
+    fill: white;
+}
+.svgbob .end_marked_arrow {
+    marker-end: url(#arrow);
+}
+.svgbob .start_marked_arrow {
+    marker-start: url(#arrow);
+}
+.svgbob .end_marked_diamond {
+    marker-end: url(#diamond);
+}
+.svgbob .start_marked_diamond {
+    marker-start: url(#diamond);
+}
+.svgbob .end_marked_circle {
+    marker-end: url(#circle);
+}
+.svgbob .start_marked_circle {
+    marker-start: url(#circle);
+}
+.svgbob .end_marked_open_circle {
+    marker-end: url(#open_circle);
+}
+.svgbob .start_marked_open_circle {
+    marker-start: url(#open_circle);
+}
+.svgbob .end_marked_big_open_circle {
+    marker-end: url(#big_open_circle);
+}
+.svgbob .start_marked_big_open_circle {
+    marker-start: url(#big_open_circle);
+}<!--separator--></style><defs><marker id="arrow" viewBox="-2 -2 8 8" refX="4" refY="2" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><polygon points="0,0 0,4 4,2 0,0"></polygon></marker><marker id="diamond" viewBox="-2 -2 8 8" refX="4" refY="2" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><polygon points="0,2 2,0 4,2 2,4 0,2"></polygon></marker><marker id="circle" viewBox="0 0 8 8" refX="4" refY="4" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><circle cx="4" cy="4" r="2" class="filled"></circle></marker><marker id="open_circle" viewBox="0 0 8 8" refX="4" refY="4" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><circle cx="4" cy="4" r="2" class="bg_filled"></circle></marker><marker id="big_open_circle" viewBox="0 0 8 8" refX="4" refY="4" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><circle cx="4" cy="4" r="3" class="bg_filled"></circle></marker></defs><rect class="backdrop" x="0" y="0" width="344" height="288"></rect><text x="82" y="12" >pins</text><line x1="24" y1="56" x2="52" y2="56" class="solid end_marked_big_open_circle"></line><line x1="24" y1="72" x2="52" y2="72" class="solid end_marked_big_open_circle"></line><line x1="24" y1="120" x2="52" y2="120" class="solid end_marked_big_open_circle"></line><line x1="160" y1="120" x2="148" y2="120" class="solid end_marked_big_open_circle"></line><line x1="160" y1="120" x2="176" y2="120" class="solid"></line><line x1="24" y1="136" x2="52" y2="136" class="solid end_marked_big_open_circle"></line><line x1="160" y1="136" x2="148" y2="136" class="solid end_marked_big_open_circle"></line><line x1="160" y1="136" x2="176" y2="136" class="solid"></line><line x1="24" y1="152" x2="52" y2="152" class="solid end_marked_big_open_circle"></line><line x1="160" y1="152" x2="148" y2="152" class="solid end_marked_big_open_circle"></line><line x1="160" y1="152" x2="176" y2="152" class="solid"></line><line x1="24" y1="168" x2="52" y2="168" class="solid end_marked_big_open_circle"></line><line x1="160" y1="168" x2="148" y2="168" class="solid end_marked_big_open_circle"></line><line x1="160" y1="168" x2="176" y2="168" class="solid"></line><line x1="24" y1="184" x2="52" y2="184" class="solid end_marked_big_open_circle"></line><line x1="160" y1="184" x2="148" y2="184" class="solid end_marked_big_open_circle"></line><line x1="160" y1="184" x2="176" y2="184" class="solid"></line><line x1="24" y1="200" x2="52" y2="200" class="solid end_marked_big_open_circle"></line><line x1="160" y1="200" x2="148" y2="200" class="solid end_marked_big_open_circle"></line><line x1="160" y1="200" x2="176" y2="200" class="solid"></line><line x1="24" y1="216" x2="52" y2="216" class="solid end_marked_big_open_circle"></line><line x1="160" y1="216" x2="148" y2="216" class="solid end_marked_big_open_circle"></line><line x1="160" y1="216" x2="176" y2="216" class="solid"></line><line x1="24" y1="232" x2="52" y2="232" class="solid end_marked_big_open_circle"></line><line x1="160" y1="232" x2="148" y2="232" class="solid end_marked_big_open_circle"></line><line x1="160" y1="232" x2="176" y2="232" class="solid"></line><text x="250" y="28" >LEDs</text><text x="242" y="60" >B0</text><text x="322" y="60" >D5</text><text x="2" y="60" >D3</text><text x="2" y="76" >D2</text><text x="2" y="124" >D1</text><text x="2" y="140" >D0</text><text x="2" y="156" >D4</text><text x="2" y="172" >C6</text><text x="2" y="188" >D7</text><text x="2" y="204" >E6</text><text x="2" y="220" >B4</text><text x="2" y="236" >B5</text><text x="186" y="124" >F4</text><text x="186" y="140" >F5</text><text x="186" y="156" >F6</text><text x="186" y="172" >F7</text><text x="186" y="188" >B1</text><text x="186" y="204" >B3</text><text x="186" y="220" >B2</text><text x="186" y="236" >B6</text><g><path d="M 44,24 A 8,8 0,0,0 36,32" class="nofill"></path><line x1="44" y1="24" x2="156" y2="24" class="solid"></line><path d="M 156,24 A 8,8 0,0,1 164,32" class="nofill"></path><line x1="36" y1="32" x2="36" y2="260" class="solid"></line><line x1="164" y1="32" x2="164" y2="260" class="solid"></line><path d="M 36,260 A 4,4 0,0,0 40,264" class="nofill"></path><line x1="40" y1="264" x2="160" y2="264" class="solid"></line><path d="M 164,260 A 4,4 0,0,1 160,264" class="nofill"></path></g><g><line x1="216" y1="48" x2="240" y2="48" class="solid"></line><line x1="228" y1="32" x2="228" y2="48" class="solid"></line><line x1="216" y1="48" x2="228" y2="72" class="solid"></line><line x1="240" y1="48" x2="228" y2="72" class="solid"></line><line x1="216" y1="72" x2="240" y2="72" class="solid"></line><line x1="228" y1="72" x2="228" y2="96" class="solid"></line></g><g><line x1="296" y1="48" x2="320" y2="48" class="solid"></line><line x1="308" y1="32" x2="308" y2="48" class="solid"></line><line x1="296" y1="48" x2="308" y2="72" class="solid"></line><line x1="320" y1="48" x2="308" y2="72" class="solid"></line><line x1="296" y1="72" x2="320" y2="72" class="solid"></line><line x1="308" y1="72" x2="308" y2="96" class="solid"></line></g></svg>
\ No newline at end of file