Simulated Targets

A simulated target replaces the driver and the gateway of a target by a simulation engine, driven by a YAML description. It serves dry runs, the CI of procedure repositories, load tests and the training of operators — before any hardware exists.

The engine, stellar-simulator, registers as a driver and as a gateway, under the same contract as real ones: the MCS does not tell a simulated target from a real one, except by the environment that allows it (typically SIM). A procedure validated on a simulated target runs unchanged on a flatsat and in orbit.

A simulation#

Simulations live in simulations/<name>.yaml of the configuration repository. stellar check compiles them against the catalogue of their platform, and the engine reads them from the repository. The simulated platform-v3 of the example repository:

simulation: platform-v3-sim
platform: platform-v3@1.4.0
seed: 42
initial:
  tcu[*]: {responding: true, mode: STANDBY, anode_voltage: 0 V}
telecommands:
  ping:
    reply: {responding: true}
    delay: 200 ms
  set_mode:
    reply: {mode: args.mode}
    delay: 2 s
  standby:
    reply: {mode: STANDBY}
    delay: 1 s
  safe_mode:
    reply: {mode: SAFE_MODE}
    delay: 1 s
  set_anode_voltage:
    ramp: {anode_voltage: {to: args.voltage, rate: args.ramp}}
  activate_file:
    delay: 500 ms
  start_stream: {stream: start}
  stop_stream: {stream: stop}
measures:
  anode_voltage: {noise: 0.5 V}
  cathode_temperature: {model: first_order, target: 900 degC, tau: 60 s}
faults:
  tcu_silent:
    tcu[TCU3].responding: false
  anode_overvoltage:
    tcu[TCU1].anode_voltage: 310 V
  cathode_overheat:
    tcu[TCU2].cathode_temperature: 1300 degC
gateway:
  rate_bps: 1000000
files:
  lttm: {every: 10 min, size: 64 KiB}

The description is compiled against the catalogue: an unknown telecommand, measure, component, instance, argument or file type is an error (simulation::unknown-…), shown in the editor like any diagnostic. stellar schema simulation prints its JSON Schema.

A simulation written from the catalogue#

A platform needs no simulation written by hand to be simulated: stellar generate simulation writes one from its catalogue, a simulated target that keeps the contract of the catalogue — each telecommand gives what its verification (ACK 3) expects — and a starting point to make more realistic.

stellar generate simulation lab-psu --repository examples/config    # simulations/lab-psu-sim.yaml
stellar generate simulation platform-v3@1.4.0 --name platform-v3-twin -o twin.yaml

What the catalogue says becomes behaviour:

What the catalogue does not say is listed at the end of the file and on the terminal, to complete by hand: the effect of a telecommand that changes the state without a verification (the current of a load), a condition that cannot be inverted, an alarm without a fault. The telecommands are commented with their description.

Before writing, the command compiles the simulation and checks it: each telecommand is sent alone to a fresh engine, in simulated time, and its verifications are evaluated as the executor would.

lab-psu-sim on lab-psu@1.0.0: each telecommand sent alone, its verification evaluated
  psu.set_voltage                  ok       verified after 1500ms (voltage=30.0)
  psu.output_on                    ok       verified after 300ms
  psu.output_off                   ok       verified after 0s

An existing file is kept (--force replaces it). The command exits with 1 when a telecommand is not played as its catalogue verifies it.

Checking a simulation: stellar sim check#

stellar sim check lab-psu-sim --repository examples/config

The same check, on a simulation of the repository, written by hand or generated and edited: it needs no NATS. Each telecommand gets a verdict:

The arguments are their default, else the middle of their range, else the last value of their enum, true or a byte. The command exits with 1 when a telecommand failed.

Reference of the format#

Top level#

Names#

A telecommand or a measure is written alone when its name is unique in the platform, else component.name. The measures of a reply or a ramp are those of the component of the telecommand, for the instance the telecommand is sent to.

In initial and faults, a key names a component — tcu[*] for all its instances, tcu[TCU3] for one, psu for a component without instances — or a measure directly (tcu[TCU3].responding).

Values#

Literals with their unit (0 V, 1.2 A), booleans, enum values, or an argument of the telecommand (args.mode). A measure without initial value is 0, false, or the first value of its enum.

Telecommands#

A telecommand whose catalogue declares verify: [echo] receives a conforming echo when the simulation describes it, with no effect if need be: tcu.blank_firing: {}.

What a telecommand does next: then#

An equipment often goes on by itself after a command: a camera told READY cools down, then is ready once its detector reaches its set point; an acquisition goes back to READY when it ends. then lists these steps, applied in order after the first effect of the telecommand:

