reference

Telemetry Schema Baseline

Reference shape for device payloads published to Twinise Cloud.

Telemetry Schema Baseline

Telemetry is flat JSON published to a per-device MQTT topic (devices/<id>/telemetry). Devices behind a hub are relayed on hubs/<hubId>/devices/<id>/telemetry. The device identity comes from the topic, not from a payload field.

Payload Shape

  • Readings are top-level keys. The map is free-form — every key you send becomes a metric channel.
  • Frames are stamped by the platform on receipt. A timestamp key inside the payload is treated as an ordinary key and does not set the sample time.
  • The Unreal plugin stamps live frames at client receive time.

Topics And Message Types

  • Each device publishes on four topic types: telemetry, attributes, connected, and disconnected.
  • Connection state is reported on the connected and disconnected topics, not inside telemetry frames.
  • attributes frames are broadcast live to subscribers and never persisted.

Example Payload

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

{
  "temperature": 23.4,
  "humidity": 42.8,
  "light": 318
}

Storage And Live Delivery

  • Every top-level key is treated as a telemetry channel. Ordering is receive order; nothing is reordered on a payload timestamp.
  • Live messages are forwarded to subscribers immediately and unaveraged.
  • Stored history is averaged per second — numerics to two decimal places, last value wins for strings — and written in batches once a minute, so history trails live by up to 60 seconds.

Clients subscribe over STOMP on SockJS and receive each message as a JSON envelope:

{
  "type": "telemetry",
  "deviceId": "TX-ENV-001",
  "data": { "temperature": 23.4, "humidity": 42.8 },
  "timestamp": "2026-02-26T20:31:10Z"
}

type is telemetry, attributes, or connection_status. data carries the payload exactly as published.

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