MQTT

Der WattWächter Plus kann seine Messwerte als MQTT-Telemetrie an einen beliebigen MQTT-Broker veröffentlichen — geeignet für Home Assistant, ioBroker, openHAB, Node-RED und jedes andere System mit MQTT-Client.

Home Assistant Auto-Discovery

Die Sensoren werden automatisch per Home Assistant MQTT-Discovery angekündigt und tauchen ohne manuelle YAML-Konfiguration als Geräte-Entitäten auf. Details unten unter Home Assistant Auto-Discovery.

Voraussetzungen

• WattWächter Plus eingerichtet und mit dem WLAN verbunden — falls noch nicht geschehen, folge zunächst der Anleitung unter Erste Schritte
• Erreichbarer MQTT-Broker (z. B. Mosquitto, EMQX, HiveMQ, der Home-Assistant-Add-on-Broker)
• Bei TLS: passendes CA-Zertifikat — siehe TLS-Verbindung weiter unten

---

MQTT aktivieren

MQTT ist ab Werk deaktiviert. Aktivieren und konfigurieren kannst Du es über alle vier Konfigurationswege — Weboberfläche, Smartphone-App, Cloud-Portal oder REST-API (siehe Einstellungen für die allgemeine Einführung). Mindestens nötig sind:

• Aktiviert → true
• Broker-Hostname → DNS-Name oder IP des Brokers
• Port → 1883 (unverschlüsselt) oder 8883 (TLS, Default)

Optional, je nach Broker:

• Benutzername / Passwort (verschlüsselt im Gerätespeicher abgelegt)
• Eigene Client-ID (default: die Geräte-ID wattwaechter-XXXXXXXXXXXX)
• Eigener Topic-Prefix (siehe Topic-Struktur)
• Sendeintervall anpassen (siehe Sendeintervall)
• TLS deaktivieren, falls der Broker nur unverschlüsselt erreichbar ist
• CA-Zertifikat für selbstsignierte Broker (siehe TLS-Verbindung)

Änderungen werden ohne Neustart übernommen — der WattWächter verbindet sich unmittelbar neu.

---

Topic-Struktur

Alle Topics liegen unter einem konfigurierbaren Topic-Prefix. Der Default ist:

WattWaechter/{client_id}

{client_id} entspricht standardmäßig der Geräte-ID (wattwaechter-XXXXXXXXXXXX, die letzten 12 Zeichen der MAC). Sowohl Prefix als auch Client-ID können in den Einstellungen überschrieben werden.

Topic	Inhalt	Retained
{prefix}/status	online nach erfolgreicher Verbindung	ja
{prefix}/{obis}	Aktueller Messwert (siehe Payload-Format)	ja
homeassistant/sensor/{client_id}_{obis_}/config	Home-Assistant-Discovery-Definition	ja

Beispiel-Topics für ein Gerät mit der ID wattwaechter-aabbcc112233:

WattWaechter/wattwaechter-aabbcc112233/status                        → online
WattWaechter/wattwaechter-aabbcc112233/1.8.0                         → 12345.678
WattWaechter/wattwaechter-aabbcc112233/2.8.0                         →    42.123
WattWaechter/wattwaechter-aabbcc112233/16.7.0                        →   -812.4
homeassistant/sensor/wattwaechter-aabbcc112233_1_8_0/config          → {JSON}

OBIS-Format im Topic

Im Wert-Topic wird die OBIS-Kurzform mit Punkten verwendet (z. B. 1.8.0). Im Discovery-Topic werden die Punkte durch Unterstriche ersetzt (1_8_0), weil Punkte in Home-Assistant-Discovery-Topics nicht erlaubt sind.

---

Payload-Format

Veröffentlichte Messwerte sind rohe Float-Werte als ASCII-String, ohne JSON-Wrapper. Beispiel: 12345.678. Die Anzahl der Nachkommastellen richtet sich nach dem Wertetyp (3 bzw. 4 Stellen).

Eine Liste aller veröffentlichten OBIS-Kennzahlen findest Du in der Geräteübersicht. Welche Werte konkret publiziert werden, hängt vom Zähler und den freigeschalteten OBIS-Codes ab.

---

Sendeintervall

Bestimmt den Abstand zwischen zwei Telemetrie-Publishes — also wie oft die aktuellen Zählerwerte an den Broker gesendet werden.

Wert
Default	60 s
Minimum	1 s
Einheit	Sekunden

