Python module to upload or download firmware to / from ST Microelectronics STM32 microcontrollers over UART.
Also supports ST BlueNRG devices, and the SweetPeas bootloader for Wiznet W7500.
Compatible with Python version 3.6 to 3.10 and PyPy 3.7 to 3.9.
pip install stm32loader
To install the latest development version:
pip install git+https://github.com/florisla/stm32loader.git
usage: stm32loader [-h] [-e] [-u] [-w] [-v] [-r] [-l LENGTH] -p PORT [-b BAUD] [-a ADDRESS] [-g ADDRESS] [-f FAMILY] [-V] [-q] [-s] [-R] [-B] [-n] [-P {even,none}] [--version] [FILE.BIN]
Flash firmware to STM32 microcontrollers.
positional arguments:
FILE.BIN File to read from or store to flash.
optional arguments:
-h, --help show this help message and exit
-e, --erase Erase (note: this is required on previously written memory).
-u, --unprotect Unprotect in case erase fails.
-w, --write Write file content to flash.
-v, --verify Verify flash content versus local file (recommended).
-r, --read Read from flash and store in local file.
-l LENGTH, --length LENGTH
Length of read.
-p PORT, --port PORT Serial port (default: $STM32LOADER_SERIAL_PORT).
-b BAUD, --baud BAUD Baudrate. (default: 115200)
-a ADDRESS, --address ADDRESS
Target address. (default: 134217728)
-g ADDRESS, --go-address ADDRESS
Start executing from address (0x08000000, usually).
-f FAMILY, --family FAMILY
Device family to read out device UID and flash size; e.g F1 for STM32F1xx (default: $STM32LOADER_FAMILY).
-V, --verbose Verbose mode.
-q, --quiet Quiet mode.
-s, --swap-rts-dtr Swap RTS and DTR: use RTS for reset and DTR for boot0.
-R, --reset-active-high
Make RESET active high.
-B, --boot0-active-low
Make BOOT0 active low.
-n, --no-progress Don't show progress bar.
-P {even,none}, --parity {even,none}
Parity: "even" for STM32, "none" for BlueNRG. (default: even)
--version show program's version number and exit
examples:
stm32loader -p COM7 -f F1
stm32loader -e -w -v example/main.bin
stm32loader -p /dev/tty.usbserial-ftCYPMYJ -e -w -v somefile.bin
This will pre-erase flash, write somefile.bin
to the flash on the device, and then
perform a verification after writing is finished.
You can skip the -p
option by configuring environment variable
STM32LOADER_SERIAL_PORT
.
Similarly, -f
may be supplied through STM32LOADER_FAMILY
.
To read out firmware and store it in a file:
stm32loader -r -p /dev/cu.usbserial-A5XK3RJT -f F1 -l 0x10000 -a 0x08000000 dump.bin
- ST
AN2606
: STM32 microcontroller system memory boot mode - ST
AN3155
: USART protocol used in the STM32 bootloader - ST
AN4872
: BlueNRG-1 and BlueNRG-2 UART bootloader protocol
Original Version by Ivan A-R (tuxotronic.org). Contributions by Domen Puncer, James Snyder, Floris Lambrechts, Atokulus, sam-bristow, NINI1988, Omer Kilic, Szymon Szantula, rdaforno, Mikolaj Stawiski, Tyler Coy, Alex Klimaj, Ondrej Mikle, denniszollo, emilzay, michsens, blueskull, Mattia Maldini.
Inspiration for features from:
-
Configurable RTS/DTR and polarity, extended erase with pages: https://github.com/pazzarpj/stm32loader
-
Memory unprotect https://github.com/3drobotics/stm32loader
-
Correct checksum calculation for paged erase: jsnyder#4
-
ST BlueNRG chip support https://github.com/lchish/stm32loader
-
Wiznet W7500 chip / SweetPeas custom bootloader support https://github.com/Sweet-Peas/WiznetLoader
If you don't need the flexibility of a Python tool, you can take
a look at other similar tools in ALTERNATIVES.md
.
The below assumes you are connecting an STM32F10x. For other chips, the serial pins and/or the BOOT0 / BOOT1 values may differ.
Make the following connections:
- Serial adapter
GND
to MCUGND
. - Serial adapter power to MCU power or vice versa (either 3.3 or 5 Volt).
- Note if you're using 5 Volt signaling or 3V3 on the serial adapter.
- Serial
TX
to MCURX
(PA10
). - Serial
RX
to MCUTX
(PA9
). - Serial
DTR
to MCURESET
. - Serial
RTS
to MCUBOOT0
(orBOOT0
to 3.3V). - MCU
BOOT1
toGND
.
If either RTS
or DTR
are not available on your serial adapter, you'll have to
manually push buttons or work with jumpers.
When given a choice, set BOOT0
manually high and drive RESET
through the serial
adapter (it needs to toggle, whereas BOOT0
does not).
- Command-line argument for readout protection.
- Command-line argument for write protection/unprotection.
- STM8 devices (ST
UM0560
). - Paged flash erase for devices with page size <> 1 KiB.
- Other bootloader protocols (e.g. I2C, HEX -> implemented in
stm32flash
).
- Use f-strings.
- Use proper logging instead of print statements.
- Start using
IntEnum
for commands and replies.