diff --git a/doc/README-config.md b/doc/README-config.md index b314b84ea..6afba83cc 100644 --- a/doc/README-config.md +++ b/doc/README-config.md @@ -1,11 +1,12 @@ -## Configuring the FSFW +Configuring the FSFW +====== The FSFW can be configured via the `fsfwconfig` folder. A template folder has been provided 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 +# Auto-Translation of Events The FSFW allows the automatic translation of events, which allows developers to track triggered events directly via consoke output. Using this feature requires: @@ -23,7 +24,7 @@ An example implementations of these translation file generators can be found as of the [SOURCE project here](https://git.ksat-stuttgart.de/source/sourceobsw/-/tree/development/generators) or the [FSFW example](https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example_public/src/branch/master/generators) -### Configuring the Event Manager +## Configuring the Event Manager The number of allowed subscriptions can be modified with the following parameters: diff --git a/doc/README-highlevel.md b/doc/README-highlevel.md index dd94d6da0..7bf96c640 100644 --- a/doc/README-highlevel.md +++ b/doc/README-highlevel.md @@ -1,6 +1,7 @@ -# High-level overview +High-level overview +====== -## Structure +# 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 @@ -10,37 +11,44 @@ This simplifies the instantiation of objects and allows the usage of some standa 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 +# Failure Handling -Functions should return a defined ReturnValue_t to signal to the caller that something has gone wrong. -Returnvalues must be unique. For this the function HasReturnvaluesIF::makeReturnCode or the Macro MAKE_RETURN can be used. -The CLASS_ID is a unique id for that type of object. See returnvalues/FwClassIds. +Functions should return a defined `ReturnValue_t` to signal to the caller that something has +gone wrong. Returnvalues must be unique. For this the function `HasReturnvaluesIF::makeReturnCode` +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. -### OSAL +# 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 [OSAL README](doc/README-osal.md#top) provides more detailed information on provided components and how to use them. +The [OSAL README](doc/README-osal.md#top) provides more detailed information on provided components +and how to use them. -### Core Components +# Core Components The FSFW has following core components. More detailed informations can be found in the [core component section](doc/README-core.md#top): -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. +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. 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 -### Static IDs in the framework +# 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 "defaultcft/fsfwconfig/objects/Factory::setStaticFrameworkObjectIds()". +An example setup of ids can be found in the example config in `defaultcft/fsfwconfig/objects` + inside the function `Factory::setStaticFrameworkObjectIds()`. -### Events +# Events 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 @@ -48,25 +56,39 @@ unique SUBSYSTEM_ID. Every SystemObject can call triggerEvent from the parent cl Therefore, event messages contain the specific EventId and the objectId of the object that has triggered. -### Internal Communication +# Internal Communication -Components communicate mostly over Message through Queues. -Those queues are created by calling the singleton QueueFactory::instance()->create(). +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 +# 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. -#### CCSDS Frames, CCSDS Space Packets and PUS +## 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 opended 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/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 +the [example tmtc folder](https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example_public/src/branch/master/tmtc). + +More generally, any class responsible for handling incoming telecommands and sending telemetry +can implement the generic `TmTcBridge` class located in `tmtcservices`. + +## 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 +# 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, @@ -74,16 +96,18 @@ health and commanding interface. By separating the underlying Communication Inte `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). +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, Health +# 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. +The two interfaces `HasModesIF` and `HasHealthIF` provide access for commanding and monitoring +of components. On-board Mode Management is implement in hierarchy system. DeviceHandlers 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 next level which are the Subsystems. +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. 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, @@ -101,7 +125,7 @@ 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. -## Unit Tests +# Unit Tests 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