# 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](https://www.media-techport.de/2023/08/howto-ssh-schluessel-fuer-gitea-einfache-einrichtung/). 1. Generate the key by replacing the `````` with something unique of your choice (e.g. mail address): ```(cmd) ssh-keygen -t ed25519 -C "" ``` - 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. ```(cmd) 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: ```cmd ssh-add ``` Now you have set up your ssh key!
Docker ## Docker 1. ![Install docker](https://docs.docker.com/engine/install/ubuntu/) via apt repository. NOT via snap, this can lead to cruel errors during usage. 1. Make sure that you can use docker as sudo. 1. Add a docker group ```(cmd) sudo groupadd docker ``` 1. Add you user to this group ```(cmd) sudo usermod -aG docker $USER ``` 1. Log out and log back in or run ```(cmd) newgrp docker ``` 1. Test it with ```(cmd) docker run hello-world ``` 1. Log in to a registry using docker ```(cmd) docker login git.fasttube.de ``` 1. 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](https://docs.docker.com/engine/reference/commandline/login/).
# Installation ```(cmd) git clone --recurse-submodules ssh://git@git.fasttube.de:313/FaSTTUBe/stm32_devcontainer.git ``` # Usage ## Start the DevContainer 1. Install the [Dev Container Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in VS Code. 1. Navigate to the cloned repository in the terminal ```(cmd) cd /path/to/ft_as ``` 1. Open VS Code with: ```(cmd) code . ``` 1. 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. ```(cmd) xhost + ``` To verify if everything worked, try to open the STM32CubeMX. Execute the following from inside the container: ```(cmd) 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 ```(cmd) echo $DISPLAY OUTPUT: :1 ``` ```(cmd) xauth list OUTPUT: :1 MIT-MAGIC-COOKIE-1 ``` ```(cmd) export DISPLAY=:1 ``` ```(cmd) 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 ```(cmd) git submodule add ``` 1. Open STM32CubeMX with the terminal command ```stm32cubemx``` 1. Choose a MCU family. If it is one of the supporterd ones you dont even have to login here. 1. Configure the Project as CMake project and set the directory to the repo you just created. 1. 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](https://github.com/MaJerle/stm32-cube-cmake-vscode/blob/main/README.md) 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` |