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)
```bash
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
```bash
# 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
```bash
sudo systemctl status mosquitto
sudo systemctl restart mosquitto
sudo systemctl stop mosquitto
```

## Usage

### Testing Installation
```bash
# 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)
```python
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
```yaml
mqtt:
  broker: 10.60.1.101
  port: 1883
  username: admin
  password: "your-password"
```

## Maintenance

### Adding Users
```bash
sudo mosquitto_passwd -c /etc/mosquitto/passwd <username>
```

### Changing Password
```bash
sudo mosquitto_passwd /etc/mosquitto/passwd <username>
```

### Restarting Service
```bash
sudo systemctl restart mosquitto
```

### Viewing Logs
```bash
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.