Schnittstelle für Heimautomatisierung

Endpunkt & Zugriff

Der jeweils aktuelle Messwert steht als JSON unter folgender Adresse bereit:

GET https://sensorwaterlevel.wasserstandpixendorf.workers.dev/retrieve/water_level
Authorization: Bearer cfut_X2DODWiX3Agvij0pozMksH4ey8RF114QQoA2GugOb07512cb

Der Zugriffstoken ist ein reiner Lesezugriff: Er kann ausschließlich den aktuellen Messwert abrufen und keinerlei Daten verändern. Er darf deshalb öffentlich geteilt und in Konfigurationen hinterlegt werden.

Antwort

{
  "water_level": -3.34,
  "timestamp": "2026-11-03T21:20:00.205103+01:00"
}

Der Dienst antwortet mit:

• 200 mit dem letzten Messwert (Normalfall),
• 401 wenn der Authorization-Header fehlt oder das Token falsch ist,
• 404 wenn für den Schlüssel noch kein Wert vorliegt (kommt in der Praxis nicht vor).

Hinweis am Rande: Die Antwort wird als text/plain ausgeliefert, enthält aber gültiges JSON. Sehr strikte Clients, die auf den Inhaltstyp application/json bestehen, müssen den Textkörper selbst als JSON dekodieren.

Abfrageintervall: alle 10 Minuten, nicht öfter

Der Sensor veröffentlicht alle 10 Minuten einen neuen Messwert. Ein häufigeres Abfragen liefert keine aktuelleren Daten, erzeugt aber unnötige Last — davon ist abzuraten. Empfohlenes Abfrageintervall: 10 Minuten (600 Sekunden) oder seltener.

Zwei Verhaltensweisen sind normal und keine Störung:

• Über Nacht ist der Sensor abgeschaltet (etwa 23 bis 6 Uhr). Der Wert bleibt in dieser Zeit unverändert stehen.
• Fällt die Verbindung zwischen Sensor und Cloud zeitweise aus, bleibt der zuletzt gemessene Wert abrufbar.

Werten Sie dafür in Ihrer Automatisierung den timestamp aus, nicht nur den Messwert — zum Beispiel mit einer Warnung, wenn der Wert älter als 30 Minuten ist (über Nacht entsprechend länger).

Beispiel: Home Assistant

Als REST-Sensor in der configuration.yaml (der Name des Sensors ist frei wählbar):

rest:
  - resource: "https://sensorwaterlevel.wasserstandpixendorf.workers.dev/retrieve/water_level"
    method: GET
    scan_interval: 600
    headers:
      Authorization: "Bearer cfut_X2DODWiX3Agvij0pozMksH4ey8RF114QQoA2GugOb07512cb"
    sensor:
      - name: "Water Level Pixendorf"
        value_template: "{{ value_json.water_level | float | round(2) }}"
        unit_of_measurement: "m"

Das scan_interval: 600 entspricht genau dem Veröffentlichungsintervall des Sensors — schneller zu pollen bringt nichts.

Weitere Systeme

Jedes System, das einen HTTP-GET-Abruf mit Kopfzeile beherrscht, kann die Schnittstelle nutzen — z. B. ioBroker, Node-RED, openHAB, FHEM oder ein Skript auf einem Raspberry Pi. Kurzer Test mit curl — alles in einer Zeile (ein mehrzeiliges Fortsetzungszeichen wie \ funktioniert nur in Linux-Shells, nicht in der Windows-Eingabeaufforderung; dort unbedingt als Einzelzeile einfügen, sonst läuft ein unvollständiger Befehl los):

curl -H "Authorization: Bearer cfut_X2DODWiX3Agvij0pozMksH4ey8RF114QQoA2GugOb07512cb" https://sensorwaterlevel.wasserstandpixendorf.workers.dev/retrieve/water_level

Erwartete Ausgabe: eine JSON-Zeile wie {"water_level": -3.32, "timestamp": "..."}. In der Windows-Eingabeaufforderung (cmd), Git Bash, Linux und macOS funktioniert diese Zeile unverändert.

PowerShell: Dort ist curl kein echtes curl, sondern ein Alias für Invoke-WebRequest — die curl-Parameter werden abgelehnt. Entweder das echte Programm explizit aufrufen:

curl.exe -H "Authorization: Bearer cfut_X2DODWiX3Agvij0pozMksH4ey8RF114QQoA2GugOb07512cb" https://sensorwaterlevel.wasserstandpixendorf.workers.dev/retrieve/water_level

… oder PowerShell-eigen mit automatisch geparstem JSON:

Invoke-RestMethod -Uri "https://sensorwaterlevel.wasserstandpixendorf.workers.dev/retrieve/water_level" -Headers @{ Authorization = "Bearer cfut_X2DODWiX3Agvij0pozMksH4ey8RF114QQoA2GugOb07512cb" }

Als serverseitiges JavaScript — in Node.js ab Version 18 als komplettes Skript (z. B. als abruf.mjs speichern, dann mit node abruf.mjs starten):

const res = await fetch(
  "https://sensorwaterlevel.wasserstandpixendorf.workers.dev/retrieve/water_level",
  { headers: { Authorization: "Bearer cfut_X2DODWiX3Agvij0pozMksH4ey8RF114QQoA2GugOb07512cb" } }
);
const data = await res.json();
console.log(data.water_level, "m unter Flurniveau, gemessen:", data.timestamp);

In Node-RED ist dafür kein Code nötig: ein http request-Knoten mit der URL und einer Authorization-Kopfzeile mit dem Token genügt. Node.js-Versionen älter als 18 haben kein eingebautes fetch.

Wichtig für Web-Entwickler: Der Dienst sendet keine CORS-Header. Ein Abruf direkt aus einer Webseite im Browser (clientseitiges JavaScript) wird deshalb blockiert. Web-Widgets müssen den Wert über ihr eigenes Backend abrufen (z. B. PHP auf dem eigenen Webserver).

Das Prinzip ist überall gleich: GET-Anfrage an die Adresse senden, den Authorization-Header mit dem Token mitschicken, water_level aus der JSON-Antwort lesen — und höchstens alle 10 Minuten abfragen.