2021-05-18 15:31:04 +02:00
|
|
|
High-level overview
|
|
|
|
======
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Structure
|
2021-01-13 11:39:19 +01:00
|
|
|
|
|
|
|
The general structure is driven by the usage of interfaces provided by objects.
|
2022-09-15 13:51:59 +02:00
|
|
|
The FSFW uses C++17 as baseline. Most modern compilers like GCC should have support for this
|
|
|
|
standard, even for micocontrollers.
|
|
|
|
|
2022-09-15 13:57:39 +02:00
|
|
|
The FSFW might use dynamic allocation during program initialization but not during runtime.
|
|
|
|
It offers pool objects, static containers and it also exposes the Embedded Template Library
|
|
|
|
to allow writing code which does not perform allocation during runtime. The fsfw uses run-time type
|
|
|
|
information but will not throw exceptions.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Failure Handling
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
Functions should return a defined `ReturnValue_t` to signal to the caller that something has
|
2022-08-16 12:29:53 +02:00
|
|
|
gone wrong. Returnvalues must be unique. For this the function `returnvalue::makeCode`
|
2021-05-18 15:31:04 +02:00
|
|
|
or the macro `MAKE_RETURN` can be used. The `CLASS_ID` is a unique id for that type of object.
|
|
|
|
See `returnvalues/FwClassIds` folder. The user can add custom `CLASS_ID`s via the
|
|
|
|
`fsfwconfig` folder.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# OSAL
|
2021-01-13 11:39:19 +01:00
|
|
|
|
|
|
|
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.
|
2021-05-18 15:31:04 +02:00
|
|
|
The [OSAL README](doc/README-osal.md#top) provides more detailed information on provided components
|
|
|
|
and how to use them.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Core Components
|
2021-01-13 11:39:19 +01:00
|
|
|
|
|
|
|
The FSFW has following core components. More detailed informations can be found in the
|
|
|
|
[core component section](doc/README-core.md#top):
|
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
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.
|
2021-01-13 11:39:19 +01:00
|
|
|
3. Clock: This module provided common time related functions
|
|
|
|
4. EventManager: This module allows routing of events generated by `SystemObjects`
|
|
|
|
5. HealthTable: A component which stores the health states of objects
|
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Static IDs in the framework
|
2021-01-13 11:39:19 +01:00
|
|
|
|
|
|
|
Some parts of the framework use a static routing address for communication.
|
2021-05-18 15:31:04 +02:00
|
|
|
An example setup of ids can be found in the example config in `defaultcft/fsfwconfig/objects`
|
|
|
|
inside the function `Factory::setStaticFrameworkObjectIds()`.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Events
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:12:48 +02:00
|
|
|
Events are tied to objects. EventIds can be generated by calling the Macro MAKE_EVENT.
|
|
|
|
This works analog to the returnvalues. Every object that needs own EventIds has to get a
|
|
|
|
unique SUBSYSTEM_ID. Every SystemObject can call triggerEvent from the parent class.
|
|
|
|
Therefore, event messages contain the specific EventId and the objectId of the object that
|
|
|
|
has triggered.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Internal Communication
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
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.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# External Communication
|
2021-01-13 11:39:19 +01:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
## TMTC Communication
|
|
|
|
|
|
|
|
The FSFW provides some components to facilitate TMTC handling via the PUS commands.
|
2021-05-18 15:32:52 +02:00
|
|
|
For example, a UDP or TCP PUS server socket can be opened on a specific port using the
|
2021-05-18 15:31:04 +02:00
|
|
|
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/spacefisch/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
|
2021-05-18 15:32:52 +02:00
|
|
|
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.
|
2021-05-18 15:31:04 +02:00
|
|
|
|
|
|
|
More generally, any class responsible for handling incoming telecommands and sending telemetry
|
2021-05-18 15:34:31 +02:00
|
|
|
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.
|
2021-05-18 15:31:04 +02:00
|
|
|
|
|
|
|
## CCSDS Frames, CCSDS Space Packets and PUS
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:12:48 +02:00
|
|
|
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`.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Device Handlers
|
2021-01-13 11:39:19 +01:00
|
|
|
|
|
|
|
DeviceHandlers are another important component of the FSFW.
|
2021-05-18 15:12:48 +02:00
|
|
|
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`.
|
2021-05-18 15:31:04 +02:00
|
|
|
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).
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Modes and Health
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
The two interfaces `HasModesIF` and `HasHealthIF` provide access for commanding and monitoring
|
|
|
|
of components. On-board Mode Management is implement in hierarchy system.
|
2021-01-13 11:39:19 +01:00
|
|
|
DeviceHandlers and Controllers are the lowest part of the hierarchy.
|
2021-05-18 15:31:04 +02:00
|
|
|
The next layer are Assemblies. Those assemblies act as a component which handle
|
|
|
|
redundancies of handlers. Assemblies share a common core with the next level which
|
|
|
|
are the Subsystems.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:12:48 +02:00
|
|
|
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.
|
2021-01-13 11:39:19 +01:00
|
|
|
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.
|
2021-05-18 15:12:48 +02:00
|
|
|
Therefore, it allows a modular system to create system modes and easy commanding of those, because
|
|
|
|
only the highest components must be commanded.
|
2021-01-13 11:39:19 +01:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2021-05-18 15:31:04 +02:00
|
|
|
# Unit Tests
|
2021-01-13 11:39:19 +01:00
|
|
|
|
2021-05-18 15:12:48 +02:00
|
|
|
Unit Tests are provided in the unittest folder. Those use the catch2 framework but do not include
|
|
|
|
catch2 itself. More information on how to run these tests can be found in the separate
|
2021-01-13 11:39:19 +01:00
|
|
|
[`fsfw_tests` reposoitory](https://egit.irs.uni-stuttgart.de/fsfw/fsfw_tests)
|