APIs - Externe Schnittstellen

Table of Contents

1. Lokale Schnittstellen
2. FEMS-App REST/JSON Lese- und Schreibzugriff
- 2.1. Lesezugriff
- 2.2. Schreibzugriff
3. FEMS App Modbus/TCP Lese- und Schreibzugriff
4. FEMS App Websocket/JSON-Api
5. FEMS App Cloud REST/JSON-Api

Das FENECON Energiemanagementsystem (FEMS) stellt verschiedene externe Schnittstellen - sog. APIs, Application Programming Interfaces - bereit, über die Daten ausgelesen oder Aktionen ausgeführt werden können. Darüber ist die Einbindung z. B. in eine Netzleitstelle oder ein Smart-Home-System möglich.

1. Lokale Schnittstellen

Lokale Schnittstellen ermöglichen den Zugriff auf das FEMS im lokalen Netzwerk. Es ist dafür notwendig, dass das zugreifende Gerät direkten Zugriff auf die IP-Adresse des FEMS hat - also z. B. im gleichen physischen Netzwerk angeschlossen ist.

2. FEMS-App REST/JSON Lese- und Schreibzugriff

Die FEMS-Apps REST/JSON Lese- und Schreibzugriff ermöglichen den Zugriff auf das FEMS im lokalen Netzwerk über eine an REST angelehnte Schnittstelle. Es ist dafür notwendig, dass das zugreifende Gerät direkten Zugriff auf die IP-Adresse des FEMS hat – also z. B. im gleichen physischen Netzwerk angeschlossen ist.

2.1. Lesezugriff

Die "FEMS App REST/JSON Lesezugriff" stellt eine an REST angelehnte Schnittstelle zur Verfügung, mit der Datenpunkte im System ausgelesen werden können.

Diese App ist im Standard-Lieferumfang des FEMS enthalten.

Die Basis-Adresse für die REST-Zugriffe lautet http://<BENUTZER>:<PASSWORT>@<IP>:80/rest

http ist das Protokoll
<BENUTZER> ist der Benutzername. Da die Authentifizierung lediglich über das Passwort erfolgt, kann hier ein beliebiger Wert (z. B. "x") angegeben werden
<PASSWORT> ist das Passwort des Benutzers. Der Standard "Gast"-Benutzer im FEMS hat das Passwort "user"
<IP> ist die IP-Adresse des FEMS
80 ist der Port für die REST/JSON-Api (optional)

Wenn Ihr FEMS also die lokale IP-Adresse '192.168.0.23' hat, lautet die Basis-Adresse für REST-Zugriffe http://x:user@192.168.0.23:80/rest

2.1.1. /channel Endpunkt

Der /channel Endpunkt ermöglicht den Zugriff auf einzelne Datenpunkte, sogenannte "Channels", im System.

Die vollständige Adresse des Endpunkts lautet:

http://x:<PASSWORT>@<IP>:80/rest/channel/<KOMPONENTE>/<KANAL>

<KOMPONENTE> ist die ID der Komponente.
<KANAL> ist die ID des Kanals

2.1.2. Datenpunkte

Die folgenden Datenpunkte können ausgelesen werden:

Datenpunkt

Beschreibung

Einheit

_sum/State

Zustand des Systems (0: Ok, 1:Info, 2:Warning, 3:Fault)

_sum/EssSoc

Ladezustand des Speichers

Prozent [%]

_sum/EssActivePower

Wirkleistung des Speichers

Watt [W]

_sum/GridActivePower

Wirkleistung am Netzanschlusspunkt

Watt [W]

_sum/ProductionActivePower

Wirkleistung Erzeuger

Watt [W]

_sum/ProductionAcActivePower

Wirkleistung AC Erzeuger

Watt [W]

_sum/ProductionDcActualPower

Wirkleistung DC Erzeuger

Watt [W]

_sum/ConsumptionActivePower

Wirkleistung Verbraucher

Watt [W]

_sum/EssActiveChargeEnergy

Energie Speicherbeladung

WattHours [Wh]

_sum/EssActiveDischargeEnergy

Energie Speicherentladung

WattHours [Wh]

_sum/GridBuyActiveEnergy

Energie Netzbezug

WattHours [Wh]

_sum/GridSellActiveEnergy

Energie Netzeinspeisung

WattHours [Wh]

_sum/ProductionActiveEnergy

Energie Erzeugung

WattHours [Wh]

_sum/ProductionAcActiveEnergy

Energie AC Erzeugung

WattHours [Wh]

