Measures, Limits and Calibration

A measure is a value the platform produces: a voltage, a mode, a flag, the last telecommand received. The driver decodes it from the telemetry; the MCS calibrates it, checks its limits, stores its current value and archives every sample. This page lists every key of a measure.

components:
  tcu:
    instances: tcu_id
    measures:
      responding: {type: bool, max_age: 30s}
      mode: {type: tcu_operating_mode}
      last_telecommand: {type: bytes}
      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]}
      cathode_temperature: {type: f32, unit: degC}

Keys of a measure#

Names are identifiers (a letter, then letters, digits and _), unique in the component across measures, derived measures, telecommands and alarms.

Types#

Numeric types are explicit (i32, u16, f32…). Prefer bytes to a hexadecimal string: how bytes are displayed is a choice of the interface. An enum measure takes the values of a named enum:

enums:
  obc_mode: [NOMINAL, SAFE, MAINTENANCE]
components:
  obc:
    measures:
      mode: {type: obc_mode, description: Operating mode.}

An inline enum (type: enum, values: [ON, OFF]) is accepted only when no named enum already has these values (catalogue::anonymous-enum).

Freshness: max_age#

Every sample carries its ground reception time. max_age bounds the age of the current value that check (in a step) and requires (before a telecommand) accept: an older or absent value fails the check or rejects the telecommand. Measures without max_age are accepted whatever their age.

responding: {type: bool, max_age: 30s}   # produced on board: reply to ping

See Time and Freshness for the time references of a sample.

Limits#

limits: {soft: [5 V, 280 V], hard: [0 V, 300 V]}

• soft and hard are each [low, high], both optional. Bounds are numbers in the unit of the measure, or quantities in a compatible unit ([-20 degC, 60 degC], [300 mV, 5 V]).
• Limits apply to the physical value, after calibration.
• Soft limits should lie within the hard limits (catalogue::soft-outside-hard, a warning).
• Only numeric measures have limits (catalogue::limits-on-non-numeric).

Leaving the limits raises the alarm named after the measure (tcu[TCU1].anode_voltage): critical outside the hard limits, else warning outside the soft limits. Derived measures accept limits too. See Alarms and Alarm Handling.

Calibration#

The driver publishes typed raw values; the MCS applies the calibration declared in the catalogue and archives both the raw and the physical value.

anode_voltage:
  raw: u16                  # what the driver publishes
  type: f32                 # the physical value
  unit: V
  calibration: {polynomial: [0.0, 0.005]}

A calibration is exactly one of three forms:

# Thermistor: a table, linear between points (interpolation defaults to linear).
battery_temperature:
  raw: u16
  type: f32
  unit: degC
  calibration:
    table: [[0, -40.0], [1200, 0.0], [2600, 25.0], [4095, 85.0]]
    interpolation: linear

# Status code: an enumeration into the values of an enum
# (enums: {heater_state: [OFF, ON, FAULT]}).
heater_state:
  raw: u8
  type: heater_state
  calibration: {enum: {0: OFF, 1: ON, 2: FAULT}}

Rules:

• calibration requires raw (catalogue::calibration-without-raw), and raw is only meaningful with a calibration (catalogue::raw-without-calibration).
• raw is an integer or float type (catalogue::invalid-raw-type).
• A polynomial or a table produces a number: the measure is numeric. An enumeration produces an enum value: the measure is an enum.
• A raw value the calibration does not cover (outside the table, unknown or non-integer code) produces no sample; it is logged by the compute stage.

Calibration kept in the driver#

When the calibration is intellectual property, it stays in the driver, which publishes the physical value directly. Declare the measure without raw and calibration: the MCS then takes the value as physical and applies nothing.

temperature: {type: f32, unit: degC}   # calibrated by the driver

Such a measure has no raw value archived, so it cannot be recalibrated from its history.

Samples#

Each measure is published by the compute stage on stellar.param.<target>.<component>.<instance>.<measure> (stream PARAMS):

The current value table keeps the latest sample of each measure. See Measures and Current Values.

Coverage by drivers#

A driver declares the measures it covers (tcu.anode_voltage). The reconciler binds a driver to a link only when it covers every measure and telecommand of the components the link carries, except the generated measures of files and stream, which the MCS produces itself. See Links and Bindings.