MQTT Explained: The Message Bus Behind Many IoT Systems

Quickstart

If you want the fastest path from “MQTT is a mystery” to “I can build with it,” do these in order. The goal is not to memorize the spec—it’s to internalize the handful of behaviors that make or break real deployments.

Overview

MQTT is a lightweight publish/subscribe messaging protocol built around a central broker. Clients (devices, services, dashboards) connect to the broker and either publish messages to a topic, or subscribe to topics and receive messages as they arrive. This decoupling is why MQTT is often described as a “message bus” for IoT systems.

If you’re coming from HTTP: MQTT isn’t request/response. It’s streaming + fanout. One sensor publish can update many subscribers (storage service, dashboard, alerting, analytics) without the sensor knowing they exist. That’s what makes MQTT a great fit for constrained devices, intermittent connectivity, and systems that evolve over time.

Core concepts

You can use MQTT successfully with just a few core ideas. The details matter—but only a few details are “high leverage.” This section focuses on the behaviors that affect reliability, latency, and operational sanity.

Broker, client, and topics

QoS: delivery guarantees (and what “guarantee” means)

QoS is not “network reliability.” It’s a contract between client and broker about delivery semantics. The network can still drop connections, and your application still needs idempotency for commands and state updates.

Retained messages: “latest value on subscribe”

A retained message is stored by the broker per topic. When a new subscriber subscribes, the broker immediately sends the retained message (if any) before new live messages arrive. This is perfect for state: “What’s the device mode right now?” or “Is it online?”

Sessions, keepalive, and disconnect behavior

Devices disconnect. Wi-Fi drops. LTE changes IPs. MQTT is designed for this reality—but you must configure it. The key knobs are:

The common pattern for IoT fleets is: persistent session (so commands aren’t lost while offline), LWT for presence, and “desired state” topics so devices converge after reboot.

Step-by-step

Let’s build a tiny but realistic MQTT system: a broker, a subscriber, and a “device” publisher. You can run this locally, then reuse the same architecture when you move to a cloud broker or a gateway on a LAN.

Step 1 — Decide a topic layout (before you write code)

Pick a topic taxonomy that stays readable at scale. Here’s a solid default:

Step 2 — Run a broker locally (Docker)

For local development, a broker like Mosquitto is the quickest way to experiment. The snippet below runs Mosquitto and exposes the standard MQTT port.

version: "3.8"
services:
  mqtt:
    image: eclipse-mosquitto:2
    container_name: mqtt
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
      - mosq_data:/mosquitto/data
      - mosq_log:/mosquitto/log

volumes:
  mosq_data:
  mosq_log:

Step 3 — Prove routing with a subscriber and a publisher

Use CLI tools to validate topic patterns before you build firmware or backend services. Subscribe first (so you can see messages), then publish a test message.

# 1) Subscribe to everything under the root (wildcards)
mosquitto_sub -h localhost -p 1883 -v -t 'acme/site-1/#'

# 2) Publish telemetry (QoS 0)
mosquitto_pub -h localhost -p 1883 -t 'acme/site-1/device-42/telemetry/temp' -q 0 -m '{"v":21.7,"ts":1736430000}'

# 3) Publish a retained status message (so new subscribers get it immediately)
mosquitto_pub -h localhost -p 1883 -t 'acme/site-1/device-42/status' -r -q 1 -m 'online'

At this point you’ve validated the basic “message bus” flow. Now we’ll simulate a device that: (1) publishes telemetry periodically, (2) sets online/offline presence correctly, and (3) can be extended to react to commands.

Step 4 — Implement a tiny device client (with LWT + retained presence)

A good MQTT device client should handle reconnects, publish presence, and keep payloads consistent. The following Python example uses a single topic namespace and includes an LWT so the broker marks the device offline if it dies.

import json
import random
import time
import paho.mqtt.client as mqtt

BROKER_HOST = "localhost"
BROKER_PORT = 1883

ROOT = "acme/site-1/device-42"
TOPIC_STATUS = f"{ROOT}/status"
TOPIC_TELEMETRY = f"{ROOT}/telemetry/temp"

CLIENT_ID = "device-42-sim"
KEEPALIVE = 30

def on_connect(client, userdata, flags, rc):
    # Publish "online" as retained so dashboards instantly see current status.
    client.publish(TOPIC_STATUS, payload="online", qos=1, retain=True)