_sum/ProductionDcActiveEnergy

Energie DC Erzeugung

WattHours [Wh]

_sum/ConsumptionActiveEnergy

Energie Verbraucher

WattHours [Wh]

_sum/EssActivePowerL1

Wirkleistung Phase 1 Speicher

Watt [W]

_sum/EssActivePowerL2

Wirkleistung Phase 2 Speicher

Watt [W]

_sum/EssActivePowerL3

Wirkleistung Phase 3 Speicher

Watt [W]

_sum/GridActivePowerL1

Wirkleistung Phase 1 Netz

Watt [W]

_sum/GridActivePowerL2

Wirkleistung Phase 2 Netz

Watt [W]

_sum/GridActivePowerL3

Wirkleistung Phase 3 Netz

Watt [W]

_sum/ProductionAcActivePowerL1

Wirkleistung Phase 1 Erzeuger

Watt [W]

_sum/ProductionAcActivePowerL2

Wirkleistung Phase 2 Erzeuger

Watt [W]

_sum/ProductionAcActivePowerL3

Wirkleistung Phase 3 Erzeuger

Watt [W]

_sum/ConsumptionActivePowerL1

Wirkleistung Phase 1 Verbraucher

Watt [W]

_sum/ConsumptionActivePowerL2

Wirkleistung Phase 2 Verbraucher

Watt [W]

_sum/ConsumptionActivePowerL3

Wirkleistung Phase 3 Verbraucher

Watt [W]

2.1.3. Beispiel 1 - Abfrage des Ladezustands: cURL

Das Kommandozeilen-Programm cURL ist sowohl unter Windows und Linux vorinstalliert.

Um den Ladezustand des Stromspeichers auszulesen, senden Sie einen GET-Request an die Adresse: http://x:user@192.168.0.23:80/rest/channel/_sum/EssSoc

Sie erhalten eine Antwort im JSON-Format:

2.1.3.1. Windows

Der folgende Befehl speichert die Antwort im JSON-Format in die Datei out.json

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

Um den Inhalt der Datei auszugeben, nutzen Sie:

>type out.json

Ausgabe:

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

Den Wert des Ladezustands finden Sie unter value. Im Beispiel oben beträgt er 99 %.

2.1.3.2. Linux

Der folgende Befehl speichert die Antwort im JSON-Format in die Datei out.json

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

Um den Inhalt der Datei auszugeben, nutzen Sie:

>cat out.json

Ausgabe:

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

Den Wert des Ladezustands finden Sie unter value. Im Beispiel oben beträgt er 99 %.

2.1.4. Beispiel 2 - Abfrage des Ladezustands: Python

Python Versionen für Windows und Linux erhalten Sie hier: https://www.python.org/downloads/

Um den Ladezustand des Stromspeichers auszulesen, muss ebenfalls ein GET-Request an die Adresse:
http://x:user@192.168.0.23:80/rest/channel/_sum/EssSoc gesendet werden.

Hierfür kann die requests Bibliothek genutzt werden, die zu Beginn importiert werden muss:

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()

Der Befehl liefert eine Antwort im JSON-Format. Diese kann mit dem folgenden Befehl ausgegeben werden:

print(response.text)

Ausgabe:

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

Den Wert des Ladezustands finden Sie unter value. Im Beispiel oben beträgt er 99 %.

2.1.5. Beispiel 3 - Abfrage des Ladezustands: Talend API Tester

Talend API Tester ist eine Erweiterung für Google Chrome, die es ermöglicht, REST APIs zu testen.

Zunächst muss ein Authorization Header hinzugefügt werden:

Talend API Tester Authentication

Anschließend kann der GET-Request ausgeführt werden.

Den Wert des Ladezustands finden Sie unter value. Im Beispiel oben beträgt er 99 %.

2.2. Schreibzugriff

Die "FEMS App REST/JSON Schreibzugriff" stellt eine an REST angelehnte Schnittstelle zur Verfügung, mit der Datenpunkte im System beschrieben werden können.

Diese App ist nicht im Standard-Lieferumfang des FEMS enthalten. Sie kann jedoch nachträglich jederzeit nachgerüstet werden. Kontaktieren Sie uns hierfür!

Die Verwendung des Schreibzugriffs ist nicht über den Gast-Zugang möglich. Stattdessen ist ein gesonderter Kundenzugang notwendig. Hierfür ist das Passwort "owner" zu verwenden. Der Nutzername kann wie beim Lesezugriff beliebig gewählt werden.

