Set Up Mosquitto MQTT on Raspberry Pi: Local IoT Message Hub

The Internet of Things (IoT) is built on rapid, lightweight communication between smart sensors, microcontrollers, and automation engines. While standard HTTP web requests are great for loading websites, their heavy protocol overhead, repeated TCP connection handshakes, and polling requirements make them poorly suited for battery-powered sensors and real-time smart home controls.

MQTT (Message Queuing Telemetry Transport) is the industry-standard, lightweight publish/subscribe messaging protocol designed specifically for IoT. Instead of sensors communicating with each other directly, all devices connect to a central MQTT Broker. Sensors publish short telemetry messages to named topics (like home/livingroom/temperature), and interested subscribers (like Home Assistant or a dashboard) receive updates instantly.

Eclipse Mosquitto is the most popular open-source MQTT broker in the world. It is blazing fast, rock solid, and runs on a Raspberry Pi using less than 10 MB of RAM!

This guide covers installing Mosquitto on Raspberry Pi OS, hardening security by disabling anonymous access and creating password-protected user accounts, designing a clean topic hierarchy, testing with command-line pub/sub utilities, and monitoring your broker with Open Pi.

Hardware planning and prerequisites

• Supported Boards: Mosquitto is exceptionally efficient. It runs flawlessly on any Raspberry Pi Zero, 2, 3, 4, or 5 with as little as 256 MB of RAM.
• Operating System: A clean installation of Raspberry Pi OS (32-bit or 64-bit).
• Network Interface: For high-reliability home automation, connect your Raspberry Pi via wired Ethernet. Even minor Wi-Fi drops can cause battery-operated door sensors to miss state change notifications.
• Static IP: Assign a static IP address or DHCP reservation to your Raspberry Pi so microcontrollers (ESP8266, ESP32, Arduino) and smart plugs always know where to find the broker.

Install Mosquitto Broker and Client Tools

Install Mosquitto and its accompanying command-line utilities from the official package repositories:

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

By default, Mosquitto installs as a systemd service. Check its active status:

sudo systemctl status mosquitto

Security hardening: Authentication and access control

Recent versions of Mosquitto (version 2.0 and later) implement strict default security: they only bind to localhost and refuse remote connections unless explicitly configured with listeners and authentication.

Step 1: Create an encrypted password file

Never run an open, unauthenticated MQTT broker on your local network. Rogue smart bulbs or infected IoT devices could sniff messages or inject false commands.

Create a secure password file using mosquitto_passwd. In this example, we create a user named homeassistant:

sudo mosquitto_passwd -c /etc/mosquitto/passwd homeassistant

Enter a strong passphrase when prompted. To add additional users (for example, for an ESP32 sensor or Zigbee2MQTT), run the same command without the -c flag (which creates a new file):

sudo mosquitto_passwd /etc/mosquitto/passwd esp32_sensor

Step 2: Configure Mosquitto listeners

Create a custom configuration file in /etc/mosquitto/conf.d/:

sudo nano /etc/mosquitto/conf.d/default.conf

Paste the following production configuration:

# Port and network listener
listener 1883
protocol mqtt

# Security settings
allow_anonymous false
password_file /etc/mosquitto/passwd

# Persistence settings
persistence true
persistence_location /var/lib/mosquitto/

• listener 1883: Listens for incoming MQTT connections on standard port 1883 across all network interfaces.
• allow_anonymous false: Rejects any connection attempt that lacks valid username and password credentials.
• persistence true: Saves retained messages and QoS state to disk across broker reboots.

Restart Mosquitto to apply the security rules:

sudo systemctl restart mosquitto

Understanding Topic Hierarchy and Namespace Design

Topics in MQTT are forward-slash-delimited strings used to route messages. Designing a logical topic namespace keeps your home automation organized as your device collection expands.

Recommended Hierarchy Pattern:

[location]/[room]/[device_type]/[property]

Examples: - home/kitchen/sensor/temperature -> payload: 21.5 - home/kitchen/sensor/humidity -> payload: 45 - home/livingroom/light/state -> payload: ON - home/garage/door/contact -> payload: CLOSED

Topic Wildcards:

Subscribers can listen to multiple topics using wildcards: - Single-level wildcard (+): home/+/sensor/temperature receives temperature updates from every room. - Multi-level wildcard (#): home/kitchen/# receives all events, sensors, and commands under the kitchen namespace.

Testing Publish and Subscribe with the CLI

Use mosquitto_sub and mosquitto_pub to verify your broker functionality.

Terminal 1: Subscribe to messages

Open a terminal and listen to all topics under the home/ hierarchy:

mosquitto_sub -h localhost -p 1883 -u "homeassistant" -P "your_password" -t "home/#" -v

Terminal 2: Publish a test message

Open a second terminal window (or connect from another computer) and publish a test telemetry payload:

mosquitto_pub -h localhost -p 1883 -u "homeassistant" -P "your_password" -t "home/livingroom/temperature" -m "22.4"

In Terminal 1, you will instantly see the message arrive:

home/livingroom/temperature 22.4

Quality of Service (QoS) and Retained Messages

MQTT provides built-in delivery guarantees: - QoS 0 (At most once): Best-effort delivery; messages are sent without acknowledgment. Ideal for frequent temperature readings where losing a single reading does not matter. - QoS 1 (At least once): Messages are acknowledged by the broker and retried if necessary. Ideal for state changes (e.g., door opened). - Retained Messages (-r): When publishing with the retain flag, the broker stores the last message on that topic. When a new device boots up and subscribes, it immediately receives the current state rather than waiting for the next update cycle.

Monitor Mosquitto with Open Pi

Because Mosquitto coordinates device states across your home, ensuring the broker is always active and responsive is critical.

With Open Pi on your iOS or Android device: - Process Verification: Confirm that the mosquitto system daemon is running in the active process table. - Network Port Status: Check that port 1883 is actively listening for incoming client connections. - Resource Footprint: Verify that memory and CPU usage remain low.

Troubleshooting Mosquitto

• Connection Refused: not authorised: The username or password provided by the client does not match /etc/mosquitto/passwd. Re-check your credentials with mosquitto_passwd.
• Clients on Wi-Fi Cannot Connect: Ensure you created /etc/mosquitto/conf.d/default.conf with listener 1883. Without a listener directive, Mosquitto 2.0+ binds only to loopback (127.0.0.1).
• Messages Dropping Under High Load: If handling hundreds of rapid messages, verify system open file descriptor limits with ulimit -n.

Sources and further reading

• Eclipse Mosquitto: Official Documentation and Manual
• MQTT.org: Standard Protocol Specification
• Home Assistant: MQTT Integration Setup and Discovery

Monitor your Raspberry Pi from your phone

Check real-time CPU, RAM, temperature, and service health for your smart home projects with Open Pi for iOS and Android. Local-first, private, and no cloud account required.

Explore Open Pi ↗App StoreGoogle Play