Device SDK

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

JavaScriptPythonC++

Install

JavaScript

npm install @relay-x/device-sdk

Source: Realtime-Relay/device-js

Python

pip install relayx_device_sdk

Source: Realtime-Relay/device-py

C++

idf.py add-dependency "relay-x/device-cpp"

Source: Realtime-Relay/device-cpp

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",
})

C++

#include "relay/device.h"

relay_device_config_t config = {
    .api_key = "your_api_key",
    .secret  = "your_secret",
    .mode    = RELAY_MODE_PRODUCTION
};

RelayDevice* device = new RelayDevice(config);

Heap Allocation

RelayDevice contains large static buffers and must be heap-allocated with new.

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()

C++

device->connect();

Event Loop

The C++ SDK requires you to call device->process() in your main loop. This drives all internal operations — dispatching callbacks, detecting disconnects, and flushing the offline buffer.

while (true) {
    device->process();
    // your application logic here
    vTaskDelay(pdMS_TO_TICKS(10));
}

connect() authenticates with RelayX, fetches your device schema, and initializes all modules. Returns true on success in JavaScript/Python, or RELAY_OK in C++.

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

📝

Logs

Send structured logs with three severity levels

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())

C++

#include "relay/device.h"

relay_device_config_t config = {
    .api_key = "your_api_key",
    .secret  = "your_secret",
    .mode    = RELAY_MODE_PRODUCTION
};

RelayDevice* device = new RelayDevice(config);

// monitor connection status
device->connection.on_status([](relay_connection_status_t status) {
    ESP_LOGI("app", "Connection: %d", status);
});

device->connect();

// publish telemetry every 5 seconds
while (true) {
    device->process();

    float temperature = 20.0f + (float)(esp_random() % 100) / 10.0f;
    relay_err_t err = device->telemetry.publish_number("temperature", temperature);
    ESP_LOGI("app", "%s", err == RELAY_OK ? "Sent" : "Buffered (offline)");

    vTaskDelay(pdMS_TO_TICKS(5000));
}

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.

JavaScript

telemetry.publish() and event.send() return false when buffered. RPC and config operations will throw a NotConnectedError if called while disconnected.

Python

telemetry.publish() and event.send() return false when buffered. RPC and config operations will throw a NotConnectedError if called while disconnected.

C++

telemetry.publish_number() and event.send_number() return RELAY_ERR_BUFFERED when buffered. RPC and config operations return RELAY_ERR_NOT_CONNECTED if called while disconnected.

Disconnect

JavaScript

await device.disconnect();

Python

await device.disconnect()

C++

device->disconnect();

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