Connection

Monitor the connection lifecycle between your device and RelayX. Register listeners for status changes like connect, disconnect, and reconnect events.

Overview

The connection module provides visibility into the device's connection state. You don't need to manage reconnection yourself — the SDK handles it automatically — but you can react to status changes.

API

JavaScript

device.connection.listeners(callback: (event) => void) → void

• callback — Called whenever the connection status changes
• event — An object with a type property indicating what happened

Python

device.connection.listeners(callback: (event) → None) → None

• callback — Called whenever the connection status changes
• event — A dict with a type key indicating what happened

C++

device->connection.on_status(callback: relay_status_cb_t) → relay_err_t

device->connection.is_connected() → bool

• callback — Called whenever the connection status changes. Receives a relay_connection_status_t enum value.
• is_connected() — Returns true if the device is currently connected
• Returns RELAY_OK on success, RELAY_ERR_DUPLICATE_LISTENER if max listeners reached (RELAY_MAX_STATUS_LISTENERS, default 4)

Status Events

JavaScript

Event	Description
connected	Successfully connected to RelayX
disconnected	Connection closed (only on explicit disconnect() calls)
reconnecting	Connection lost, SDK is attempting to reconnect
reconnected	Successfully reconnected after a drop
auth_failed	Authentication failed — check your API key and secret

Python

Event	Description
connected	Successfully connected to RelayX
disconnected	Connection closed (only on explicit disconnect() calls)
reconnecting	Connection lost, SDK is attempting to reconnect
reconnected	Successfully reconnected after a drop
auth_failed	Authentication failed — check your API key and secret

C++

Status	Description
RELAY_STATUS_CONNECTED	Initial connection established and authenticated
RELAY_STATUS_DISCONNECTED	Connection lost
RELAY_STATUS_RECONNECTING	Reconnection attempts starting
RELAY_STATUS_RECONNECTED	Successfully reconnected, offline buffer flushed

Register a Listener

JavaScript

device.connection.listeners((event) => {
  console.log("Status:", event.type);
});

Python

def on_status(event):
    print(f"Status: {event['type']}")

device.connection.listeners(on_status)

C++

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

Handling Each Event

JavaScript

device.connection.listeners((event) => {
  switch (event.type) {
    case "connected":
      console.log("Connected to RelayX");
      break;
    case "disconnected":
      console.log("Disconnected");
      break;
    case "reconnecting":
      console.log("Connection lost, reconnecting...");
      break;
    case "reconnected":
      console.log("Reconnected — buffered messages flushed");
      break;
    case "auth_failed":
      console.error("Authentication failed — check your API key");
      break;
  }
});

Python

def on_status(event):
    match event["type"]:
        case "connected":
            print("Connected to RelayX")
        case "disconnected":
            print("Disconnected")
        case "reconnecting":
            print("Connection lost, reconnecting...")
        case "reconnected":
            print("Reconnected — buffered messages flushed")
        case "auth_failed":
            print("Authentication failed — check your API key")

device.connection.listeners(on_status)

C++

device->connection.on_status([](relay_connection_status_t status) {
    switch (status) {
        case RELAY_STATUS_CONNECTED:
            ESP_LOGI("app", "Connected to RelayX");
            break;
        case RELAY_STATUS_DISCONNECTED:
            ESP_LOGW("app", "Disconnected");
            break;
        case RELAY_STATUS_RECONNECTING:
            ESP_LOGW("app", "Connection lost, reconnecting...");
            break;
        case RELAY_STATUS_RECONNECTED:
            ESP_LOGI("app", "Reconnected — buffered messages flushed");
            break;
        default:
            break;
    }
});

Multiple Listeners

You can register multiple listeners. Each one is called independently when a status change occurs.

JavaScript

// logging
device.connection.listeners((event) => {
  console.log(`[${new Date().toISOString()}] ${event.type}`);
});

// UI updates
device.connection.listeners((event) => {
  updateStatusIndicator(event.type);
});

Python

from datetime import datetime

# logging
def log_status(event):
    print(f"[{datetime.now().isoformat()}] {event['type']}")

# app logic
def handle_status(event):
    update_status_indicator(event["type"])

device.connection.listeners(log_status)
device.connection.listeners(handle_status)

C++

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

// app logic
device->connection.on_status([](relay_connection_status_t status) {
    update_status_indicator(status);
});

Listener Limit

The C++ SDK supports up to RELAY_MAX_STATUS_LISTENERS (default 4) concurrent status listeners.

Reconnection Behavior

When the connection drops unexpectedly, the SDK automatically handles reconnection:

1. A reconnecting event is emitted once
2. The SDK keeps retrying until a connection is re-established
3. All active RPC and command listeners are resubscribed
4. Any telemetry or events buffered while offline are flushed in order
5. A reconnected event is emitted

JavaScript

info

The disconnected event only fires on explicit disconnect() calls — not on unexpected connection drops. If the connection drops unexpectedly, you'll see reconnecting followed by reconnected.

Python

info

The disconnected event only fires on explicit disconnect() calls — not on unexpected connection drops. If the connection drops unexpectedly, you'll see reconnecting followed by reconnected.

C++

info

On unexpected connection loss, the SDK emits RELAY_STATUS_DISCONNECTED → RELAY_STATUS_RECONNECTING → RELAY_STATUS_RECONNECTED once restored.

Connect and Disconnect

Connection is managed at the device level, not through this module:

JavaScript

// connect
await device.connect();

// disconnect
await device.disconnect();

Both methods return true if the state changed, false if already in that state.

Python

# connect
await device.connect()

# disconnect
await device.disconnect()

Both methods return true if the state changed, false if already in that state.

C++

// connect
device->connect();

// disconnect
device->disconnect();

Both methods return relay_err_t. You can also check connection state at any time:

if (device->connection.is_connected()) {
    // device is online
}