docs/reference/system-functional/framework.md
The F Prime Framework (Fw) provides the foundational types, base classes, port interfaces, and serialization infrastructure upon which all F Prime components are built. It defines the core abstractions of the component architecture — objects, ports, components, commands, events, telemetry, parameters, time, buffers, and data products — along with the serialization mechanisms that allow these abstractions to communicate across port boundaries.
All objects in F Prime derive from a common base class that provides identity (name) and optional registration with an object registry. Components are the primary unit of software in F Prime and come in three kinds:
Components interact exclusively through ports. The framework provides base classes that the autocoder uses to generate component infrastructure from FPP models.
Ports define typed interfaces for inter-component communication. Each port specifies a set of arguments and an optional return type. The framework provides base classes for input and output ports. At system startup, output ports are connected to input ports as defined by the topology. Port calls are the only mechanism for inter-component communication in F Prime.
All data passed between components is serialized into byte buffers. The framework provides a serialization infrastructure that supports:
Serialization enables data to be passed across port boundaries and transmitted to or from a ground system.
The command infrastructure provides the mechanism for external systems (ground or sequencers) to invoke operations on components. Commands are defined in FPP models and consist of:
When a command is received, it is deserialized from a command buffer, dispatched to the implementing component, and a completion status is returned to the command source. See Command Dispatch for details on command routing and status tracking.
Events are time-tagged log entries that record system activities and anomalies. Each event has:
Events are serialized and sent to event management services for distribution and downlink. A separate text event port provides pre-formatted human-readable strings for console logging. See Event Management for details on event collection and handling.
Telemetry channels provide a mechanism for components to publish named data values representing system state. Each telemetry channel has:
Telemetry values are serialized and sent to telemetry storage services, which collect them into packets for downlink. Telemetry packets can hold multiple channel values and are formatted with channel IDs and timestamps. See Telemetry (Channel-based) and Telemetry (Packetized) for storage and downlink options.
Parameters are named configuration values stored in non-volatile memory that can be read at startup and updated during operation. The framework provides ports for:
Parameters are defined in FPP models and managed by a parameter database service. See Parameters for details.
The framework provides a time representation that includes a time base (project-specific), a time context, seconds, and microseconds. Time values are used throughout the system to tag events and telemetry. A separate time interval type represents durations rather than absolute timestamps. Time source components implement the time port to provide the current system time to all components that need it. See Time Services for available implementations.
The framework provides a buffer type that wraps a pointer to allocated memory along with its size and an origin-tracking context value. Buffers avoid copying data by passing references to allocated memory between components. The framework defines ports for requesting buffers from a buffer manager and for sending buffers between components. Buffers must be checked for validity before use, as allocation may fail. See Buffer Management for allocation strategies.
Communication buffers provide the serialization containers for data that is transmitted between the flight software and external systems. The framework defines a base packet class with type identification and a communication buffer class for holding serialized packet data. Command packets, telemetry packets, and other data types extend this base for their specific needs. See Communication Stack for the data path between flight software and external systems.
Data products are structured file data intended for downlink. The framework defines:
The serialized container format includes a header, a header hash for integrity, data records, and a data hash. Ports are provided for requesting, getting, sending, and responding to data product buffer operations. See Data Products for the full lifecycle.
File packets provide the serialization format for transferring files between the flight software and ground system. This supports both uplink (ground to flight) and downlink (flight to ground) file transfers. See File Management for file transfer operations.
The framework provides reusable data structure implementations including maps and other collections used internally by framework services and components.
The framework includes support for hierarchical state machines that can be attached to components. State machines are defined in FPP models and auto-generated into C++ implementations. They provide a structured way to manage complex component behavior with well-defined states, transitions, and actions.