Your First Procedure

This tutorial uses the example configuration repository examples/config and its two simulated targets: sim-1, a satellite of the platform-v3 platform with three thruster control units (TCU), and psu-sim-1, a laboratory power supply. It takes about fifteen minutes and needs no hardware.

It assumes the binaries of Installation are on your PATH and a NATS server with JetStream listens on nats://localhost:4222.

1. Check and publish the configuration#

The repository holds catalogues, a topology, a library of steps and procedures and two simulations:

examples/config/
  topology.yaml
  packages/platform-v3/catalogue.yaml
  packages/lab-psu/catalogue.yaml
  packages/platform-v3-steps/{package.yaml, *.proc, stellar.lock}
  simulations/{platform-v3-sim.yaml, lab-psu-sim.yaml}
  runs/hot-standby.yaml

Compile it to check it, then publish it as the current configuration:

stellar check examples/config
stellar compile examples/config --publish nats://localhost:4222

stellar check prints the diagnostics and a summary such as Checked 4 catalogues, 1 library, the topology, 2 simulations (…): 0 errors, 0 warnings. stellar compile --publish stores the snapshot and prints its hash.

2. Start the services and the simulated targets#

In separate terminals (or in the background):

stellar-mcs
stellar-simulator --repository examples/config --simulation platform-v3-sim \
    --target sim-1 --gateway sim-gw-1
stellar-simulator --repository examples/config --simulation lab-psu-sim \
    --target psu-sim-1 --gateway psu-sim-gw-1

The simulators register as a driver and a gateway each; the reconciler binds them to the links of sim-1 and psu-sim-1, which become ready. The API answers on http://localhost:8080, the default of the stellar commands (--api, STELLAR_API).

3. Send a telecommand#

The catalogue of platform-v3 declares a ping telecommand on the tcu component, verified by the responding measure within 5 s:

ping:
  changes_state: false
  verify: [{responding: true, within: 5s}]

Send it to the first TCU:

stellar send sim-1 'tcu[TCU1].ping'

The command follows the acknowledgement chain of the telecommand until its final state: PENDING, ENCODED (ACK 1, the driver), SENT (ACK 2, the gateway), then VERIFIED (ACK 3, the verification on telemetry). It succeeds on VERIFIED or COMPLETE. The states are explained in Telecommand Lifecycle.

A telecommand with arguments takes them as name=value, quantities with their unit:

stellar send sim-1 'tcu[TCU1].set_anode_voltage' 'voltage=100 V'

ramp is not given: its default, 10 V/s, applies. A value outside the range of the argument (voltage=400 V) is refused before anything is sent, with the error tc::out-of-range.

4. Watch values#

stellar watch sim-1 'tcu[TCU1].anode_voltage'

The command prints the current value, then each new sample: the simulated anode voltage ramps up to 100 V at 10 V/s, with noise. Stop it with Ctrl-C. A measure is selected as tcu[TCU1].anode_voltage (one instance), tcu.anode_voltage (every instance) or anode_voltage (any component); without a measure, every value of the target is shown.

--until and --timeout turn it into a wait, handy in scripts:

stellar watch sim-1 'tcu[TCU1].mode' --until STANDBY --timeout 10

More in Direct Telecommands and Values.

5. Inject a fault#

The simulation declares fault scenarios. tcu_silent makes TCU3 stop answering:

stellar sim faults sim-gw-1               # the scenarios and whether each is active
stellar sim fault sim-gw-1 tcu_silent on
stellar send sim-1 'tcu[TCU3].ping'       # VERIFY_TIMEOUT after 5 s
stellar sim fault sim-gw-1 tcu_silent off

stellar sim talks to NATS directly (--nats, STELLAR_NATS_URL), not to the API.

6. Run a procedure#

The library platform-v3-steps holds the procedure Hot standby test:

procedure "Hot standby test"
  description "Powers the platform from the bench supply, then brings a TCU to hot standby."
  uses sat: platform-v3
  uses psu: lab-psu
  input tcu: tcu_id
  input bus_voltage: f32 V
  allowed in AIT, IVV

  step "Power the PPU"
    send set_voltage to psu with voltage = bus_voltage
    send output_on to psu
    expect psu.output_enabled is true within 3 s

  run "Check TCU" with sat, tcu, expected_mode = STANDBY

  if failed
    run "Safe TCU" with sat, tcu

