Init commit

doc/README-cmake.md

@@ -0,0 +1,76 @@
+<img align="center" src="./images/cmake.png" width="25%">
+
+<sub><sup>Image taken from [Wikipedia](https://commons.wikimedia.org/wiki/File:Cmake.svg) 
+and licensed under [Creative Commons 2.0](https://creativecommons.org/licenses/by/2.0/deed.en), 
+no changes made</sup></sub>
+
+CMake is a modern cross-platform build system which is able to generate
+various build systems. It also features a dependency management system which
+allows developers to operate on targets (e.g. compile target as a library, link
+against a target) which allows better control of build properties compared
+to tools like Make.
+
+## Building with CMake
+
+Generally, building software with CMake is a two-step process.
+First, the build configuration is set up using the CMake build system or IDE project 
+generators and then the software is built using the select build system or IDE.
+CMake projects are generally built out-of-source which means that the files generated
+during the build process are kept separately from the source tree. This generally involves
+creating a build folder like `Debug` or `Release` and then performing all
+steps inside that folder.
+
+It is also possible to generate IDE project files with CMake. This is 
+not recommended for Eclipse because the CDT generation is not very good. 
+Instead, it is recommended to configure the build system once in the command line and then 
+invoke the CMake build command from Eclipse.
+Script files were supplied in the `buildsystem` folder to have a starting point.
+
+It is also possible to generate Visual Studio files but this has not been tested extensively yet.
+
+It is possible to perform the build configuration steps with the
+`cmake-gui` or with the curses `ccmake` command line utility. This also provides a graphical displayed
+of available options and variables.
+
+## Build Configuration options in CMake
+
+Call `cmake --help` to get a first overview of how the CMake build configuration
+works. Generally, build options can be displayed by running following command:
+
+```sh
+cmake -LA <path-to-source>
+```
+
+The general form to configure a build system is to call this command
+in the folder where the build system should be set up (this is generally not
+in a separate folder to avoid pollution of the source tree).
+
+The generators for the host system can be displayed with `cmake --help` as well
+and are supplied with `-G` to the build configuration. 
+Please note that the OSAL and architecture specific READMEs contain the 
+explicit commands to configure the build systems correctly.
+
+```sh
+cmake -G <Build Generator> <Options and Defines> <path-to-source>
+```
+
+Following build configurations are possible by setting the `CMAKE_BUILD_TYPE`
+string when configuring the build system. Supply `-DCMAKE_BUILD_TYPE=<option>` 
+to do this:
+
+1. `None`: No flags added
+1. `Debug`: Default type if no build type is specified 
+2. `RelWithDebInfo`: Release build, but debug symbols included 
+3. `MinSizeRel`: Build for minimum size 
+4. `Release`: Build for maximum speed
+
+For more information, see the [CMake website](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/Useful-Variables#compilers-and-tools)
+
+The FSFW OSAL can be specified with the `OS_FSFW` define during build configuration
+Supply `-DOS_FSFW=<option>` to the configuration to do this.
+Possible options are:
+
+1. `host`: Host OSAL, tested for Windows 10 and Linux (Ubuntu 20.04)
+2. `linux`: Linux OSAL, tested for regular Linux (Ubuntu 20.04) and embedded Linux
+3. `freertos`: FreeRTOS OSAL, example for the STM32H743ZI-Nucleo development board provided.
+4. `rtems`: Currently, no example provided, but will be provided for STM32H743ZI-Nucleo board.

doc/README-eclipse.md

@@ -0,0 +1,190 @@
+<img align="center" src="./images/eclipse_logo_colour.png" width="30%">
+
+<sub><sup>Image taken from [Eclipse website](https://www.eclipse.org/artwork/)</sup></sub>
+
+Eclipse is a general purpose IDE, which was initially developed for Java
+but has evolved to be used for C/C++ as well. It is the recommended IDE
+to develop Software with the FSFW because it is cross-platform, provides
+useful features like an indexer and can be configured with moderate effort
+to use the Make and CMake build systems.
+
+## Setting up Eclipse - General
+
+Eclipse project files and launch configurations were provided to have a starting 
+point for application development with Eclipse. It is recommended to use those 
+files and delete unneeded run configurations manually.
+There are separate project files to either use the Makefiles or CMake.
+
+1. Install [Eclipse for C/C++](https://www.eclipse.org/downloads/packages/) 
+   using the installer. Install the Eclipse MCU plugin
+   for the STM32 and Raspberry Pi example by going to Help &rarr; Eclipse 
+   Marketplace and searching and installing the plugin
+
+2. For the STM32, the ARM toolchain (and Windows Build Tools on Windows) should have been 
+   installed previously. Go to Window &rarr; Preferences &rarr; MCU &rarr; Global ARM Toolchain 
+   and Windows Build Tools. Packages installed with xpm should be recognized automatically.
+   
+3. Setting up the indexer: It is recommended to use the separate indexers for 
+each run configurations. Right click on the project folder in the tree view, 
+go to Properties &rarr; C/C++ General &rarr; Indexer and set the indexer as shown below.
+
+   <img align="center" src="./images/eclipse/eclipse-indexer.png" width="50%">
+
+4. Cross-Compiling: In general, the provided project configurations should set up 
+   the cross compiler properly. However, if there are issues, the user should 
+   check whether the compilers are set up properly.
+   
+   Right click on the project folder in the tree view, go to 
+   Properties &rarr; C/C++ Build &rarr; Tool Chain Editor and set the correct 
+   editor. Then go to Properties &rarr; C/C++ Build &rarr; Settings and check 
+   whether the cross-compiler paths are correct.
+
+
+## Setting up Eclipse for a hosted CMake projects
+
+1. Copy the  files `.project` and `.cproject` inside the misc/eclipse/make folder 
+   into the root of the cloned folder. This will add all build configurations.
+   
+   ```sh
+   cd fsfw_example
+   cp misc/eclipse/cmake/.project .
+   cp misc/eclipse/cmake/.cproject .
+   ```
+   
+2. Import the project now by going to File &rarr; Import &rarr; Existing Projects and selecting the cloned folder. 
+   Only check the root folder, Eclipse will try to import every folder which contains
+   `.project` or `.cproject` files!
+   
+   <img src="./images/eclipse_cfg.PNG" width="50%">
+
+3. Set up the build folders. Helper scripts have been provided to perform this 
+   task and have a starting point, but a valid Python 3 installation is required for them to work. 
+   For example, to create the build folder `Debug` and build the software 
+   with the FSFW Host OSAL on Windows or Linux, perform the following steps in the MinGW64 
+   command line or Linux terminal after navigating into the cloned example folder:
+   
+   ```sh
+   cd buildsystem/cmake/scripts/Host
+   ./create_cmake_debug_cfg.sh
+   ```
+   
+   The shell script can also be run by double clicking it in Windows as long as it is executed
+   by the MinGW terminal. This shell script will first create a new Debug folder (and delete the old one)
+   and then execute the following command in the Debug folder on Windows
+   
+   ```sh
+   cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug -DOS_FSFW=host
+   ```
+   
+   or the following command on Linux:
+   
+   ```sh
+   cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DOS_FSFW=host
+   ```
+   
+   For example, the execution of the script in MinGW64 on Windows should show the
+   following output:
+   
+   <img src="./images/build_cfg_mingw.PNG" width="50%">
+   
+4. The build system is now ready to be used in Eclipse. Select the `fsfw-mingw-debug-cmake` (Windows)
+   or `fsfw-linux-debug-cmake` (Linux) launch configuration
+   in Eclipse and press the hammer button to build the software or the bug button to debug the 
+   software for a host machine. This will invoke `cmake --build . -j` in the respective build 
+   folders to build the software.
+   
+## Seting up Eclipse for Raspberry Pi projects - Remote Application
+
+Eclipse is configured to assume that the toolchain is located in `/opt/cross-pi-gcc/bin` and 
+will deduce settings and compiler specs automatically (e.g. for the indexer) if the provides build 
+and launch configurations are used. Adapt the toolchain  path accordingly if is installed 
+somewhere else.
+
+
+Follow steps one and two of the previous section. 
+
+3. Set up the run configuration properly by setting up a SSH connection with 
+   your Raspberry Pi. Go to Run &rarr; Debug Configurations.., look for the 
+   `C/C++ Remote Application` section and click on one of the configurations 
+   provided for the Raspberry Pi. A new SSH connection should be set up here. 
+   The following image shows an example
+
+    <img src="./images/eclipse/eclipse-rpi.png" width="50%">   
+
+4. Set up the build folders if this was not done already. 
+   We are going to do this with the script
+   
+   ```sh
+   cd buildsystem/cmake/scripts/RPi
+   ./create_cmake_debug_cfg.sh
+   ``` 
+
+5. The build system is now ready to be used in Eclipse. 
+   Select the `fsfw-rpi-debug-cmake` launch configuration and press the run or 
+   debug button in the top panel on the right side to run or debug the application. 
+   If there are issues, ensure that the Launch Configuration uses the correct 
+   SSH settings to connect to the Raspberry Pi. 
+
+On Windows, MinGW Makefiles are used for the cross-compilation process, but Eclipse will only 
+have the Windows environmental variables cached. This can lead to issues with the CMake build if it
+is configured in MinGW64. It is recommended to add the `RASPBIAN_ROOTFS` and the `RASPBERRY_VERSION`
+variable to the Windows environmental variables.
+
+The following picture shows an example:
+
+<img src="./images/eclipse/rpi-win-environment.PNG" width="50%">
+
+Alternatively, you can also add them to the Eclipse environmental variables in Properties &rarr;
+C/C++ Build &rarr; Environment
+
+## Setting up Eclipse for Raspberry Pi projects - TCF agent
+
+Alternatively, the [TCF agent](https://wiki.eclipse.org/TCF) can be used 
+as a more generic and powerful tool to perform remote debugging.
+
+1. Install the TCF agent plugin in Eclipse from the 
+   [releases](https://www.eclipse.org/tcf/downloads.php). Go to 
+   Help &rarr; Install New Software and use the download page, for 
+   example https://download.eclipse.org/tools/tcf/releases/1.6/1.6.2/ to search 
+   for the plugin and install it.
+
+2. Go to Window &rarr; Perspective &rarr; Open Perspective and open the 
+   **Target Explorer Perspective**. Here, the Raspberry Pi should show up if 
+   the TCF agent has been set up on the Raspberry Pi as specified 
+   [here](https://wiki.eclipse.org/TCF/Raspberry_Pi) or in the 
+   respective [README](README-rpi.md#top). Connect to it.
+
+3. Create a new **TCF Remote Application**. No launch configuration has 
+   been provided because the IP address can change regularly.
+
+ - Create a new the configuration by pressing the cogs button at the top or 
+   going to Run &rarr; Debug Configurations &rarr; Remote Application and
+   creating a new one there. 
+
+ - Select the TCF connection, the correct image in the main tab (it might be 
+   necessary to send it the the Raspberry Pi manually once) and file transfer properties
+
+ - It is also recommended to link the correct Eclipse project. 
+
+After that, comfortable remote debugging should be possible with the Debug button.
+
+## Setting up Eclipse for the Makefile projects
+
+The Makefiles are not maintained anymore and it is recommended to use the 
+CMake build configurations instead.
+
+1. Copy the  files `.project` and `.cproject` inside the misc/eclipse/make folder 
+   into the root of the cloned folder. This will add all build configurations.
+   Configurations which are not required can be deleted manually.
+   
+   ```sh
+   cd fsfw_example
+   cp misc/eclipse/make/.project .
+   cp misc/eclipse/make/.cproject .
+   ```
+   
+2. Import the project now by going to File &rarr; Import &rarr; Existing Projects and selecting
+   the cloned folder.
+   
+3. It should now be possible to build and debug the program by selecting the 
+   correct launch configuration in the top panel and hitting the hammer or debug button.

doc/README-host.md

@@ -0,0 +1,175 @@
+# FSFW demo with Host OSAL on Windows or Linux
+
+This demo has been tested for Windows and Linux. It uses 
+the host abstraction layer of the FSFW.
+
+## General Information
+
+This demo provides the opportunity to to test functionality of the
+FSFW on a host computer without the need of setting up external embedded hardware.
+
+## Prerequisites
+1. Makefile build: make installed (bundled with MSYS2 on Windows or via [xPacks Windows Build Tools](https://xpack.github.io/windows-build-tools/install/)). Natively installed on Linux.
+2. Recommended for application code development: [Eclipse for C/C++](https://www.eclipse.org/downloads/packages/) . 
+   Project files and launch configuration are provided for Eclipse to ease development.
+   Visual Studio support might follow soon following CMake implementation.
+3. CMake Build: Correct CMake installation.
+
+### Windows - MinGW64 build
+
+1. [MSYS2 and MinGW64](https://www.msys2.org/) installed
+2. Update MSYS2 by opening it and running
+   ```sh
+   pacman -Syuuu
+   ```
+   
+   After that, the gcc toolchain, git, make and CMake should be installed with
+   ```sh
+   pacman -S git mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb mingw-w64-x86_64-make mingw-w64-x86_64-cmake
+   ```
+   
+   You can install a full development environment with
+   ```sh
+   pacman -S base-devel
+   ```
+
+   or install `gcc`, `gdb` and `mingw32-make` with the following command 
+
+   ```sh
+   pacman -S mingw-w64-x86_64-toolchain
+   ```
+   
+   It is recommended to set up aliases to get to the example directory
+   quickly.
+   
+3. It is recommended to add the MinGW64 bit binaries to the system path so Eclipse can use 
+   them. It is also recommended to run `git config --global core.autocrlf true` when using MinGW64 
+   to have consistent line endings on Windows systems.
+   
+### Linux - Enabling RTOS functionalities
+
+The last chapter in the [Linux README](README-linux.md#top) specifies some steps required
+to cleanly run the FSFW on a (host) Linux system.
+
+## Building the Software with CMake
+
+CMake should be [installed](https://cmake.org/install/) first.
+More detailed information on the CMake build process and options
+can be found in the [CMake README](README-cmake.md#top).
+Readers unfamiliar with CMake should read this first. The following steps will show to to build
+the Debug executable using either the "Unix Makefiles" generator on Linux or
+the "MinGW Makefiles" generator in Windows in the command line to be as generic as possible.
+
+### Linux Build
+
+1. Create a new folder for the executable.
+   ```sh
+   mkdir Debug
+   cd Debug
+   ```
+   
+2. Configure the build system 
+   ```sh
+   cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DOS_FSFW=host ..
+   ```
+   
+3. Build the software
+   ```sh
+   cmake --build . -j
+   ```
+
+4. The binary will be located inside the Debug folder and can be run there
+   ```sh
+   ./fsfw-example
+   ```
+   
+### MinGW64 Build
+
+Set up MinGW64 like explained previously. 
+
+The CMake build can be generated either with the CMake GUI tool or with the MinGW64 command line.
+Steps will be shown with the MinGW64 command line tool, but the CMake GUI can be used on Windows 
+as well to have a convenient way to configure the CMake build.
+
+1. Open the MinGW64 terminal and navigate to the `fsfw_example` folder
+2. Create a new folder for the executable.
+   ```sh
+   mkdir Debug
+   cd Debug
+   ```
+	
+   The build options can be displayed with `cmake -L` . 
+   
+3. Configure the project and generate the native MinGW64 buildsystem
+   ```sh
+   cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug -DOS_FSFW=host ..
+   ```
+   
+   The build configuration can also be performed with the shell scripts located inside `cmake/scripts/Host` or the Python helper script `cmake_build_config.py` inside `cmake/scripts`.
+   The configured build options can now be shown with `cmake -L`.
+
+4. Call the build system (Make)
+   ```
+   cmake --build . -j
+   ```
+  
+5. Like already mentioned, it is recommended to run the binary directly as an executable by 
+   double-clicking it or in the Windows Terminal. 
+   
+### Setting up Eclipse for CMake projects
+
+The separate [Eclipse README](README-eclipse#top) specifies how to set up Eclipse to build CMake projects. 
+Separate project files and launch configurations for the MinGW build were provided.
+  
+## Building the Software with Makefiles
+
+The Makefile is able to determine the OS and supply additonal required libraries, 
+but this has only been tested for Windows 10 and Linux (Ubuntu 20.04)
+
+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. Copy the `Makefile-Hosted` file in the `make` folder into the cloned folder root
+   and rename it to `Makefile`
+   
+4. Once all the prerequisites have been met. the binary can be built with the following command. 
+   Replace `debug` with `release` to build the optimized binary.
+
+   ```sh
+   make debug -j
+   ```
+   
+### Setting up Eclipse for CMake projects
+
+The separate [Eclipse README](README-eclipse#top) specifies how to set up Eclipse to build CMake projects. Separate project files and launch configurations for the MinGW build were provided. The debug output is colored by default. It is recommended to install the
+`ANSI Escape in Console` plugin in Eclipse so the coloring works in the Eclipse console.
+
+
+## Running or Debugging the Software - Makefile
+
+### Linux 
+The Makefile binary will be generated in the `_bin` folder and can be run in Linux directly from the console.
+
+### Windows
+On Windows, it is recommended to run the binary in the command line or as a regular executable (double-click)
+to get the full debug outpu because there seem to be issues with the MinGW output.
+The Windows Terminal can be opened in Eclipse by right clicking on the `_bin` folder in the project explorer and clicking
+Show in Local Terminal
+
+## Setting up Eclipse - Makefile
+
+The separate [Eclipse README](README-eclipse#top) specifies how to set up Eclipse. Separate project files and launch
+configurations for the MinGW build were provided.
+
+
+
+
+

doc/README-linux.md

@@ -0,0 +1,172 @@
+# FSFW demo with the Linux OSAL
+
+This demo can be run on a Linux host computer. The application can be built with Make or
+with CMake. It is generally assumed that the application will still run on a host computer, 
+so the `bsp_hosted` folder is used.
+
+This demo still uses the Linux abstraction OSAL, so it is in principle possible
+to compile it for embedded linux by setting the correct cross compiler by 
+supplying `CROSS_COMPILE=<toolchain>` to the make command (however, a custom makefile 
+is propably still necessary).
+
+## Generical Information
+
+These steps were tested for Ubuntu 20.04. Adapt accordingly for used
+Linux distribution. If not done yet, install the full C++ build chain:
+
+```sh
+sudo apt-get install build-essential
+```
+
+Linux has a limit to message queue message. Please see the section 
+to set up UNIX environment for more information.
+Sometimes, special steps are necessary so the real-time functionalities can be used
+without root privileges. Instructions are contained in the setup section
+for UNIX as well.
+
+## Building the software with CMake
+
+CMake should be [installed](https://cmake.org/install/) first.
+More detailed information on the CMake build process and options 
+can be found in the [CMake README](README-cmake#top).
+Readers unfamiliar with CMake should read this first. The following steps will show to to build
+the Debug executable using the "Unix Makefiles" generator in the command line to be 
+as generic as possible.
+
+1. Clone the repository with
+   ```sh
+   git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example.git
+   cd fsfw_example
+   ```
+
+2. Update all the 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-Linux
+   cd build-Debug-Linux
+   ```
+   
+4. Create and configure the build system. The CMake default build system shoule be
+   "Unix Makefiles" by default. If this is not the case, add `-G "Unix Makefiles` 
+   to the command. Type `cmake --help` for more information.
+   
+   ```sh
+   cmake -DOS_FSFW=linux -DCMAKE_BUILD_TYPE=Debug ..
+   ```
+   
+   The build configuration can also be performed with the shell scripts located inside `cmake/scripts/Linux` or the Python helper script `cmake_build_config.py` inside `cmake/scripts`.
+   The configured build options can now be shown with `cmake -L`.
+
+5. Build the application
+   ```sh
+   cmake --build . -j
+   ```
+   The application will be located inside the Debug folder.
+
+### Setting up Eclipse for CMake projects
+
+The separate [Eclipse README](README-eclipse#top) specifies how to set up Eclipse to build CMake projects. The debug output is colored by default. It is recommended to install the
+`ANSI Escape in Console` plugin in Eclipse so the coloring works in the Eclipse console.
+
+## Building the software with Make
+
+1. Clone the repository with
+   ```sh
+   git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example.git
+   cd fsfw_example
+   ```
+
+2. Update all the submodules
+   
+   ```sh
+   git submodule init
+   git submodule sync
+   git submodule update
+   ```
+
+3. Copy the `Makefile-Linux` file in the `buildsystem/make` folder into the root folder 
+   and rename it to `Makefile`
+   
+   ```sh
+   cp buildsyste/make/Makefile-Linux .
+   mv Makefile-Linux Makefile
+   ```
+
+3. After that, the linux binary can be built with:
+
+   ```sh
+   make -j all
+   ```
+
+   to compile for Linux. All will build the debug version,
+   which can also be built with the target `debug`. The optimized
+   release version can be built with the target `release`.
+
+4. Run the binary located inside the `_bin` folder.
+
+## Setting up UNIX environment for real-time functionalities
+Please note that on most UNIX environments (e.g. Ubuntu), the real time functionalities 
+used by the UNIX pthread module are restricted, which will lead to permission errors when creating these tasks
+and configuring real-time properites like scheduling priorities.
+
+To solve this issues, try following steps:
+
+1. Edit the /etc/security/limits.conf 
+file and add following lines at the end:
+```sh
+<username>   hard   rtprio  99
+<username>   soft   rtprio  99
+```
+The soft limit can also be set in the console with `ulimit -Sr` if the hard
+limit has been increased, but it is recommended to add it to the file as well for convenience.
+If adding the second line is not desired for security reasons,
+the soft limit needs to be set for each session. If using an IDE like eclipse 
+in that case, the IDE needs to be started from the console after setting
+the soft limit higher there. After adding the two lines to the file,
+the computer needs to be restarted.
+
+It is also recommended to perform the following change so that the unlockRealtime
+script does not need to be run anymore each time. The following steps
+raise the maximum allowed message queue length to a higher number permanently, which is 
+required for some framework components. The recommended values for the new message
+length is 130.
+
+2. Edit the /etc/sysctl.conf file
+```sh
+sudo nano /etc/sysctl.conf
+```
+Append at end: 
+```sh
+fs/mqueue/msg_max = <newMsgMaxLen>
+```
+Apply changes with: 
+```sh
+sudo sysctl -p
+```
+
+A possible solution which only persists for the current session is
+```sh
+echo <newMsgMax> | sudo tee /proc/sys/fs/mqueue/msg_max
+```
+or running the `unlockRealtime` script.
+
+3. Run the shell script inside the linux folder
+```sh
+./unlockRealtime
+```
+This script executes the `sudo setcap 'cap_sys_nice=eip' \<application\>`
+command on the binaries, increases the soft real time limit of the current
+session and increases the maximum number of message queues by setting
+`/proc/sys/fs/mqueue/msg_max`.
+All changes are only applied for the current session (read 2. and 3. for 
+a permanent solution). If running the script before executing the binary does
+not help or an warning is issue that the soft real time value is invalid, 
+the hard real-time limit of the system might not be high enough (see step 1).
+

doc/README-rpi.md

@@ -0,0 +1,380 @@
+<img align="center" src="./images/rpi/RPi-Logo-Landscape-Reg-PRINT.png" width="30%">
+
+<sub><sup>Image taken from [Raspberry Pi website](https://www.raspberrypi.org/trademark-rules/). Raspberry Pi is a trademark of the Raspberry Pi Foundation</sup></sub>
+
+# Getting started on the Raspberry Pi
+
+The FSFW can be run on a Raspberry Pi with the Linux OSAL, using
+an ARM linux cross compiler. Instructions will be provided on how 
+to do this.
+
+## General Information
+
+The following instructions will show how to install the cross compiler on
+a host machine and mirror the Rapsberry Pi sysroot folder on the host machine
+so that the same libraries and headers used on the Raspberry Pi are used
+for the cross-compilation process. The provided Eclipse project files
+and launch configurations also provide a starting point to perform
+remote debugging on a Raspberry Pi, using a SSH connection.
+
+## Prerequisites for direct compilation and cross-compiling
+
+1. SSH connection to the Raspberry Pi working 
+2. Raspberry Pi linux environment set up properly
+3. CMake and rsync installed
+
+## Setting up general prerequisites for Linux systems
+
+1. Install CMake and rsync
+    
+    ```sh
+    sudo apt-get install cmake rsync
+    ```
+  
+2. Configure the Raspberry Pi Linux environment. The last section of the 
+   [Linux REAMDE](README-linux.md#top) specifies how to set up a UNIX environment for the FSFW and is
+   also applicable to the Raspberry Pi. SSH into the Raspberry Pi and 
+   follow the instructions in that section.
+   
+3. Install the `gpiod` library
+
+   ```sh
+   sudo apt-get install gpiod libgpiod-dev
+   ```
+
+## Getting started on the Raspberry Pi
+
+Make sure to follow the steps above. Now you should be able to build the software on 
+the Raspberry Pi. A ssh connection to the Raspberry Pi is assumed here
+
+You can build the software with the following commands
+
+```sh 
+mkdir build-Debug-RPi
+cd build-Debug-RPi
+cmake -DOS_FSFW=linux -DTGT_BSP=arm/raspberrypi -DLINUX_CROSS_COMPILE=OFF -DCMAKE_BUILD_TYPE=Debug ..
+cmake --build . -j
+```
+
+## Prerequisites for cross-compiling
+
+These prerequisites are valid for Linux as well as Windows hosts.
+
+1. ARM Linux cross compiler installed
+2. Raspberry Pi sysroot folder mirrored on the host machine, using `rsync`
+3. gdb-multiarch installed on host for remote debugging or TCF agent running on Raspberry Pi
+   
+
+   
+## Cross-Compiling on a Linux Host
+
+Steps tested for Ubuntu 20.04. Adapt accordingly for used Linux distribution.
+The following steps are based on this 
+[stackoverflow post](https://stackoverflow.com/questions/19162072/how-to-install-the-raspberry-pi-cross-compiler-on-my-linux-host-machine). 
+For the steps show here, we are also going to assume that a new Raspbian image 
+based on Debian buster is used. If this is not the case, it is recommended to 
+follow the steps in the stackoverflow post above and to make sure that the 
+toolchain binaries are added to the path accordingly.
+
+
+### Setting up prerequisites for cross-compiling
+
+1. Install the pre-built ARM cross-compile with the following command
+
+    ```sh
+    wget https://github.com/Pro/raspi-toolchain/releases/latest/download/raspi-toolchain.tar.gz
+    ```
+    
+    Please note that this version of the toolchain might become obsolete in the future.
+    If another toolchain installation is used, it is still recommended to unpack the toolchain in the 
+    `/opt/cross-pi-gcc` folder so that the Eclipse configuration and helper 
+	scripts work without adaptions. Add the folder to the system path. On Linux,
+    this can generally be done with the following command
+    
+    ```sh
+    export PATH=$PATH:"/opt/cross-pi-gcc/bin"
+    ``` 
+    
+    You can add this line to the `.bashrc` or `.profile` file in the `$HOME` directory 
+    to add environmental variables permanently. More experienced users can
+	perform this step is a shell script which is `source`d to keep the environment clean.
+    
+    Test the toolchain with the following command
+    
+    ```sh
+    arm-linux-gnueabihf-gcc --version
+    ``` 
+     
+    
+2. Set up a sysroot folder on the local host machine. Make sure the SSH connection to
+   the Raspberry Pi is working without issues. Then perform the following steps
+   
+   ```sh
+   cd ~
+   mkdir raspberrypi
+   cd raspberrypi
+   mkdir rootfs
+   cd rootfs 
+   pwd
+   ```
+   
+   The result of the `pwd` command will be used later to sync the root file
+   system of the Raspberry Pi to the host machine.
+   With a Raspberry Pi 4, you can replace `<ip-address>` with `raspberrypi.local` and 
+   when using the default rootfs path, you can replace `<rootfs-path>` with
+   `$HOME/raspberrypi/rootfs`.
+   
+   ```sh
+   rsync -vR --progress -rl --delete-after --safe-links pi@<ip-address>:/{lib,usr,opt/vc/lib} <rootfs-path>
+   ```
+   
+   Please note that there might be issues with some symlinks or libraries not being copied properly.
+   This has occured with files like `libc.so.6`. If there are linker issues at a later stage,
+   you can try to rerun `rsync` without the`--safe-links` flag or copy the shared libraries or 
+   symlinks manually from the Raspberry Pi to the sysroot with `scp`.
+   
+   For example, you can copy `libc.so.6` from the Raspberry Pi to the sysroot with 
+   the following command
+   
+   ```sh
+   scp pi@<ip-address>:lib/arm-linux-gnueabihf/lib.so.6 <rootfs-path>/lib/arm-linux-gnueabihf
+   ```
+   
+3. It is recommended to install `gdb-multiarch`. This tool will allow remote debugging
+   on the host computer.  You don't need to do this if the TCF agent is used.
+   
+   ```sh
+   sudo apt-get install gdb-multiarch
+   ```
+
+4. Perform the steps [in the cross-compile section](#cross-test) to build the 
+   software for the Raspberry Pi and test it.
+   
+## Cross-Compiling on a Windows Host
+
+### Additional Prerequites
+
+1. [MSYS2](https://www.msys2.org/) installed. All command line steps shown here
+   were performed in the MSYS2 MinGW64 shell (not the default MSYS2, use MinGW64!).
+   Replace `<UserName>` with respectively. It is recommended to set up
+   aliases in the `.bashrc` file to allow quick navigation to the `fsfw_example`
+   repository and to run `git config --global core.autocrlf true` for git in
+   MinGW64.
+
+### Setting up prerequisites for Windows
+
+1. Install CMake and rsync in MinGW64 after installing MSYS2
+
+   ```
+   pacman -S mingw-w64-x86_64-cmake rsync
+   ```
+   
+2. Configure the Raspberry Pi linux environment. The last section of the 
+   [Linux REAMDE](README-linux.md#top) specifies how to set up a UNIX environment 
+   for the FSFW and isalso applicable to the Raspberry Pi. SSH into the 
+   Raspberry Pi and follow the instructions in that section.
+
+3. Install the correct [ARM Linux cross-compile toolchain provided by SysProgs](https://gnutoolchains.com/raspberry/).
+   You can find out the distribution release of your Raspberry Pi by running `cat /etc/rpi-issue`.
+
+   Test the toolchain by running:
+  
+   ```sh
+   arm-linux-gnueabihf-gcc --version
+   ``` 
+
+4. Set up a sysroot folder on the local host machine. Make sure the SSH connection to
+   the Raspberry Pi is working without issues. Then perform the following steps
+   
+   ```sh
+   cd /c/Users/<UserName>
+   mkdir raspberrypi
+   cd raspberrypi
+   mkdir rootfs
+   cd rootfs
+   pwd
+   ```
+   
+   Store the result of `pwd`, it is going to be used by `rsync` later.
+   
+   Now use rsync to clone the Rapsberry Pi sysroot to the local host machine.
+   With a Raspberry Pi 4, you can replace `<ip-address>` with `raspberrypi.local`.
+   Use the rootfs location stored from the previous steps as `<rootfs-path>`.
+   
+   ```sh
+   rsync -vR --progress -rl --delete-after --safe-links pi@<ip-address>:/{lib,usr,opt/vc/lib} <rootfs-path>
+   ```
+   
+5. There might be some issues with the pthread symbolic links. Navigate to the folder
+   containing the symlinks
+   
+   ```sh
+   cd /c/User/<UserName>/raspberrypi/rootfs/usr/lib/arm-linux-gnueabihf
+   ```
+   
+   Type `more libpthread`, press  `TAB` and check whether the symbolic 
+   link `libpthread.so` is shown. If it is not, we are going to set it up
+   manually to avoid issues when linking against `pthread` later. 
+   
+   Run the following command to create a symlink to `libpthread.so.0`
+   
+   ```sh
+   ln -s ../../../lib/arm-linux-gnueabihf/libpthread.so.0 libpthread.so 
+   ```
+   
+   Please note that there might also be issues with some symlinks or libraries not being copied 
+   properly. This has occured with files like `libc.so.6`. If there are linker issues at a later 
+   stage, you can try to rerun `rsync` without `--safe-links` or copy the shared libraries or 
+   symlinks manually from the Raspberry Pi to the sysroot with `scp`.
+   
+   For example, you can copy `libc.so.6` from the Raspberry Pi to the sysroot with 
+   the following command
+   
+   ```sh
+   scp pi@<ip-address>:lib/arm-linux-gnueabihf/lib.so.6 <rootfs-path>/lib/arm-linux-gnueabihf
+   ```
+   
+6. It is recommended to install `gdb-multiarch`. 
+   This tool will allow remote debugging on the host computer. Replace
+   `x86_64` with the correct processor architecture for other architectures.
+   
+   ```sh
+   pacman -S mingw-w64-x86_64-gdb-multiarch
+   ```
+
+7. Perform the steps [in the following chapter](#cross-test) to build the
+   software for the Raspberry Pi and test it.
+  
+## <a id="cross-test"></a> Testing the cross-compilation
+
+It is recommended to set the following environmental variables for the CMake build:
+   - `CROSS_COMPILE`: Explicitely specify the name of the cross compiler 
+   - `RASPBERRY_VERSION`: Explicitely specify the version of the Raspberry Pi
+   - `RASPBIAN_ROOTFS`: Explicitely set the path to the local RPi rootfs
+   
+For example with the following commands
+   
+```sh
+export CROSS_COMPILE="arm-linux-gnueabihf"
+export RASPBERRY_VERSION="4"
+export RASPBIAN_ROOTFS="<pathToRootFS>"
+```
+   
+   
+It is recommended to test whether the environmental variables were set correctly,
+for example by running
+   
+```sh
+echo $RASPBIAN_ROOTFS
+```
+
+
+These variables can either be set every time before a debugging session to
+keep the environment clean (should be done before starting Eclipse)
+or permanently by adding the `export` commands to system files.
+
+A helper script has been provided in `cmake/scripts/RPi` to perform
+setting up the environment. The scripts need to be `source`d instead of 
+being run like regular shell scripts. 
+
+You can also set up the environmental variables permanently by adding the 
+export commands to the `.profile` or `.bashrc` file in the `$HOME` folder.
+On Windows, MinGW64 was used to set up the build system, so you can use the
+MinGW64 `.bashrc` file to do this. If you are using Eclipse to build 
+the software, Eclipse will have the system variables from Windows,
+so it is recommended to either permanently set the three environmental
+variables in the Windows system environmental variables or add them in
+Eclipse. See the [Eclipse README](README-eclipse.md#top) for more information.
+   
+Now we can test whether everything was set up properly by compiling the example
+and running it on the Raspberry Pi via command line. 
+Navigate into the `fsfw_example` folder first. 
+
+1. Build the software locally to test the cross-compilation process. 
+   We are going to create a Debug build directory first.
+   
+   ```sh 
+   mkdir build-Debug-RPi
+   cd build-Debug-RPi
+   ```
+   
+2. Configure the build system. On Linux, run the following command:
+	
+   ```sh
+   cmake -G "Unix Makefiles" -DOS_FSFW=linux -DTGT_BSP=arm/raspberrypi -DLINUX_CROSS_COMPILE=ON -DCMAKE_BUILD_TYPE=Debug ..
+   ```
+   
+   On Windows, replace `-G "Unix Makefiles"` with `-G "MinGW Makefiles"`.
+   
+   Alternatively, you can use the helper shell scripts located inside `cmake/scripts/RPi/crosscompile`
+   or the Python helper script `cmake_build_config.py` inside the `cmake/scripts` folder.
+   The `RPi` folder also contains template shell files which can be `source`d
+   to quickly set up the environmental variables if you want to keep the system path clean.
+   
+3. Run the binary to test it
+
+   ```sh
+   scp fsfw_example pi@raspberrypi.local:/home/pi/fsfw_example
+   ssh pi@raspberrypi.local
+   ./fsfw_example
+   ```
+   
+### Setting up Eclipse for a Raspberry Pi remote target
+
+It is recommended to use the provided Eclipse project files and
+launch configurations to have a starting point. See the specific section in
+the [Eclipse README](README-eclipse.md#top) for information how to do this.
+  
+#### Windows
+
+There are some additional steps necessary on Windows: The cross-compiler by 
+default is configured to look for the cross-compiler in `/opt/cross-pi-gcc/bin`. 
+The toolchain path needs to be corrected, for example like shown in the following image:
+
+<img align="center" src="./images/eclipse/eclipse-cross-compile-win.png" width="50%">
+
+
+## Setting up the TCF agent on the Raspberry Pi
+
+It is recommended to set up a [TCF agent](https://wiki.eclipse.org/TCF) for comfortable
+Eclipse remote debugging. The following steps show how to setup the TCF agent 
+on the Raspberry Pi and add it to the auto-startup applications. The steps are taken
+from [this guide](https://wiki.eclipse.org/TCF/Raspberry_Pi)
+
+1. Install required packages on the RPi
+
+   ```sh
+   sudo apt-get install git uuid uuid-dev libssl-dev
+   ```
+   
+2. Clone the repository and perform some preparation steps
+   ```sh
+   git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
+   cd org.eclipse.tcf.agent.git/agent
+   cp -R machine/arm machine/armv6l
+   ```
+   
+3. Build the TCF agent
+   ```sh
+   make
+   ```
+   
+   and then test it by running
+   
+   ```sh
+   obj/GNU/Linux/armv6l/Debug/agent –S
+   ```
+   
+4. Finally instal lthe agent for auto-start with the following steps. The last step
+   did not work on a Rapsberry Pi 4, but apparentely was not necessary.
+   
+   ```sh
+   cd org.eclipse.tcf.agent/agent
+   make install
+   sudo make install INSTALLROOT=
+   sudo update-rc.d tcf-agent defaults
+   sudo update-rc.d tcf-agent enable 2
+   ```
+   
+The [Eclipse README](README-eclipse.md#top) specifies how to perform remote 
+debugging using the TCF agent.

doc/README-stm32-freertos.md

@@ -0,0 +1,182 @@
+# 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. 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. [MSYS2](https://www.msys2.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. It is recommended to still use git for Windows for the git
+related steps.
+
+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 Debug
+   cd 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-gdb --version
+   ```
+   
+   Now we will create the build configuration for cross-compilation of an ARM target.
+   On Linux, run the following command:
+   
+   ```sh
+   cmake -G "Unix Makefiles" -DOS_FSFW=freertos -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
+   ```
+   
+   On Windows, use the following command:
+   
+   ```sh
+   cmake -G "MinGW Makefiles" -DOS_FSFW=freertos -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
+   ```
+   
+   The build configuration can also be performed with the shell scripts located inside 
+   `cmake/scripts/FreeRTOS` or the Python helper script `cmake_build_config.py` inside 
+   `cmake/scripts`.
+    
+5. Build the application
+   ```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 -Syuuu
+```
+
+```sh
+pacman -S mingw-w64-x86_64-make mingw-w64-x86_64-cmake
+```
+
+The code needs to be 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 install --global @xpack-dev-tools/windows-build-tools@latest
+   ```
+   
+   Install OpenOCD for STM32 debugging
+   ```sh
+   xpm install --global @xpack-dev-tools/openocd@latest
+   ```
+   
+4. Add arm-none-eabi-gcc binary location in the xPack folder to system variables. 
+   These are usually located in C:\Users\<...>\AppData\Roaming\xPacks\@gnu-mcu-eclipse\arm-none-eabi-gcc\<version>\.content\bin .
+   Alternatively, if you want to keep the environment and the path clean, add it temporarily 
+   with `SET PATH=%PATH%;c:\pathtotoolchain`.
+   
+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, but for Linux, the Windows Build Tools package is not required.
+
+On Linux, the a path can be added to the system variables by adding
+`export PATH=$PATH:<..../@gnu-mcu-eclipse/arm-none-eabi-gcc/<version>/.content/bin>`
+to the `.profile` or `.bashrc` file. Alternatively, if you want to keep the environment and the 
+path clean, add it temporarily with `export PATH=%PATH%;c:\pathtotoolchain`.
+   
+To install general buildtools for the linux binary, run:
+```sh
+sudo apt-get install build-essential
+```
+
+Install the USB drivers on Linux by 
+[following these instructions](https://fishpepper.de/2016/09/16/installing-using-st-link-v2-to-flash-stm32-on-linux/).
+
+## 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
+   }
+   ```

doc/README-stm32-rtems.md

@@ -0,0 +1,146 @@
+# FSFW demo with RTEMS OSAL on the STM32H743ZI
+
+This demo can be run on a STM32H743ZI-Nucleo board with the RTEMS OSAL.
+This example is still a work-in-progress.
+
+## 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 OpenOCD integration is given. Debug otuput can be read directly from the USB 
+connection to the board.
+
+## Prerequisite
+
+1. [RTEMS BSP](https://docs.rtems.org/branches/master/user/bsps/bsps-arm.html#id25) 
+   `arm/stm32h7` installed (`arm-rtems6`)
+2. [MSYS2](https://www.msys2.org/) installed on Windows. Not required on Linux.
+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. It is recommended to still use git for Windows for the git
+related steps.
+
+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 Debug-STM32-RTEMS
+   cd Debug-STM32-RTEMS
+   ```
+   
+4. Ensure that the RTEMS 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-rtems6-gcc --version
+   ```
+   
+   Now we will create the build configuration for cross-compilation of an ARM target.
+   On Linux, run the following command:
+   
+   ```sh
+   cmake -G "Unix Makefiles" -DOS_FSFW=freertos -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
+   ```
+   
+   On Windows, use the following command:
+   
+   ```sh
+   cmake -G "MinGW Makefiles" -DOS_FSFW=freertos -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
+   ```
+   
+   The build configuration can also be performed with the shell scripts located inside 
+   `cmake/scripts/RTEMS` or the Python helper script `cmake_build_config.py` inside 
+   `cmake/scripts`.
+   
+5. Build the application
+   
+   ```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
+
+Building a software for RTEMS generally requires building a cross-compiler toolchain for the target
+architecture first and then building a board or chip specific BSP. 
+The [RTEMS QuickStart Guide](https://docs.rtems.org/branches/master/user/start/index.html)
+specifies the general steps required to build a BSP. The following steps will show how
+to build the `arm/stm32h7` BSP required for the STM32H743ZI-Nucleo board. It is recommended to
+build the BSP on Linux because the build process in Windows has proven problematic
+numerous times. On Windows, it is recommended to download a pre-compiled tool suite or
+build cross-compile the toolchain for Windows on a Linux system. The BSP build process with `waf`
+should work on both OSes without issues.
+
+For Linux, it is recommended you clone and follow the steps specified in this 
+[respository](https://github.com/rmspacefish/rtems-tools). In any case, it is recommended
+to use [this fork](https://github.com/rmspacefish/rtems/tree/mueller/master) to build the BSP
+from the RTEMS sources because it contains important fixes for the relatively new `stm32h7` BSP.
+
+You can also download the pre-compiled toolchains from 
+[here](https://drive.google.com/drive/folders/15pO3FCUwceghrnYjmNlgC6K1Z8D_6iu2?usp=sharing)
+
+## Setting up Eclipse for comfortable development
+
+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.
+
+It is recommended to use the given project files which include a RTEMS configuration 
+which only requires a few steps to work properly. When using the project files,
+go to the project properties → C/C++ Build → Build Variables and adapt the
+build variable `RTEMS_PREFIX` to point to your RTEMS prefix location, for example
+`$HOME/RTEMS/rtems-tools/rtems/6`. After that, Eclipse should be able to autodetermine the 
+BSP specific include paths. 
+
+## 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 (most reliable): 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
+   }
+   ```