9 MQTT Publisher-Subscriber Setup

mqtt

impl

getting

started

In 60 Seconds

Getting started with MQTT requires three components: a broker (message server like Mosquitto), a publisher (sends data to topics), and a subscriber (receives data from topics). This chapter walks through building your first MQTT application using either browser-based Wokwi simulators requiring no hardware setup, or Python scripts with the paho-mqtt library.

9.1 Start With One Local Loop

The first MQTT build should be small enough to watch end to end: start a broker, publish one temperature value, subscribe to the matching topic, and confirm the payload arrives. Once that loop works, every later feature has a place to attach: QoS, sessions, TLS, dashboards, and lab evidence.

9.2 Learning Objectives

By the end of this chapter, you will be able to:

Explain MQTT System Components: Describe the role of each of the three essential parts (broker, publisher, subscriber) and how they connect to form a complete IoT messaging system
Demonstrate Browser Simulators: Execute MQTT code in Wokwi simulators without any hardware setup, observing publish-subscribe message flow in real time
Implement an MQTT Publisher: Construct a Python script that sends sensor data to an MQTT broker using the paho-mqtt library
Implement an MQTT Subscriber: Construct a Python script that receives and displays MQTT messages, including threshold-based alerting logic
Select Your Learning Path: Evaluate the trade-offs between simulator-based learning and real hardware projects, then justify your choice based on available resources and goals

Key Concepts

MQTT: Message Queuing Telemetry Transport — pub/sub protocol optimized for constrained IoT devices over unreliable networks
Broker: Central server routing messages from publishers to all matching subscribers by topic pattern
Topic: Hierarchical string (e.g., home/bedroom/temperature) used to route messages to interested subscribers
QoS Level: Quality of Service 0/1/2 trading delivery guarantee for message overhead
Retained Message: Last message on a topic stored by broker for immediate delivery to new subscribers
Last Will and Testament: Pre-configured message published by broker when a client disconnects ungracefully
Persistent Session: Broker stores subscriptions and pending messages allowing clients to resume after disconnection

9.3 Prerequisites

Before diving into this chapter, you should be familiar with:

MQTT Publish-Subscribe Basics: Understanding MQTT publish-subscribe roles, topics, and basic message flow is essential before implementing practical applications
MQTT QoS Levels and MQTT Session Management: QoS 0/1/2 and clean versus persistent sessions help you choose appropriate configurations for different use cases
Programming fundamentals: Basic experience with Python helps work through the code examples

Cross-Hub Connections: Your MQTT Learning Toolkit

This chapter connects to multiple learning resources:

Interactive Practice:

Simulation resources - Try browser-based MQTT simulators such as an ESP32 publisher, subscriber, or QoS tester without hardware
Network Topology Explorer - Understand how MQTT fits into Star, Mesh, and Tree topologies

Video Tutorials:

Video tutorials - Watch step-by-step MQTT setup tutorials, broker configuration guides, and ESP32 programming demonstrations

Self-Assessment:

Inline checks - Test your MQTT implementation knowledge with scenario-based questions about QoS selection, security configuration, and debugging workflows

Knowledge Reinforcement:

Knowledge-gap review - Address common MQTT misconceptions such as clean-session behavior, QoS guarantees, and retained-message timing

Pro Tip: Start with browser simulators to experiment risk-free, then progress to real hardware using the code examples in this chapter. Use the inline checks to avoid common pitfalls like forgetting client.loop() or misunderstanding QoS levels.

9.4 Getting Started (For Beginners)

New to Building MQTT Applications? Start Here!

Time: ~20 min | Level: Beginner | Unit: P09.C26.U01

This section is designed for beginners. If you’re already familiar with setting up MQTT clients and brokers, feel free to skip to the interactive labs below.

Sensor Squad: Your First MQTT Project

“Let’s build something real!” said Max the Microcontroller excitedly. “Step one: install a broker. Mosquitto is free and runs on almost anything – even a Raspberry Pi.”

Sammy the Sensor followed along: “Step two: write a publisher. In Python, it’s just five lines of code – import the library, connect to the broker, publish a message to a topic, done! I published my first temperature reading in under a minute.”

“Step three: write a subscriber!” added Lila the LED. “Another five lines – connect, subscribe to the topic, and define a callback function that runs whenever a message arrives. I had my LED changing color based on Sammy’s readings in less than 10 minutes.”

Bella the Battery encouraged everyone: “Don’t overthink it – just start! Install Mosquitto, open two terminal windows, use one to publish and one to subscribe. When you see your first message appear on the subscriber side, you’ll get that ‘aha!’ moment. Then you can add QoS, retained messages, and all the fancy features later.”

