Fprime Topology Development

Skill: F Prime Topology Development

Covers everything between "a component exists" and "a deployment runs". Most work here extends an existing topology rather than creating one from scratch. Component-level work belongs to fprime-component-development; CMake and build-cache mechanics belong to fprime-cmake-build-system.

Canonical references: building the topology, port/component/topology overview, autocoded functions. Working exemplar: TestDeploymentsProject/Ref/Top/.

1 — Anatomy of a Top/ directory

Definition and membership are separate: an instance defined in instances.fpp only joins the topology when named by instance <name> inside deployment topology <Name> { ... }. Defined-but-unused instances are legal and are neither constructed nor started.

2 — Instance definitions

• Passive: instance posixTime: Svc.PosixTime base id 0x10020000
• Queued: add queue size ...
• Active: add queue size ..., stack size ..., priority ..., and cpu ... where affinity matters.

Base IDs must be unique and non-overlapping across the whole deployment, including subtopologies. Ref uses 0xDSSCCxxx (deployment / subtopology / component / reserved low 12 bits for the instance's own events, commands, channels) — see the header comment in instances.fpp. Subtopologies offset from a configurable BASE_ID constant.

Thread priorities, stack sizes and affinities are project- and platform-specific; take them from the project's own conventions rather than from a generic default.

3 — Connections

Pattern graphs — one specifier per service wires the whole deployment's command, event, telemetry, text-event, parameter, time, and health ports, each naming the serving instance, e.g. telemetry connections instance CdhCore.tlmSend. Prefer these over hand-wiring service ports.

Direct graphs — named blocks connections <Name> { a.out -> b.in }. Group by subsystem or by instance pair; port arrays are indexed, and indices should come from an FPP enum (e.g. Ports_RateGroups) rather than bare integers.

Matched ports — match <a> with <b> in the component model forces parallel arrays to be connected at identical indices; FPP errors when they are not. See common port patterns.

Rate group scheduling — a timer drives rateGroupDriverComp.CycleIn; each CycleOut[<group>] drives one ActiveRateGroup.CycleIn, whose RateGroupMemberOut[<slot>] ports call each member's schedIn-style port synchronously, in slot order. Rates come from the DividerSet passed to RateGroupDriver::configure in the topology .cpp. See rate groups.

Unconnected output ports assert when invoked. A port that is optional by design can be guarded with isConnected_<port>_OutputPort(portNum) in the C++ implementation.

4 — Phased initialization

setupTopology calls autocoded functions in a fixed order: initComponents → setBaseIds → connectComponents → configComponents → project configureTopology → regCommands → loadParameters → startTasks. Teardown reverses it: stopTasks → freeThreads → tearDownComponents → deinitComponents. Never start tasks or register commands before connections exist.

Per-instance C++ can be attached in FPP instead of the .cpp, via init specifiers on an instance body:

instance $health: Svc.Health base id CdhCoreConfig.BASE_ID + 0x002000 \
  queue size CdhCoreConfig.QueueSizes.$health \
{
  phase Fpp.ToCpp.Phases.configComponents """
  CdhCore::health.setPingEntries(...);
  """
}

Phases are mandatory inside subtopologies; deployments may use either. Phase list and semantics: subtopology how-to.

5 — Subtopologies

Use one when a group of instances is only meaningful together and is reused across deployments (comms stack, C&DH core, data products). Do not create one for a single component.

Consume an F Prime core subtopology by instantiating it and wiring its declared topology ports (CdhCore.Subtopology.tlmSendRun), not the inner instances; a locally developed subtopology may instead be imported and its instances referenced qualified (MySubtopology.rateGroup.CycleIn). Its PingEntries live in GlobalDefs::PingEntries and its SubtopologyTopologyDefs.hpp must be included by the deployment's TopologyDefs.hpp. Configuration is overridden with a config module. See subtopologies and develop a subtopology.

6 — Wiring a new component into an existing deployment

1. Define the instance in instances.fpp with a fresh base ID.
2. Add instance <name> to the topology.
3. Connect its functional ports in a connections block; attach schedIn-style ports to the appropriate rate group slot.
4. Health: for an active instance with Svc.Ping ports, add PingEntries::<Module>_<instance> { WARN, FATAL } to <Dep>TopologyDefs.hpp. See health checking.
5. Telemetry: list every new channel in a packet in *Packets.fppi or in the trailing omit { ... } block.
6. Project-specific setup (allocators, configure() calls) in configureTopology or a configComponents phase.
7. Register the new module and regenerate — see fprime-cmake-build-system. Adding an FPP file to Top/ also requires it in the topology module's AUTOCODER_INPUTS.

7 — Failure modes