Merge remote-tracking branch 'upstream/development' into mueller/cfdp-pdus
This commit is contained in:
commit
602fa3a956
@ -4,6 +4,9 @@ set(FSFW_VERSION 2)
|
||||
set(FSFW_SUBVERSION 0)
|
||||
set(FSFW_REVISION 0)
|
||||
|
||||
# Add the cmake folder so the FindSphinx module is found
|
||||
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
|
||||
|
||||
option(FSFW_GENERATE_SECTIONS
|
||||
"Generate function and data sections. Required to remove unused code" ON
|
||||
)
|
||||
@ -12,6 +15,7 @@ if(FSFW_GENERATE_SECTIONS)
|
||||
endif()
|
||||
|
||||
option(FSFW_BUILD_UNITTESTS "Build unittest binary in addition to static library" OFF)
|
||||
option(FSFW_BUILD_DOCS "Build documentation with Sphinx and Doxygen" OFF)
|
||||
if(FSFW_BUILD_UNITTESTS)
|
||||
option(FSFW_TESTS_GEN_COV "Generate coverage data for unittests" ON)
|
||||
endif()
|
||||
@ -36,7 +40,9 @@ option(FSFW_ADD_SGP4_PROPAGATOR "Add SGP4 propagator code" OFF)
|
||||
|
||||
set(LIB_FSFW_NAME fsfw)
|
||||
set(FSFW_TEST_TGT fsfw-tests)
|
||||
set(FSFW_DUMMY_TGT fsfw-dummy)
|
||||
|
||||
project(${LIB_FSFW_NAME})
|
||||
add_library(${LIB_FSFW_NAME})
|
||||
|
||||
if(FSFW_BUILD_UNITTESTS)
|
||||
@ -59,7 +65,6 @@ if(FSFW_BUILD_UNITTESTS)
|
||||
set(FSFW_CONFIG_PATH tests/src/fsfw_tests/unit/testcfg)
|
||||
configure_file(tests/src/fsfw_tests/unit/testcfg/FSFWConfig.h.in FSFWConfig.h)
|
||||
configure_file(tests/src/fsfw_tests/unit/testcfg/TestsConfig.h.in tests/TestsConfig.h)
|
||||
configure_file(tests/src/fsfw_tests/unit/testcfg/OBSWConfig.h.in OBSWConfig.h)
|
||||
|
||||
project(${FSFW_TEST_TGT} CXX C)
|
||||
add_executable(${FSFW_TEST_TGT})
|
||||
@ -147,7 +152,7 @@ else()
|
||||
set(OS_FSFW "host")
|
||||
endif()
|
||||
|
||||
if(FSFW_BUILD_UNITTESTS)
|
||||
if(FSFW_BUILD_UNITTESTS OR FSFW_BUILD_DOCS)
|
||||
configure_file(src/fsfw/FSFW.h.in fsfw/FSFW.h)
|
||||
configure_file(src/fsfw/FSFWVersion.h.in fsfw/FSFWVersion.h)
|
||||
else()
|
||||
@ -163,6 +168,9 @@ if(FSFW_ADD_HAL)
|
||||
add_subdirectory(hal)
|
||||
endif()
|
||||
add_subdirectory(contrib)
|
||||
if(FSFW_BUILD_DOCS)
|
||||
add_subdirectory(docs)
|
||||
endif()
|
||||
|
||||
if(FSFW_BUILD_UNITTESTS)
|
||||
if(FSFW_TESTS_GEN_COV)
|
||||
@ -234,9 +242,11 @@ endif()
|
||||
# The project CMakeLists file has to set the FSFW_CONFIG_PATH and add it.
|
||||
# If this is not given, we include the default configuration and emit a warning.
|
||||
if(NOT FSFW_CONFIG_PATH)
|
||||
message(WARNING "Flight Software Framework configuration path not set!")
|
||||
set(DEF_CONF_PATH misc/defaultcfg/fsfwconfig)
|
||||
message(WARNING "Setting default configuration from ${DEF_CONF_PATH} ..")
|
||||
if(NOT FSFW_BUILD_DOCS)
|
||||
message(WARNING "Flight Software Framework configuration path not set!")
|
||||
message(WARNING "Setting default configuration from ${DEF_CONF_PATH} ..")
|
||||
endif()
|
||||
add_subdirectory(${DEF_CONF_PATH})
|
||||
set(FSFW_CONFIG_PATH ${DEF_CONF_PATH})
|
||||
endif()
|
||||
|
18
README.md
18
README.md
@ -42,7 +42,7 @@ There are some functions like `printChar` which are different depending on the t
|
||||
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](doc/README-config.md#top) provides more specific
|
||||
a starting point. The [configuration section](docs/README-config.md#top) provides more specific
|
||||
information about the possible options.
|
||||
|
||||
## Adding the library
|
||||
@ -109,14 +109,14 @@ The `coverage.py` script located in the `script` folder can also be used to do t
|
||||
|
||||
## Index
|
||||
|
||||
[1. High-level overview](doc/README-highlevel.md#top) <br>
|
||||
[2. Core components](doc/README-core.md#top) <br>
|
||||
[3. Configuration](doc/README-config.md#top) <br>
|
||||
[4. OSAL overview](doc/README-osal.md#top) <br>
|
||||
[5. PUS services](doc/README-pus.md#top) <br>
|
||||
[6. Device Handler overview](doc/README-devicehandlers.md#top) <br>
|
||||
[7. Controller overview](doc/README-controllers.md#top) <br>
|
||||
[8. Local Data Pools](doc/README-localpools.md#top) <br>
|
||||
[1. High-level overview](docs/README-highlevel.md#top) <br>
|
||||
[2. Core components](docs/README-core.md#top) <br>
|
||||
[3. Configuration](docs/README-config.md#top) <br>
|
||||
[4. OSAL overview](docs/README-osal.md#top) <br>
|
||||
[5. PUS services](docs/README-pus.md#top) <br>
|
||||
[6. Device Handler overview](docs/README-devicehandlers.md#top) <br>
|
||||
[7. Controller overview](docs/README-controllers.md#top) <br>
|
||||
[8. Local Data Pools](docs/README-localpools.md#top) <br>
|
||||
|
||||
|
||||
|
||||
|
13
cmake/FindSphinx.cmake
Normal file
13
cmake/FindSphinx.cmake
Normal file
@ -0,0 +1,13 @@
|
||||
# Look for an executable called sphinx-build
|
||||
find_program(SPHINX_EXECUTABLE
|
||||
NAMES sphinx-build
|
||||
DOC "Path to sphinx-build executable")
|
||||
|
||||
include(FindPackageHandleStandardArgs)
|
||||
|
||||
# Handle standard arguments to find_package like REQUIRED and QUIET
|
||||
find_package_handle_standard_args(
|
||||
Sphinx
|
||||
"Failed to find sphinx-build executable"
|
||||
SPHINX_EXECUTABLE
|
||||
)
|
66
docs/CMakeLists.txt
Normal file
66
docs/CMakeLists.txt
Normal file
@ -0,0 +1,66 @@
|
||||
# This is based on this excellent posting provided by Sy:
|
||||
# https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
|
||||
find_package(Doxygen REQUIRED)
|
||||
find_package(Sphinx REQUIRED)
|
||||
|
||||
get_target_property(LIB_FSFW_PUBLIC_HEADER_DIRS ${LIB_FSFW_NAME} INTERFACE_INCLUDE_DIRECTORIES)
|
||||
# TODO: Add HAL as well
|
||||
file(GLOB_RECURSE LIB_FSFW_PUBLIC_HEADERS ${PROJECT_SOURCE_DIR}/src/*.h)
|
||||
file(GLOB_RECURSE RST_DOC_FILES ${PROJECT_SOURCE_DIR}/docs/*.rst)
|
||||
|
||||
set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src)
|
||||
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
|
||||
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
|
||||
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
|
||||
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
|
||||
|
||||
# Replace variables inside @@ with the current values
|
||||
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
|
||||
|
||||
# Doxygen won't create this for us
|
||||
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
|
||||
|
||||
# Only regenerate Doxygen when the Doxyfile or public headers change
|
||||
add_custom_command(
|
||||
OUTPUT ${DOXYGEN_INDEX_FILE}
|
||||
DEPENDS ${LIB_FSFW_PUBLIC_HEADERS}
|
||||
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
|
||||
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
|
||||
COMMENT "Generating docs"
|
||||
VERBATIM
|
||||
)
|
||||
|
||||
# Nice named target so we can run the job easily
|
||||
add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
|
||||
|
||||
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
|
||||
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
|
||||
set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
|
||||
|
||||
# Only regenerate Sphinx when:
|
||||
# - Doxygen has rerun
|
||||
# - Our doc files have been updated
|
||||
# - The Sphinx config has been updated
|
||||
add_custom_command(
|
||||
OUTPUT ${SPHINX_INDEX_FILE}
|
||||
COMMAND
|
||||
${SPHINX_EXECUTABLE} -b html
|
||||
# Tell Breathe where to find the Doxygen output
|
||||
-Dbreathe_projects.fsfw=${DOXYGEN_OUTPUT_DIR}/xml
|
||||
${SPHINX_SOURCE} ${SPHINX_BUILD}
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
DEPENDS
|
||||
# Other docs files you want to track should go here (or in some variable)
|
||||
${RST_DOC_FILES}
|
||||
${DOXYGEN_INDEX_FILE}
|
||||
MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
|
||||
COMMENT "Generating documentation with Sphinx"
|
||||
)
|
||||
|
||||
# Nice named target so we can run the job easily
|
||||
add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE})
|
||||
|
||||
# Add an install target to install the docs
|
||||
include(GNUInstallDirs)
|
||||
install(DIRECTORY ${SPHINX_BUILD}
|
||||
DESTINATION ${CMAKE_INSTALL_DOCDIR})
|
7
docs/Doxyfile.in
Normal file
7
docs/Doxyfile.in
Normal file
@ -0,0 +1,7 @@
|
||||
INPUT = "@DOXYGEN_INPUT_DIR@"
|
||||
|
||||
RECURSIVE = YES
|
||||
|
||||
OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIR@"
|
||||
|
||||
GENERATE_XML = YES
|
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
@ -31,7 +31,9 @@ cohesive pool variables. These sets simply iterator over the list of variables a
|
||||
`read` and `commit` functions of each variable. The following diagram shows the
|
||||
high-level architecture of the local data pools.
|
||||
|
||||
<img align="center" src="./images/PoolArchitecture.png" width="50%"> <br>
|
||||
.. image:: ../misc/logo/FSFW_Logo_V3_bw.png
|
||||
:alt: FSFW Logo
|
||||
|
||||
|
||||
An example is shown for using the local data pools with a Gyroscope.
|
||||
For example, the following code shows an implementation to access data from a Gyroscope taken
|
16
docs/api.rst
Normal file
16
docs/api.rst
Normal file
@ -0,0 +1,16 @@
|
||||
API
|
||||
====
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 4
|
||||
|
||||
api/objectmanager
|
||||
api/task
|
||||
api/ipc
|
||||
api/returnvalue
|
||||
api/event
|
||||
api/modes
|
||||
api/health
|
||||
api/action
|
||||
api/devicehandler
|
||||
api/controller
|
15
docs/api/action.rst
Normal file
15
docs/api/action.rst
Normal file
@ -0,0 +1,15 @@
|
||||
Action Module API
|
||||
=================
|
||||
|
||||
``ActionHelper``
|
||||
-----------------
|
||||
|
||||
.. doxygenclass:: ActionHelper
|
||||
:members:
|
||||
|
||||
``HasActionsIF``
|
||||
-----------------
|
||||
|
||||
.. doxygenclass:: HasActionsIF
|
||||
:members:
|
||||
:protected-members:
|
16
docs/api/controller.rst
Normal file
16
docs/api/controller.rst
Normal file
@ -0,0 +1,16 @@
|
||||
Controller API
|
||||
=================
|
||||
|
||||
``ControllerBase``
|
||||
-------------------------
|
||||
|
||||
.. doxygenclass:: ControllerBase
|
||||
:members:
|
||||
:protected-members:
|
||||
|
||||
``ExtendedControllerBase``
|
||||
-----------------------------
|
||||
|
||||
.. doxygenclass:: ExtendedControllerBase
|
||||
:members:
|
||||
:protected-members:
|
16
docs/api/devicehandler.rst
Normal file
16
docs/api/devicehandler.rst
Normal file
@ -0,0 +1,16 @@
|
||||
Device Handler Base API
|
||||
=========================
|
||||
|
||||
``DeviceHandlerBase``
|
||||
-----------------------
|
||||
|
||||
.. doxygenclass:: DeviceHandlerBase
|
||||
:members:
|
||||
:protected-members:
|
||||
|
||||
``DeviceHandlerIF``
|
||||
-----------------------
|
||||
|
||||
.. doxygenclass:: DeviceHandlerIF
|
||||
:members:
|
||||
:protected-members:
|
6
docs/api/event.rst
Normal file
6
docs/api/event.rst
Normal file
@ -0,0 +1,6 @@
|
||||
.. _eventapi:
|
||||
|
||||
Event API
|
||||
============
|
||||
|
||||
.. doxygenfile:: Event.h
|
9
docs/api/health.rst
Normal file
9
docs/api/health.rst
Normal file
@ -0,0 +1,9 @@
|
||||
Health API
|
||||
===========
|
||||
|
||||
``HasHealthIF``
|
||||
------------------
|
||||
|
||||
.. doxygenclass:: HasHealthIF
|
||||
:members:
|
||||
:protected-members:
|
9
docs/api/ipc.rst
Normal file
9
docs/api/ipc.rst
Normal file
@ -0,0 +1,9 @@
|
||||
IPC Module API
|
||||
=================
|
||||
|
||||
``MessageQueueIF``
|
||||
-------------------
|
||||
|
||||
.. doxygenclass:: MessageQueueIF
|
||||
:members:
|
||||
:protected-members:
|
10
docs/api/modes.rst
Normal file
10
docs/api/modes.rst
Normal file
@ -0,0 +1,10 @@
|
||||
Modes API
|
||||
=========
|
||||
|
||||
|
||||
``HasModesIF``
|
||||
---------------
|
||||
|
||||
.. doxygenclass:: HasModesIF
|
||||
:members:
|
||||
:protected-members:
|
30
docs/api/objectmanager.rst
Normal file
30
docs/api/objectmanager.rst
Normal file
@ -0,0 +1,30 @@
|
||||
Object Manager API
|
||||
=========================
|
||||
|
||||
``SystemObject``
|
||||
--------------------
|
||||
|
||||
.. doxygenclass:: SystemObject
|
||||
:members:
|
||||
:protected-members:
|
||||
|
||||
``ObjectManager``
|
||||
-----------------------
|
||||
|
||||
.. doxygenclass:: ObjectManager
|
||||
:members:
|
||||
:protected-members:
|
||||
|
||||
``SystemObjectIF``
|
||||
--------------------
|
||||
|
||||
.. doxygenclass:: SystemObjectIF
|
||||
:members:
|
||||
:protected-members:
|
||||
|
||||
``ObjectManagerIF``
|
||||
-----------------------
|
||||
|
||||
.. doxygenclass:: ObjectManagerIF
|
||||
:members:
|
||||
:protected-members:
|
10
docs/api/returnvalue.rst
Normal file
10
docs/api/returnvalue.rst
Normal file
@ -0,0 +1,10 @@
|
||||
.. _retvalapi:
|
||||
|
||||
Returnvalue API
|
||||
==================
|
||||
|
||||
.. doxygenfile:: HasReturnvaluesIF.h
|
||||
|
||||
.. _fwclassids:
|
||||
|
||||
.. doxygenfile:: FwClassIds.h
|
8
docs/api/task.rst
Normal file
8
docs/api/task.rst
Normal file
@ -0,0 +1,8 @@
|
||||
Task API
|
||||
=========
|
||||
|
||||
``ExecutableObjectIF``
|
||||
-----------------------
|
||||
|
||||
.. doxygenclass:: ExecutableObjectIF
|
||||
:members:
|
56
docs/conf.py
Normal file
56
docs/conf.py
Normal file
@ -0,0 +1,56 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'Flight Software Framework'
|
||||
copyright = '2021, Institute of Space Systems (IRS)'
|
||||
author = 'Institute of Space Systems (IRS)'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = '2.0.1'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [ "breathe" ]
|
||||
|
||||
breathe_default_project = "fsfw"
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'alabaster'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = []
|
41
docs/config.rst
Normal file
41
docs/config.rst
Normal file
@ -0,0 +1,41 @@
|
||||
Configuring the FSFW
|
||||
=====================
|
||||
|
||||
The FSFW can be configured via the ``fsfwconfig`` folder. A template folder has been provided in
|
||||
``misc/defaultcfg`` to have a starting point for this. The folder should be added
|
||||
to the include path. The primary configuration file is the ``FSFWConfig.h`` folder. Some
|
||||
of the available options will be explained in more detail here.
|
||||
|
||||
Auto-Translation of Events
|
||||
----------------------------
|
||||
|
||||
The FSFW allows the automatic translation of events, which allows developers to track triggered
|
||||
events directly via console output. Using this feature requires:
|
||||
|
||||
1. ``FSFW_OBJ_EVENT_TRANSLATION`` set to 1 in the configuration file.
|
||||
2. Special auto-generated translation files which translate event IDs and object IDs into
|
||||
human readable strings. These files can be generated using the
|
||||
`fsfwgen Python scripts <https://egit.irs.uni-stuttgart.de/fsfw/fsfw-gen>`_.
|
||||
3. The generated translation files for the object IDs should be named ``translatesObjects.cpp``
|
||||
and ``translateObjects.h`` and should be copied to the ``fsfwconfig/objects`` folder
|
||||
4. The generated translation files for the event IDs should be named ``translateEvents.cpp`` and
|
||||
``translateEvents.h`` and should be copied to the ``fsfwconfig/events`` folder
|
||||
|
||||
An example implementations of these translation file generators can be found as part
|
||||
of the `SOURCE project here <https://git.ksat-stuttgart.de/source/sourceobsw/-/tree/develop/generators>`_
|
||||
or the `FSFW example <https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted/src/branch/master/generators>`_
|
||||
|
||||
Configuring the Event Manager
|
||||
----------------------------------
|
||||
|
||||
The number of allowed subscriptions can be modified with the following
|
||||
parameters:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
namespace fsfwconfig {
|
||||
//! Configure the allocated pool sizes for the event manager.
|
||||
static constexpr size_t FSFW_EVENTMGMR_MATCHTREE_NODES = 240;
|
||||
static constexpr size_t FSFW_EVENTMGMT_EVENTIDMATCHERS = 120;
|
||||
static constexpr size_t FSFW_EVENTMGMR_RANGEMATCHERS = 120;
|
||||
}
|
2
docs/controllers.rst
Normal file
2
docs/controllers.rst
Normal file
@ -0,0 +1,2 @@
|
||||
Controllers
|
||||
=============
|
70
docs/core.rst
Normal file
70
docs/core.rst
Normal file
@ -0,0 +1,70 @@
|
||||
.. _core:
|
||||
|
||||
Core Modules
|
||||
=============
|
||||
|
||||
The core modules provide the most important functionalities of the Flight Software Framework.
|
||||
|
||||
Clock
|
||||
------
|
||||
|
||||
- This is a class of static functions that can be used at anytime
|
||||
- Leap Seconds must be set if any time conversions from UTC to other times is used
|
||||
|
||||
Object Manager
|
||||
---------------
|
||||
|
||||
- Must be created during program startup
|
||||
- The component which handles all references. All :cpp:class:`SystemObject`\s register at this
|
||||
component.
|
||||
- All :cpp:class:`SystemObject`\s needs to have a unique Object ID. Those can be managed like
|
||||
framework objects.
|
||||
- A reference to an object can be retrieved by calling the ``get`` function of
|
||||
:cpp:class:`ObjectManagerIF`. The target type must be specified as a template argument.
|
||||
A ``nullptr`` check of the returning pointer must be done. This function is based on
|
||||
run-time type information.
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
template <typename T> T* ObjectManagerIF::get(object_id_t id);
|
||||
|
||||
- A typical way to create all objects on startup is a handing a static produce function to the
|
||||
ObjectManager on creation. By calling ``ObjectManager::instance()->initialize(produceFunc)`` the
|
||||
produce function will be called and all :cpp:class:`SystemObject`\s will be initialized
|
||||
afterwards.
|
||||
|
||||
Event Manager
|
||||
---------------
|
||||
|
||||
- Component which allows routing of events
|
||||
- Other objects can subscribe to specific events, ranges of events or all events of an object.
|
||||
- Subscriptions can be done during runtime but should be done during initialization
|
||||
- Amounts of allowed subscriptions can be configured in ``FSFWConfig.h``
|
||||
|
||||
Health Table
|
||||
---------------
|
||||
|
||||
- A component which holds every health state
|
||||
- Provides a thread safe way to access all health states without the need of message exchanges
|
||||
|
||||
Stores
|
||||
--------------
|
||||
|
||||
- The message based communication can only exchange a few bytes of information inside the message
|
||||
itself. Therefore, additional information can be exchanged with Stores. With this, only the
|
||||
store address must be exchanged in the message.
|
||||
- Internally, the FSFW uses an IPC Store to exchange data between processes. For incoming TCs a TC
|
||||
Store is used. For outgoing TM a TM store is used.
|
||||
- All of them should use the Thread Safe Class storagemanager/PoolManager
|
||||
|
||||
Tasks
|
||||
---------
|
||||
|
||||
There are two different types of tasks:
|
||||
|
||||
- The PeriodicTask just executes objects that are of type ExecutableObjectIF in the order of the
|
||||
insertion to the Tasks.
|
||||
- FixedTimeslotTask executes a list of calls in the order of the given list. This is intended for
|
||||
DeviceHandlers, where polling should be in a defined order. An example can be found in
|
||||
``defaultcfg/fsfwconfig/pollingSequence`` folder
|
||||
|
3
docs/devicehandlers.rst
Normal file
3
docs/devicehandlers.rst
Normal file
@ -0,0 +1,3 @@
|
||||
Device Handlers
|
||||
==================
|
||||
|
115
docs/getting_started.rst
Normal file
115
docs/getting_started.rst
Normal file
@ -0,0 +1,115 @@
|
||||
Getting Started
|
||||
================
|
||||
|
||||
|
||||
Getting started
|
||||
----------------
|
||||
|
||||
The `Hosted FSFW example`_ 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.
|
||||
|
||||
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
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
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
|
||||
|
||||
.. code-block:: 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
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
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`_.
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
mkdir build-tests && cd build-tests
|
||||
cmake -DFSFW_BUILD_UNITTESTS=ON -DFSFW_OSAL=host ..
|
||||
|
||||
|
||||
You can also use ``-DFSFW_OSAL=linux`` on Linux systems.
|
||||
|
||||
Coverage data in HTML format can be generated using the `Code coverage`_ CMake module.
|
||||
To build the unittests, run them and then generare the coverage data in this format,
|
||||
the following command can be used inside the build directory after the build system was set up
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cmake --build . -- fsfw-tests_coverage -j
|
||||
|
||||
|
||||
The ``helper.py`` script located in the ``script`` folder can also be used to create, build
|
||||
and open the unittests conveniently. Try ``helper.py -h`` for more information.
|
||||
|
||||
Building the documentation
|
||||
----------------------------
|
||||
|
||||
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/>`_. You can set up a
|
||||
documentation build system using the following commands
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mkdir build-docs && cd build-docs
|
||||
cmake -DFSFW_BUILD_DOCS=ON -DFSFW_OSAL=host ..
|
||||
|
||||
Then you can generate the documentation using
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cmake --build . -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.
|
||||
|
||||
.. _`Hosted FSFW example`: https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted
|
||||
.. _`Catch2 library`: https://github.com/catchorg/Catch2
|
||||
.. _`Code coverage`: https://github.com/bilke/cmake-modules/tree/master
|
149
docs/highlevel.rst
Normal file
149
docs/highlevel.rst
Normal file
@ -0,0 +1,149 @@
|
||||
.. _highlevel:
|
||||
|
||||
High-level overview
|
||||
===================
|
||||
|
||||
Structure
|
||||
----------
|
||||
|
||||
The general structure is driven by the usage of interfaces provided by objects.
|
||||
The FSFW uses C++11 as baseline. The intention behind this is that this C++ Standard should be
|
||||
widely available, even with older compilers.
|
||||
The FSFW uses dynamic allocation during the initialization but provides static containers during runtime.
|
||||
This simplifies the instantiation of objects and allows the usage of some standard containers.
|
||||
Dynamic Allocation after initialization is discouraged and different solutions are provided in the
|
||||
FSFW to achieve that. The fsfw uses run-time type information but exceptions are not allowed.
|
||||
|
||||
Failure Handling
|
||||
-----------------
|
||||
|
||||
Functions should return a defined :cpp:type:`ReturnValue_t` to signal to the caller that something has
|
||||
gone wrong. Returnvalues must be unique. For this the function :cpp:func:`HasReturnvaluesIF::makeReturnCode`
|
||||
or the :ref:`macro MAKE_RETURN_CODE <retvalapi>` can be used. The ``CLASS_ID`` is a unique ID for that type of object.
|
||||
See the :ref:`FSFW Class IDs file <fwclassids>`. The user can add custom ``CLASS_ID``\s via the
|
||||
``fsfwconfig`` folder.
|
||||
|
||||
OSAL
|
||||
------------
|
||||
|
||||
The FSFW provides operation system abstraction layers for Linux, FreeRTOS and RTEMS.
|
||||
The OSAL provides periodic tasks, message queues, clocks and semaphores as well as mutexes.
|
||||
The :ref:`OSAL README <osal>` provides more detailed information on provided components
|
||||
and how to use them.
|
||||
|
||||
Core Components
|
||||
----------------
|
||||
|
||||
The FSFW has following core components. More detailed informations can be found in the
|
||||
:ref:`core component section <core>`:
|
||||
|
||||
1. Tasks: Abstraction for different (periodic) task types like periodic tasks or tasks
|
||||
with fixed timeslots
|
||||
2. ObjectManager: This module stores all `SystemObjects` by mapping a provided unique object ID
|
||||
to the object handles.
|
||||
3. Static Stores: Different stores are provided to store data of variable size (like telecommands
|
||||
or small telemetry) in a pool structure without using dynamic memory allocation.
|
||||
These pools are allocated up front.
|
||||
4. Clock: This module provided common time related functions
|
||||
5. EventManager: This module allows routing of events generated by `SystemObjects`
|
||||
6. HealthTable: A component which stores the health states of objects
|
||||
|
||||
Static IDs in the framework
|
||||
--------------------------------
|
||||
|
||||
Some parts of the framework use a static routing address for communication.
|
||||
An example setup of IDs can be found in the example config in ``misc/defaultcfg/fsfwconfig/objects``
|
||||
inside the function ``Factory::setStaticFrameworkObjectIds``.
|
||||
|
||||
Events
|
||||
----------------
|
||||
|
||||
Events are tied to objects. EventIds can be generated by calling the
|
||||
:ref:`macro MAKE_EVENT <eventapi>` or the function :cpp:func:`event::makeEvent`.
|
||||
This works analog to the returnvalues. Every object that needs own Event IDs has to get a
|
||||
unique ``SUBSYSTEM_ID``. Every :cpp:class:`SystemObject` can call
|
||||
:cpp:func:`SystemObject::triggerEvent` from the parent class.
|
||||
Therefore, event messages contain the specific EventId and the objectId of the object that
|
||||
has triggered.
|
||||
|
||||
Internal Communication
|
||||
-------------------------
|
||||
|
||||
Components communicate mostly via Messages through Queues.
|
||||
Those queues are created by calling the singleton ``QueueFactory::instance()->create`` which
|
||||
will create `MessageQueue` instances for the used OSAL.
|
||||
|
||||
External Communication
|
||||
--------------------------
|
||||
|
||||
The external communication with the mission control system is mostly up to the user implementation.
|
||||
The FSFW provides PUS Services which can be used to but don't need to be used.
|
||||
The services can be seen as a conversion from a TC to a message based communication and back.
|
||||
|
||||
TMTC Communication
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The FSFW provides some components to facilitate TMTC handling via the PUS commands.
|
||||
For example, a UDP or TCP PUS server socket can be opened on a specific port using the
|
||||
files located in ``osal/common``. The FSFW example uses this functionality to allow sending
|
||||
telecommands and receiving telemetry using the
|
||||
`TMTC commander application <https://github.com/robamu-org/tmtccmd>`_.
|
||||
|
||||
Simple commands like the PUS Service 17 ping service can be tested by simply running the
|
||||
``tmtc_client_cli.py`` or ``tmtc_client_gui.py`` utility in
|
||||
the `example tmtc folder <https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example_public/src/branch/master/tmtc>`_
|
||||
while the `fsfw_example` application is running.
|
||||
|
||||
More generally, any class responsible for handling incoming telecommands and sending telemetry
|
||||
can implement the generic ``TmTcBridge`` class located in ``tmtcservices``. Many applications
|
||||
also use a dedicated polling task for reading telecommands which passes telecommands
|
||||
to the ``TmTcBridge`` implementation.
|
||||
|
||||
CCSDS Frames, CCSDS Space Packets and PUS
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If the communication is based on CCSDS Frames and Space Packets, several classes can be used to
|
||||
distributed the packets to the corresponding services. Those can be found in ``tcdistribution``.
|
||||
If Space Packets are used, a timestamper has to be provided by the user.
|
||||
An example can be found in the ``timemanager`` folder, which uses ``CCSDSTime::CDS_short``.
|
||||
|
||||
Device Handlers
|
||||
--------------------------
|
||||
|
||||
DeviceHandlers are another important component of the FSFW. The idea is, to have a software
|
||||
counterpart of every physical device to provide a simple mode, health and commanding interface.
|
||||
By separating the underlying Communication Interface with
|
||||
``DeviceCommunicationIF``, a device handler (DH) can be tested on different hardware.
|
||||
The DH has mechanisms to monitor the communication with the physical device which allow
|
||||
for FDIR reaction. Device Handlers can be created by implementing ``DeviceHandlerBase``.
|
||||
A standard FDIR component for the DH will be created automatically but can
|
||||
be overwritten by the user. More information on DeviceHandlers can be found in the
|
||||
related [documentation section](doc/README-devicehandlers.md#top).
|
||||
|
||||
Modes and Health
|
||||
--------------------
|
||||
|
||||
The two interfaces ``HasModesIF`` and ``HasHealthIF`` provide access for commanding and monitoring
|
||||
of components. On-board mode management is implement in hierarchy system.
|
||||
|
||||
- Device handlers and controllers are the lowest part of the hierarchy.
|
||||
- The next layer are assemblies. Those assemblies act as a component which handle
|
||||
redundancies of handlers. Assemblies share a common core with the top level subsystem components
|
||||
- The top level subsystem components are used to group assemblies, controllers and device handlers.
|
||||
For example, a spacecraft can have a atttitude control subsystem and a power subsystem.
|
||||
|
||||
Those assemblies are intended to act as auto-generated components from a database which describes
|
||||
the subsystem modes. The definitions contain transition and target tables which contain the DH,
|
||||
Assembly and Controller Modes to be commanded.
|
||||
Transition tables contain as many steps as needed to reach the mode from any other mode, e.g. a
|
||||
switch into any higher AOCS mode might first turn on the sensors, than the actuators and the
|
||||
controller as last component.
|
||||
The target table is used to describe the state that is checked continuously by the subsystem.
|
||||
All of this allows System Modes to be generated as Subsystem object as well from the same database.
|
||||
This System contains list of subsystem modes in the transition and target tables.
|
||||
Therefore, it allows a modular system to create system modes and easy commanding of those, because
|
||||
only the highest components must be commanded.
|
||||
|
||||
The health state represents if the component is able to perform its tasks.
|
||||
This can be used to signal the system to avoid using this component instead of a redundant one.
|
||||
The on-board FDIR uses the health state for isolation and recovery.
|
Before Width: | Height: | Size: 52 KiB After Width: | Height: | Size: 52 KiB |
69
docs/index.rst
Normal file
69
docs/index.rst
Normal file
@ -0,0 +1,69 @@
|
||||
.. Flight Software Framework documentation master file, created by
|
||||
sphinx-quickstart on Tue Nov 30 10:56:03 2021.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Flight Software Framework (FSFW) documentation
|
||||
================================================
|
||||
|
||||
.. image:: ../misc/logo/FSFW_Logo_V3_bw.png
|
||||
:alt: FSFW Logo
|
||||
|
||||
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.
|
||||
|
||||
Index
|
||||
-------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
getting_started
|
||||
highlevel
|
||||
core
|
||||
config
|
||||
osal
|
||||
pus
|
||||
devicehandlers
|
||||
controllers
|
||||
localpools
|
||||
api
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
181
docs/localpools.rst
Normal file
181
docs/localpools.rst
Normal file
@ -0,0 +1,181 @@
|
||||
Local Data Pools
|
||||
=========================================
|
||||
|
||||
The following text is targeted towards mission software developers which would like
|
||||
to use the local data pools provided by the FSFW to store data like sensor values so they can be
|
||||
used by other software objects like controllers as well. If a custom class should have a local
|
||||
pool which can be used by other software objects as well, following steps have to be performed:
|
||||
|
||||
1. Create a ``LocalDataPoolManager`` member object in the custom class
|
||||
2. Implement the ``HasLocalDataPoolIF`` with specifies the interface between the local pool
|
||||
manager and the class owning the local pool.
|
||||
|
||||
The local data pool manager is also able to process housekeeping service requests in form
|
||||
of messages, generate periodic housekeeping packet, generate notification and snapshots of changed
|
||||
variables and datasets and process notifications and snapshots coming from other objects.
|
||||
The two former tasks are related to the external interface using telemetry and telecommands (TMTC)
|
||||
while the later two are related to data consumers like controllers only acting on data change
|
||||
detected by the data creator instead of checking the data manually each cycle. Two important
|
||||
framework classes ``DeviceHandlerBase`` and ``ExtendedControllerBase`` already perform the two steps
|
||||
shown above so the steps required are altered slightly.
|
||||
|
||||
Storing and Accessing pool data
|
||||
-------------------------------------
|
||||
|
||||
The pool manager is responsible for thread-safe access of the pool data, but the actual
|
||||
access to the pool data from the point of view of a mission software developer happens via proxy
|
||||
classes like pool variable classes. These classes store a copy
|
||||
of the pool variable with the matching datatype and copy the actual data from the local pool
|
||||
on a ``read`` call. Changed variables can then be written to the local pool with a ``commit`` call.
|
||||
The ``read`` and ``commit`` calls are thread-safe and can be called concurrently from data creators
|
||||
and data consumers. Generally, a user will create a dataset class which in turn groups all
|
||||
cohesive pool variables. These sets simply iterator over the list of variables and call the
|
||||
``read`` and ``commit`` functions of each variable. The following diagram shows the
|
||||
high-level architecture of the local data pools.
|
||||
|
||||
.. image:: ../docs/images/PoolArchitecture.png
|
||||
:alt: Pool Architecture
|
||||
|
||||
An example is shown for using the local data pools with a Gyroscope.
|
||||
For example, the following code shows an implementation to access data from a Gyroscope taken
|
||||
from the SOURCE CubeSat project:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
class GyroPrimaryDataset: public StaticLocalDataSet<3 * sizeof(float)> {
|
||||
public:
|
||||
/**
|
||||
* Constructor for data users
|
||||
* @param gyroId
|
||||
*/
|
||||
GyroPrimaryDataset(object_id_t gyroId):
|
||||
StaticLocalDataSet(sid_t(gyroId, gyrodefs::GYRO_DATA_SET_ID)) {
|
||||
setAllVariablesReadOnly();
|
||||
}
|
||||
|
||||
lp_var_t<float> angVelocityX = lp_var_t<float>(sid.objectId,
|
||||
gyrodefs::ANGULAR_VELOCITY_X, this);
|
||||
lp_var_t<float> angVelocityY = lp_var_t<float>(sid.objectId,
|
||||
gyrodefs::ANGULAR_VELOCITY_Y, this);
|
||||
lp_var_t<float> angVelocityZ = lp_var_t<float>(sid.objectId,
|
||||
gyrodefs::ANGULAR_VELOCITY_Z, this);
|
||||
private:
|
||||
|
||||
friend class GyroHandler;
|
||||
/**
|
||||
* Constructor for data creator
|
||||
* @param hkOwner
|
||||
*/
|
||||
GyroPrimaryDataset(HasLocalDataPoolIF* hkOwner):
|
||||
StaticLocalDataSet(hkOwner, gyrodefs::GYRO_DATA_SET_ID) {}
|
||||
};
|
||||
|
||||
There is a public constructor for users which sets all variables to read-only and there is a
|
||||
constructor for the GyroHandler data creator by marking it private and declaring the ``GyroHandler``
|
||||
as a friend class. Both the atittude controller and the ``GyroHandler`` can now
|
||||
use the same class definition to access the pool variables with ``read`` and ``commit`` semantics
|
||||
in a thread-safe way. Generally, each class requiring access will have the set class as a member
|
||||
class. The data creator will also be generally a ``DeviceHandlerBase`` subclass and some additional
|
||||
steps are necessary to expose the set for housekeeping purposes.
|
||||
|
||||
Using the local data pools in a ``DeviceHandlerBase`` subclass
|
||||
--------------------------------------------------------------
|
||||
|
||||
It is very common to store data generated by devices like a sensor into a pool which can
|
||||
then be used by other objects. Therefore, the ``DeviceHandlerBase`` already has a
|
||||
local pool. Using the aforementioned example, the ``GyroHandler`` will now have the set class
|
||||
as a member:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
class GyroHandler: ... {
|
||||
|
||||
public:
|
||||
...
|
||||
private:
|
||||
...
|
||||
GyroPrimaryDataset gyroData;
|
||||
...
|
||||
};
|
||||
|
||||
|
||||
The constructor used for the creators expects the owner class as a parameter, so we initialize
|
||||
the object in the `GyroHandler` constructor like this:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
GyroHandler::GyroHandler(object_id_t objectId, object_id_t comIF,
|
||||
CookieIF *comCookie, uint8_t switchId):
|
||||
DeviceHandlerBase(objectId, comIF, comCookie), switchId(switchId),
|
||||
gyroData(this) {}
|
||||
|
||||
|
||||
We need to assign the set to a reply ID used in the ``DeviceHandlerBase``.
|
||||
The combination of the ``GyroHandler`` object ID and the reply ID will be the 64-bit structure ID
|
||||
``sid_t`` and is used to globally identify the set, for example when requesting housekeeping data or
|
||||
generating update messages. We need to assign our custom set class in some way so that the local
|
||||
pool manager can access the custom data sets as well.
|
||||
By default, the ``getDataSetHandle`` will take care of this tasks. The default implementation for a
|
||||
``DeviceHandlerBase`` subclass will use the internal command map to retrieve
|
||||
a handle to a dataset from a given reply ID. Therefore,
|
||||
we assign the set in the ``fillCommandAndReplyMap`` function:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
void GyroHandler::fillCommandAndReplyMap() {
|
||||
...
|
||||
this->insertInCommandAndReplyMap(gyrodefs::GYRO_DATA, 3, &gyroData);
|
||||
...
|
||||
}
|
||||
|
||||
|
||||
Now, we need to create the actual pool entries as well, using the ``initializeLocalDataPool``
|
||||
function. Here, we also immediately subscribe for periodic housekeeping packets
|
||||
with an interval of 4 seconds. They are still disabled in this example and can be enabled
|
||||
with a housekeeping service command.
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
ReturnValue_t GyroHandler::initializeLocalDataPool(localpool::DataPool &localDataPoolMap,
|
||||
LocalDataPoolManager &poolManager) {
|
||||
localDataPoolMap.emplace(gyrodefs::ANGULAR_VELOCITY_X,
|
||||
new PoolEntry<float>({0.0}));
|
||||
localDataPoolMap.emplace(gyrodefs::ANGULAR_VELOCITY_Y,
|
||||
new PoolEntry<float>({0.0}));
|
||||
localDataPoolMap.emplace(gyrodefs::ANGULAR_VELOCITY_Z,
|
||||
new PoolEntry<float>({0.0}));
|
||||
localDataPoolMap.emplace(gyrodefs::GENERAL_CONFIG_REG42,
|
||||
new PoolEntry<uint8_t>({0}));
|
||||
localDataPoolMap.emplace(gyrodefs::RANGE_CONFIG_REG43,
|
||||
new PoolEntry<uint8_t>({0}));
|
||||
|
||||
poolManager.subscribeForPeriodicPacket(gyroData.getSid(), false, 4.0, false);
|
||||
return HasReturnvaluesIF::RETURN_OK;
|
||||
}
|
||||
|
||||
Now, if we receive some sensor data and converted them into the right format,
|
||||
we can write it into the pool like this, using a guard class to ensure the set is commited back
|
||||
in any case:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
PoolReadGuard readHelper(&gyroData);
|
||||
if(readHelper.getReadResult() == HasReturnvaluesIF::RETURN_OK) {
|
||||
if(not gyroData.isValid()) {
|
||||
gyroData.setValidity(true, true);
|
||||
}
|
||||
|
||||
gyroData.angVelocityX = angularVelocityX;
|
||||
gyroData.angVelocityY = angularVelocityY;
|
||||
gyroData.angVelocityZ = angularVelocityZ;
|
||||
}
|
||||
|
||||
|
||||
The guard class will commit the changed data on destruction automatically.
|
||||
|
||||
Using the local data pools in a ``ExtendedControllerBase`` subclass
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Coming soon
|
||||
|
||||
|
35
docs/make.bat
Normal file
35
docs/make.bat
Normal file
@ -0,0 +1,35 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
63
docs/osal.rst
Normal file
63
docs/osal.rst
Normal file
@ -0,0 +1,63 @@
|
||||
.. _osal:
|
||||
|
||||
Operating System Abstraction Layer (OSAL)
|
||||
============================================
|
||||
|
||||
Some specific information on the provided OSALs are provided.
|
||||
|
||||
Linux
|
||||
-------
|
||||
|
||||
This OSAL can be used to compile for Linux host systems like Ubuntu 20.04 or for
|
||||
embedded Linux targets like the Raspberry Pi. This OSAL generally requires threading support
|
||||
and real-time functionalities. For most UNIX systems, this is done by adding ``-lrt`` and
|
||||
``-lpthread`` to the linked libraries in the compilation process. The CMake build support provided
|
||||
will do this automatically for the ``fsfw`` target. It should be noted that most UNIX systems need
|
||||
to be configured specifically to allow the real-time functionalities required by the FSFW.
|
||||
|
||||
Hosted OSAL
|
||||
-------------------
|
||||
|
||||
This is the newest OSAL. Support for Semaphores has not been implemented yet and will propably be
|
||||
implemented as soon as C++20 with Semaphore support has matured. This OSAL can be used to run the
|
||||
FSFW on any host system, but currently has only been tested on Windows 10 and Ubuntu 20.04. Unlike
|
||||
the other OSALs, it uses dynamic memory allocation (e.g. for the message queue implementation).
|
||||
Cross-platform serial port (USB) support might be added soon.
|
||||
|
||||
FreeRTOS OSAL
|
||||
------------------
|
||||
|
||||
FreeRTOS is not included and the developer needs to take care of compiling the FreeRTOS sources and
|
||||
adding the ``FreeRTOSConfig.h`` file location to the include path. This OSAL has only been tested
|
||||
extensively with the pre-emptive scheduler configuration so far but it should in principle also be
|
||||
possible to use a cooperative scheduler. It is recommended to use the `heap_4` allocation scheme.
|
||||
When using newlib (nano), it is also recommended to add ``#define configUSE_NEWLIB_REENTRANT`` to
|
||||
the FreeRTOS configuration file to ensure thread-safety.
|
||||
|
||||
When using this OSAL, developers also need to provide an implementation for the
|
||||
``vRequestContextSwitchFromISR`` function. This has been done because the call to request a context
|
||||
switch from an ISR is generally located in the ``portmacro.h`` header and is different depending on
|
||||
the target architecture or device.
|
||||
|
||||
RTEMS OSAL
|
||||
---------------
|
||||
|
||||
The RTEMS OSAL was the first implemented OSAL which is also used on the active satellite Flying Laptop.
|
||||
|
||||
TCP/IP socket abstraction
|
||||
------------------------------
|
||||
|
||||
The Linux and Host OSAL provide abstraction layers for the socket API. Currently, only UDP sockets
|
||||
have been imlemented. This is very useful to test TMTC handling either on the host computer
|
||||
directly (targeting localhost with a TMTC application) or on embedded Linux devices, sending
|
||||
TMTC packets via Ethernet.
|
||||
|
||||
Example Applications
|
||||
----------------------
|
||||
|
||||
There are example applications available for each OSAL
|
||||
|
||||
- `Hosted OSAL <https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-hosted>`_
|
||||
- `Linux OSAL for MCUs <https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-linux-mcu>`_
|
||||
- `FreeRTOS OSAL on the STM32H743ZIT <https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-stm32h7-freertos>`_
|
||||
- `RTEMS OSAL on the STM32H743ZIT <https://egit.irs.uni-stuttgart.de/fsfw/fsfw-example-stm32h7-rtems>`_
|
2
docs/pus.rst
Normal file
2
docs/pus.rst
Normal file
@ -0,0 +1,2 @@
|
||||
PUS Services
|
||||
==============
|
@ -1,23 +1,49 @@
|
||||
target_include_directories(${TARGET_NAME} PRIVATE
|
||||
if(DEFINED TARGET_NAME)
|
||||
target_include_directories(${TARGET_NAME} PRIVATE
|
||||
${CMAKE_CURRENT_SOURCE_DIR}
|
||||
)
|
||||
|
||||
target_sources(${TARGET_NAME} PRIVATE
|
||||
ipc/missionMessageTypes.cpp
|
||||
pollingsequence/PollingSequenceFactory.cpp
|
||||
objects/FsfwFactory.cpp
|
||||
)
|
||||
|
||||
# If a special translation file for object IDs exists, compile it.
|
||||
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/objects/translateObjects.cpp")
|
||||
target_sources(${TARGET_NAME} PRIVATE
|
||||
objects/translateObjects.cpp
|
||||
)
|
||||
endif()
|
||||
|
||||
# If a special translation file for events exists, compile it.
|
||||
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/objects/translateObjects.cpp")
|
||||
target_sources(${TARGET_NAME} PRIVATE
|
||||
events/translateEvents.cpp
|
||||
ipc/missionMessageTypes.cpp
|
||||
pollingsequence/PollingSequenceFactory.cpp
|
||||
objects/FsfwFactory.cpp
|
||||
)
|
||||
|
||||
# If a special translation file for object IDs exists, compile it.
|
||||
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/objects/translateObjects.cpp")
|
||||
target_sources(${TARGET_NAME} PRIVATE
|
||||
objects/translateObjects.cpp
|
||||
)
|
||||
endif()
|
||||
|
||||
# If a special translation file for events exists, compile it.
|
||||
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/objects/translateObjects.cpp")
|
||||
target_sources(${TARGET_NAME} PRIVATE
|
||||
events/translateEvents.cpp
|
||||
)
|
||||
endif()
|
||||
else()
|
||||
target_include_directories(${LIB_FSFW_NAME} PRIVATE
|
||||
${CMAKE_CURRENT_SOURCE_DIR}
|
||||
)
|
||||
|
||||
target_sources(${LIB_FSFW_NAME} PRIVATE
|
||||
ipc/missionMessageTypes.cpp
|
||||
pollingsequence/PollingSequenceFactory.cpp
|
||||
objects/FsfwFactory.cpp
|
||||
)
|
||||
|
||||
# If a special translation file for object IDs exists, compile it.
|
||||
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/objects/translateObjects.cpp")
|
||||
target_sources(${LIB_FSFW_NAME} PRIVATE
|
||||
objects/translateObjects.cpp
|
||||
)
|
||||
endif()
|
||||
|
||||
# If a special translation file for events exists, compile it.
|
||||
if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/objects/translateObjects.cpp")
|
||||
target_sources(${LIB_FSFW_NAME} PRIVATE
|
||||
events/translateEvents.cpp
|
||||
)
|
||||
endif()
|
||||
endif()
|
||||
|
@ -7,7 +7,7 @@
|
||||
#include <fsfw/tmtcpacket/pus/tm/TmPacketStored.h>
|
||||
#include <fsfw/tmtcservices/CommandingServiceBase.h>
|
||||
#include <fsfw/tmtcservices/PusServiceBase.h>
|
||||
#include <fsfw/internalError/InternalErrorReporter.h>
|
||||
#include <fsfw/internalerror/InternalErrorReporter.h>
|
||||
|
||||
#include <cstdint>
|
||||
|
||||
@ -48,6 +48,6 @@ void Factory::setStaticFrameworkObjectIds() {
|
||||
|
||||
DeviceHandlerFailureIsolation::powerConfirmationId = objects::NO_OBJECT;
|
||||
|
||||
TmPacketStored::timeStamperId = objects::NO_OBJECT;
|
||||
TmPacketBase::timeStamperId = objects::NO_OBJECT;
|
||||
}
|
||||
|
||||
|
@ -1,83 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*
|
||||
"""Small portable helper script to generate LCOV HTML coverage data"""
|
||||
import os
|
||||
import platform
|
||||
import sys
|
||||
import time
|
||||
import argparse
|
||||
import webbrowser
|
||||
from typing import List
|
||||
|
||||
|
||||
"""Copy this helper script into your project folder. It will try to determine a CMake build folder
|
||||
and then attempt to build your project with coverage information.
|
||||
|
||||
See Unittest documentation at https://egit.irs.uni-stuttgart.de/fsfw/fsfw for more
|
||||
information how to set up the build folder.
|
||||
"""
|
||||
def main():
|
||||
|
||||
parser = argparse.ArgumentParser(description="Processing arguments for LCOV helper script.")
|
||||
parser.add_argument(
|
||||
'-o', '--open', action='store_true', help='Open coverage data in webbrowser'
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
build_dir_list = []
|
||||
if not os.path.isfile('README.md'):
|
||||
os.chdir('..')
|
||||
for directory in os.listdir("."):
|
||||
if os.path.isdir(directory):
|
||||
os.chdir(directory)
|
||||
check_for_cmake_build_dir(build_dir_list)
|
||||
os.chdir("..")
|
||||
|
||||
if len(build_dir_list) == 0:
|
||||
print("No valid CMake build directory found. Trying to set up hosted build")
|
||||
build_directory = 'build-Debug-Host'
|
||||
os.mkdir(build_directory)
|
||||
os.chdir(build_directory)
|
||||
os.system('cmake -DFSFW_OSAL=host -DFSFW_BUILD_UNITTESTS=ON ..')
|
||||
os.chdir('..')
|
||||
elif len(build_dir_list) == 1:
|
||||
build_directory = build_dir_list[0]
|
||||
else:
|
||||
print("Multiple build directories found!")
|
||||
build_directory = determine_build_dir(build_dir_list)
|
||||
perform_lcov_operation(build_directory)
|
||||
if os.path.isdir('fsfw-tests_coverage') and args.open:
|
||||
webbrowser.open('fsfw-tests_coverage/index.html')
|
||||
|
||||
|
||||
def check_for_cmake_build_dir(build_dir_dict: list):
|
||||
if os.path.isfile("CMakeCache.txt"):
|
||||
build_dir_dict.append(os.getcwd())
|
||||
|
||||
|
||||
def perform_lcov_operation(directory):
|
||||
os.chdir(directory)
|
||||
os.system("cmake --build . -- fsfw-tests_coverage -j")
|
||||
|
||||
|
||||
def determine_build_dir(build_dir_list: List[str]):
|
||||
build_directory = ""
|
||||
for idx, directory in enumerate(build_dir_list):
|
||||
print(f"{idx + 1}: {directory}")
|
||||
while True:
|
||||
idx = input("Pick the directory to perform LCOV HTML generation by index: ")
|
||||
if not idx.isdigit():
|
||||
print("Invalid input!")
|
||||
continue
|
||||
|
||||
idx = int(idx)
|
||||
if idx > len(build_dir_list) or idx < 1:
|
||||
print("Invalid input!")
|
||||
continue
|
||||
build_directory = build_dir_list[idx - 1]
|
||||
break
|
||||
return build_directory
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
@ -1,3 +0,0 @@
|
||||
#!/bin/sh
|
||||
mkdir build-Unittest && cd build-Unittest
|
||||
cmake -DFSFW_BUILD_UNITTESTS=ON -DFSFW_OSAL=host -DCMAKE_BUILD_TYPE=Debug ..
|
188
scripts/helper.py
Executable file
188
scripts/helper.py
Executable file
@ -0,0 +1,188 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*
|
||||
"""Small portable helper script to generate test or doc configuration for the
|
||||
flight software framework
|
||||
"""
|
||||
import os
|
||||
import argparse
|
||||
import webbrowser
|
||||
import shutil
|
||||
import sys
|
||||
import time
|
||||
from typing import List
|
||||
|
||||
|
||||
UNITTEST_FOLDER_NAME = 'build-tests'
|
||||
DOCS_FOLDER_NAME = 'build-docs'
|
||||