Telecommands and Verification

A telecommand of the catalogue is semantic: a name, typed arguments and the rules the runtime applies around it. The driver turns it into bytes; the MCS checks its preconditions, follows its acknowledgements and verifies its effect on the measures. Four keys drive the runtime: changes_state (automatic retry), hazardous (confirmation), requires (preconditions) and verify (ACK 3).

components:
  tcu:
    instances: tcu_id
    telecommands:
      ping:
        changes_state: false
        verify: [{responding: true, within: 5s}]
      standby:
        requires: [{responding: true}]
        verify: [echo, {mode: STANDBY, within: 10s}]
      set_mode:
        args:
          mode: {type: tcu_operating_mode}
        verify: [echo, {mode: args.mode, within: 10s}]
      set_anode_voltage:
        args:
          voltage: {type: f32, unit: V, range: [0 V, 300 V]}
          ramp: {type: f32, unit: V/s, range: [1 V/s, 50 V/s], default: 10 V/s}
        verify: [echo]
      blank_firing:
        hazardous: true
        requires: [{mode: STANDBY}]

Keys of a telecommand#

On a multi-instance component, a telecommand is sent to one instance (send ping to sat.tcu[TCU2], stellar send sim-1 'tcu[TCU2].ping'); its requires and verify read the measures of that instance.

Arguments#

args:
  voltage: {type: f32, unit: V, range: [0 V, 300 V], description: Voltage to deliver.}
  ramp: {type: f32, unit: V/s, range: [1 V/s, 50 V/s], default: 10 V/s}
  mode: {type: tcu_operating_mode}
  data: {type: bytes}

Arguments are always named when sent. Their values are written like the inputs of a run: a quantity with its unit (100 V, converted into the unit of the argument), an enum value, a boolean, or bytes in hexadecimal. The compiler checks type, unit and range of the literal values of send … with; values coming from inputs are checked when the run is resolved; a direct telecommand is checked by the API (POST /v1/tc).

send set_anode_voltage to sat.tcu[tcu] with voltage = 100 V

stellar send sim-1 'tcu[TCU1].set_anode_voltage' 'voltage=100 V'   # ramp takes its default

changes_state and retries#

A telecommand is assumed to change the on-board state unless it says otherwise. Only a step whose telecommands are all changes_state: false is eligible for retry. A run that sends only such telecommands (and checks) holds a shared lease on its targets, and only such a telecommand may be sent directly while a run holds a shared lease on the target. See Retries and Leases and Crash Recovery.

hazardous#

A hazardous telecommand needs a confirmation before each send: in a step, every send of it follows its own ask operator "…" (a compile error otherwise). Who confirms depends on the environment (hazardous_confirmation): the operator alone in IVV, the operator then a supervisor in in_orbit, nobody where human orchestration is off. See Safety Rules and Hazardous Confirmations.

A hazardous telecommand without verify raises a compile warning (catalogue::hazardous-without-verify): its effect should be checked. The procedure of an alarm reaction may not send a hazardous telecommand.

Conditions#

requires and verify list conditions. A condition is written in one of two forms:

• a map of measure → expected value, with within in verify only: {mode: STANDBY, within: 10s}, {voltage: args.voltage, within: 3s}. Several measures in one map must all match. A plain number is taken in the unit of the measure; text is an enum value, a quantity (28 V) or an argument (args.mode);
• an expression, as a string: "mode is not SAFE_MODE", "anode_voltage < 50 V", "responding and mode is STANDBY". See Derived Measures for the syntax.

Conditions read the measures and derived measures of the component, and the arguments of the telecommand as args.<name>. Temporal functions are refused there: declare a derived measure (ping_answered: updated_at(responding) > sent_at(ping)) and name it in the condition.

requires: preconditions#

Preconditions are checked before ACK 1, on the current value table. A condition that is false, or that reads a value absent or older than its max_age, rejects the telecommand without encoding it: the REJECTED event gives the reason.

standby:
  requires: [{responding: true}]
blank_firing:
  hazardous: true
  requires: [{mode: STANDBY}, "cathode_ready"]

echo and within are refused in requires (catalogue::echo-in-requires, catalogue::within-in-requires).

