Raspberry Pi MQTT Monitor

The easiest way to monitor your Raspberry Pi or Linux system health in Home Assistant — up and running in minutes with zero manual HA configuration.

Features

• Zero-config Home Assistant setup — MQTT discovery messages create devices and sensors automatically
• Remote control — restart, shutdown, and update your device from Home Assistant
• Custom scripts — run your own scripts/programs on the host from Home Assistant buttons
• Flexible delivery — publish over MQTT or directly via the Home Assistant REST API
• Run as a service or cron job — auto-configured by the installer
• External sensor support — DS18B20 (temperature) and SHT21 (temperature + humidity)
• Sensor availability — sensors are marked unavailable in HA when readings fail
• Multi-language — English, German, French, and Bulgarian
• Easy updates — run rpi-mqtt-monitor --update or trigger from the Home Assistant UI

What Gets Monitored

GPU sensors. The installer autodetects your GPU vendor and enables the matching sensors.

• Intel uses intel-gpu-tools (intel_gpu_top); it requires root, so values only populate when running as the systemd service.
• NVIDIA uses the native pynvml library (nvidia-ml-py) and the NVIDIA driver — no root required.
• AMD reads sysfs (/sys/class/drm, in-kernel amdgpu driver) with no extra tools — no root required.

CPU temperature. The reading comes from a psutil sensor whose key varies by board. Set cpu_thermal_zone to the right key — run rpi-mqtt-monitor --config, select cpu_thermal_zone, and pick from the sensors detected live on your machine (e.g. soc_thermal on a Rock64). If the configured key is unknown, the first available sensor is used automatically.

CPU voltage. On a Raspberry Pi this reads vcgencmd measure_volts. On other hosts (e.g. x86 / Ubuntu) it falls back to a Vcore reading from hwmon (lm-sensors), which requires a supported Super-I/O driver — install lm-sensors and run sensors-detect; if sensors then shows a Vcore line it is picked up automatically. Many x86 boxes (especially no-name mini-PCs) have no Super-I/O voltage chip at all, so CPU voltage is simply unavailable there. In that case the sensor reports no value (rather than a misleading 0 V); either disable voltage or set use_availability = True for an explicit "unavailable" state in Home Assistant.

SSD health. The installer autodetects non-rotating drives (NVMe and SATA SSDs) and offers to install smartmontools and enable the ssd_health sensors. smartctl needs root, so values populate when running as the systemd service, or in cron mode via the passwordless sudoers entry the installer adds for smartctl. NVMe metrics come from the uniform SMART health log; SATA wear and data-written are read from the vendor attribute table and are best-effort (they vary by manufacturer).

Table of Contents

• Installation
  • Automated
  • Manual
• Uninstallation
• CLI Reference
• Configuration
  • External Sensors
• Home Assistant Integration
• How to Update
• Feature Requests

Installation

Automated

bash <(curl -s https://raw.githubusercontent.com/hjelev/rpi-mqtt-monitor/master/remote_install.sh)

The installer will:

• Install missing dependencies (git, python3, pip, paho-mqtt, requests, psutil)
• Create a Python virtual environment (rpi_mon_env)
• Prompt you to configure MQTT host and credentials in config.py
• Set up a systemd service or cron job

Running as a service is recommended — it enables the restart, shutdown, and display control buttons in Home Assistant.

Automated Installation Preview

Manual

See the Manual Installation wiki page for step-by-step instructions including service and cron configuration.

Uninstallation

rpi-mqtt-monitor --uninstall

CLI Reference

usage: rpi-mqtt-monitor [-h] [-H] [-d] [-s] [-v] [-u] [-w] [-c] [--uninstall]

Monitor CPU load, temperature, frequency, free space, etc., and publish the
data to an MQTT server or Home Assistant API.

options:
  -h, --help       show this help message and exit
  -H, --hass_api   send readings via Home Assistant API (not via MQTT)
  -d, --display    display values on screen
  -s, --service    run as a service; sleep interval set in config.py
  -v, --version    display installed version and exit
  -u, --update     update script and config then exit
  -w, --hass_wake  display Home Assistant wake-on-LAN configuration
  -c, --config     open the interactive TUI configurator and exit
  --uninstall      uninstall rpi-mqtt-monitor and remove all related files

Interactive configurator

Run rpi-mqtt-monitor --config to open a terminal UI for editing config.py. Move through the settings with the ↑/↓ arrows; each setting shows its description and default value. Press Enter to edit the selected value — booleans toggle, while numbers and strings open an inline editor pre-filled with the current value (Esc cancels an edit). Press s to save and q to quit. Comments, ordering, formatting and the existing quote style in config.py are preserved; complex settings (lists and the output function) are shown read-only with a note to edit them directly in the file.

Configuration

All options live in src/config.py. Key settings:

Full configuration reference: Configuration wiki

Display control backends

With display_control = True, the monitor on/off buttons auto-detect a working backend for the current environment:

GNOME and most non-wlroots Wayland compositors expose no CLI to force monitors off, so external monitors are controlled over DDC/CI with ddcutil. When you enable display control during install.sh, the installer detects your backend and offers to perform this setup for you. To do it manually:

sudo apt install ddcutil
echo i2c-dev | sudo tee /etc/modules-load.d/i2c-dev.conf
sudo modprobe i2c-dev
sudo usermod -aG i2c $USER     # the service runs as this user; re-login or restart the service afterwards
ddcutil detect                 # confirm your monitor(s) are listed

Each monitor must have DDC/CI enabled in its on-screen (OSD) menu — some ship with it off.

If none of the above fits your setup, set display_on_command / display_off_command in config.py to any custom command, which always takes precedence over auto-detection.

Home Assistant Integration

When discovery_messages = True (the default), a new MQTT device is created in Home Assistant automatically — no configuration.yaml edits required. Just add it to a dashboard.

The auto-created device groups all readings, controls (restart, shutdown, update), and sensors under a single Home Assistant entry:

Home Assistant API

To bypass MQTT and push directly to the HA REST API, use the --hass_api flag and configure hass_host and hass_token in config.py.

Wake on LAN

Run rpi-mqtt-monitor --hass_wake to print the YAML snippet for a Home Assistant Wake-on-LAN switch preconfigured with your device's MAC address and IP.

Home Assistant Dashboard

External Sensors

Supports DS18B20 (1-Wire temperature) and SHT21 (I²C temperature + humidity) sensors.

Configure in config.py:

ext_sensors = [
    ["Housing", "ds18b20", "0014531448ff", -300],
    ["ext2",    "sht21",   0,              [-300, 0]],
]

Full setup guide: External Sensors wiki

Feature Requests

Open an issue or submit a pull request — contributions are welcome.