Zum Inhalt

REST-API

Die WattWächter REST API ist unter http://wattwaechter-XXXXXXXXXXXX.local/api/v1/ erreichbar und bietet vollen Zugriff auf Gerätedaten, Einstellungen und Steuerungsfunktionen.

Aus Python? Dann mit der Bibliothek

Für eigene Python-Skripte gibt es die offizielle Bibliothek aio-wattwaechter. Sie übernimmt Anfragen, Token und das Auswerten der Antworten — siehe Python.

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:

  1. POST /api/v1/auth/tokens/generate — Generiert neue Tokens (noch nicht aktiv)
  2. 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

Emulation und Schalten (ab Firmware 1.3)

Methode Endpunkt Auth Beschreibung
GET /api/v1/emulation/status READ Emulation (Shelly und EcoTracker): ausgelieferte Werte und abfragende Geräte
GET /v1/json — EcoTracker-Schnittstelle: aktuelle Leistung und Zählerstände, nur mit eingeschaltetem EcoTracker-Modus
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 GET und 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 429 und Retry-After: 1. Mehrere Bereiche ändert man deshalb am besten in einer Anfrage.
  • Antwort: {"success": true, "applied": {…}}. Unter applied steht 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ßendes GET /api/v1/settings.
  • Passwörter (WLAN, Access Point, MQTT, NES-Zähler) liefert GET nie 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 400 ab (Unknown field: …) — ein Tippfehler fällt also auf. Unbekannte Unterfelder (z. B. mqtt.hots) werden dagegen stillschweigend ignoriert; prüfe nach dem Speichern mit GET.
  • 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_TOKEN oder als X-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 Hostname wattwaechter-…).
  • 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/ca hoch.

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 Stromzähler (WattWächter Plus)

Stromwandler-Faktor

Für Zähler hinter Stromwandlern (halbindirekte Messung): Der Faktor multipliziert Ströme, Leistungen und Zählerstände, z. B. 50 bei einem Wandler 250/5 A. Erlaubt sind 1 bis 10000; ungültige Werte setzen den Faktor auf 1 (Direktmessung). Gilt ab dem nächsten Telegramm, frühere Werte bleiben unverändert.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"ctRatio": 50}'

Glättung (Median-Filter)

Nur für Zähler mit OBIS-/D0-Protokoll: Anzahl der Messwerte, aus denen der Median gebildet wird (1 bis 9, Standard 5; 1 = keine Glättung). SML-Zähler ignorieren den Wert.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"medianFilterSize": 3}'

NES-Zähler (C12.18)

Zugangsdaten vom Messstellenbetreiber und das Abfrageverhalten — Details unter NES-Zähler.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "c1218": {
          "password": "PASSWORT-VOM-MSB",
          "userId": 2,
          "idleStart": "02:10",
          "idleSeconds": 480,
          "pollSeconds": 2,
          "logoffMinutes": 8
        }
      }'
Feld Bereich Bedeutung
password höchstens 20 Zeichen "" löscht das Passwort
userId 0–65535 Benutzer-ID für die Anmeldung (Standard 2)
idleStart "HH:MM" Beginn des täglichen Ruhefensters
idleSeconds 0–3600 Länge des Ruhefensters, 0 = keins
pollSeconds 1–300 Abfragetakt
logoffMinutes 0–1440 Sitzung nach so vielen Minuten neu aufbauen, 0 = offen lassen

Emulation: Shelly und EcoTracker (ab Firmware 1.3)

Manche Geräte können den WattWächter Plus nicht direkt auslesen, wohl aber einen EcoTracker oder einen Shelly Pro 3EM — zum Beispiel viele Batteriespeicher und Wechselrichter. Für sie spricht der WattWächter Plus deren Protokoll. Dann liest dein Gerät die Werte direkt von deinem Stromzähler, ein zusätzliches Messgerät im Verteiler ist nicht nötig. In der Weboberfläche: Einstellungen → Emulation.

Es gibt zwei Protokolle unter emulation. Beide sind ab Werk aus, beide dürfen gleichzeitig an sein. Kann dein Gerät beide, nimm EcoTracker.

Einstellung Protokoll Wofür So findet der Speicher den WattWächter
emulation.ecotracker EcoTracker Speicher, die den EcoTracker als Zähler anbieten, z. B. EcoFlow STREAM, Growatt NOAH, Hoymiles, Marstek per mDNS als ecotracker-… (_everhome._tcp), sonst IP-Adresse eintragen
emulation.shelly Shelly Pro 3EM Nur Speicher, die keinen anderen Zähler akzeptieren Marstek per UDP-Rundruf, andere per mDNS als shellypro3em-… (_shelly._tcp, _http._tcp), sonst IP-Adresse eintragen