verify: ACK 3#

ACK 3 is a predicate on measures, not a correlation of packets. It is evaluated only on samples received on the ground after SENT, so that a value older than the telecommand never verifies it:

• with within, the condition must become true within the window, which starts at SENT;
• without within, it is judged on the first samples of its measures received after SENT, waited for at most executor.ack_timeout (10 s by default).

Every verification must hold for VERIFIED. A condition without window that is false gives VERIFY_FAILED; a window that elapses gives VERIFY_TIMEOUT.

echo asks the driver, the only one that knows the bytes, to compare the frames it receives with the telecommands it encoded recently. It publishes an ECHO event with conforming; a non-conforming echo gives VERIFY_FAILED.

set_voltage:
  args:
    voltage: {type: f32, unit: V, range: [0 V, 60 V]}
  verify: [{voltage: args.voltage, within: 3s}]
set_mode:
  args:
    mode: {type: tcu_operating_mode}
  verify: [echo, {mode: args.mode, within: 10s}]

verify and within are optional. Without verify, the telecommand goes from SENT to COMPLETE without ACK 3. That is the case of a time-tagged telecommand, executed later on board: its effect is checked afterwards by an explicit check, at the next pass for instance.

See Telecommand Lifecycle for the full state machine.

Parameters#

A component may declare parameters: on-board settings, such as the rate of a transmitter or the anode voltage of a TCU, whose value depends on the mode of the target. The topology gives their value per target and mode; configure <role> for <mode> sets them through the telecommand named by set and checks them through the measure named by readback. The whole mechanism is described in Modes and Parameters.

components:
  tcu:
    instances: tcu_id
    parameters:
      operating_mode:
        description: Operating mode of the TCU.
        type: tcu_operating_mode
        set: {telecommand: set_mode, arg: mode}
        readback: mode
      anode_voltage:
        description: Anode voltage, read back within the noise of the measure.
        type: f32
        unit: V
        range: [0 V, 300 V]
        tolerance: 2 V
        set: {telecommand: set_anode_voltage, arg: voltage}
        readback: anode_voltage
      anode_ramp:
        description: Rate at which the anode voltage is reached.
        type: f32
        unit: V/s
        range: [1 V/s, 50 V/s]
        set: {telecommand: set_anode_voltage, arg: ramp}

Rules checked by the compiler:

• A parameter is a number, bool or an enum value (catalogue::parameter-type).
• set names a telecommand of the component (catalogue::unknown-setter) and one of its arguments (catalogue::unknown-setter-argument), of the type and unit of the parameter (catalogue::setter-type-mismatch). Several parameters may share one setter, each through its own argument; two parameters on the same argument are refused (catalogue::duplicate-setter).
• Every other argument of a setter needs a default, since configure sends only the values of the parameters (catalogue::setter-argument-without-default).
• readback names a measure or derived measure of the component (catalogue::unknown-readback) of the type and unit of the parameter (catalogue::readback-type-mismatch).
• tolerance is for numeric parameters only (catalogue::tolerance-on-non-numeric), not negative and in the unit of the parameter (catalogue::invalid-tolerance).
• Parameters have their own namespace: a parameter may bear the name of a measure (anode_voltage above); param tells them apart in procedures.
• A multi-instance component has one parameter per instance: tcu[TCU1].anode_voltage.
• Parameters are part of the compiled catalogue: adding one changes its hash, and so the locks of the libraries that use it.

Telecommands of the standard components#

• files: the telecommands of the transfer protocol (list, read, write), and those a procedure sends to a file (delete_file, activate_file). An argument named file_id receives the file of the instance: send delete_file to sat.files[lttm] needs no with. See Files and Streams.
• stream: telecommands addressed to a stream (send start_stream to sat.stream[camera]).
• link: the COP-1 directives unlock and set_vr, generated for every target. See COP-1 and the Link Component.

Coverage by drivers#

A driver declares the telecommands it covers (tcu.set_mode). A link that carries a component needs a driver covering all its telecommands; otherwise it stays unbound with the reason (does not cover 1 of platform-v3@1.4.0, such as tcu.reboot). See Links and Bindings.