KSat/fsfw
15
4
Fork 0
forked from fsfw/fsfw
Code Issues Pull Requests 1 Releases Wiki Activity

Merge pull request 'Doc Update + PUS IDs' (#422) from mueller/another-update-package into development

Browse Source 
Reviewed-on: fsfw/fsfw#422
This commit is contained in:
Steffen Gaisser 2021-05-25 14:49:10 +02:00
commit 5ac68f731e
8 changed files with 233 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@ -38,11 +38,12 @@ a starting point. The [configuration section](doc/README-config.md#top) provides
[1. High-level overview](doc/README-highlevel.md#top) <br> [1. High-level overview](doc/README-highlevel.md#top) <br>
[2. Core components](doc/README-core.md#top) <br> [2. Core components](doc/README-core.md#top) <br>
[3. OSAL overview](doc/README-osal.md#top) <br> [3. Configuration](doc/README-config.md#top) <br>
[4. PUS services](doc/README-pus.md#top) <br> [4. OSAL overview](doc/README-osal.md#top) <br>
[5. Device Handler overview](doc/README-devicehandlers.md#top) <br> [5. PUS services](doc/README-pus.md#top) <br>
[6. Controller overview](doc/README-controllers.md#top) <br> [6. Device Handler overview](doc/README-devicehandlers.md#top) <br>
[7. Local Data Pools](doc/README-localpools.md#top) <br> [7. Controller overview](doc/README-controllers.md#top) <br>
[8. Local Data Pools](doc/README-localpools.md#top) <br>

3
datalinklayer/DataLinkLayer.h
View File

@ -19,7 +19,8 @@ class VirtualChannelReception;
class DataLinkLayer : public CCSDSReturnValuesIF { class DataLinkLayer : public CCSDSReturnValuesIF {
public: public:
static const uint8_t SUBSYSTEM_ID = SUBSYSTEM_ID::SYSTEM_1; static const uint8_t SUBSYSTEM_ID = SUBSYSTEM_ID::SYSTEM_1;
static const Event RF_AVAILABLE = MAKE_EVENT(0, severity::INFO); //!< A RF available signal was detected. P1: raw RFA state, P2: 0 //! [EXPORT] : [COMMENT] A RF available signal was detected. P1: raw RFA state, P2: 0
static const Event RF_AVAILABLE = MAKE_EVENT(0, severity::INFO);
static const Event RF_LOST = MAKE_EVENT(1, severity::INFO); //!< A previously found RF available signal was lost. P1: raw RFA state, P2: 0 static const Event RF_LOST = MAKE_EVENT(1, severity::INFO); //!< A previously found RF available signal was lost. P1: raw RFA state, P2: 0
static const Event BIT_LOCK = MAKE_EVENT(2, severity::INFO); //!< A Bit Lock signal. Was detected. P1: raw BLO state, P2: 0 static const Event BIT_LOCK = MAKE_EVENT(2, severity::INFO); //!< A Bit Lock signal. Was detected. P1: raw BLO state, P2: 0
static const Event BIT_LOCK_LOST = MAKE_EVENT(3, severity::INFO); //!< A previously found Bit Lock signal was lost. P1: raw BLO state, P2: 0 static const Event BIT_LOCK_LOST = MAKE_EVENT(3, severity::INFO); //!< A previously found Bit Lock signal was lost. P1: raw BLO state, P2: 0

27
doc/README-config.md
View File

@ -1,12 +1,30 @@
Configuring the FSFW
## Configuring the FSFW ======
The FSFW can be configured via the `fsfwconfig` folder. A template folder has 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 been provided to have a starting point for this. The folder should be added
to the include path. 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
### Configuring the Event Manager 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
[modgen Python scripts](https://git.ksat-stuttgart.de/source/modgen.git).
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/development/generators)
or the [FSFW example](https://egit.irs.uni-stuttgart.de/fsfw/fsfw_example_public/src/branch/master/generators)
## Configuring the Event Manager
The number of allowed subscriptions can be modified with the following The number of allowed subscriptions can be modified with the following
parameters: parameters:
@ -19,3 +37,4 @@ static constexpr size_t FSFW_EVENTMGMT_EVENTIDMATCHERS = 120;
static constexpr size_t FSFW_EVENTMGMR_RANGEMATCHERS = 120; static constexpr size_t FSFW_EVENTMGMR_RANGEMATCHERS = 120;
} }
``` ```

20
doc/README-core.md
View File

@ -19,8 +19,9 @@ A nullptr check of the returning Pointer must be done. This function is based on
```cpp ```cpp
template <typename T> T* ObjectManagerIF::get( object_id_t id ) 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. * A typical way to create all objects on startup is a handing a static produce function to the
By calling objectManager->initialize() the produce function will be called and all SystemObjects will be initialized afterwards. ObjectManager on creation. By calling objectManager->initialize() the produce function will be
called and all SystemObjects will be initialized afterwards.
### Event Manager ### Event Manager
@ -36,14 +37,19 @@ By calling objectManager->initialize() the produce function will be called and a
### Stores ### Stores
* The message based communication can only exchange a few bytes of information inside the message itself. Therefore, additional information can * The message based communication can only exchange a few bytes of information inside the message
be exchanged with Stores. With this, only the store address must be exchanged in the message. itself. Therefore, additional information can be exchanged with Stores. With this, only the
* 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. 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 * All of them should use the Thread Safe Class storagemanager/PoolManager
### Tasks ### Tasks
There are two different types of 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. * The PeriodicTask just executes objects that are of type ExecutableObjectIF in the order of the
* 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 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

134
doc/README-highlevel.md
View File

@ -1,99 +1,135 @@
# High-level overview High-level overview
======
## Structure # Structure
The general structure is driven by the usage of interfaces provided by objects. 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 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. 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. 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. Dynamic Allocation after initialization is discouraged and different solutions are provided in the
The fsfw uses run-time type information but exceptions are not allowed. 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. Functions should return a defined `ReturnValue_t` to signal to the caller that something has
Returnvalues must be unique. For this the function HasReturnvaluesIF::makeReturnCode or the Macro MAKE_RETURN can be used. gone wrong. Returnvalues must be unique. For this the function `HasReturnvaluesIF::makeReturnCode`
The CLASS_ID is a unique id for that type of object. See returnvalues/FwClassIds. 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 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 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 The FSFW has following core components. More detailed informations can be found in the
[core component section](doc/README-core.md#top): [core component section](doc/README-core.md#top):
1. Tasks: Abstraction for different (periodic) task types like periodic tasks or tasks with fixed timeslots 1. Tasks: Abstraction for different (periodic) task types like periodic tasks or tasks
2. ObjectManager: This module stores all `SystemObjects` by mapping a provided unique object ID to the object handles. with fixed timeslots
3. Static Stores: Different stores are provided to store data of variable size (like telecommands or small telemetry) in a pool structure without 2. ObjectManager: This module stores all `SystemObjects` by mapping a provided unique object ID
using dynamic memory allocation. These pools are allocated up front. 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 3. Clock: This module provided common time related functions
4. EventManager: This module allows routing of events generated by `SystemObjects` 4. EventManager: This module allows routing of events generated by `SystemObjects`
5. HealthTable: A component which stores the health states of objects 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. 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. Events are tied to objects. EventIds can be generated by calling the Macro MAKE_EVENT.
Every object that needs own EventIds has to get a unique SUBSYSTEM_ID. This works analog to the returnvalues. Every object that needs own EventIds has to get a
Every SystemObject can call triggerEvent from the parent class. 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. 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. Components communicate mostly via Messages through Queues.
Those queues are created by calling the singleton QueueFactory::instance()->create(). 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 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 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. 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
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. The FSFW provides some components to facilitate TMTC handling via the PUS commands.
If Space Packets are used, a timestamper must be created. For example, a UDP or TCP PUS server socket can be opened on a specific port using the
An example can be found in the timemanager folder, this uses CCSDSTime::CDS_short. 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)
while the `fsfw_example` application is running.
#### Device Handlers 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. 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. The idea is, to have a software counterpart of every physical device to provide a simple mode,
By separating the underlying Communication Interface with DeviceCommunicationIF, a device handler (DH) can be tested on different hardware. health and commanding interface. By separating the underlying Communication Interface with
The DH has mechanisms to monitor the communication with the physical device which allow for FDIR reaction. `DeviceCommunicationIF`, a device handler (DH) can be tested on different hardware.
Device Handlers can be created by overriding `DeviceHandlerBase`. The DH has mechanisms to monitor the communication with the physical device which allow
A standard FDIR component for the DH will be created automatically but can be overwritten by the user. for FDIR reaction. Device Handlers can be created by implementing `DeviceHandlerBase`.
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. The two interfaces `HasModesIF` and `HasHealthIF` provide access for commanding and monitoring
On-board Mode Management is implement in hierarchy system. of components. On-board Mode Management is implement in hierarchy system.
DeviceHandlers and Controllers are the lowest part of the hierarchy. 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. The next layer are Assemblies. Those assemblies act as a component which handle
Assemblies share a common core with the next level which are the Subsystems. 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. Those Assemblies are intended to act as auto-generated components from a database which describes
The definitions contain transition and target tables which contain the DH, Assembly and Controller Modes to be commanded. the subsystem modes. The definitions contain transition and target tables which contain the DH,
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. 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. 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. 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. 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. 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. 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. 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. 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 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
[`fsfw_tests` reposoitory](https://egit.irs.uni-stuttgart.de/fsfw/fsfw_tests) [`fsfw_tests` reposoitory](https://egit.irs.uni-stuttgart.de/fsfw/fsfw_tests)

13
events/fwSubsystemIdRanges.h
View File

@ -1,8 +1,10 @@
#ifndef FSFW_EVENTS_FWSUBSYSTEMIDRANGES_H_ #ifndef FSFW_EVENTS_FWSUBSYSTEMIDRANGES_H_
#define FSFW_EVENTS_FWSUBSYSTEMIDRANGES_H_ #define FSFW_EVENTS_FWSUBSYSTEMIDRANGES_H_
#include <cstdint>
namespace SUBSYSTEM_ID { namespace SUBSYSTEM_ID {
enum { enum: uint8_t {
MEMORY = 22, MEMORY = 22,
OBSW = 26, OBSW = 26,
CDH = 28, CDH = 28,
@ -19,12 +21,17 @@ enum {
SYSTEM_MANAGER_1 = 75, SYSTEM_MANAGER_1 = 75,
SYSTEM_1 = 79, SYSTEM_1 = 79,
PUS_SERVICE_1 = 80, PUS_SERVICE_1 = 80,
PUS_SERVICE_2 = 82,
PUS_SERVICE_3 = 83,
PUS_SERVICE_5 = 85,
PUS_SERVICE_6 = 86,
PUS_SERVICE_8 = 88,
PUS_SERVICE_9 = 89, PUS_SERVICE_9 = 89,
PUS_SERVICE_17 = 97, PUS_SERVICE_17 = 97,
PUS_SERVICE_23 = 103,
FW_SUBSYSTEM_ID_RANGE FW_SUBSYSTEM_ID_RANGE
}; };
} }
#endif /* FSFW_EVENTS_FWSUBSYSTEMIDRANGES_H_ */ #endif /* FSFW_EVENTS_FWSUBSYSTEMIDRANGES_H_ */

4
objectmanager/frameworkObjects.h
View File

@ -1,8 +1,9 @@
#ifndef FSFW_OBJECTMANAGER_FRAMEWORKOBJECTS_H_ #ifndef FSFW_OBJECTMANAGER_FRAMEWORKOBJECTS_H_
#define FSFW_OBJECTMANAGER_FRAMEWORKOBJECTS_H_ #define FSFW_OBJECTMANAGER_FRAMEWORKOBJECTS_H_
#include <fsfw/objectmanager/SystemObjectIF.h> #include "SystemObjectIF.h"
// The objects will be instantiated in the ID order
namespace objects { namespace objects {
enum framework_objects: object_id_t { enum framework_objects: object_id_t {
FSFW_OBJECTS_START = 0x53000000, FSFW_OBJECTS_START = 0x53000000,
@ -16,6 +17,7 @@ enum framework_objects: object_id_t {
PUS_SERVICE_17_TEST = 0x53000017, PUS_SERVICE_17_TEST = 0x53000017,
PUS_SERVICE_20_PARAMETERS = 0x53000020, PUS_SERVICE_20_PARAMETERS = 0x53000020,
PUS_SERVICE_200_MODE_MGMT = 0x53000200, PUS_SERVICE_200_MODE_MGMT = 0x53000200,
PUS_SERVICE_201_HEALTH = 0x53000201,
//Generic IDs for IPC, modes, health, events //Generic IDs for IPC, modes, health, events
HEALTH_TABLE = 0x53010000, HEALTH_TABLE = 0x53010000,

34
returnvalues/FwClassIds.h
View File

@ -1,9 +1,14 @@
#ifndef FSFW_RETURNVALUES_FWCLASSIDS_H_ #ifndef FSFW_RETURNVALUES_FWCLASSIDS_H_
#define FSFW_RETURNVALUES_FWCLASSIDS_H_ #define FSFW_RETURNVALUES_FWCLASSIDS_H_
#include <cstdint>
// The comment block at the end is used by the returnvalue exporter.
// It is recommended to add it as well for mission returnvalues
namespace CLASS_ID { namespace CLASS_ID {
enum { enum: uint8_t {
OPERATING_SYSTEM_ABSTRACTION = 1, //OS FW_CLASS_ID_START = 0, // [EXPORT] : [START]
OPERATING_SYSTEM_ABSTRACTION, //OS
OBJECT_MANAGER_IF, //OM OBJECT_MANAGER_IF, //OM
DEVICE_HANDLER_BASE, //DHB DEVICE_HANDLER_BASE, //DHB
RMAP_CHANNEL, //RMP RMAP_CHANNEL, //RMP
@ -55,18 +60,19 @@ enum {
HAS_ACTIONS_IF, //HF HAS_ACTIONS_IF, //HF
DEVICE_COMMUNICATION_IF, //DC DEVICE_COMMUNICATION_IF, //DC
BSP, //BSP BSP, //BSP
TIME_STAMPER_IF, //TSI 53 TIME_STAMPER_IF, //TSI
SGP4PROPAGATOR_CLASS, //SGP4 54 SGP4PROPAGATOR_CLASS, //SGP4
MUTEX_IF, //MUX 55 MUTEX_IF, //MUX
MESSAGE_QUEUE_IF,//MQI 56 MESSAGE_QUEUE_IF,//MQI
SEMAPHORE_IF, //SPH 57 SEMAPHORE_IF, //SPH
LOCAL_POOL_OWNER_IF, //LPIF 58 LOCAL_POOL_OWNER_IF, //LPIF
POOL_VARIABLE_IF, //PVA 59 POOL_VARIABLE_IF, //PVA
HOUSEKEEPING_MANAGER, //HKM 60 HOUSEKEEPING_MANAGER, //HKM
DLE_ENCODER, //DLEE 61 DLE_ENCODER, //DLEE
PUS_SERVICE_9, //PUS9 62 PUS_SERVICE_3, //PUS3
FILE_SYSTEM, //FILS 63 PUS_SERVICE_9, //PUS9
FW_CLASS_ID_COUNT //is actually count + 1 ! FILE_SYSTEM, //FILS
FW_CLASS_ID_COUNT // [EXPORT] : [END]
}; };
} }