fsfw-example-stm32h7-rtems/README.md

238 lines
9.6 KiB
Markdown
Raw Normal View History

2021-07-15 16:55:08 +02:00
<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
2021-07-15 16:57:51 +02:00
This demo can be run on a STM32H743ZI-Nucleo board with the RTEMS OSAL.
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
## General information
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
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.
2021-07-15 16:55:08 +02:00
2021-07-16 13:54:28 +02:00
## Prerequisites
See [Prerequisites](#prereq) for detailed instructions on how to set them up.
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
1. [RTEMS BSP](https://docs.rtems.org/branches/master/user/bsps/bsps-arm.html#id25)
`arm/stm32h7` installed (`arm-rtems6`)
2021-07-16 13:54:28 +02:00
2. [RTEMS LwIP support](https://github.com/rmspacefish/rtems-lwip) installed for networking.
It is recommended to generate a build folder first because this will generate the required
`lwipopts.h` file.
3. [MinGW64](https://www.msys2.org/) or [Ninja Build](https://ninja-build.org/) installed on Windows.
2021-07-15 16:55:08 +02:00
Not required on Linux.
2021-07-16 13:54:28 +02:00
4. Recommended for application code development:
2021-07-15 16:55:08 +02:00
[Eclipse for C/C++](https://www.eclipse.org/downloads/packages/) installed with the Eclipse MCU
plugin
2021-07-16 13:54:28 +02:00
5. [OpenOCD](https://xpack.github.io/openocd/) installed for Eclipse debugging
6. STM32 USB drivers installed
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
# Building the software with CMake
2021-07-15 16:55:08 +02:00
On Windows, the following steps should be performed inside the MinGW64 console
2021-07-15 16:57:51 +02:00
after installing MSYS2. It is recommended to still use git for Windows for the git
related steps.
2021-07-15 16:55:08 +02:00
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
```
2021-07-15 16:57:51 +02:00
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:
2021-07-15 16:55:08 +02:00
```sh
2021-07-15 16:57:51 +02:00
arm-rtems6-gcc --version
2021-07-15 16:55:08 +02:00
```
Now we will create the build configuration for cross-compilation of an ARM target.
2021-07-15 16:57:51 +02:00
On Linux, run the following command:
2021-07-15 16:55:08 +02:00
```sh
2021-07-15 16:57:51 +02:00
cmake -G "Unix Makefiles" -DOS_FSFW=rtems -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
2021-07-15 16:55:08 +02:00
```
2021-07-15 16:57:51 +02:00
On Windows, use the following command:
2021-07-15 16:55:08 +02:00
```sh
2021-07-15 16:57:51 +02:00
cmake -G "MinGW Makefiles" -DOS_FSFW=rtems -DCMAKE_BUILD_TYPE=Debug -DTGT_BSP=arm/stm32h743zi-nucleo ..
2021-07-15 16:55:08 +02:00
```
The build configuration can also be performed with the shell scripts located inside
2021-07-15 16:57:51 +02:00
`cmake/scripts/RTEMS` or the Python helper script `cmake_build_config.py` inside
2021-07-15 16:55:08 +02:00
`cmake/scripts`.
2021-07-15 16:57:51 +02:00
5. Build the application
2021-07-15 16:55:08 +02:00
```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.
2021-07-16 13:54:28 +02:00
# <a id="prereq"></a> Setting up the prerequisites
## Setting up RTEMS
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
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/nucleo-h743zi` 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.
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
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
`arm/nucleo-h743zi` BSP.
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
You can also download the pre-compiled toolchains from
[here](https://drive.google.com/drive/folders/15pO3FCUwceghrnYjmNlgC6K1Z8D_6iu2?usp=sharing)
2021-07-15 16:55:08 +02:00
2021-07-16 13:54:28 +02:00
## Installing LwIP for RTEMS
If you have not installed lwIP for RTEMS yet, you need to do it once.
Installing it requires two variables:
- `LWIP_OPTS_PATH`: Path to the `lwiptops.h`. This path will usually be the build folder after
CMake build generation, for example `build-Debug` for a Debug build
- `RTEMS_PREFIX`: RTEMS prefix. The lwIP support will be installed there, and the prefix should
be the same location used when installing the RTEMS BSP
- `RTEMS_BSP`: RTEMS BSP being used
You can install the lwIP support like this
```sh
export RTEMS_PREFIX=<pathToRtemsPrefix>
cd build-Debug
export LWIP_OPTS_PATH=$(pwd)
2021-07-16 14:40:22 +02:00
cd ..
cd cmake/rtems-lwip
2021-07-16 13:54:28 +02:00
./waf configure --prefix=$RTEMS_PREFIX --lwip-opts=$LWIP_OPTS_PATH --rtems-bsp=arm/nucleo-h743zi
./waf
./waf install
```
This will install the required headers and `liblwip.a` at the specified prefix so you can
use them when building RTEMS applications.
## Installing the USB drivers for the STM32
### Windows
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
You can install the [STM32 USB drivers](https://www.st.com/en/development-tools/stsw-link009.html)
2021-07-15 16:55:08 +02:00
2021-07-16 13:54:28 +02:00
### Linux
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
You can install the STM32 USB drivers on Ubuntu with the following command
2021-07-15 16:55:08 +02:00
```sh
sudo apt-get install stlink-tools
```
2021-07-15 16:57:51 +02:00
# Setting up Eclipse for comfortable development
2021-07-15 16:55:08 +02:00
The separate [Eclipse README](README-eclipse#top) specifies how to set up Eclipse.
2021-07-15 16:57:51 +02:00
The STM32 configuration uses the xPacks OpenOCD and the xPacks ARM Toolchain, so those should be
2021-07-15 16:55:08 +02:00
installed as well. OpenOCD should be configured correctly in the STM32 launch configurations.
2021-07-15 16:57:51 +02:00
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 &rarr; C/C++ Build &rarr; 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
2021-07-15 16:55:08 +02:00
2021-07-15 16:57:51 +02:00
## OpenOCD errors
2021-07-15 16:55:08 +02:00
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.
2021-07-15 16:57:51 +02:00
3. Third way (most reliable): Add the following lines to the `stm32h7x.cfg` file located inside
the OpenOCD folder inside the `scripts/target` folder:
2021-07-15 16:55:08 +02:00
```sh
2021-07-15 16:57:51 +02:00
$_CHIPNAME.cpu0 configure -event gdb-attach {
2021-07-15 16:55:08 +02:00
halt
}
2021-07-15 16:57:51 +02:00
$_CHIPNAME.cpu0 configure -event gdb-attach {
2021-07-15 16:55:08 +02:00
reset init
}
```