fsfw-example-stm32h7-freertos/README.md

<img align="center" src="https://egit.irs.uni-stuttgart.de/fsfw/fsfw/raw/branch/mueller/master/misc/logo/FSFW_Logo_V3_bw.png" width="50%">

# <a id="top"></a> <a name="linux"></a> FSFW Example Application

This repository features a demo application. The example has been run successfully on the following 
platforms:

 - Linux host machine with the Linux OSAL or the Host OSAL
 - Windows with the Host OSAL
 - STM32H743ZI-Nucleo with the FreeRTOS OSAL
 - Raspberry Pi with the Linux OSAL
 - STM32H743ZI-Nucleo with the RTEMS OSAL

The purpose of this example is to provide a demo of the FSFW capabilities.
However, it can also be used as a starting point to set up a repository for
new flight software. It also aims to provide developers with practical examples
of how the FSFW is inteded to be used and how project using the FSFW should or can be
set up and it might serve as a basic test platform for the FSFW as well to ensure all OSALs
are compiling and running as expected.

The repository contains a Python TMTC program which can be used to showcase
the TMTC capabilities of the FSFW (currently, using the ECSS PUS packet standard).

# Configuring the Example

The build system will copy three configuration files into the build directory:

1. `commonConfig.h` which contains common configuration parameters
2. `OBSWConfig.h` which can contain machine and architecture specific configuration options
3. `FSFWConfig.h` which contains the configuration for the flight software framework

These files can be edited manually after `CMake` build generation.

# Index

[Getting started with Eclipse for C/C++](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-common/src/branch/master/doc/README-eclipse.md)<br>
[Getting started with CMake](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-common/src/branch/master/doc/README-cmake.md)<br>

