MQTT Interface

The service provides an MQTT interface that enables persistent bidirectional communication between devices and the platform. For documentation on the available commands and events for each service, refer to the individual service MQTT API documentation. Currently only a subsection of the Alarmbridge API is offered over MQTT.

The MQTT broker is available at mqtt.{stage}.iotcomms.io.

• Port: 443
• Transport: MQTT over TLS
• ALPN: The mqtt ALPN protocol extension is required when connecting on port 443.

Devices are provisioned and managed through the Device Service. The same device credentials used for SIP Digest Authentication are used for MQTT authentication, so no separate provisioning is required for the MQTT interface. Devices must be pre-provisioned in the Device Service before they can authenticate with the MQTT interface.

For more details on device provisioning, refer to the Device Service documentation.

The MQTT interface uses a custom HMAC-SHA256 based authentication scheme.

MQTT Client ID

The MQTT client ID must exactly match the provisioned deviceId.

Username

The MQTT username is a query string with the following format:

device={deviceId}&tenant={tenant}

Password

The MQTT password is constructed as follows:

1. Obtain the current Unix time as a whole number of seconds.
2. Compute an HMAC-SHA256 of that timestamp, represented as a decimal string, using the device's HA1 hash as the key.
3. Encode the digest as a hexadecimal string.
4. Set the MQTT password to the UTF-8 encoding of signature={hex-digest}&timestamp={unix-seconds}.

The timestamp must be within ±5 minutes of server time. Connections with a timestamp outside this window will be rejected.

The device's HA1 hash is provisioned via the Device Service. For more details on device credential provisioning, refer to the Device Service documentation.

Below is a reference implementation for constructing the password, written in node:

import crypto from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000);

const signature = crypto.createHmac("sha256", deviceHa1)
  .update(String(timestamp))
  .digest("hex");

const password = Buffer.from(`signature=${signature}&timestamp=${timestamp}`, "utf-8");