Alarms

Alarms are declared in the catalogue, next to the measures they watch. The alarm service evaluates them on real-time samples, manages their lifecycle (raised, acknowledged, cleared, shelved) and can run a procedure when one is raised. This page covers the declarations; the lifecycle, acknowledgement and shelving are in Alarm Handling.

components:
  tcu:
    instances: tcu_id
    measures:
      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}
    alarms:
      cathode_overheat:
        severity: critical
        when: stable(cathode_temperature > 1200 degC, 5 s)
        on_raise: run "Safe TCU"

Two sources of alarms#

On a multi-instance component, every alarm exists per instance: tcu[TCU1].cathode_overheat and tcu[TCU2].cathode_overheat have their own state. On a single-instance component, it is written without index: eps.undervoltage.

Because the alarm of the limits bears the name of the measure, measures, derived measures, telecommands and alarms of a component share one namespace (catalogue::name-collision).

Limits#

Limits are declared on the measure (or the derived measure) itself: see Measures, Limits and Calibration.

temperature:
  raw: i16
  type: f32
  unit: degC
  calibration: {polynomial: [0.0, 0.1]}
  limits: {soft: [-20 degC, 60 degC], hard: [-40 degC, 85 degC]}

Named alarms#

when uses the syntax of derived measures, temporal functions included. Use stable to debounce a condition, or a window function to watch a trend:

alarms:
  cathode_overheat:
    severity: critical
    when: stable(cathode_temperature > 1200 degC, 5 s)
  stream_gap:                       # on the standard stream component
    severity: warning
    when: delta(gaps, 30 s) > 0
  silent:
    severity: warning
    when: age(responding) > 2 min

A condition that is not boolean is refused (expr::type-mismatch).

How conditions are evaluated#

• Real time only. Deferred samples never raise an alarm: they are archived and analysed afterwards.
• Same evaluation as the compute stage. The alarm service reads the real-time samples of PARAMS, measures and derived measures, keeps the same history and schedules the same deadlines: cathode_overheat is raised 5 s after the threshold is crossed, without a new sample.
• Unknown changes nothing. A condition whose value is unknown (no value, empty window) leaves the alarm in its state.

Reactions: on_raise#

on_raise: run "Safe TCU"

A reaction runs a procedure on the target of the alarm, once per activation: when the alarm goes to ACTIVE_UNACK from NORMAL or CLEARED_UNACK because of its condition. An increase of severity, a shelved alarm or the end of a shelving triggers nothing.

The compiler checks the procedure against the libraries that depend on the platform:

• it exists in such a library (procedure::unknown-reaction);
• it sends no hazardous telecommand, directly or through its calls (procedure::hazardous-reaction): a reaction runs without confirmation;
• it declares exactly one role, of the platform of the alarm, and, for a multi-instance component, exactly one input of the enum of its instances; for a single-instance component, no input (procedure::invalid-reaction). The executor binds them to the target and the instance of the alarm.

procedure "Safe TCU"
  uses sat: platform-v3
  input tcu: tcu_id

  step "Command safe mode"
    send safe_mode to sat.tcu[tcu]
    expect sat.tcu[tcu].mode is SAFE_MODE within 10 s

At run time, a run holding the target is suspended first, and the reaction must be allowed in the environment; in in_orbit, it is launched only when a link is available. See Alarm Handling for the full sequence.