REST/JSON Write acces specs

Deze instucties beschrijven toegang tot het energieopslagsysteem via de REST/JSON API en leggen de functionaliteit van de interface uit. Vereisten Het apparaat dat toegang heeft tot het energieopslagsysteem (bijvoorbeeld een laptop/pc) moet rechtstreekse toegang hebben tot het IP-adres van de FEMS, bijvoorbeeld door verbinding te maken met hetzelfde fysieke netwerk.

Basisprincipes REST/JSON

De REST/JSON-interface maakt via REST-toegang mogelijk tot de FEMS in het lokale netwerk.

Leestoegang

Deze app biedt een op REST gebaseerde interface waarmee datapunten in het systeem kunnen worden uitgelezen.

Opmerking

Deze app is standaard inbegrepen in de leveringsomvang van de FEMS.

Het basisadres voor REST-toegang ishttp://<BENUTZER>:<PASSWORT>@<IP>:80/rest

Http is het protocol
<BENUTZER>is de gebruikersnaam. Omdat de authenticatie alleen via het wachtwoord plaatsvindt, kan hier elke waarde (bijvoorbeeld “x”) worden opgegeven
<PASSWORT>is het wachtwoord van de gebruiker. De standaard “gast”-gebruiker in FEMS heeft het wachtwoord ” gebruiker “
<IP>is het IP-adres van de FEMS
80is de poort voor de REST/JSON API (optioneel)

Dus als uw FEMS het lokale IP-adres ‘192.168.0.23’ heeft, is het basisadres voor REST-toegang http://x:user@192.168.0.23:80/rest

Waarschuwing

Om veiligheidsredenen worden eenvoudige authenticatieverzoeken niet ondersteund, omdat bij deze variant wachtwoorden via de URL worden verzonden. Headerverificatie moet expliciet worden gebruikt voor REST-aanroepen. Een zoekopdracht rechtstreeks via de browser (zonder extensie) is daarom niet mogelijk. In dit geval verschijnt er een foutmelding, zie Figuur Foutmelding bij eenvoudige authenticatieverzoeken . Voor het uitvoeren van query’s in de browser kunt u de Talend API Tester-extensie gebruiken, zoals hier beschreven.

Figuur 1. Foutmelding voor eenvoudige authenticatieverzoeken

/channel eindpunt

Het /channeleindpunt maakt toegang mogelijk tot individuele datapunten, zogenaamde “kanalen”, in het systeem.

Het volledige adres van het eindpunt is:

http://x:<WACHTWOORD>@<IP>:80/rest/channel/<COMPONENT>/<CHANNEL>

<KOMPONENTE>is de ID van het onderdeel
<KANAL>is de ID van het kanaal s

Data punten

De volgende gegevenspunten kunnen worden gelezen:

Data punt	Beschrijving	Eenheid
_sum/State	Systeemstatus (0: Ok, 1:Info, 2:Waarschuwing, 3:Fout)
_sum/EssSoc	Ladingsniveau geheugen	procent [%]
_sum/EssActivePower	Actieve kracht van het geheugen	Watt [W]
_sum/GridActivePower	Werkelijk vermogen op het netaansluitpunt	Watt [W]
_sum/ProductionActivePower	Actieve stroomgenerator	Watt [W]
_sum/ProductionAcActivePower	AC-generator met actief vermogen	Watt [W]
_sum/ProductionDcActualPower	Actief vermogen DC-generator	Watt [W]
_sum/ConsumptionActivePower	Actieve stroomverbruiker	Watt [W]
_sum/EssActiveChargeEnergy	Energieopslag laden	Wattuur [Wh]
_sum/EssActiveDischargeEnergy	Ontlading van energieopslag	Wattuur [Wh]
_sum/GridBuyActiveEnergy	Energie uit het net	Wattuur [Wh]
_sum/GridSellActiveEnergy	Teruglevering energienet	Wattuur [Wh]
_sum/ProductionActiveEnergy	Energie productie	Wattuur [Wh]
_sum/ProductionAcActiveEnergy	Energie AC-opwekking	Wattuur [Wh]
_sum/ProductionDcActiveEnergy	Energie DC-opwekking	Wattuur [Wh]
_sum/ConsumptionActiveEnergy	Energieverbruiker	Wattuur [Wh]
_sum/EssActivePowerL1	Actief vermogen fase 1 opslag	Watt [W]
_sum/EssActivePowerL2	Actief vermogen fase 2 opslag	Watt [W]
_sum/EssActivePowerL3	Actief vermogen fase 3 opslag	Watt [W]
_sum/GridActivePowerL1	Actief vermogen fase 1 netwerk	Watt [W]
_sum/GridActivePowerL2	Actief vermogen fase 2 netwerk	Watt [W]
_sum/GridActivePowerL3	Actief vermogen fase 3 netwerk	Watt [W]
_sum/ProductionAcActivePowerL1	Actief vermogen fase 1 generator	Watt [W]
_sum/ProductionAcActivePowerL2	Actief vermogen fase 2 generator	Watt [W]
_sum/ProductionAcActivePowerL3	Actief vermogen fase 3 generator	Watt [W]
_sum/ConsumptionActivePowerL1	Actief vermogen fase 1 verbruiker	Watt [W]
_sum/ConsumptionActivePowerL2	Actief vermogen fase 2 verbruiker	Watt [W]
_sum/ConsumptionActivePowerL3	Actief vermogen fase 3 verbruiker	Watt [W]