It declares two roles, sat and psu, typed by platform, and two inputs. A run request binds each role to a target and gives the inputs, in an environment (examples/config/runs/hot-standby.yaml):

run: Hot standby test
environment: AIT
targets: {sat: sim-1, psu: psu-sim-1}
inputs: {tcu: TCU2, bus_voltage: 28 V}

Launch it:

stellar run examples/config/runs/hot-standby.yaml

stellar run prints run <id> launched, then follows the log of the run, one line per event: procedure and step starts and ends, each telecommand sent and its final state, each expect or check with the samples that decided it. It exits with success when the procedure succeeds.

With --detach, it only prints the run identifier (a ULID). You can then follow and inspect the run:

RUN=$(stellar run examples/config/runs/hot-standby.yaml --detach)
stellar watch "$RUN"        # follow it; an identifier of run is told apart from a target
stellar status "$RUN"       # running, suspended, waiting for an answer, finished

See the failure handling at work#

Run the procedure on TCU3 while it is silent:

stellar sim fault sim-gw-1 tcu_silent on
sed 's/TCU2/TCU3/' examples/config/runs/hot-standby.yaml > hot-standby-tcu3.yaml
stellar run hot-standby-tcu3.yaml
stellar sim fault sim-gw-1 tcu_silent off

The step TCU answers of Check TCU retries (retry 3 times every 2 s), then fails; the if failed block runs Safe TCU, and the run finishes in failure. See Retries.

Answer, suspend and resume#

A run can wait for people: a question of ask operator, or a decision when a step whose telecommands change the on-board state fails (it cannot be replayed automatically). The follow-up then prints the command expected, for instance waiting: stellar answer <run> replay|skip|fail|abort:

stellar answer "$RUN" replay     # replay the step, skip it, or abort the run
stellar answer "$RUN" yes        # confirm a question

An operator can also suspend a run at the end of the current instruction, then resume it:

stellar suspend "$RUN"
stellar resume "$RUN" --choice replay     # or skip, fail, abort
stellar abort "$RUN"

In the AIT environment of this tutorial, human orchestration is off: confirmations are acknowledged automatically and no identity is required. In IVV or in_orbit, the environment decides who must confirm; see Hazardous Confirmations and Questions, Decisions and Control.

7. Get the report#

Every run keeps its evidence: resolved inputs, the acknowledgement chain of each telecommand, the samples that validated each check, each confirmation. The HTML test report is rendered from it:

stellar report "$RUN" -o report.html

See Evidence and Reports.

8. Raise an alarm#

The catalogue declares an alarm on the cathode temperature, with an automatic reaction:

alarms:
  cathode_overheat:
    severity: critical
    when: stable(cathode_temperature > 1200 degC, 5 s)
    on_raise: run "Safe TCU"

stellar sim fault sim-gw-1 cathode_overheat on    # TCU2 at 1300 degC
stellar alarms watch                               # the transitions, live

After 5 s above the threshold, tcu[TCU2].cathode_overheat goes ACTIVE_UNACK and the alarm service launches Safe TCU on TCU2. Acknowledge it, then clear the fault:

stellar alarms ack sim-1 'tcu[TCU2].cathode_overheat'
stellar sim fault sim-gw-1 cathode_overheat off
stellar alarms --all

See Alarm Handling.

9. Dry run, without any infrastructure#

A procedure also runs dry, on ephemeral simulated targets, with no shared server at all. The command starts a local nats-server (the binary must be on the PATH, or given by --nats-server or STELLAR_NATS_SERVER), the services of the core in its own process, and one simulated target per role, played by the simulation of the repository for its platform — or by one written on the fly from its catalogue when simulations/ has none:

stellar run --dry examples/config/runs/hot-standby.yaml --repository examples/config \
    --report report.html

The roles get targets named dry-<role>, in a SIM environment without human orchestration; the environment and targets of the request are ignored, and so is allowed in. The command succeeds when the procedure succeeds: this is what the CI of a procedure repository runs.

Where to go next#

• Describe your own platform: Catalogue Packages.
• Simulate it from its catalogue: stellar generate simulation <catalogue>, see A simulation written from the catalogue.
• Describe your targets and links: Targets.
• Write procedures: Steps and Procedures.
• The whole command line: CLI Reference.