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.
Einschalten
- Öffne die Weboberfläche des Moduls und schalte unter Geräteeinstellungen den Expertenmodus ein.
- Öffne die Seite Experte, schalte in der Karte API den Schalter API aktivieren ein und klick auf Speichern.
- 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
| Adresse | Methode | Was sie tut |
|---|---|---|
/api/v1/info | GET | Softwareversion, Pumpenmodell, WLAN-Signal |
/api/v1/status | GET | alle aktuellen Werte: Schalter, Temperaturen, Energie, Wartung, Wasserwerte |
/api/v1/controls | POST | schalten und einstellen |
/api/v1/maintenance | POST | Wartung als erledigt eintragen |
/api/v1/waterquality | POST | gemessene Wasserwerte und Pflegemittel eintragen |
/api/v1/schedule | GET, POST, DELETE | Smart Schedule lesen, starten, abbrechen |
/api/v1/config/spa | GET, POST | SPA-Einstellungen (Strompreis, Intervalle, Tasten, Gastmodus ...) |
/api/v1/config/mqtt | GET, POST | MQTT-Einstellungen |
/api/v1/config/wifi | GET, POST | WLAN-Einstellungen (das Modul startet danach neu) |
/api/v1/config/hardware | GET, POST | Pumpen- und Displaytyp |
/api/v1/system/wifiscan | GET | WLAN-Netze in der Nähe |
/api/v1/system/restart | POST | Modul 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.
nullheiß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
| Code | Bedeutung |
|---|---|
| 200 | erledigt |
| 400 | ungültige Eingabe, der Text sagt, welches Feld |
| 401 | der API-Schlüssel fehlt, ist falsch oder wurde gelöscht |
| 403 | die API ist aus, oder der Schlüssel darf nur lesen |
| 409 | zu viele Befehle auf einmal, kurz warten |
| 423 | die Wärmeverlust-Messung läuft gerade |
| 429 | 5 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.