MQTT (Mosquitto)

MQTT is the lightweight publish/subscribe protocol of devices and sensors. The MQTT add-on runs Eclipse Mosquitto, a small, widely used MQTT broker: devices publish readings to topics, and subscribers (apps, workspaces, streaming workflows) receive them as they arrive.

Overview

• Versions: 2.1.2, 2.0.22, 2.0.21 (default: 2.1.2)
• Default Port: 1883
• Cluster Support: No (one broker)
• Use Cases: IoT telemetry, sensor readings, device commands, last-known values per device
• Sign-in: the add-on's username and password; a client without them is refused

Key Features

• Topics and wildcards: topics are paths such as factory/line-A/sensors/temp; a subscription can use + (one level) and # (everything below)
• Retained messages: a message published as retained is the topic's last value, sent to every new subscriber at once
• Quality of service: QoS 0 (at most once), 1 (at least once) and 2 (exactly once)
• Persistent sessions: a client that connects without a clean session gets the messages it missed while away

Resources

Setting	Options	Default
CPU (vCPU)	Any number of cores, e.g. 0.25, 0.5	0.25
Memory	Any amount in GB	0.25 GB
Disk	Any amount in GB	1 GB

Mosquitto is small: a quarter of a CPU and 256 MB of memory serve thousands of devices. Disk holds retained messages and persistent sessions.

Creating an MQTT Add-on

1. Navigate to Add-ons and click Create Add-on
2. Select MQTT (Mosquitto) as the type
3. Choose a version
4. Configure the Add-on Label, an optional Description and the resources
5. Optionally enable automatic backups
6. Click Create Add-on

The add-on is RUNNING once the broker accepts the add-on's credentials and refuses a client without them.

Connection Information

The Connection tab shows the host, port, username and password. In STRONGLY_SERVICES the add-on is under services.addons.mqtt:

{
  "id": "addon-abc123defg",
  "name": "plant-sensors",
  "type": "mqtt",
  "category": "add-on",
  "status": "running",
  "version": "2.1.2",
  "connection": {
    "connection_string": "mqtt://user_a1b2c3d4:<password>@<internal-host>:1883",
    "host": "<internal-host>",
    "port": 1883,
    "ssl": false
  },
  "auth": {
    "method": "username_password",
    "credentials": { "username": "user_a1b2c3d4", "password": "<password>" }
  }
}

host, port and ssl mean the same as on an MQTT data source, so code and workflow nodes that read one read the other.

Python

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

services = json.loads(os.environ['STRONGLY_SERVICES'])
broker = next(a for a in services['services']['addons']['mqtt'] if a['name'] == 'plant-sensors')

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.username_pw_set(broker['auth']['credentials']['username'], broker['auth']['credentials']['password'])
client.on_message = lambda c, u, msg: print(msg.topic, msg.payload)
client.connect(broker['connection']['host'], broker['connection']['port'])
client.subscribe('factory/+/sensors/#', qos=1)
client.publish('factory/line-A/sensors/temp', '{"c": 21.5}', qos=1, retain=True)
client.loop_forever()

Node.js

const mqtt = require('mqtt');

const services = JSON.parse(process.env.STRONGLY_SERVICES);
const broker = services.services.addons.mqtt.find(a => a.name === 'plant-sensors');
const client = mqtt.connect(`mqtt://${broker.connection.host}:${broker.connection.port}`, {
  username: broker.auth.credentials.username,
  password: broker.auth.credentials.password,
});
client.on('connect', () => client.subscribe('factory/+/sensors/#', { qos: 1 }));
client.on('message', (topic, payload) => console.log(topic, payload.toString()));

In Streaming Workflows

The Streaming MQTT Source subscribes to topics and turns each message into a frame (with its topic, QoS and retained flag). Its Connection Type picks an MQTT add-on or an MQTT data source (a broker you run elsewhere, with TLS and certificates when it needs them); the node reads either the same way.

The IoT Anomaly Responder template offers three choices on its install form: create a new MQTT add-on, use one you have, or use an MQTT data source.

Backups

An MQTT backup holds the broker's retained messages (each topic's last value, with its QoS). Persistent sessions and messages queued for offline clients are not part of a backup.

• Back up now: click Back Up Now on the Backup tab while the add-on is running.

• Automatic: on the Backup tab turn on Enable Automatic Backups, choose a Backup Schedule and a Retention, and click Save Configuration.

• History: the Backup tab lists every backup with its status, size and any error.

• Restore: click Restore next to a succeeded backup and confirm. The retained messages are replaced by the backup's: retained messages the backup does not have are cleared. Connected clients stay connected and receive the restored retained messages on their next subscribe. A retained message published at QoS 2 is restored at QoS 1. See Restoring a backup.

Monitoring

The Metrics tab measures the running add-on live: CPU, memory and disk use, network traffic, open and new connections, response time (a subscribe round trip) and health. The Logs tab shows the broker's log, including each client's connect and disconnect.

Best Practices

1. Design topics as paths from general to specific (site/line/device/measurement) so wildcards select what a subscriber needs
2. Retain last values (status, configuration) and not streams of readings
3. Use QoS 1 for readings you must not lose; QoS 0 for high-rate telemetry where a gap is fine
4. Give each device its own client id so persistent sessions do not collide

Related Documentation

• Managed Add-ons Overview
• Apache Kafka
• Streaming workflows