reference

Telemetry Schema Baseline

Reference shape for device payloads accepted by Twinise Cloud.

Telemetry Schema Baseline

Telemetry is flat JSON published to a per-device MQTT topic (device/<id>/telemetry). The device identity comes from the topic, not from a payload field.

Payload Shape

  • Readings are top-level keys with numeric or boolean values.
  • An optional timestamp field (ts, timestamp, datetime, or time; ISO 8601 or epoch) marks when the sample was taken.
  • Frames without a timestamp are stamped at receive time.

Status And Metadata

  • Connection status is reported on dedicated connected/disconnected topics, not inside telemetry frames.
  • Firmware version is captured at device registration (via the QR payload), not per frame.

Example Payload

Published to device/TX-ENV-001/telemetry:

{
  "temperature": 23.4,
  "humidity": 42.8,
  "pressure": 1013.2,
  "timestamp": "2026-02-26T20:31:10Z"
}

Merge Rules

  • Every top-level key other than the timestamp is treated as a telemetry channel and merged into device state.
  • Frames without a timestamp are stamped at receive time; per-key merge protects state from out-of-order data.
  • Metric values must be numeric or boolean depending on key contract.
  • Source timestamps more than 24 hours from receive time are replaced with the receive time before merge.

Unreal Mapping Notes

  • Keep metric names stable across firmware versions.
  • Normalize units before driving materials/FX.
  • Keep display scaling in Unreal, not in raw payload values.

Related Pages