[Getting started with the Hosted OSAL](#this)<br>
[Getting started with the FreeRTOS OSAL on a STM32](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-stm32h7-freertos)<br>
[Getting started with the RTEMS OSAL on a STM32](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-stm32h7-rtems)<br>
[Getting started with the Raspberry Pi](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)<br>
[Getting started with the Beagle Bone Black](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)<br>

# FSFW demo with FreeRTOS OSAL on the STM32H743ZI

This demo can be run on a STM32H743ZI-Nucleo board with the FreeRTOS OSAL.

## General Information

The board is flashed and debugged with OpenOCD and this README specifies on how
to make this work with the Eclipse IDE. Other IDEs or the command line can be used as well as long 
as long as OpenOCD integration is given. The example demo uses newlib nano (glibc). 
Some system calls were overriden so the C and C++ stdio functions work. IO is sent via the HUART3,
so debug output can be read directly from the USB connection to the board.

## Prerequisite

1. [MinGW64](https://www.msys2.org/) or [Ninja Build](https://ninja-build.org/) installed on Windows.
   Not required on Linux.
2. [GNU ARM Toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/) installed, recommended 
   to add binaries to system path.
3. Recommended for application code development: 
   [Eclipse for C/C++](https://www.eclipse.org/downloads/packages/) installed with the Eclipse MCU 
   plugin
4. [OpenOCD](https://xpack.github.io/openocd/) installed for Eclipse debugging
5. STM32 USB drivers installed, separate steps for 
   [Windows](https://www.st.com/en/development-tools/stsw-link009.html) or 
   [Linux](https://fishpepper.de/2016/09/16/installing-using-st-link-v2-to-flash-stm32-on-linux/)

## Building the software with CMake

On Windows, the following steps should be performed inside the MinGW64 console 
after installing MSYS2 or inside another Unix shell like `git bash`. 

1. Clone this repository
   ```sh
   git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example.git
   ```

2. Set up submodules
   ```sh
   git submodule init
   git submodule update
   ```
   
3. Navigate into the cloned repository and create a folder for the build. We will create a 
   Debug build folder.

   ```sh
   mkdir build-Debug
   cd build-Debug
   ```

4. Ensure that the ARM compiler has been added to the path and can be called from 
   the command line. For example, the following command should work:

   ```sh
   arm-none-eabi-gcc --version
   ```
   
   Now we will create the build configuration for cross-compilation of an ARM target.
   On Linux, the following build will create a debug build configuration with
   the Unix Makefile generator. You can also specify `-G Ninja` to use Ninja instead
   of Make.
   
   ```sh
   cmake ..
   ```
   
   On Windows, use the following command to build with the `MinGW Makefiles` build system
   
   ```sh
   cmake -G "MinGW Makefiles" ..
   ```
   
   The build configuration can also be performed with the shell scripts located inside 
   `cmake/scripts`.
    
5. Build the application with the following command

   ```sh
   cmake --build . -j
   ```
   The application will be located inside the Debug folder and has been compiled for 
   the flash memory.
   
6. You can test the application by first connecting the STM32H743ZI-Nucleo via USB.
   The device should now show up in the list of connected devices (make sure the USB drivers are 
   installed as well). Drag and drop the binary file into the connected device to flash it. 
   The debug output is also sent via the connected USB port and a blink pattern (1 second interval) 
   can be used to verify the software is running properly.
   
## Setting up the prerequisites

### Windows

It is recommended to install [MSYS2](https://www.msys2.org/) first.
Open MinGW64 and run the following commands to update it and install make and cmake 
(replace x86_64 if compiling on different architecture):

```sh
pacman -Syu
```

```sh
pacman -S mingw-w64-x86_64-make mingw-w64-x86_64-cmake
```

Alternatively, you can install [Ninja Build](https://ninja-build.org/), but you need
to add the folder containing the `ninja.exe` executable to the system path so you
can run `ninja -v` from the command line. If you do this, you can also use
`git bash` or the Windows command lines with the CMake Ninja generator
to build the software.

The code needs to be cross-compiled for the ARM target system and we will use the
[GNU ARM Toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/).

1. Install NodeJS LTS. Add nodejs folder (e.g. "C:\Program Files\nodejs\")
   to system variables. Test by running `npm --version` in command line
2. Install [XPM](https://www.npmjs.com/package/xpm)
   ```sh
   npm install --global xpm
   ```

3. Install gnu-arm Toolchain for Eclipse (version can be specified)
   ```sh
   xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@latest
   ```
   
   `xpm` will display where the package was installed. Search in that path for
   the hidden `.content` folder, which will contain a `bin` folder and store
   the full path to that `bin` folder for later.

   Install OpenOCD for STM32 debugging
   ```sh
   xpm install --global @xpack-dev-tools/openocd@latest
   ```
   
4. If you want to build from the command line, you need to add the `arm-none-eabi-gcc` 
   binary location in the xPack folder to system variables. You can do this in a Unix
   shell like `git bash` or `MinGW64` with the following command

   ```sh
   export PATH=$PATH:"<pathToToolchain>"
   ```
   
   You can also add these lines to a shell script like `path_setter.sh` and then source
   the script with `. path_setter.sh` to do this conveniently. You can test whether
   the path was set up properly by running `arm-none-eabi-gcc -v`

5. Install the [STM32 USB drivers](https://www.st.com/en/development-tools/stsw-link009.html)

If you don't want to install nodejs you may go with the 
[four-command manual installation](https://xpack.github.io/arm-none-eabi-gcc/install/#manual-install). 

### Linux

Install the [GNU ARM toolchain](https://xpack.github.io/arm-none-eabi-gcc/install/)
like explained above.
   
To install general buildtools for the linux binary, run:
```sh
sudo apt-get install build-essential
```

Install the [USB drivers](https://github.com/stlink-org/stlink) on Linux.
On Ubuntu, you can run the following command to install it:

```sh
sudo apt-get install stlink-tools
```

## Setting up Eclipse for OpenOCD debugging

The separate [Eclipse README](README-eclipse#top) specifies how to set up Eclipse.
The STM32 configuration uses the xPacks OpenOCD and the xPacks ARM Toolchain, so those should be 
installed as well. OpenOCD should be configured correctly in the STM32 launch configurations.

## Troubleshooting 

### OpenOCD errors

If you get the following error in OpenOCD: "Error: auto_probe failed", this could be related from
switching between FreeRTOS and RTEMS. You can try the following steps:

1. First way:  Flash the binary manually by drag & droping the binary into the USB drive manually 
   once
   
2. Second way: Add -c "gdb_memory_map disable" to the OpenOCD arguments (in Eclipse) and run once.
   Debugging might not be possible, so remove it for subsequent runs.

3. Third way: Add the following lines to the `stm32h7x.cfg` file located inside the OpenOCD folder 
   inside the `scripts/target` folder:

   ```sh
   $_CHIPNAME.cpu configure -event gdb-attach {
       halt
   }

   $_CHIPNAME.cpu configure -event gdb-attach {
       reset init
   }
   ```