Projects / Home MQTT broker on a Pi

Home MQTT broker on a Pi

Beginner1 hGuided buildReviewed

Build it step by step

0 of 7 done
  1. Pi ZeroSANDISRASPBERR

    Write the card

    Use Raspberry Pi Imager with SSH and Wi-Fi set.

  2. Pi Zero

    Log in

    Connect over SSH using the hostname you chose.

  3. Pi Zero

    Install

    Run the apt commands to install Mosquitto and its test tools.

  4. Pi Zero

    Add a user

    Run mosquitto_passwd and add the config file that turns off anonymous access.

  5. Pi Zero

    Restart and test

    Subscribe in one terminal and publish in another.

  6. Pi Zero

    Plan the topics

    Use home/room/sensor, for example home/lounge/temperature.

  7. Pi Zero

    Check it starts at boot

    Reboot and run the subscribe command again.

In short

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

FromToWhy
microSD card with Raspberry Pi OS LitePi microSD slotOperating system
Power supplyPi power portPower (the Zero uses a micro-USB supply; the Pi 4 and 5 use USB-C)
Pi Wi-Fi or EthernetYour home routerNetwork

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.

CheckExpected
Publish with the right passwordMessage appears in the subscriber
Publish without a passwordConnection refused
Reboot the PiBroker 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 →

Ask Lark AI

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.