Zum Hauptinhalt springen

WifiWhirl® API

Die Schnittstelle deines Moduls für Smart-Home-Systeme und eigene Skripte: alle Werte lesen, steuern, planen. Ab Software 2.1.0.

Über die API (Programmierschnittstelle) sprechen andere Programme direkt mit deinem Modul, zum Beispiel der ioBroker-Adapter oder ein eigenes Skript. Sie können alle Werte lesen, den Whirlpool schalten, einen Smart Schedule planen und Einstellungen ändern.

Die API funktioniert nur mit einem API-Schlüssel und nur in deinem Heimnetz. Du brauchst sie nur, wenn ein Programm sie verlangt. Für einfache Schaltbefehle reichen die Webhooks.

IP-Adresse (z. B. 192.168.178.42) oder vollständiger Hostname (xxxxxx ist die Seriennummer von deinem Aufkleber). Du findest beides in der Weboberfläche unter Netzwerkkonfiguration. Dein Browser merkt sie sich für alle Seiten.Bleibt nur in diesem Browser-Tab und ist weg, sobald du ihn schließt. Er wird nie an WifiWhirl oder an diese Website geschickt, sondern nur in die Beispiele eingesetzt.

Einschalten​

  1. Öffne die Weboberfläche des Moduls und schalte unter Geräteeinstellungen den Expertenmodus ein.
  2. Öffne die Seite Experte, schalte in der Karte API den Schalter API aktivieren ein und klick auf Speichern.
  3. Leg darunter einen API-Schlüssel an: Gib ihm einen Namen, zum Beispiel ioBroker, wähl Nur lesen oder Lesen und steuern und klick auf Schlüssel erzeugen. Kopier den Schlüssel sofort, er wird nur dieses eine Mal angezeigt.

Du kannst bis zu 4 Schlüssel anlegen, am besten einen pro Programm. Brauchst du einen nicht mehr, löschst du ihn. Programme mit den anderen Schlüsseln laufen weiter. Das Modul speichert die Schlüssel nur verschlüsselt (als Hash), deshalb kann es einen verlorenen Schlüssel nicht noch einmal anzeigen. Leg dann einfach einen neuen an.


Erster Test​

Öffne im Browser http://192.168.178.42/api/v1/info. Ohne Schlüssel siehst du die Softwareversion und ob die API eingeschaltet ist.

Mit Schlüssel im Terminal (trag oben Adresse und Schlüssel ein, dann stimmen alle Beispiele):

curl -H 'Authorization: Bearer DEIN-API-SCHLUESSEL' http://192.168.178.42/api/v1/status

Alle Adressen​

AdresseMethodeWas sie tut
/api/v1/infoGETSoftwareversion, Pumpenmodell, WLAN-Signal
/api/v1/statusGETalle aktuellen Werte: Schalter, Temperaturen, Energie, Wartung, Wasserwerte
/api/v1/controlsPOSTschalten und einstellen
/api/v1/maintenancePOSTWartung als erledigt eintragen
/api/v1/waterqualityPOSTgemessene Wasserwerte und Pflegemittel eintragen
/api/v1/scheduleGET, POST, DELETESmart Schedule lesen, starten, abbrechen
/api/v1/config/spaGET, POSTSPA-Einstellungen (Strompreis, Intervalle, Tasten, Gastmodus ...)
/api/v1/config/mqttGET, POSTMQTT-Einstellungen
/api/v1/config/wifiGET, POSTWLAN-Einstellungen (das Modul startet danach neu)
/api/v1/config/hardwareGET, POSTPumpen- und Displaytyp
/api/v1/system/wifiscanGETWLAN-Netze in der Nähe
/api/v1/system/restartPOSTModul neu starten

Die vollständige Beschreibung aller Felder zum Herunterladen (OpenAPI, z. B. für Postman oder Swagger): wifiwhirl-api-v1.yaml

Gut zu wissen​

  • Temperaturen sind immer in °C, auch wenn deine Pumpe °F anzeigt.
  • Zeitangaben sind Unix-Zeit in Sekunden. null heißt „noch nie“.
  • Du schickst nur die Felder, die du ändern willst. Ist eins davon ungültig, ändert sich gar nichts.

Schalten​

curl -H 'Authorization: Bearer DEIN-API-SCHLUESSEL' -H 'Content-Type: application/json' \
-d '{"heater": true, "targetTemperature": 38}' \
http://192.168.178.42/api/v1/controls

Mögliche Felder: power, lock, pump, heater, bubbles, jets (jeweils true/false), targetTemperature (20-40), unit ("C"/"F"), brightness (0-8). Die Heizung schaltet die Filterpumpe automatisch mit ein.

Smart Schedule​

# am 24.12.2026 um 19 Uhr 38 °C, danach läuft nur die Filterpumpe weiter
curl -H 'Authorization: Bearer DEIN-API-SCHLUESSEL' -H 'Content-Type: application/json' \
-d '{"targetTime": 1798135200, "targetTemperature": 38, "afterTarget": "pump"}' \
http://192.168.178.42/api/v1/schedule

# abbrechen
curl -H 'Authorization: Bearer DEIN-API-SCHLUESSEL' -X DELETE http://192.168.178.42/api/v1/schedule

afterTarget: "off" alles aus, "pump" nur die Filterpumpe läuft weiter, "heater" die Temperatur wird gehalten.

Wartung und Wasserwerte​

curl -H 'Authorization: Bearer DEIN-API-SCHLUESSEL' -H 'Content-Type: application/json' \
-d '{"done": ["filterCleaned"]}' http://192.168.178.42/api/v1/maintenance

curl -H 'Authorization: Bearer DEIN-API-SCHLUESSEL' -H 'Content-Type: application/json' \
-d '{"ph": 7.4, "chlorine": 0.8, "dose": {"ph": -40}}' \
http://192.168.178.42/api/v1/waterquality

Antworten​

CodeBedeutung
200erledigt
400ungültige Eingabe, der Text sagt, welches Feld
401der API-Schlüssel fehlt, ist falsch oder wurde gelöscht
403die API ist aus, oder der Schlüssel darf nur lesen
409zu viele Befehle auf einmal, kurz warten
423die Wärmeverlust-Messung läuft gerade
4295 falsche Schlüssel, 30 Sekunden warten

Sicherheit​

  • Das Modul spricht nur unverschlüsseltes HTTP. Mach es nicht aus dem Internet erreichbar, zum Beispiel über eine Portfreigabe im Router. Für unterwegs gibt es die PoolLink Cloud.
  • Gib jedem Programm einen eigenen Schlüssel und nur so viele Rechte wie nötig. Ein Dashboard braucht nur Nur lesen.
  • Schlüssel, Login und OTA-Passwort lassen sich nur in der Weboberfläche ändern, nicht über die API.