Tutorial: Eine MQTT-Discovery-Nachricht veröffentlichen, die im Energie-Dashboard ankommt

MQTT Discovery beschreibt einen Sensor für Home Assistant. Ein separates Topic transportiert die Messwerte. Das Energie-Dashboard nutzt anschließend geeignete Sensordaten und Statistiken. Diese Schritte sind getrennt zu prüfen: Gültiges JSON allein garantiert weder eine funktionierende Entität noch eine Energiegrafik.

1. Zuerst die Messgröße festlegen

Das Beispiel erfasst aufgelaufenen Strombezug in kWh. Der Zähler steigt normalerweise und kann wieder bei null beginnen. Dafür passt total_increasing. Ein Lebenszeitzähler ohne Rücksetzung kann total ohne last_reset verwenden. Ein saldierender Zähler mit steigenden und fallenden Werten benötigt eine andere Behandlung; total_increasing würde echte Rückgänge falsch einordnen.

Leistung in W beschreibt den momentanen Energieumsatz, Energie in kWh eine aufsummierte Menge. Aktuelle Home-Assistant-Versionen unterstützen geeignete Leistungssensoren in den Leistungsfeldern des Dashboards: device_class: power mit state_class: measurement. Ein W-Messwert darf nicht einfach die Beschriftung kWh erhalten.

2. Eine gültige Sensorkonfiguration veröffentlichen

Voraussetzungen sind ein erreichbarer Broker, eine eingerichtete MQTT-Integration und aktivierte Discovery mit dem erwarteten Präfix. Das Beispiel für eine einzelne Komponente verwendet homeassistant/sensor/example_meter_import/config. Die Kennungen im Discovery-Topic erlauben Buchstaben, Ziffern, Unterstriche und Bindestriche, keinen beliebigen Freitext.

Die Datei energy-discovery.json beschreibt einen erfundenen Zähler. Die stabile eindeutige Kennung muss innerhalb der Installation eindeutig bleiben. Der Anzeigename lässt sich unabhängig davon ändern.

{
  "name": "Imported energy",
  "state_topic": "example/meter/import_kwh",
  "unique_id": "example_meter_import",
  "device_class": "energy",
  "unit_of_measurement": "kWh",
  "state_class": "total_increasing",
  "expire_after": 900,
  "device": {
    "identifiers": [
      "example_meter"
    ],
    "name": "Example meter"
  }
}

state_topic ist für einen MQTT-Sensor erforderlich. Weitere Felder richten sich nach der gewünschten Funktion. Eine eindeutige Kennung ermöglicht die Verwaltung über das Entitätsregister und die hier gezeigte Gerätezuordnung; eine allgemeine Pflicht des Energie-Dashboards ist das Feld nicht. Geräte-Discovery mit einer gemeinsamen device-Nachricht verwendet ein anderes Format mit zusätzlichen Pflichtfeldern.

3. Konfiguration verfügbar und Messwerte aktuell halten

Das Beispiel speichert die Konfiguration mit Retain beim Broker. Alternativ kann der Sender Discovery nach der Startmeldung von Home Assistant erneut veröffentlichen, normalerweise online auf homeassistant/status. Nach Discovery werden außerdem aktuelle Zustände benötigt. Retain ist damit eine Übertragungsmöglichkeit, weder Pflichtfeld noch Garantie für eine Sicherung auf Festplatte bei Brokerausfällen.

Die folgenden Befehle benötigen Mosquitto-Clients ab Version 2.1, da -o erst dort verfügbar ist. mqtt-client.conf enthält Brokeradresse, TLS-Einstellungen und Zugangsdaten als Optionen, jeweils eine pro Zeile. Restriktive Dateirechte schützen die Zugangsdaten; das Passwort steht nicht in der Befehlszeile. Bei älteren Versionen ist die Standard-Konfigurationsdatei eine Alternative. Für Zustandsnachrichten darf die Datei keine Retain-Option enthalten.

mosquitto_pub -o ./mqtt-client.conf -q 1 -r \
  -t homeassistant/sensor/example_meter_import/config \
  -f energy-discovery.json
mosquitto_pub -o ./mqtt-client.conf -q 1 \
  -t example/meter/import_kwh -m '1234.500'
mosquitto_pub -o ./mqtt-client.conf -q 1 \
  -t example/meter/import_kwh -m '1234.625'

Zuerst läuft nur der Konfigurationsbefehl. Vor den beiden Messwertbefehlen müssen Entität und Zustandsabonnement bereitstehen; eine erfolgreiche Veröffentlichung beweist noch keine verarbeitete Discovery. Bei einer Umstellung muss außerdem ein vorhandener Retain-Wert auf dem Zustandstopic entfernt werden. Spätere Nachrichten ohne Retain löschen diesen alten gespeicherten Wert nicht.

Die beiden Beispielwerte unterscheiden sich um 0,125 kWh. Dafür ist ein isolierter Testsensor vorgesehen; erfundene Werte gehören nicht in die Historie eines echten Zählers. Der Sender sollte regelmäßig und mit ausreichendem Abstand zur eingestellten Ablaufzeit von 900 Sekunden melden.

Die Zustandsnachrichten verwenden bewusst kein -r. Bei expire_after könnte ein gespeicherter alter Wert nach erneutem Laden wieder zugestellt werden und frisch erscheinen. Verfügbarkeitsmeldungen mit Birth und Will können zusätzlich einen Verbindungsabbruch anzeigen. Ein Nachweis aktueller physischer Messungen entsteht dadurch nicht.

4. Jede Stufe getrennt prüfen

• Discovery: Das genaue Konfigurationstopic abonnieren und MQTT-Fehler in Home Assistant prüfen. Syntaktisch gültiges JSON kann trotzdem das Sensorschema verletzen.
• Messwert: Auf example/meter/import_kwh muss eine Zahl mit Dezimalpunkt und ohne Einheit stehen. Ein Abonnement dieses Zweigs erfasst keine Nachrichten unter homeassistant/....
• Statistik: Energieklasse, kWh-Einheit, passende Summenklasse und aktiven Recorder prüfen. Statistikfehler und nicht verfügbare Werte sind vor der Interpretation einer Grafik zu klären.
• Dashboard: Den Sensor im Feld für bezogene Energie auswählen. Kurzzeitstatistiken entstehen alle fünf Minuten, Langzeitstatistiken stündlich. Der erste Wert setzt den Ausgangspunkt und zählt nicht als Verbrauch seit der Installation. Direkt nach Discovery ist deshalb keine vollständige Grafik garantiert.

Unerwartete Rückgänge erfordern eine Prüfung von Zähler und Zustandsklasse. Eine Rücksetzung und ein echter negativer Energiefluss sind verschiedene Vorgänge. Die Addition von Zählern mit unterschiedlichen Rücksetzzeitpunkten kann künstliche Summen erzeugen; getrennte Dashboard-Quellen vermeiden dieses konkrete Additionsproblem.

mosquitto_pub -o ./mqtt-client.conf -q 1 -r \
  -t homeassistant/sensor/example_meter_import/config -n

Quellen

• MQTT discovery
• MQTT sensor
• Energy FAQ
• Long-term statistics
• Sensor state classes
• Mosquitto publisher
• Mosquitto broker persistence