REST-API¶
Gleiche API wie beim WattWächter Plus
Die REST-API ist beim WattWächter Gas dieselbe wie beim WattWächter Plus. Die Messwerte tragen aber die Einheit m³ im Namen (z. B. import_total_m3, flow_m3h, consumption_m3 statt import_total_kWh, power_W), Einspeisewerte fehlen, und /api/v1/history/latest enthält zusätzlich einen Block gw mit Sensordaten. Welches Gerät antwortet, steht in /api/v1/system/info unter esp.model_id (ww_gw_mf bzw. ww_gw_id, beim Plus ww_plus).
Die WattWächter REST API ist unter http://wattwaechter-XXXXXXXXXXXX.local/api/v1/ erreichbar und bietet vollen Zugriff auf Gerätedaten, Einstellungen und Steuerungsfunktionen.
Authentifizierung¶
Ab Werk deaktiviert
Die API-Authentifizierung ist ab Werk deaktiviert. Alle Endpunkte sind ohne Token erreichbar. Einzige Ausnahme: Schreiben von anderen Webseiten. Die Authentifizierung kann über die Einstellungen aktiviert werden (api_auth_required: true).
Wenn aktiviert, verwendet die API Bearer Tokens im Authorization-Header:
Authorization: Bearer DEIN_TOKEN
Alternativ geht der Header X-Api-Token: DEIN_TOKEN.
Es gibt zwei Token-Stufen:
- READ Token — Daten lesen (History, Status, Einstellungen anzeigen)
- WRITE Token — Einstellungen ändern, OTA starten, Reboot auslösen
Token erneuern
Tokens können über einen zweistufigen Prozess erneuert werden:
POST /api/v1/auth/tokens/generate— Generiert neue Tokens (noch nicht aktiv)POST /api/v1/auth/tokens/confirm— Aktiviert die neuen Tokens (innerhalb von 60 Sekunden)
Dieser Zwei-Phasen-Ansatz verhindert ein Aussperren, falls die Antwort verloren geht.
Schreiben von anderen Webseiten (ab Firmware 1.3)¶
Auch ohne aktivierte Authentifizierung darf nicht jede Webseite auf das Gerät schreiben. Schickt ein Browser eine Anfrage von einer Seite, die nicht vom Gerät selbst stammt, braucht sie den WRITE-Token. So kann keine fremde Webseite, die jemand im selben Netz öffnet, Einstellungen ändern oder Geräte schalten.
- Betroffen sind alle Aufrufe, die etwas ändern (
POST,DELETE). Lesen (GET) geht weiterhin ohne Token. - Nicht betroffen sind die Weboberfläche des Geräts, die App, Home Assistant und eigene Skripte.
Ohne Token antwortet das Gerät mit:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{"error":"Write access from another web page needs the WRITE token"}
Eine eigene Webseite, die auf das Gerät schreiben soll, schickt den WRITE-Token mit:
fetch('http://wattwaechter-XXXXXXXXXXXX.local/api/v1/settings', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer DEIN_WRITE_TOKEN'
},
body: JSON.stringify({ ledEnable: false })
});
Den WRITE-Token zeigt die Ersteinrichtung an. Hast du ihn nicht notiert, erzeugst du in der Weboberfläche unter Einstellungen → API-Sicherheit neue Tokens.
Hinter einem Reverse-Proxy
Das Gerät erkennt eine fremde Seite daran, dass der Origin-Header einen anderen Host nennt als der Host-Header. Ein Reverse-Proxy muss den Host-Header deshalb durchreichen (nginx: proxy_set_header Host $host;). Sonst lehnt das Gerät auch Änderungen aus der eigenen Weboberfläche ab.
Rate Limits & Fehlercodes¶
Da der WattWächter auf einem ESP32 mit begrenztem Arbeitsspeicher läuft, sind eingehende API-Anfragen begrenzt. Clients sollten den Retry-After-Header beachten und Anfragen entsprechend zurückstellen.
Rate Limit¶
Es sind maximal 25 Anfragen pro 10 Sekunden erlaubt (geräteweit, nicht pro IP — mehrere Clients teilen sich das Budget). Wird das Limit überschritten, antwortet das Gerät mit:
HTTP/1.1 429 Too Many Requests
Retry-After: 10
Content-Type: application/json
{"error":"Too many requests"}
Heap-Schutz¶
Sinkt der freie Heap unter eine kritische Schwelle (25 KB), werden neue API-Anfragen kurzzeitig abgelehnt, um das Gerät stabil zu halten:
HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json
{"error":"Service temporary unavailable"}
Tritt typischerweise bei sehr großen Antworten (z. B. langen History-Zeiträumen) unter gleichzeitiger Last auf. Ein Wiederholungsversuch nach wenigen Sekunden ist in der Regel erfolgreich.
Python-Client
Die Python-Bibliothek berücksichtigt sowohl 429 als auch 503 automatisch und respektiert den Retry-After-Header.
Endpunkt-Übersicht¶
System¶
| Methode | Endpunkt | Auth | Beschreibung |
|---|---|---|---|
| GET | /api/v1/system/alive |
— | Healthcheck |
| GET | /api/v1/system/info |
READ | Systeminformationen |
| GET | /api/v1/system/led |
READ | LED-Status |
| GET | /api/v1/system/wifi_scan |
— | WLAN-Scan |
| GET | /api/v1/system/timezones |
READ | Zeitzonen-Liste |
| POST | /api/v1/system/reboot |
WRITE | Neustart |
History¶
| Methode | Endpunkt | Auth | Beschreibung |
|---|---|---|---|
| GET | /api/v1/history/latest |
READ | Aktuellster Messwert |
| GET | /api/v1/history/highRes?date=YYYY-MM-DD |
READ | 15-Min-Daten für einen Tag |
| GET | /api/v1/history/lowRes?start=YYYY-MM-DD&days=7 |
READ | Tageswerte |
Einstellungen¶
| Methode | Endpunkt | Auth | Beschreibung |
|---|---|---|---|
| GET | /api/v1/settings |
READ | Einstellungen lesen |
| POST | /api/v1/settings |
WRITE | Einstellungen ändern (partiell) — siehe Einstellungen ändern |
| POST | /api/v1/auth/tokens/generate |
WRITE | Neue Tokens generieren |
| POST | /api/v1/auth/tokens/confirm |
WRITE | Tokens aktivieren |
| GET | /api/v1/mqtt/ca |
READ | CA-Zertifikat-Status |
| POST | /api/v1/mqtt/ca |
WRITE | CA-Zertifikat hochladen |
| DELETE | /api/v1/mqtt/ca |
WRITE | CA-Zertifikat löschen |
| POST | /api/v1/cloud/pair |
WRITE | Cloud-Pairing-Token senden |
| GET | /api/v1/cloud/pair |
READ | Status von Pairing und Cloud-Verbindung |
| DELETE | /api/v1/cloud/pair |
WRITE | Cloud-Pairing aufheben; ?data=delete löscht zusätzlich den Cloud-Verlauf |
OTA¶
| Methode | Endpunkt | Auth | Beschreibung |
|---|---|---|---|
| GET | /api/v1/ota/check |
READ | Update prüfen |
| POST | /api/v1/ota/start |
WRITE | Update starten |
Logs¶
| Methode | Endpunkt | Auth | Beschreibung |
|---|---|---|---|
| GET | /api/v1/logs/rawdump |
READ | SmartMeter Ringbuffer (binär) |
| GET | /api/v1/logs/persistent |
READ | Persistentes CSV-Logfile |
| GET | /api/v1/logs/ram |
READ | RAM-Log Snapshot (CSV) |
Modbus TCP¶
| Methode | Endpunkt | Auth | Beschreibung |
|---|---|---|---|
| GET | /api/v1/modbus/status |
READ | Modbus-Server-Status und aktuelle Register-Belegung |
→ Details & Aktivierung: Modbus TCP
Schalten (ab Firmware 1.3)¶
| Methode | Endpunkt | Auth | Beschreibung |
|---|---|---|---|
| GET | /api/v1/switch/status |
READ | Zustand der Schaltregeln |
| POST | /api/v1/switch/test |
WRITE | Gerät einer Regel von Hand schalten oder Verbindung prüfen |
Ein- und Ausschalten bzw. die Regeln selbst laufen über POST /api/v1/settings.
Einstellungen ändern (POST /api/v1/settings)¶
Alles, was du in der Weboberfläche unter Einstellungen speicherst, geht über diesen einen Endpunkt. Du kannst ihn genauso aus Skripten, Home Assistant (rest_command), Node-RED oder ioBroker aufrufen.
So funktioniert es¶
- Nur was du mitschickst, ändert sich. Du brauchst vorher kein
GETund schickst nie die komplette Konfiguration.{"ledEnable": false}schaltet nur die LED aus, alles andere bleibt, wie es ist. - Format: JSON mit
Content-Type: application/json, höchstens 2 KB je Anfrage (ab Firmware 1.3: 8 KB). - Eine Änderung pro Sekunde. Folgt die nächste Anfrage schneller, antwortet das Gerät mit
429undRetry-After: 1. Mehrere Bereiche ändert man deshalb am besten in einer Anfrage. - Antwort:
{"success": true, "applied": {…}}. Unterappliedsteht deine Anfrage zurück — nicht der gespeicherte Stand. Passwörter fehlen darin ab Firmware 1.3; ältere Firmware gibt sie im Klartext zurück. Ob ein Wert angekommen ist, zeigt ein anschließendesGET /api/v1/settings. - Passwörter (WLAN, Access Point, MQTT, NES-Zähler) liefert
GETnie zurück, nur ob eines gesetzt ist (password_set,passwordSet). Feld weglassen = Passwort bleibt; leerer Text""= Passwort wird gelöscht. - Unbekannte Felder auf oberster Ebene lehnt das Gerät mit
400ab (Unknown field: …) — ein Tippfehler fällt also auf. Unbekannte Unterfelder (z. B.mqtt.hots) werden dagegen stillschweigend ignoriert; prüfe nach dem Speichern mitGET. - Die meisten Änderungen wirken sofort, ohne Neustart: MQTT verbindet sich neu, Modbus startet bzw. stoppt, der Access Point startet neu, die Zeitzone gilt sofort. WLAN-Änderungen lösen einen Neuverbindungsversuch aus — siehe WLAN wechseln.
- Mit API-Schutz brauchst du den WRITE-Token, entweder als
Authorization: Bearer DEIN_WRITE_TOKENoder alsX-Api-Token: DEIN_WRITE_TOKEN.
In den Beispielen steht WW für die Adresse deines Geräts, z. B.:
WW=http://wattwaechter-XXXXXXXXXXXX.local # oder die IP-Adresse, z. B. http://192.168.178.50
Ist der API-Schutz eingeschaltet, hänge an jeden Aufruf -H "Authorization: Bearer DEIN_WRITE_TOKEN" an.
Aktuelle Einstellungen lesen¶
curl -s $WW/api/v1/settings
Die Antwort hat dieselbe Struktur, die du beim Schreiben verwendest. Zusätzlich enthält sie reine Anzeigewerte wie rebootsTotal oder password_set, die sich nicht schreiben lassen.
Gerätename¶
Erscheint in der Weboberfläche, in Home Assistant und in der App. Höchstens 31 Zeichen.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"device_name": "Keller Hausanschluss"}'
Status-LED aus- oder einschalten¶
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"ledEnable": false}'
Zeitzone, Zeitserver und Sprache¶
Die erlaubten Zeitzonen liefert GET /api/v1/system/timezones; ein unbekannter Name wird mit 400 Invalid timezone abgelehnt. Die Sprache der Weboberfläche ist de oder en.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"timezone": "Europe/Berlin",
"ntp_server": "fritz.box",
"language": { "active": "en" }
}'
WLAN wechseln¶
Vorsicht: Du kannst dich aussperren
Nach einer WLAN-Änderung verbindet sich das Gerät neu. Stimmen SSID oder Passwort nicht, ist es im alten Netz nicht mehr erreichbar. Es fällt dann auf das Ausweich-WLAN oder den Access Point zurück. Die Antwort auf die Anfrage kommt noch vor dem Wechsel — sie bestätigt also nur, dass die Werte gespeichert sind, nicht dass die Verbindung klappt.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"wifi": {
"primary": { "ssid": "MeinWLAN", "password": "geheimes-passwort" }
}
}'
Die SSID darf höchstens 32 Zeichen haben (sonst 400). Ändert sich nichts an den WLAN-Feldern, verbindet sich das Gerät auch nicht neu.
Feste IP-Adresse¶
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"wifi": {
"primary": {
"static_ip": true,
"ip": "192.168.178.50",
"subnet": "255.255.255.0",
"gateway": "192.168.178.1",
"dns": "192.168.178.1"
}
}
}'
Zurück zu DHCP: {"wifi": {"primary": {"static_ip": false}}}. Einfacher und sicherer ist meist, im Router eine feste Adresse für den WattWächter zu vergeben.
Ausweich-WLAN¶
Ein zweites Netz, das der WattWächter nutzt, wenn das erste nicht erreichbar ist (z. B. Repeater im Keller).
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"wifi": {
"secondary": { "enable": true, "ssid": "MeinWLAN-Keller", "password": "anderes-passwort" }
}
}'
Access Point¶
Der Access Point ist das eigene WLAN des WattWächters für die Einrichtung. Abschalten:
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"accessPoint": {"enable": false}}'
Mit eigenem Namen und Passwort:
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"accessPoint": {
"enable": true,
"ssid": "WattWaechter-Keller",
"password_enable": true,
"password": "mindestens8zeichen"
}
}'
Passwort mit mindestens 8 Zeichen
WPA2 verlangt 8 bis 63 Zeichen. Ein kürzeres oder längeres Passwort lehnt die API ab Firmware 1.3 mit 400 ab. Ältere Firmware nimmt es an, der Access Point startet dann aber ohne Passwort. Ein leeres password löscht das Passwort, ein leerer ssid-Wert stellt den automatischen Namen wieder her.
MQTT¶
Verbindung zu einem eigenen Broker einrichten (hier Mosquitto in Home Assistant ohne TLS):
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"mqtt": {
"enable": true,
"host": "homeassistant.local",
"port": 1883,
"use_tls": false,
"user": "wattwaechter",
"password": "mqtt-passwort",
"sendInterval": 10
}
}'
sendInterval: Sekunden zwischen zwei Messwert-Nachrichten, mindestens 1.client_id: Name, unter dem sich das Gerät am Broker anmeldet. Ein leerer Text""stellt den Standard wieder her (der Hostnamewattwaechter-…).topic_prefix: Anfang aller Topics, z. B."WattWaechter/keller".- Ein eigenes CA-Zertifikat für TLS lädst du separat über
POST /api/v1/mqtt/cahoch.
Nur das Intervall ändern — die übrigen MQTT-Werte bleiben:
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"mqtt": {"sendInterval": 60}}'
Ob die Verbindung steht, zeigt GET /api/v1/mqtt/status. Mehr dazu unter MQTT.
Modbus TCP¶
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"modbus": {"enable": true, "port": 502}}'
Der Server startet sofort. Welche Register er liefert, zeigt GET /api/v1/modbus/status — siehe Modbus TCP.
Automatische Updates und Cloud¶
# Updates nicht mehr nachts automatisch installieren
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"autoOta": false}'
# Verbindung zur WattWächter-Cloud pausieren (die Kopplung bleibt bestehen)
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"awsIotEnabled": false}'
Die Cloud-Kopplung selbst steuerst du über POST/DELETE /api/v1/cloud/pair.
API-Schutz einschalten¶
Ab dann verlangen fast alle Aufrufe einen Token (ausgenommen z. B. /system/alive). Damit du dich nicht aussperrst, nimmt das Gerät die Änderung nur an, wenn du dabei schon den WRITE-Token mitschickst — sonst antwortet es mit 403. Die Tokens stehen in der Weboberfläche unter Einstellungen → API-Sicherheit.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer DEIN_WRITE_TOKEN" \
-d '{"api_auth_required": true}'
Ausschalten: {"api_auth_required": false} (ebenfalls mit WRITE-Token, weil der Schutz da ja noch an ist).
Nur beim WattWächter Gas: Zähler einstellen¶
Alle Werte unter gw prüft das Gerät, bevor es etwas speichert. Liegt einer außerhalb des Bereichs, wird die ganze Anfrage mit 400 abgelehnt und nichts geändert.
Zählerstand eintragen oder korrigieren¶
initialReading ist der Stand in m³, den du gerade am Zähler abliest. Ab diesem Wert zählt das Gerät weiter; die Korrektur zählt nicht als Verbrauch.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"gw": {"initialReading": 1234.567}}'
Jede Eingabe erhöht readingSeq (sichtbar in GET /api/v1/settings unter gw). Den aktuellen Stand zeigt dort reading.
Medium, Volumen pro Umdrehung und Empfindlichkeit¶
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"gw": {
"medium": "gas",
"pulseVolume": 0.01,
"hysteresis": 250
}
}'
| Feld | Bereich | Bedeutung |
|---|---|---|
medium |
"gas" oder "water" |
Was gezählt wird |
pulseVolume |
0,0001–1 m³ | Volumen pro Umdrehung der Zählrolle (Gas typisch 0,01, Wasser 0,001) |
hysteresis |
Magnetfeld (GW-MF): 10–5000 µT, Standard 250 · Induktiv (GW-ID): 5–500 Schritte, Standard 15 | Empfindlichkeit bzw. Mindestausschlag der Erkennung |
Eine Änderung von pulseVolume lässt den Zählerstand nicht springen; nur künftige Umdrehungen zählen mit dem neuen Wert. Welche Variante du hast, steht in GET /api/v1/system/info unter esp.model_id (ww_gw_mf / ww_gw_id).
Umrechnung in kWh (nur Gas)¶
Brennwert und Zustandszahl stehen auf deiner Gasrechnung. Daraus rechnet das Gerät m³ in kWh um (m³ × Zustandszahl × Brennwert).
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"gw": {"calorificValue": 11.2, "zNumber": 0.9542}}'
| Feld | Bereich |
|---|---|
calorificValue |
5–15 kWh/m³ |
zNumber |
0,8–1,2 |
Geräte schalten (ab Firmware 1.3)¶
Schaltregeln schalten einen Shelly oder ein anderes Gerät mit HTTP-Schnittstelle ein oder aus — nach Messwerten, Uhrzeit und Laufzeit oder nach der geflossenen Menge. Bis zu 4 Regeln. In der Weboberfläche findest du sie unter Einstellungen → Schalten.
Die Liste wird immer komplett ersetzt
Anders als die übrigen Einstellungen ist switch.rules keine Teiländerung: Du schickst alle Regeln, die danach gelten sollen. Eine Regel, die in der Liste fehlt, ist gelöscht. Lies deshalb vorher die aktuelle Liste mit GET /api/v1/settings (Feld switch.rules), ändere sie und schicke sie vollständig zurück. Ist eine Regel fehlerhaft, wird nichts gespeichert.
Aufbau einer Regel¶
Jede Regel hat ein Ziel (target) und zwei Seiten: on sagt, wann eingeschaltet wird, off, wann ausgeschaltet wird. Jede Seite hat bis zu 4 Bedingungen (conditions). match legt fest, wie sie verknüpft sind:
"all": Alle Bedingungen müssen gelten (UND). Das gilt auch, wennmatchfehlt."any": Eine Bedingung reicht (ODER).
Eine Seite darf leer bleiben ("conditions": []). Dann schaltet die Regel in diese Richtung nie — zum Beispiel ein Ventil, das sie nur schließt, aber nie öffnet. Mindestens eine Seite braucht eine Bedingung.
{
"name": "Beispiel",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.60", "channel": 0 },
"on": { "match": "all", "conditions": [ … ] },
"off": { "match": "any", "conditions": [ … ] }
}
| Feld | Werte | Bedeutung |
|---|---|---|
name |
höchstens 31 Zeichen | Anzeigename |
enable |
true / false |
Regel aktiv. Fehlt das Feld, ist sie aktiv |
target.type |
shelly, tasmota oder url |
Shelly (Gen1 und ab Gen2, wird automatisch erkannt), Tasmota-Gerät oder eigene Adresse für jedes andere Gerät |
target.host |
IP oder Name, optional mit :port |
Bei shelly und tasmota, ohne http:// |
target.channel |
0–3 (shelly), 0–7 (tasmota) |
Ausgang, gezählt ab 0: beim Shelly die id, bei Tasmota steht 0 für Power1, 1 für Power2 usw. |
target.on_url, target.off_url |
http://…, höchstens 159 Zeichen |
Nur bei url: werden per GET aufgerufen. https geht nicht. Eine Seite mit Bedingungen braucht ihre Adresse, die andere darf leer sein ("") |
on, off |
match: all oder any · conditions: bis zu 4 |
Einschalt- bzw. Ausschaltseite |
Bedingungen¶
type |
Felder | Erfüllt, wenn … | Gerät |
|---|---|---|---|
value |
source, op (above oder below), value, delay (0–86400 s, Standard 0) |
der Messwert über bzw. unter value liegt — ununterbrochen mindestens delay Sekunden |
alle, Messwerte siehe unten |
time |
at ("HH:MM"), days |
es genau diese Uhrzeit ist. Gilt die ganze Minute lang | alle |
window |
from, to ("HH:MM"), days |
die Uhrzeit ab from und vor to liegt. Geht auch über Mitternacht |
alle |
state |
for (1–604800 s) |
das Gerät seit mindestens for Sekunden im Gegenzustand ist: auf der Ausschaltseite an seit, auf der Einschaltseite aus seit |
alle |
volume |
value (m³, größer als 0) |
seit dem letzten Wechsel mindestens so viel geflossen ist — auf der Ausschaltseite also seit dem Einschalten | nur Gas und Wasser |
days ist eine Liste von Wochentagen: 1 = Montag bis 7 = Sonntag. Fehlt das Feld, gilt jeder Tag. Ein Zeitraum über Mitternacht gehört zu dem Tag, an dem er beginnt: {"type": "window", "from": "22:00", "to": "06:00", "days": [5]} gilt von Freitag 22 Uhr bis Samstag 6 Uhr.
Mit state baust du Laufzeiten und Pausen. Auf der Ausschaltseite mit "any" ist es eine Höchstlaufzeit (aus spätestens nach …), mit "all" eine Mindestlaufzeit (aus frühestens nach …). Auf der Einschaltseite gilt dasselbe für die Pause.
Welche Messwerte? (source)¶
Eine value-Bedingung beobachtet einen von vier Messwerten. Welche ein Gerät kennt, hängt davon ab, was es misst:
source |
Einheit | Gerät | Was gemessen wird |
|---|---|---|---|
export |
W | WattWächter Plus | Überschuss = Einspeisung ins Netz. Positiv, solange du einspeist, negativ bei Netzbezug |
import |
W | WattWächter Plus | Netzbezug. Positiv, solange du Strom beziehst, negativ bei Einspeisung |
flow |
m³/h | WattWächter Gas, WattWächter Wasser | Durchfluss am Zähler, aus den Impulsen berechnet, nie negativ |
draw |
m³ | WattWächter Gas, WattWächter Wasser | Menge ohne Pause: was seit Beginn des laufenden Durchflusses geflossen ist. Fällt der Durchfluss auf 0, beginnt sie von vorn |
export und import sind derselbe Messwert (die aktuelle Leistung am Zähler, OBIS 16.7.0), nur mit umgekehrtem Vorzeichen: "export" mit above 1500 heißt „mehr als 1500 W Einspeisung“, "import" mit above 1500 heißt „mehr als 1500 W Bezug“. Nimm den Wert, bei dem sich deine Schwelle natürlich liest; export below 0 ist gleichbedeutend mit import above 0.
Auf diesem Gerät sind flow und draw möglich — es misst Gas bzw. Wasser, keine Leistung. Eine Regel mit export oder import lehnt es mit 400 switch.rules[0]: source not available on this device ab.
draw und die Bedingung volume zählen beide Kubikmeter, aber ab einem anderen Moment: draw ab Beginn des Durchflusses, egal was geschaltet wurde. volume ab dem letzten Wechsel des geschalteten Geräts.
Durchfluss und Mengen stehen in der API immer in m³/h bzw. m³. Welche Messwerte ein Gerät kennt, steht in GET /api/v1/switch/status unter sources.
Beispiele¶
Ein Shelly schaltet eine Meldeleuchte ein, wenn 10 Minuten lang mehr als 2,5 m³/h Gas fließen, und wieder aus, wenn der Durchfluss eine Minute lang unter 0,5 m³/h liegt.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"switch": {
"rules": [
{
"name": "Meldeleuchte Gas",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.60", "channel": 0 },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "above", "value": 2.5, "delay": 600 }
] },
"off": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "below", "value": 0.5, "delay": 60 }
] }
}
]
}
}'
Weitere Beispiele¶
Die folgenden Regeln setzt du einzeln oder zusammen in die Liste rules ein (höchstens 4 Regeln je Gerät).
Dunstabzug beim Kochen mit Gas — Mindestlaufzeit, Name statt IP, zweiter Ausgang. Fließt 10 Sekunden lang Gas, startet der Dunstabzug über Ausgang 2 eines Shelly Plus 2PM. Aus geht er, wenn 5 Minuten lang kaum noch etwas fließt und er mindestens 10 Minuten gelaufen ist.
{
"name": "Dunstabzug",
"enable": true,
"target": { "type": "shelly", "host": "shelly-kueche.local", "channel": 1 },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "above", "value": 0.05, "delay": 10 }
] },
"off": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "below", "value": 0.01, "delay": 300 },
{ "type": "state", "for": 600 }
] }
}
Viel Gas ohne Pause. Werden mehr als 5 m³ ohne Pause verbraucht, schaltet eine Meldeleuchte ein und nach 30 Minuten wieder aus.
{
"name": "Gas 5 m³ ohne Pause",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.62", "channel": 0 },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "draw", "op": "above", "value": 5, "delay": 0 }
] },
"off": { "match": "all", "conditions": [
{ "type": "state", "for": 1800 }
] }
}
Volllast mitten in der Nacht — Zeitraum und Uhrzeit, Tasmota, vorbereitet. Mit Nachtabsenkung läuft die Heizung nachts kaum. Zieht sie zwischen 0 und 5 Uhr 30 Minuten lang mehr als 2 m³/h, schaltet eine Tasmota-Steckdose eine Warnleuchte ein. Um 07:00 geht sie aus. Die Regel ist vorbereitet, aber noch ausgeschaltet ("enable": false).
{
"name": "Gas nachts",
"enable": false,
"target": { "type": "tasmota", "host": "192.168.178.62", "channel": 0 },
"on": { "match": "all", "conditions": [
{ "type": "window", "from": "00:00", "to": "05:00" },
{ "type": "value", "source": "flow", "op": "above", "value": 2, "delay": 1800 }
] },
"off": { "match": "all", "conditions": [
{ "type": "time", "at": "07:00" }
] }
}
Hoher Verbrauch melden — eigene URL, nur einschalten. Fließen 15 Minuten lang mehr als 3 m³/h, schaltet eine WLAN-Steckdose, die weder Shelly noch Tasmota ist, über ihre HTTP-Adresse eine Warnleuchte ein. Die Ausschaltseite bleibt leer: Die Leuchte schaltest du nach dem Nachsehen selbst ab.
{
"name": "Warnleuchte Gas",
"enable": true,
"target": { "type": "url", "on_url": "http://192.168.178.62/relay?state=on", "off_url": "" },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "above", "value": 3, "delay": 900 }
] },
"off": { "match": "all", "conditions": [] }
}
Reine Zeitschaltung ohne Messwert. Eine Pumpe läuft 5 Minuten, macht 25 Minuten Pause, und so weiter. Beide Seiten fragen nur, wie lange das Gerät schon im Gegenzustand ist. Gezählt wird ab dem Moment, in dem der WattWächter den Zustand des Shelly kennt. Ein Neustart des WattWächter unterbricht das nicht.
{
"name": "Takt 5/25",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.64", "channel": 0 },
"on": { "match": "all", "conditions": [ { "type": "state", "for": 1500 } ] },
"off": { "match": "all", "conditions": [ { "type": "state", "for": 300 } ] }
}
Was die Beispiele zusammen zeigen
| Variante | Wo |
|---|---|
Shelly mit IP, Name (….local) oder IP:Port |
host |
| Zweiter Ausgang eines Mehrkanal-Shelly | "channel": 1 |
Tasmota-Gerät, erster Ausgang (Power1) |
"type": "tasmota", "channel": 0 |
| Eigene URL, auch nur mit Einschalt-Adresse | "type": "url", "off_url": "" |
| Nur einschalten oder nur ausschalten | Die andere Seite leer lassen: "conditions": [] |
| Mehrere Bedingungen | "match": "all" (UND) oder "match": "any" (ODER) |
| Mindestlaufzeit / Höchstlaufzeit | state auf der Ausschaltseite, mit all bzw. any |
| Uhrzeit, Zeitraum, Wochentage | time, window, days |
| Sofort schalten | "delay": 0 |
| Regel vorbereiten, aber noch nicht aktiv | "enable": false |
Alle Regeln löschen:
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"switch": {"rules": []}}'
Verhalten¶
- Geschaltet wird, wenn eine Seite neu erfüllt ist — einmal, solange sie ununterbrochen gilt. Eine
time-Bedingung gilt eine Minute lang und schaltet so einmal am Tag. - Von Hand geschaltet bleibt geschaltet. Schaltest du das Gerät um (am Shelly, in seiner App oder über
/switch/test), überstimmt dich die Regel nicht, solange ihre Seite weiter gilt. Erst wenn die Seite einmal weg war und wieder erfüllt ist, schaltet sie erneut. - Werden beide Seiten im selben Moment erfüllt, gewinnt Ausschalten. Die Einschaltseite schaltet erst wieder, wenn sie einmal nicht galt.
- Uhrzeit und Wochentag richten sich nach der Zeitzone des Geräts. Bevor die Uhr per Zeitserver (NTP) gestellt ist, gelten
timeundwindownicht. Was das Gerät gerade für die Uhrzeit hält, steht in/switch/statusuntertime. Eine verpasste Schaltzeit (time) holt das Gerät bis zu 15 Minuten lang nach: bei nicht erreichbarem Ziel alle 30 Sekunden, nach einer WLAN-Lücke einmal, nach einem Stromausfall nicht. stateundvolumebrauchen den Zustand des Geräts. Einen Shelly und ein Tasmota-Gerät fragt der WattWächter alle 30 Sekunden ab, so zählen auch Wechsel von Hand. Bei einer eigenen URL kennt er den Zustand erst, wenn er selbst geschaltet hat — vorher gelten diese Bedingungen nicht. Eine Zeitschaltung mit eigener URL startest du deshalb einmal über/switch/test.- Zustand und Dauer überstehen einen Neustart. Der WattWächter merkt sich je Regel den Zustand und den Zeitpunkt des letzten Wechsels. Nach einem Neustart zählt „an seit“ bzw. „aus seit“ von dort weiter — bei Shelly und Tasmota, sofern das Gerät noch im selben Zustand ist. Eine geänderte Regel beginnt neu.
- Ohne frischen Messwert gilt eine
value-Bedingung nicht (Sensor meldet einen Fehler). Ihre Wartezeit beginnt danach neu. Das gilt auch für die Ausschaltseite: Ein eingeschaltetes Gerät bleibt ohne Messwert an. Wer das absichern will, gibt der Ausschaltseite mit"any"zusätzlich eine Höchstlaufzeit (state). Die Weboberfläche zeigt bei der Regel einen Hinweis, solange der Messwert fehlt. Ein stehender Zähler ist kein Fehler: Durchfluss 0 ist ein gültiger Messwert. - Geht ein Befehl schief (Gerät nicht erreichbar), versucht es der WattWächter nach 30 Sekunden erneut.
- Eine verpasste Schaltzeit (
time) wird bis zu 15 Minuten lang nachgeholt. Ist das Gerät in der Schaltminute nicht erreichbar, versucht es der WattWächter weiter. Konnte er in der Minute selbst nicht auswerten (kein WLAN, Uhr noch nicht gestellt, Start dauert länger), schaltet er beim nächsten Mal — außer das Gerät hat seit der Schaltzeit schon gewechselt. Nach einem Stromausfall wird nicht nachgeholt. - Shellys und Tasmota-Geräte mit Passwortschutz werden noch nicht unterstützt. Ein Tasmota-Gerät mit Passwort lässt sich über
urlschalten:http://<ip>/cm?user=admin&password=<passwort>&cmnd=Power%20On.
Zustand abfragen und von Hand testen¶
curl -s $WW/api/v1/switch/status
# Regel 0 von Hand einschalten (zählt nicht als Schaltvorgang der Regel)
curl -s -X POST $WW/api/v1/switch/test \
-H "Content-Type: application/json" \
-d '{"rule": 0, "action": "on"}'
# Nur die Verbindung zum Shelly prüfen
curl -s -X POST $WW/api/v1/switch/test \
-H "Content-Type: application/json" \
-d '{"rule": 0, "action": "check"}'
/switch/test antwortet sofort mit 202; das Ergebnis steht ein bis drei Sekunden später in /switch/status unter manual.
Felder in GET /api/v1/switch/status:
| Feld | Bedeutung |
|---|---|
sources |
Messwerte, die dieses Gerät kennt (flow, draw) |
volume |
true, wenn volume-Bedingungen möglich sind (Gas und Wasser) |
max_rules, max_conds |
Höchstzahl Regeln (4) und Bedingungen je Seite (4) |
time, weekday |
Uhrzeit des Geräts ("HH:MM") und Wochentag (1 = Montag); null, solange die Uhr nicht gestellt ist |
rules[].commanded |
Letzter eigener Befehl der Regel: on, off oder unknown |
rules[].actual, actual_s |
Zustand des Geräts (on, off, unknown) und vor wie vielen Sekunden er zuletzt gelesen bzw. gesetzt wurde |
rules[].gen, model |
Erkannter Shelly: Generation und Modell (bei tasmota und url 0 und leer) |
rules[].state_s |
Sekunden im aktuellen Zustand |
rules[].volume_since |
m³ seit dem letzten Wechsel |
rules[].on, rules[].off |
met: Seite gerade erfüllt. Je Bedingung in conds: met, wait_s (Sekunden, bis sie gilt; -1 = nicht absehbar) und value (aktueller Messwert bei value-Bedingungen, sonst null) |
rules[].last_action |
Letzter Schaltvorgang: cmd, auto (true = durch die Regel) und s (vor Sekunden) |
rules[].error |
Letzter Fehler: code (unreachable, auth, not_shelly, not_tasmota, bad_reply) und s |
rules[].manual |
Ergebnis von /switch/test: ok und s, oder pending |
Fehlermeldungen der Schaltregeln¶
Eine fehlerhafte Regel lehnt das Gerät mit 400 ab, z. B. {"success":false,"error":"switch.rules[1]: at most 4 conditions per side"}. Die Zahl in eckigen Klammern ist die Nummer der Regel, gezählt ab 0.
| Meldung | Ursache |
|---|---|
switch.rules: at most 4 rules |
Mehr als 4 Regeln |
rule needs at least one condition |
Beide Seiten leer |
match must be all or any |
match ist weder all noch any |
at most 4 conditions per side |
Mehr als 4 Bedingungen auf einer Seite |
condition type must be value, time, window, state or volume |
Unbekannter type |
source must be export, import, flow or draw |
Unbekannte source |
source not available on this device |
export oder import auf einem Gas- oder Wassergerät |
condition op must be above or below |
op fehlt oder ist falsch |
threshold must be a number |
value fehlt oder ist keine Zahl |
delay out of range (0-86400 s) |
delay negativ oder länger als 24 Stunden |
time must be HH:MM |
at, from oder to nicht im Format "HH:MM" |
window start and end must differ |
from und to gleich |
days must be a list of weekdays 1-7 |
days ist keine Liste oder enthält etwas anderes als 1–7 |
at least one weekday |
days ist leer |
duration out of range (1-604800 s) |
for fehlt, ist 0 oder länger als 7 Tage |
volume out of range |
volume mit 0 oder weniger |
switching on needs target.on_url |
Einschaltseite mit Bedingungen, aber leere on_url (entsprechend switching off needs target.off_url) |
target needs on_url or off_url |
Eigene URL ohne Adressen |
target.host must be an IP address or host name |
host leer, zu lang oder mit http://, Pfad oder Leerzeichen |
target.channel out of range (0-3) bzw. (0-7) |
Ausgang außerhalb 0–3 (Shelly) bzw. 0–7 (Tasmota) |
name too long (max 31) |
Name zu lang |
Mehrere Bereiche auf einmal¶
Alles in einer Anfrage spart Wartezeit (eine Änderung pro Sekunde) und ist atomar: Ist ein Wert ungültig, wird nichts gespeichert.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"device_name": "Keller",
"ledEnable": false,
"timezone": "Europe/Berlin",
"mqtt": { "enable": true, "host": "192.168.178.10", "port": 1883, "use_tls": false },
"modbus": { "enable": true }
}'
Atomar gilt für die Prüfungen
Abgelehnt wird vor dem Speichern bei: unbekanntem Feld auf oberster Ebene, zu langer SSID, ungültigen Werten unter gw, switch und ungültiger Zeitzone. Andere Werte (z. B. eine Portnummer außerhalb des Bereichs) werden nicht als Fehler gemeldet, sondern ignoriert oder begrenzt.
Aus Python¶
import requests
WW = "http://wattwaechter-XXXXXXXXXXXX.local"
HEADERS = {} # mit API-Schutz: {"Authorization": "Bearer DEIN_WRITE_TOKEN"}
r = requests.post(f"{WW}/api/v1/settings",
json={"mqtt": {"sendInterval": 30}},
headers=HEADERS, timeout=10)
if r.status_code == 429:
# zu schnell hintereinander: kurz warten und erneut senden
...
r.raise_for_status()
print(requests.get(f"{WW}/api/v1/settings", headers=HEADERS, timeout=10).json()["mqtt"])
Fehlermeldungen¶
| Status | Antwort (Beispiel) | Ursache |
|---|---|---|
400 |
{"error":"Missing JSON body"} |
Kein Body oder Content-Type nicht application/json |
400 |
{"error":"Invalid JSON"} |
Kein gültiges JSON (z. B. Komma am Ende) |
400 |
{"success":false,"error":"Unknown field: ledEnabled"} |
Tippfehler im Feldnamen auf oberster Ebene |
400 |
{"success":false,"error":"Modifying reboot counters is forbidden"} |
rebootCounter, rebootsTotal, rebootsAll sind nur lesbar |
400 |
{"success":false,"error":"SSID too long (max 32 chars): wifi.primary.ssid"} |
SSID länger als 32 Zeichen |
400 |
{"error":"Invalid timezone"} |
Zeitzone nicht in /api/v1/system/timezones |
400 |
{"success":false,"error":"gw.pulseVolume out of range (0.0001-1 m³)"} |
Wert außerhalb des erlaubten Bereichs |
400 |
{"success":false,"error":"switch.rules[0]: at most 4 conditions per side"} |
Fehlerhafte Schaltregel (Nummer in eckigen Klammern), siehe Fehlermeldungen der Schaltregeln |
401 |
API-Schutz an, Token fehlt oder falsch | |
403 |
{"success":false,"error":"To enable API authentication, you must provide the WRITE token. …"} |
API-Schutz einschalten ohne WRITE-Token |
403 |
{"error":"Write access from another web page needs the WRITE token"} |
Anfrage aus dem Browser von einer anderen Webseite ohne WRITE-Token, siehe Schreiben von anderen Webseiten |
413 |
{"error":"Request body too large. Max 2KB allowed."} |
Anfrage zu groß (ab Firmware 1.3: 8 KB) |
429 |
{"error":"Too many settings updates. Wait 1 second."} |
Weniger als 1 Sekunde seit der letzten Änderung (Retry-After: 1) |
429 |
{"error":"Settings update in progress. Try again."} |
Eine andere Änderung läuft gerade |
Interaktive API-Dokumentation¶
Die vollständige API-Spezifikation im OpenAPI-Format:
Hinweis
Die API-Dokumentation wird automatisch aus der Firmware-OpenAPI-Spezifikation generiert.