# 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

<details>
<summary>Git</summary>

## 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 ```<Write a tag here>``` with something unique of your choice (e.g. mail address):

```(cmd)
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.

```(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 <directory to private SSH key>
```

Now you have set up your ssh key!

</details>


<details>
<summary>Docker</summary>

## 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/).

</details>


# 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`      |