Sämtliche Schreibzugriffe müssen als POST-Requests gesendet werden.

2.2.1. Timeout

Die "FEMS App REST/JSON-Api Schreibzugriff" verfügt über einen konfigurierbaren Timeout. Im Standard ist dieser auf 60 Sekunden konfiguriert. Er sorgt dafür, dass ein Vorgabewert 60 Sekunden lang aktiv bleibt. Sobald ein neuer Vorgabewert geschrieben wird, wird der neue Wert verwendet. Erfolgt kein neuer Vorgabewert innerhalb von 60 Sekunden, fällt die Steuerung auf den nachrangig priorisierten Controller zurück - z. B. Vorgabe einer "0"-Leistung oder Eigenverbrauchsoptimierung.

2.2.2. /channel Endpunkt

Genau wie bei der "FEMS App REST/JSON Lesezugriff", wird über den Endpunkt /channel der Zugriff auf einzelne Datenpunkte, sogenannte "Channels", im System ermöglicht.

Die vollständige Adresse des Endpunkts lautet:

http://x:<PASSWORT>@<IP>:80/rest/channel/<KOMPONENTE>/<KANAL>

<KOMPONENTE> ist die ID der Komponente.
<KANAL> ist die ID des Kanals

2.2.3. Datenpunkte

Die folgenden Datenpunkte können beschrieben werden:

Datenpunkt

Beschreibung

Einheit

ess0/SetActivePowerEquals

Wirkleistungsvorgabe

Watt [W]

ess0/SetReactivePowerEquals

Blindleistungsvorgabe

VoltAmpereReactive [VAR]

ess0/SetActivePowerLessOrEquals

(Maximale) Wirkleistungsvorgabe

Watt [W]

ess0/SetReactivePowerLessOrEquals

(Maximale) Blindleistungsvorgabe

VoltAmpereReactive [VAR]

ess0/SetActivePowerGreaterOrEquals

(Minimale) Wirkleistungsvorgabe

Watt [W]

ess0/SetReactivePowerGreaterOrEquals

(Minimale) Wirkleistungsvorgabe

VoltAmpereReactive [VAR]

Mehr Informationen zum Channel SetActivePowerEquals und anderen Channels zur Leistungsvorgabe finden Sie im Glossar

2.2.4. Beispiel 1 - Wirkleistungsvorgabe: Python

Um z. B. dem ersten Stromspeichersystem (bzw. Stromspeicher-Cluster) eine Entladeleistung von 5 kW vorzugeben, senden Sie einen POST-Request an die Adresse http://192.168.0.23:80/rest/channel/ess0/SetActivePowerEquals mit der Leistungsvorgabe im JSON Format

{
  "value": 5000
}

Eine Entladung des Speichers wird durch einen positiven, eine Beladung durch einen negativen Wert umgesetzt.

Hierfür kann die requests Bibliothek genutzt werden, die zu Beginn importiert werden muss:

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()

Die korrekte Durchführung des Requests kann über einen anschließenden GET-Request oder das Online-Monitoring (s. unten) überprüft werden.

Talend API Tester POST Success

2.2.5. Beispiel 2 - Wirkleistungsvorgabe: Talend API Tester

Talend API Tester ist eine Erweiterung für Google Chrome, die es ermöglicht, REST APIs zu testen.

Zunächst muss ein Authorization Header hinzugefügt werden:

Talend API Tester Authentication POST

Anschließend kann der POST-Request ausgeführt werden.

Die korrekte Durchführung des requests kann über einen anschließenden GET-Request oder das Online-Monitoring (s. unten) überprüft werden.

Talend API Tester POST Success

3. FEMS App Modbus/TCP Lese- und Schreibzugriff

Diese Anleitung dient der Beschreibung der FEMS App Modbus/TCP. Zunächst werden Grundlagen zum Protokoll beschrieben. Anschließend wird die Funktionsweise der App erklärt.

3.1. Grundlagen Modbus/TCP

Das Modbus-Protokoll ist ein Kommunikationsprotokoll, das auf einer Client/Server-Architektur basiert. Es wurde 1979 von Gould-Modicon für die Kommunikation mit seinen speicherprogrammierbaren Steuerungen ins Leben gerufen. In der Industrie hat sich der Modbus zu einem De-facto-Standard entwickelt, da es sich um ein offenes Protokoll handelt. Seit 2007 ist die Version Modbus TCP Teil der Norm IEC 61158.

Wikipedia: Modbus/TCP

