STM32 DevContainer

This repo aims to amke development with st easier. You can develop with VSCode in a cmake project using the CubeMX generator features for the HAL firmware. Debugging is possible via OpenOCD.

Introduction

You are supposed to use VSCode with this repository. The clue is to have everything inside a DevContainer. Therefore no installation of anything but docker and git is required and everybody has the same development toolchain. The following tools come preinstalled in the image:

• CubeMX
• OpenOCD

For debugging you can use OpenOCD. The nedded config files are given aswell.

You dont need a MyST account to generate the firmware code for the following MCU families:

• F3
• F4

It is planned to add F0 and H7.

Prepare

Git

SSH Keys

Setup your SSH key to have an easy life with git in the future. A short description is given below. You can view detailed information on the web to see how to use Git with SSH.

1. Generate the key by replacing the <Write a tag here> with something unique of your choice (e.g. mail address):

ssh-keygen -t ed25519 -C "<Write a tag here>"

• The program asks you where you want to save the file. Just hit Enter.

• The program asks you for a password. Just hit Enter and leave it empty. This makes git inside VS Code more easy.

• The program asks for password verification. Hit Enter Again.

2. Copy the public key to your account inside Git. The following command prints it out in the console.

cat ~/.ssh/id_ed25519.pub

Copy it with your mouse and Ctrl + C or Ctrl + Shift + C.

3. Paste the public key into your SSH key in your Git account. For this click on your icon on the top right corner -> Preferences -> SSH Kes (on the left hand side). Choose a name and create the key.

4. Add this key to your ssh manager using the following command:

ssh-add <directory to private SSH key>

Now you have set up your ssh key!

Docker

Docker

1. via apt repository. NOT via snap, this can lead to cruel errors during usage.

2. Make sure that you can use docker as sudo.

   1. Add a docker group

      sudo groupadd docker
      

   2. Add you user to this group

      sudo usermod -aG docker $USER
      

   3. Log out and log back in or run

      newgrp docker
      

   4. Test it with

      docker run hello-world
      

3. Log in to a registry using docker

   docker login git.fasttube.de
   

4. A prompt appears.

   • Enter your username.

   • Enter your password.

   NOTE : The password is stored on your local computer encrypted in a json file using base64 encoding. This isn't inherently safe. The integration of a credential helper is recommended. For more information look into the docs.

Installation

git clone --recurse-submodules ssh://git@git.fasttube.de:313/FaSTTUBe/stm32_devcontainer.git

Usage

Start the DevContainer

1. Install the Dev Container Extension in VS Code.

2. Navigate to the cloned repository in the terminal

   cd /path/to/ft_as
   

3. Open VS Code with:

   code .
   

4. On the bottom left corner a popup should appear. Hit: Reopen in Container. If it does not appear hit Ctrl + Shift + P and type in the search bar: Reopen in Container

   NOTE : This can also be used to rebuild the container by searching for Rebuild and Reopen in Container

   Congratulations. Now you are developing inside the Container using the VS Code as user interface. Everything you do inside this session will be inside of the running container.

Test the Setup

You might need to enable your host system to be able to see UIs.

xhost +

To verify if everything worked, try to open the STM32CubeMX. Execute the following from inside the container:

stm32cubemx

If it does not work you may have to play around with the DISPLAY environment variable. Check the following section.

Display

If you run into this issue, you can try this solution from https://stackoverflow.com/a/44434831

echo $DISPLAY
OUTPUT:
:1

xauth list
OUTPUT:
<device>:1  MIT-MAGIC-COOKIE-1  <secret>

export DISPLAY=:1

xhost +local:docker
OUTPUT:
non-network local connections being added to access control list

Then return to Test the Setup section and check if everything is working correctly

Add a new Repository

0. Firstly create a new repo in gitea. Then add it as submodule from the projects folder with

   git submodule add <ssh link to your new repo>
   

1. Open STM32CubeMX with the terminal command stm32cubemx

2. Choose a MCU family. If it is one of the supporterd ones you dont even have to login here.

3. Configure the Project as CMake project and set the directory to the repo you just created.

4. Hit Generate Code and see how the repo structure appears.

Now you can work with the project like a standard CMake project. Create a build folder and hit cmake .. && make e.g.

NOTE : The CMakeLists.txt file will not be regenerated when the code is regenerated if something changes in the ioc file. So feel free to link your own libraries here.

Compile main.c always with c++ compiler

Configure main.c via CMake for C++

If you want to use C++ it can be annoying, that the main.c is compiled with the C compiler and regenerated as main.c if something changed in the ioc file. To enforce a compilation with the C++ compiler you just have to add the following line to your CMakeLists.txt project

SET_SOURCE_FILES_PROPERTIES(Core/Src/main.c PROPERTIES LANGUAGE CXX)

Debug

For debugging you have to configure the launch.json.

• Create your own configuration for your project based on the existing ones.
• Set the environment variable (like in the existing launchfiles)
• Add it to the docker-compose.yaml file.
• Rebuild the container using Ctrl + Shift + P and Rebuild Container. Then the environment variable should be available everywhere.
• Hit F5 and your project should be build, the debugger starts and flashes the code onto the MCU

HINT : Sometimes the flashrate is critical when it comes to long cables on SWD flashing. This can be set in the stm32f3x.cfg e.g. Just get your specific one from /usr/share/openocd/scripts/target and look for adapter speed. Change it accordingly to your needs.

Hints

CPU flags for gcc-arm-none-eabi compiler and linker

General rule for settings would be as per table below

STM32 Family	-mcpu	-mfpu	-mfloat-abi
STM32F0	cortex-m0	Not used	soft
STM32F1	cortex-m3	Not used	soft
STM32F2	cortex-m3	Not used	soft
STM32F3	cortex-m4	fpv4-sp-d16	hard
STM32F4	cortex-m4	fpv4-sp-d16	hard
STM32F7 SP	cortex-m7	fpv5-sp-d16	hard
STM32F7 DP	cortex-m7	fpv5-d16	hard
STM32G0	cortex-m0plus	Not used	soft
STM32C0	cortex-m0plus	Not used	soft
STM32G4	cortex-m4	fpv4-sp-d16	hard
STM32H5	cortex-m33	fpv5-sp-d16	hard
STM32H7	cortex-m7	fpv5-d16	hard
STM32L0	cortex-m0plus	Not used	soft
STM32L1	cortex-m3	Not used	soft
STM32L4	cortex-m4	fpv4-sp-d16	hard
STM32L5	cortex-m33	fpv5-sp-d16	hard
STM32U0	cortex-m0plus	Not used	soft
STM32U5	cortex-m33	fpv5-sp-d16	hard
STM32WB	cortex-m4	fpv4-sp-d16	hard
STM32WBA	cortex-m33	fpv5-sp-d16	hard
STM32WL CM4	cortex-m4	Not used	soft
STM32WL CM0	cortex-m0plus	Not used	soft