Overview

stm8gal is an application for programming or reading out STM8 memory using the built-in ROM bootloader (BSL) via UART or SPI interface. It is compatible with Windows, MacOS X and Linux, including Raspbian. For a list of tested configurations see section Test Overview.

Note: stm8gal replaces the STM8_serial_flasher. The latter was renamed after a proposal by Philipp Krause

Tools with similar functionality via the UART interface are:

Flash Loader Demonstrator (UM0462) by STM (proprietary, Windows only)
stm8flasher by ottinger (open-source, Windows & Linux)
stm-serial-flasher by gamadril (open-source, Chrome)

For bug reports or feature requests please send me a note.

Have fun! Georg

License / Disclaimer

stm8gal and it's source code is distributed under the Apache License Version 2.0 (see License)
required flash write/erase RAM routines by Basil Hussain is distributed under the Apache License Version 2.0. Sources are available from https://github.com/basilhussain/stm8-bootloader-erase-write
optimized CRC32 calculation by Basil Hussain is distributed under the MIT License. Sources are available from https://github.com/basilhussain/stm8-crc

Building the Software

The majority of stm8gal is written in ISO C 99 with some OS-specific routines required e.g. for serial communication. However the required serial libs are part of all standard compiler suites and shouldn't pose a compatibility issue. In case of portability issues please contact the author for support.

Non ANSI-C extensions:

wiringPi library, which is Raspberry Pi specific, and allows automatic reset of the STM8 via GPIO header pin. Is pre-installed for Raspbian Stretch and above. To activate remove comment in Makefile
spidev kernel library for interfacing to the SPI. To activate remove comment in Makefile. The Raspberry Pi and other "embedded PCs" provide direct SPI pin access, so no extra hardware is required. For "normal" PCs, an extra hardware and likely an adaptation of the SPI send/receive routines is required (volunteers?)

A code reference can be generated by running Doxygen with input file 'Doxyfile'. Then open file './doxygen/html/index.html' with a webbrowser. For other output formats, e.g. PDF, modify 'Doxyfile' accordingly.

Linux

Use one of the following options to build stm8gal:

Open a terminal and change to the project directory. Then type make
Alternatively double-click file "_compile.sh". May require execute permissions via chmod u+x *.sh
in Geany open project "stm8gal.geany"and make (Shift+F9)
for SPI communication via supported SPI adapter (untested!):
- requires installed spidev and user access to SPI hardware
- specify CFLAGS += -DUSE\_SPIDEV and SOURCES += spi\_spidev\_comm.c in file "Makefile"

Note: Under Linux access to serial ports may be prohibited. To grant access rights see here

Raspberry Pi

Same as Linux above, but with additional option:

for reset STM8 via GPIO header:
- specify -DUSE\_WIRING and -lwiringPi in file "Makefile"
- if required install wiringPi. To check type gpio readall in commandline
- enable GPIO access via raspi-config
- add user to group gpio (sudo usermod -a -G gpio $(whoami))
for UART communication via GPIO header:
- enable serial interface access via raspi-config
- add user to group dialout (sudo usermod -a -G dialout $(whoami))
for SPI communication via GPIO header:
- install spidev if required (is pre-installed for Raspbian Stretch and above)
- specify CFLAGS += -DUSE\_SPIDEV and SOURCES += spi\_spidev\_comm.c in file "Makefile"
- enable SPI access via raspi-config
- add user to group spi (sudo usermod -a -G spi $(whoami))

Windows

Use one of the following options to build stm8gal:

in DevC++ open project "stm8gal.dev" and build all (F12)
in Microsoft Visual C++ open project "MSVC" and build all
in File Explorer double-click file "_compile.bat". Requires gcc and mingw32-make to be installed and in PATH. May require some modifications to the batchfile and file Makefile

Note: Windows commandline (cmd.exe) requires a path on a mounted drive, i.e. path to the tool has to start with 'C:', 'D:' or similar. So either copy the tool to a mounted drive or use 'connect network drive' to assign a drive letter. This limitation does not apply to POSIX operating systems

MacOSX

Same as for Linux above. However, for double-click rename files ".sh" to ".command"

Note: Due to lack of a Macintosh, compatibility with MacOSX is no longer tested. Therefore, please provide feedback if you have experience with stm8gal on a Mac. Also a Mac binary for distribution is highly appreciated. Thanks!

