pi-hub-config/README.md

Mosquitto MQTT Broker Setup for Pi Zero 2 W Hub

Overview

This repository contains the complete setup for a Mosquitto MQTT broker running on a Raspberry Pi Zero 2 W, serving as a central hub for IoT devices.

Hardware Target

• Device: Raspberry Pi Zero 2 W
• IP Address: 10.60.1.101
• OS: Raspberry Pi OS Lite
• User: overseer

Installation

Quick Install (on Pi Zero 2 W)

ssh overseer@10.60.1.101
cd ~
curl -O https://code.cubecraftcreations.com/cubecraft/pi-hub-config/raw/branch/dev/install-mosquitto.sh
chmod +x install-mosquitto.sh
sudo ./install-mosquitto.sh

Manual Installation

1. Install packages: sudo apt-get install mosquitto mosquitto-clients python3-paho-mqtt
2. Create directories: /etc/mosquitto/conf.d, /etc/mosquitto/acl, /var/lib/mosquitto/data
3. Copy configuration files to /etc/mosquitto/
4. Set up users with mosquitto_passwd

Configuration

Main Configuration (/etc/mosquitto/conf.d/mosquitto.conf)

• Persistence: Enabled at /var/lib/mosquitto/data/
• Port: 1883 (standard MQTT)
• Authentication: Enabled (anonymous access disabled)
• ACL: Configured in /etc/mosquitto/acl/acl.conf
• Logging: Full logging to /var/log/mosquitto/mosquitto.log

Access Control List

See /etc/mosquitto/acl/acl.conf for full topic patterns.

User	Read Topics	Write Topics
hub	/ (all)	hub/+/set
sensor	sensors/+/data	devices/+/commands
mobile	home/+/status	home/+/control
admin	# (all)	# (all)

Security

• Password file: /etc/mosquitto/passwd (mode 600)
• No anonymous access
• ACL-enforced topic restrictions
• Systemd service with security hardening (NoNewPrivileges, ProtectSystem=strict)

systemd Service

Auto-start Configuration

# Copy service file to systemd
sudo cp mosquitto.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mosquitto
sudo systemctl start mosquitto

Service Management

sudo systemctl status mosquitto
sudo systemctl restart mosquitto
sudo systemctl stop mosquitto

Usage

Testing Installation

# Subscribe to test topic
mosquitto_sub -h localhost -t test -u admin -P <password>

# Publish test message
mosquitto_pub -h localhost -t test -m "Hello Mosquitto" -u admin -P <password>

MQTT Client Examples

Python (paho-mqtt)

import paho.mqtt.client as mqtt

client = mqtt.Client("client-id")
client.username_pw_set("admin", password="your-password")
client.connect("10.60.1.101", 1883, 60)
client.subscribe("test")
client.loop_start()

Home Assistant

mqtt:
  broker: 10.60.1.101
  port: 1883
  username: admin
  password: "your-password"

Maintenance

Adding Users

sudo mosquitto_passwd -c /etc/mosquitto/passwd <username>

Changing Password

sudo mosquitto_passwd /etc/mosquitto/passwd <username>

Restarting Service

sudo systemctl restart mosquitto

Viewing Logs

sudo journalctl -u mosquitto -f
# or
tail -f /var/log/mosquitto/mosquitto.log

Troubleshooting

Service won't start

• Check configuration syntax: mosquitto -c /etc/mosquitto/conf.d/mosquitto.conf -t
• Verify file permissions on /etc/mosquitto/
• Check logs: journalctl -u mosquitto

Authentication failures

• Verify password file exists: ls -la /etc/mosquitto/passwd
• Check password file permissions: should be 600
• Test with: mosquitto_sub -h localhost -t test -u <user> -P <pass> -v

Connection refused

• Ensure service is running: systemctl status mosquitto
• Verify no firewall blocking port 1883
• Check if another MQTT broker is running

Deployment Checklist

• Install dependencies: apt-get install mosquitto mosquitto-clients python3-paho-mqtt
• Run install script: ./install-mosquitto.sh
• Create admin user password
• Copy systemd service file
• Enable and start service
• Test with mosquitto_pub/sub
• Configure firewall (allow port 1883)
• Update DNS/DHCP with static IP for Pi Zero 2 W
• Document in network inventory

Related Projects

• CUB-231: Mosquitto MQTT broker setup on Pi Zero 2 W hub
• Pi hub serves as central MQTT broker for IoT devices
• Integrates with Home Assistant at 10.60.1.80

License

MIT License - See LICENSE file for details.