From 9cd5a6a404c41e63c41249062039e7ee6455c353 Mon Sep 17 00:00:00 2001 From: "r.koeppe" Date: Tue, 18 Jun 2024 11:31:04 +0000 Subject: [PATCH] Added readme --- README.md | 202 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 201 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 86d5d8b..43dec23 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,205 @@ # STM32 DevContainer -This repo is a template to make STM programming easier. You can develop with the standard STM32CubeIDE or in a VSCode cmake project. Debugging is possible in both ways using GDB Link Server or OpenOCD. +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. It should be preinstalled in Ubuntu. + +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 git@github.com:rimakoe/stm32.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. + +## Create a CMake Repo + +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 it up in the *projects* directory. + +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. + +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. + + +# Debug + +For debugging you have to configure the launch.json + +# 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` | \ No newline at end of file