Documentation Index
Fetch the complete documentation index at: https://docs.valar.space/llms.txt
Use this file to discover all available pages before exploring further.
For the complete documentation index, see llms.txt.The Tracking Data Message (TDM) is a standardized ASCII text format for exchanging spacecraft tracking observations between ground stations, control centers, and orbit determination systems. Unlike OEM which contains computed ephemeris, TDM contains raw or processed measurement data from tracking sensors such as radar, optical telescopes, and ranging systems.
Doppler observables: TDM blocks containing
DOPPLER_INSTANTANEOUS rows are ingested as range-rate observations alongside angle and range measurements. See Doppler (Range-Rate) Measurements below for the supported keywords, two-way convention rules, default sigma, and error codes.Key Components
A TDM file contains a hierarchical structure:- Header: File-level metadata including format version, creation date, and originator
- Segment(s): One or more independent tracking data segments, each containing:
- Metadata Section: Observation context (participants, time system, measurement types, reference frame)
- Data Section: Time-tagged measurements in chronological order
Structure Overview
TDM Hierarchy
Segment Structure
Each segment is self-contained with its own metadata and data:- Metadata defines the observation context and applies to all measurements in the data section
- Data contains timestamped observations in the format:
KEYWORD = EPOCH VALUE
Metadata Fields
Required Metadata
| Field | Description | Example Values |
|---|---|---|
| TIME_SYSTEM | Time system for all epochs | UTC, TAI, GPS |
| PARTICIPANT_1 | First participant in tracking path | Ground station ID, spacecraft ID |
| PARTICIPANT_2 | Second participant in tracking path | Spacecraft ID, ground station ID |
| MODE | Data transmission mode | SEQUENTIAL, SINGLE_DIFF |
| PATH | Signal path between participants | 1,2 (one-way), 2,1,2 (two-way) |
Observation-Specific Metadata
Depending on the measurement type, additional metadata is required:Angle Observations
- ANGLE_TYPE: Geometry convention (AZEL, RADEC, XEYN, XSYE)
- REFERENCE_FRAME: Coordinate frame for angles (EME2000, ITRF, topocentric)
Range Observations
- RANGE_UNITS: Units for range measurements (km, m, s, RU)
- TRANSMIT_BAND: Frequency band (S, X, Ka)
- RECEIVE_BAND: Receiving frequency band
Optional Metadata
- TIMETAG_REF: Time tag reference point (TRANSMIT, RECEIVE, BOUNCE)
- INTEGRATION_INTERVAL: Data averaging period (seconds)
- CORRECTION_ANGLE_1: Correction applied to first angle component
- CORRECTION_ANGLE_2: Correction applied to second angle component
- CORRECTION_RANGE: Range correction applied
Corrections fields indicate whether measurements have been preprocessed to remove systematic errors, biases, or atmospheric effects.
Measurement Types
TDM supports a wide variety of tracking observations:Angle Measurements
| Keyword | Description | Units | ANGLE_TYPE |
|---|---|---|---|
| ANGLE_1 | First angle component | degrees | Azimuth (AZEL), RA (RADEC), X-East (XEYN) |
| ANGLE_2 | Second angle component | degrees | Elevation (AZEL), Dec (RADEC), Y-North (XEYN) |
- AZEL: Azimuth and elevation (local horizontal frame, typical for radar and RF tracking)
- RADEC: Right ascension and declination (inertial frame, typical for optical telescopes)
- XEYN: X-East and Y-North (topocentric Cartesian)
- XSYE: X-South and Y-East (alternative topocentric)
Range Measurements
| Keyword | Description | Units |
|---|---|---|
| RANGE | One-way or two-way range | km, m, s, or range units (RU) |
- One-way: Signal travels from transmitter to receiver (PATH = 1,2 or 2,1)
- Two-way: Signal transmitted, reflected, and received (PATH = 1,2,1 or 2,1,2)
Doppler (Range-Rate) Measurements
DOPPLER measurements in a CCSDS 503.0-B-2 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). Doppler observables flow through the same orbit determination pipeline that consumes range and angle measurements: VALAR 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.Supported Doppler observables
The CCSDS standard defines three Doppler-family keywords. VALAR accepts onlyDOPPLER_INSTANTANEOUS and rejects the other two with explicit error codes.
| Keyword | 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, not in 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. Larger windows are rejected 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 | 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 |
- 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 with aTRK_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.
Doppler error codes
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: 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 VALAR does not accept. | Re-emit the data with DOPPLER_INSTANTANEOUS rows. |
TRK_DOPPLER_COUNT_UNSUPPORTED | Observation row uses DOPPLER_COUNT, which VALAR 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 not in 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}. | Re-emit with a supported band. |
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: One-way X-band Doppler block
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 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. 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.
Frequency Measurements
| Keyword | Description | Units |
|---|---|---|
| RECEIVE_FREQ | Received signal frequency | Hz |
| TRANSMIT_FREQ_1 | First transmitter frequency | Hz |
| TRANSMIT_FREQ_2 | Second transmitter frequency | Hz |
Additional Observations
| Keyword | Description | Units |
|---|---|---|
| MAG | Visual or radar magnitude | dimensionless |
| RCS | Radar cross-section | m² |
| PRESSURE | Atmospheric pressure | hPa |
| TEMPERATURE | Atmospheric temperature | K |
| HUMIDITY | Relative humidity | % |
Critical Keywords
MODE — Transmission Mode
Defines the signal transmission configuration:- SEQUENTIAL: Measurements taken in chronological sequence (most common)
- SINGLE_DIFF: Single-difference measurements (VLBI, GPS)
- COHERENT: Coherent ranging
- CONSTANT: Constant frequency transmission
PATH — Signal Path
Specifies the route of the signal between participants:- 1,2: One-way from Participant 1 to Participant 2
- 2,1: One-way from Participant 2 to Participant 1
- 1,2,1: Two-way round trip starting from Participant 1
- 2,1,2: Two-way round trip starting from Participant 2
TIMETAG_REF — Time Tag Reference
Indicates when the measurement timestamp refers to:- TRANSMIT: Time when signal was transmitted
- RECEIVE: Time when signal was received
- BOUNCE: Time when signal reflected off target (two-way ranging)
Common Use Cases
- Orbit Determination: Processing radar and optical tracking to estimate spacecraft state
- Orbit Solution Validation: Comparing predicted ephemeris against ground-based observations
- Navigation Support: Providing ranging data for real-time navigation
- Conjunction Assessment: Sharing raw observations for independent orbit solutions
- Data Archiving: Long-term storage of historical tracking campaigns
- Multi-Station Campaigns: Combining observations from multiple ground stations
Complete definition of the TDM standard in CCSDS 503.0-B-2 specification.
Sample TDM Files
Example 1: Optical Angle Measurements (RADEC)
This example shows right ascension and declination measurements from an optical telescope tracking a spacecraft in an inertial reference frame:Example 2: Radar Tracking (AZEL + Range)
This example shows azimuth-elevation angles with two-way range from a ground-based radar:Multi-Segment TDM Example
A single TDM file can contain multiple segments from different stations or observation sessions:Usage in VALAR
When working with TDM files in VALAR:- Sensor Configuration Required: Ground station or sensor metadata must be configured in VALAR before importing TDM files. This includes station location, antenna characteristics, and measurement biases.
- Automatic Processing: VALAR validates TDM structure, parses metadata, and associates measurements with the correct spacecraft and sensors.
- Orbit Determination: TDM measurements are used as observations in weighted least-squares orbit determination to estimate spacecraft state vectors.
- Residual Analysis: After orbit determination, VALAR computes observation residuals (measured minus computed) for quality assessment.
- Multi-Station Support: TDM files with multiple segments from different stations are automatically handled.
Best Practices
Data Quality
- Include COMMENT fields: Document observation conditions, corrections applied, and data quality issues
- Specify corrections: Use CORRECTION_* keywords to indicate preprocessing
- Provide metadata: Include INTEGRATION_INTERVAL and measurement uncertainties when available
File Organization
- One segment per pass: Separate distinct tracking passes or observation sessions into different segments
- Consistent time systems: Use UTC for operational tracking data
- Appropriate reference frames: Use ITRF for ground-based AZEL, EME2000/GCRF for RADEC
Measurement Types
- Match ANGLE_TYPE to sensor: Use AZEL for radar/RF, RADEC for optical telescopes
- Specify PATH correctly: Ensure PATH matches actual signal propagation
- Use TIMETAG_REF appropriately: TRANSMIT for radar, RECEIVE for optical
Interoperability
- Follow CCSDS conventions: Adhere to standard keyword names and units
- Validate before sharing: Ensure TDM syntax and semantics are correct
- Document non-standard fields: If using custom keywords, explain them in comments
Comparison with Other Formats
| Feature | TDM | OEM | OPM |
|---|---|---|---|
| Data Type | Raw observations | Computed ephemeris | State snapshot |
| Temporal Scope | Observation period | Time series | Single epoch |
| Source | Ground sensors | Propagation/OD | OD output |
| Purpose | Input to OD | Trajectory sharing | State exchange |
| Measurement Types | Angles, range | Position, velocity | Position, velocity, elements |
| Multi-Segment | Yes (multiple stations) | Yes (multiple intervals) | No |
Reference Frames and Time Systems
Supported Reference Frames
TDM supports any reference frame appropriate for the measurement type:- ITRF/ITRF2020: Earth-fixed frame for ground-based AZEL measurements
- EME2000/GCRF: Inertial frames for RADEC measurements
- Topocentric: Station-centered frames (local horizontal)
Time Systems
Standard time systems for TDM:- UTC: Coordinated Universal Time (most common for operational tracking)
- TAI: International Atomic Time
- GPS: GPS Time
- TDB: Barycentric Dynamical Time (deep space missions)
Ensure your time system matches the precision requirements of your orbit determination. For sub-meter accuracy, distinguish between UTC, TAI, and dynamical time systems.
Technical References
VALAR’s TDM processing is built on industry-standard astrodynamics models, following:- CCSDS 503.0-B-2: Tracking Data Message standard
- CCSDS 502.0-B-3: Navigation Data Messages (for reference frame definitions)
- IERS Conventions: Earth orientation and time systems
- Vallado’s Fundamentals of Astrodynamics and Applications