Zum Inhalt

WifiWhirl per Webhooks steuern

Ab der Version 1.1.3 deines WifiWhirl-Moduls kannst du viele Funktionen bequem über Webhooks (HTTP-Aufrufe) fernsteuern. Dies ermöglicht die Integration in viele Smart-Home-Systeme, eigene Skripte oder den direkten Aufruf über einen Webbrowser.

Grundlagen

Webhooks sind eine einfache Methode, mit der Anwendungen über das HTTP-Protokoll miteinander kommunizieren können. Im Fall des WifiWhirl-Moduls sendest du eine speziell formatierte URL an das Modul, um eine Aktion auszulösen.

Wichtige Hinweise vorab:

  • Ersetze in allen Beispiel-URLs wifiwhirl.local durch den Hostnamen oder die lokale IP-Adresse deines WifiWhirl-Moduls im Netzwerk. Den Hostnamen (oft wifiwhirl-xxxxxx.local) oder die IP-Adresse findest du z.B. in der Weboberfläche deines Routers oder beim Start des Moduls auf dem Pumpendisplay.
  • Alle Webhook-Aufrufe erfolgen über die HTTP GET-Methode, sofern nicht anders angegeben.
  • Die zu sendenden Befehle werden als JSON-Objekt im send-Parameter der URL übergeben. Die Struktur ist dabei immer {"CMD":<Befehlsnummer>,"VALUE":<Wert>}.

Verfügbare Webhook-Befehle

Die folgende Tabelle listet alle verfügbaren Befehle auf, die du per Webhook an dein WifiWhirl-Modul senden kannst:

Funktion CMD VALUE Typ VALUE Beispiele & Hinweise Beispiel-URL (mit wifiwhirl.local)
Pumpe Ein/Aus 4 Boolean true (ein), false (aus) http://wifiwhirl.local/hook/?send={"CMD":4,"VALUE":true}
Heizung & Pumpe Ein/Aus 3 Boolean true (ein), false (aus) http://wifiwhirl.local/hook/?send={"CMD":3,"VALUE":true}
AirJet-Düsen Ein/Aus 2 Boolean true (ein), false (aus) http://wifiwhirl.local/hook/?send={"CMD":2,"VALUE":true}
HydroJet-Düsen Ein/Aus 11 Boolean true (ein), false (aus) http://wifiwhirl.local/hook/?send={"CMD":11,"VALUE":true}
Ziel-Temperatur setzen 0 Unsigned Integer Ganzzahl, z.B. 30 für 30°C http://wifiwhirl.local/hook/?send={"CMD":0,"VALUE":30}
Display-Helligkeit setzen 12 Unsigned Integer 0 (aus) bis 8 (max. Helligkeit) http://wifiwhirl.local/hook/?send={"CMD":12,"VALUE":8}
Umgebungstemp. setzen (°C) 15 Integer Ganzzahl in °C, z.B. 20 für 20°C (-40 bis 60) http://wifiwhirl.local/hook/?send={"CMD":15,"VALUE":20}
Tasten aktivieren/deaktivieren 26 Boolean true (aktivieren), false (deaktivieren) http://wifiwhirl.local/hook/?send={"CMD":26,"VALUE":false}
pH-Wert setzen 27 Unsigned Integer Wert = pH × 10, z.B. 72 für pH 7,2 http://wifiwhirl.local/hook/?send={"CMD":27,"VALUE":72}
Chlorgehalt setzen 28 Unsigned Integer Wert = Cl × 10 in mg/L, z.B. 15 für 1,5 mg/L http://wifiwhirl.local/hook/?send={"CMD":28,"VALUE":15}
Cyanursäure (CYA) setzen 29 Unsigned Integer Wert = CYA × 10 in mg/L, z.B. 300 für 30,0 mg/L http://wifiwhirl.local/hook/?send={"CMD":29,"VALUE":300}
Alkalität setzen 30 Unsigned Integer Wert in mg/L, z.B. 100 für 100 mg/L http://wifiwhirl.local/hook/?send={"CMD":30,"VALUE":100}


Erweiterte Parameter für /hook/

Neben CMD und VALUE unterstützt der /hook/-Endpunkt optional weitere Parameter im JSON-Objekt:

Parameter Typ Beschreibung
XTIME Integer Unix-Timestamp, wann der Befehl ausgeführt werden soll. Standardmäßig sofort (jetzt).
INTERVAL Integer Wiederholungsintervall in Sekunden. 0 = einmalig.
FORCE Boolean true = Sicherheitsprüfungen umgehen (z.B. Pumpe ausschalten wenn Heizung läuft). Vorsichtig einsetzen.

Detaillierte Erklärungen zu den Parametern

  • CMD (Command ID): Eine eindeutige Nummer, die den auszuführenden Befehl identifiziert (siehe Tabelle oben).
  • VALUE (Wert): Der Wert, der für den jeweiligen Befehl gesetzt werden soll.
    • Boolean: Akzeptiert true (für einschalten/aktivieren) oder false (für ausschalten/deaktivieren).
    • Unsigned Integer: Akzeptiert positive Ganzzahlen (inkl. 0).
    • Integer: Akzeptiert positive und negative Ganzzahlen.

Anwendungsbeispiel mit curl

Du kannst Webhooks einfach über die Kommandozeile mit einem Tool wie curl testen. Um beispielsweise die Pumpe einzuschalten (angenommen, dein Modul ist unter 192.168.1.100 erreichbar):

