Device SDK

Runs on your device. Publish telemetry, respond to commands, manage configuration — with automatic reconnection and offline buffering.

JavaScriptPython

Install

JavaScript

npm install @relay-x/device-sdk

Python

pip install relayx_device_sdk

Initialize

Create a RelayDevice instance with your API key and secret from console.relay-x.io.

JavaScript

const { RelayDevice } = require("@relay-x/device-sdk");

const device = new RelayDevice({
  api_key: "your_api_key",
  secret: "your_secret",
  mode: "production",
});

Python

from relayx_device_sdk import RelayDevice

device = RelayDevice({
    "api_key": "your_api_key",
    "secret": "your_secret",
    "mode": "production",
})

The mode parameter separates your data into isolated environments so test data never mixes with production:

• "production" — Live environment for real device data
• "test" — Isolated sandbox for development and testing

Connect

JavaScript

await device.connect();

Python

await device.connect()

connect() authenticates with RelayX, fetches your device schema, and initializes all modules. It returns true on success, false if already connected.

Modules

🔌

Connection

Monitor connection status and lifecycle events

📡

Telemetry

Publish sensor readings with schema validation

💬

RPC

Receive calls from the App SDK and return a response

📨

Command

Receive async commands with guaranteed delivery

⚙️

Configuration

Get and set device configuration

⚡

Event

Publish discrete events for one-off moments

⏰

Time

NTP-synchronized timestamps

Quick Example

A complete example that connects a device, monitors the connection, and publishes temperature readings every 5 seconds.

JavaScript

const { RelayDevice } = require("@relay-x/device-sdk");

const device = new RelayDevice({
  api_key: "your_api_key",
  secret: "your_secret",
  mode: "production",
});

// monitor connection status
device.connection.listeners((event) => {
  console.log("Connection:", event.type);
});

async function main() {
  await device.connect();

  // publish telemetry every 5 seconds
  setInterval(async () => {
    const temperature = 20 + Math.random() * 10;
    const sent = await device.telemetry.publish("temperature", temperature);
    console.log(sent ? "Sent" : "Buffered (offline)");
  }, 5000);
}

main();

Python

import asyncio
import random
from relayx_device_sdk import RelayDevice

device = RelayDevice({
    "api_key": "your_api_key",
    "secret": "your_secret",
    "mode": "production",
})

# monitor connection status
def on_status(event):
    print(f"Connection: {event['type']}")

device.connection.listeners(on_status)

async def main():
    await device.connect()

    # publish telemetry every 5 seconds
    while True:
        temperature = 20 + random.random() * 10
        sent = await device.telemetry.publish("temperature", temperature)
        print("Sent" if sent else "Buffered (offline)")
        await asyncio.sleep(5)

asyncio.run(main())

Connection Lifecycle

The Device SDK handles reconnection automatically. If the connection drops, the SDK will:

1. Emit a reconnecting event
2. Keep retrying until a connection is re-established
3. Resubscribe to all active listeners on reconnect
4. Flush any messages that were buffered while offline
5. Emit a reconnected event

Offline Buffering

When the device is disconnected, telemetry and event publishes are buffered in memory. Once the connection is restored, buffered messages are flushed in order. telemetry.publish() and event.send() return false when a message is buffered instead of sent.

RPC and config operations require an active connection and will throw a NotConnectedError if called while disconnected.

Disconnect

JavaScript

await device.disconnect();

Python

await device.disconnect()

Gracefully closes the connection, cleans up all consumers, and clears the offline buffer.