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, entstehen doppelte Entitäten, ohne dass Home Assistant warnt. Verwende nur eine der beiden Quellen.

---

TLS-Verbindung

Der Default-Port ist 8883 mit TLS. Der WattWächter verifiziert das Broker-Zertifikat gegen ein eingebautes CA-Bundle mit den gängigen öffentlichen Wurzelzertifikaten.

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

Eigenes CA-Zertifikat hochladen

Betreibst Du einen Broker mit selbstsigniertem Zertifikat oder einer eigenen internen CA (typisch bei Mosquitto im Heimnetz), kennt das eingebaute Bundle die ausstellende CA nicht und der Handshake schlägt fehl. Für diesen Fall lässt sich ein eigenes CA-Zertifikat hinterlegen.

Es wird ergänzt, nicht ersetzt

Das hochgeladene Zertifikat wird an das eingebaute Bundle angehängt. Verbindungen zu Brokern mit öffentlich signierten Zertifikaten funktionieren also weiter. Das gilt auch umgekehrt: Das Bundle ist geräteweit geteilt und wird außer für MQTT auch für OTA-Updates und die Cloud-Anbindung verwendet.

Kein Feld in den Einstellungen — trotzdem kein Kommandozeilen-Zwang

Auf der Einstellungsseite gibt es kein Upload-Feld für Zertifikate; das läuft über die REST-API. Dafür musst Du aber nicht ins Terminal: Der API-Explorer in der Weboberfläche bringt für alle drei Endpunkte fertige Formulare mit — siehe unten.

Anforderungen an die Datei

Kriterium	Wert
Format	PEM — die Datei muss -----BEGIN CERTIFICATE----- und -----END CERTIFICATE----- enthalten
Maximale Größe	8192 Bytes; darüber wird der Upload mit 400 abgelehnt
Anzahl	ein Upload-Slot. Ein erneuter POST überschreibt das vorhandene Zertifikat
Ablage	/user_ca.pem im Gerätespeicher — bleibt über Neustarts erhalten

Das Zertifikat wird nicht in Einzelzertifikate zerlegt: Du kannst also auch mehrere aneinandergehängte PEM-Blöcke in einer Datei hochladen (Zwischen- plus Wurzelzertifikat), solange die 8 KB nicht überschritten werden.

Der Werksreset löscht es

Ein Zurücksetzen auf Werkseinstellungen entfernt das hinterlegte Zertifikat mit. Nach einem Werksreset musst Du es erneut hochladen.

Über den API-Explorer

Der bequemste Weg, wenn Du das Zertifikat nur einmal einspielen willst. Öffne die Weboberfläche des WattWächters und klicke auf API Explorer. Die drei CA-Endpunkte findest Du in der Gruppe Interfaces:

Ist die API-Authentifizierung aktiv, trage zuerst oben rechts im Feld API Token einen WRITE-Token ein — sonst antwortet das Gerät mit 401.

Klapp dann POST /api/v1/mqtt/ca auf. Der Explorer zeigt ein Feld JSON-Body und darunter die Schaltfläche Example: JSON upload, die Dir ein fertiges Gerüst einsetzt. Ersetze darin den Beispiel-Zertifikatstext durch Deinen eigenen und klicke auf Send Request:

Zeilenumbrüche als \n

Im JSON-Body muss das PEM einzeilig stehen, die Zeilenumbrüche also als \n geschrieben werden — genau so, wie es das eingesetzte Beispiel vormacht. Kopierst Du den Dateiinhalt mit echten Umbrüchen hinein, ist das kein gültiges JSON und Du bekommst Invalid JSON zurück. Wer das umgehen will, nimmt den curl-Weg mit text/plain weiter unten.

Hochladen per curl

Zwei Content-Types werden akzeptiert. Als JSON, mit dem PEM im Feld certificate:

curl -X POST http://wattwaechter-XXXXXXXXXXXX.local/api/v1/mqtt/ca \
  -H "Authorization: Bearer WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"certificate": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"}'

Oder — meist praktischer — die PEM-Datei direkt als Rohtext, dann musst Du keine Zeilenumbrüche escapen:

curl -X POST http://wattwaechter-XXXXXXXXXXXX.local/api/v1/mqtt/ca \
  -H "Authorization: Bearer WRITE_TOKEN" \
  -H "Content-Type: text/plain" \
  --data-binary @meine-broker-ca.pem

Antwort bei Erfolg — bundle_size ist das eingebaute Bundle inklusive Deines Zertifikats:

{ "success": true, "message": "Certificate added", "bundle_size": 7500 }

Wird erst beim nächsten Verbindungsaufbau wirksam

Eine bestehende MQTT-Verbindung läuft mit dem Bundle weiter, mit dem sie aufgebaut wurde. Das neue Zertifikat greift beim nächsten Reconnect — erzwingen kannst Du das, indem Du MQTT in den Einstellungen kurz aus- und wieder einschaltest oder das Gerät neu startest.

Status abfragen

Im API-Explorer genügt ein Klick auf GET /api/v1/mqtt/ca und Send Request — der Endpunkt braucht keinen Body:

Oder per curl:

curl http://wattwaechter-XXXXXXXXXXXX.local/api/v1/mqtt/ca \
  -H "Authorization: Bearer READ_TOKEN"

{ "has_custom_cert": false, "bundle_size": 5750, "custom_size": 0 }

Feld	Bedeutung
has_custom_cert	true, wenn ein eigenes Zertifikat hinterlegt ist
bundle_size	Größe des wirksamen Bundles in Bytes (eingebaut + eigenes)
custom_size	Größe des eigenen Zertifikats in Bytes, sonst 0

Erneuern und entfernen

Zum Erneuern oder Austauschen lädst Du das neue Zertifikat einfach per POST hoch — es ersetzt das alte. Ein vorheriges DELETE ist nicht nötig.

Läuft das hinterlegte Zertifikat ab, schlägt der TLS-Handshake fehl und der WattWächter landet im Reconnect-Backoff. Sichtbar wird das über GET /api/v1/mqtt/status, siehe Status & Diagnose.

Zum Entfernen ebenfalls per API-Explorer über DELETE /api/v1/mqtt/ca:

Oder per curl:

curl -X DELETE http://wattwaechter-XXXXXXXXXXXX.local/api/v1/mqtt/ca \
  -H "Authorization: Bearer WRITE_TOKEN"

{ "success": true, "message": "Custom certificate deleted", "bundle_size": 5750 }

War gar kein eigenes Zertifikat hinterlegt, antwortet das Gerät mit 404:

{ "success": false, "error": "No custom certificate to delete" }

Fehlermeldungen beim Upload

Alle mit HTTP-Status 400:

error	Ursache
Missing request body	Der Request hatte keinen Body
Content-Type must be application/json or text/plain	Anderer Content-Type gesetzt
Invalid JSON	Body ist kein gültiges JSON (nur bei application/json)
Missing 'certificate' field	JSON ohne das Feld certificate
Failed to add certificate. Check PEM format.	BEGIN/END-Marker fehlen, Datei leer, oder über 8192 Bytes

Die Endpunkte brauchen Token, wenn die API-Authentifizierung aktiv ist: GET einen READ-Token, POST und DELETE einen WRITE-Token.

---

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"