Nicht möglich ist es bei Herstellern, die den Zähler über die Cloud koppeln: den EcoTracker über das everHome-Konto (z. B. Zendure), den Shelly über die Shelly-Cloud (z. B. Zendure, Anker, EcoFlow).

Der Hostname bleibt wattwaechter-….local, und der WattWächter ist weiter als _wattwaechter._tcp zu finden.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"emulation": {"shelly": {"enable": true}, "ecotracker": {"enable": true}}}'

Was gerade ausgeliefert wird und welche Geräte abfragen, zeigt GET /api/v1/emulation/status für beide Modi. Steht dort value.direction_unknown: true, meldet der Zähler die Leistung ohne Richtung (Bezug oder Einspeisung) — der WattWächter gibt sie dann nicht weiter, value.valid ist false. Das gilt auch, wenn er die Richtung an den Zählerständen abliest: Nahe 0 W, wo ein Speicher regelt, käme sie zu spät.

Mit eingeschaltetem EcoTracker-Modus beantwortet der WattWächter GET /v1/json auf Port 80 — ohne Token und außerhalb von /api/v1. Per mDNS meldet er sich als _everhome._tcp.

curl -s $WW/v1/json
{
  "power": -3127,
  "powerAvg": -3114,
  "agePower": 496,
  "powerPhase1": -1025,
  "powerPhase2": -1176,
  "powerPhase3": -926,
  "energyCounterOut": 5552927.8,
  "energyCounterIn": 1541618.4
}
Feld Einheit Bedeutung
power W Aktuelle Leistung: positiv = Bezug, negativ = Einspeisung
powerAvg W Mittel der letzten Minute
agePower ms Alter des Messwerts
powerPhase1 bis powerPhase3 W Leistung je Phase, nur wenn der Zähler gültige Phasenwerte liefert
energyCounterIn, energyCounterOut Wh Zählerstand Bezug (1.8.0) und Einspeisung (2.8.0) — in Wh, nicht kWh. Fehlt, wenn der Zähler den Wert nicht liefert
energyCounterInT1, energyCounterInT2 Wh Bezug Tarif 1 und 2, nur wenn der Zähler 1.8.1 und 1.8.2 liefert

Ohne aktuellen Messwert liefert /v1/json keine Werte (leeres JSON), wie ein echter EcoTracker. Ist der Modus aus, gibt es 404. Ändern lässt sich über diese Schnittstellen nichts.

Jackery

Speicher von Jackery funktionieren mit dem EcoTracker-Modus wahrscheinlich nicht. Sie halten die HTTP-Verbindung zum EcoTracker offen, der Webserver des WattWächters schließt aber jede Verbindung nach der Antwort.

„Shelly“ ist eine Marke der Shelly Group, „EcoTracker“ eine Marke der everHome GmbH. Der WattWächter ist kein Produkt dieser Unternehmen. Die Emulation nutzt die Kommunikationsprotokolle des EcoTracker und des Shelly Pro 3EM, damit Speicher und Wechselrichter, die nur diese Zähler unterstützen, die Messwerte lesen können.

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. 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, wenn match fehlt.
  • "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 export und import möglich. flow, draw und die Bedingung volume gibt es nur beim WattWächter Gas und Wasser; hier lehnt das Gerät sie mit 400 switch.rules[0]: source not available on this device bzw. volume is only available on gas and water devices ab. Welche Messwerte ein Gerät kennt, steht in GET /api/v1/switch/status unter sources.

Beispiele

Ein Heizstab geht über einen Shelly an, sobald 60 Sekunden lang mehr als 1500 W eingespeist werden — aber nur zwischen 9 und 17 Uhr. Er geht aus, wenn der Überschuss 60 Sekunden lang unter 100 W liegt oder er 2 Stunden gelaufen ist. Nach den 2 Stunden geht er erst wieder an, wenn die Einschaltseite einmal nicht galt und dann neu erfüllt ist.

Dazu ein Lastabwurf für die Sauna über eine Tasmota-Steckdose: Zieht das Haus 5 Sekunden lang mehr als 6000 W aus dem Netz, geht sie aus. Liegt der Bezug wieder 5 Minuten unter 3000 W, kommt sie zurück.

