fsfw/docs/README-highlevel.md

137 lines
7.1 KiB
Markdown
Raw Normal View History

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)