Voorbeeld 1 – De laadstatus opvragen: cURL

Voorbeeld 1 – De laadstatus opvragen: cURL

Het opdrachtregelprogramma cURL is vooraf geïnstalleerd op zowel Windows als Linux.

Om de laadstatus van de energieopslag te lezen, stuurt u een GET verzoek naar het adres: http://x:user@192.168.0.23:80/rest/channel/_sum/EssSoc

U ontvangt een antwoord in JSON-formaat:

Windows

Met de volgende opdracht wordt het antwoord in JSON-indeling opgeslagen in het bestand out.json

>curl -o out.json http://x:user@192.168.0.23:80/rest/channel/_sum/EssSoc

Om de inhoud van het bestand uit te voeren, gebruikt u:

>type out.json

Uitkomst:

{“address”:“_sum/EssSoc”,”type”:“INTEGER”,”accessMode”:“RO”,”text”:“”,”unit”:“%”,”value”:99}

De waarde van de laadtoestand vindt u onder waarde. In het bovenstaande voorbeeld is dit 99%.

Linux

Met de volgende opdracht wordt het antwoord in JSON-indeling opgeslagen in het bestand out.json

$curl -o out.json http://x:user@192.168.0.23:80/rest/channel/_sum/EssSoc

Om de inhoud van het bestand uit te voeren, gebruikt u:

>cat out.json

Uitkomst:

{“address”:“_sum/EssSoc”,”type”:“INTEGER”,”accessMode”:“RO”,”text”:“”,”unit”:“%”,”value”:99}

De waarde van de laadtoestand vindt u onder waarde. In het bovenstaande voorbeeld is dit 99%.

Voorbeeld 2 – Chargestatus opvragen: Python

Python-versies voor Windows en Linux zijn hier beschikbaar:

https://www.python.org/downloads/

Om de laadstatus van de energieopslag uit te lezen, moet er ook een aanvraag worden verzonden GETnaar het adres:
http://x:user@192.168.0.23:80/rest/channel/_sum/EssSoc

Hiervoor kan de verzoekbibliotheek worden gebruikt, die aan het begin moet worden geïmporteerd:

import requests

url = ‘http://192.168.0.23:80/rest/channel/_sum/EssSoc’

user = ‘x’
password = ‘user’

session = requests.Session()
session.auth = (user, password)

response = session.get(url)
response.raise_for_status()

De opdracht retourneert een antwoord in JSON-indeling. Dit kan worden gedaan met het volgende commando:

print(response.text)

Uitkomst:

{“address”:“_sum/EssSoc”,”type”:“INTEGER”,”accessMode”:“RO”,”text”:“”,”unit”:“%”,”value”:99}

De waarde van de laadtoestand vindt u onder waarde. In het bovenstaande voorbeeld is dit 99%.