Using the Software

stm8gal is a commandline tool without graphical interface (volunteers...?). The application is called from the command line or via shell script using the below syntax.

usage: stm8gal with following options/commands:

-h/-help                        print this help
-v/-verbose [level]             set verbosity level 0..3 (default: 2)
-B/-background                  skip prompts and colors for background operation (default: foreground)
-q/-exit-prompt                 prompt for <return> prior to exit (default: no prompt)
-R/-reset [rst]                 reset for STM8: 0=skip, 1=manual, 2=DTR line (RS232), 3=send 'Re5eT!' @ 115.2kBaud, 4=Arduino pin pin 8, 5=Raspi pin 12, 6=RTS line (RS232) (default: manual)
-i/-interface [line]            communication interface: 0=UART, 1=SPI via Arduino, 2=SPI via spidev (default: UART)
-u/-uart-mode [mode]            UART mode: 0=duplex, 1=1-wire, 2=2-wire reply, other=auto-detect (default: auto-detect)
-p/-port [name]                 communication port (default: list available ports)
-b/-baudrate [speed]            communication baudrate in Baud (default: 115200)
-V/-verify [method]             verify flash content after upload: 0=skip, 1=CRC32 checksum, 2=read-back (default: read-back)
-j/-jump-addr [address]         jump to address (as dec or hex) before exit of stm8gal, or -1 for skip (default: flash)
-w/-write-file [file [addr]]    upload file from PC to uController. For binary file (*.bin) with address offset (as dec or hex)
-W/-write-byte [addr value]     change value at given address (both as dec or hex)
-r/-read [start stop output]    read memory range (as dec or hex) and save to file or print (output=console)
-e/-erase-sector [addr]         erase flash sector containing given address (as dec or hex). Use carefully!
-E/-erase-full                  mass erase complete flash. Use carefully!

Notes:

reset via RasPi GPIO (-R 5) is only available on a Raspberry Pi and if stm8gal was built with wiringPi support (see Building the Software)
interface spidev (-i 2) is only available if stm8gal was built with spidev support (see Building the Software)
SPI via Arduino (-i 1) and reset via Arduino GPIO (-R 4) requires an additional Arduino programmed as SPI bridge
to avoid address conflicts with Boot-ROM or CRC32-verify RAM routines, optional user RAM code should start at address 0x400

Supported File Formats

Supported import formats (option '-w'):

Motorola S19 (*.s19), for a description see here
Intel Hex (*.hex, *.ihx), for a description see here
ASCII table (*.txt) consisting of lines with 'addr value' (dec or hex). Lines starting with '#' are ignored. For example see here
Binary (*.bin) with an additional starting address

Supported export formats (option '-r'):

print to stdout ('console')
Motorola S19 (*.s19)
Intel Hex (*.hex, *.ihx)
ASCII table (*.txt) with 'hexAddr hexValue'
Binary (*.bin) without starting address

Data is uploaded and exported in the specified order, i.e. later uploads may overwrite previous uploads. Also exports only contain the previous uploads, i.e. intermediate exports only contain the memory content up to that point in time.

Examples

Program custom muBoard via USB with manual reset

supply the muBoard via USB from the PC, here a RasPi. This also establishes the USB<->UART connection via an on-board FT232 adapter
note name of serial port, e.g. COM10 (Win) or /dev/ttyUSB0 (Linux). Hint: launching stm8gal without argument lists the available ports

software usage:

-stm8gal -p /dev/ttyUSB0 -w main.ihx (Linux)

-stm8gal -p COM10 -w main.ihx (Windows)

Program STM8S Discovery Board via UART pins from Raspberry Pi with reset via GPIO

connect the STM8S Discovery Board to the Raspberry Pi in the same sequence as shown below. Notes:
- configure STM8S Discovery for 3.3V supply to avoid damage to the Raspberry Pi 3.3V GPIOs
- for direct GPIO and UART access add user to groups 'gpio' and 'dialout'
- in addition, reset via header pin requires wiringPi installed with user access
- for pinning of the Raspberry Pi GPIO header type "gpio readall" on the command line, or see e.g. here

software usage:

-stm8gal -p /dev/ttyAMA0 -w main.ihx -R 5 (RasPi 1+2)