curl -s -X POST $WW/api/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "switch": {
          "rules": [
            {
              "name": "Heizstab",
              "enable": true,
              "target": { "type": "shelly", "host": "192.168.178.60", "channel": 0 },
              "on": {
                "match": "all",
                "conditions": [
                  { "type": "value", "source": "export", "op": "above", "value": 1500, "delay": 60 },
                  { "type": "window", "from": "09:00", "to": "17:00" }
                ]
              },
              "off": {
                "match": "any",
                "conditions": [
                  { "type": "value", "source": "export", "op": "below", "value": 100, "delay": 60 },
                  { "type": "state", "for": 7200 }
                ]
              }
            },
            {
              "name": "Sauna Lastabwurf",
              "enable": true,
              "target": { "type": "tasmota", "host": "192.168.178.61", "channel": 0 },
              "on":  { "match": "all", "conditions": [
                { "type": "value", "source": "import", "op": "below", "value": 3000, "delay": 300 }
              ] },
              "off": { "match": "all", "conditions": [
                { "type": "value", "source": "import", "op": "above", "value": 6000, "delay": 5 }
              ] }
            }
          ]
        }
      }'

Weitere Beispiele

Die folgenden Regeln setzt du einzeln oder zusammen in die Liste rules ein (höchstens 4 Regeln je Gerät).

Wärmepumpe mit Überschuss — Mindestlaufzeit, Name statt IP, zweiter Ausgang. Gibt die Wärmepumpe über Ausgang 2 eines Shelly Plus 2PM frei, wenn 5 Minuten lang mehr als 3000 W übrig sind. Die Ausschaltseite verknüpft mit "all": Aus geht sie erst, wenn der Überschuss 10 Minuten unter 500 W liegt und sie mindestens 30 Minuten gelaufen ist. Das schont den Verdichter.

{
  "name": "Wärmepumpe SG-Ready",
  "enable": true,
  "target": { "type": "shelly", "host": "shelly-waermepumpe.local", "channel": 1 },
  "on":  { "match": "all", "conditions": [
    { "type": "value", "source": "export", "op": "above", "value": 3000, "delay": 300 }
  ] },
  "off": { "match": "all", "conditions": [
    { "type": "value", "source": "export", "op": "below", "value": 500, "delay": 600 },
    { "type": "state", "for": 1800 }
  ] }
}

Nur einschalten — eigene URL ohne Ausschalt-Adresse. Startet die Spülmaschine über eine WLAN-Steckdose, die weder Shelly noch Tasmota ist und sich über eine HTTP-Adresse schalten lässt, sobald 2 Minuten lang mehr als 1000 W übrig sind. Die Ausschaltseite bleibt leer: Die Maschine beendet ihr Programm selbst, deshalb braucht die Regel keine off_url.

{
  "name": "Spülmaschine starten",
  "enable": true,
  "target": { "type": "url", "on_url": "http://192.168.178.62/relay?state=on", "off_url": "" },
  "on":  { "match": "all", "conditions": [
    { "type": "value", "source": "export", "op": "above", "value": 1000, "delay": 120 }
  ] },
  "off": { "match": "all", "conditions": [] }
}

Boiler im Nachttarif — Uhrzeit und Wochentage, Port, vorbereitet. Montag bis Freitag um 22:00 an, jeden Morgen um 06:00 aus. Am Wochenende bleibt er aus. Der Shelly ist mit Port angegeben, die Regel ist vorbereitet, aber noch ausgeschaltet ("enable": false).

{
  "name": "Boiler Nachttarif",
  "enable": false,
  "target": { "type": "shelly", "host": "192.168.178.63:8080", "channel": 0 },
  "on":  { "match": "all", "conditions": [
    { "type": "time", "at": "22:00", "days": [1, 2, 3, 4, 5] }
  ] },
  "off": { "match": "all", "conditions": [
    { "type": "time", "at": "06:00" }
  ] }
}

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 time und window nicht. Was das Gerät gerade für die Uhrzeit hält, steht in /switch/status unter time. 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.
  • state brauchen 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 (Messwert älter als 10 Sekunden). 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. Dasselbe gilt, solange der Zähler die Leistung ohne Richtung meldet (nur den Betrag) und der WattWächter sie auch an den Zählerständen noch nicht ablesen konnte: export und import gelten dann nicht, und GET /api/v1/switch/status meldet direction_unknown: true. Liefert der Zähler seltener einen Wert, etwa alle 35 Sekunden im Abfragemodus, richtet sich die Grenze nach seinem Takt: zwei Abstände plus 5 Sekunden.
  • 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 url schalten: 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 (export, import)
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 (nur Gas und Wasser, hier null)
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 flow oder draw auf dem WattWächter Plus
volume is only available on gas and water devices volume-Bedingung auf dem WattWächter Plus
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
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 c1218, 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"])

Für eigene Programme ist die Bibliothek aio-wattwaechter bequemer — siehe Python.

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":"c1218.password too long (max 20 chars)"} Wert außerhalb des erlaubten Bereichs
400 {"success":false,"error":"gw settings not supported on this device (not_gw)"} gw gibt es nur bei Gas/Wasser
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.