Extending Stellar Control

The core of Stellar Control never touches a byte of a target. Everything that depends on a platform, a medium or a downstream system lives in external components: processes outside the MCS that talk to it through NATS only (or, for pass feeders, through the HTTP API). This section explains how to write them.

The components you can write#

flowchart LR
    subgraph MCS["Core of the MCS"]
      EX[Executor]
      CO[Compute stage]
      RE[Reconciler]
    end
    EX -- "SemanticTc<br/>stellar.tc.encode.*" --> D[Driver]
    D -- "unit<br/>stellar.tc.wrap.*" --> T[Transport]
    T -- "frame<br/>stellar.tc.uplink.*" --> G[Gateway]
    D -. "frame (no transport)" .-> G
    G -- "raw frame<br/>stellar.tm.raw.*" --> T
    T -- "unit<br/>stellar.tm.unit.*" --> D
    D -- "RawSample[]<br/>stellar.tm.decoded.*" --> CO
    RE -- "bindings, credentials" --> D & T & G
    MCS -- "JetStream consumers" --> C[Output connector]
    F[Pass feeder] -- "HTTP" --> API[API]

The contract is the interface#

The contract is JSON over NATS, independent of any language: registration, heartbeats, control verbs, bindings and the data plane. The MCS checks it at registration and binds only the instances that fit the topology. The NATS contract reference lists every subject, header and message; stellar schema <kind> prints the JSON Schema of each message.

Two SDKs implement it, so that a component only declares what it does:

Both SDKs handle the same chores: the nkey key pair, registration with retries, the JWT issued by the reconciler and its renewal, heartbeats, the common control verbs (status, credentials, bindings, reregister), subscriptions derived from the bindings, JetStream consumers, telecommand events (ACK 1 and ACK 2), deadlines, fragments and reconnection.

A component in another language sends the same messages: nothing in the MCS knows which SDK, if any, a component uses.

Choosing#

• Python for a quick integration, a bench instrument, a text protocol, a connector or a feeder script. The examples in examples/python carry a SCPI power supply into the MCS in a few dozen lines each.
• Rust for flight links: CCSDS framing, COP-1, CFDP, strict timing, test vectors replayed bit for bit, and a Prometheus endpoint.
• Any language when a component must live in an existing code base: follow the NATS contract.

Layering#

The repository enforces one-way dependencies (scripts/check-layers.py, run in CI): sdk ← core ← tooling, and examples depend on the SDK only. A driver embeds the contract and the SDK, never the core; the core is shipped without the SDK. What an example does, a team outside the MCS can do.

Example components#

All of them are built on the SDK alone, and are the best starting points.

How a component joins a target#

1. The topology declares a link of a target with a driver (by name and version, platform-v3-ccsds@4), an optional transport and a gateway (by name, or a tag constraint such as any(tag: sband)).
2. The component starts with bootstrap credentials limited to registration and heartbeats, and registers: software name and version, and what it implements.
3. The reconciler checks the registration, binds the instance to the links it fits, issues it a JWT with exactly the permissions of its bindings, and sends it its bindings.
4. The component subscribes to the subjects of its bindings; the target becomes ready when every link has a driver, a transport when declared, and a gateway bound.

See Drivers, Transports and Gateways for the binding rules seen from the topology.