telecommands:
  camera.set_mode:
    reply: {mode: COOLING}
    delay: 200 ms
    ramp:
      detector_temperature: {to: 17 degC, rate: 0.5}
    then:
      - after: 120 s
        until: "detector_temperature <= 18 degC"
        reply: {mode: args.mode}
  camera.start_acquisition:
    reply: {mode: IMAGING}
    delay: 150 ms
    ramp:
      acquisition_progress: {to: 100, rate: 5}
    then:
      - after: 20 s
        reply: {mode: READY, acquisition_progress: 0}

• A step never applies before the one above it, nor before the end of the delay.
• until is evaluated every 100 ms of simulated time, on the same instants whatever the speed of the simulation: a seed replays the same run.
• A command received meanwhile takes over. A telecommand sent to the same instance cancels the steps still to come of the earlier telecommands, when they set or ramp a measure it sets or ramps itself. For example, set_mode STANDBY during the cooling of a set_mode READY leaves the camera in STANDBY.
• A fault keeps its forced values over the steps.

stellar sim check and stellar generate simulation let the steps run within the window of each verification. verify: [{mode: args.mode, within: 130s}] holds once the step sets the mode.

Measures#

Faults#

A fault is a named set of forced values. While a fault is active, its values replace those of the model. Faults are switched while a run is in progress, to test if failed blocks, alarms and their reactions (see Driving faults).

The simulated link: gateway#

• Passes. passes: {first: 0 s, every: 90 min, duration: 10 min} — a pass lasts at most its period (simulation::invalid-passes). Outside a pass, the gateway reports the link unavailable, refuses the uplink and publishes no frame: current values age as in orbit. Without passes, the link is always available. The measured throughput is the one the SDK counts.
• Losses. loss drops that share of the frames each way: a telecommand sent but never received on board, a downlink frame never published. It exercises retries, timeouts and the retransmissions of file transfers.
• COP-1. With cop1: true, telecommands go up in AD frames of a fixed virtual channel, taken on board by a FARM-1 whose CLCW comes down in the telemetry. The simulated transport sim-cop1@1, which the link declares, runs COP-1 and lets the rest through. See COP-1 and the Link Component.

On-board files: files#

files:
  lttm: {every: 10 min, size: 64 KiB}

For each file type declared by the files component of the catalogue, a file is born at each multiple of every in simulated time, of the given size.

• A file has an identifier (numbered from 1 in the order of generation), a type, a size, a generation date and a generation (1 at birth). Its checksum uses the algorithm of the catalogue.
• Its content is deterministic (seed, identifier, generation), except for an lttm: it records the samples of every measure at its generation, one JSON line per on-board instant, one period apart going back, padded with newlines to its size. The simulated driver decodes the lttm files into deferred samples.
• The list telecommand of the transfer protocol brings down a directory frame, decoded into measures of files; the read telecommand brings down a chunk frame, at the rate of the link. Requests not served are lost at the end of a pass or when the gateway restarts.
• The write telecommand writes on board and returns an echo. Its first chunk, at offset 0 and different from the content in place, starts a new generation; an absent file is created, of the last declared type. The checksum of a written file is computed at the next listing.
• For a platform that transfers its files with CFDP, the simulator runs a CFDP entity on board (entity 2; the ground is entity 1). It sends the files the ground asks by Proxy Put Request, within the rate of the pass, and writes the files it receives. Its PDUs suffer the losses, which exercises NAKs and retransmissions.

Streams#

A telecommand marked stream: start starts the stream it is sent to; stream: stop stops it. A stream produces its segments on board at its nominal rate; outside a pass, they are lost. See Continuous Streams.

Raw values#

For a measure calibrated by the MCS (raw and calibration in the catalogue), the engine publishes the raw value by inverting the calibration: polynomial of degree 1, monotonic table, or enumeration. Another calibration is refused when the simulator starts.

Determinism#

The clock of the engine is simulated and its random generator internal: a seed replays exactly the same samples, which makes CI tests of procedures reproducible. Several engines simulate many targets, for load tests.

Running a simulated target#

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