Mittels Modbus können ein Client (z. B. ein PC/EMS) und mehrere Server (z. B. Mess- und Regelsysteme, Batteriespeicher, PV-Anlage, Ladestation E-Auto) verbunden werden. Es gibt zwei Versionen: Eine für die serielle Schnittstelle (EIA-232 und EIA-485) und eine für Ethernet. In dieser Anleitung wird die Version für Ethernet beschrieben. Hierbei werden TCP/IP-Pakete verwendet, um die Daten zu übermitteln.

Lese- und Schreibzugriffe sind auf folgende Objekttypen möglich:

Objekttyp

Zugriff

Größe

Funktionscode

Einzelner Ein-/Ausgang „Coil“

Lesen & Schreiben

1-bit

01 / 05 / 15

Einzelner Eingang „Discrete Input“

nur Lesen

1-bit

(analoge) Eingänge „Input Register“

nur Lesen

16-bits

(analoge) Ein-/Ausgänge „Holding Register“

Lesen & Schreiben

16-bits

03 / 06 / 16

3.2. Lesezugriff

Diese App ist im Standard-Lieferumfang des FEMS enthalten.

Die Modbus-Schnittstelle ist folgendermaßen konfiguriert:

Table 1. Parameter der FEMS APP Modbus/TCP-API, Lesezugriff
Geräteadresse	IP-Adresse des FEMS (z.B. 192.168.0.20)
Port	502
Unit-ID	1
Function-Codes	03 (Read Holding Registers)
	04 (Read Input Registers)

Die Schnittstelle ermöglicht standardmäßig Zugriff auf die Kanäle der Komponente _sum. Der Zugriff auf weitere Komponenten wird projektspezifisch freigegeben – um z. B. ansteuerbare Stromspeichersysteme oder Ladesäulen über die Schnittstelle freizugeben.

3.3. Modbus-Tabelle

Die individuelle Modbus-Tabelle für Ihr System können Sie bequem über das Online-Monitoring als Excel-Datei wie folgt herunterladen:

Figure 1. Reiter links oben im FEMS Online-Monitoring öffnen

Figure 2. Reiter "Einstellungen" öffnen

Figure 3. Anlagenprofil öffnen

Figure 4. ctrlApiModbusTcp öffnen

Figure 5. "Download Protocol"

Die wichtigsten Datenpunkte finden Sie auch hier in der Schnellübersicht:

Address (Adresse)

Name (Name)

Type (Typ)

Value/Description (Wert/Beschreibung)

Unit (Einheit)

Access (Zugang)

Header

Hash of "OpenEMS"

uint16

0x6201

Length of block "_meta"

uint16

199

OpenEMS Version Major

uint16

2020

OpenEMS Version Minor

uint16

OpenEMS Version Patch

uint16

Manufacturer

string16

FENECON GmbH

Manufacturer Model

string16

OpenEMS

Manufacturer Options

string16

Manufacturer Version

string16

Manufacturer Serial Number

string16

Manufacturer EMS Serial Number

string16

Sum

200

Component-ID

string16

_sum

216

Length of block "_sum"

uint16

300

220

Hash of "OpenemsComponent"

uint16

0xb3dc

221

Length of block "OpenemsComponent"

uint16

222

_sum/State

enum16

0:Ok, 1:Info, 2:Warning, 3:Fault

300

Hash of "Sum"

uint16

0x462b

301

Length of block "Sum"

uint16

220

302

_sum/EssSoc

uint16

Percent [%]

303

_sum/EssActivePower

float32

AC-side power of Energy Storage System. Includes excess DC-PV production for hybrid inverters. Negative values for charge; positive for discharge

Watt [W]

305

Reserved

float32

307

Reserved

float32

309

_sum/EssReactivePower

float32

VoltAmpereReactive [var]

311

Reserved

float32

313

Reserved

float32

315

_sum/GridActivePower

float32

Grid exchange power. Negative values for sell-to-grid; positive for buy-from-grid

Watt [W]

317

_sum/GridMinActivePower

float32

Watt [W]

319

_sum/GridMaxActivePower

float32

Watt [W]

321

Reserved

float32

323

Reserved

float32

325

Reserved

float32

327

_sum/ProductionActivePower

float32

Total production; always positive

Watt [W]

329

_sum/ProductionMaxActivePower

float32

Watt [W]

331

_sum/ProductionAcActivePower

float32

Production from AC source

Watt [W]

333

_sum/ProductionMaxAcActivePower

float32

Watt [W]

335

Reserved

float32

337

Reserved

float32

339

