>_ ctrlaltbrian
raspberry-pi intermediate 30 min

Raspberry Pi: install and configure Mosquitto MQTT broker

Set up a local MQTT broker on a Raspberry Pi so your ESP32s and other devices can publish and subscribe without depending on a cloud.

Code available for: Python
Published Aug 2, 2026

A local MQTT broker is the central nervous system of most home automation projects. Every sensor publishes to it. Every automation subscribes from it. Every dashboard reads from it. The broker is the part you want running on hardware you control, not on a cloud that might disappear.

This tutorial installs Mosquitto on a Raspberry Pi and configures it for a home network.

What you need

  • Raspberry Pi (any model) running Raspberry Pi OS
  • Network access to the Pi (you already know how to SSH in)

Install Mosquitto

sudo apt update
sudo apt install -y mosquitto mosquitto-clients

That’s it. The default configuration starts the broker on port 1883 with no authentication.

Verify it works

On the Pi itself:

mosquitto_sub -h localhost -t "test/#" -v &
mosquitto_pub -h localhost -t "test/hello" -m "world"

You should see test/hello world printed in the subscriber.

Or from your laptop:

mosquitto_sub -h pi-pihole.local -t "test/#" -v

Then on the Pi:

mosquitto_pub -h localhost -t "test/hello" -m "world"

The laptop should see the message. If not, check the firewall on the Pi:

sudo ufw allow 1883/tcp

(Or, if you use iptables, allow port 1883 there.)

Configuring for a home network

The default config lets any device on the network publish or subscribe to any topic. That is fine for a closed home network, but I add two things:

  1. A username and password (so random devices on the network cannot impersonate your sensors).
  2. Allow anonymous read-only access (so a dashboard can subscribe without a password, but only the broker admin can publish).

Edit /etc/mosquitto/mosquitto.conf:

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

# Optional: persistent sessions (broker remembers subscriptions across restarts)
persistence true
persistence_location /var/lib/mosquitto/

# Optional: log to file
log_dest file /var/log/mosquitto/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information

Create the password file:

sudo mosquitto_passwd -c /etc/mosquitto/passwd brian

(Enter a password when prompted.)

Restart:

sudo systemctl restart mosquitto

Test:

mosquitto_pub -h localhost -u brian -P your-password -t "test/hello" -m "world"
mosquitto_sub -h localhost -u brian -P your-password -t "test/#" -v

Letting devices connect without passwords (read-only)

If you have devices that only need to subscribe (e.g. a dashboard), you can allow anonymous read-only access. The trick is Mosquitto’s ACL system.

Create /etc/mosquitto/acl:

# Default: only authenticated users
user brian
topic readwrite #

# Anonymous: read-only
user anonymous
topic read #

Update the mosquitto config:

listener 1883
allow_anonymous true
acl_file /etc/mosquitto/acl
password_file /etc/mosquitto/passwd

Restart:

sudo systemctl restart mosquitto

Now an anonymous subscriber (no username, no password) can read but cannot publish. The authenticated user brian can publish and subscribe.

For ESP32 clients, set the username and password in the PubSubClient library:

client.connect("esp32-publisher", "brian", "your-password");

Securing with TLS

If you want MQTT over TLS (so devices on the open internet can connect without sending the password in cleartext), you need a domain name and a certificate (e.g. from Let’s Encrypt). The configuration is more involved; I cover it in the book Production MQTT.

For a home network, plain MQTT on port 1883 is fine.

Testing from Python

import paho.mqtt.client as mqtt
import time

def on_connect(client, userdata, flags, rc):
    print("Connected with result code " + str(rc))
    client.subscribe("ctrlaltbrian/#")

def on_message(client, userdata, msg):
    print(msg.topic + " " + str(msg.payload.decode()))

client = mqtt.Client()
client.username_pw_set("brian", "your-password")
client.on_connect = on_connect
client.on_message = on_message

client.connect("localhost", 1883, 60)
client.loop_start()

while True:
    client.publish("ctrlaltbrian/test", "hello from python")
    time.sleep(5)

Install paho-mqtt:

pip3 install --break-system-packages paho-mqtt

Run it. You should see the messages coming back to yourself.

Web-based monitoring

If you want a browser-based view of what is going through the broker:

sudo apt install -y mosquitto mosquitto-clients
sudo apt install -y mqtt-explorer   # no, this is a desktop app

For a server-side option, install MQTT Explorer via snap, or use a small web dashboard. The book Home Automation with Raspberry Pi uses Node-RED with the MQTT nodes for this.

Using Mosquitto with Home Assistant

If you are running Home Assistant, configure the MQTT integration to point at the local broker. HA will subscribe to homeassistant/# and you can configure devices to publish sensor data with the HA discovery prefix.

The HA version is in the book Home Automation with Raspberry Pi.

When the broker silently drops messages

  • Topic ACL: if the topic is not allowed for the user, the broker silently drops it. Check /etc/mosquitto/acl.
  • QoS 0: at most once. If the subscriber is offline, it misses the message. Use QoS 1 or 2 if you need guaranteed delivery.
  • Retained flag: new subscribers do not see the last message by default. Set the retain flag on publishes you want new subscribers to see immediately.

What to build next

  • A Node-RED dashboard that subscribes to your sensors.
  • Home Assistant with the MQTT integration.
  • A Telegram bot that sends you a message when a sensor trips.

The Node-RED dashboard is in the book Home Automation with Raspberry Pi. The Telegram bot is one of the next tutorials on this site.