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
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
Common ANGLE_TYPE values:
- 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
Range measurements can be:
- 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.
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.
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.
Behaviour 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 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.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
Additional Observations
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
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