ProcirelSetting Up a Mosquitto MQTT Broker on Raspberry Pi
A local Mosquitto broker makes your smart home self-reliant. No cloud dependency, sub-millisecond LAN latency, and full control of security. Setup is one install command plus a config file that most tutorials get wrong.
> At a glance: 7 minute guide · part 5 of 10 in the complete IoT and ESP32 guide track · includes a worked example and a quick-reference table.
## Install and first test
Here is the working theory in one pass. On Raspberry Pi OS: apt install mosquitto mosquitto-clients. Test locally with mosquitto_sub -t test/# in one terminal and mosquitto_pub -t test/hello -m hi in another. That pair of commands is your lifelong MQTT debugging kit.
| C | o | n | f | i | g | | l | i | n | e |
| — | — | — | — | — | — | — | — | — | — | — |
| P | u | r | p | o | s | e | | | | |
| listener 1883 | MQTT on LAN | | | | | | | | | |
| allow_anonymous false | Require credentials | | | | | | | | | |
| password_file /etc/mosquitto/passwd | User database | | | | | | | | | |
| listener 8883 + certfile | TLS-encrypted listener | | | | | | | | | |
| persistence true | Retained messages survive restarts | | | | | | | | | |
## Authentication and config
What this means at the bench: Modern Mosquitto denies anonymous access by default. Create a password file with mosquitto_passwd, allow_anonymous false, and define a listener. Restart the service and re-test with credentials an open broker on a LAN is a toy. An authenticated one is infrastructure.
## Integration and hardening
Point Home Assistant, ESPs and Node-RED at the Pi’s LAN address. Disable remote access unless you need it. If you do, TLS listener plus strong credentials, ideally behind a VPN. A ups-backed Pi makes the whole home’s automation resilient to internet outages.
## 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.
1. Install Mosquitto and client tools
2. Verify loopback pub/sub before any config
3. Add users with mosquitto_passwd and disable anonymous
4. Test one ESP32 publish against the broker before fleet rollout
### Worked example
After allow_anonymous false, an ESP that had published freely returns “connection refused. Not authorised” until its sketch gains the username and password exactly the failure you want to see in testing, not in production. Run the numbers yourself with the related calculator and the result should agree to within rounding.
> Practical note from the bench. Our standard Pi image ships with Mosquitto, authenticated users and a -v debug alias; new devices get a user, never a blanket policy.
## Field mistakes we see again and again
– Leaving allow_anonymous true on a reachable network
– Port-forwarding 1883 to the internet without TLS
– Forgetting persistence, losing retained state on restart
## Key takeaways
– Install and first test the foundation of this guide; revisit it if any measurement here surprises you.
– Authentication and config the foundation of this guide; revisit it if any measurement here surprises you.
– Integration and hardening the foundation of this guide; revisit it if any measurement here surprises you.
## Who this guide is for
Beginners get a single focused topic instead of a whole textbook chapter. It assumes the track’s earlier pages in the complete IoT and ESP32 guide path. Intermediate readers use it as a reference the table, the worked example and the mistake list answer the questions that come up mid-build. If you teach, the structure (theory, application, example, failure modes) maps cleanly onto a lab session.
## What you need before starting
Nothing exotic: the parts or tools named in the guide, a multimeter. A notebook for the numbers. Install Mosquitto and client tools before you begin the guide assumes it and keep the quick-reference table above within sight while you work through the steps.
### Quick reference card
| Aspect | Where to find it in this guide |
| — | — |
| Core theory | Install and first test |
| Application steps | How to apply this in your build |
| Worked numbers | Worked example |
| Failure modes | Field mistakes we see again and again |
## 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](/tutorial/iot-esp32-complete-guide) pillar page for the full map, or continue with [MQTT fundamentals](/tutorial/mqtt-protocol-explained) and [Home Assistant integration](/tutorial/home-assistant-mqtt-integration).
## Frequently asked questions
Can the broker run on the same Pi as Home Assistant?
Yes Mosquitto is lightweight; a single Pi handles a home-sized fleet comfortably.
How do I see all traffic while debugging?
mosquitto_sub -t ‘#’ -v with credentials the whole home at a glance.
Where do I go next?
Back to the [complete IoT and ESP32 guide](/tutorial/iot-esp32-complete-guide) pillar page 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](/tutorial/iot-esp32-complete-guide) maps every step in order.
– Next: [Biomedical Sensors: How Wearables Measure the Body](/tutorial/biomedical-sensor-guide)
– Next: [ESP32 WiFi That Never Dies: Reconnection Strategies](/tutorial/esp32-wifi-reconnection-strategies)
– Next: [Home Assistant + MQTT: A Local Smart Home That Lasts](/tutorial/home-assistant-mqtt-integration)
– Work the numbers: [battery life estimator](/tools/battery-life) · [LM317 designer](/tools/lm317-regulator) · [wire gauge checker](/tools/wire-gauge-awg)
## Working method notes
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.
## What the bench taught us
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.
## A parting thought for builders
A note on radio current, which defines this track: transmit bursts draw in spikes, not averages. Scope the supply or log RSSI before concluding the protocol is at fault.
Working through Install and first testand Authentication and config with that habit in mind takes minutes, and it is the difference between reading about this topic and owning it.