MQTT is a tiny publish/subscribe protocol: devices publish messages to named topics. Anyone subscribed to those topics receives them. Neither side needs to know the other exists which is exactly why it scales from one sensor to factory floors.
At a glance: 8 minute guide · part 4 of 10 in the complete IoT and ESP32 guide track · includes a worked example and a quick-reference table.
Topics and the broker
A broker (Mosquitto, HiveQ…) routes everything. Topics are hierarchical strings home/livingroom/temperature and subscriptions accept wildcards: home/+/temperature or home/#. One broker, hundreds of quiet clients.
| C | o | n | c | e | p | t | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| W | h | a | t | i | t | d | o | e | s | ||
| T | y | p | i | c | a | l | u | s | e | ||
| Topic | Named channel | home/kitchen/temp | |||||||||
| + / # wildcards | Subscribe patterns | + filters one level | |||||||||
| QoS 1 | At-least-once delivery | Most telemetry | |||||||||
| Retained | Last value kept for new subscribers | Switch/desired state | |||||||||
| LWT | Announces unexpected death | Device offline alerts |
QoS levels and retained messages
QoS 0 sends and forgets; QoS 1 guarantees at-least-once (duplicates possible). QoS 2 guarantees exactly-once with more overhead. Retained messages let a new subscriber instantly learn the last known value perfect for state topics like switch positions.
Keepalive, LWT and security
Keepalive pings detect silently dead clients; the Last Will message publishes on ungraceful drops. Use username/password at minimum, TLS where feasible. Never expose a broker to the raw internet VPN or an authenticated bridge is the sane pattern.
How to apply this in your build
Work through the sequence below each step assumes the previous one passed. For numbers that need calculating, the linked tools at the end of this guide do the arithmetic instantly.
- Design a topic tree before wiring any devices
- Publish telemetry to state topics, subscribe to command topics
- Enable retained messages for state, not for streams
- Set keepalive and a Last Will for every device
Worked example
A thermostat publishes home/bedroom/setpoint (retained) and home/bedroom/temperature (QoS 0, every 30 s). Home Assistant restarts and instantly knows the setpoint without asking. Run the numbers yourself with the related calculator and the result should agree to within rounding.
Practical note from the bench. Topic naming pays compound interest: location/device/measurement reads itself. We document the tree in the project README before flashing anything.
Common mistakes to avoid
- Publishing high-rate streams as retained brokers bloat
- Chatty QoS 2 on battery devices handshakes cost milliamp-hours
- Open broker port forwarded to the internet "temporarily"
Key takeaways
- Topics and the broker the foundation of this guide; revisit it if any measurement here surprises you.
- QoS levels and retained messages the foundation of this guide; revisit it if any measurement here surprises you.
- Keepalive, LWT and security the foundation of this guide; revisit it if any measurement here surprises you.
Prerequisites and preparation
Before starting. Design a topic tree before wiring any devices and publish telemetry to state topics, subscribe to command topics. Keep a calculator to hand every number in the worked example is reproducible. Total time including the bench steps: about 6-8 minutes.
Who benefits most
Hobbyists meeting this topic for the first time, students who want the version with real numbers instead of abstract symbols. Returning engineers refreshing a corner of the craft. The mistake list alone justifies the visit every entry in it was learned the expensive way.
Quick reference card
| Aspect | Where to find it in this guide |
|---|---|
| Core theory | Topics and the broker |
| Application steps | How to apply this in your build |
| Worked numbers | Worked example |
| Failure modes | Common mistakes to avoid |
How this fits the complete IoT and ESP32 guide track
This guide is one stop in the structured learning path. Start from the complete IoT and ESP32 guide complete guide for the full map, or continue with Mosquitto broker setup and WiFi reconnection patterns.
Frequently asked questions
MQTT or HTTP for my project? Telemetry and commands between machines → MQTT. Serving web pages or one-off cloud calls → HTTP.
Does MQTT need the internet? No a local broker on a Raspberry Pi runs your smart home entirely offline.
Where do I go next? Back to the complete IoT and ESP32 guide complete guide it indexes every guide in this track and updates as new ones are published.
Continue this track
- Building a foundation? The iot, sensors & esp32 complete guide maps every step in order.
- Next: Gyroscope Sensor Explained: Working, Arduino & Uses
- Next: 5G Architecture Explained: What Actually Changed
- Next: Arduino to ESP32 Microcontroller Guide for Engineers
- Work the numbers: battery life estimator · LM317 designer · wire gauge checker
Measurement discipline
Keep a lab notebook entry for every build in this track. The measured values, the deviations from the guide and the reason for each. Six months from now, those notes are worth more than any tutorial. They describe your bench and your components rather than a general case.
When a result here disagrees with your expectation, write down both numbers before changing anything. The gap between predicted and measured is where the real engineering lives. It is usually a tolerance, a parasitic or an assumption that was never checked.
Formulas and checks from this guide
Verification checklist for this track: watch RSSI before blaming code, measure supply current during radio bursts. Confirm MQTT topics against the broker log. Wireless bugs are usually power or signal problems wearing a software disguise.
Bookmark this page against your next build in the track. The checklist above is the same one used across 23 guides in this series.
Hard-won notes
Measure current during transmit bursts. Sags under load are power problems, no firmware fixes those.
Location, then device, then measurement. Document the tree before flashing the first device.
How to revisit this guide
Second readings work best with a purpose. Pick one section from Topics and the broker,QoS levels and retained messages,Keepalive, LWT and security and rebuild only that part at the bench, predicting each value before measuring. Prediction errors mark exactly which concept needs the next pass, and the linked iot calculators resolve any arithmetic doubt in seconds. Keep the marked sections in your notebook: after a month of builds, that list becomes your personal IoT syllabus.
Extended Application Notes
This section expands the practical application of mqtt explained: the protocol behind practical iot beyond the worked example, into the situations builders actually meet. Component substitution: when the exact specified part is unavailable, the substitution logic follows the governing parameter of this design, not the nominal value, and the verification step after any substitution is to re-measure the one quantity this guide identified as critical. Batch variation: components vary, and the design margins recommended in the sections above absorb that variation; if a second build behaves differently, the difference itself is diagnostic and points to the tolerance that dominated. Environmental limits: temperature, supply variation and ageing each push a real circuit away from its bench behaviour, and the recommended practice is to test the extremes deliberately rather than discover them in the field. These notes exist because the bench taught them, repeatedly, and each one was once a real troubleshooting session that ended in understanding.
Failure Analysis in Depth
The mistakes section above lists the traps; this section explains why each trap exists and how to recognize it early. Publishing high-rate streams as retained brokers bloat Chatty QoS 2 on battery devices handshakes cost milliamp-hours Open broker port forwarded to the internet "temporarily". Each of these failures has a signature that appears in measurement before it appears in smoke: a reading that drifts, a waveform that differs from the prediction, a temperature that climbs faster than the calculation. The discipline this guide teaches is to measure at the first sign, not at the last, and the sections above give the specific instrument and setting for each check. Failure analysis is not pessimism; it is the fastest curriculum in electronics, because a fault understood once is a fault prevented forever.
Pre-Build Checklist
Before powering any build of this design, run the list: every component value verified against the specification above, the critical measurement points identified and accessible, the instrument modes and ranges chosen in advance, the expected values written down beside the bench, and the power source current-limited for first application. The checklist takes two minutes and replaces the most expensive class of beginner error, which is not ignorance but confidence outrunning verification. Builders who adopt the checklist across the guides in this track report first-apply success rates that feel like cheating, but it is not cheating, it is engineering.
What Comes Next
Having worked through this guide, the natural next steps are the adjacent guides in the track index above, each of which assumes exactly the vocabulary this page built. The calculators linked in the tools section verify every number in seconds, and the complete guide at the head of this track maps the entire curriculum. Read once, build once, measure always: that is the method this site teaches and the method every section above followed before publication.
Theory in Practice, Extended
The theory section of mqtt explained: the protocol behind practical iot deserves one more pass with the bench in mind, because knowing a relationship and applying it under constraint are different skills. In application, the relationship is never isolated: it interacts with tolerances, with temperature, with the behaviour of adjacent stages, and with the measurement itself. The extended practice is to take the governing formula from the sections above and stress it, deliberately. Push the input to the edge of its specified range and watch the output follow the prediction, then push past it and watch the prediction break, because the edge of the specification is exactly where the formula stops being the whole story. That boundary, found on the bench rather than in the datasheet, is the real knowledge this guide offers beyond the mathematics.
Component Sourcing and Substitution Notes
Real builds meet real supply chains, and this section addresses the practical reality. The specified components in this guide were chosen for the reasons stated in the design sections, but equivalent parts from reputable manufacturers almost always serve, provided the governing parameters match, not merely the nominal ones. The substitution checklist: match the parameter this guide identified as critical, verify the package and pinout against the physical part before layout, check the datasheet revision for silent changes, and re-run the verification measurement after installation. Avoid unbranded surplus and marketplace components for anything this guide treats as safety-relevant; the failure mode of a counterfeit is not degradation, it is unpredictability, and unpredictability defeats every other design decision in the chain.
Instrumentation for This Design
Every measurement recommended in this guide maps to a specific instrument configuration, and this section consolidates them. Voltage checks: DC range selected before probing, leads verified against a known source, meter burden considered when the node is high impedance. Current checks: circuit broken at the defined point, meter inserted with the correct range and fuse status confirmed first. Waveform checks: probe compensated against the reference before any amplitude claim, ground lead kept short, bandwidth sufficient for the edge rather than the repetition rate. The instrumentation discipline matters more than the instrument class, and a modest instrument used correctly outperforms an expensive one used casually, a claim this site demonstrates throughout its measurement guides.
Documentation Template for This Build
Close the loop the way professional builds do: record the design values from this guide, the as-built values including every substitution, the measured results beside the predicted ones, and the deviation notes that explain every gap. The template is short, a single page, and it converts a successful build into a reference that survives component changes, firmware updates and the passage of months. Every guide on this site was built and documented exactly this way before publication, and the discipline is offered here as part of the curriculum rather than an afterthought. A build that is documented is twice built, once in copper and once in confidence.
Last updated 23 August 2026