MQTT is the messaging protocol that powers the FidesInnova IoT ecosystem — and most of the IoT industry. Understanding how it works, how to configure it securely, and how it integrates with the FidesInnova Node is essential for any developer building on the platform.
This guide covers MQTT from first principles through to production-grade MQTTS (TLS-secured MQTT) configuration, with practical examples for connecting devices to the FidesInnova Node.
What Is MQTT?
MQTT (Message Queuing Telemetry Transport) is a lightweight publish-subscribe messaging protocol designed specifically for constrained devices and low-bandwidth, high-latency networks. It was originally developed by IBM and Cirrus Link for satellite-linked oil pipeline monitoring in the 1990s — a context that perfectly matches the requirements of modern IoT.
MQTT runs over TCP/IP. The core architecture has three components:
- Broker — the central server that receives all messages and routes them to subscribers. FidesInnova Node includes an integrated broker (based on Mosquitto/EMQX).
- Publisher — a client (typically an IoT device) that sends messages to the broker on a topic.
- Subscriber — a client that receives messages from the broker for topics it has subscribed to.
Topics: The Routing Layer
MQTT routes messages using topics — hierarchical strings that act as address channels. A device publishes to a topic; a subscriber receives all messages on that topic. Topics use forward slashes as separators and support wildcards:
# Example topic structure for a FidesInnova deployment
building/floor3/room12/temperature
building/floor3/room12/humidity
building/floor3/+/temperature # + wildcard: all rooms on floor 3
building/# # # wildcard: everything in the building
Quality of Service (QoS) Levels
MQTT defines three QoS levels that balance delivery reliability against network overhead:
QoS 0 — At Most Once
Fire-and-forget. The broker does not acknowledge receipt. Fastest, but messages can be lost if the connection drops. Suitable for high-frequency sensor readings where occasional loss is acceptable.
QoS 1 — At Least Once
The broker acknowledges receipt. Messages are retransmitted until acknowledged — duplicates possible. Good for alerts and events where loss is unacceptable but duplicates are tolerable.
QoS 2 — Exactly Once
Four-way handshake ensures exactly one delivery. Highest overhead. Required for billing, transaction, and ZKP proof submission events where duplicate or missing messages would corrupt records.
For FidesInnova ZKP proof submissions, always use QoS 2 to guarantee exactly-once delivery to the blockchain submission queue.
Connecting to the FidesInnova Node
The FidesInnova Node exposes an MQTT broker on port 1883 (plain) and 8883 (TLS/MQTTS). All production deployments should use 8883. Here is a complete connection example in C++ for an ESP32 device:
#include <WiFiClientSecure.h>
#include <PubSubClient.h>
// Node TLS certificate (obtain from your FidesInnova Node dashboard)
const char* ca_cert = "-----BEGIN CERTIFICATE-----
...";
WiFiClientSecure espClient;
PubSubClient client(espClient);
void setup() {
espClient.setCACert(ca_cert);
client.setServer("your-node.fidesinnova.io", 8883);
client.connect(deviceId, username, token);
}
void publishReading(float temp) {
String payload = "{\"temp\":" + String(temp) + "}";
client.publish("sensor/temperature", payload.c_str(), true); // retained
}
MQTTS: TLS Security for Production IoT
Plain MQTT transmits all data — including device credentials and sensor readings — in cleartext. Any network observer can read and modify the traffic. MQTTS adds TLS encryption, providing:
- Confidentiality — all traffic is encrypted; passive eavesdroppers see only ciphertext
- Integrity — TLS MACs detect any in-transit modification of messages
- Authentication — clients verify the broker's identity via its TLS certificate, preventing man-in-the-middle attacks
- Mutual TLS (mTLS) — optionally, clients present their own certificate, cryptographically authenticating the device to the broker
Certificate Management
The FidesInnova Node generates a self-signed CA certificate during setup. Device firmware must include this CA certificate to verify the broker's identity. For production deployments with Let's Encrypt or a commercial CA, devices can use the standard root CA bundle.
# Generate device certificate for mTLS (on Linux/Mac)
openssl genrsa -out device001.key 2048
openssl req -new -key device001.key -out device001.csr \
-subj "/CN=device-001/O=FidesInnova"
openssl x509 -req -in device001.csr \
-CA node-ca.crt -CAkey node-ca.key \
-CAcreateserial -out device001.crt -days 3650
Retained Messages and Last Will
Two MQTT features are particularly useful for IoT deployments:
Retained messages — the broker stores the last message on a topic and delivers it immediately to any new subscriber. This is essential for device state topics: a new subscriber to device/001/status immediately receives the current status without waiting for the next publication.
Last Will and Testament (LWT) — a message the broker publishes automatically on a device's behalf if the device disconnects ungracefully. Configure LWT to publish to a device/offline topic when a device loses connectivity — the FidesInnova Node Service Contracts can react to these events to trigger alerts.
// Set LWT before connecting
client.setWill(
"device/001/status", // topic
"offline", // payload
1, // QoS
true // retained
);
MQTT Best Practices for FidesInnova Deployments
- Always use MQTTS (port 8883) in production — never transmit device credentials or sensor data over plain MQTT
- Use unique client IDs — duplicate client IDs cause connection conflicts; use the device's hardware MAC address or a UUID
- Set appropriate QoS — QoS 0 for high-frequency sensor streams, QoS 2 for ZKP proof submissions and critical events
- Use retained messages for state topics — ensures late-joining subscribers get current state immediately
- Implement exponential backoff for reconnections — prevents broker overload when many devices reconnect simultaneously after an outage
- Topic namespace discipline — use consistent hierarchical topic naming (site/floor/room/sensor) to make Service Contract subscriptions manageable
- Enable LWT for all devices — allows the Node and Service Contracts to detect and respond to unexpected device disconnections
MQTT and ZKP: The Complete Trust Stack
MQTT provides the transport layer — efficient, reliable message delivery from device to node. ZKP provides the trust layer — cryptographic proof that the payload is authentic. Together, they form the complete FidesInnova security model:
- MQTTS encrypts the channel — nobody can eavesdrop or modify messages in transit
- Device authentication (mTLS or token) proves the connection comes from a legitimate device
- ZKP proofs prove the payload content is authentic — even if the device is compromised
- Blockchain storage creates an immutable, timestamped record of every proof