This post is also available in: cs
Development tools are probably the biggest weakness of the whole STM8 ecosystem. The
manufacturer provides the STVD development environment
(guide here (in Czech)),
which is adequate, but old and no longer developed. Sometimes it is hard to get it
running on a particular PC. The Cosmic compiler does work, but the constant
license checking is really annoying; … and its error messages didn’t seem very
clear to me either.
And I haven’t even mentioned the main point: It doesn’t run on Linux!

That is why I created a toolchain that relies on OpenSource tools. If you want to use this toolchain, you need to install these tools:
- Development environment
- Compiler
- Programmer/Flasher — software to upload the program to the chip
- Debugger
When I was putting all this together, this page helped me a lot, so you can take a look: https://github.com/hbend1li/stm8_started.
Pre-prepared Installation¶
I have prepared a teaching image of Devuan Linux, where everything is already set up and installed. So you don’t need to install everything manually, just:
- install VirtualBox
- install the Extension Pack into VirtualBox
- download the prepared image: Devuan-X+MIT.ova and import it.
A few notes about the image:
- updated on November 2, 2026
- size 5722 MB
- built with VirtualBox 7.2.22
- release: Devuan 6 Excalibur (based on Debian 13 Trixie)
- desktop: Openbox + xfce4-panel
- https://mamut.spseol.cz/nozka/public/virtual-img-ova/Devuan-X+MIT.ova
- How to use VirtualBox and the prepared image (in Czech):
- MIT-Virtualbox