9.4.1 What Will You Learn in This Chapter? (Simple Explanation)

In previous chapters, you learned what MQTT is (the theory). In this chapter, you’ll learn how to actually build MQTT applications (the practice).

Analogy: It’s like learning to drive a car.

Previous chapters = Driving theory (how gears work, traffic rules, car parts)
This chapter = Getting behind the wheel and actually driving!

9.4.2 The Three Essential MQTT Components

Every MQTT system needs three parts:

Component	Role	Simple Analogy	Your Implementation
MQTT Broker	Message post office	Central mailbox at your street	Mosquitto, HiveMQ, test.mosquitto.org
Publisher	Sends messages	Someone dropping letters in mailbox	ESP32 with temperature sensor
Subscriber	Receives messages	Someone checking mailbox for letters	Python dashboard on your laptop

Mobile Quick Guide: MQTT Components

MQTT Broker: message post office. Think of Mosquitto, HiveMQ, or test.mosquitto.org as the central mailbox that routes every message.
Publisher: sends messages. Your ESP32 with a temperature sensor plays this role and pushes readings to a topic.
Subscriber: receives messages. A Python dashboard on your laptop listens to the topic and displays the readings.

9.5 Quick Check: MQTT Components

Putting Numbers to It: Message Frequency vs Broker Load

For an MQTT broker handling $N$ devices each publishing at rate $r$ messages/sec to $T$ topics with $S$ subscribers per topic:

Broker input rate: $ R_{} = N r $

Broker output rate (fan-out to all subscribers): $ R_{} = N r S $

Example (1000 sensors, 0.1 msg/sec, 3 subscribers each):

Input: $R_{\text{in}} = 1000 \times 0.1 = 100\text{ msg/sec}$
Output: $R_{\text{out}} = 1000 \times 0.1 \times 3 = 300\text{ msg/sec}$
Fan-out factor: $\frac{R_{\text{out}}}{R_{\text{in}}} = S = 3\times$

Broker CPU load formula (simplified): $ R_{} + 0.005 N_{} $

For 1000 devices @ 100 msg/sec with 3× fan-out: $ + 0.005 = 3 + 5 = 8% $

Scaling insight: Doubling message rate doubles CPU load (linear in $R$), but doubling devices increases both $R$ and connection overhead. At 10,000 devices publishing 0.1 msg/sec: - Input: 1000 msg/sec - Output (3 subscribers): 3000 msg/sec - CPU: $0.01 \times 3000 + 0.005 \times 10,000 = 80\%$ (needs cluster)

Lesson: Broker load scales with (message rate × subscriber count). High fan-out (many subscribers per topic) requires more broker resources than high device count alone.

Simple flow:

ESP32 (Publisher)  →  Broker (test.mosquitto.org)  →  Your Laptop (Subscriber)
    "Temp: 24°C"           [Routes message]              "Display: 24°C"

Mobile Flow Summary

ESP32 publisher: reads the DHT22 sensor and sends a temperature update.
MQTT broker: receives that update on iot/sensors/temperature and routes it onward.
Laptop subscriber: listens to the same topic and displays the latest reading.

9.5.1 Your First MQTT Project: What You’ll Build

Goal: Create a complete IoT temperature monitoring system.

What happens:

ESP32 reads temperature from DHT22 sensor every 10 seconds
ESP32 publishes temperature to topic: iot/sensors/temperature
Broker (test.mosquitto.org) receives and stores the message
Your laptop subscribes to iot/sensors/temperature and displays readings
Bonus: Alert system triggers when temperature > 25C

Visual flow:

1. ESP32 Publisher	→	2. MQTT Broker	→	3. Laptop Subscriber
Reads the DHT22 sensor and sends a fresh temperature message every 10 seconds.		Accepts the publish on `iot/sensors/temperature` and routes it to subscribers.		Receives the routed update, shows the latest value, and can raise a high-temperature alert.

Mobile Visual Flow

1. ESP32 Publisher: reads the DHT22 sensor and publishes a temperature message every 10 seconds.
2. MQTT Broker: receives the message on the topic and routes it to every subscriber that asked for that data.
3. Laptop Subscriber: receives the routed message and displays the latest reading or raises an alert above 25C.

Alternative View: Lab Setup Components

Figure 9.1: MQTT lab setup showing hardware, network, and application layers

