Skip to content

Pi Monitoring

Jump to bottom
Ethan Knox edited this page May 8, 2026 · 1 revision

Per-host health metrics (CPU, memory, temperature, disk, uptime, network throughput) reported from each onboard Raspberry Pi to the Home Assistant MQTT broker. Discovery messages auto-create one HA device per host, so adding a new Pi to the fleet requires no HA-side configuration.

Tooling

rpi-mqtt-monitor (hjelev). The script probes the host once per invocation, publishes one MQTT message per metric (with HA discovery payloads), and exits.

Hosts running it

  • ✅ boatflix.local (Jellyfin / NAS Pi) — reference install, the pattern below was copied from here
  • ✅ ironclaw.local (agent Pi)
  • ❓ Other LAN Pis (salonviewscreen, openplotter) — add them using the same recipe

The monitor publishes to the broker on homeassistant.local:1883; HA's MQTT integration auto-discovers each device under homeassistant/<component>/rpi-MQTT-monitor/<hostname>/....

Install layout (per host)

The monitor is installed system-wide under /opt. The unusual nested path mirrors the upstream install.sh — keep it as-is so the cron line is identical across hosts.

/opt/rpi-mqtt-monitor/                       # outer dir (clone parent)
└── rpi-mqtt-monitor/                        # actual repo
    ├── src/
    │   ├── rpi-cpu2mqtt.py                  # entry point
    │   └── config.py                        # edited with broker creds (NOT in git)
    ├── rpi_mon_env/                         # python venv (created by install.sh)
    ├── requirements.txt                     # paho-mqtt==1.6.1, requests, psutil
    └── install.sh

Install recipe (new host)

Run as a user with sudo:

sudo apt-get install -y python3-venv git
sudo mkdir -p /opt/rpi-mqtt-monitor
sudo git clone https://github.com/hjelev/rpi-mqtt-monitor.git /opt/rpi-mqtt-monitor/rpi-mqtt-monitor
cd /opt/rpi-mqtt-monitor/rpi-mqtt-monitor
sudo python3 -m venv rpi_mon_env
sudo ./rpi_mon_env/bin/pip install -r requirements.txt

Then either:

  • Copy src/config.py from another Pi that already has it (preserves all the dialed-in flags), or
  • Edit src/config.py and set: 
    mqtt_host = "homeassistant.local"
mqtt_user = "pi_monitor"
mqtt_password = "<redacted — same on every Pi; pull from any existing host's config.py>"
mqtt_port = "1883"
mqtt_topic_prefix = "rpi-MQTT-monitor"
discovery_messages = True

Most other defaults are fine. Sensors enabled across the fleet: cpu_load, cpu_temp, used_space, memory, uptime, net_io, git_update. The restart_button, shutdown_button, and update flags expose HA buttons backed by sudoers entries the script's install.sh adds.

Cron entry (root)

*/2 * * * * cd /opt/rpi-mqtt-monitor/rpi-mqtt-monitor; /opt/rpi-mqtt-monitor/rpi-mqtt-monitor/rpi_mon_env/bin/python3 /opt/rpi-mqtt-monitor/rpi-mqtt-monitor/src/rpi-cpu2mqtt.py

Install with sudo crontab -e. The repo also ships a systemd unit (rpi-mqtt-monitor.service) that uses the script's --service flag for an internal loop; on Defiant we use cron instead so a hung run is killed cleanly every 2 minutes.

Verify

One-shot manual run with output:

sudo /opt/rpi-mqtt-monitor/rpi-mqtt-monitor/rpi_mon_env/bin/python3 \
  /opt/rpi-mqtt-monitor/rpi-mqtt-monitor/src/rpi-cpu2mqtt.py --display

Then check HA → Settings → Devices → MQTT — the host should show up by hostname within a minute.

Cross-refs

Defiant

Systems

Clone this wiki locally