Adding st-link to mbed-os-env docker image and update documentation

If you use a docker image to simplify the setup of the development toolchain there are several issues. There is a suggestion to use a Python venv but this is not fully isolating the toolchain. A docker image is preferred to speedup getting up and running with a working toolchain.

Docker image source: Package mbed-os-env · GitHub
Help page to use docker:

  1. No support for st-link

A lot of people use ST-Link programmers or clones and/or non mbed enabled devices. The project located at is the Linux answer for STLink programmers that are only supported officially in Windows. The docker container does not contains this driver natively and because the container is non persistent you have to install the tool each time you start the container. The suggestion is to add this driver in the container natively.

  1. Rights on files and folders:

If you use a command like mbed-tools deploy, the folders and files are checked out with root ownership. If you want to manipulate the project files outside the container you have a lot of right issues and ambigious git ownership. You need ‘sudo chown’ and add trusted git sources to solve it. There is maybe a way to execute the docker with the same rights as the caller.

  1. mbed-tools detect works with udev

To enable mbed-detect you need to map additional files in the docker session and if you use WSL2 in Windows you need to forward the USB device with a tool like The suggestion is to run docker with the following options:

run -it --privileged --mount=type=bind,source="$(pwd)",destination=/var/mbed -w /var/mbed  -v /dev/disk/by-id:/dev/disk/by-id -v /dev/serial/by-id:/dev/serial/by-id -v /run/udev:/run/udev:ro
  1. Docker deamon in WSL2 not enabled by default

You need to start the deamon in another window first with ‘sudo dockerd’

  1. Mismatch in pip packages when executing ‘mbed-tools detect’

solve error: cannot import name ‘collections_abc’ from ‘six.moves’ after mbed-tools detect

pip3 install click==7.1
pip3 install --upgrade six>=1.13.0

ImportError: cannot import name ‘soft_unicode’ from ‘markupsafe’

pip install markupsafe==2.0.1

Hi @sunnydaywest ,

have you considered using Mbed Studio or Keil Studio Cloud? They come with a lot of these tools already set up for you.

Federico - Keil Studio Cloud team

I’m convinced about the idea to keep the code and environment as less as party dependent. Doing everything in command line has the advantage that documentation is easier and everything can be scripted and reproduced in a predefined way. I like to use the classical toolchain (gcc/git/cmake/…) in Linux and keep a separation between code and tooling so that everybody can use his own SDK environment.

Minor correction, there actually is a Linux version of STM32CubeProgrammer, the first party program for interacting with ST-Link devices. Unfortunately, the ST license forbids distributing it except by directly downloading it from their site (so they can send you spam emails) so that’s probably why it’s not in the docker image.

However, in my experience, OpenOCD can directly program most STM32 devices just fine using an ST-Link, so you can get away with using that. The only exception is, sadly, STM32U5, where it seems to have random programming failures on the device I tested. For STM32U5, the only thing that programs it reliably for me are PyOCD and STM32CubeProgrammer, and only the STM32Cube GDB server is able to debug it.

You may want to check out Mbed CE, where I have configured Mbed to interact with a variety of programming applications via target config files like this. It enables true one-click building and flashing via running a command line ninja flash-YourTarget. It seems like U575 doesn’t currently have stlink-tools support, but it could be added just by adding a block like this to the config file. And feel free to give the Linux setup instructions a try – it should hopefully be a little more straightforward . We don’t currently have a docker image, but contributions would be appreciated!