MQTT: a working guide to topics, QoS, security and Sparkplug B

Catalin NegruPublished 4 min read

MQTT is a publish and subscribe messaging protocol that runs over TCP. A client publishes a message to a named topic on a broker, and the broker forwards it to every client subscribed to that topic. The publisher and the subscribers never connect to each other, and each of them opens its connection outward to the broker, which is why MQTT suits devices behind firewalls, on cellular links and on networks that drop.

This guide covers what is in the packets, which settings decide whether a message arrives, and which mistakes produce which symptoms. The protocol facts come from the OASIS MQTT 3.1.1 and MQTT 5.0 standards and, for Sparkplug, from the Eclipse Sparkplug specification.

Where MQTT is found

In industrial settings MQTT is the uplink more often than the field bus. A gateway reads a PLC over Modbus or OPC UA on the plant network, then publishes the values over MQTT to a broker on site or in the cloud. Sensors with their own firmware, cellular modems, LoRaWAN network servers and edge computers publish directly. Historians, dashboards and analytics subscribe.

The reason is the direction of the connection. A polled protocol needs the reader to reach the device, which means an inbound path to the plant. With MQTT the device dials out, sends only what changed, and tells the broker what to announce if it disappears.

How the pages in this guide fit together

What is MQTT? explains clients and brokers, a CONNECT and a PUBLISH packet decoded byte by byte, sessions, keep alive and the Last Will, the differences between versions 3.1.1 and 5.0, and how the protocol compares with Modbus and OPC UA.

MQTT topics and wildcards covers topic names and topic filters: the / level separator, the + and # wildcards with a match table, retained messages, $ topics and shared subscriptions.

MQTT QoS covers the three delivery levels: the packet exchange for each, what the DUP flag and packet identifier do, why the level is set per hop, and what it takes for a message to be queued for an offline client.

MQTT ports lists the registered ports, 1883 and 8883, how MQTT over WebSockets is carried, and what a firewall has to allow.

MQTT security covers TLS, user name and password, client certificates, MQTT 5.0 enhanced authentication, and per-topic authorization.

Sparkplug B covers the specification that fixes a topic namespace, a Protocol Buffers payload and birth and death messages on top of MQTT, so that industrial publishers and consumers agree without a private convention.

The problems that take the most time

SymptomUsual causeCovered in
Two devices keep disconnecting each otherBoth connect with the same client identifierMQTT security
A subscriber receives nothing, with no errorTopic names are case sensitive, or a leading / adds an empty levelMQTT topics and wildcards
A new subscriber sees an old value immediatelyA retained message is stored on that topicMQTT topics and wildcards
Messages sent while a client was offline never arriveClean session, or a QoS 0 subscriptionMQTT QoS
The same reading is stored twiceQoS 1 redelivery after a reconnectMQTT QoS
The TCP connection opens, then closes at onceA TLS client on port 1883, or a plain client on 8883MQTT ports
A device shows online long after it lost powerNo Last Will, or a keep alive that is too longWhat is MQTT?

Using MQTT with ControlCom

ControlCom Connect, the hosted platform, has an MQTT broker that devices publish to over TLS on port 8883. A device you write the integration for yourself is registered as a Generic device. Creating it provisions a certificate and shows the connection details: the endpoint, the client ID and the topic. The device authenticates with its certificate and private key and publishes a JSON payload whose dataArray holds a key, a value and an optional millisecond timestamp per reading. The connection is outbound only; nothing on site has to be reachable from outside. The MQTT documentation  has the payload formats and a code example, and the Node-RED walkthrough shows the same steps without writing a client.

The ControlCom Edge Server, the on-site component, covers equipment you cannot reprogram. It reads devices over industrial protocols and ships the values to ControlCom Connect through its own outbound MQTT publisher. It also runs a local Sparkplug B broker, with a listener rule that maps inbound Sparkplug metrics to platform variables and an MQTT Explorer tool for browsing the topic tree. The page for controls engineers describes how this fits a commissioning workflow.

Register a Generic device, download its certificate, and publish JSON to its topic on port 8883. The values land in ControlCom Connect as variables that can be trended, alarmed on and reported.

In this guide

  1. 1What is MQTT? Clients, brokers and the packets between themWhat MQTT is and how it works: clients, brokers and topics, a CONNECT and PUBLISH packet decoded, sessions, keep alive, the Last Will, and 3.1.1 vs 5.0.
  2. 2MQTT topics and wildcards: syntax, matching rules and retained messagesMQTT topics explained: level syntax, the + and # wildcards with a match table, retained messages, $ topics, shared subscriptions and naming mistakes.
  3. 3MQTT QoS: what levels 0, 1 and 2 guarantee and what they costMQTT QoS explained: the packet exchange for levels 0, 1 and 2, the DUP flag and packet identifier, QoS downgrade, offline queueing and which level to use.
  4. 4MQTT port numbers: 1883, 8883 and MQTT over WebSocketsThe MQTT port for plain TCP is 1883 and for TLS it is 8883. How MQTT over WebSockets is carried, what a firewall must allow, and how to test a connection.
  5. 5MQTT security: TLS, authentication and topic access controlMQTT security in practice: TLS on port 8883, user names and passwords, client certificates, MQTT 5.0 enhanced authentication and per-topic access control.
  6. 6MQTT Sparkplug B: topic namespace, birth and death messages, and payloadMQTT Sparkplug B explained: the spBv1.0 topic namespace, birth and death certificates, the Protocol Buffers payload, sequence numbers and host state.