@nolag/iot

IoT device telemetry and command dispatch with acknowledgment tracking.

Overview

Connect IoT devices and controllers over real-time channels. Devices push telemetry (sensor readings, status updates, or any structured measurement) while controllers dispatch commands with Promise-based acknowledgment tracking and configurable timeouts. Two roles participate in a device group: devices report data and acknowledge commands, and controllers watch telemetry and issue commands. A wrapper plays one role; a process that needs both runs two wrappers on two clients with different device IDs. Groups organise devices by fleet, physical location, or function. Your app owns one core NoLag client and injects it into NoLagIoT; the wrapper attaches its behaviour to that connection.

Key Features

• Real-time telemetry broadcast from devices to all group subscribers
• Promise-based command dispatch with configurable acknowledgment timeout
• Commands and acks routed by device ID with filters, so a device only receives its own commands
• Ephemeral topics throughout, suited to high-frequency data
• Device online/offline presence via lobby
• Multiple groups per connection; join by zone, building floor, vehicle type, etc.

How It Works

NoLagIoT attaches to an injected @nolag/js-sdk client and manages a lobby that reflects device presence. Calling joinGroup(name) returns a DeviceGroup that subscribes to three topics: telemetry for sensor readings, commands for command payloads, and _cmd_ack for acknowledgments. None of them is logged server-side. Routing uses filters: a device subscribes to commands filtered on its own deviceId, and a controller subscribes to _cmd_ack filtered on its deviceId, so a command reaches only its target and an ack reaches only its sender. A controller sees every command on the group but never emits command; only devices do.

When a controller calls sendCommand() the SDK stores a pending Promise keyed on the command ID and publishes the DeviceCommand. When the target device calls ackCommand(), the matching Promise resolves on 'acked' or 'completed' and rejects on 'failed', or rejects after commandTimeout. The first ack settles the command; later acks for the same ID are ignored. Publishers never receive their own messages, so telemetry you send is stored in your own buffer without emitting telemetry. The app owns the socket lifecycle; the wrapper never opens or closes it.

A fresh subscribe or an ordinary reconnect never replays history, and this SDK never triggers replay; see Replay for the one case where the broker replays messages.

import { NoLagApi } from "@nolag/js-sdk";

const api = new NoLagApi(process.env.NOLAG_API_KEY); // nlg_live_...
const app = await api.apps.create({ name: "My App", blueprintId: "nolag-iot-sdk" });
console.log(app.slug); // e.g. "my-app-a3f9": this is your appName

const actor = await api.actors.create({ name: "sensor-01", actorType: "device" });
console.log(actor.accessToken); // shown once; keep it

Installation

npm install @nolag/iot @nolag/js-sdk

Quick Start

The device and the controller are two clients with different device IDs. Both join the seeded factory-floor group.

import { NoLag } from '@nolag/js-sdk'
import { NoLagIoT } from '@nolag/iot'

const client = NoLag(DEVICE_TOKEN)
const iot = new NoLagIoT({
  client,
  appName: APP_SLUG, // the slug returned when you created the app
  deviceId: 'sensor-01',
  role: 'device',    // one role per wrapper; 'device' is the default
})

await client.connect()   // the app owns the connection
await iot.ready()        // wrapper setup complete

// Join the seeded group
const group = iot.joinGroup('factory-floor')

// Publish readings. The sensor id is the first argument; unit and tags are options.
group.sendTelemetry('temperature', 22.4, { unit: 'celsius', tags: { line: 'A' } })
group.sendTelemetry('humidity', 61, { unit: 'percent' })

// Commands addressed to this deviceId arrive here. Ack once: 'acked' or
// 'completed' resolves the controller's Promise, 'failed' rejects it.
group.on('command', async (cmd) => {
  console.log('Received command:', cmd.command, cmd.params, 'from', cmd.sentBy)
  try {
    const result = await handleCommand(cmd.command, cmd.params)
    group.ackCommand(cmd.id, 'completed', result)
  } catch (err) {
    group.ackCommand(cmd.id, 'failed', err instanceof Error ? err.message : String(err))
  }
})

// Teardown: the wrapper releases its handlers; the app closes the socket.
iot.detach()
client.disconnect()

API Reference

NoLagIoT

Constructor Options

NoLagIoT Events

DeviceGroup

DeviceGroup Events

Types