docs/user-manual/overview/04-cmd-evt-chn-prm.md
Typically, spacecraft software is controlled through commands and monitored using a set of events and telemetry
channels. These are the critical data constructs supported directly by F´ and have built-in autocoder support. In
addition, the F´ Svc components handle these types making it easy to define and control an F´ system through commands,
events, and telemetry channels.
Parameters allow for controlling stored values that affect the operation of an F´ system. They have framework support to automatically, load, store, and set these values using commands.
[!NOTE] Events are sometimes called EVRs and telemetry channels are sometimes called EHAs.
These types will be elaborated within this guide. It contains:
Each Component defines a set of commands for operations. Unlike ports, which are intended for component to component communication, commands are designed for user interaction with a component. Commands are defined through a series of
properties. Users can send commands to the F´ system and via Svc::CmdDispatcher these commands are dispatched to a
handling component to invoke some behavior. The handling component handles a command by defining a command handler function
to run when the command arrives.
The properties defining commands are shown below:
Code in the component-specific generated base class calls a function to invoke the user-defined command handler. This is hooked up by connecting the command registration, command dispatch, and command response ports.
When commands are defined for a component, the autocoder automatically adds ports for registering and receiving commands, and reporting an execution status when finished. Each component that handles commands should be hooked up to the command dispatcher connecting the registration, dispatch, and response ports in parallel.
Figure 4. Command dispatcher. The command dispatcher receives the raw buffer containing the command and arguments. The command opcode is extracted, and a lookup table is used to find the handling component. The argument buffer is then passed to the component, and the command dispatcher waits without blocking for the component to return status..
In many projects, commands need to be sequenced in order. In order to facilitate this, the framework provides
Svc::CmdSequencer. The command sequencer reads a defined sequence of commands and sends each in turn to the command
dispatcher; after each command is dispatched, the status of its execution is returned to the sequencer. Sending command buffers
to the command dispatcher through the command sequencer is an alternate path to sending them externally from the ground.
Figure 5. Command sequence. The command sequencer loads a sequence file from the file system, sends the command, and waits for the response for each command in the sequence. A failed response terminates the sequence, while a successful response moves to the next command in the sequence.
Events represent a log of activities taken by the embedded system. Events can be thought of in the same way as a program
execution log in that they enable the ability to trace the execution of the system. Events are sent out of the system via
the Svc::EventManager component and components defining events should hook up the log port to it. If console logging is
desired, the text log port can be hooked up to the Svc::PassiveConsoleTextLogger component. Events are defined per
component and are typically used to capture what the component is doing. Events can occur sporadically; however, they
should all be captured for downlink. Events are defined by the following properties:
[!NOTE] the use of events to severity levels are based on the judgement of the system designer.
Code in the component-specific generated base class provides a function to call to emit each event defined by the component. This function expects an argument to be supplied for each argument defined by the event. The code generator automatically adds ports for retrieving a time tag and sending events. There are two independent ports for sending events:
Events first acquire a time tag to represent when they occurred and then are typically sent to the Svc::EventManager
component on their way to be sent down to the ground. This logger component both processes the event and also recognizes
and begins responses for FATAL severity events.
Figure 6. Event log. The component implementation calls a function to generate the event. The base class retrieves the time tag from the time source component. The component sends the event to the event log component, which reads it from the port queue and sends it to the ground.
Channels, also known as Telemetry Channels, or just Telemetry, represent the current reading of some portion of the system state. This state is either restricted to "send on change" or "send per update" even if the update is already the current value. Channels are broken up per component and are typically sampled at a set rate and downlinked. Channels are id, time, and value triples and are defined per component with the following properties:
Code in the component-specific generated base class provides a function to call to set the current value for a channel id. This function must be supplied with a typed argument for the value. It will request the time tag internally. The code generator automatically adds ports for retrieving time tags and sending channelized data.
The telemetry database acts as a double-buffered store for telemetry values. Components are free to update channels at
any time; however, the current value will be read from the telemetry database and sent to the ground at a set rate.
Components using this service should hook up the telemetry port to the telemetry database (Svc::TlmChan).
Figure 7. Telemetry database. The telemetry database has a double-buffered array of telemetry buffers. The base class function retrieves the time tag from the time source component and then writes the updated value to the telemetry database component. The telemetry database is called periodically to send the current set of telemetry to the ground.
[!NOTE] the periodic call to the telemetry database is typically made by a rate group.
Parameters are traditional means of storing non-volatile states in the embedded system. The framework provides code generation to manage parameters defined by a component. Parameters are defined by the following properties:
The code generator automatically adds ports for retrieving parameters. During initialization, a public method in the class is called which retrieves the parameters and stores copies locally. Calls can reoccur if the parameter is updated. The code-generated base class provides a function to call for each parameter to retrieve the stored copy; and an implementation class can retrieve the value whenever the parameter value is needed.
The framework provides the ability to store these parameters in the parameter database (Svc::PrmDb). This component
provides ports to get and set parameters, which are stored in a file to persist across reboots.
Figure 8. Parameter manager. The parameter manager or database loads the file containing parameters from the file system during initialization. The initialization subsequently calls loadParameters() on components with parameters. Components can set and retrieve parameters. The parameter manager saves the updated values to the file system via the set and save commands auto-generated for every parameter; the set command updates the value of the parameter locally within the component that owns it, and the save command pushing the current value of the parameter to non-volatile storage, meaning it will persist within the files of the system across system resets.
The Svc components use serialize ports to generically handle port data of different types to support uplink and
downlink.