Voorbeeld 3 – Opvragen laadstatus: Talend API Tester

Talend API Tester is een extensie voor Google Chrome waarmee u REST API’s kunt testen.

Eerst moet een Authorizatie Header worden toegevoegd:

Het verzoek kan vervolgens GET worden uitgevoerd.

De waarde van de laadtoestand vindt u onder waarde. In het bovenstaande voorbeeld is dit 99%.

Schrijftoegang

Deze app biedt een RUSTEr is een soortgelijke interface beschikbaar waarmee datapunten in het systeem kunnen worden beschreven.

Opmerking

Deze app is niet inbegrepen in de standaard leveringsomvang van de FEMS. Het kan echter op elk moment achteraf worden ingebouwd. Neem hiervoor contact met ons op!

Opmerking

Het gebruik van schrijftoegang is niet mogelijk via gasttoegang. In plaats daarvan is afzonderlijke klanttoegang noodzakelijk. Hiervoor moet het wachtwoord “eigenaar” worden gebruikt. Net als bij leestoegang kan de gebruikersnaam willekeurig worden gekozen.

Alle schrijftoegangen moeten POST als verzoeken worden verzonden.

Time-out

Deze app heeft een configureerbare time-out. Standaard is dit ingesteld op 60 seconden. Het zorgt ervoor dat een standaardwaarde 60 seconden actief blijft. Zodra een nieuwe standaardwaarde wordt geschreven, wordt de nieuwe waarde gebruikt. Als er binnen 60 seconden geen nieuwe standaardwaarde is, valt de besturing terug naar de controller met lagere prioriteit – b.v. B. Een “0”-prestatie specificeren of het eigen verbruik optimaliseren.

/channel eindpunt

Het eindpunt /channel maakt toegang mogelijk tot individuele datapunten, zogenaamde “kanalen”, in het systeem.

Het volledige adres van het eindpunt is:

http://x:<WACHTWOORD>@<IP>:80/rest/channel/<COMPONENT>/<CHANNEL>

KOMPONENTE>is de ID van het onderdeel .
<KANAL>is de ID van het kanaal s

Datapunten

De volgende gegevenspunten kunnen worden beschreven:

Data punt	Beschrijving	Eenheid
ess0/SetActivePowerEquals	Specificatie actief vermogen	Watt [W]
ess0/SetReactivePowerEquals	Specificatie van reactief vermogen	VoltAmpereReactief [VAR]
ess0/SetActivePowerLessOrEquals	Specificatie van (maximaal) actief vermogen	Watt [W]
ess0/SetReactivePowerLessOrEquals	(Maximale) blindvermogenspecificatie	VoltAmpereReactief [VAR]
ess0/SetActivePowerGreaterOrEquals	(Minimale) specificatie actief vermogen	Watt [W]
ess0/SetReactivePowerGreaterOrEquals	(Minimale) specificatie actief vermogen	VoltAmpereReactief [VAR]

Opmerking

Zie de verklarende woordenlijst voor meer informatie over het kanaal SetActivePowerEqualsen andere kanalen voor prestatietargeting

Voorbeeld 1 – Specificatie actief vermogen: Python

Naar b.v. Als u bijvoorbeeld een ontladingsvermogen van 5 kW wilt opgeven voor het eerste energieopslagsysteem (of energieopslagcluster), stuurt u een POST verzoek naar het adres http://192.168.0.23:80/rest/channel/ess0/SetActivePowerEqualsmet de vermogensspecificatie in JSON- formaat

{
“value”: 5000
}

Opmerking

Een ontlading van het geheugen wordt gerealiseerd door een positieve waarde, een laden door een negatieve waarde.

Hiervoor kan de verzoekbibliotheek worden gebruikt, die aan het begin moet worden geïmporteerd:

import requests

url = ‘http://192.168.0.23:80/rest/channel/ess0/SetActivePowerEquals’

user = ‘x’
password = ‘owner’

session = requests.Session()
session.auth = (user, password)

data = {“value”: 5000}

response = session.post(url, json = data)
response.raise_for_status()

De juiste uitvoering van het verzoek kan GET worden gecontroleerd via een vervolgverzoek of online monitoring.