Catalogue Packages

A catalogue describes a platform model, not one satellite: every target that implements platform-v3@1.4.0 shares its components, measures, derived measures, telecommands, alarms, files and streams. The MCS only ever handles this semantic view; the bytes stay inside the drivers.

A catalogue is a YAML file, packages/<name>/catalogue.yaml in the configuration repository. YAML is an exchange format as much as an input format: a subsystem team can generate its catalogue in CI from its types, its ICD or its TM/TC database, and publish it as a versioned package. The compiler checks a generated catalogue exactly like a hand-written one.

A first catalogue#

The catalogue of platform-v3, from examples/config, shortened:

package: platform-v3
version: 1.4.0
status: released

enums:
  tcu_id: [TCU1, TCU2, TCU3]
  tcu_operating_mode: [STANDBY, AUTOTEST_CATHODE_HOT_STANDBY, THRUST_MODE, SAFE_MODE]

components:
  tcu:
    instances: tcu_id
    measures:
      responding: {type: bool, max_age: 30s}   # produced on board: reply to ping
      mode: {type: tcu_operating_mode}
      anode_voltage:
        raw: u16
        type: f32
        unit: V
        calibration: {polynomial: [0.0, 0.005]}
        limits: {soft: [5 V, 280 V], hard: [0 V, 300 V]}
    telecommands:
      ping:
        changes_state: false
        verify: [{responding: true, within: 5s}]
      set_mode:
        args:
          mode: {type: tcu_operating_mode}
        verify: [echo, {mode: args.mode, within: 10s}]

Top-level keys#

Unknown keys are errors: every mapping of the catalogue refuses fields it does not know.

Status#

status is a policy, applied by the environments, not a workflow. A target engaged in an environment without allow_draft must implement a released catalogue (topology::draft-not-allowed at compile time), and a run refuses draft packages there (run::draft-not-allowed). How a draft becomes released (merge request, approvals) is the review process of the team on the Git repository: the MCS imposes no editing or validation role. See Environments and Policies.

Enums#

enums:
  tcu_id: [TCU1, TCU2, TCU3]
  obc_mode: [NOMINAL, SAFE, MAINTENANCE]

• Enum names and values are identifiers: a letter, then letters, digits and _.
• An enum has at least one value, and no value twice.
• An enum lists the instances of a component (instances: tcu_id), or types a measure or an argument (type: tcu_operating_mode).
• No anonymous duplicate. A measure or argument may declare an inline enum with type: enum and values: [A, B], but only when no named enum has these values: otherwise the compiler refuses it (catalogue::anonymous-enum) and asks for type: <named enum>. One source of truth per enum.

Components and instances#

A component groups measures, derived measures, telecommands and alarms. It carries its instances: with instances: tcu_id, everything in the component is indexed by the values of the enum.

Procedures address a measure as role.component[instance].measure and a telecommand target as role.component[instance]: sat.tcu[TCU2].mode, send ping to sat.tcu[tcu]. For a single-instance component, the index is omitted: psu.output_enabled. See Syntax and Names.

One namespace per component#

Measures, derived measures, telecommands and alarms of a component share one namespace: a name cannot be both a measure and a telecommand (catalogue::name-collision). The reason is the alarm of the limits of a measure, which bears the name of the measure (tcu[TCU1].anode_voltage).

Reserved names#

The MCS generates standard components and enums:

A catalogue that defines a component link, or an enum link_id or fop_state, cannot be used by a target (topology::reserved-name).

Descriptions#

Components, measures, derived measures, telecommands, arguments and alarms accept a description in free text:

components:
  psu:
    description: The bench power supply feeding the platform.
    measures:
      voltage: {type: f32, unit: V, max_age: 5s, description: Output voltage.}

Editor hovers, the web console and GET /v1/targets/{target}/catalogue show them. A description is not part of the compiled catalogue: rewording it changes neither the hash of the catalogue nor the binding of the drivers, only the configuration revision.

Types, units and durations#

Units apply to numeric types only (catalogue::unit-on-non-numeric). A unit is a symbol with an optional prefix, combined with * (or ·), / and integer powers ^:

Prefixes n, u (or µ), m, k, M and G apply to the SI symbols (mV, kHz, Mbit/s, MHz), not to min, h, d, degC, deg or %. Examples: V/s, m/s^2, kbit/s, Mbps.

Units are checked by dimension: subtracting degC from V is a compile error, and a quantity is converted when its unit is compatible (300 mV into V).

Quantities are written as a number, a space and a unit: 5 V, 10 V/s, -20 degC, 256 kbit/s. Durations are a number followed by d, h, min, s, ms, us or ns, with or without a space: 30s, 10 s, 3 min.

Checking a catalogue#

The catalogue is validated by a JSON Schema generated from the types of the compiler, then by the compiler itself:

stellar schema catalogue > catalogue.schema.json   # for editors and CI
stellar check examples/config                      # every catalogue, topology and procedure

Diagnostics are written for operators, with a stable code (catalogue::unknown-type), the faulty line and, where possible, a suggestion. The VS Code extension shows them live and completes the keys from the same schema.