Home Assistant per MQTT anbinden
Messwerte automatisch als MQTT-Entitäten anlegen
Ein Python-Skript kann Messwerte an einen MQTT-Broker senden und Home Assistant die zugehörige Entität per MQTT Discovery beschreiben. Die Konfiguration bleibt damit beim Datenlieferanten; zusätzliche Sensorblöcke in der configuration.yaml sind nicht nötig.
Voraussetzungen
- MQTT-Integration in Home Assistant
- erreichbarer Broker, etwa der Mosquitto-Broker als Home-Assistant-Add-on
- eigener Broker-Benutzer mit den nötigen Topic-Rechten
- Python-Virtual-Environment auf dem LAN-Server
Der übliche unverschlüsselte MQTT-Port ist 1883. Er sollte nur im vertrauenswürdigen LAN erreichbar sein. Für Verbindungen über fremde Netze sind TLS oder ein VPN erforderlich.
1. Paho MQTT installieren
python3 -m venv /opt/lanserver/venv
/opt/lanserver/venv/bin/pip install paho-mqtt
2. Discovery und Zustand veröffentlichen
Seit Home Assistant Core 2026.4 wird object_id in MQTT-Konfigurationen ignoriert. default_entity_id schlägt eine Entity-ID vor; unique_id sorgt dafür, dass die Entität in der Entity Registry verwaltet werden kann.
Das Beispiel nutzt die Callback-API von Paho MQTT 2.x und wartet auf die Übertragung, bevor es die Verbindung trennt:
import json
import os
import paho.mqtt.client as mqtt
BROKER = "SERVER-IP-DER-HOME-ASSISTANT-INSTANZ"
PORT = 1883
USER = os.environ["MQTT_USER"]
PASSWORD = os.environ["MQTT_PASSWORD"]
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
client.username_pw_set(USER, PASSWORD)
client.connect(BROKER, PORT, keepalive=60)
config_topic = "homeassistant/sensor/lanserver/temperature/config"
state_topic = "lanserver/sensor/temperature"
availability_topic = "lanserver/status"
config = {
"name": "Temperatur",
"unique_id": "lanserver_temperature_01",
"default_entity_id": "sensor.lanserver_temperatur",
"state_topic": state_topic,
"availability_topic": availability_topic,
"unit_of_measurement": "°C",
"device_class": "temperature",
"state_class": "measurement",
"value_template": "{{ value_json.temperature }}",
"device": {
"identifiers": ["lanserver_01"],
"name": "LAN-Server",
"manufacturer": "DIY"
}
}
client.loop_start()
client.publish(config_topic, json.dumps(config), qos=1, retain=True).wait_for_publish()
client.publish(availability_topic, "online", qos=1, retain=True).wait_for_publish()
client.publish(state_topic, json.dumps({"temperature": 42.5}), qos=1, retain=True).wait_for_publish()
client.disconnect()
client.loop_stop()
Zugangsdaten kommen aus einer geschützten Umgebungsdatei des systemd-Dienstes, nicht aus dem veröffentlichten Python-Code.
Retained Discovery sorgt dafür, dass Home Assistant die Konfiguration nach einem Neustart wieder erhält. Ein retained Zustand liefert den zuletzt bekannten Messwert zurück; er kann jedoch veraltet sein. Deshalb ist ein Verfügbarkeitstopic sinnvoll. Für einen kurzlebigen Timer-Job beschreibt online lediglich, dass der letzte Lauf erfolgreich publiziert hat – nicht, dass ein dauerhafter Prozess aktiv ist.
3. Regelmäßig per systemd-Timer ausführen
# /etc/systemd/system/mqtt-sensor.service
[Unit]
Description=MQTT sensor update
[Service]
Type=oneshot
EnvironmentFile=/etc/lanserver/mqtt.env
ExecStart=/opt/lanserver/venv/bin/python /opt/lanserver/mqtt_sensor.py
# /etc/systemd/system/mqtt-sensor.timer
[Unit]
Description=Update MQTT sensor every five minutes
[Timer]
OnBootSec=1min
OnUnitActiveSec=5min
Persistent=true
[Install]
WantedBy=timers.target
systemctl daemon-reload
systemctl enable --now mqtt-sensor.timer
systemctl list-timers mqtt-sensor.timer
Fehlersuche
1. Mit einem MQTT-Client prüfen, ob Konfigurations- und Zustands-Topic eintreffen.
2. Groß-/Kleinschreibung und vollständige Topic-Pfade vergleichen.
3. Broker-Anmeldung und ACLs kontrollieren.
4. Nach geänderten unique_id-Werten alte retained Configs bewusst mit leerem retained Payload löschen.
5. journalctl -u mqtt-sensor.service auf Python- oder Netzwerkfehler prüfen.
Fazit
MQTT Discovery ist für regelmäßig aktualisierte Sensoren gut geeignet. Zu einer belastbaren Umsetzung gehören eindeutige IDs, bestätigte Publishes, ein definierter Umgang mit retained Daten und getrennt gespeicherte Zugangsdaten.
