Build it step by step
0 of 7 doneWrite the card
Use Raspberry Pi Imager with SSH and Wi-Fi set.
Log in
Connect over SSH using the hostname you chose.
Install
Run the apt commands to install Mosquitto and its test tools.
Add a user
Run mosquitto_passwd and add the config file that turns off anonymous access.
Restart and test
Subscribe in one terminal and publish in another.
Plan the topics
Use home/room/sensor, for example home/lounge/temperature.
Check it starts at boot
Reboot and run the subscribe command again.
How do you build a home MQTT broker on a Pi?
A Pi runs the Mosquitto broker with a password, so every sensor in the house can publish and every screen can subscribe. You need Raspberry Pi Zero 2 W, SanDisk microSD card 32 GB (A1, Class 10) and Raspberry Pi 15 W USB-C power supply. It takes 7 steps and about 60 minutes.
- Level
- Beginner
- Time
- About 60 min
- Parts
- 3
Parts list
Tick what you already own. It saves to My Garage, so “Build with what I have” knows.
Wiring
| From | To | Why |
|---|---|---|
| microSD card with Raspberry Pi OS Lite | Pi microSD slot | Operating system |
| Power supply | Pi power port | Power (the Zero uses a micro-USB supply; the Pi 4 and 5 use USB-C) |
| Pi Wi-Fi or Ethernet | Your home router | Network |
Code
Use Raspberry Pi Imager to write Raspberry Pi OS Lite and, in its settings, set a hostname, a user, your Wi-Fi and turn on SSH. The commands run on the Pi. Plain MQTT on port 1883 is for your home network only: do not open the port on your router to the internet. For access from outside use a VPN, or add TLS before exposing anything. Never reuse your Wi-Fi password for MQTT users, and keep the password out of any code you share.
# Run these on the Pi over SSH. Use your own names and passwords; the ones below are placeholders. sudo apt update sudo apt install -y mosquitto mosquitto-clients # Create a user (you will be asked to type a password) sudo mosquitto_passwd -c /etc/mosquitto/passwd home # Save this as /etc/mosquitto/conf.d/local.conf (sudo nano /etc/mosquitto/conf.d/local.conf) # listener 1883 # allow_anonymous false # password_file /etc/mosquitto/passwd sudo systemctl enable mosquitto sudo systemctl restart mosquitto # Test in two terminals (replace YOUR_PASSWORD and the Pi's address) mosquitto_sub -h localhost -u home -P YOUR_PASSWORD -t 'home/#' -v mosquitto_pub -h localhost -u home -P YOUR_PASSWORD -t 'home/lounge/temperature' -m '27.5'
Test checklist
What you should see at each check. If a reading is far off, stop and use the troubleshooting list.
| Check | Expected |
|---|---|
| Publish with the right password | Message appears in the subscriber |
| Publish without a password | Connection refused |
| Reboot the Pi | Broker starts by itself |
| Subscribe to home/# | Every room's messages appear |
If it does not work
Connection refused
Check allow_anonymous false, the password file path and that you supplied -u and -P.
Service fails to start
Run sudo journalctl -u mosquitto for the error, often a typo in the config file.
Cannot reach it from another device
Check the Pi's IP address and that listener 1883 is set.
Password file errors
Make sure the file is readable by mosquitto and rerun mosquitto_passwd.
Still stuck? Find the fault step by step with your multimeter →
Common questions
What parts do I need for the home MQTT broker on a Pi?
Raspberry Pi Zero 2 W, SanDisk microSD card 32 GB (A1, Class 10) and Raspberry Pi 15 W USB-C power supply.
How long does the home MQTT broker on a Pi take to build?
About 60 minutes for a beginner maker, in 7 steps.
How do I know the home MQTT broker on a Pi works?
Publish with the right password: Message appears in the subscriber. Publish without a password: Connection refused. Reboot the Pi: Broker starts by itself.
Connection refused: what should I check?
Check allow_anonymous false, the password file path and that you supplied -u and -P.
Service fails to start: what should I check?
Run sudo journalctl -u mosquitto for the error, often a typo in the config file.
Cannot reach it from another device: what should I check?
Check the Pi's IP address and that listener 1883 is set.
Password file errors: what should I check?
Make sure the file is readable by mosquitto and rerun mosquitto_passwd.
