REST-API
Sensor direkt per HTTP abfragen und steuern, für Skripte und andere Systeme
Neben dem Webinterface hat jeder Eco-Sensor eine REST-API. Damit lesen Sie Messwerte aus und schalten oder verstellen Dinge direkt über die IP-Adresse des Sensors, ohne Cloud und ohne Home Assistant. Jedes System, das HTTP-Anfragen senden kann, kommt damit zurecht: Skripte (curl, Python), Node-RED, ioBroker, openHAB, FHEM und viele andere.
Die API gehört zu ESPhome und ist in jedem Eco-Sensor eingebaut, es gibt nichts einzuschalten. Auch die Webseite des Sensors benutzt sie.
Welche Schnittstelle wofür?
| REST-API | Home-Assistant-API | ecosensors.cloud | |
|---|---|---|---|
| Wofür | eigene Skripte und beliebige Systeme | Home Assistant | Dashboard, Verläufe, Benachrichtigungen |
| Reichweite | nur im lokalen Netz | nur im lokalen Netz | von überall |
| Absicherung | Zugangspasswort, unverschlüsselt (http) | eigener Schlüssel, verschlüsselt | Ihr Konto |
Voraussetzungen
- Das System, das den Sensor abfragt, befindet sich im selben Netzwerk wie der Sensor.
- Sie kennen die Adresse des Sensors (Name oder IP-Adresse, siehe Sensor finden). Richten Sie im Router eine feste IP-Adresse für den Sensor ein, sonst läuft Ihre Anbindung ins Leere, sobald der Router eine neue Adresse vergibt. In den Beispielen unten steht
192.168.1.95. - Die Zugangsdaten sind dieselben wie am Webinterface: Benutzer
adminund das Passwort des Sensors. Die API verlangt eine HTTP-Anmeldung (bei ESPhome „Digest“). Beim EcoMBR1 ist ab Werk kein Passwort gesetzt, dann braucht auch die API keines: Setzen Sie trotzdem ein Zugangspasswort.
So ist eine Anfrage aufgebaut
Jeder Wert und jede Bedienmöglichkeit eines Sensors ist eine Entität mit einer festen Adresse:
http://<Adresse>/<Typ>/<Name>
Der Name steht genau so da, wie ihn der Sensor kennt (englisch, z. B. Grid Frequency). Leerzeichen schreiben Sie als %20, also Grid%20Frequency. Welche Entitäten Ihr Sensor hat, zeigt der Ereignisstrom. Der Typ sagt, was für eine Entität es ist:
| Typ | Bedeutung | Beispiel | value in der Antwort |
|---|---|---|---|
sensor |
Messwert | Grid Frequency | Zahl |
binary_sensor |
Zustand mit zwei Werten | Relay Override | true / false |
text_sensor |
Text | Tibber Price Level | Text |
switch |
Schalter | Relay 1 | true / false |
number |
einstellbarer Zahlenwert | Grid Relay ON | Zahl als Text, z. B. "-500" |
button |
löst eine Aktion aus | Restart | (keine Antwort mit Wert) |
Welche Entitäten es gibt, hängt vom Sensor ab; die Beispiele hier stammen vom EcoMBR1.
Werte lesen
Ein Wert wird mit einer einfachen GET-Anfrage gelesen, im Browser genauso wie mit curl:
curl http://192.168.1.95/sensor/Grid%20Frequency
{"id":"sensor/Grid Frequency","value":50.01,"state":"50.0 Hz"}
value ist der Wert zum Weiterverarbeiten, state derselbe Wert als Text mit Einheit, wie ihn das Webinterface zeigt. Weitere Beispiele:
curl http://192.168.1.95/switch/Relay%201
# {"id":"switch/Relay 1","value":false,"state":"OFF"}
curl http://192.168.1.95/text_sensor/Tibber%20Price%20Level
# {"id":"text_sensor/Tibber Price Level","value":"EXPENSIVE","state":"EXPENSIVE"}
Ist ein Zugangspasswort gesetzt, geben Sie die Zugangsdaten mit. --anyauth lässt curl das Anmeldeverfahren selbst wählen:
curl --anyauth -u admin:IhrPasswort http://192.168.1.95/sensor/Grid%20Frequency
Schalten und einstellen
Alles, was etwas verändert, ist eine POST-Anfrage. Die Aktion steht hinten an der Adresse:
# Schalter: ein, aus, umschalten
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/turn_on
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/turn_off
curl -X POST -d '' http://192.168.1.95/switch/Relay%201/toggle
# Zahlenwert setzen (hier: Einschaltpunkt der Netzleistungs-Steuerung)
curl -X POST -d '' "http://192.168.1.95/number/Grid%20Relay%20ON/set?value=-500"
# Knopf drücken (hier: Neustart)
curl -X POST -d '' http://192.168.1.95/button/Restart/press
Die Antwort ist 200 ohne Inhalt; den neuen Zustand lesen Sie wie oben mit GET. Der Zusatz -d '' ist wichtig: Eine POST-Anfrage ohne Inhalt und ohne Längenangabe lehnt der Sensor mit dem Fehler 411 ab. Andere Werkzeuge brauchen dasselbe: eine leere Anfrage mit Content-Length: 0.
Beim EcoMBR1 lässt sich das Relais nur von Hand schalten, solange keine Steuerung (Netzleistung, Tibber) eingeschaltet ist, siehe Relais einstellen. Eine eingeschaltete Steuerung bestimmt das Relais selbst.
Alle Werte und Live-Aktualisierung
Eine Liste aller Entitäten als eigene Adresse gibt es nicht. Dafür liefert der Sensor unter /events einen Ereignisstrom (Server-Sent Events): Gleich nach dem Verbinden schickt er alle Entitäten mit ihrem aktuellen Wert, danach jede Änderung sofort.
curl -N http://192.168.1.95/events
event: state
data: {"id":"sensor/Phase A Voltage","domain":"sensor","name":"Phase A Voltage","value":234,"state":"234.0 V","uom":"V", ...}
Das Feld id ist genau der Teil, den Sie hinter die Adresse des Sensors schreiben. So finden Sie heraus, welche Entitäten es gibt, und bekommen Änderungen ohne ständiges Abfragen. Wer nur gelegentlich einen Wert braucht, fragt einfach regelmäßig per GET ab.
Ein Sensor ist ein kleiner Mikrocontroller und verträgt nur wenige gleichzeitige Verbindungen. Fragen Sie nicht schneller als alle paar Sekunden ab, und schließen Sie einen Ereignisstrom wieder, wenn Sie ihn nicht mehr brauchen.
Beispiele für eigene Anwendungen
Python (mit der Bibliothek requests):
import requests
from requests.auth import HTTPDigestAuth
auth = HTTPDigestAuth("admin", "IhrPasswort") # ohne Passwort am Sensor weglassen
base = "http://192.168.1.95"
leistung = requests.get(f"{base}/sensor/Grid%20Active%20Power", auth=auth, timeout=5).json()["value"]
print(leistung, "W")
if leistung < -500: # Einspeisung: Relais ein
requests.post(f"{base}/switch/Relay%201/turn_on", data="", auth=auth, timeout=5)
Node-RED, ioBroker, openHAB und ähnliche Systeme: Sie brauchen einen Baustein, der HTTP-Anfragen sendet (in Node-RED der Knoten http request, in anderen Systemen heißt er ähnlich), mit Digest-Anmeldung, falls ein Passwort gesetzt ist. Für Werte tragen Sie die GET-Adresse ein und lesen das Feld value aus der JSON-Antwort. Zum Schalten senden Sie eine POST-Anfrage an die Adresse mit turn_on, turn_off oder toggle.
Sicherheit
Ohne Zugangspasswort kann jeder in Ihrem WLAN Werte lesen und den Sensor bedienen (z. B. das Relais schalten). Die Verbindung ist nicht verschlüsselt (http): Das Passwort geht zwar nicht im Klartext über das Netz, ein gezielter Angreifer im selben Netzwerk wird dadurch aber nicht abgehalten.
- Machen Sie die API nicht aus dem Internet erreichbar (keine Portweiterleitung im Router). Für den Zugriff von unterwegs nutzen Sie das Dashboard auf ecosensors.cloud oder ein VPN in Ihr Heimnetz.
- Legen Sie das Passwort nicht im Klartext in Skripten ab, die Sie weitergeben.
- Die Home-Assistant-API ist eine eigene, verschlüsselte Schnittstelle, siehe Home Assistant.