Telemetry

Publish sensor readings from your device to RelayX. Telemetry is fire-and-forget — readings are delivered to your app and stored for historical queries.

Overview

The telemetry module validates readings against your device schema and publishes them with NTP-synchronized timestamps. When disconnected, readings are buffered and flushed on reconnect.

Access via device.telemetry.

API

JavaScript

await device.telemetry.publish(metric, reading)

Python

await device.telemetry.publish(metric, reading)

Parameter	Type	Description
metric	string	The metric name (must match your device schema)
reading	any	The value to publish (number, string, boolean, or object)

Returns true if sent, false if buffered (offline)

Throws ValidationError if the metric or reading type doesn't match the schema

Publish a Reading

JavaScript

const sent = await device.telemetry.publish("temperature", 22.5);
console.log(sent ? "Sent" : "Buffered (offline)");

Python

sent = await device.telemetry.publish("temperature", 22.5)
print("Sent" if sent else "Buffered (offline)")

Schema Validation

Every device has a schema that defines its metrics. The SDK validates each publish() call against it:

• The metric name must exist in the schema
• The reading type must match the type defined for that metric

If validation fails, a ValidationError is thrown.

If the schema failed to load on connect, validation is skipped and any metric name and type is accepted.

Supported Types

Schema Type	Accepted Values
number	Any numeric value (integer or float)
string	Any string value
boolean	true or false
json	Objects and arrays

null and undefined readings bypass type checking and are accepted for any metric.

Timestamps

Every reading is automatically timestamped using the device's NTP-synchronized time. The payload sent to RelayX looks like:

{
  "value": 22.5,
  "timestamp": 1711900800000
}

You don't need to add timestamps yourself — the SDK handles this.

Offline Buffering

When the device is disconnected, publish() buffers the message in memory and returns false. Once the connection is restored, all buffered messages are flushed in order.

JavaScript

const sent = await device.telemetry.publish("temperature", 22.5);

if (!sent) {
  console.log("Device is offline — reading buffered");
}

Python

sent = await device.telemetry.publish("temperature", 22.5)

if not sent:
    print("Device is offline — reading buffered")

info

Buffered messages are stored in memory only. If the device process restarts while offline, buffered messages are lost.

Error Handling

JavaScript

try {
  await device.telemetry.publish("unknown_metric", 42);
} catch (err) {
  // ValidationError: metric "unknown_metric" not found in schema
  console.error(err.message);
}

Python

try:
    await device.telemetry.publish("unknown_metric", 42)
except ValidationError as err:
    # metric "unknown_metric" not found in schema
    print(err)