diff --git a/README.md b/README.md index 7094e5dc0..3cf20d57b 100644 --- a/README.md +++ b/README.md @@ -1,208 +1 @@ -![FSFW Logo](misc/logo/FSFW_Logo_V3_bw.png) - -# Flight Software Framework (FSFW) - -The Flight Software Framework is a C++ Object Oriented Framework for unmanned, -automated systems like Satellites. - -The initial version of the Flight Software Framework was developed during -the Flying Laptop Project by the University of Stuttgart in cooperation -with Airbus Defence and Space GmbH. - -## Quick facts - -The framework is designed for systems, which communicate with external devices, perform control loops, -receive telecommands and send telemetry, and need to maintain a high level of availability. Therefore, -a mode and health system provides control over the states of the software and the controlled devices. -In addition, a simple mechanism of event based fault detection, isolation and recovery is implemented as well. - -The FSFW provides abstraction layers for operating systems to provide a uniform operating system -abstraction layer (OSAL). Some components of this OSAL are required internally by the FSFW but is -also very useful for developers to implement the same application logic on different operating -systems with a uniform interface. - -Currently, the FSFW provides the following OSALs: - -- Linux -- Host -- FreeRTOS -- RTEMS - -The recommended hardware is a microprocessor with more than 1 MB of RAM and 1 MB of non-volatile -memory. For reference, current applications use a Cobham Gaisler UT699 (LEON3FT), a -ISISPACE IOBC or a Zynq-7020 SoC. The `fsfw` was also successfully run on the -STM32H743ZI-Nucleo board and on a Raspberry Pi and is currently running on the active -satellite mission Flying Laptop. - -## Getting started - -The [Hosted FSFW example](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted) provides a -good starting point and a demo to see the FSFW capabilities. -It is recommended to get started by building and playing around with the demo application. -There are also other examples provided for all OSALs using the popular embedded platforms -Raspberry Pi, Beagle Bone Black and STM32H7. - -Generally, the FSFW is included in a project by providing -a configuration folder, building the static library and linking against it. -There are some functions like `printChar` which are different depending on the target architecture -and need to be implemented by the mission developer. - -A template configuration folder was provided and can be copied into the project root to have -a starting point. The [configuration section](docs/README-config.md#top) provides more specific -information about the possible options. - -## Prerequisites - -The Embedded Template Library (etl) is a dependency of the FSFW which is automatically -installed and provided by the build system unless the correction version was installed. -The current recommended version can be found inside the fsfw `CMakeLists.txt` file or by using -`ccmake` and looking up the `FSFW_ETL_LIB_MAJOR_VERSION` variable. - -You can install the ETL library like this. On Linux, it might be necessary to add `sudo` before -the install call: - -```cpp -git clone https://github.com/ETLCPP/etl -cd etl -git checkout -mkdir build && cd build -cmake .. -cmake --install . -``` - -It is recommended to install `20.27.2` or newer for the package version handling of -ETL to work. - -## Adding the library - -The following steps show how to add and use FSFW components. It is still recommended to -try out the example mentioned above to get started, but the following steps show how to -add and link against the FSFW library in general. - -1. Add this repository as a submodule - - ```sh - git submodule add https://egit.irs.uni-stuttgart.de/fsfw/fsfw.git fsfw - ``` - -2. Add the following directive inside the uppermost `CMakeLists.txt` file of your project - - ```cmake - add_subdirectory(fsfw) - ``` - -3. Make sure to provide a configuration folder and supply the path to that folder with - the `FSFW_CONFIG_PATH` CMake variable from the uppermost `CMakeLists.txt` file. - It is also necessary to provide the `printChar` function. You can find an example - implementation for a hosted build - [here](https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted/src/branch/master/bsp_hosted/utility/printChar.c). - -4. Link against the FSFW library - - ```sh - target_link_libraries(${YourProjectName} PRIVATE fsfw) - ``` - -5. It should now be possible use the FSFW as a static library from the user code. - -## Building the unittests - -The FSFW also has unittests which use the [Catch2 library](https://github.com/catchorg/Catch2). -These are built by setting the CMake option `FSFW_BUILD_UNITTESTS` to `ON` or `TRUE` -from your project `CMakeLists.txt` file or from the command line. - -You can install the Catch2 library, which prevents the build system to avoid re-downloading -the dependency if the unit tests are completely rebuilt. The current recommended version -can be found inside the fsfw `CMakeLists.txt` file or by using `ccmake` and looking up -the `FSFW_CATCH2_LIB_VERSION` variable. - -```sh -git clone https://github.com/catchorg/Catch2.git -cd Catch2 -git checkout -cmake -Bbuild -H. -DBUILD_TESTING=OFF -sudo cmake --build build/ --target install -``` - -The fsfw-tests binary will be built as part of the static library and dropped alongside it. -If the unittests are built, the library and the tests will be built with coverage information by -default. This can be disabled by setting the `FSFW_TESTS_COV_GEN` option to `OFF` or `FALSE`. - -You can use the following commands inside the `fsfw` folder to set up the build system - -```sh -mkdir build-tests && cd build-tests -cmake -DFSFW_BUILD_TESTS=ON -DFSFW_OSAL=host -DCMAKE_BUILD_TYPE=Debug .. -``` - -You can also use `-DFSFW_OSAL=linux` on Linux systems. - -Coverage data in HTML format can be generated using the `CodeCoverage` -[CMake module](https://github.com/bilke/cmake-modules/tree/master). -To build the unittests, run them and then generate the coverage data in this format, -the following command can be used inside the build directory after the build system was set up - -```sh -cmake --build . -- fsfw-tests_coverage -j -``` - -The `coverage.py` script located in the `script` folder can also be used to do this conveniently. - -## Building the documentations - -The FSFW documentation is built using the tools Sphinx, doxygen and breathe based on the -instructions provided in [this blogpost](https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/). If you -want to do this locally, set up the prerequisites first. This requires a ``python3`` -installation as well. Example here is for Ubuntu. - -```sh -sudo apt-get install doxygen graphviz -``` - -And the following Python packages - -```sh -python3 -m pip install sphinx breathe -``` - -You can set up a documentation build system using the following commands - -```sh -mkdir build-docs && cd build-docs -cmake -DFSFW_BUILD_DOCS=ON -DFSFW_OSAL=host .. -``` - -Then you can generate the documentation using - -```sh -cmake --build . -- Sphinx -j -``` - -You can find the generated documentation inside the `docs/sphinx` folder inside the build -folder. Simply open the `index.html` in the webbrowser of your choice. - -The `helper.py` script located in the script` folder can also be used to create, build -and open the documentation conveniently. Try `helper.py -h for more information. - -## Formatting the sources - -The formatting is done by the `clang-format` tool. The configuration is contained within the -`.clang-format` file in the repository root. As long as `clang-format` is installed, you -can run the `auto-format.sh` helper script to format all source files consistently. Furthermore cmake-format is required to format CMake files which can be installed with: -````sh -sudo pip install cmakelang -```` - -## Index - -[1. High-level overview](docs/README-highlevel.md#top)
-[2. Core components](docs/README-core.md#top)
-[3. Configuration](docs/README-config.md#top)
-[4. OSAL overview](docs/README-osal.md#top)
-[5. PUS services](docs/README-pus.md#top)
-[6. Device Handler overview](docs/README-devicehandlers.md#top)
-[7. Controller overview](docs/README-controllers.md#top)
-[8. Local Data Pools](docs/README-localpools.md#top)
- - - +- \ No newline at end of file