What Are F Prime Ports? Understanding NASA's Component Communication Interface

F Prime ports are typed message interfaces generated from the F Prime Component (FPP) language that enable compile-time safe communication between flight software components without exposing implementation details.

F Prime is an open-source flight software framework developed by NASA for embedded systems and robotic applications. At the heart of its modular architecture lie F Prime ports, which serve as the primary abstraction for inter-component communication. These ports are automatically generated from FPP (F Prime Component) language definitions, creating strongly-typed C++ interfaces that ensure data integrity across the system.

What Are F Prime Ports?

F Prime ports act as typed contracts that define exactly what data types components can exchange. Each port declaration specifies the precise signature of messages sent (output ports) or received (input ports), allowing the FPP compiler to generate strongly-typed C++ wrappers. This design catches type mismatches at compile time rather than runtime, critical for flight software reliability.

The port abstraction hides implementation details while exposing a clean, functional interface. When components communicate through ports, they invoke methods on generated C++ classes rather than directly calling each other, maintaining loose coupling and supporting modular design patterns essential for aerospace applications.

The F Prime Port Class Hierarchy

All F Prime ports inherit from a common base class defined in Fw/Port/PortBase.hpp. This hierarchy provides consistent connection management and optional tracing capabilities across the framework.

The inheritance structure follows this pattern:

• Fw::Port::PortBase – The generic foundation storing connection state (m_connObj) and implementing isConnected() checks
• Fw::Port::InputPortBase – Base class for all input ports receiving typed messages
• Fw::Port::OutputPortBase – Base class for all output ports sending typed messages (defined in Fw/Port/OutputPortBase.hpp)
• Fw::Port::InputSerializePort – Specialized input port for handling serialized data streams
• Fw::Port::OutputSerializePort – Specialized output port for transmitting serialized data

Input ports implement handler methods that components override to process incoming messages, while output ports provide the invoke() method to initiate communication.

Defining Ports in FPP

Port definitions begin in .fpp files using the F Prime Component language. The compiler translates these declarations into C++ classes that inherit from the appropriate base classes.

Consider a watchdog component that sends periodic health checks:

module Svc {
  port WatchDogPingPort {
    async input U32 cmd;      // Input port: receives a command word
  }
  
  component WatchDog {
    output port ping: WatchDogPingPort;   // Output port used by the component
  }
}

The FPP compiler generates:

• The WatchDogPingPort interface class
• The WatchDog component with an output port member named ping_OutputPort
• Type-safe methods ensuring only U32 values pass through the interface

Implementing Port Communication in C++

Components interact with ports through the generated C++ API. Output ports use the invoke() method (provided by OutputPortBase) to send messages, while input ports implement handler callbacks.

Here is how a watchdog component sends a ping command:

#include "Svc/WatchDog/WatchDog.hpp"

void WatchDog::handleTimer(void) {
    // Use the output port to send a ping command
    this->ping_OutputPort.invoke(0xDEADBEEF);
}

The invoke() method handles the mechanics of transferring control to the connected input port, managing the m_connObj pointer internally, and optionally emitting trace messages when FW_PORT_TRACING is enabled during compilation.

Connecting Ports in Topologies

Ports remain unconnected until runtime wiring occurs in topology files. The F Prime build system generates connection code based on topology definitions, typically found in files like FppTestProject/FppTest/topology/top_ports/TopPortsTopologyDefs.hpp.

Developers establish connections using generated setter methods:

#include "Svc/WatchDog/WatchDog.hpp"
#include "SomeOtherComponent.hpp"

void Topology::setup() {
    WatchDog wd;
    SomeOtherComponent soc;

    // Connect the WatchDog's ping output to the other component's input
    wd.set_ping_OutputPort(soc.get_ping_InputPort());
}

The set_<port>_OutputPort method stores the connection pointer inside the port's base class, enabling subsequent invoke() calls to reach the correct destination handler.

Runtime Connection Management and Diagnostics

F Prime ports provide built-in safety mechanisms to prevent invocations on unconnected ports. The isConnected() method, implemented in PortBase, checks whether the internal connection pointer (m_connObj) has been set.

Always verify connections before invoking:

if (wd.get_ping_OutputPort().isConnected()) {
    // Safe to invoke the port
    wd.get_ping_OutputPort().invoke(0);
}

When FW_PORT_TRACING is enabled in the build configuration, ports automatically emit trace messages for every invocation, helping developers debug communication flows in complex topologies. This tracing capability hooks into the base class invocation path without requiring changes to component business logic.

Summary

• F Prime ports are compile-time generated C++ interfaces that enable type-safe communication between components in the NASA fprime framework.
• All ports inherit from PortBase (Fw/Port/PortBase.hpp), with specialized input and output variants handling directional data flow.
• Port definitions begin in FPP files and generate classes with strongly-typed invoke() methods and connection management.
• Runtime wiring occurs in topology files, using generated set_<port>_OutputPort methods to bind output ports to input handlers.
• The isConnected() method and FW_PORT_TRACING flag provide runtime safety and debugging capabilities for mission-critical software.

Frequently Asked Questions

What is the difference between input and output ports in F Prime?

Input ports receive messages and require component implementations to override handler methods defined in the base class. Output ports send messages and provide the invoke() method to call connected input handlers. Input ports derive from Fw::Port::InputPortBase while output ports derive from Fw::Port::OutputPortBase, with each storing connection state in the shared PortBase parent class.

How are F Prime ports connected at runtime?

Runtime connections occur in topology files where developers call generated setter methods like set_ping_OutputPort() to assign an output port to a specific input port instance. The setter stores a pointer (m_connObj) in the base class, creating a direct call chain that invokes the input handler when the output port's invoke() method executes.

Can F Prime ports be used for debugging and tracing?

Yes. When the FW_PORT_TRACING configuration flag is enabled during compilation, ports automatically emit trace messages for every invocation. This occurs within the base class implementation in PortBase.hpp, allowing developers to monitor inter-component communication flows without modifying component code. The isConnected() method also aids debugging by preventing null pointer dereferences on unconnected ports.

What are serialized ports in F Prime?

Serialized ports (InputSerializePort and OutputSerializePort) are specialized variants that handle raw byte streams rather than typed C++ objects. These ports appear in Fw/Port/InputSerializePort.hpp and Fw/Port/OutputSerializePort.hpp, enabling communication between components that exchange data in serialized formats, useful for ground system interfaces or heterogeneous component integration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}