4  MQTT Publish-Subscribe Basics

mqtt
fund
pubsub

4.1 Start With One Publication

Imagine a door sensor publishing home/front-door/contact = open. The sensor does not know whether a phone app, alarm panel, logger, or automation rule is listening. MQTT publish-subscribe works because the broker receives one publication, matches it to subscriptions, and leaves evidence about who should receive it next.

4.2 MQTT Pub-Sub Separates Senders, Receivers, and Evidence

MQTT publish-subscribe is a broker-mediated messaging pattern. A device publishes a message to a topic. The broker receives it and forwards it to clients whose subscriptions match that topic. The publisher does not need to know who is listening, and each subscriber does not need to know which device produced the message.

This decoupling is why MQTT fits many IoT telemetry and command workflows. A sensor can keep publishing readings as dashboards, rules engines, data stores, and maintenance tools subscribe or unsubscribe over time. The broker becomes the routing and delivery boundary that must be designed, secured, observed, and tested.

Broker Bex, the messaging guide

Broker Bex

“A message with no subscriber is a tree falling in an empty forest — design the topic before the payload.”

Through this chapter, Bex keeps one board per message: which topic names it, what delivery it needs, and who is subscribed when it arrives.

MQTT publish-subscribe message flow showing a publisher sending a topic message to a broker, a subscriber registering a matching topic filter, and the broker forwarding the matched payload.
MQTT pub-sub has three visible decisions: the publisher names the topic, the subscriber registers a topic filter, and the broker decides which publications match before forwarding data.

If you only need the intuition, this layer is enough: MQTT is not device-to-device chat. It is topic-based routing through a broker. The useful review questions are who may publish, who may subscribe, what topic path is used, and what evidence proves the broker delivered the right message to the right consumers.

That separation is helpful only when the topic contract is explicit. The publisher owns the message family and payload version. The broker owns the match between concrete topic names and subscription filters. Each subscriber owns the reason it needs the stream and the limit on how broad its filter may be. When a new dashboard or analytics job is added, the sensor firmware should not need a new destination list; the broker should start routing after the new client subscribes to the approved filter.

A quick pub-sub review therefore asks for a small evidence trail: publisher client id, publish topic, subscriber filter, broker access-control result, delivery count, and any retained or queued state. Without that trail, "decoupled" can become hidden coupling because nobody can prove which clients are supposed to receive which messages.

The One-Minute MQTT Roles

Publisher

A client that sends a message to a named topic, such as site/greenhouse-2/air/temperature.

Broker

The routing service that authenticates clients, receives publishes, matches subscriptions, and forwards messages.

Subscriber

A client that registers interest in an exact topic or topic filter, then receives matching messages from the broker.

Beginner Examples

  • A soil sensor publishes moisture readings. A dashboard and irrigation rule both subscribe without requiring firmware changes on the sensor.
  • A maintenance service subscribes to device health topics. It can be added after deployment because the publisher only knows the topic, not every future consumer.
  • A broad wildcard can be useful for operations, but dangerous for normal applications if it exposes unrelated devices or overloads a subscriber.

Overview Knowledge Check

If this explains the role split, you can stop here. Continue to Practitioner when you need to design a topic and subscription record for a real deployment.

4.3 Design the Topic and Subscription Record

A useful MQTT design starts with one message family, not with a broker product. Name the message, its topic, the publisher identity, the allowed subscribers, the delivery behavior, and the evidence that shows routing worked.

Topic Record Workflow

1. Name the message family. State whether the message is telemetry, state, command, alert, configuration, or maintenance data.
2. Write the topic shape. Choose stable path levels such as site, area, device, capability, and signal. Keep names predictable and avoid hiding meaning in payload-only fields.
3. Define subscription filters. Record exact topics and any + or # wildcard use, including who owns each broad subscription.
4. Choose delivery state. Record QoS, retained-message use, session behavior, last-will status, duplicate handling, and stale-data policy.
5. Keep broker evidence. Record client id, authentication result, publish count, matched subscriptions, delivery acknowledgements, disconnects, and rejected topics.

Worked Example: Greenhouse Telemetry

A greenhouse sensor publishes air temperature every few minutes. The dashboard needs fresh values. The automation rule needs alerts. The data warehouse needs history. A topic record keeps those needs separate instead of forcing the sensor to know every consumer.

Design Item
Record
Why It Matters
Review Evidence
Publish topic
site/greenhouse-2/sensor-17/air/temperature
The path names the site, device, capability, and measured signal.
Broker log shows accepted publish from the expected client id.
Dashboard subscription
site/greenhouse-2/+/air/temperature
The + wildcard receives one device level without subscribing to unrelated sites.
Subscriber count and received-message trace match the expected greenhouse devices.
Operations subscription
site/greenhouse-2/#
A broad filter is reserved for operations tools, not embedded in every application.
Access-control rule shows only the operations role can use the broad filter.
Freshness policy
Timestamp in payload, stale marker in dashboard, and last-will status topic.
Users can distinguish current readings from retained or delayed values.
Dashboard test shows stale values are marked instead of presented as live.

