st-flash

Flash firmware to STM32 microcontrollers

TLDR

Read 4096 bytes from the device starting from 0x8000000

$ st-flash read [firmware].bin [0x8000000] [4096]

Write firmware to device starting from 0x8000000

$ st-flash write [firmware].bin [0x8000000]

Erase firmware from device

$ st-flash erase

SYNOPSIS

st-flash [OPTIONS] [ARGS...]

Common Commands:
st-flash write

st-flash write
st-flash read

  st-flash erase
  st-flash reset
  st-flash info

PARAMETERS

write [address]
Writes a binary or Intel HEX file to the target's flash memory. For binary files, a hexadecimal address is required.

read

    Reads size bytes from the specified address on the target and saves them to a binary file.

erase
    Erases the entire flash memory of the connected STM32 microcontroller.

reset
    Resets the target microcontroller, typically causing it to start execution from the beginning of its firmware.

info
    Displays information about the connected ST-LINK debug probe and the target STM32 microcontroller.

--format
    Specifies the input file format (e.g., 'binary', 'ihex'). Usually auto-detected from file extension.

--flash=
    Manually specifies the flash size of the target in bytes. Useful if auto-detection fails.

--debug
    Enables verbose debug output, showing more details about the communication and operations.

--area=
    Specifies the memory area for read/write operations (e.g., 'flash', 'sram', 'option').

--connect-under-reset
    Holds the target microcontroller in reset during the connection process.

--serial
    Selects a specific ST-LINK by its serial number when multiple probes are connected.

--port
    Specifies the TCP/IP port number for network-connected ST-LINK probes (e.g., ST-LINK/V3E).

DESCRIPTION

st-flash is a command-line utility from the
stlink open-source project, designed for programming and interacting with STM32 microcontrollers. It provides functionalities to write firmware images (e.g., .bin, .hex files) to the device's flash memory, read memory contents, erase the chip, and verify written data. It communicates with the STM32 target through ST-LINK debug probes (V1, V2, V3) connected via USB. Supporting various flash memory types and sizes found in STM32 families, st-flash is an essential tool for embedded developers working with STM32 MCUs, especially in Linux environments.

CAVEATS

Permissions: st-flash often requires root privileges or proper
udev rules configured to access the ST-LINK USB device.
ST-LINK Versions: Compatibility and feature support can vary between ST-LINK V1, V2, and V3 probes.
Flash Protection: Operations like reading or writing protected memory regions may fail unless the protection is first disabled using specific commands or tools.
Device Support: While widely compatible, newer STM32 microcontroller series might require an updated version of the stlink package.

SUPPORTED FILE FORMATS

st-flash primarily supports raw binary (.bin) and Intel HEX (.hex) file formats. When writing an Intel HEX file, the address information is embedded within the file itself, so an explicit address argument is not needed.

MEMORY AREA TARGETING

Beyond the main flash memory, st-flash can interact with other memory areas on the STM32, such as SRAM for temporary data transfer or option bytes for configuration, by using the --area flag.

HISTORY

st-flash is a core component of the
stlink open-source project, which originated as a community-driven effort to provide cross-platform (Linux/macOS) support for ST-LINK debug probes. Before its existence, official ST-LINK tools were primarily Windows-based. Over time, it has evolved significantly, adding robust support for various ST-LINK versions and a wide array of STM32 microcontroller families, establishing itself as a de-facto standard command-line tool for embedded development on Linux systems.