It connects to NATS with the variables of the SDK: STELLAR_NATS_URL (nats://localhost:4222 by default) and STELLAR_NATS_CREDENTIALS. Logs follow RUST_LOG.

The driver registers with the name of the simulation as software, version 1.0.0, which a link driver: platform-v3-sim@1 accepts. The topology declares the simulated target like any other:

targets:
  sim-1:
    platform: platform-v3@1.4.0
    environments: [SIM, AIT]
    links:
      nominal: {driver: platform-v3-sim@1, gateway: sim-gw-1, default: true}
      direct:  {driver: platform-v3-sim@1, gateway: sim-gw-1}

Its frames are an internal JSON of the simulator, opaque to the MCS like any frame.

Driving faults#

stellar sim faults sim-gw-1                   # the faults and whether each is active
stellar sim fault sim-gw-1 tcu_silent on
stellar sim fault sim-gw-1 tcu_silent off

{"faults": [{"name": "tcu_silent", "active": true}, {"name": "anode_overvoltage", "active": false}]}

stellar sim talks to NATS directly (--nats, STELLAR_NATS_URL, and the NATS security options --nats-credentials, --nats-ca, --nats-cert, --nats-key), not to the API. The API exposes the same:

A gateway that does not answer gives 404 sim::unknown-gateway; a real gateway, which does not know these verbs, 422 sim::not-simulated; an unknown fault 422 sim::refused.

Each change is published on stellar.sim.evt.<target> as {fault, active, at}, so that the evidence and the reports of a run show the faults active during it.

Faults scheduled by a run#

A run request can switch faults itself, to rehearse the recovery of a procedure (its if failed blocks, the reactions to its alarms) without anybody at a terminal:

# runs/tvac-leak.yaml
run: TVAC cycle
environment: SIM
targets: {chamber: chamber-sim, psu: psu-sim, dut: cam-sim}
inputs: {hot: 50 degC, cold: -30 degC}
faults:
  - {target: chamber, fault: vacuum_leak, at: {step: Plateau, after: 10 s}, off: {after: 60 s}}

• Checked twice. When the run is resolved, the role must be one of the run (run::fault-target), the step one the run may enter (run::fault-step), and the environment not in_orbit (run::fault-not-simulated). When the run starts, before anything is sent, the target must be served by a simulated gateway whose simulation has that fault: otherwise the run ends failed, fault `vacuum_leak` of `chamber` cannot be scheduled: `chamber-1` is not a simulated target (…).
• In the log. Each switch is logged in the run (log fault `vacuum_leak` switched on for `chamber-sim` (scheduled by the request)) and published on stellar.sim.evt.<target>, so the report shows it.
• Delays are those of the executor, like wait: in a dry run, --speed does not shorten them.
• After a restart of the executor, the faults of the run are scheduled again from its resumption.

Control verbs of the simulated gateway#

The simulated gateway answers these verbs on stellar.ctl.rpc.gateway.<instance>.<verb>, besides status:

nats request stellar.ctl.rpc.gateway.sim-gw-1.generate '{"file_type": "lttm", "size": 65536}'
nats request stellar.ctl.rpc.gateway.sim-gw-1.corrupt '{"id": 3, "active": true}'

Dry runs#

A dry run plays a procedure on ephemeral simulated targets, without any shared infrastructure:

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

It starts a local nats-server (--nats-server, STELLAR_NATS_SERVER), then, in its own process, the reconciler, the compute stage, the value table, the alarm service and the executor, on the snapshot of the local repository. Each role gets a target dry-<role>, played by the simulation of the repository whose platform is the version of the library, with the links its telecommands use. Its parameters, for configure, are those of the target dry-<role> when the topology declares one, else those of the first target of the same platform and version. The procedure runs in a SIM environment without human orchestration, ignoring allowed in, the environment and the targets of the request.

A platform without a simulation in simulations/ gets one written from its catalogue on the fly (see A simulation written from the catalogue), which the log says: a procedure runs dry as soon as its catalogue exists.

Decisions. When a step not eligible for retry fails, a run waits for a decision (see Decisions). Nobody watches a dry run: it answers by itself, fail by default, so that the if failed blocks run — the recovery of the procedure is tested too — and the command exits with 1. The answer is logged and in the report as given by the dry run. The web editor and the VS Code extension run the same dry run.

Alarms and reactions. The alarms of the targets are evaluated as in operation, those of limits and the named ones: each transition shows in the log (alarm dry-chamber.vacuum.vacuum_leak ACTIVE_UNACK (critical)) and in a section of the report. A reaction (on_raise) is a run of the dry run: it takes the target from the run (see Automatic reactions), its events show in the log prefixed by [reaction], and its report follows that of the run. Once the reactions are over, the dry run resumes the run they suspended as it answers a decision (--on-decision): by default the step where it stopped fails, and its if failed blocks run on the state the reaction made safe (suspended by alarm …, failed by the dry run); with --on-decision abort, the run is aborted without them. The command exits with 1. Reactions still running when the run ends are followed two minutes at most.

Faults. The faults of the request, and those of --fault, are switched by the dry run like any run (see Faults scheduled by a run): the CI of a procedure repository tests its recovery.

stellar run --dry runs/hot-standby.yaml --fault "sat:tcu_silent@TCU answers"

The log shows as with stellar watch, and the command succeeds when the procedure succeeds: this is the CI of a procedure repository. See Running Procedures and the CLI Reference. The VS Code extension and the web editor run the same dry run on the procedure under the cursor.

See also#

• Your First Procedure: the example simulated targets.
• API reference: simulation.