This diagram shows the three-layer lab architecture: hardware (ESP32 + sensor), network (Wi-Fi + MQTT broker), and application (monitoring tools).

9.5.2 Two Ways to Try MQTT (Choose Your Path)

Path 1: Browser Simulator (Easiest)

No hardware needed
Works immediately
Perfect for learning
Not real sensors

How: Scroll down to the “Interactive Simulator” section, open the Wokwi starter project, paste in the publisher sketch, and then click Play.

Path 2: Real Hardware (Best for learning)

Real sensors (actual temperature readings)
Full IoT experience
Can deploy anywhere
Requires ESP32 + DHT22 sensor

Hardware needed:

ESP32 DevKit-class board
DHT22 or similar temperature sensor
Breadboard and jumper wires
USB cable (usually included with ESP32)

These are low-cost reusable parts; use local availability, lab inventory, or simulator access to choose the most practical path.

9.5.3 Common Beginner Questions

Q: Do I need to install an MQTT broker on my computer?

A: No! You can use free public brokers like: - test.mosquitto.org (most popular) - broker.hivemq.com - mqtt.eclipseprojects.io

These are perfect for learning and testing. For production projects, you’ll want your own broker.

Q: What’s the difference between ESP32 code and Python code?

A: They do different jobs: - ESP32 code (C/C++): Runs on the microcontroller near your sensor (publisher) - Python code: Runs on your computer to display data (subscriber)

Both talk to the same MQTT broker!

Q: Can multiple devices subscribe to the same topic?

A: Yes! That’s the beauty of MQTT. You can have: - Your laptop showing temperature on a dashboard - Your phone app showing the same data - A database logger saving historical data - An alert system checking for high temperatures

All subscribed to iot/sensors/temperature simultaneously!

Q: What if my Wi-Fi disconnects?

A: MQTT is designed for unreliable networks: - The broker stores messages (if you use QoS > 0) - Your client will automatically reconnect - You won’t lose critical data

This is why MQTT is perfect for IoT (where Wi-Fi isn’t always reliable).

9.5.4 Self-Check: Are You Ready?

Question: You want to build a soil moisture monitor that sends alerts to your phone when plants need watering. Which component runs where?

Answer:

Publisher (ESP32 in the garden):

Reads soil moisture sensor
Publishes to topic: garden/moisture/plant1
Example message: {"moisture": 45, "status": "needs_water"}

Broker (in the cloud):

test.mosquitto.org or your own broker
Receives messages from ESP32
Routes to subscribers

Subscriber (on your phone):

Python script or mobile app
Subscribes to garden/moisture/plant1
Triggers push notification when moisture < 50%

Why this works:

ESP32 stays near the plant (wired to sensor)
Your phone can be anywhere with internet
Broker bridges them across the internet
Multiple family members can all get alerts (multiple subscribers)

Common Mistake: Using test.mosquitto.org in Production

The Mistake: A developer builds a prototype using the public MQTT broker test.mosquitto.org, gets excited about how well it works, and deploys a real sensor fleet without changing the broker.

Why This Is Dangerous:

Zero Authentication: Anyone can subscribe to garden/moisture/plant1 and see your data
Zero Encryption: WiFi sniffing reveals all messages in plain text
No Reliability Guarantee: Public brokers regularly restart, losing connections and retained messages
Topic Collisions: Another developer might use the same topic name, creating data mix-ups

Production consequences:

Competitor subscribes to your topics and reverse-engineers your IoT product design
Retained messages from someone else’s testing pollute your production topics
Broker outage during a critical greenhouse event causes missed alerts

The Fix: Spend 30 minutes setting up a private broker:

# Install Mosquitto on Ubuntu/Raspberry Pi
sudo apt install mosquitto mosquitto-clients

# Create user account
sudo mosquitto_passwd -c /etc/mosquitto/passwd myuser

# Configure /etc/mosquitto/mosquitto.conf
allow_anonymous false
password_file /etc/mosquitto/passwd
listener 8883
cafile /etc/ssl/certs/ca.crt
certfile /etc/ssl/certs/server.crt
keyfile /etc/ssl/private/server.key

# Restart broker
sudo systemctl restart mosquitto

Deployment comparison:

Public broker: free for learning, but provides no project-specific authentication, privacy, or uptime accountability
Private broker: inexpensive to self-host, but you own user accounts, TLS certificates, patching, and monitoring
Managed cloud IoT broker: adds managed TLS, device identity, topic policies, and operational monitoring

Bottom Line: Use public brokers ONLY for learning/prototyping. Production deployments need private brokers with authentication and TLS.

