Time and Freshness

Every sample carries two times — when it was measured and when the ground received it — and every decision of the MCS uses one of them on purpose. This page explains which time is used where, so that checks, verifications, derived measures and reports behave as expected, including after a loss of signal or a dump of on-board telemetry.

One time scale#

The whole chain works in a single time scale, set by the global configuration:

time:
  scale: utc     # utc (default), tai or gps

Every timestamp of the MCS — in samples, events, logs, passes and reports — is expressed in that scale, as RFC 3339 text with nanosecond resolution (2026-10-02T10:15:03.912Z). Drivers deliver on-board time already converted into it: the conversion from the on-board clock (counter, epoch, leap seconds) is part of the ICD of the target and belongs in the driver.

Two times per sample#

On-board time dates what happened on the spacecraft; it is never the reference of a wait. Ground time is when the MCS learned about it; it is the reference of freshness and of every timeout, because it is the only clock the ground controls.

For a derived measure, time is that of its most recent input and ground_time that of its oldest input: a derived measure is never fresher than its oldest source.

Freshness#

A measure may declare how old its current value may be to be trusted:

measures:
  responding: {type: bool, max_age: 30s}

• check and requires read the current value and refuse one that is absent, or whose age — measured from its ground_time — exceeds max_age. A failed requires rejects the telecommand before encoding (REJECTED).
• A value without max_age is always accepted by check and requires, however old.
• A temporal derived measure whose window holds no sample (for instance during a loss of signal) is unknown: published once with value: null, and refused by check and requires like a stale value.

During a loss of signal, current values simply age: nothing is invented, and checks that need fresh data fail rather than trusting old values.

Waits and windows#

Every wait of the MCS has a bound, measured on ground time.

The requirement of a sample received after SENT avoids false successes on a value that was already true before the telecommand. The executor reads such samples from the PARAMS stream starting at SENT, so a measure produced once — the reply to a ping, for instance — still satisfies the expect that follows the send, even if it arrived during the verification of the telecommand.

Durations are literals with a unit (10 s, 3 min, 500 ms), so the maximum duration of a procedure is known before launch. See Safety Rules and Maximum Duration.

Durations in configuration files#

In the global configuration and in YAML files, a duration is a number followed by d, h, min, s, ms, us or ns, with or without a space: 5s, 3 min, 30d.

Real-time and deferred telemetry#

Each sample is marked with its delivery:

• realtime: received live, during a pass or on a bench;
• deferred: recorded on board and downloaded later — frames replayed by the spacecraft and marked Stellar-Delivery: deferred by the gateway, or samples decoded from a long-term telemetry file (LTTM) by the driver, one message per on-board instant.

Deferred samples are archived and used for analysis, but they never drive live decisions:

A dump of yesterday's telemetry therefore never overwrites today's current value, never raises a stale alarm, and never disturbs a stable(…) condition.

Temporal derived functions#

Windows and durations of temporal functions (avg(x, 10 s), stable(cond, 30 s), since, rate…) are computed on sample time (time): on-board time when the driver provides it. The compute stage evaluates them at processing time over the real-time samples it keeps, and re-evaluates them at their next deadline (end of a stable duration, a sample leaving a window, every second for age and since) without waiting for a new sample. Windows are bounded by derived.max_window (1 h by default). Same samples, same result: a temporal derived measure can be recomputed from the history. See Derived Measures.

Times in other places#

Ground stations and benches#

Gateways stamp the ground reception time of each frame, so their clocks matter most: synchronize them by NTP, or by PTP where the timing of within windows is tight. A gateway on a bench, without a notion of visibility, reports its link as always available; a ground station gateway reports it only during passes, and current values age between passes as they would in orbit.