MQTT Protocol Reference

Connection parameters, topic structure, payload formats, and quality-of-service details for devices connecting to Beacon Tower via MQTT.

Connection Parameters

Parameter	Description	Example
Protocol	MQTT 3.1.1 over TCP (TLS optional)	—
Host	Broker address from onboarding	mqtt.example.com
Port	1883 (TCP) or 8883 (TLS)	—
Username	Device ID	temp-sensor-001
Password	Primary key from provisioning	aB3x...
Client ID	Unique per connection (conventionally the device ID)	temp-sensor-001
Clean Session	true (recommended)	—

Devices receive their host, port, and credentials from the Onboarding Service via GET /get_settings.

Authentication

The MQTT broker uses username/password authentication backed by a credentials database:

• Username = device ID
• Password = primary key (or secondary key during rotation)
• Passwords are stored as bcrypt hashes — the broker verifies against the hash at connect time

mTLS alternative

For certificate-based deployments, the broker authenticates devices via mTLS using Glaze CA-issued X.509 certificates instead of username/password. The device identity and tenant are extracted from the certificate's CN and OU fields. See Certificate Onboarding for details.

Access Control

Each device is restricted by an ACL to its own topic namespace:

devices/{deviceId}/#    (read + write)

A device cannot publish to or subscribe to another device's topics. The ACL is created automatically during provisioning.

Reconnection

Devices should implement exponential backoff on disconnection:

Attempt	Delay
1	1 second
2	2 seconds
3	4 seconds
...	doubles each time
Max	60 seconds

Topic Structure

All device communication uses the devices/{deviceId}/ topic prefix.

Telemetry (Device → Cloud)

devices/{deviceId}/telemetry

QoS: 1 (At Least Once)

The device publishes JSON payloads containing sensor readings:

{"temperature": 22.5, "humidity": 48.2}

Multi-signal payloads are supported — each key becomes a separate telemetry signal in the platform. The payload format must match what the ingress pipeline expects for the configured parser.

Standard Format (Default Parser)

A flat JSON object where keys are signal names and values are readings:

{"motor_temp": 85.5, "inlet_pressure": 101.3}

With Timestamp

Include a timestamp field (ISO 8601) to set the measurement time. If omitted, the broker receive time is used:

{"motor_temp": 85.5, "timestamp": "2026-02-25T10:30:00Z"}

The timestamp key is consumed by the parser and not forwarded as a signal.

Supported Value Types

JSON Type	Example	Notes
Number	85.5, 42, -10	Most common for telemetry
Boolean	true, false	Binary states
String	"running", "idle"	Status codes, enums
Object	{"lat": 59.33, "lon": 18.07}	Structured values
Array	[1.0, 2.0, 3.0]	Vector/batch values

Custom Parsers

For non-standard payload formats, the provider can be configured with a parser header. See Parsers for OBIS, structured metric, and JMESPath options.

Reported Properties (Device → Cloud)

devices/{deviceId}/twin/reported

QoS: 1 (At Least Once)

The device publishes its current state as a JSON object:

{
  "firmware_version": "2.1.0",
  "reporting_interval": 60,
  "battery_level": 87
}

Reported properties are:

1. Stored in the device twin database with an incremented version counter
2. Forwarded to the message queue as a ProviderClientPropertiesChanged message for downstream processing

See Device Twins for the full twin model.

Desired Properties (Cloud → Device)

devices/{deviceId}/twin/desired

QoS: 1 (At Least Once)

The device subscribes to this topic to receive configuration updates from the cloud. When an operator sets desired properties (via the platform API), the MQTT Provider publishes the full desired state to this topic:

{
  "reporting_interval": 30,
  "alert_threshold": 85.0
}

The device should apply the desired configuration and then publish updated reported properties to confirm.

Direct Methods (Cloud → Device)

Direct methods use a request/response pattern with correlation IDs:

Invocation (device subscribes):

devices/{deviceId}/methods/{methodName}/invoke

Response (device publishes):

devices/{deviceId}/methods/{methodName}/response/{correlationId}

See Direct Methods for the full protocol.

QoS Levels

All Beacon Tower MQTT communication uses QoS 1 (At Least Once):

• The broker acknowledges receipt with a PUBACK
• If no PUBACK is received, the client retransmits
• Duplicate messages are possible — the platform handles idempotency

QoS 0 (fire-and-forget) is not recommended as it provides no delivery guarantee. QoS 2 (exactly once) is supported by MQTT but not required by the platform.

Message Size

The maximum message size is determined by the broker configuration. The platform enforces a 1 MB limit per message. Keep telemetry payloads well under this — typical messages are a few hundred bytes.

Complete Example

A temperature sensor connecting and publishing telemetry:

import paho.mqtt.client as mqtt
import json, time

# Credentials from GET /get_settings
DEVICE_ID = "temp-sensor-001"
BROKER_HOST = "mqtt.example.com"
BROKER_PORT = 1883
PASSWORD = "device-primary-key"

client = mqtt.Client(client_id=DEVICE_ID, clean_session=True)
client.username_pw_set(DEVICE_ID, PASSWORD)
client.connect(BROKER_HOST, BROKER_PORT)
client.loop_start()

# Subscribe to desired properties and commands
client.subscribe(f"devices/{DEVICE_ID}/twin/desired", qos=1)
client.subscribe(f"devices/{DEVICE_ID}/methods/+/invoke", qos=1)

# Publish telemetry
while True:
    payload = json.dumps({"temperature": 22.5, "humidity": 48.2})
    client.publish(f"devices/{DEVICE_ID}/telemetry", payload, qos=1)
    time.sleep(10)

Next Steps

• Device Twins — Managing desired and reported properties
• Direct Methods — Invoking commands on devices
• Telemetry Ingestion — How the platform processes published telemetry
• Device Onboarding — How devices obtain their credentials
• Certificate Onboarding — EST-based onboarding with X.509 certificates and mTLS