Sehr kurze Intervalle erzeugen entsprechend mehr Netzwerk- und Broker-Last und sind für Energie-Monitoring selten nötig. Für reine Verbrauchsstatistiken reichen oft auch 5–10 Minuten. Für Live-Anzeigen (z. B. „Wieviel zieht der Backofen gerade?") sind 1–5 Sekunden sinnvoll.

---

Home Assistant Auto-Discovery

Sobald MQTT aktiv ist und sich der WattWächter mit dem Broker verbunden hat, werden für jeden bekannten OBIS-Wert automatisch Home-Assistant-Discovery-Nachrichten veröffentlicht. Home Assistant erkennt das Gerät dadurch ohne manuelles YAML als WattWächter Plus und legt pro Messwert einen Sensor an.

Beispiel-Discovery-Payload (für 1.8.0 – Gesamtbezug):

{
  "name": "Active Energy (A+R+)",
  "state_topic": "WattWaechter/wattwaechter-aabbcc112233/1.8.0",
  "device_class": "energy",
  "unit_of_measurement": "kWh",
  "state_class": "total_increasing",
  "unique_id": "wattwaechter-aabbcc112233_1_8_0",
  "device": {
    "identifiers": ["wattwaechter-aabbcc112233"],
    "name": "Wattwächter",
    "manufacturer": "SmartCircuits GmbH",
    "model": "WattWächter Plus"
  }
}

Discovery-Topics sind retained — Home Assistant erkennt das Gerät damit auch nach einem Neustart sofort wieder. Sie werden ca. 2 Sekunden nach erfolgreicher Verbindung publiziert und nicht automatisch gelöscht, wenn MQTT später deaktiviert wird. Soll das Gerät aus Home Assistant verschwinden, lösche die Discovery-Topics manuell (z. B. mit mosquitto_pub -r -n -t homeassistant/sensor/.../config).

Konflikt mit lokaler HA-Integration

Wenn parallel die native Home-Assistant-Integration läuft, erkennt diese die aktive MQTT-Discovery und warnt. Verwende nur eine der beiden Quellen, sonst entstehen doppelte Entitäten.

---

TLS-Verbindung

Der Default-Port ist 8883 mit TLS. Der WattWächter verifiziert das Broker-Zertifikat gegen ein eingebautes CA-Bundle. Bei eigenen oder selbstsignierten Zertifikaten kannst Du ein zusätzliches CA-Zertifikat hochladen — siehe API-Endpunkte unter POST /api/v1/mqtt/ca (REST-API-Referenz).

TLS lässt sich für reine lokale Broker auch komplett deaktivieren — dann nutzt der WattWächter Port 1883 unverschlüsselt.

---

Authentifizierung

Optional via Benutzername + Passwort. Beide Felder werden vor dem Schreiben in den Gerätespeicher AES-verschlüsselt und nur zur Laufzeit entschlüsselt — sie sind über die REST-API nicht im Klartext lesbar.

Lasse beide Felder leer, wenn Dein Broker anonyme Verbindungen erlaubt.

---

Reconnect-Verhalten

Bei Verbindungsabbruch versucht der WattWächter selbstständig neu zu verbinden. Die Wartezeit verdoppelt sich bei jedem Fehlversuch mit ±25 % Jitter:

1 s → 2 s → 4 s → 8 s → … → 256 s (Cap)

Nach längeren Ausfällen (8 / 20 / 50+ aufeinanderfolgende Fehler) erhöht sich der Cap progressiv bis maximal 5 Minuten, um den Broker zu schonen.

Eine Änderung an den MQTT-Einstellungen löst sofort einen Reconnect mit den neuen Werten aus.

---

Status & Diagnose

Den aktuellen Verbindungsstatus liefert der Endpunkt GET /api/v1/mqtt/status (READ-Token):

{
  "enabled": true,
  "state": "CONNECTED",
  "host": "mqtt.example.com",
  "port": 8883,
  "client_id": "wattwaechter-aabbcc112233",
  "use_tls": true,
  "last_error": 0,
  "last_error_message": "",
  "reconnect_attempts": 0
}

Mögliche state-Werte: OFF, INIT, CONNECTING, CONNECTED, WAIT_RETRY, FAILED.

---

Beispiel: Subscribe mit mosquitto_sub

# Alle Werte eines Geräts mitlesen
mosquitto_sub -h mqtt.example.com -p 8883 \
  -t "WattWaechter/wattwaechter-aabbcc112233/#" -v

# Nur den aktuellen Bezug
mosquitto_sub -h mqtt.example.com -p 8883 \
  -t "WattWaechter/wattwaechter-aabbcc112233/16.7.0"