def on_disconnect(client, userdata, rc):
    # rc != 0 usually means unexpected disconnect; LWT will handle offline in that case.
    pass

client = mqtt.Client(client_id=CLIENT_ID, clean_session=True)

# LWT: if the client disappears without a clean disconnect, broker publishes "offline" retained.
client.will_set(TOPIC_STATUS, payload="offline", qos=1, retain=True)

client.on_connect = on_connect
client.on_disconnect = on_disconnect

client.connect(BROKER_HOST, BROKER_PORT, keepalive=KEEPALIVE)
client.loop_start()

try:
    while True:
        payload = {
            "v": round(18.0 + random.random() * 8.0, 1),
            "ts": int(time.time()),
            "unit": "C",
            "schema": "temp.v1"
        }
        # QoS 0 is fine for frequent telemetry; include timestamp so consumers can detect staleness.
        client.publish(TOPIC_TELEMETRY, payload=json.dumps(payload), qos=0, retain=False)
        time.sleep(2.0)
except KeyboardInterrupt:
    # Clean shutdown: publish offline explicitly and disconnect.
    client.publish(TOPIC_STATUS, payload="offline", qos=1, retain=True)
    client.loop_stop()
    client.disconnect()

Step 5 — Design payloads that won’t hurt you later

MQTT doesn’t enforce a payload format. That freedom is great—until you have multiple producers and consumers. Treat your payload as an API:

Step 6 — Security and operations (the “real system” checklist)

MQTT is easy to prototype—and equally easy to accidentally expose. Before any internet-facing deployment, treat these as non-negotiable:

Common mistakes

MQTT is simple, which means the mistakes are usually about design choices rather than syntax. Here are the patterns that create “it works in the lab but not in the field.”

FAQ

What is MQTT used for?

MQTT is used for lightweight messaging where many producers and consumers need to exchange data reliably, especially with constrained devices or unstable networks. Common examples: sensor telemetry, device commands, presence/status, home automation, industrial monitoring, and dashboards that update in real time.

What’s the difference between MQTT QoS 0, 1, and 2?

QoS 0 is best-effort (fastest). QoS 1 retries until acknowledged (delivery is “at least once,” so duplicates can occur). QoS 2 uses a longer handshake for “exactly once” delivery (highest overhead). In practice, most IoT systems use QoS 0 for telemetry and QoS 1 for commands/status that must arrive.

When should I use retained messages?

Use retained messages for state where the “latest value” matters to new subscribers: online/offline status, current mode, last reading, desired configuration. Avoid retaining transient events (alarms, button presses) because new subscribers will see the last retained value and may misinterpret it as a new event.

How do I model commands in MQTT?

For simple systems, publish commands to a per-device topic (often QoS 1) and include an ID so duplicates are safe. For more robust systems, publish a retained desired state and let devices report a retained reported state. Desired/reported state is resilient to offline devices and reboots.

Does MQTT work in browsers?

Many brokers support MQTT over WebSockets, which makes browser clients possible. The mental model remains the same (publish/subscribe), but you’ll typically terminate WebSockets at the broker and keep standard MQTT for devices.

How do I secure MQTT?

Use per-client authentication, strict topic-based ACLs, and TLS when traffic crosses untrusted networks. Also separate environments and avoid broad wildcard access in production. Security is less about the protocol and more about who is allowed to publish/subscribe to which topics.

Cheatsheet

Keep this section bookmarked. It’s the fast scan for “what should I choose?” and “what’s the safe default?”

Wrap-up

MQTT is popular in IoT for a reason: it’s simple, efficient, and built for unreliable networks. The trick is to use the protocol’s “superpowers” on purpose—topics as a namespace, QoS as a tradeoff, retained messages for state, and LWT + sessions for real-world connectivity.

If you take one practical pattern from this post, take this: model device control as desired state + reported state, and use retained messages so devices recover from offline periods automatically. That single decision makes fleets far easier to operate.

Want to go deeper? The related posts below pair well with MQTT when you’re building real devices and deploying safely.

Related posts

• ESP32 Starter Guide: GPIO, Wi-Fi, and Real Projects
• Bluetooth Low Energy Basics: Advertising, GATT, and Power
• Power Optimization in IoT: Sleep Modes and Battery Math
• OTA Updates for IoT: The Safe Way to Ship Firmware
• Sensors 101: Noise, Calibration, and Real Signal Reading
• Home Automation Architecture: Local-First vs Cloud