MQTT¶

!! abstract "Summary"

- **MQTT (Message Queuing Telemetry Transport)** is a lightweight **publish/subscribe** messaging protocol built for constrained devices and unreliable networks — exactly the conditions IoT devices usually live in.
- Unlike HTTP's request/response model, MQTT clients never talk to each other directly — every message passes through a central **broker**, which routes messages based on **topics** rather than destination addresses.
- It's an OASIS standard, currently at version 5.0 (with 3.1.1 still widely deployed), and runs over TCP — typically port `1883` unencrypted, or `8883` over TLS.

!!! tip "Think of MQTT as:"

    "A radio station, not a phone call — publishers broadcast onto a named channel (topic), and anyone tuned in (subscribed) hears it, with no idea who else is publishing or listening."

Overall Ideas¶

A Bit of History¶

MQTT wasn't designed for the modern IoT boom — it was invented in 1999 by Andy Stanford-Clark (IBM) and Arlen Nipper (Arcom, now Cirrus Link) to solve a much narrower problem: monitoring oil pipeline sensors over satellite links that were slow, expensive per byte, and frequently dropped.¹ Those constraints shaped five design goals that still define MQTT today — simple to implement, support a range of QoS levels, lightweight and bandwidth-efficient, agnostic to the data it carries, and able to maintain continuous session awareness across an unreliable link.¹

Why It Caught On for IoT¶

• Minimal overhead — the fixed header can be as small as 2 bytes, so framing cost stays trivial even for a tiny payload.
• Bandwidth efficient — pub/sub means the network carries a message once per interested party (via the broker), not once per potential recipient.
• Flexible reliability — QoS 0–2 lets each individual message pick its own tradeoff, instead of forcing an entire application into one reliability model.
• Bidirectional & connection-aware — the broker can push data to a client at any time, and Keep Alive plus LWT mean a dropped connection gets detected and reported quickly, not silently.
• Scales to many-to-many — thousands of devices can publish to, or subscribe from, the same broker without any of them knowing about each other.

Built on TCP/IP¶

MQTT doesn't reinvent reliable delivery — it's an application-layer protocol that assumes an already-established TCP connection underneath, and leans on TCP for what TCP already does well: guaranteed delivery, in-order bytes, and retransmission of lost packets at the transport layer.² That's a deliberate choice, not an oversight — it's exactly what lets MQTT's own framing stay so minimal. The tradeoff is that MQTT needs a working, connection-oriented network underneath it, which is part of why MQTT-SN exists — for links too constrained to justify a full TCP stack.

Publish/Subscribe Architecture¶

Every MQTT connection is between one client and the broker — clients never connect directly to each other.¹ This decoupling is the whole point:

• A publisher doesn't need to know who (or how many) subscribers exist.
• A subscriber doesn't need to know who's publishing.
• Publishers and subscribers don't even need to be connected at the same time — that's what retained messages and sessions exist to handle.

Topics & Wildcards¶

Topics are hierarchical, UTF-8 strings with levels separated by / — for example, home/livingroom/temperature. There's no need to "create" a topic in advance; publishing or subscribing to one simply makes it exist.

Subscribers can use two wildcard characters when subscribing (never when publishing):²

Quality of Service (QoS)¶

MQTT defines three delivery guarantees, chosen per-message by the publisher and capped per-subscription by the subscriber:²

Retained Messages & Last Will and Testament¶

Two features specifically address MQTT's async nature — that publishers and subscribers aren't guaranteed to be online at the same time:

• Retained messages — when a publisher sets the retain flag, the broker stores that message (only the single most recent one per topic) and immediately delivers it to any client that subscribes afterward, rather than making them wait for the next publish.⁴
• Last Will and Testament (LWT) — a client can register a message, at connect time, that the broker will publish on its behalf if that client disconnects ungracefully (network drop, timeout) rather than cleanly (a proper DISCONNECT packet).⁵

Sessions & Keep Alive¶

• Clean Session (MQTT 3.1.1) / Session Expiry Interval (MQTT 5.0) — controls whether the broker discards a client's subscriptions and undelivered QoS ½ messages when it disconnects, or preserves them for when it reconnects.⁶
• Keep Alive — the client tells the broker, at connect time, the longest gap it will allow between packets. If nothing else is sent, the client pings the broker with PINGREQ (answered with PINGRESP) to prove the connection is still alive. If the broker hears nothing for 1.5× the Keep Alive interval, it closes the connection and fires the client's LWT if one was set.⁶

MQTT Control Packets¶

Every MQTT interaction is built from one of 15 Control Packet types, each identified by a 4-bit type value in the packet's fixed header:²

Overall Flow¶

Putting everything above together, a typical MQTT session looks like this:⁸