curl "http://192.168.1.100/hook/?send={\"CMD\":4,\"VALUE\":true}"

Beachte die notwendige Maskierung der Anführungszeichen (\") innerhalb des JSON-Strings, wenn du curl in einer typischen Shell-Umgebung verwendest.

Statusabfrage per /getstates/

Seit Version 1.1.6 gibt es einen Endpunkt, mit dem du den aktuellen Ein-/Aus-Status aller wichtigen Komponenten deines WifiWhirl-Moduls auslesen kannst.

  • Endpunkt: /getstates/
  • Methode: HTTP GET
  • Parameter: Keine

Antwortformat

Beispiel-Abfrage: 

curl "http://192.168.1.100/getstates/"

Beispiel-Antwort: 

{"pump":true,"heater":false,"bubbles":false,"jets":false,"power":true,"lock":true}

Bedeutung der Schlüssel:

Schlüssel Typ Beschreibung
pump Boolean Status der Filterpumpe (true = an, false = aus)
heater Boolean Status der Heizung (true = an, false = aus)
bubbles Boolean Status der AirJet-Düsen (true = an, false = aus)
jets Boolean Status der HydroJet-Düsen (true = an, false = aus)
power Boolean Gesamtstatus des Systems (true = an, false = aus)
lock Boolean Status der Tastensperre (true = aktiv, false = inaktiv)

Temperaturabfrage per /gettemps/

Seit Version 1.2.0 gibt es einen Endpunkt für alle Temperaturwerte. Die Antwort enthält immer beide Einheiten (Celsius und Fahrenheit), unabhängig von der Geräteeinstellung.

  • Endpunkt: /gettemps/
  • Methode: HTTP GET
  • Parameter: Optional - Feldfilterung über Query-Parameter

Antwortformat

Beispiel-Abfrage (alle Felder): 

curl "http://192.168.1.100/gettemps/"

Beispiel-Antwort: 

{"currentC":38,"currentF":100,"targetC":40,"targetF":104,"ambientC":20,"ambientF":68,"unit":"C"}

Bedeutung der Schlüssel:

Schlüssel Typ Beschreibung
currentC Number Aktuelle Wassertemperatur in °C
currentF Number Aktuelle Wassertemperatur in °F
targetC Number Zieltemperatur in °C
targetF Number Zieltemperatur in °F
ambientC Number Umgebungstemperatur in °C
ambientF Number Umgebungstemperatur in °F
unit String Einstellung am Gerät: "C" (Celsius) oder "F" (Fahrenheit)

Feldfilterung

Um Bandbreite zu sparen, kannst du gezielt nur bestimmte Felder anfordern, indem du ihre Namen als Query-Parameter übergibst:

# Nur aktuelle Temperatur in Celsius
curl "http://192.168.1.100/gettemps/?currentC"

# Aktuelle und Zieltemperatur in Celsius
curl "http://192.168.1.100/gettemps/?currentC&targetC"

Ohne Parameter werden immer alle Felder zurückgegeben.

HTTP Polling Fallback

Seit Version 1.2.0 stehen zwei zusätzliche Endpunkte als Fallback für Browser bereit, die Probleme mit WebSocket-Verbindungen haben (z.B. bestimmte iOS-Safari-Versionen). Diese Endpunkte werden normalerweise vom Frontend intern genutzt und können in der Web-Konfiguration aktiviert werden.

GET /getpolldata/

Gibt den vollständigen aktuellen Gerätezustand als JSON-Array zurück (äquivalent zu den WebSocket-Nachrichten STATES, TIMES und OTHER).

  • Endpunkt: /getpolldata/
  • Methode: HTTP GET
  • Parameter: Keine

POST /sendcommand/

Sendet einen Steuerbefehl an das Modul. Akzeptiert dasselbe JSON-Format wie die WebSocket-Schnittstelle.

  • Endpunkt: /sendcommand/
  • Methode: HTTP POST
  • Body: JSON-Objekt mit den Feldern CMD, VALUE, XTIME, INTERVAL, TXT, FORCE

Beispiel: 

curl -X POST "http://192.168.1.100/sendcommand/" \
     -H "Content-Type: application/json" \
     -d '{"CMD":4,"VALUE":true}'

Wichtige Sicherheitshinweise

  • Keine Authentifizierung: Die Webhook-Schnittstelle des WifiWhirl-Moduls verfügt über keine eingebaute Authentifizierung oder Verschlüsselung (HTTPS). Jeder, der Zugriff auf dein lokales Netzwerk hat und die IP-Adresse/den Hostnamen deines Moduls kennt, kann diese Webhooks auslösen.
  • Netzwerksicherheit: Stelle sicher, dass dein WLAN angemessen gesichert ist (z.B. durch WPA2 Verschlüsselung und ein starkes Passwort).
  • Kein Fernzugriff ohne VPN: Setze das Modul nicht direkt dem Internet aus (z.B. durch Port-Weiterleitungen im Router). Wenn du von außerhalb deines Heimnetzwerks auf die Webhooks zugreifen möchtest, verwende eine sichere VPN-Verbindung zu deinem Heimnetzwerk.

Bei Fragen oder Problemen mit den Webhooks, schaue bitte auch in die FAQ oder erstelle ein Issue im WifiWhirl GitHub Repository.