_sum/ProductionDcActualPower

float32

Production from DC source

Watt [W]

341

_sum/ProductionMaxDcActualPower

float32

Watt [W]

343

_sum/ConsumptionActivePower

float32

Watt [W]

345

_sum/ConsumptionMaxActivePower

float32

Watt [W]

347

Reserved

float32

349

Reserved

float32

351

_sum/EssActiveChargeEnergy

float64

WattHours [Wh]

355

_sum/EssActiveDischargeEnergy

float64

WattHours [Wh]

359

_sum/GridBuyActiveEnergy

float64

WattHours [Wh]

363

_sum/GridSellActiveEnergy

float64

WattHours [Wh]

367

_sum/ProductionActiveEnergy

float64

WattHours [Wh]

371

_sum/ProductionAcActiveEnergy

float64

WattHours [Wh]

375

_sum/ProductionDcActiveEnergy

float64

WattHours [Wh]

379

_sum/ConsumptionActiveEnergy

float64

WattHours [Wh]

383

_sum/EssDcChargeEnergy

float64

WattHours [Wh]

387

_sum/EssDcDischargeEnergy

float64

WattHours [Wh]

391

_sum/EssActivePowerL1

float32

AC-side power of Energy Storage System on phase L1. Includes excess DC-PV production for hybrid inverters. Negative values for charge; positive for discharge

Watt [W]

393

_sum/EssActivePowerL2

float32

AC-side power of Energy Storage System on phase L2. Includes excess DC-PV production for hybrid inverters. Negative values for charge; positive for discharge

Watt [W]

395

_sum/EssActivePowerL3

float32

AC-side power of Energy Storage System on phase L3. Includes excess DC-PV production for hybrid inverters. Negative values for charge; positive for discharge

Watt [W]

397

_sum/GridActivePowerL1

float32

Grid exchange power on phase L1. Negative values for sell-to-grid; positive for buy-from-grid

Watt [W]

399

_sum/GridActivePowerL2

float32

Grid exchange power on phase L2. Negative values for sell-to-grid; positive for buy-from-grid

Watt [W]

401

_sum/GridActivePowerL3

float32

Grid exchange power on phase L3. Negative values for sell-to-grid; positive for buy-from-grid

Watt [W]

403

_sum/ProductionAcActivePowerL1

float32

Production from AC source on phase L1

Watt [W]

405

_sum/ProductionAcActivePowerL2

float32

Production from AC source on phase L2

Watt [W]

407

_sum/ProductionAcActivePowerL3

float32

Production from AC source on phase L3

Watt [W]

409

_sum/ConsumptionActivePowerL1

float32

Watt [W]

411

_sum/ConsumptionActivePowerL2

float32

Watt [W]

413

_sum/ConsumptionActivePowerL3

float32

Watt [W]

415

_sum/EssDischargePower

float32

Actual AC-side battery discharge power of Energy Storage System. Negative values for charge; positive for discharge

Watt [W]

417

_sum/GridMode

enum16

1:On-Grid, 2:Off-Grid

ess0

500

Component-ID

string16

ess0

516

Length of block "ess0"

uint16

580

520

Hash of "OpenemsComponent"

uint16

0xb3dc

521

Length of block "OpenemsComponent"

uint16

522

ess0/State

enum16

0:Ok, 1:Info, 2:Warning, 3:Fault

600

Hash of "SymmetricEss"

uint16

0x42ee

601

Length of block "SymmetricEss"

uint16

100

602

ess0/Soc

uint16

Percent [%]

603

ess0/GridMode

enum16

1:On-Grid, 2:Off-Grid

604

ess0/ActivePower

float32

Watt [W]

700

Hash of "ManagedSymmetricEss"

uint16

0xa3ed

701

Length of block "ManagedSymmetricEss"

uint16

100

702

ess0/AllowedChargePower

float32

Watt [W]

704

ess0/AllowedDischargePower

float32

Watt [W]

706

ess0/SetActivePowerEquals

float32

Watt [W]

708

ess0/SetReactivePowerEquals

float32

VoltAmpereReactive [var]

710

ess0/SetActivePowerLessOrEquals

float32

Watt [W]

712

ess0/SetReactivePowerLessOrEquals

float32

VoltAmpere [VA]

714

ess0/SetActivePowerGreaterOrEquals

float32

Watt [W]

716

ess0/SetReactivePowerGreaterOrEquals

float32

Watt [W]

800

Hash of "EssSymmetric"

uint16

0x1352

801

Length of block "EssSymmetric"

