Symphon-E App REST/JSON Schreibzugriff

1. Introduction

Dear customer,

Thank you for choosing the "Symphon-E App REST/JSON Schreibzugriff". 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 "Symphon-E App REST/JSON Schreibzugriff", you received a 16-digit license key. You can use this license key to redeem the app independently in the EMS App Center.

Eine Anleitung zur Vorgehensweise finden Sie hier.

3. REST/JSON — Write access

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

3.1. Prerequisites

The device accessing the electrical energy storage system (e.g. notebook/PC) must have direct access to the IP address of the EMS - e. g. be connected to the same physical network.

3.2. REST/JSON basics

The REST/JSON interface enables access to the EMS 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 EMS. 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

This app has a configurable timeout. By default, this is configured to 60 seconds. It ensures that a default value remains active for 60 seconds. As soon as a new default value is written, the new value is used. If no new default value is written within 60 seconds, the controller falls back to the lower-priority controller - e. g. specification of a "0" output or self-consumption optimization.

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

For example, to specify a discharge power of 5 kW for the first electrical energy storage system (or electrical energy storage cluster), send a POST request to the address http://192.168.0.23:80/rest/channel/ess0/SetActivePowerEquals with the power specification in 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).