Sending Data to ControlCom Connect via MQTT

ControlCom Connect provides a flexible and reliable way to ingest data from your IoT devices using the MQTT protocol. This guide explains how to connect your devices and send data in the supported formats.

Connection Details

To send data to ControlCom Connect, you'll need the following connection details, which can be found in the ControlCom Connect interface under Administration > Devices > [Selected Device]:

• Broker: The MQTT broker hostname
• Port: The MQTT broker port
• Topic: The MQTT topic to publish data to
• Client ID: The unique identifier for your device connection

These details are specific to each device in your organization and must be used exactly as provided to ensure proper data routing and authentication.

Payload Formats

ControlCom Connect supports two payload formats for sending data:

Format 1: Key-Value Object

This format allows you to send a single timestamp with multiple data points:

{
  "timestamp": 1647359121000,
  "data": {
    "temperature": 24.5,
    "humidity": 65,
    "pressure": 1013.2,
    "status": "normal",
    "isActive": true
  }
}

The structure follows this interface:

{
  timestamp?: number;  // Optional: Unix timestamp in milliseconds
  data?: {
    [key: string]: string | number | boolean;  // Key-value pairs of data points
  };
}

If timestamp is omitted, the current server time will be used when the message is received.

Format 2: Data Array

This format allows you to send multiple data points with individual timestamps:

{
  "dataArray": [
    {
      "key": "temperature",
      "value": 24.5,
      "timestamp": 1647359121000
    },
    {
      "key": "humidity",
      "value": 65,
      "timestamp": 1647359121000
    },
    {
      "key": "pressure",
      "value": 1013.2,
      "timestamp": 1647359123000
    },
    {
      "key": "status",
      "value": "normal",
      "timestamp": 1647359121000
    },
    {
      "key": "isActive",
      "value": true,
      "timestamp": 1647359123000
    }
  ]
}

The structure follows this interface

{
  dataArray: {
    key: string;                      // Variable name
    value: string | number | boolean; // Variable value
    timestamp?: number;               // Optional: Unix timestamp in milliseconds
  }[];
}

If timestamp is omitted for any item, the current server time will be used when the message is received.

Using MQTT

MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol designed for IoT applications. To send data to ControlCom Connect:

1. Connect to the MQTT broker using the broker address and port from your device settings
2. Authenticate using the client ID and any required credentials
3. Publish messages to the specified topic using one of the supported payload formats
4. Maintain the connection or reconnect as needed based on your device's capabilities

Most MQTT clients support features like:

• Quality of Service (QoS) levels
• Persistent sessions
• Last Will and Testament messages
• Keep-alive intervals

Configure these based on your specific requirements for data reliability and device connectivity.

Code Examples

import { connect } from "mqtt";
import fs from "fs";

const BROKER_URL = "brokerurl";
const BROKER_PORT = 8883;
const TOPIC = "organizationId/deviceId";
const CLIENT_ID = "deviceId";

export type DataArrayItemInterface = {
  key: string;
  value: string | number | boolean;
  timestamp?: number;
};

export type PublishDataPayload = {
  dataArray: DataArrayItemInterface[];
};

const start = () => {
  const client = connect({
    host: BROKER_URL,
    port: BROKER_PORT,
    clientId: CLIENT_ID,
    protocol: "mqtts",
    protocolVersion: 5,
    clean: true,
    reconnectPeriod: 5000,
    cert: fs.readFileSync("certs/certificate.pem.crt"),
    ca: fs.readFileSync("certs/AmazonRootCA1.pem"),
    key: fs.readFileSync("certs/private.pem.key"),
  });

  client.on("connect", async () => {
    console.log(`Connected to MQTT broker ${BROKER_URL}:${BROKER_PORT}`);
    const payload: PublishDataPayload = {
      dataArray: [
        {
          key: "temperature",
          value: 25.2,
          timestamp: Date.now(), // passed in milliseconds
        },
      ],
    };
    const result = await client.publishAsync(TOPIC, JSON.stringify(payload));
    console.log("Published message", result);
    client.end();
  });

  client.on("error", (error) => {
    console.error("MQTT Client Error:", error);
  });
};

start();

Best Practices

When sending data to ControlCom Connect, follow these best practices:

Data Formatting

• Use consistent variable names across messages
• Choose appropriate data types for your values
• Include timestamps for time-sensitive data
• Keep payload sizes reasonable (under 256KB)
• Use the data array format when sending historical data with different timestamps

Connection Management

• Implement reconnection logic with exponential backoff
• Use TLS for secure connections (port 8883)
• Set appropriate QoS levels based on data importance
• Consider using persistent sessions for intermittently connected devices
• Monitor connection status and handle disconnections gracefully

Error Handling

• Validate data before sending
• Buffer data locally when connection is lost
• Implement logging for debugging
• Handle and report errors appropriately
• Test with different network conditions

By following these guidelines and using the supported payload formats, you can ensure reliable data transmission to ControlCom Connect from your IoT devices.

For a visual, flow-based approach to connecting your devices to ControlCom Connect, check out our Node-RED Integration Guide.