For the complete documentation index, see llms.txt.
Overview
DOPPLER measurements in a CCSDS 503.0-B-2 Tracking Data Message (TDM) are line-of-sight range-rate observations — the time derivative of the slant range between a ground station and a spacecraft. Unlike angle (AZEL/RADEC) or range observations, a Doppler sample reports how fast the geometric distance to the target is changing at a given epoch (m/s). VALAR ingests Doppler observables when a TDM block carries theDOPPLER_INSTANTANEOUS keyword and meets the v1 ingestion contract described below. Ingested Doppler records flow into the same orbit determination pipeline that consumes range and angle measurements: the platform converts the producer-side observable into the internal one-way / two-way MEAN range-rate convention used by the measurement model, normalises the timetag to receive-time, and emits a normalised record carrying band, transponder-delay, and correction-state metadata for downstream OD.
Doppler ingestion is gated by the
doppler-measurements feature flag. When the flag is off, TDM blocks containing Doppler observables are parsed but the Doppler rows are skipped (existing behaviour). When the flag is on, Doppler rows are validated and emitted per the rules below.Supported observables
The CCSDS standard defines three Doppler-family keywords. v1 accepts only one of them and rejects the other two with explicit error codes.| Keyword | v1 status | Notes |
|---|---|---|
| DOPPLER_INSTANTANEOUS | Accepted | Range-rate sample at the stated epoch (km/s on the wire, converted to m/s on emission) |
| DOPPLER_INTEGRATED | Rejected | Raises TRK_DOPPLER_INTEGRATED_UNSUPPORTED — different observable model |
| DOPPLER_COUNT | Rejected | Raises TRK_DOPPLER_COUNT_UNSUPPORTED — phase-count observable, out of v1 scope |
INTEGRATION_INTERVAL constraint
DOPPLER_INSTANTANEOUS rows are accepted only when the block-level INTEGRATION_INTERVAL is absent or ≤ 1 s. A larger window means the value is a window average; timestamping it as if it were instantaneous introduces a systematic time shift of order Tc/2, which can translate into kilometre-scale along-track position bias in LEO. v1 rejects this case with TRK_INSTANTANEOUS_INTEGRATION_WINDOW_TOO_LARGE.
The 1 s threshold matches the operational envelope of modern commercial and institutional Earth-orbit receivers (KSAT, SSC, Leaf Space, Viasat RT Logic, post-2015 ESTRACK).
Default sigma values
When the producer does not provide a per-observation σ in the TDM and no per-sensor σ is configured for DOPPLER in the sensor catalog, VALAR applies a per-band default. The emitted record carriessigmaDefaulted=true for audit.
| Band | Default σ (m/s) | Source |
|---|---|---|
| X | 1.0×10⁻³ m/s | DKR-3 §2 X-band reference noise |
| S | 5.0×10⁻³ m/s | Scaled from X-band per typical S-band carrier-noise ratios |
| Ka | 5.0×10⁻⁴ m/s | Scaled from X-band per typical Ka-band carrier-noise ratios |
Applied when no per-observation σ is in the TDM AND no sensor catalog σ is configured for DOPPLER. The emitted record carries
sigmaDefaulted=true for audit.Two-way Doppler convention
CCSDS 503.0-B-2 does not mandate which convention a producer uses for two-way Doppler. The two valid forms differ by a factor of two and the keyword alone does not distinguish them — silently assuming one when the producer uses the other introduces a 100% bias in the observable. VALAR resolves the convention per sensor via thetwoWayDopplerConvention field on the sensor configuration. See the Sensors page for where to set it.
| Setting | Definition | Adapter behaviour |
|---|---|---|
| MEAN | Observable is the arithmetic mean of uplink and downlink instantaneous rates (DSN convention) | Accept; emit observable as-received (km/s → m/s) |
| SUM | Observable is d/dt of the round-trip range (e.g. GMAT’s native form) | Accept; halve observable at emission to normalise to the internal MEAN convention; provenance logged |
| UNDECLARED | No per-sensor configuration | Magnitude-based auto-detection — accept with warning when |ρ̇| ≤ 10 km/s, reject otherwise |
Consequences per setting
- MEAN: ingestion succeeds without warning; the value is consumed verbatim by the measurement model.
- SUM: ingestion succeeds; the observable is halved before emission and the per-record provenance flag records the conversion. Downstream OD sees a MEAN-convention observable.
- UNDECLARED with
|ρ̇| ≤ 10 km/s: ingestion succeeds withTRK_TWO_WAY_CONVENTION_ASSUMED_MEANwarning. The 10 km/s sanity bound matches the maximum plausible LEO line-of-sight velocity for a MEAN-convention observable (circular-orbit velocity at LEO ≈ 7.6 km/s). - UNDECLARED with
|ρ̇| > 10 km/s: ingestion fails the block withTRK_AMBIGUOUS_TWO_WAY_CONVENTION. The magnitude is consistent with a SUM-convention observable that the adapter cannot safely halve without an explicit producer declaration.
Error code reference
The Doppler ingestion contract is fail-closed: every reject path surfaces a specific error code. Codes are scoped at three fatal levels — file-level (entire file rejected), block-level (block rejected, sibling blocks continue), and observation-level (row rejected, sibling rows continue). Two warning codes log vendor-assumption cases without rejecting.| Code | Cause | Remediation |
|---|---|---|
TRK_AMBIGUOUS_CORRECTIONS | Producer correction-state inputs (CORRECTIONS_APPLIED plus STEC / TROPO_* data rows) form an inconsistent combination. | Reconcile the producer’s TDM: either declare CORRECTIONS_APPLIED = YES with co-timestamped correction rows, or set NO with no correction rows. |
TRK_AMBIGUOUS_TWO_WAY_CONVENTION | Two-way block has no twoWayDopplerConvention configured and observable magnitude exceeds the 10 km/s MEAN-convention sanity bound. | Configure twoWayDopplerConvention = SUM or MEAN on the sensor in question. |
TRK_TWO_WAY_CONVENTION_ASSUMED_MEAN (warning) | Two-way block has no twoWayDopplerConvention configured but observable magnitude is within sanity bound; defaulted to MEAN. | Configure twoWayDopplerConvention explicitly on the sensor to silence the warning. |
TRK_DOPPLER_INTEGRATED_UNSUPPORTED | Observation row uses DOPPLER_INTEGRATED, which v1 does not accept. | Re-emit the data with DOPPLER_INSTANTANEOUS rows, or wait for follow-on integrated-Doppler support. |
TRK_DOPPLER_COUNT_UNSUPPORTED | Observation row uses DOPPLER_COUNT, which v1 does not accept. | Re-emit the data with DOPPLER_INSTANTANEOUS rows. |
TRK_INSTANTANEOUS_INTEGRATION_WINDOW_TOO_LARGE | DOPPLER_INSTANTANEOUS row carries INTEGRATION_INTERVAL > 1 s, risking a Tc/2 time-shift bias. | Re-emit with INTEGRATION_INTERVAL ≤ 1 s, or configure a per-sensor operator override when the producer timestamps at interval midpoint. |
TRK_TDM_PARSE_FAILED | The CCSDS TDM file failed to parse. | Validate the file against CCSDS 503.0-B-2 syntax and resubmit. |
TRK_UNSUPPORTED_TDM_VERSION | TDM uses an unsupported version (e.g. legacy -B-1). | Upgrade the producer to emit CCSDS 503.0-B-2. |
TRK_UNSUPPORTED_TIME_SYSTEM | TIME_SYSTEM is not in {UTC, TAI, GPS} (e.g. SCLK, UT1, TDB, TT, TCB, TCG). | Re-emit the TDM in UTC, TAI, or GPS. |
TRK_UNSUPPORTED_MODE | MODE is not SEQUENTIAL (e.g. SINGLE_DIFF differential Doppler). | Re-emit with MODE = SEQUENTIAL. |
TRK_UNSUPPORTED_PATH | PATH is not in {1,2} (one-way) or {2,1,2} (two-way) — e.g. three-way {2,1,3}. | Re-emit with a one-way or two-way coherent path; three-way is out of v1 scope. |
TRK_MISSING_PARTICIPANT | A participant slot referenced by PATH is empty. | Populate the missing PARTICIPANT_* slot in the block metadata. |
TRK_UNRESOLVED_PARTICIPANT | Neither participant resolves to a station (or both resolve to the same kind), so direction is undefined. | Verify station / spacecraft identifiers match the mission catalog; three-way Doppler is rejected here. |
TRK_MISSING_BAND | Model-applied tropospheric or ionospheric corrections are required but TRANSMIT_BAND / RECEIVE_BAND is missing. | Populate TRANSMIT_BAND and RECEIVE_BAND ({S, X, Ka}) on the block metadata. |
TRK_UNKNOWN_BAND | A band keyword is present but not in {S, X, Ka} (v1 supports only these three). | Re-emit with a supported band; UHF / L / K / C / VHF / W are future development. |
TRK_MISSING_TRANSPONDER_DELAY | Two-way block lacks both pre-applied transponder calibration and metadata constants (TRANSMIT_DELAY_1, RECEIVE_DELAY_1). | Add TRANSMIT_DELAY_1 and RECEIVE_DELAY_1 to metadata, or pre-apply the calibration upstream. |
TRK_UNKNOWN_CORRECTION_KEYWORD | A non-standard CORRECTION_* keyword is not in the closed vendor-alias table. | Use a CCSDS 503.0-B-2 keyword, or request an alias-table extension. |
TRK_NO_EPHEMERIS_FOR_SHIFT | TIMETAG_REF = TRANSMIT requires a reference ephemeris for light-time normalisation, but none is loaded. | Load an initial ephemeris for the spacecraft before ingesting the TDM. |
TRK_CORRECTIONS_ASSUMED_NO (warning) | CORRECTIONS_APPLIED is absent and no correction rows / metadata are present; defaulted to NO. | Set CORRECTIONS_APPLIED explicitly on the producer side to silence the warning. |
Example TDM
A valid one-way DOPPLER TDM block, X-band downlink from a single ground station to a spacecraft, conforming to CCSDS 503.0-B-2:PATH = 1,2selects the one-way downlink modality (signal travels fromPARTICIPANT_1toPARTICIPANT_2).TIMETAG_REF = RECEIVEmeans the epoch on each data row is the receive time at the ground station; no light-time shift is applied at ingest.INTEGRATION_INTERVAL = 1.0is at the v1 boundary (≤ 1 s); larger values would reject withTRK_INSTANTANEOUS_INTEGRATION_WINDOW_TOO_LARGE.CORRECTIONS_APPLIED = YESwith noSTEC/TROPO_*data rows is accepted only when metadataCORRECTION_*values are also present (see the correction-state resolution table in the ingestion specification). For the more common case where the producer pre-applies corrections via the data section, co-timestampedSTECandTROPO_DRY/TROPO_WETrows accompany eachDOPPLER_INSTANTANEOUSrow.- Doppler values are in km/s on the wire and are converted to m/s on emission to the internal record.
See the canonical TDM file format page for the full CCSDS keyword catalogue, segment structure, and time-system / reference-frame conventions shared with non-Doppler observables.