MQTT Methods

Use MQTT to send and receive real-time messages from external brokers.

MQTT is a lightweight publish/subscribe protocol designed for reliable machine-to-machine communication and low-latency updates. Learn more about MQTT.

Use it for scenarios like live sensor telemetry, device status updates, real-time dashboards, alerting, and command/control flows where updates need to arrive immediately.

Overview

The MQTT API provides a full publish/subscribe workflow for device-connected applications. It supports broker discovery, connection lifecycle management, message publishing, topic subscriptions, and connection status monitoring.

Important: MQTT support requires Node Pro and doesn't work on Node Mini.

Importing

import { mqtt } from '@telemetryos/sdk';

Broker Types

The SDK currently exposes MQTT brokers with these properties:

• name - Broker display name
• address - Broker host/IP
• port - Broker port
• protocol - mqtt, mqtts, ws, or wss

Methods

discover()

Discover available MQTT brokers configured for the platform.

Signature:

async discover(): Promise<Array<{
  name: string;
  address: string;
  port: number;
  protocol: 'mqtt' | 'mqtts' | 'ws' | 'wss';
}>>

Returns: Promise resolving to a list of brokers

connect()

Create a connection to a selected broker.

Signature:

async connect(
  brokerUrl: string,
  options?: {
    username?: string;
    password?: string;
    clientId?: string;
    keepalive?: number;
    clean?: boolean;
    reconnectPeriod?: number;
    connectTimeout?: number;
  },
): Promise<string>

Parameters:

• brokerUrl - Fully-qualified broker URL (for example, wss://broker.example.com:443)
• options - Optional authentication and connection settings

Returns: Promise resolving to a clientId assigned by the platform

Example:

try {
  const clientId = await mqtt().connect('wss://broker.example.com:8883', {
    clientId: 'display-01',
  });
  console.log('connected:', clientId);
} catch (error) {
  console.error('MQTT connect failed:', error);
}

disconnect()

Close a broker connection.

Signature:

async disconnect(clientId: string): Promise<void>

publish()

Publish a message to a topic.

Signature:

async publish(
  clientId: string,
  topic: string,
  payload: string,
  options?: {
    qos?: 0 | 1 | 2;
    retain?: boolean;
  },
): Promise<void>

Parameters:

• clientId - Client identifier returned by connect()
• topic - MQTT topic to publish to
• payload - String payload body
• options - Optional publish flags (qos, retain)

subscribe()

Subscribe to topic messages.

Signature:

async subscribe(
  clientId: string,
  topic: string,
  handler: (message: {
    topic: string;
    payload: string;
    qos: 0 | 1 | 2;
    retain: boolean;
  }) => void,
  options?: { qos?: 0 | 1 | 2 },
): Promise<boolean>

Example:

await mqtt().subscribe(clientId, 'facility/alerts', (msg) => {
  console.log('topic:', msg.topic);
  console.log('payload:', msg.payload);
}, { qos: 1 });

unsubscribe()

Stop receiving messages from a topic.

Signature:

async unsubscribe(clientId: string, topic: string, handler?: (message: any) => void): Promise<boolean>

getConnectionStatus()

Check whether a client is connected.

Signature:

async getConnectionStatus(clientId: string): Promise<'connected' | 'disconnected' | 'connecting' | 'reconnecting' | 'error'>

subscribeConnectionStatus()

Subscribe to connection state updates.

Signature:

async subscribeConnectionStatus(
  clientId: string,
  handler: (status: 'connected' | 'disconnected' | 'connecting' | 'reconnecting' | 'error') => void,
): Promise<boolean>

unsubscribeConnectionStatus()

Remove a connection status subscription.

Signature:

async unsubscribeConnectionStatus(
  clientId: string,
  handler?: (status: 'connected' | 'disconnected' | 'connecting' | 'reconnecting' | 'error') => void,
): Promise<boolean>

Next Steps

• Proxy Methods - External API access with CORS handling
• Platform Methods - Account and device introspection
• Weather Methods - Built-in weather data without external brokers