Skill: F Prime Component Design (FPP)

The design phase codifies requirements into an FPP model — the single source of truth for the component's interface. The FPP compiler generates C++ base classes, test harnesses, and dictionaries from this model.

For FPP syntax and modeling details, see the FPP User's Guide. For component/port/command kinds, see Selecting Component, Port, and Command Kinds.

Reference the F Prime design patterns where possible — standard solutions exist for common needs:

• Rate Group Pattern — docs/user-manual/design-patterns/rate-group.md
• Health Checking — docs/user-manual/design-patterns/health-checking.md
• Manager-Worker — docs/user-manual/design-patterns/manager-worker.md
• Application-Manager-Driver — docs/user-manual/design-patterns/app-man-drv.md
• Common Port Patterns — docs/user-manual/design-patterns/common-port-patterns.md
• Hub Pattern — docs/user-manual/design-patterns/hub-pattern.md
• Subtopologies — docs/user-manual/design-patterns/subtopologies.md

STOP — Confirm Before Designing

Before writing any FPP:

1. Requirements must be confirmed (see fprime-component-requirements).
2. Ask the user about any ambiguity in:
   • Port types (does a suitable port already exist, or do we need a new one?)
   • Command argument types and names
   • Telemetry channel update frequency semantics (on-change vs. periodic)
   • Event severity levels (DIAGNOSTIC, ACTIVITY_LO, ACTIVITY_HI, WARNING_LO, WARNING_HI, FATAL)
   • Parameter default values
   • Whether to use existing F Prime standard ports (Fw.Signal, Svc.Sched, Svc.Ping, etc.)

Step-by-Step Process

Step 0 — Scaffold with fprime-util

Start with fprime-util new --component for the base structure. This generates the initial directory layout, CMakeLists.txt, and FPP stub.

Step 1 — Choose Component Kind

Based on requirements (see docs/user-manual/framework/component-and-port-selection.md for the full decision guide):

Ask the user if unsure. The component kind determines thread ownership and port synchronization semantics.

Step 2 — Define Ports

For each interface requirement, define input/output ports. Port kinds:

• sync input — executes in caller's thread
• async input — enqueued, executes in component's thread
• guarded input — sync with component-wide mutex

See the FPP User's Guide for port definition syntax.

Standard framework ports to consider including:

If the component is active, it probably needs health-ping support. Requirements should imply whether rate-group scheduling is needed. Ask the user only if unsure about which standard services to connect to.

Step 3 — Define Commands, Telemetry, Events, Parameters

Follow the FPP User's Guide for syntax. Follow F Prime Style Guidelines for naming conventions:

• Commands: UPPER_SNAKE_CASE
• Telemetry channels: PascalCase
• Events: PascalCase
• Parameters: PascalCase

For each construct, derive names, types, and semantics from the confirmed requirements. Define an event for each command that describes what the command did, including the command arguments, so the implementation can emit it (CPP-37). Every event emission must be traceable to a single call site (CPP-36): give each site its own event, or an argument (typically an enum) whose value differs at every site. Ask the user if:

• The command kind (sync/async/guarded) is ambiguous
• The event severity level is unclear
• Parameter defaults or valid ranges are unspecified

Step 4 — Build and Verify

fprime-util build

The FPP model should compile and generate the base class. Fix any FPP errors before proceeding.

Step 5 — Confirm Design with User

Present the FPP model to the user and wait for confirmation. The model is the interface contract — implementation and tests are written against it.

New Port Definitions

If a requirement needs a port type that doesn't exist:

1. Ask the user what the port should carry (arguments, return type).
2. Create a new .fpp file in an appropriate Ports/ directory. See the FPP User's Guide for port definition syntax.
3. Add to CMakeLists.txt and register with add_fprime_subdirectory.

Anti-Patterns

• Guessing port types — always check existing ports first and ask
• Using async ports for cyclic/deadline work
• Omitting time get port when telemetry or events are defined
• One event emitted from several sites with indistinguishable arguments (CPP-36)
• Hardcoding opcodes/IDs without checking for conflicts (let the build system assign them, or ask the user for the base ID)
• Using bare primitive types (int, unsigned) — use U32, FwSizeType, etc. (CPP-3, CPP-28)