Metadata-Version: 2.4
Name: stm32loader
Version: 1.0.0
Summary: Flash firmware to STM32 microcontrollers using Python.
Author: jsnyder, Floris Lambrechts
Author-email: Floris Lambrechts <florisla@gmail.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Requires-Dist: pyserial
Requires-Dist: progress
Requires-Dist: intelhex ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: nox>=2026.2.9 ; extra == 'dev'
Requires-Dist: nox-uv>=0.7.1 ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: pylint ; extra == 'dev'
Requires-Dist: bump-my-version ; extra == 'dev'
Requires-Dist: cogapp ; extra == 'dev'
Requires-Dist: intelhex ; extra == 'hex'
Requires-Python: >=3.9
Project-URL: Home, https://github.com/florisla/stm32loader
Project-URL: BugTracker, https://github.com/florisla/stm32loader/issues
Project-URL: SourceCode, https://github.com/florisla/stm32loader
Provides-Extra: dev
Provides-Extra: hex
Description-Content-Type: text/markdown

# STM32Loader

[![PyPI package](https://badge.fury.io/py/stm32loader.svg)](https://badge.fury.io/py/stm32loader)
[![Test](https://github.com/florisla/stm32loader/actions/workflows/test.yaml/badge.svg)](https://github.com/florisla/stm32loader/actions/workflows/test.yaml)
[![Lint](https://github.com/florisla/stm32loader/actions/workflows/lint.yaml/badge.svg)](https://github.com/florisla/stm32loader/actions/workflows/lint.yaml)
[![License](https://img.shields.io/pypi/l/stm32loader.svg)](https://pypi.org/project/stm32loader/)
[![Downloads](https://pepy.tech/badge/stm32loader)](https://pepy.tech/project/stm32loader)

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.9-3.15 and PyPy 3.10-3.11.


## Run using `uvx`

    uvx stm32loader


## Installation with pip

    pip install stm32loader

To also support loading `.hex` files:

    pip install stm32loader[hex]

To install the latest development version:

    pip install git+https://github.com/florisla/stm32loader.git


## Usage

<!-- [[[cog
import sys
from io import StringIO
import cog
from stm32loader.main import main

sys.stdout = StringIO()

main("--help", avoid_system_exit=True)

cog.out(f"```\n{sys.stdout.getvalue()}```")

sys.stdout.close()
sys.stdout = sys.__stdout__
]]] -->
```
usage: stm32loader [-h] [-e] [-E] [-u] [-x] [--write-unprotect]
                   [--write-protect] [-w] [-v] [-r] [-l LENGTH] -p PORT
                   [-b BAUD] [-a ADDRESS | -o OFFSET] [-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.

options:
  -h, --help            show this help message and exit
  -e, --erase           Erase the full flash memory or a specific region
                        (support --address and --length). Note: this is
                        required on previously written memory.
  -E, --auto-erase      Before writing, erase only the flash pages that the
                        written data covers.
  -u, --unprotect       Unprotect flash from readout.
  -x, --protect         Protect flash against readout.
  --write-unprotect     Disable write protection before flashing
  --write-protect       Enable write protection after flashing
  -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 of read or erase. For write and verify, use
                        only this many bytes of the file.
  -p, --port PORT       Serial port (default: $STM32LOADER_SERIAL_PORT).
  -b, --baud BAUD       Baudrate. (default: 115200)
  -a, --address ADDRESS
                        Target address for read or write. For erase, this is
                        used when you supply --length. Default: the start of
                        flash memory.
  -o, --offset OFFSET   Alternative to --address: an offset from the start of
                        flash memory.
  -g, --go-address ADDRESS
                        Start executing from address (0x08000000, usually).
  -f, --family FAMILY   Device family to read out device UID and flash size;
                        e.g F1 for STM32F1xx. Possible values: C0, F0, F1, F2,
                        F3, F4, F7, G0, G4, H5, H7, L0, L1, L4, L5, WBA, WB0,
                        WB, WL, U5, W, NRG, WIZ, GD32VW55X (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, --parity {even,none}
                        Parity: "even" for STM32, "none" for BlueNRG.
                        (default: even)
  --version             show program's version number and exit

examples:
  stm32loader --port COM7 --family F1
  stm32loader --erase --write --verify example/main.bin
```
<!-- [[[end]]] -->

## Command-line example

```
stm32loader --port /dev/tty.usbserial-ftCYPMYJ --erase --write --verify 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.

To erase only the flash pages that the new data will occupy, use `--auto-erase`
instead of `--erase`:

```
stm32loader --port /dev/tty.usbserial-ftCYPMYJ --auto-erase --write --verify somefile.bin
```

The erased range is rounded out to whole pages (sectors), following the device's
flash layout. This also works on devices with mixed sector sizes.

You can skip the `--port` option by configuring environment variable
`STM32LOADER_SERIAL_PORT`.
Similarly, `--family` may be supplied through `STM32LOADER_FAMILY`.

To read out firmware and store it in a file:

```
stm32loader --read --port /dev/cu.usbserial-A5XK3RJT --family F1 --length 0x10000 --address 0x08000000 dump.bin 
```


To erase the full device:

```
stm32loader --erase --port /dev/cu.usbserial-A5XK3RJT
```

Or erase only a specific region of the flash:

```
stm32loader --erase --address 0x08000000 --length 0x2000 --port /dev/cu.usbserial-A5XK3RJT
```



## Reference documents

* 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


## Acknowledgement

Original version by Ivan A-R (tuxotronic.org).
See `CONTRIBUTORS.md` for all contributors and sources of inspiration.


## Alternatives

If you don't need the flexibility of a Python tool, you can take
a look at other similar tools in `ALTERNATIVES.md`.


## Electrically

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 MCU `GND`.
- 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 MCU `RX` (`PA10`).
- Serial `RX` to MCU `TX` (`PA9`).
- Serial `DTR` to MCU `RESET`.
- Serial `RTS` to MCU `BOOT0` (or `BOOT0` to 3.3V).
- MCU `BOOT1` to `GND`.

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).


## Not currently supported

* Command-line argument for write protection for some devices (e.g. those with dual-bank flash).
* STM8 devices (ST `UM0560`).
* Other bootloader protocols (e.g. I2C, HEX -> implemented in `stm32flash`).
