diff --git a/README.md b/README.md new file mode 100644 index 0000000..5272f0a --- /dev/null +++ b/README.md @@ -0,0 +1,232 @@ + + +# 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)
+[Getting started with CMake](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-common/src/branch/master/doc/README-cmake.md)
+ +[Getting started with the Hosted OSAL](#this)
+[Getting started with the FreeRTOS OSAL on a STM32](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-stm32h7-freertos)
+[Getting started with the RTEMS OSAL on a STM32](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-stm32h7-rtems)
+[Getting started with the Raspberry Pi](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)
+[Getting started with the Beagle Bone Black](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu)
+ +# 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 + + ```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 +``` + +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` 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:"" + ``` + + 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. + +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 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 + } + ``` diff --git a/example_common b/example_common index 0901604..ff6025d 160000 --- a/example_common +++ b/example_common @@ -1 +1 @@ -Subproject commit 090160485498a92fdf896ad74ffd97f768a4a269 +Subproject commit ff6025d04d2b3abd278d909c2844bd808bee06b4