uint16

300

3.4. Beispiel 1: Lesezugriff Batterieladezustand mit QModMaster

Im Folgenden soll der Lesezugriff auf den Ladezustand (SoC) der Batterie mittels des kostenlosen Tools QModMaster exemplarisch gezeigt werden.

Das Tool kann unter folgendem Link heruntergeladen werden:
Online: https://sourceforge.net/projects/qmodmaster/

Der Wert des Ladezustands ist wie folgt hinterlegt (s. oben):

Table 2. Registeradresse für den Ladezustand der Batterie
Address	Name	Type	Value/Description	Unit	Access
302	_sum/EssSoc	uint16		Percent [%]	RO

Standardmäßig wird in QModbusMaster die Base Address auf 1 gesetzt. Dieser Wert ist auf 0 zu ändern. Anderenfalls sind die Registeradressen aus dem Anlagenprofil um 1 verschoben.

Figure 6. Einstellungen

Unter Modbus TCP Settings müssen Slave IP und TCP Port richtig konfiguriert sein.

Figure 7. Modbus TCP Einstellungen

Da es sich um einen unit16 handelt, muss ein 16-bit Wort, also ein Register, ausgelesen werden. Nach Setzen der Werte auf den Menüpunkt "Read/Write" klicken. Der gelesene Wert erscheint unten.

Figure 8. Wert lesen

Der Abgleich mit dem FEMS Live-Monitoring bestätigt die Korrektheit des gelesenen Wertes.

Figure 9. Vergleich mit FEMS Live-Monitoring

Die Durchführung anderer Leseoperationen erfolgt analog.

3.5. Beispiel 2: Lesezugriff Speicherbeladung/Speicherentladung bei Hybrid Systemen und DC-PV mit QModMaster

Im Folgenden soll der Wert der Speicherbe- bzw. -entladung eines FENECON Pro Hybrid 10 mit DC-PV berechnet werden.

Das folgende Beispiel ist für alle FENECON Speichersysteme mit Hybrid Wechselrichter (und DC-PV) gültig

Hierzu ist das folgende Register notwendig:

Table 3. Registeradresse zur Bestimmung der Speicherbeladung/Speicherentladung
Address	Name	Type	Value/Description	Unit	Access
415	_sum/EssDischargePower	float32	Actual AC-side battery discharge power of Energy Storage System. Negative values for charge; positive for discharge	Watt [W]	RO

Alternativ kann die Speicherbe- bzw. -entladung auch manuell wie folgt errechnet werden:

Table 4. Registeradressen zur Bestimmung der Speicherbeladung/Speicherentladung
Address	Name	Type	Value/Description	Unit	Access
303	_sum/EssActivePower	float32	AC-side power of Energy Storage System. Includes excess DC-PV production for hybrid inverters. Negative values for charge; positive for discharge	Watt [W]	RO
339	_sum/ProductionDcActualPower	float32	Production from DC source	Watt [W]	RO

Register 303 liefert die AC-Leistung des Batteriewechselrichters. Diese enthält auch die Leistung der in AC umgewandelten DC-PV Leistung.
Register 339 liefert die reine DC-Leistung der PV-Produktion.

Der Wert der Speicherbe- bzw. -entladung berechnet sich anschließend durch die Differenz der Register 303 und 339

Zur Veranschaulichung folgendes theoretisches Beispiel:

10 kW [_sum/ProductionDcActualPower][339]
6 kW [_sum/EssActivePower][303]

Speicherbeladung/Speicherentladung: Register 303 - Register 339 = 6 kW - 10 kW = -4 kW (negativer Wert für Speicherbeladung)

Mittels QModMaster läuft die Berechnung wie folgt:

Figure 10. Abfrage Register 339

Die DC-seitige Produktion beträgt hier ca. 2,2 kW

Figure 11. Abfrage Register 303

Die AC-Entladung beträgt hier ca. 0,91 kW

Wie im theoretischen Beispiel oben errechnet sich die Speicherbe- bzw. -entladung durch Differenz der Register 303 und 339:

3.6. Schreibzugriff

Diese App ist nicht im Standard-Lieferumfang des FEMS enthalten. Sie kann jedoch nachträglich jederzeit nachgerüstet werden.

Die Modbus-Schnittstelle ist folgendermaßen konfiguriert:

Table 5. Parameter der FEMS APP Modbus/TCP-API, Schreibzugriff
Geräteadresse	IP-Adresse des FEMS (z.B. 192.168.0.20)
Port	502
Unit-ID	1
Function-Codes	03 (Read Holding Registers)
	04 (Read Input Registers)
	06 (Write Single Holding Register)
	16 (Write Multiple Holding Registers)

