fsfw-from-zero/ws-objects/README.md

Global Addressable Objects and the Object Manager

The FSFW is an object-oriented framework and uses the concept of classes and objects to model a remote system like a satellite. Usually, every non-trivial object in the flight software is assigned a 32-bit object ID. This ID is then used as an address field for that object. Lets say for example that you want to change the ACS controller mode and the controller has the object ID 0x12345678. You would then send a mode command to the object 0x12345678 to do this task. In general, using objects allows software developers to model the architecture of the satellite and also makes it easier for SW developers to reason with Operations about what the satellite should be capable of.

Some other examples of addressable building blocks of a software built with the FSFW could be

• Device handlers for external sensors or payloads
• Assembly components which manage device redundancy
• Subsystem components which perform the mode and health management of related device, assembly and controller objects

The framework also has a global singleton class to store global objects and retrieve them back in an arbitrary format (e.g. only a certain interface of an object) at a later point.

The required interface of a class to be compatible to the object manager is the SystemObjectIF. The SystemObject class is a base class implementing this interface which is implemented by most base classes in the framework.

It is recommended to do the task workshop located inside ws-tasks before doing this workshop, unless you are familiar with how task scheduling with the framework works.

1. Creating a user SystemObject

In this chapter, a custom class will be created which is insertable into the global object manager.

Subtasks

1. Create a custom class MySystemObject which implements the SystemObject base class. Use the object ID 0x10101010. The second argument of the SystemObject constructor can be used to disable object manager registration. Use it to do exactly that.
2. Override the initialize function and print out a test string in the function.
3. Create a dynamic instance of that class on the heap using the new keyword.
4. Print out the object ID in hex format with 8 digits. You can use the iostream manipulators setw, setfill and hex to do this. You need to include the iomanip C++ system header t ouse those.
5. Call the initialize function of your dynamic object
6. Explicitely delete your global object. Forgetting to delete dynamic resources in C++ is generally a resource leak because the memory claimed for creating that dynamic resource can not be re-used by the OS.

Hints

• You can use #include "fsfw/objectmanager.h" to include everything you need.
• The SystemObject base class receives its object ID information by constructor argument. Every base (parent) class which does not have a default (empty) constructor needs to be initialized by the child class constructor. You can do this in the child class constructor member initializer list

Notes on memory and resource management

In desktop programs, it is very common to simply dynamically allocate all required resources as they are required. It should be noted that dynamic memory allocation can show non-deterministic behaviour, which is something that should be avoided in real-time environments. Especially on smaller systems, where the RAM might be limited to something like for example 1 MB, one has to be really careful with dynamic memory management to not run out of memory during run-time.

A possible side-effect of running out of memory would be that the allocation can take a possibly infinite time. Another side-effect which is probably more common is that the allocation simply fails and a nullptr is returned, which causes the application to crash unless every allocation call is checked.

Omitting dynamic memory allocation altogether is not really a acceptable solution either unless dealing with really, REALLY (!) small systems like a PIC microcontroller. A good solution is to limit the dynamic memory allocation to the program initialization time and only use pre-allocated memory during run-time. This is what the FSFW or real time OSes like RTEMS generally promote and support.

It is also important to keep in mind that std library containers generally allocate dynamically when inserting new entries.

2. Initialize the object using the ObjectManager

The SystemObject base class will take care of automatically registering the object at the global object manager as part of its constructor. The object manager stores all inserted objects by the SystemObjectIF base class pointer inside a hash map, so all inserted objects can be retrieved at a later stage. The object manager is also able to call the initialize method of all its registered objects. The initialize method allows to return an explicit returnvalue for failed object initialization. This is generally not possible for object constructors. The usual way to have an object construction fail is to use exceptions, which might or might not be available to your project.

Subtasks

1. Register the MySystemObject class into the global object manager. You can do this with a simple tweak of the base class constructor.
2. Remove the delete call. The object manager will delete all of its contained objects automatically in its own destructor
3. Retrieve the global instance of the object manager using its static instance method and use it to initialize all system objects including your custom system object.
4. Retrieve the concrete instance of your object using the ObjectManager get method. Please note that you explicitely have to specify the target type you want to retrieve using a template argument to get. Use that instance to retrieve and print the object ID instead of using the instance returned by new

3. Schedule your object using its object ID

The object ID is now an addressing unit which can be used at various places in the framework. One example is to schedule the object. This means that instead of passing the concrete instance of the object, you can also add units to schedule by using their object ID.

Subtasks

1. Retrieve the global instance of the TaskFactory using its static instance method.

2. Create a new enum called ObjectIds and make your object ID constant an enum number if it. If this is not the case already the case, refactor your MySystemObject to expect the Object ID via constructor argument and pass your enum member as the object ID.

3. Add the ExecutableObjectIF to the list of implemented interface in MySystemObject and rename it to MyObject to make it executable. Most IDEs have some functionality to make renaming an object as convenient as possible.

4. Create a PeriodicTask and add your custom system object using its object ID with the addComponent method.

5. Schedule the object. Do not forget to put the main thread to sleep, for example by using code like this

   while(true) {
      using namespace std::chrono_literals;
      this_thread::sleep_for(5000ms);
   }
   

Hints

• You can use #include "fsfw/tasks/TaskFactory.h" to include everything you need.

General note on global mutable objects

Please note that the object manager is a software entity which global mutable state. This is something which can easily introduce subtle and dangerous bugs into a multi-threaded software. If you are sharing an object with the manager between multiple threads, all object accesses needs to be protected explicitely with concurrency tools like a Mutex by the developer.

The object manager has no own capabilities to ensure thread-safey in such a case. It is recommended to do the ws-ipc workshop to get familiar with various ways for objects to communicate with each other in a thread-safe way.