ISP flashing guide: add instructions for flashing STM32duino bootloader (#16568)

1 files changed, 91 insertions, 1 deletions

diff --git a/docs/isp_flashing_guide.md b/docs/isp_flashing_guide.md
index febb34c574..08f56e987b 100644
--- a/docs/isp_flashing_guide.md
+++ b/docs/isp_flashing_guide.md
@@ -4,7 +4,7 @@ In order to flash a microcontroller over USB, it needs something called a bootlo
 
 However, it can sometimes happen that the bootloader becomes corrupted and needs reflashing, or you may want to change the bootloader to another one. It's not possible to do this with the existing bootloader, because, of course, it is already running, and cannot overwrite itself. Instead, you will need to ISP flash the microcontroller.
 
-There are several different kinds of bootloaders available for AVR microcontrollers. Most STM32 ARM-based microcontrollers already have a USB-capable bootloader in ROM, so generally do not need to be ISP flashed.
+There are several different kinds of bootloaders available for AVR microcontrollers. Most STM32 ARM-based microcontrollers already have a USB-capable bootloader in ROM, so generally do not need to be ISP flashed. The one current exception is the [STM32F103](#flashing-stm32duino-bootloader).
 
 ## Hardware
 
@@ -260,3 +260,93 @@ For mass production purposes, it is possible to join the bootloader and QMK firm
  4. Save it as a new file, for example `<keyboard>_<keymap>_production.hex`.
 
 You can then ISP flash this combined firmware instead, which allows you to skip the extra step of flashing the QMK firmware over USB.
+
+## Flashing STM32Duino Bootloader
+
+As mentioned above, *most* supported STM32 devices already possess a USB DFU bootloader which cannot be overwritten, however the ROM bootloader in the STM32F103 used on the Bluepill is not USB capable. In this case an ST-Link V2 dongle is required to upload the STM32Duino bootloader to the device. These can be readily purchased for relatively cheap on eBay and other places.
+
+This bootloader is a descendant of the Maple bootloader by Leaflabs, and is compatible with dfu-util.
+
+### Software
+
+To communicate with the ST-Link, you must install the following packages:
+
+* **macOS:** `brew install stlink openocd`
+* **Windows (MSYS2):** `pacman -S mingw-w64-x86_64-stlink mingw-w64-x86_64-openocd`
+* **Linux:** will vary by distribution, but will likely be `stlink` and `openocd` through your particular package manager
+
+Additionally, you may need to update the ST-Link's firmware with the [`STSW-LINK007`](https://www.st.com/en/development-tools/stsw-link007.html) application. Note you will be asked to provide your name and email address if you do not have an ST.com account (this does not create one).
+
+Finally, the bootloader binary itself can be downloaded from [here](https://github.com/rogerclarkmelbourne/STM32duino-bootloader/blob/master/bootloader_only_binaries/generic_boot20_pc13.bin).
+
+### Wiring
+
+Connect the four-pin header on the end of the Bluepill to the matching pins on the ST-Link (the pinout will usually be printed on the side):
+
+|ST-Link      |Bluepill|
+|-------------|--------|
+|`GND` (6)    |`GND`   |
+|`SWCLK` (2)  |`DCLK`  |
+|`SWDIO` (4)  |`DIO`   |
+|`3.3V` (8)   |`3.3`   |
+
+### Flashing
+
+Firstly, make sure both jumpers on the Bluepill are set to 0.
+
+Check that the ST-Link can talk to the Bluepill by running `st-info --probe`:
+
+```
+Found 1 stlink programmers
+  version:    V2J37S7
+  serial:     2C1219002B135937334D4E00
+  flash:      65536 (pagesize: 1024)
+  sram:       20480
+  chipid:     0x0410
+  descr:      F1xx Medium-density
+```
+
+If the reported `chipid` is `0x0410`, everything is working. If it is `0x0000`, check your wiring, and try swapping the `SWDIO` and `SWCLK` pins, as some ST-Link dongles may have incorrect pinouts.
+
+Next, run the following command:
+
+```
+st-flash --reset --format binary write <path-to-bootloader> 0x08000000
+```
+
+where `<path-to-bootloader>` is the path to the bootloader `.bin` file above. You can run this command from the directory you downloaded it to, so that you can simply pass in the filename.
+
+If all goes well, you should get output similar to the following:
+
+```
+st-flash 1.7.0
+2022-03-08T12:16:30 INFO common.c: F1xx Medium-density: 20 KiB SRAM, 64 KiB flash in at least 1 KiB pages.
+file generic_boot20_pc13.bin md5 checksum: 333c30605e739ce9bedee5999fdaf81b, stlink checksum: 0x0008e534
+2022-03-08T12:16:30 INFO common.c: Attempting to write 7172 (0x1c04) bytes to stm32 address: 134217728 (0x8000000)
+2022-03-08T12:16:30 INFO common.c: Flash page at addr: 0x08000000 erased
+2022-03-08T12:16:30 INFO common.c: Flash page at addr: 0x08000400 erased
+2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08000800 erased
+2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08000c00 erased
+2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001000 erased
+2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001400 erased
+2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001800 erased
+2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001c00 erased
+2022-03-08T12:16:31 INFO common.c: Finished erasing 8 pages of 1024 (0x400) bytes
+2022-03-08T12:16:31 INFO common.c: Starting Flash write for VL/F0/F3/F1_XL
+2022-03-08T12:16:31 INFO flash_loader.c: Successfully loaded flash loader in sram
+2022-03-08T12:16:31 INFO flash_loader.c: Clear DFSR
+  8/  8 pages written
+2022-03-08T12:16:31 INFO common.c: Starting verification of write complete
+2022-03-08T12:16:31 INFO common.c: Flash written and verified! jolly good!
+2022-03-08T12:16:31 WARN common.c: NRST is not connected
+```
+
+Otherwise, if you receive an `Unknown memory region` error, run the following command to unlock the STM32F103:
+
+```
+openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c "init; reset halt; stm32f1x unlock 0; reset halt; exit"
+```
+
+Then re-plug the ST-Link and try again.
+
+After all of this, unplug the Bluepill from the ST-Link and connect it to USB. It should now be ready to flash using dfu-util, the QMK CLI or Toolbox.