FEMS App REST/JSON Write Access

1. Introduction

Dear customer,

Thank you for choosing the "FEMS App REST/JSON Write Access". You are welcome to send us your suggestions so that we can further improve the quality of our products.

2. Installing the app

When you ordered the "FEMS App REST/JSON Write Access", you received a 16-digit license key. You can use this license key to redeem the app independently in the FEMS App Center.

Find instructions on how to proceed here.

3. FEMS App REST/JSON Write Access

These instructions describe write access to an FENECON electrical energy storage system using the REST/JSON API. The functionality of the interface is then explained.

3.1. Prerequisites

Das auf das Stromspeichersystem zugreifende Gerät (z. B. Notebook/PC) muss direkten Zugriff auf die IP-Adresse des FEMS haben — also z. B. im selbem physischen Netzwerk angeschlossen sein.

3.2. REST/JSON basics

The REST/JSON interface enables access to the FEMS in the local network via an interface based on REST .

3.3. Write access

This app provides an interface based on REST that can be used to describe data points in the system.

This app is not included in the standard scope of delivery of the FEMS. However, it can be retrofitted at any time. Please contact us if you would like a retrofit.

It is not possible to use write access through a guest login. Instead, a separate customer login is required. The password "owner" must be used for this. As with read access, the user name is up to your preference.

All write accesses must be sent as POST requests.

3.3.1. Timeout

Diese App 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.

3.3.2. /channel endpoint

The endpoint /channel enables access to individual data points, so-called "channels", in the system.

The full address of the endpoint is:

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

<COMPONENT> is the ID of the component.
<CHANNEL> is the ID of the channel

3.3.3. Data points

The following data points of the component _ess0 can be described:

Table 1. Data points of the component *_ess0*
Data point	Description	Unit
`SetActivePowerEquals`	Default charging or discharging power	Watt [W]
`SetReactivePowerEquals`	Set reactive power specification	VoltAmpere Reactive [var]
`SetActivePowerLessOrEquals`	Set maximum discharge power	Watt [W]
`SetReactivePowerLessOrEquals`	Set maximum reactive power	VoltAmpere Reactive [var]
`SetActivePowerGreaterOrEquals`	Set maximum charging power	Watt [W]
`SetReactivePowerGreaterOrEquals`	Set minimum reactive power	VoltAmpere Reactive [var]

The registers for reactive power specifications cannot currently be used for home systems.

You can find more information on the 'SetActivePowerEquals' channel and other channels for power setting at Glossary.

3.3.4. Example 1 — Active power specification: 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
}

Positive values correspond to battery discharging — Negative values correspond to battery charging.

The requests library, which must be imported at the beginning, can be used for this:

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

The correct execution of the request can be checked via a subsequent GET request or via Online Monitoring (see below).

3.3.5. Example 2 — Active power specification: Talend API Tester

Talend API Tester is an extension for Google Chrome that allows to test REST APIs.

First, an Authorization header must be added:

The POST request can then be executed.

The correct execution of the request can be checked via a subsequent GET request or via Online Monitoring (see below).