Bex’s Topic Board

  • Topic: the path itself names site, device, capability, and signal — site/greenhouse-2/sensor-17/air/temperature.
  • QoS: delivery state is written into the record — QoS, retained use, session behavior, last will.
  • Subscriber: the broad # filter belongs to operations alone; retained or delayed values are marked stale, never live.

This record avoids two common mistakes: making the topic too vague for authorization, and using wildcards so broadly that subscribers receive data they do not need or should not see.

Practitioner Knowledge Check

If your job is to design a usable MQTT namespace, this topic and subscription record is the artifact to keep. Continue to Under the Hood for broker and session boundaries.

4.4 Broker Routing, Sessions, and Failure Boundaries

The MQTT broker is not just a pipe. It authenticates clients, checks authorization, stores session state when configured, matches topic filters, forwards messages, handles retained messages, and may publish last-will status when a client disconnects unexpectedly.

Broker Boundary Ledger

Boundary
Broker Responsibility
Evidence to Keep
Failure Question
Client connection
Accept or reject the client identity and connection parameters.
Client id, authentication result, connection time, clean or persistent session setting.
Did the right client connect under the right identity?
Publish authorization
Decide whether a client may publish to a topic.
Accepted and rejected publish logs, ACL rule, topic path, payload size, QoS.
Did a device publish only to its permitted namespace?
Subscription matching
Match exact topics and wildcard filters to incoming publishes.
Subscription filter, matched topic count, broad wildcard ownership, subscriber identity.
Did the broker route messages to the intended consumers only?
Delivery state
Apply QoS behavior, retained-message handling, queued messages, and last-will publication.
Acknowledgement trace, retained flag, session queue, duplicate handling, last-will event.
Can the system explain duplicates, stale state, offline status, and missed messages?

Mechanics That Matter

  • Topic filters are routing rules. The + wildcard matches exactly one topic level; # matches all remaining levels and should be tightly controlled.
  • QoS is delivery behavior, not application truth. MQTT QoS can help with message transfer, but the application still needs freshness, idempotency, and duplicate handling.
  • Retained messages are state snapshots. They help new subscribers see the latest value, but they can also make old state look current if freshness is not visible.
  • Last will is failure evidence. It gives the broker a way to publish an offline status when a client disappears without a graceful disconnect.

Bex’s Topic Board

  • Topic: + matches exactly one level; # takes every level that remains.
  • QoS: it moves the message, not the truth — freshness, idempotency, and duplicates stay application work.
  • Subscriber: a retained snapshot greets late subscribers; last will speaks for a client that vanished mid-session.

Common Review Pitfalls

  1. Using # for normal applications. Broad subscriptions are easy during testing and risky in production.
  2. Putting authorization only in application code. Broker topic ACLs should prevent the wrong publisher or subscriber path before the message reaches application logic.
  3. Confusing retained with fresh. A retained value can be useful and still be old; show age or source timestamp.
  4. Ignoring offline semantics. Without a status topic, last-will policy, and stale-data rule, missing devices can look healthy.

Under-the-Hood Knowledge Check

At this depth, MQTT is a broker contract. The topic tree, subscription filters, client identity, delivery state, and failure semantics should be explicit enough that routing behavior can be reviewed after deployment.

4.5 Summary

  • MQTT publish-subscribe routes messages through a broker, so publishers and subscribers do not need direct knowledge of each other.
  • Topic design is a product and operations contract, not just a string convention.
  • The + wildcard matches one topic level; # matches the remaining levels and should be restricted.
  • QoS, retained messages, persistent sessions, and last will shape delivery evidence, but they do not remove the need for application-level freshness and duplicate handling.
  • A defensible MQTT design records publisher identity, topic shape, subscriber filters, broker ACLs, delivery behavior, and stale-data handling.

4.6 Key Takeaway

Design MQTT from the topic contract outward: name who may publish, who may subscribe, what broker evidence proves routing, and how applications handle stale, duplicate, or missing messages.

4.7 See Also

MQTT Architecture

Review broker components, clients, sessions, and deployment architecture.

MQTT Topic Design and Wildcards

Deepen topic hierarchy, wildcard filtering, and namespace design.

MQTT Quality of Service Levels

Connect pub-sub routing to QoS, duplicates, sessions, and reliability tradeoffs.

MQTT Security Fundamentals

Apply authentication, ACLs, TLS, and topic isolation to the broker boundary.