Targets

Everything the MCS controls is a target: a satellite in orbit, a flatsat on a bench, a laboratory power supply, an RF bench, an EGSE. A target implements a platform (a catalogue version), is engaged in some environments, and is reached through links. Targets are declared in topology.yaml, at the root of the configuration repository: this file is the desired state of the reconciler.

The topology file#

topology.yaml has four sections:

Its JSON Schema is printed by stellar schema topology; stellar check compiles it with the rest of the repository.

Declaring a target#

From examples/config/topology.yaml:

targets:
  sim-1:
    platform: platform-v3@1.4.0
    environments: [SIM, AIT]
    links:
      nominal: {driver: platform-v3-sim@1, gateway: sim-gw-1, default: true}
      direct:  {driver: platform-v3-sim@1, gateway: sim-gw-1}
  flatsat-1:
    platform: platform-v3@1.4.0
    environments: [AIT, IVV]
    links:
      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]}
  psu-lab-2:
    platform: lab-psu@1.0.0
    environments: [AIT, IVV]
    links:
      scpi: {driver: scpi-psu@1, gateway: lab-eth-1, default: true}
  sat1-fm:
    platform: platform-v3@1.4.0
    environments: [AIT, IVV, in_orbit]
    links:
      nominal:
        driver: platform-v3-ccsds@4
        transport: ccsds-tc@1
        gateway: "any(tag: sband)"
        default: true
        params: {scid: 0x2C5, tm_length: 256}

Rules checked by the compiler:

• A target name uses ASCII letters, digits, _ and -, starting with a letter (topology::invalid-name).
• The platform resolves to a catalogue of the repository (topology::unresolved-platform). Write an exact version: the target, its drivers and its procedures all refer to that version.
• Each environment exists and is listed once (topology::unknown-environment, topology::duplicate-environment); a target is engaged in at least one (topology::no-environment).
• A draft catalogue is refused in an environment without allow_draft (topology::draft-not-allowed).
• The catalogue does not use the names reserved by the standard link component (topology::reserved-name).

Modes and parameters#

The topology declares the modes of operation, and each target gives the value of the parameters of its catalogue in each mode. The current mode of a target, configure and the ground chain are described in Modes and Parameters.

modes:
  Nominal: {description: TCUs powered and ready to fire, default: true}
  Survival: {description: TCUs safe and anodes off}

targets:
  sim-1:
    platform: platform-v3@1.4.0
    environments: [SIM, AIT]
    # … links
    parameters:
      tcu.operating_mode: {Nominal: STANDBY, Survival: SAFE_MODE}
      tcu.anode_voltage: {Nominal: 200 V, Survival: 0 V}
      tcu[TCU2].anode_voltage: {Nominal: 180 V}
      tcu.anode_ramp: 50 V/s
  flatsat-1:
    platform: platform-v3@1.4.0
    environments: [AIT, IVV]
    # … links
    parameters:
      tcu.operating_mode: {Nominal: STANDBY, Survival: SAFE_MODE}
      tcu.anode_voltage: {Nominal: 200 V, Survival: 0 V}
      tcu.anode_ramp: 20 V/s
    # IVV qualifies the flatsat at a lower voltage.
    overrides:
      IVV:
        parameters:
          tcu.anode_voltage: {Nominal: 150 V}

• modes is an ordered map of modes, each with an optional description. When there are modes, exactly one has default: true: the mode of a target whose mode was never set (topology::default-mode). Mode names are identifiers, as procedures write them (configure sat for Survival).
• Keys name a parameter as procedures do: component.parameter, component[instance].parameter, or the parameter alone on a platform of one component. On a multi-instance component, a key without instance (tcu.anode_voltage) holds for every instance, and the key of an instance (tcu[TCU2].anode_voltage) wins for it. A key that names no component, instance or parameter of the catalogue is refused (topology::unknown-parameter).
• Values are one value for every mode (tcu.anode_ramp: 50 V/s) or a map by mode, possibly partial: a mode left out has no value from that key. A mode must be declared (topology::unknown-mode). Each value is checked against the parameter: type, unit (converted, 2.2 GHz for a parameter in Hz), range and enum value (topology::invalid-parameter-value).
• overrides.<environment>.parameters replaces values key by key and mode by mode in one environment of the target (topology::unknown-override-environment for an environment the target is not engaged in). On flatsat-1, tcu.anode_voltage is 150 V in Nominal in IVV, 200 V in AIT, and 0 V in Survival everywhere.

A parameter of an instance takes, in this order: the override of its own key, the value of its own key, the override of the key without instance, the value of the key without instance. An override of tcu.anode_voltage therefore does not change an instance that has a value of its own in that mode.

Modes and parameters are optional. Without modes, targets have no mode: in a repository with a topology, configure … for and param … in name an undeclared mode (procedure::unknown-mode), and a param without in fails at run time.

The catalogue of a target#

The catalogue of a target is the catalogue of its platform, plus the standard link component with one instance per declared link: sat1-fm has link[nominal], flatsat-1 has link[nominal] and link[direct]. See COP-1 and the Link Component.

GET /v1/targets/{target}/catalogue returns it, and the web console shows it on the page of the target. See the monitoring API.

Readiness#

A target is ready when every link has a registered, healthy and compatible driver, transport (when the link has one) and gateway, bound by the reconciler. The reconciler publishes the readiness of each target in the stellar_readiness bucket: ready, the configuration revision the target runs with, and one reason per unbound link, for instance:

link `nominal`: no driver `platform-v3-ccsds` registered
link `direct`: gateway `bench-can-1` is degraded: bus off

A run checks that its targets are ready at launch; GET /v1/topology and the Topology view of the web console show the reasons. See Links and Bindings for the binding rules.

Configuration revisions#

Each target runs with one configuration revision, the hash of a compiled snapshot. When a new snapshot is published (stellar compile --publish), the reconciler moves each target to it at its next safe point: a target that holds a run lease, or whose pass is in progress, keeps its revision until the run or the pass ends. The components bound to a target stamp its revision on their messages (Stellar-Config). See Compilation, Snapshots and Locks.

Output connectors#

The topology also declares the output connectors, external processes that store or relay the data of the MCS:

connectors:
  timeseries-db:
    data: [tm_raw, measures, tc_events, run_events, alarms]
    targets: [sat1-fm, flatsat-1, sim-1, psu-sim-1]
  partner-relay:
    data: [files]
    targets: [sat1-fm]

See Output Connectors for delivery, lag and credentials.