Part 07 — Telemetry Data ModelLink to the section Part 07 — Telemetry Data Model#

Maturity: Draft · Profiles: S (mandatory core), C and N (additional members) · Schema: univip.telemetry.v0.2 (../schemas/telemetry.schema.json)

7.1 PrinciplesLink to the section 7.1 Principles#

1. Units in names. Every numeric member carries its unit suffix: _m, _mps, _deg, _degps, _pct, _v, _a, _s, _ms, _dbm, _kbps. No alternative units exist on the wire (ADR-0006).
2. References in names. Altitude is never bare; see altitude_msl_m, altitude_ellipsoid_m, altitude_agl_m, altitude_rel_m.
3. Absence means unknown. A member that is not present is unknown. null is NOT used for numeric members. Enumerations use the explicit UNKNOWN value.
4. One timestamp per sample. timestamp is the time of validity of the sample (sensor time), not transmission time. Members measured at materially different times (for example GNSS at 1 Hz, attitude at 50 Hz) are reported as of timestamp with the device choosing the most recent values; where the age matters, an age_ms member MAY be given in position, motion, power or a payloads[] entry (the age of that object's values at timestamp), and MUST be given for values carried over from a source that has stopped (§7.11).
5. Monotonic sequence. sequence increases by one per sample per operation and allows gap detection.

7.2 StructureLink to the section 7.2 Structure#

{
  "schema": "univip.telemetry.v0.2",
  "device_id": "urn:univip:acme:SN12345",
  "session_id": "flight-2026-10-15-1042",
  "timestamp": "2026-10-15T10:32:15.125Z",
  "sequence": 4201,
  "time": { "source": "GNSS", "accuracy_ms": 2 },
  "position": { "...§7.4..." },
  "motion": { "...§7.5..." },
  "power": { "...§7.6..." },
  "link": { "...§7.7..." },
  "vehicle": { "...§7.8..." },
  "payloads": [ { "...§7.9..." } ],
  "health": { "...§7.10..." }
}

7.3 Header membersLink to the section 7.3 Header members#

7.4 position (Profile S: REQUIRED when a fix exists)Link to the section 7.4 position (Profile S: REQUIRED when a fix exists)#

When no position estimate exists, position is omitted and health.gnss.fix is NONE. Underwater vehicles without GNSS report health.gnss.fix: NONE and a non-GNSS position.source; horizontal_accuracy_m is then REQUIRED.

7.5 motionLink to the section 7.5 motion#

7.6 powerLink to the section 7.6 power#

REQUIRED (S) while the source is reporting. When the source has stopped (§7.11) the device either omits power or repeats the last known values with age_ms.

7.7 linkLink to the section 7.7 link#

A gateway that cannot observe the radio link reports state: UNKNOWN.

7.8 vehicleLink to the section 7.8 vehicle#

7.9 payloads[] (Profile C: REQUIRED for each payload)Link to the section 7.9 payloads[] (Profile C: REQUIRED for each payload)#

7.10 healthLink to the section 7.10 health#

7.11 Publication rate and gapsLink to the section 7.11 Publication rate and gaps#

• Profile S: ≥ 1 Hz powered, ≥ 2 Hz deployed; device SHOULD support ≥ 5 Hz. The client MAY request a rate via welcome or PATCH /config. A device whose link or source cannot sustain this (an acoustic link, or a vendor protocol that reports state at 0.5 Hz) MUST declare a lower telemetry.rate_hz.max in capabilities and is then held to that value; its staleness threshold below is then at least 2.5 sample periods.
• A requested or applied rate is an upper bound. A device publishes each sample of its source at most once and MUST NOT repeat a sample to reach a rate higher than the source provides; the effective rate is then the source's rate.
• A device MUST NOT fabricate samples; when the underlying source stops, the device MUST stop publishing position and motion, MUST keep publishing at ≥ 1 Hz with link.state: LOST (or UNKNOWN where it cannot observe the link), vehicle.vehicle_state: UNKNOWN and health.status: UNKNOWN, and MUST publish vehicle.telemetry.stale after 5 s. Any value it repeats from before the stop carries age_ms (§7.1).
• Clients MUST tolerate gaps and MUST NOT interpolate across a gap longer than 2 s without marking the result as estimated. A client SHOULD show telemetry as stale when no sample has arrived for max(3 / applied_rate_hz s, 2 s), while the device is offline, or while vehicle.telemetry.stale is active, and SHOULD display the age of what it shows.
• vehicle_state SHOULD NOT oscillate: a device reports HOLDING only after the vehicle has stayed below 0.5 m/s ground speed for 2 s and leaves it only when that no longer holds (the dwell of Annex A.2.2 applies to every device).

7.12 Relationship to media timeLink to the section 7.12 Relationship to media time#

See Part 09 §9.5. The timestamp member is on the same clock as the RTCP sender-report NTP time of all streams from the device.