… but still read the text below so you know how to use it.
Pre-built Packages¶
Hint
If you have a Linux distribution based on Debian (Ubuntu, Mint, Devuan, …), you don’t need to compile anything complicated. Just use our repository and install the ready-made (precompiled) packages.
Prepared repository:
https://mamut.spseol.cz/debian/
Just enter:
1 2 3 4 5 6 | |
… and everything you need is installed.
If you use another Linux distribution or a different OS, or you simply want more control over what you install, see the separate article: Installing/Compiling the tools for the STM8 toolchain.
What you actually installed with the prepared packages:
sdcc,sdcc-libraries— compiler (installation details)openocd— flashing and debugging (installation details)stm8flash— flashing (installation details)stm8-binutils-gdb— debuggerstm8-gdb(installation details)cgdb— frontend for GDB (installation)ccls— LSP server for the editor (optional) (installation details)stm8newproject— new project automationglabproject— interactive creation of GitLab projects from the CLImake,git,fzf,python3-serial— helper tools for the toolchain
Toolchain¶
The core of the whole toolchain is a Makefile,
complemented by several helper scripts (the .make directory) and a starting
source code tree of the project:
https://gitlab.com/spseol/mit-no/STM8S-toolchain
The toolchain can be used on Linux, macOS and Windows. But it is developed and primarily intended for Linux, and that is where it works best.
It is very simple to use: download, unpack or clone the toolchain repository.
This gives you a folder with a new project, and inside it you just run make
commands (see the overview in Usage).
Projects and SPL Library¶
The directory structure of individual projects looks like this:
MIT
├── Project-1
│ ├── inc
│ ├── lib
│ └── src
├── Project-blikblik
│ ├── inc
│ ├── lib
│ └── src
├── SPL
│ ├── inc
│ └── src
└── SPLSPL
├── inc
└── src
Make a directory where all your projects will be — in the example above it is
MIT. In the same directory there will also be directories named SPL and SPLSPL. In the SPL directories is the Standard Peripheral Library from
ST. This library has quite a strange license and therefore I
can’t just give it to you. You should
find it
and download it. Then you also
need to apply a patch,
which converts the library so it can be used with our SDCC compiler.
The whole process is quite a lot of work, … but try typing make spl — maybe it will sort itself out.
Creating a new project
Creating a project can be automated with a set of scripts
available in the repository
STM8S new project automation.
It is the content of the stm8newproject package mentioned above. If you install it,
just run the command stm8newproject or stm8newproject.gui.
Further automation is available in the repository GitLab project interactive CLI, which can make creating a new project on GitLab much easier.
Usage¶
Everything is controlled with the make program. In the project directory you just
run the following commands:
make spl— downloads and prepares librariesmake— compiles the projectmake flash— uploads the program to the chip (whenmake debugis running, the program is only compiled and the debugger uploads it to the chip)make clean— deletes everything that was compiledmake rebuild— deletes everything and compiles againmake debug— debugging with one command: compiles, uploads, stops atmain()and opens cgdb
The toolchain can do more… just keep reading or see the project README.
I should also mention that my colleague Wykys has also created a toolchain, which is much simpler and therefore easier to read:
Development Environment¶
I use Vim or rather Neovim. Not everyone likes this environment though, so as an editor and development environment I recommend VScodium/VScode.
Installation is described here.
For features like code completion, go-to-definition, or inline error highlighting
you need an
LSP server.
I recommend using ccls instead of the
C/C++
extension from Microsoft. The C/C++ extension does not always behave correctly
with embedded platforms, while ccls works reliably, IMHO.
ccls is optional. When compiling, the toolchain creates the file
compile_commands.json itself, from which ccls learns the compiler flags and the
paths to header files, so you don’t have to configure anything by hand. On Debian and
derived distributions you install it from the ccls package (it is in the command in
Pre-built Packages); for other systems the installation
is described here.
Then install the ccls extension in VSCode/Codium — in VSCode from the
Marketplace,
in VSCodium from Open VSX.
Alternative: clangd
An alternative to ccls is the LSP server clangd,
which also works quite well. It uses the same compile_commands.json file.
The clangd
extension is on the Marketplace for VSCode and on
Open VSX
for VSCodium. On Debian you install it from the clangd package.
Compilation — SDCC¶
Watch out for SDCC version
SDCC version 4.5.0 is unusable for the STM8 platform. See the details in SDCC installation.
SDCC - Small Device C Compiler is a compiler
for various, more or less known 8-bit architectures. For STM8 it has one
major disadvantage: it cannot remove unused (dead) code. What does this mean? Well…
if you write everything yourself, it practically means nothing. But if you
use some library (such as SPL), you will start to be bothered a lot, because
the resulting machine code contains many functions that you compiled only because
they were part of the library — not because you wanted to use them. These functions
are not called anywhere and so the
linker should remove them. And that
is exactly what doesn’t happen :-(.
As a result, a program that could be about 2-3 kB ends up being 30 kB.
Fortunately there is one hack, which works
roughly like this: The SPL library is split into small files (one function per file) and each is
compiled as a separate module. These modules are made into a library, which the SDCC
linker can already work with correctly. That is why the SPL library appears twice in the
directory structure.
SPLSPL stands for SPLit SPL and
is used exactly for this.
There are other solutions, SDCC-gas and sdccrm, but they are historical:
the projects are unmaintained and SPLSPL is more than enough today. For the
curious, you can find them in a separate article
Dead code removal in SDCC.
SDCC installation for Linux, macOS and Windows is described here.
Flashing¶
The program is uploaded to the chip through an ST-LINK programmer. The toolchain can do it with three tools, and which one is used depends on the command and the operating system:
make flash— OpenOCD on Linux and macOS, STVP on Windows. This is the default choice, which works on all systems.make stm8flash— always stm8flash.make debug— the debugger uploads the program itself, so you don’t need to flash manually.
STVP¶
STVP is software from
the chip manufacturer ST for Windows. It allows access to all parts of microcontroller
memory. It has a graphical version and a command-line version. It is the command-line
version (STVP_CmdLine.exe) that our
toolchain relies on; if you use
it on Windows, the make flash command uses it to flash the chip. You just need to have
STVP installed.
OpenOCD¶
Open On-Chip Debugger is a tool for debugging and stepping through
a program directly on the chip. openocd can also upload a program to the device memory.
It works on Linux, macOS and Windows.
Installation and the script for the flashing itself (which is part of the toolchain) are described here.
stm8flash¶
Another option is the program stm8flash. We have it in our
repository.
https://github.com/vdudouyt/stm8flash
stm8flash is a small command-line tool that communicates with the chip through the
SWIM interface of the ST-LINK programmer. For a long time it was the only tool on Linux that
could do this; OpenOCD has been able to flash only since 2018, and stm8flash still
supports more chips and handles memory better (it can read, verify and write
it, including the EEPROM). In the toolchain you use it with the make stm8flash
command, which uploads the compiled program (out.ihx). The make stm8flash-unlock
command writes values into the option bytes that turn off read-out protection (ROP) —
handy when the chip is “locked” and cannot be flashed.
Installation for other systems and building from source code are described here.
Debugging¶
Communication with the chip: OpenOCD¶
openocd — Open On-Chip Debugger — is the tool we use to
communicate with the chip and start/stop/step through the program. This tool handles communication between the debugger and the chip via the ST-LINK debug interface. Installation is
described here.
OpenOCD is run on its own like this:
1 | |
(The example is for the STM8S103 chip; for other chips the target/*.cfg file changes —
stm8s003.cfg, stm8s105.cfg, in general stm8s.cfg.)
Don’t worry, you don’t have to type this every time. It is written in the Makefile, which
picks the right target according to the chip, so just call:
1 | |
Running OpenOCD on its own is useful only for connecting GDB by hand or for graphical tools such as VSCode, which connect to port 3333.
For debugging you don’t need to start OpenOCD by hand: the make debug command starts it
itself and stops it again when debugging ends (details in the article
A small STM8-GDB course).
1 | |
STM8-GDB¶
GDB (GNU Debugger) is the standard tool for finding bugs in software. It allows you to stop the program, step through it, and look at variables while it runs — or even change them. For the STM8 platform you need the modified STM8-GDB from GNU binutils. Installation is described here.
GDB is a text tool. My recommendation: don’t be put off and use GDB directly, or its lightweight wrapper cgdb. Both tools are described in detail in a separate article (in Czech) A small STM8-GDB course.
In our toolchain, debugging is started with one command:
1 | |
This command compiles the project, starts OpenOCD, uploads the program to the chip, stops at
the beginning of main() and opens cgdb. If you modify the program while debugging, just call make flash in another terminal and the debugger uploads the new program to the chip itself.
A small STM8-GDB course¶
You can find more detailed information in a separate article (in Czech): A small STM8-GDB course.
All other graphical tools use GDB as a backend. Their advantage and disadvantage is the GUI, which may be more attractive to many people, but on the other hand you may lose some features such as conditional breakpoints.
Debugging in VS Code and VSCodium¶
Debugging with make debug — breakpoints, stepping, variables and peripheral
registers, see A small STM8-GDB course — can also be controlled by clicking in the VSCodium
or VS Code editor (installation of the editor is described
here). This is done by the
STM8 Toolchain Debugger extension. Under the hood it runs the same stm8-gdb and
the same OpenOCD as make debug, so everything from A small STM8-GDB course applies here
too. The debug console even accepts GDB commands, including sfr and p TIM4->CR1.
The extension is tested on Linux. Everything except STM8 binutils-gdb is tested on
macOS as well, so if you manage to get stm8-gdb running there, it will work too. On
macOS you only need to install all the dependencies.
Windows is neither supported nor tested.
Only one debugger at a time
The ST-LINK can be held by only one program, so you cannot have make debug
(cgdb) and debugging in the editor running at the same time.
Installing the extension¶
For debugging you need the same as for make debug: make, python3, git, SDCC,
OpenOCD and stm8-gdb version 15 or newer with Python and DAP support
(see Installation) and an ST-LINK. Node.js and npm are not needed.
stm8-gdb is not part of the extension, you must have it installed beforehand. It is
a special build of GDB for STM8 (STM8 binutils-gdb),
the procedure is in the article
Installing/Compiling the tools for the STM8 toolchain.
The extension is called spseol.stm8-toolchain. In the editor you will find it in the
Extensions panel by searching for STM8 Toolchain:
- in VSCodium it comes from Open VSX,
- in VS Code from the Visual Studio Marketplace.
The extension can also be installed from a project created from our toolchain, without a marketplace:
1 | |
The command packages the extension and installs it into all code and codium editors
it finds (make vscode IDES=codium selects just one). Restart the editor after installation.
New project¶
Open the command palette (Ctrl+Shift+P) and choose STM8: New Project…. In an empty
editor window where you do not have any folder open yet, it is enough to click the
New STM8 Project button in the Explorer panel. The extension:
- asks for the folder for projects (setting
stm8.projectsFolder) and for the project name. All projects should live in one folder, because they share the SPL library in../SPLSPL, - clones the toolchain from GitLab and prepares a git repository with a single commit
(the original history of the toolchain stays in the
upstreambranch), - opens the project. The first build downloads the SPL library, which requires internet.
You choose the target chip by clicking in the bottom status bar (it changes
DEVICE_FLASH in the Makefile).
Older project¶
You update a project created earlier with the STM8: Update Toolchain command. The
extension offers it by itself when you open a project with an older toolchain. The same
can be done from the terminal with make upgrade, but that target exists only in
projects that have already gone through the new toolchain once.
The update replaces .make/ and .vscode/launch.json, adds missing lines to
.gitignore and merges your Makefile with the new version: your settings for the
chip, frequency and compiler path stay. If your changes collide with the new ones, it
leaves conflict markers (<<<<<<<) in the Makefile and the project will not build
until you fix them. Source files (src/, inc/) and the README are not changed.
Nothing is committed, so you can check the result with git diff. Changes in .make/,
Makefile and launch.json must be committed before the update, otherwise the
extension refuses it.
Debugging¶
Press F5 (the STM8 debug configuration). Just like make debug, the extension:
- builds the project with debug information (compiler errors show up in the Problems panel),
- starts OpenOCD and flashes the program into the chip,
- stops the program at the beginning of
main().
Then you debug as in other editors: you set a breakpoint by clicking next to the line
number, step with the buttons on the toolbar (or F10, F11), and see variables in the
side panel, in Watch, and when hovering the mouse over an expression in the code.
The Run and Debug side panel gains an STM8 Peripherals view. It is
sfr as a tree: the peripherals of your chip, their registers and
bits. Values are read at every stop and whatever changed since the previous stop is
highlighted in yellow. By ticking a single-bit field you write the bit; with the pencil
on a register or a multi-bit field you enter a new value (decimal, 0x… or 0b…).
Registers whose reading clears flags (UART1->DR, SPI->DR, …) behave the same as in
the sfr command: the tree does not read them by itself. You read
them with the Read icon. Hovering the mouse over an expression in the code does not
read them either.
The bottom status bar has the Build, Flash, Debug buttons and the chip selector.
When something does not work¶
| message | what to do |
|---|---|
Old toolchain – run STM8: Update Toolchain … |
the project is old, run STM8: Update Toolchain |
stm8-gdb 15 or newer is required / not found in PATH |
install stm8-gdb following the installation article |
No ST-Link found on USB |
connect the board, on Linux check the udev rules |
make debug is running (PID …) |
close cgdb, only one debugger can run at a time |
ST-Link may be in use by another OpenOCD … |
quit the other OpenOCD (make openocd, another editor window) |
… timed out after 30 s |
the chip does not respond, check the cable and power; the OpenOCD log is in build-*-elf/openocd.log |
You will find the GDB output in the Output panel in the STM8 debug channel.
Details about the extension, its settings and limitations are in its README.
Other VScode/Codium extensions¶
You can play around and try various extensions for VSCode/Codium. You will certainly need to edit the .vscode/launch.json file in the project and correctly link it with stm8-gdb.
Here is a list of a few extensions that might work. There are guides on the internet suggesting
they do work. I personally never managed to get it running to my full satisfaction and I stick
with my favourite cgdb. If you succeed, please let me know.
Here is also a draft of my .vscode/launch.json for Native Debug.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | |