Links and Bindings

A link is a way to reach a target: a driver, an optional transport and a gateway. A target has one or more links; each step chooses its link (via direct), else the default link is used, so one run may use several links to the same target. The topology declares the links; the reconciler binds each of them to running instances and publishes whether the target is ready.

targets:
  flatsat-1:
    platform: platform-v3@1.4.0
    environments: [AIT, IVV]
    links:
      # Packets in CCSDS frames under COP-1; the flatsat has its own spacecraft identifier.
      nominal:
        driver: platform-v3-ccsds@4
        transport: ccsds-tc@1
        gateway: bench-rf-1
        default: true
        params: {scid: 0x2C6, tm_length: 256}
      direct:  {driver: tcu-can@2, gateway: bench-can-1, components: [tcu]}

Keys of a link#

Link names are identifiers (a letter, then letters, digits and _): they are the instances of the standard link component (link[nominal]).

The default link#

Each target declares exactly one default: true link, even when it has only one link (topology::no-default-link, topology::several-default-links). The default link carries the whole catalogue. It is the link of steps without via, of direct telecommands without --link, of file transfers, and the one whose availability decides whether a manual run can start in orbit.

Version requirements#

Drivers and transports are referenced by software name and version requirement:

Binaries of drivers are versioned and kept at the version the topology requires, so that an archive of raw telemetry can be decoded again by the same driver.

Links that carry part of the catalogue#

A link may carry only some components, such as the CAN bus of a bench that reaches the TCUs only:

direct: {driver: tcu-can@2, gateway: bench-can-1, components: [tcu]}

• The components exist in the catalogue (topology::unknown-component) and the list is not empty (topology::no-component).
• The default link cannot be restricted (topology::default-link-restricted).
• A telecommand of another component sent through this link is refused: when a run is resolved (run::link-component), by the API for a direct telecommand (tc::link-component), and by the executor as a safeguard.
• Its driver only has to cover the components the link carries: tcu-can covers tcu.* and nothing else. For components imported from another package, the driver of that package may serve the link (see Bindings).

Gateways and tag constraints#

A gateway is either an instance name or a constraint on the tags it registers:

gateway: bench-rf-1                  # this instance
gateway: "any(tag: sband)"           # any gateway tagged sband
gateway: "any(tag: sband, tag: eu)"  # any gateway carrying every listed tag

In an inline YAML mapping ({…}), quote the constraint. During a pass, the gateway of a constrained link is the one serving the station of the pass: a gateway serves a station when it carries the station name as a tag (gs-a) in addition to the tags of the constraint. A link to a named gateway (a bench) ignores stations. See Passes.

Choosing a link#

In a procedure, via selects a link, and the link component addresses its COP-1 state:

step "TCU answers" retry 3 times every 2 s
  uses sat: platform-v3
  input tcu: tcu_id
  send ping to sat.tcu[tcu] via direct
  expect sat.tcu[tcu].responding is true within 5 s

Links belong to targets, not to platforms: the compiler accepts any link name in via and link[…], and the name is checked when a run is resolved against its targets. For a direct telecommand: stellar send flatsat-1 'tcu[TCU2].ping' --link direct.

Every sample carries the link it arrived through (link field, Stellar-Link header).

Bindings#

For each link of each target, the leader of the reconciler binds registered instances:

1. Gateway. The named instance, or a gateway carrying every tag of the constraint.
2. Driver. A driver whose software is the name of the link's driver, whose version satisfies the requirement (@4), whose catalogue requirement (platform-v3@^1.4) accepts the version of the target's catalogue, and whose coverage includes every telecommand and measure of the components the link carries (the generated measures of files and stream excepted). The catalogue requirement may also name a package the platform imports the components of the link from (hsc-100@^1.0 for a link carrying the imported camera): see Imports, drivers and procedures.
3. Transport, when the link has one: a transport of that name and a satisfying version.
4. Chain. The output of the driver is the input of the transport, and the output of the transport (or of the driver, without transport) is the uplink link type of the gateway; the parameters of the link satisfy the schemas of the driver and the transport. See Drivers, Transports and Gateways.

Instances must be alive (a heartbeat within three periods) and not degraded. When several fit:

• a valid binding is kept while its instances still fit: a new instance only takes new links;
• otherwise the fitting instance serving the fewest links is chosen, by name on a tie;
• the links of a target that go through the same gateway share their driver: it decodes the frames of that gateway once, without duplicate samples or chunks.

An instance that disappears (its key expires in stellar_instances) loses its links, and the targets concerned are no longer ready until another instance takes them.

What a binding contains#

Bindings are stored in the stellar_bindings bucket, key <target>.<link>, and delivered to each driver, transport and gateway by its bindings control verb:

Each encode and uplink subject has its durable consumer (encode_<codec>_<target>, uplink_<gateway>_<target>), shared by the links with the same codec or gateway and delivering one message at a time: a telecommand is encoded and sent once, and the order of the telecommands of a target is kept, even while links move between instances.

Readiness#

A target is ready when all its links are bound. Otherwise stellar_readiness gives one reason per unbound link, the first refusal met:

link `nominal`: no driver `platform-v3-ccsds` registered
link `nominal`: driver `ccsds-1` is `platform-v3-ccsds@3.2.0`, `platform-v3-ccsds@4` is required
link `nominal`: driver `ccsds-1` implements `platform-v3@^1.3`, not `platform-v3@2.0.0`
link `camera`: driver `hsc-100-csp-1` implements `hsc-100@^2.0`, but `cubesat-6u@1.0.0` imports `hsc-100@1.0.0`
link `camera`: driver `hsc-100-csp-1` implements `hsc-100@^1.0`, but the link carries `obc`, which `cubesat-6u@1.0.0` does not import from `hsc-100`: give it `components: [imager]`
link `nominal`: driver `ccsds-1` does not cover 2 of `platform-v3@1.4.0`, such as `tcu.reboot`
link `nominal`: no gateway registered
link `direct`: driver `tcu-can-1` produces `space-packet`, gateway `bench-can-1` carries `can`: the link needs a transport
link `rf`: parameters of link in `IVV` refused by transport `csp1-kiss-1`: …
link `direct`: gateway `bench-can-1` is degraded: bus off

In order: no instance of that software is alive; wrong driver version; catalogue version not accepted by the driver; incomplete coverage; no gateway fits the name or the tags; the chain does not hold; the parameters are refused by a schema; an instance reports itself degraded.

GET /v1/topology returns each target with its links, their bindings, readiness, reasons and leases; GET /v1/instances/{kind}/{instance} shows what a driver covers and misses against the current configuration. The web console shows both in its Topology and Instances views. See the monitoring API.