-stm8gal -p /dev/serial0 -w main.ihx -R 5 (RasPi 3)

Program STM8S Discovery Board via SPI pins from Raspberry Pi using spidev with reset via GPIO

connect the STM8S Discovery Board to the Raspberry Pi in the same sequence as shown below. Notes:
- configure STM8S Discovery for 3.3V supply to avoid damage to the Raspberry Pi 3.3V GPIOs
- for direct GPIO and SPI access add user to groups 'gpio' and 'spi'
- in addition, reset via header pin requires wiringPi installed with user access
- for pinning of the Raspberry Pi GPIO header type "gpio readall" on the command line, or see e.g. here

software usage:

-stm8gal -i 2 -p /dev/spidev0.0 -w main.ihx -R 5

Program STM8S Discovery Board via Arduino SPI bridge and reset via GPIO

Ensure voltage level compatibility between Arduino and STM8. Note that ATMega-based (8-bit) Arduinos generally have 5V GPIOs, while ARM-based (32-bit) boards only support 3.3V. Exposing a 3.3V device to 5V signals may damage the 3.3V device.
Supply the Arduino to the PC via USB. This also establishes an USB connection to the on-board microcontroller
Program the Arduino to act an an USB<->SPI bridge.
Note name of serial port, e.g. COM10 (Win) or /dev/ttyUSB0 (Linux). Hint: launching stm8gal without argument lists the available ports
connect the STM8S Discovery Board to the Arduino in the same sequence as shown below.

software usage:

-stm8gal -i 1 -p /dev/ttyUSB0 -w main.ihx -R 4

Memory dump muBoard via USB with manual reset

supply the muBoard via USB from the PC, here a RasPi. This also establishes the USB<->UART connection via an on-board FT232 adapter
note name of serial port, e.g. COM10 (Win) or /dev/ttyUSB0 (Linux). Hint: launching stm8gal without argument lists the available ports

software usage:

-stm8gal -p /dev/ttyUSB0 -r 0x8000 0x8FFF dump.s19 (Linux, Motorola S19 format)

-stm8gal -p /dev/ttyUSB0 -r 0x8000 0x8FFF dump.txt (Linux, table format)

-stm8gal -p COM10 -r 0x8000 0x8FFF dump.s19 (Windows, Motorola S19 format)

Notes

bootloader programming via UART, SPI or CAN is supported by most STM8 devices. However, not all devices support each interface. A full description of the bootloaders can be found in UM0560, including an overview of STM8 devices with respective bootloader mode. For stm8gal >=v1.2.0 the UART mode can optionally be auto-detected:

To program via stm8gal, communication between PC and STM8 must be possible. On the STM8 side this is via UART or SPI, on the PC side this is generally via USB or RS232.
- On some boards, e.g. the muBoard, an USB<->UART bridge is already present. In this case, no additional hardware is required
- However, e.g. the popular STM8S Discovery and STM8L Discovery boards connect to a standard PC via SWIM (=debug) interface. In this case a separate adapter is required to connect to the respective STM8 UART or SPI pins, e.g. UM232R. When connecting, make sure that the voltage levels of STM8 and the adapter are compatible. Exposing a 3.3V device to 5V signals may damage the 3.3V device.
- Exception is the Raspberry Pi or similar “embedded PCs“ with direct access to UART and SPI pins via the GPIO header. In this case make sure that the voltage levels of STM8 and embedded PC are compatible, e.g. for RasPi with 3.3V pins also supply the STM8 with Vdd=3.3V. As noted above, never expose a 3.3V device to 5V signals.
- Alternatively an Arduino can be used to act as a USB<->SPI bridge using a dedicated "gateway software". For the Arduino project and a technical documentation see the Arduino SPI_bridge repository. Again, note compatible voltage levels of Arduino and STM8.
Prior to uploading code via stm8gal the STM8 ROM bootloader needs to be activated via option bytes. For details see the respective STM8 device datasheet. If required, change the option bytes via SWIM debug interface using
- ST Visual Programmer application by STM (proprietary, Windows only)
- stm8flash by Valentin Dudouyt to upload and run the STM8 program in subfolder './BSL_activate'
- Notes
  - Virgin devices (i.e. flash completely erased) automatically have the bootloader enabled