1. Connect — client sends CONNECT, broker replies CONNACK.
2. Subscribe — client sends SUBSCRIBE with one or more topic filters, broker replies SUBACK confirming the granted QoS for each.
3. Exchange messages — as matching messages are published (by this client or any other), the broker forwards them as PUBLISH packets, running whatever QoS handshake that message's QoS level requires.
4. Stay alive — during any quiet period, PINGREQ/PINGRESP keep the connection alive.
5. Disconnect — client sends DISCONNECT to close cleanly, suppressing its LWT.

This is why nothing on this page needed a separate diagram for "how you connect" versus "how you publish" — it's all one continuous session, built entirely from the packets and concepts already covered above.

Example¶

The fastest way to actually feel how MQTT works is two terminals and a local broker — no cloud account, no IoT device required.

Install Mosquitto — an open-source MQTT broker that also ships the mosquitto_pub/mosquitto_sub CLI clients:

sudo apt install -y mosquitto mosquitto-clients
sudo systemctl status mosquitto

Mosquitto starts automatically on install, listening on localhost:1883.

Terminal 1 — subscribe and leave it running:

mosquitto_sub -h localhost -t "kuoquo/test" -v

Terminal 2 — publish a message:

mosquitto_pub -h localhost -t "kuoquo/test" -m "Hello from Terminal 2"

You should see the message appear in Terminal 1 immediately — that round trip is the entire flow described above: CONNECT/CONNACK for both clients, SUBSCRIBE/SUBACK for Terminal 1, and a PUBLISH the broker forwarded the moment it arrived.

MQTT 5.0: What's New¶

MQTT 5.0 (2019) added several features on top of 3.1.1,⁹ without changing the core pub/sub model:²

• Reason Codes — nearly every acknowledgment packet can now carry a specific reason for success or failure, instead of MQTT 3.1.1's mostly binary outcomes.
• User Properties — arbitrary key/value metadata attachable to most packets.
• Session Expiry Interval & Message Expiry Interval — finer-grained, explicit control (in seconds) over how long a session or an individual message survives, including how long a retained message sticks around.¹⁰
• Topic Alias — lets a client substitute a short integer for a long topic name after the first use, shrinking repeated PUBLISH overhead.
• Shared Subscriptions — multiple clients can subscribe to the same topic filter as a group, with the broker load-balancing messages across them rather than delivering to every member.
• Request/Response pattern support — standardized Response Topic and Correlation Data properties, making RPC-style interactions over MQTT's pub/sub model much cleaner to implement.

MQTT-SN: For Constrained Devices¶

MQTT-SN (MQTT for Sensor Networks) is a related but separate specification — not simply "MQTT over UDP" — designed for devices too constrained even for MQTT's already-light TCP footprint, such as battery-powered sensors on low-power radio links. It replaces long text-based topic names with short pre-registered topic IDs, and typically talks to the rest of an MQTT network through a gateway that translates between MQTT-SN and standard MQTT.

Best Practices¶

Guidance drawn from how the concepts above actually get used in production:

• Design topics deliberately — use a consistent hierarchy (e.g., <location>/<device-type>/<device-id>/<measurement>), and treat topic names as a stable API, not an afterthought. Changing them later breaks every subscriber depending on the old names.
• Default to QoS 0, not QoS 2 — QoS 2's four-packet handshake has real overhead. Reach for QoS 1 or 2 only when a specific message actually needs the stronger guarantee — a command is a better candidate than a repeating sensor reading, where the next update arriving soon anyway makes an occasional drop harmless.
• Set an LWT on every long-lived client — it's the only reliable way subscribers learn a device went offline unexpectedly, rather than assuming silence just means "nothing to report."
• Use retained messages for state, not one-off events — a device's current status is a good fit; a discrete event like a button press generally isn't, since a new subscriber would receive that "stale" retained event as if it just happened.
• Use TLS (8883) outside a trusted local network — plain MQTT (1883) sends everything, including usernames and passwords, in cleartext.
• Keep payloads small and structured — JSON is common and interoperable, but for genuinely constrained devices, a compact binary format (CBOR, Protobuf) can meaningfully cut bandwidth and parsing cost.
• Set a sensible Keep Alive, not the maximum — too long delays detecting a dead connection (and firing the LWT); too short wastes bandwidth on pings. Tens of seconds to a few minutes covers most IoT use cases.

Useful Resources¶

• MQTT Version 5.0 — OASIS Standard — the current specification
• MQTT Version 3.1.1 — OASIS Standard — still the most widely deployed version
• HiveMQ — MQTT Essentials, a ten-part series covering these concepts in more depth
• ShareTechnote — IoT: MQTT — byte-level packet structure and a captured protocol sequence
• Mosquitto — the open-source broker used in the example above