3.7. Beispiel 2: Schreibzugriff auf EssActivePower mit QModMaster

Im Folgenden soll der Schreibzugriff für das Setzen der EssActivePower mittels des kostenlosen Tools QModMaster exemplarisch gezeigt werden. Hierdurch kann die Funktion des Controller Fix Active Power Symmetric simuliert werden.

Der Wert ist wie folgt hinterlegt (s. oben):

Table 6. Registeradresse für das Setzen der *EssActivePower* des Speichers
Address	Name	Type	Value/Description	Unit	Access
706	ess0/SetActivePowerEquals	float32		Watt [W]	WO

Zusätzlich zur Überprüfung der Base Address auf 0 muss sichergestellt werden, dass unter Endian die Einstellung Little ausgewählt ist.

Figure 12. Einstellungen

Da es sich um einen float32 handelt, müssen zwei 16-bit Wörter, also zwei Register, geschrieben werden. In diesem Beispiel soll der Speicher mit 4000 (4E+03) Watt entladen werden. Der Wert kann direkt als Dezimalzahl in das Register eingegeben werden, wobei das Data Format Float zu wählen ist. Nach Setzen des Wertes auf den Menüpunkt "Read/Write" klicken, um die Schreiboperation durchzuführen.

Figure 13. Wert schreiben

Der Abgleich mit dem FEMS Live-Monitoring bestätigt die Korrektheit des geschriebenen Wertes.

Figure 14. Vergleich mit FEMS Live-Monitoring

Die Schreiboperation wird nur für die Dauer des Api-Timeout durchgeführt. Diese beträgt in der Standardkonfiguration 60 Sekunden, kann aber durch den FENECON Service beliebig angepasst werden.

Figure 15. Konfiguration Komponente Controller Api Modbus/TCP Read-Write

Die Durchführung anderer Schreiboperationen erfolgt analog.

4. FEMS App Websocket/JSON-Api

TODO… wir arbeiten daran.

5. FEMS App Cloud REST/JSON-Api

Die REST/JSON-Api verwendet das Protokoll JSON-RPC.

5.1. Verbindungsdaten

Verwenden Sie für alle Verbindungen die folgenden Daten:

Method

POST

URL

https://fenecon.de/fems/rest/jsonrpc

Sowie als Kopfdaten ("Headers"):

Authorization

Basic <Encoded Username + Password>

Content-Type

application/json

Bei Verwendung der REST/JSON-Api sind die von JSON-RPC geforderten Parameter jsonrpc: '2.0' und id: UUID optional.

5.2. Status aller FEMSe

Liefert den Status aller FEMSe, auf die Sie Zugriff haben.

5.2.1. Request

{
  "method": "getEdgesStatus",
  "params": {}
}

5.2.2. Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result":{
    "fems1234":{
      "online": true
    },
    "fems4711":{
      "online": false
    }
  }
}

5.3. Datenpunkte aller FEMSe

Liest die aktuellen Werte bestimmter Kanäle.

5.4. Request

{
  "method": "getEdgesChannelsValues",
  "params": {
    "ids": string[],
    "channels": string[]
  }
}

Beispiel:

{
  "method": "getEdgesChannelsValues",
  "params": {
    "ids": [
      "fems1234",
      "fems4711"
    ],
    "channels": [
      "_sum/EssSoc",
      "_sum/ProductionActivePower"
    ]
  }
}

5.5. Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result": {
    [Edge-ID: string]: [{
      [Channel-Address: string]: number
    }]
  }
}

Beispiel:

{
  "jsonrpc":"2.0",
  "id":"UUID",
  "result":{
    "fems1234":{
      "_sum/EssSoc":50,
      "_sum/ProductionActivePower":0
    },
    "fems4711":{
      "_sum/EssSoc":99,
      "_sum/ProductionActivePower":null
    }
  }
}

5.6. Zugriff auf ein spezifisches FEMS

Um auf ein spezifisches FEMS zuzugreifen, werden die spezifischen JSON-RPC Requests in einen übergeordneten JSON-RPC-Request edgeRpc verpackt:

{
  "method": "edgeRpc", (1)
  "params": {
    "edgeId": string, (2)
    "payload": {} (3)
  }
}

1	Der eindeutige Methodenname
2	Der Name des FEMS, z. B. `fems1234`
3	Die `payload` enthält den JSON-RPC Request, der an das FEMS weitergeleitet wird