The BSL can be entered only within 1s after reset or power-on. Exception are virgin devices, which remain in bootloader mode indefinitely.
The UART "reply" mode (see above) supports single-wire interfaces like LIN or ISO9141. It requires a "Rx echo" for each sent byte. Using the reply mode with dual wires therefore requires stm8gal to echo each received byte individually, which results in extremely low reading speed due to USB latency.
SPI communication via spidev or Arduino SPI bridge works reliably only up to 250kBaud in my test setup (see above)
The STM32 uses a very similar bootloader protocol, so adapting the flasher tool for STM32 should be straightforward. However, I have no board available, but please feel free to go ahead...

Test Overview

stm8gal has recently been tested only for the below STM8 devices and operating systems. Theoretically it should work for all STM8 devices with bootloader, especially since STM8AF, STLUX, STNRG and STM8SPLNB seem to be test variants of the STM8S, and STM8AL and STM8T seem to be test variants of the STM8L. However, this has not been tested, so if you use stm8gal in another setup, any feedback is highly appreciated!

green: test passed; yellow: not yet tested

Known Bugs

currently no known bugs

If you are aware of bugs, please drop me a note or start an issue on the project homepage.

Revision History

v1.5.0 (2021-01-23)

replaced write/erase RAM routines by STM with OSS routines (see gicking#4)
removed STM8S 32kB v1.4 and 128kB v2.4. According to STM support were never released and development is stopped
removed STM8S 256kB v1.0. According to STM support variant was never released and development is stopped
fixed bug in v1.4.3 which prevented flash write/erase after CRC32-verify

v1.4.3 (2021-01-09)

fixed bug in SPI read-back after write
fixed bug in CRC32-verify (see gicking#20)

v1.4.2 (2020-12-26)

support re-synchronization w/o STM8 reset
add option verify via CRC32 checksum (see gicking#20)
- add parameter to verify option (-V/-verify). Is required due to new CRC32 check

v1.4.1 (2020-12-13)

minor bugfix

v1.4.0 (2020-04-09)

improved S19 export for >16bit addresses
added IHX export option

v1.3.0 (2019-01-02)

add multiple up- and downloads in single run
added option to print memory map and sector erase
fixed S19 export bugs for >16bit addresses and small images
fixed IHX import bug for record type 5
fixed mass erase timeout bug
fixed bug for files with "holes" -> only write specified data
harmonized files with https://github.com/gicking/hexfile_merger

v1.2.0 (2018-12-02)

add automatic UART mode detection (duplex, 1-wire, 2-wire reply). See UART mode issue
changed default UART baudrate to 115.2kBaud for robustness

v1.1.8 (2018-10-07)

add option for background operation for IDE usage. Skip prompts and setting console color & title
add different verbosity levels (0..2) for IDE usage

v1.1.7 (2018-01-04)

added option to skip reset (-R 0) via commandline
reset STM8 before opening port to avoid flushing issue under Linux

v1.1.6 (2017-12-22)

fixed bug in SPI using Arduino bridge

v1.1.5 (2017-12-20)

added SPI support via Arduino bridge
replace manual reset parameter "-Q" with "-R 0"
fixed bug in "2-wire reply mode" (wrong echo)

v1.1.4 (2017-12-14)

added SPI support via spidev (currently only POSIX)
add user-space access to RasPi GPIOs via wiringPi for automatic reset. Use header numbering scheme (="physical")
removed verbose commandline option (-V). Always print verbose
added listing of /dev/serial0 (new in Pi3, see https://raspberrypi.stackexchange.com/questions/45570/how-do-i-make-serial-work-on-the-raspberry-pi3)

v1.1.3 (2017-08-29)

renamed from "STM8_serial_flasher" to "stm8gal", following a proposal by Philipp Krause (see gicking/STM8_serial_flasher#10)

v1.1.2 (2016-05-25)

add optional flash mass erase prior to upload

v1.1.1 (2016-02-03):

add support for STM8L family (skip RAM code upload)
add memory dump to file

v1.1.0 (2015-06-22):

add support for STM8 bootloader “reply mode“
add optional reset of STM8 via DTR (RS232/USB) or GPIO18 (Raspberry)

v1.0.0 (2014-12-21):

initial release by Georg Icking-Konert under the Apache License 2.0

rhaas80 / stm8gal