Ready to build? The sections below provide three complete implementations:

Interactive Simulators - No hardware, start immediately
Python Examples - Publisher/Subscriber code you can run on your laptop
Lab Exercise - Complete ESP32 project with real sensors

Let’s start with the browser simulator so you can see MQTT in action right now!

9.6 Interactive Simulator

9.6.1 Try MQTT in Your Browser

Open a starter ESP32 workspace in Wokwi and paste the MQTT publisher sketch from the next section so you can try the workflow in your browser.

Launch the Wokwi Starter

Open a new ESP32 project in Wokwi
Paste the MQTT publisher code from the next section into the Arduino sketch.
Run the simulator and watch the Serial Monitor for broker connection and publish messages.
When you’re ready for a fuller hardware project, continue to MQTT Hands-On Labs.

Using the Simulator

Open the starter ESP32 project in Wokwi
Paste the publisher sketch from the next section into the Arduino editor.
Click the green “Play” button to run the simulation
Watch the Serial Monitor for broker connection and publish messages
No hardware needed - runs entirely in your browser

9.7 Example Code: MQTT Publisher

Here’s a complete example using Python to publish temperature data:

# Python MQTT Publisher Example
import paho.mqtt.client as mqtt
import time
import random

# MQTT Broker settings
BROKER = "test.mosquitto.org"  # Public test broker
PORT = 1883
TOPIC = "iotclass/sensors/temperature"

# Create MQTT client (paho-mqtt 2.0+ API)
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="TempSensor_001")

# Connect to broker
print(f"Connecting to {BROKER}...")
client.connect(BROKER, PORT)

# Publish temperature readings
try:
    while True:
        # Simulate temperature sensor
        temp = round(20 + random.uniform(-5, 5), 2)

        # Publish message
        client.publish(TOPIC, f"{temp}")
        print(f"Published: {temp}C to {TOPIC}")

        time.sleep(5)  # Wait 5 seconds

except KeyboardInterrupt:
    print("Stopping publisher...")
    client.disconnect()

9.7.1 Publisher Code Check

9.8 Example Code: MQTT Subscriber

And here’s how to receive those messages:

# Python MQTT Subscriber Example
import paho.mqtt.client as mqtt

BROKER = "test.mosquitto.org"
PORT = 1883
TOPIC = "iotclass/sensors/temperature"

# Callback when connection is established (paho-mqtt 2.0+ signature)
def on_connect(client, userdata, flags, reason_code, properties):
    print(f"Connected with reason code {reason_code}")
    client.subscribe(TOPIC)
    print(f"Subscribed to {TOPIC}")

# Callback when message is received
def on_message(client, userdata, msg):
    temp = float(msg.payload.decode())
    print(f"Received: {temp}C from {msg.topic}")

    # Alert if temperature is too high
    if temp > 25:
        print("Warning: High temperature detected!")

# Create and configure client (paho-mqtt 2.0+ API)
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="Dashboard_001")
client.on_connect = on_connect
client.on_message = on_message

# Connect and start listening
client.connect(BROKER, PORT)
client.loop_forever()  # Block and listen for messages

9.9 Lab Exercise: Build a Temperature Monitoring System

Using the publisher and subscriber examples above, build the complete temperature monitoring system described in Your First MQTT Project. Follow these steps:

Set up broker: Use test.mosquitto.org for learning, or install Mosquitto locally
Run the publisher: Copy the publisher code above, run it in one terminal
Run the subscriber: Copy the subscriber code, run it in a second terminal
Verify end-to-end: Confirm published temperatures appear in the subscriber output
Add threshold alerts: Modify the subscriber to trigger warnings when temperature exceeds 25C (already included in the example code)

9.10 Label the Diagram

9.11 Order the Steps

9.12 Concept Relationships

MQTT Implementation connects to:

MQTT Publish-Subscribe Basics - Theoretical foundation for the publish-subscribe pattern implemented here
MQTT QoS Levels and MQTT Session Management - Delivery and session choices that drive implementation decisions
MQTT Topic Design and Wildcards - Topic hierarchy design for real projects
MQTT Production Operations - Broker operations and deployment concerns after the starter build works

Implementation workflow: Learn theory (MQTT basics) -> choose hardware or simulator -> implement basic pub/sub (this chapter) -> add production patterns (next chapter) -> deploy securely (labs chapter).

9.13 See Also

MQTT Python Patterns - paho-mqtt usage and production coding patterns
Lab: CoAP Implementation - Alternative lightweight protocol for comparison
MQTT Topic Design and Wildcards - Topic hierarchy design for real projects
MQTT Security - Securing your MQTT implementations