5.6.1. Historische Datenpunkte

Abfrage der historischen Daten.

Request

{
  "method": "queryHistoricTimeseriesData",
  "params": {
    "timezone": Number,
    "fromDate": YYYY-MM-DD,
    "toDate": YYYY-MM-DD,
    "channels": ChannelAddress[],
    "resolution"?: Number
  }
}

Beispiel

{
  "method": "edgeRpc",
  "params": {
    "edgeId": "fems1234",
    "payload": {
      "method": "queryHistoricTimeseriesData",
      "params": {
        "timezone": -2,
        "fromDate": 2020-01-15,
        "toDate": 2020-01-16,
        "channels": [
          "_sum/EssSoc",
          "_sum/ProductionActivePower"
        ]
      }
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result": {
    "timestamps": [
      '2020-01-15T10:15:30Z',...
    ],
    "data": {
      "_sum/EssSoc": [
        50, 51,...
      ],
      "_sum/ProductionActivePower": [
        2000, 2020,...
      ]
    }
  }
}

5.6.2. Historische Energiewerte

Request

{
  "method": "queryHistoricTimeseriesEnergy",
  "params": {
    "timezone": Number,
    "fromDate": YYYY-MM-DD,
    "toDate": YYYY-MM-DD,
    "channels": ChannelAddress[]
  }
}

Response

{
  "result": {
    "data": {
      [channelAddress]: number | null
    }
  }
}

5.6.3. Excel-Export historischer Datenpunkte und Energiewerte

Request

{
  "method": "queryHistoricTimeseriesExportXlxs",
  "params": {
    "timezone": Number,
    "fromDate": YYYY-MM-DD,
    "toDate": YYYY-MM-DD,
    "dataChannels": ChannelAddress[],
    "energyChannels": ChannelAddress[]
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result": {
    "payload": Base64-String
  }
}

5.6.4. Aktuelle Konfiguration lesen

Request

{
  "method": "getEdgeConfig",
  "params": {}
}

Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result": {
    "components": {
      "alias": string,
      "factoryId": string,
      "properties": {
        [key: string]: value
      },
      "channels": {
        [channelId: string]: {}
      }
    },
    "factories": {
      [key: string]: {
        natureIds: string[]
      }
    }
  }
}

5.6.5. Neue Komponente anlegen

Request

{
  "method": "createComponentConfig",
  "params": {
    "factoryPid": string,
    "properties": [{
      "name": string,
      "value": any
    }]
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result": {}
}

5.6.6. Komponente umkonfigurieren

Request

{
  "method": "updateComponentConfig",
  "params": {
    "componentId": string,
    "properties": [{
      "name": string,
      "value": any
    }]
  }
}

Beispiel: Änderung der Konfiguration eines Fix Active-Power Controllers zur statischen Leistungsvorgabe an ein Stromspeichersystem:

{
  "method": "edgeRpc",
  "params": {
    "edgeId": "fems1234",
    "payload": {
      "method": "updateComponentConfig",
      "params": {
        "componentId": "ctrlFixActivePower0", (1)
        "properties": [{
          "name": "power",
          "value": -4000 (2)
        }]
      }
    }
  }
}

1	ID des Controllers
2	Leistungsvorgabe: positiv für Entladung; negativ für Beladung

Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result": {}
}

5.6.7. Komponente löschen

Request

{
  "method": "deleteComponentConfig",
  "params": {
    "componentId": string
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result": {}
}

5.6.8. Wertvorgabe

Über diesen Request kann z. B. eine Leistungsvorgabe an ein Stromspeichersystem (innerhalb der erlaubten Grenzen) gegeben werden.

Request

{
  "method": "setChannelValue",
  "params": {
    "componentId": string,
    "channelId": string,
    "value": any
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": "UUID",
  "result": {}
}

5.6.9. Zugriff auf eine spezifische Komponente

Verschiedene Komponenten erlauben weiterführende, spezifische Zugriffe. Ähnlich zu edgeRpc wird der eigentliche Request an die Komponente hier in einen componentJsonApi Request verpackt.

{
  "method": "componentJsonApi",
  "params": {
    "componentId": string,
    "payload": {}
  }
}

5.7. FEMS App Cloud Websocket/JSON-Api

TODO… wir arbeiten daran.

5.7.1. Verbindungsdaten

Verwenden Sie für alle Verbindungen die folgenden Daten:

URL	https://fenecon.de/fems-backend-to-backend