MQTT¶
Der WattWächter Gas 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.
Diese Seite beschreibt die Schnittstelle selbst. Für Home Assistant gibt es eine Schritt-für-Schritt-Anleitung: Home Assistant (MQTT).
Voraussetzungen¶
- WattWächter Gas eingerichtet und mit dem WLAN verbunden — falls noch nicht geschehen, folge zunächst der Einrichtung
- Erreichbarer MQTT-Broker (z. B. Mosquitto, EMQX, HiveMQ oder die Mosquitto-App in Home Assistant) — für Home Assistant siehe MQTT-Broker in Home Assistant einrichten
- Bei TLS: passendes CA-Zertifikat — siehe TLS-Verbindung weiter unten
MQTT aktivieren¶
MQTT ist ab Werk deaktiviert. Aktivieren und konfigurieren kannst du es über die Weboberfläche, das Cloud-Portal oder die 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) oder8883(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 Gas verbindet sich unmittelbar neu.
Topic-Struktur¶
Alle Topics liegen unter einem konfigurierbaren Topic-Prefix. Der Default ist:
WattWaechter/wattwaechter-aabbcc112233/status → online
WattWaechter/wattwaechter-aabbcc112233/7-0:3.0.0 → 4321.456
WattWaechter/wattwaechter-aabbcc112233/7-0:43.0.0 → 0.312
WattWaechter/wattwaechter-aabbcc112233/7-0:16.7.0 → 3.260
homeassistant/sensor/wattwaechter-aabbcc112233_7_0_3_0_0/config → {JSON}
{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
Gas und Wasser erscheinen im Wert-Topic in voller OBIS-Schreibweise (z. B. 7-0:3.0.0), weil die Kurzform mit Strom-Kennzahlen verwechselt werden könnte. Im Discovery-Topic werden -, : und . durch Unterstriche ersetzt (7_0_3_0_0), weil diese Zeichen in Home-Assistant-Discovery-Topics nicht erlaubt sind.
Medium wechseln
Stellst du in den Einstellungen das Medium um (Gas ↔ Wasser), räumt das Gerät die Topics des alten Mediums auf und sendet die Discovery neu.
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).
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 Verbrauchsmessung selten nötig. Für reine Verbrauchsstatistiken reichen oft auch 5–10 Minuten. Für Live-Anzeigen (z. B. „Läuft gerade Wasser?") sind 1–5 Sekunden sinnvoll.
Home Assistant Auto-Discovery¶
Sobald MQTT aktiv ist und sich das Gerät mit dem Broker verbunden hat, werden für jeden bekannten OBIS-Wert automatisch Home-Assistant-Discovery-Nachrichten veröffentlicht. Home Assistant legt dadurch ohne manuelles YAML ein Gerät WattWächter Gas an, mit einem Sensor pro Messwert.
Beispiel-Discovery-Payload (für 7-0:3.0.0 – Zählerstand):
{
"name": "Zählerstand",
"state_topic": "WattWaechter/wattwaechter-aabbcc112233/7-0:3.0.0/json",
"value_template": "{{ value_json.value }}",
"last_reset_value_template": "{{ value_json.last_reset }}",
"availability_topic": "WattWaechter/wattwaechter-aabbcc112233/status",
"payload_available": "online",
"payload_not_available": "offline",
"unit_of_measurement": "m³",
"device_class": "gas",
"state_class": "total",
"unique_id": "wattwaechter-aabbcc112233_7_0_3_0_0",
"device": {
"identifiers": ["wattwaechter-aabbcc112233"],
"name": "WattWächter Gas",
"manufacturer": "SmartCircuits GmbH",
"model": "WattWächter Gas",
"model_id": "ww_gw_mf"
}
}
Der Name der Entität folgt der Sprache aus den Geräteeinstellungen. Den Zählerstand sendet das Gerät zusätzlich als JSON unter …/7-0:3.0.0/json, zusammen mit last_reset: Meldest du einen Zählerwechsel, beginnt der Zählerstand in Home Assistant neu. Gerätename und Modell lauten WattWächter Gas. model_id ist ww_gw_mf bei der Variante Magnetfeld und ww_gw_id bei Induktiv.
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. Ab Home Assistant 2026.12 bietet Home Assistant ein per MQTT eingebundenes Gerät nicht mehr zur Einrichtung der Integration an, manuell hinzufügen lässt es sich aber weiterhin. Verwende nur eine der beiden Quellen.
TLS-Verbindung¶
Der Default-Port ist 8883 mit TLS. Der WattWächter prüft das Zertifikat des Brokers gegen ein eingebautes CA-Bundle. Es enthält genau drei Root-Zertifikate:
| Root-Zertifikat | typisch für |
|---|---|
| ISRG Root X1 | Zertifikate von Let's Encrypt |
| DigiCert Global Root G2 | Zertifikate von DigiCert |
| Amazon Root CA 1 | Zertifikate von Amazon (z. B. AWS IoT Core) |
Stammt das Zertifikat deines Brokers von einer anderen Zertifizierungsstelle — auch einer öffentlichen wie Sectigo oder GlobalSign —, schlägt die Verbindung fehl. Lade dann das passende Root-Zertifikat als eigenes CA-Zertifikat hoch.
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, einer eigenen internen CA (typisch bei Mosquitto im Heimnetz) oder einem Zertifikat einer anderen Zertifizierungsstelle als den drei oben, 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 Zertifikaten der drei eingebauten Zertifizierungsstellen 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 Root-Zertifikat), 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 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 Beispiel: JSON upload, die Dir ein fertiges Gerüst einsetzt.
Ersetze darin den Beispiel-Zertifikatstext durch Deinen eigenen und klicke auf
Anfrage senden:
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 Anfrage senden — 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 Durchfluss
mosquitto_sub -h mqtt.example.com -p 8883 \
-t "WattWaechter/wattwaechter-aabbcc112233/7-0:43.0.0"



