REST/JSON - Lese-/Schreibzugriff
Über die REST/JSON-Schnittstelle fragen Sie die Werte Ihres SOLIO mit einfachen HTTP-Aufrufen ab, zum Beispiel aus einer Smart-Home-Zentrale, einem eigenen Skript oder einer Tabellenkalkulation. Mit dem Schreibzugriff geben Sie außerdem die Leistung Ihres Speichers vor.
Diese Seite richtet sich an technisch versierte Anwender, Installateure und Entwickler. Für die normale Nutzung Ihres SOLIO brauchen Sie die Schnittstelle nicht.
Wofür brauche ich das?
REST/JSON ist der übliche Weg, wie Webdienste und Programme Daten austauschen. Die Antworten kommen im Textformat JSON und lassen sich in fast jeder Programmiersprache leicht weiterverarbeiten. Typische Einsätze:
- Eine Smart-Home-Zentrale zeigt den Ladezustand des Speichers an oder schaltet Geräte abhängig vom Solarüberschuss.
- Ein eigenes Skript schreibt Messwerte regelmäßig in eine Datenbank oder Tabelle.
- Ein externes System gibt die Lade- oder Entladeleistung des Speichers vor (Schreibzugriff).
Die Schnittstelle funktioniert nur im lokalen Netzwerk. Für den Zugriff über das Internet gibt es die Customer API.
Werte abfragen. Gehört zum Standardumfang.
Leistung des Speichers vorgeben. Wird bei Bedarf freigeschaltet.
Voraussetzungen
- Das abfragende Gerät ist im selben Netzwerk wie das SOLIO und erreicht dessen IP-Adresse direkt.
- Sie kennen die IP-Adresse des SOLIO, zum Beispiel aus der Geräteliste Ihres Routers.
- Sie kennen das Passwort für die Anmeldung am SOLIO. Ab Werk ist das
userfür den Gastzugang undownerfür den Eigentümerzugang. Haben Sie die Passwörter geändert, gelten Ihre eigenen. Mehr dazu unter Passwort am SOLIO ändern.
Lesezugriff
Der Lesezugriff gehört zum Standardumfang. Im App Center ist dafür die App REST/JSON lesend installiert.
Adresse und Anmeldung
Jeder Messwert hat eine Adresse aus Komponente und Kanal, zum Beispiel _sum/EssSoc für den Ladezustand. Abgefragt wird er so:
http://<IP>/rest/channel/<Komponente>/<Kanal>
Für ein SOLIO mit der Adresse 192.168.178.30 lautet der Aufruf für den Ladezustand also:
http://192.168.178.30/rest/channel/_sum/EssSoc
- Methode:
GET - Anmeldung: HTTP Basic Authentication. Als Benutzernamen können Sie
guestbzw.owneroder einen beliebigen Platzhalter wiexverwenden, entscheidend ist das Passwort. - Port:
80, Sie müssen ihn nicht angeben.
Browser senden Zugangsdaten aus der Adresszeile in der Regel nicht mit, deshalb erhalten Sie dort meist eine Fehlermeldung. Nutzen Sie für Tests ein Werkzeug wie curl, Python oder einen API-Client, der die Zugangsdaten als Authorization-Header überträgt.
Die Antwort
{"address":"_sum/EssSoc","type":"INTEGER","accessMode":"RO","text":"","unit":"%","value":99}
| Feld | Bedeutung |
|---|---|
address | Adresse des Messwerts |
type | Datentyp, z. B. INTEGER |
accessMode | RO nur lesbar, RW les- und schreibbar, WO nur schreibbar |
unit | Einheit |
value | Der aktuelle Wert, hier 99 % |
Für Komponente und Kanal können Sie auch Suchmuster (reguläre Ausdrücke) verwenden. _sum/.* liefert zum Beispiel alle Summenwerte auf einmal, die Antwort ist dann eine Liste.
Wichtige Messwerte
Lesen können Sie grundsätzlich alle Kanäle Ihres SOLIO. Die wichtigsten Summenwerte:
| Adresse | Beschreibung | Einheit |
|---|---|---|
_sum/State | Zustand der Anlage (0: Ok, 1: Info, 2: Warning, 3: Fault) | |
_sum/EssSoc | Ladezustand des Speichers | % |
_sum/EssActivePower | Speicherleistung, negativ = Laden, positiv = Entladen | W |
_sum/GridActivePower | Netzleistung, negativ = Einspeisung, positiv = Bezug | W |
_sum/ProductionActivePower | Gesamte Erzeugung | W |
_sum/ProductionAcActivePower | Erzeugung AC | W |
_sum/ProductionDcActualPower | Erzeugung DC | W |
_sum/ConsumptionActivePower | Verbrauch | W |
_sum/EssActiveChargeEnergy | Energie Speicherbeladung | Wh |
_sum/EssActiveDischargeEnergy | Energie Speicherentladung | Wh |
_sum/GridBuyActiveEnergy | Energie Netzbezug | Wh |
_sum/GridSellActiveEnergy | Energie Netzeinspeisung | Wh |
_sum/ProductionActiveEnergy | Energie Erzeugung | Wh |
_sum/ConsumptionActiveEnergy | Energie Verbrauch | Wh |
_sum/EssActivePowerL1 … L3 | Speicherleistung je Phase | W |
_sum/GridActivePowerL1 … L3 | Netzleistung je Phase | W |
_sum/ProductionAcActivePowerL1 … L3 | Erzeugung AC je Phase | W |
_sum/ConsumptionActivePowerL1 … L3 | Verbrauch je Phase | W |
Beispiel mit curl
curl ist unter Windows 10 und 11, macOS und Linux bereits installiert. Der Aufruf ist überall gleich:
curl -u x:user http://192.168.178.30/rest/channel/_sum/EssSoc
Die Antwort erscheint direkt im Fenster. Der Ladezustand steht im Feld value.
Beispiel mit Python
Mit der Bibliothek requests:
import requests
url = "http://192.168.178.30/rest/channel/_sum/EssSoc"
response = requests.get(url, auth=("x", "user"))
response.raise_for_status()
print(response.json()["value"]) # z. B. 99
Beispiel mit einem API-Client
In einem API-Client wie dem Chrome-Plugin Talend API Tester tragen Sie die Adresse ein und fügen einen Authorization-Header mit Basic Authentication hinzu.
Schreibzugriff
Mit dem Schreibzugriff geben Sie die Wirk- und Blindleistung des Speichers vor. Er gehört nicht zum Standardumfang, kann aber jederzeit über die App REST/JSON Schreibzugriff freigeschaltet werden. Sprechen Sie uns dazu an.
- Methode:
POSTan dieselbe Adresse wie beim Lesen, zum Beispielhttp://<IP>/rest/channel/ess0/SetActivePowerEquals - Inhalt: JSON mit dem Feld
value, zum Beispiel{"value": 5000} - Anmeldung: mindestens mit dem Eigentümer-Passwort (ab Werk
owner). Mit dem Gastzugang ist Schreiben nicht möglich. - Vorzeichen: Negative Werte laden den Speicher, positive Werte entladen ihn.
Timeout
Eine Vorgabe gilt nur für die Dauer des Timeouts, standardmäßig 60 Sekunden. Ein neuer Wert ersetzt den alten. Kommt innerhalb dieser Zeit keine neue Vorgabe, übernimmt wieder die normale Regelung Ihres SOLIO, zum Beispiel die Eigenverbrauchsoptimierung. Senden Sie den Wert also regelmäßig neu.
Beschreibbare Kanäle
| Adresse | Bedeutung | Einheit |
|---|---|---|
ess0/SetActivePowerEquals | Vorgabe Wirkleistung | W |
ess0/SetReactivePowerEquals | Vorgabe Blindleistung | var |
ess0/SetActivePowerLessOrEquals | Vorgabe maximaler Entladeleistung | W |
ess0/SetReactivePowerLessOrEquals | Vorgabe maximaler Blindleistung | var |
ess0/SetActivePowerGreaterOrEquals | Vorgabe maximaler Beladeleistung | W |
ess0/SetReactivePowerGreaterOrEquals | Vorgabe minimaler Blindleistung | var |
ess0 steht für den Speicher bzw. den Speicherverbund Ihrer Anlage. Die Grenzen des Speichers gelten weiter, die tatsächliche Leistung kann deshalb von der Vorgabe abweichen.
Beispiel: 5 kW entladen mit Python
import requests
url = "http://192.168.178.30/rest/channel/ess0/SetActivePowerEquals"
response = requests.post(url, json={"value": 5000}, auth=("x", "owner"))
response.raise_for_status()
Dasselbe mit curl:
curl -u x:owner -H "Content-Type: application/json" -d "{\"value\": 5000}" http://192.168.178.30/rest/channel/ess0/SetActivePowerEquals
Ob die Vorgabe wirkt, sehen Sie im Portal unter Speichersystem oder mit einem GET-Aufruf auf _sum/EssActivePower.
Wer das Eigentümer-Passwort kennt und Ihr Heimnetz erreicht, kann den Speicher steuern. Ändern Sie deshalb das Standardpasswort und geben Sie die Schnittstelle nie ins Internet frei.