9.14 Match the Concepts

9.15 Deep-Dive Note: MQTT Connection Evidence Boundaries

Before a client can publish or subscribe, it has to open a broker session. The client sends CONNECT; the broker replies with CONNACK. That first exchange carries the client identifier, clean-start or clean-session intent, keep-alive interval, optional will message, credentials, and the broker’s acceptance or refusal result. A beginner demo should therefore prove more than “the script printed connected”: it should record the chosen client ID, accepted CONNACK, Session Present value, keep-alive interval, and one intentional refusal such as bad credentials or a duplicate client ID.

sequenceDiagram
    participant C as Client
    participant B as Broker
    C->>B: CONNECT (client id, keep-alive, clean start)
    B-->>C: CONNACK (accepted, session present?)
    Note over C,B: Session open
    C->>B: PINGREQ (keep-alive)
    B-->>C: PINGRESP

Treat the setup fields as operational evidence. A random client ID can make every reconnect look like a new device, so queued session state is never resumed. A duplicated client ID can make two gateways disconnect each other in a loop. A robust client subscribes again when Session Present = 0, but avoids duplicating subscriptions when the broker says the old session was resumed. It should also log refused CONNACK codes separately from network failures because bad username/password, unauthorized client ID, unsupported protocol version, and broker unavailable point to different fixes.

Keep-alive is the liveness contract for quiet clients. The client declares the interval in seconds; if it has no other packet to send, it sends PINGREQ and expects PINGRESP. Any MQTT control packet resets the timer, so a telemetry publisher that sends every 20 seconds does not need separate pings for a 60 second keep-alive. If the broker receives no control packet within 1.5 x keep-alive, it disconnects the client and publishes the will message if one was configured. Setting keep-alive to 0 disables that mechanism, which can leave half-dead connections lingering.

For the first broker smoke test, save one packet trace or broker log containing CONNECT, CONNACK, client ID, clean-start/session-present state, keep-alive value, one accepted publish/subscribe path, and one expected refusal. That record makes later reconnect, duplicate-ID, and offline-presence bugs diagnosable.

9.16 What’s Next

Chapter	Focus	Why Read It
MQTT Python Patterns and Security	Production-ready coding patterns, error handling, reconnection logic, and TLS authentication	Build on the basic publisher/subscriber code from this chapter with robust, real-world practices
MQTT Hands-On Labs	Complete ESP32 projects: temperature dashboard, home automation, and TLS security configuration	Apply the concepts from this chapter using real hardware with DHT22 and other sensors
MQTT QoS Levels and MQTT Session Management	QoS 0/1/2, clean vs persistent sessions, and Last Will behavior	Understand when to upgrade from the default QoS 0 used in this chapter’s examples
MQTT Publish-Subscribe Basics	Core publish-subscribe architecture, topic hierarchies, and protocol internals	Revisit the theoretical foundation if you want to deepen understanding of how the broker routes messages
MQTT Security	TLS/SSL setup, username/password authentication, and access control lists (ACLs)	The essential follow-up after learning to avoid public brokers in production deployments
Lab: CoAP Implementation	CoAP protocol as a REST-over-UDP alternative to MQTT	Compare MQTT’s broker-centric model against CoAP’s peer-to-peer request-response design

Mobile What’s Next Guide

MQTT Python Patterns and Security: production-ready coding patterns, reconnection logic, and TLS. Read this next when you want to harden the basic publisher/subscriber examples.
MQTT Hands-On Labs: complete ESP32 projects with dashboards, automation, and TLS. Read this when you’re ready to move from a simple starter example to full hardware builds.
MQTT QoS Levels and MQTT Session Management: QoS 0/1/2, clean sessions, persistent sessions, and Last Will behavior. Read this when you need to choose stronger delivery guarantees than the defaults shown here.
MQTT Publish-Subscribe Basics: topic hierarchies, publish-subscribe routing, and protocol internals. Revisit this if you want the deeper theory behind the implementation details.
MQTT Security: TLS/SSL, username/password authentication, and ACLs. Read this when you’re moving past public brokers and into real deployments.
Lab: CoAP Implementation: a REST-over-UDP alternative to MQTT. Read this to compare MQTT’s broker-centric model with CoAP’s request-response approach.

9.17 Key Takeaway

Start MQTT implementation by proving a minimal secure connection, publish, subscribe, and disconnect path. Then add topic structure, QoS, retained messages, and reconnection handling one behavior at a time.