MQTT Guide

Overview

ControlBird's MQTT integration runs in two modes. In client mode it connects to an external MQTT broker, subscribes to topics, and turns incoming payloads into tag values; it can also publish tag values back out to topics. In broker mode it hosts an embedded MQTT broker so devices and other systems can publish and subscribe against ControlBird itself. Both modes are set up in the IO Manager app, with no configuration files.

The client speaks MQTT 3.1.1 and supports topic wildcards, QoS levels 0, 1, and 2, retained messages, and three payload formats (String, JSON, and Binary). Inbound JSON payloads can be reduced to a single value with a JSONPath expression.

Client mode: connecting to a broker

An MQTT tag is one topic. Its ID is a dotted name that is unique in your tenant, for example House.Livingroom.Temperature; its source is the MQTT topic.

1. Open the IO Manager, go to the Tags section, and choose Add tag to start Create Custom Device.
2. Pick the MQTT card in the Client role.
3. Enter a Device Name and fill in the connection form with the broker host and port (default 1883; the client connects to exactly the port you enter), and optionally a username.
4. In the Points step, choose Add Point for each topic. Give it a tag ID, a type, a source path holding the topic, and a direction.
5. Finish the wizard. The connection starts and your tags show live values in the Tags section.

Client connection form

Tag source addresses and payloads

A tag's source path is the MQTT topic. The rest of its settings control direction, payload handling, and publish options.

Topic wildcards

MQTT topics are hierarchical, separated by /. Two wildcards work in subscription patterns:

• + matches exactly one topic level, for example sensors/+/value.
• # matches the remaining levels and must be the last character, for example house/#.

Payload formats

Extracted values are converted to the tag's value type. Format is never detected automatically, so choose Binary explicitly for binary payloads.

Examples

Subscribe to a plain-text temperature topic:

Tag ID:         House.Kitchen.Temperature
Source Path:    sensors/temperature
Payload format: String
Direction:      Read

Extract one value from a JSON payload:

Tag ID:         House.Livingroom.Brightness
Source Path:    zigbee/light/brightness
Payload format: Json
JSON path:      $.brightness
Direction:      Read

Publish a setpoint as a retained message at QoS 1:

Tag ID:      House.Hall.Setpoint
Source Path: control/setpoint
Direction:   Write
QoS:         AtLeastOnce
Retain:      on

Mirror state in both directions on one topic:

Tag ID:         House.Hall.Light
Source Path:    devices/light/state
Direction:      ReadWrite
Payload format: String

Security and reliability

TLS / MQTTS

Turn on TLS in the connection form, or later in the Security section of the endpoint's details, and choose the certificate the client presents. See the certificates guide for managing certificate material.

Quality of service

Reconnect behavior

On connection failure the client retries with exponential backoff between the minimum and maximum wait (1 and 60 seconds by default). The keep-alive heartbeat (60 seconds by default) lets the broker detect a dead client.

Broker mode: hosting an embedded broker

Create a connection the same way, but pick the MQTT card in the Server role. Its connection form takes:

Limitations

• The embedded broker is a plain pub/sub broker: it has no tags of its own.
• Topic length is capped at 65535 bytes, the MQTT specification limit.

Observability

Logging is on by default and records MQTT TX/RX packets. In a self-hosted, peered multi-node deployment, only one node holds the active connection or broker at a time, and the role moves automatically if that node becomes unavailable. For broader device setup, return to step 6: Connect Your First Device.