fsfw-example-stm32h7-freertos/README.md

315 lines
11 KiB
Markdown
Raw Normal View History

2022-05-22 16:23:08 +02:00
<img align="center" src="https://egit.irs.uni-stuttgart.de/fsfw/fsfw/raw/branch/development/misc/logo/FSFW_Logo_V3_bw.png" width="50%">
2021-07-12 21:36:57 +02:00
# <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.
2022-05-22 16:23:08 +02:00
## Prerequisites
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
If you have not set up the prerequisites yet, go to the [prerequisites chapter](#prereq) for
detailed instructions on how to install these.
Here is a brief overview of the required tools to develop software for the STM32H7 microcontroller:
1. CMake build system generator installed
2. Build system like [Ninja Build](https://ninja-build.org/) or [Make](https://www.msys2.org/)
installed.
3. Bare-Metal ARM toolchain installed
4. Recommended for application code development:
2021-07-12 21:36:57 +02:00
[Eclipse for C/C++](https://www.eclipse.org/downloads/packages/) installed with the Eclipse MCU
plugin
2022-05-22 16:23:08 +02:00
5. [OpenOCD](https://xpack.github.io/openocd/) installed for Eclipse debugging
6. STM32 USB drivers installed, separate steps for
2021-07-12 21:36:57 +02:00
[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
2022-05-22 15:32:21 +02:00
git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-stm32h7-freertos
2021-07-12 21:36:57 +02:00
```
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
2022-05-22 15:32:21 +02:00
mkdir cmake-build-debug
cd cmake-build-debug
2021-07-12 21:36:57 +02:00
```
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
2021-07-12 21:41:07 +02:00
the Unix Makefile generator. You can also specify `-G Ninja` to use Ninja instead
of Make.
2021-07-12 21:36:57 +02:00
```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.
2022-05-22 16:24:05 +02:00
## <a id="prereq"></a> Setting up Prerequisites
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
### CMake
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
**Linux**
2021-07-12 21:36:57 +02:00
```sh
2022-05-22 16:23:08 +02:00
sudo apt-get install cmake
2021-07-12 21:36:57 +02:00
```
2022-05-22 16:23:08 +02:00
**Windows**
On Windows, you can use `pacman -S mingw-w64-x86_64-cmake`, but you can also install the Windows
CMake via the [installer](https://cmake.org/download/). It is recommended to pick the install
option `Add CMake to system PATH for all users` to CMake can be used from the command line.
Please note that you need to add the Windows CMake path to the MinGW64 path manually
if you want to use it in CMake.
### Cross-Compiler
2022-05-22 16:27:28 +02:00
The instuctions here specify how to install and use a specific version of the
[xPacks cross-compiler](https://xpack.github.io/arm-none-eabi-gcc/) but you can use any other
ARM cross-compiler which can generate bare-metal code, usually denoted by the `arm-none-eabi`
cross-compiler triplet.
2022-05-22 16:23:08 +02:00
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).
**Windows**
On Windows, it is recommended to perform the `xpm` and toolchain installation from the Windows
command line.The simple way required npm, which can be installed by installing
[NodeJS](https://nodejs.org/en/). Make sure `npm` can be run from the command line by adding
the folder containing `npm.exe` to the system path and running the following command
2021-07-12 21:36:57 +02:00
```sh
2022-05-22 16:23:08 +02:00
npm install --global xpm@latest
2022-05-22 16:28:48 +02:00
xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@11.2.1-1.1.1 --verbose
2021-07-12 21:36:57 +02:00
```
2022-05-22 16:23:08 +02:00
On Windows, the toolchain binaries will be located in a folder like this
2021-07-12 21:41:07 +02:00
2022-05-22 16:23:08 +02:00
```sh
C:\Users\<User>\AppData\Roaming\xPacks\@xpack-dev-tools\arm-none-eabi-gcc\<version>\.content\bin
```
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
You can now run the following commands in the repository root:
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
```sh
xpm init
2022-05-22 16:28:48 +02:00
xpm install @xpack-dev-tools/arm-none-eabi-gcc@11.2.1-1.1.1
2022-05-22 16:23:08 +02:00
```
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
to create symlinks to the toolchain in `./xpacks/.bin`.
You can now set up the environment by using `. load_path.sh` or the following command
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
```sh
export PATH="$(pwd)/xpacks/.bin":$PATH
```
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
On Windows, you can use the graphical system environmental variables editor to add the
`.bin` path to the system variables permanently or use the appriate command for `CMD` or
PowerShell to update the `PATH`
2021-07-12 21:36:57 +02:00
2022-05-22 16:23:08 +02:00
**Linux**
Install `npm` and `nodejs` first. Example for Ubuntu according to
[this guide](https://linuxize.com/post/how-to-install-node-js-on-ubuntu-20-04/).
```sh
curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get update && sudo apt-get install nodejs
```
Check that `npm` is installed with `npm --version`.
Then `xpm` and the cross-compiler are installed.
```sh
sudo npm install --global xpm@latest
2022-05-22 16:28:48 +02:00
xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@11.2.1-1.1.1 --verbose
2022-05-22 16:23:08 +02:00
```
You can now run the following commands in the repository root:
```sh
xpm init
2022-05-22 16:28:48 +02:00
xpm install @xpack-dev-tools/arm-none-eabi-gcc@11.2.1-1.1.1
2022-05-22 16:23:08 +02:00
```
to create symlinks to the toolchain in `./xpacks/.bin`.
You can now set up the environment by using `. load_path.sh` or the following command
2021-07-12 21:36:57 +02:00
```sh
2022-05-22 16:23:08 +02:00
export PATH="$(pwd)/xpacks/.bin":$PATH
2021-07-12 21:36:57 +02:00
```
2022-05-22 16:23:08 +02:00
### Build System
It is recommended to use `ninja` or `make` as the software build system.
**Windows**
It is recommended to use the [Ninja build system](https://ninja-build.org/). Download the ninja
executable and place it somewhere.
You need to add the folder containing the ninja executable to the system environmental variables
so it can be used in the build process. You can test whether `ninja` works by running
`ninja --version` in the command line.
Alternatively or additionally, you can also install `mingw32-make`
which comes bundled with [MinGW64](https://www.msys2.org/). Make sure to add the binaries path to
the Windows path during installation. Otherwise, you need to add `msys64/mingw64/bin` to the
Windows path so you can run installed binaries from the command line.
Open the `MinGW64` shell and run the following commands.
```sh
pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-make mingw-w64-x86_64-cmake
```
You can test successfull installation with `mingw32-make -v` from the Windows Command Line.
**Linux**
On Linux, `make` is pre-installed and it is recommended to use it directly.
You can install `ninja` with
```sh
sudo apt-get install ninja-build
```
### USB Drivers
**Windows**
Install the [STM32 USB drivers](https://www.st.com/en/development-tools/stsw-link009.html).
**Linux**
2021-07-14 13:38:07 +02:00
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
```
2021-07-12 21:36:57 +02:00
## 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
}
```