316 lines
11 KiB
Markdown
316 lines
11 KiB
Markdown
<img align="center" src="https://egit.irs.uni-stuttgart.de/fsfw/fsfw/raw/branch/development/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](https://openocd.org/) 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.
|
|
|
|
## Prerequisites
|
|
|
|
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:
|
|
[Eclipse for C/C++](https://www.eclipse.org/downloads/packages/) installed with the Eclipse MCU
|
|
plugin
|
|
5. [OpenOCD](https://xpack.github.io/openocd/) installed for Eclipse debugging
|
|
6. 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-stm32h7-freertos
|
|
```
|
|
|
|
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 cmake-build-debug
|
|
cd cmake-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.
|
|
|
|
## <a id="prereq"></a> Setting up Prerequisites
|
|
|
|
### CMake
|
|
|
|
**Linux**
|
|
|
|
```sh
|
|
sudo apt-get install cmake
|
|
```
|
|
|
|
**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
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
```sh
|
|
npm install --global xpm@latest
|
|
xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@11.2.1-1.1.1 --verbose
|
|
```
|
|
|
|
On Windows, the toolchain binaries will be located in a folder like this
|
|
|
|
```sh
|
|
C:\Users\<User>\AppData\Roaming\xPacks\@xpack-dev-tools\arm-none-eabi-gcc\<version>\.content\bin
|
|
```
|
|
|
|
You can now run the following commands in the repository root:
|
|
|
|
```sh
|
|
xpm init
|
|
xpm install @xpack-dev-tools/arm-none-eabi-gcc@11.2.1-1.1.1
|
|
```
|
|
|
|
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
|
|
|
|
```sh
|
|
export PATH="$(pwd)/xpacks/.bin":$PATH
|
|
```
|
|
|
|
On Windows, you can use git bash to perform the step above.
|
|
|
|
Alternatively, 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` variable.
|
|
|
|
**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
|
|
xpm install --global @xpack-dev-tools/arm-none-eabi-gcc@11.2.1-1.1.1 --verbose
|
|
```
|
|
|
|
You can now run the following commands in the repository root:
|
|
|
|
```sh
|
|
xpm init
|
|
xpm install @xpack-dev-tools/arm-none-eabi-gcc@11.2.1-1.1.1
|
|
```
|
|
|
|
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
|
|
|
|
```sh
|
|
export PATH="$(pwd)/xpacks/.bin":$PATH
|
|
```
|
|
|
|
### 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**
|
|
|
|
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
|
|
}
|
|
```
|