Benutzerdefinierte Zähler

Hinweis: Der cFos Charging Manager kann die meisten solaren Wechselrichter mittels SunSpec auslesen (Gerätetyp "SunSpec Solar Inverter / Meter"). In diesem Fall brauchen Sie keine eigene Zählerdefinition zu erstellen.

Der cFos Charging Manager erlaubt Ihnen, eigene Zählerdefinitionen anzulegen, um Zähler zu unterstützen, die nicht im Standard-Repertoire vorhanden sind. Es gibt derzeit zwei Typen: Modbus-Zähler und HTTP/JSON-Zähler. Die Definitionsdateien zu diesen Zählern sind sehr ähnlich. Modbus-Zähler lesen ihre Daten via Modbus aus bestimmten Registern, während HTTP/JSON-Zähler ihre Daten per HTTP Request holen und als Antwort JSON parsen. Zum Parsen verwendet der cFos Charging Manager hierbei eine kleine "query language".

Benutzerdefinierte Zähler können neben einer Reihe vordefinierter Variablen, wie Strom und Spannung, auch unbekannte, benutzerdefinierte Variablen einlesen, Inputs abfragen und Outputs setzen. Das einlesen von Variablen und Setzen von Outputs erlaubt dabei die Auswertung von Formeln. Dies ist in Kombination mit den weiter unten beschriebenen Charging Manager Variablen und globalen Charging Manager Outputs ein mächtiges feature und erlaubt sogar gewisse Hausautomatisationaufgaben und das Steuern von externe Geräten, wie Batteriespeichern. Wenn Sie hiermit Steuerungsaufgaben realisieren, geben Sie uns bitte feedback. Uns interessiert sehr, was die Leute mit dem cFos Charging Manager alles steuern und es hilft uns, den Charging Manager nach Kundenbedürfnissen weiterzuentwickeln.

Hier eine Beispiel-Definition für Modbus und eine für HTTP/JSON:
Beispiel-Definition für Modbus-Zähler herunterladen
Beispiel-Definition für HTTP/JSON-Zähler herunterladen

Im Charging Manager sind ein paar solcher Dateien schon mitgeliefert, aber Sie können unter "System Konfiguration" eigene Dateien hochladen und auch wieder löschen.
Hier finden Sie einen Großteil der von uns mitgelieferten Zählerdefinitionen:
Mitgelieferte Zählerdefinitionen herunterladen

Falls Sie eine eigene Zählerdatei erstellt haben und diese für andere Nutzer relevant sein könnte, wären wir Ihnen sehr dankbar, wenn Sie uns diese zur Verfügung stellen könnten. Dann liefern wir diese mit zukünftigen Versionen des Charging Managers aus.

Zähler-Definitionen für weitere Zähler herunterladen

Aufbau einer Definitionsdatei:

Zählerdefinitionen sind JSON-Dateien mit einem globalen JSON Object, das Eigenschaften und Unterobjekte besitzt. 'rtype' bestimmt den Typ der Leseoperation: 0 = Modbus, 1 = HTTP/JSON. Zahlen können Sie wahlweise in dezimal oder hex mit Prefix 0x angeben. Außerdem sind einzeilige Kommentare mittels // erlaubt. Wir empfehlen Ihre Definitions-Dateien durch einen JSON5 Validator laufen zu lassen, z.B. diesen JSON5 Validator

Sie sollten unbedingt das Kapitel Formeln gelesen haben, um zu verstehen, welche Werte in der folgenden Referenz in Formeln herangezogen werden können.

Modbus Definitionen besitzen ein Objekt 'rtu' mit folgenden Eigenschaften:

silence_period, in msec. bestimmt, die Pausenlänge vor einem Modbus RTU Zugriff, damit das Gerät den Start einer Nachricht erkennt.
silence_same_slave, true: Die Pause wird auch bei mehreren Zugriffen auf das selbe Gerät eingehalten.
retries: Die Anzahl der Wiederholungen, falls das Gerät nicht antwortet.
rcv_timeout: in msec. die maximale Wartezeit pro Zugriff, bis das Gerät antwortet.

Diese globalen Eigenschaften gelten für Modbus TCP und RTU:

modbus_read: Die Funktionsnummer des Modbus Lese Kommandos, meist 3 oder 4.
modbus_read_max_registers: Die maximale Anzahl am Stück lesbarer Register.
modbus_allow_gaps: true = Es dürfen unbenutzte Registerbereiche in einer Leseoperation mit gelesen werden.

Für Modbus TCP und HTTP/JSON gibt es ein Objekt 'tcp' mit folgenden Eigenschaften:

connect_timeout: is msec. die maximale Wartezeit auf eine TCP-Verbindung.
delay_after_connect: in msec. Pause nach dem Verbindungsaufbau vor dem Senden des ersten Kommandos.

Beide Definitionstypen (Modbus und HTTP/JSON) haben zusätzlich folgende Eigenschaften:

upd_delay: in msec. bestimmt das Intervall in dem ein Gerät gelesen werden kann. Einige Geräte werden überlastet, wenn sie zu oft abgefragt werden.
manufacturer: String, Name des Herstellers. Dies wird in den erweiterten Information der Kachel angezeigt.
delay_accumulated: true = Akkumulierte Werte (kWh) werden nur alle 3 Sekunden oder bei ausreichender Leistung abgefragt. false = Diese Werte werden immer mit abgefragt.
ui_addr: URL, falls abweichend von der Geräte-Adresse zum Aufruf des Webinterface.
reserved: Array mit Werten, die als 0 interpretiert werden (nützlich, falls das Gerät modellabhängig bestimmte Werte unterstützt).

Wenn Sie die oben gelisteten Eigenschaften weglassen, nimmt der cFos Charging Manager Standardwerte, die in den meisten Fällen gut funktionieren.

In der JSON Definition folgt als nächstes die Definition von Variablen, die der Zähler nutzt, um Werte für Strom, Spannung, etc. zu lesen oder auszurechnen. Der Charging Manager kennt folgende Variablen:
type_designation, version, firmware_version, serial: Diese bilden die Modellbezeichnung, wie in den erweiterten Infos der Kachel angezeigt. Diese werden beim Einrichten oder Rücksetzen des Zählers einmal abgefragt.
voltage_l1..voltage_l3, current_l1..current_l3, power_w, power_var, power_va, power_w_l1..power_w_l3, power_w_l1_minus..power_w_l3_minus, power_w_import, power_w_export: Der cFos Charging Manager versucht aus diesen Werte für voltage_l1..l3, vorzeichenbehaftete current_l1..l3, power_w und power_va zu berechnen. Sie müssen nicht alle Variablen angeben. Der cFos Charging Manager versucht, die Werte aus den vorhandenen Variablen zu berechnen.
import_wh, export_wh, import_wh_l1..import_wh_l3, export_wh_l1..export_wh_l3: Der Charging Manager nutzt diese Variablen, um import_wh und export_wh zu berechnen. Sie müssen nicht alle Variablen angeben. Der cFos Charging Manager versucht, die Werte aus den vorhandenen Variablen zu berechnen.

Zusätzlich können Sie weitere Variablen mit anderem Namen definieren, die bei jedem Update ausgelesen bzw. mittels Formeln berechnet werden.

Definition einer Variablen:

Das Objekt ist nach dem Namen der oben gelisteten Variablen benannt und hat folgende Eigenschaften:
fixed: String mit festen Wert. Nützlich, wenn z.B. kein Wert ermittelbar ist, z.B. für type_designation oder Spannung.
expr: String, die Variable wird nicht ausgelesen, sondern als Formel ausgewertet.
type: Falls nicht fixed oder expr, der Typ der Variablen: int16, int32, float, int64, string. Dies ist für Modbus wichtig, um die Register im richtigen Format auszulesen. Bei JSON/HTTP können Sie meist float nehmen.
resolution: float, der gelesene Wert wird mit 'resolution' multipliziert. Werte für Spannung müssen in Volt vorliegen, Ströme in Milliampere, Leistungen in Watt, Energie in Watt-Stunden (Wh). Mit negativer 'resolution' können Sie einen Wert invertieren, falls dieser mit umgekehrten Vorzeichen vorliegt.
address: number (Modbus) oder String (HTTP/JSON), die Modbus Register Nummer oder die HTTP URL des zu lesenden Wertes.
query: String, bei HTTP JSON die Angabe in der query language des Charging Managers, mit der er den zu lesenden Wert in der JSON Antwort findet.
order: String, bei Modbus die byte order, entweder "hl" oder "lh", in der der Wert vorliegt. length: number, bei Modbus die Länge eines Strings in Registern. Bei den Variablen 'version' und 'firmware_version' wird 'length' genutzt, um aus numerischen Versionen, Strings mit Punkten zu machen. Hierbei sind für 'length' Werte von 2 oder 4 erlaubt, die dann in den Versionsformaten a.b, und a.b.c.d resultieren. Bei 'length' 2 und Typ 'int16' trennt der Charging Manager low und high byte durch Punkt, bei int32 low und high word, bei 'int64' low und high dword. Bei 'lenth' 4 und 'int32', zerlegt der Charging Manager den Wert in 4 durch Punkt getrennte bytes. Bei 'int64' die 4 words entsprechend.

Definition von Inputs:

Pro Gerät kann der Charging Manager bis zu 32 Input Werte aus verschiedenen Registers bzw. JSON Elementen abfragen. Die Eigenschaft "Inputs" ist ein JSON Array. Pro Input müssen Sie folgende Eigenschaften definieren:
address: Adresse (Modbus Register oder URL).
count: Anzahl der Input Bits, die mit dieser Anfrage gelesen werden.
query: Bei HTTP/JSON, query language, um den Wert in der Antwort zu finden.

Der cFos Charging Manager liest bei jedem Update alle so definieren Inputs und legt die Bits intern in ein Array, das mit dann in Formeln abgefragt werden kann, Input1..InputN.

Definition von Outputs:

Pro Gerät kann der Charging Manager bis zu 32 Outputs schalten. Alle Outputs werden am Ende jedes Update Zyklus geschaltet, sofern sich der Zustand des jeweiligen Output geändert hat.
Pro Input müssen Sie folgende Eigenschaften definieren:
address: HTTP URL mit optionaler HTTP Methode, z.B. GET http://www.example.com?output1=${var1}. Um Modbus-Register zu setzen, können Sie das HTTP API des cFos Charging Managers verwenden. Der Charging Manageer erkennt passenden Zugriffe auf localhost und leitet den request an den internen handler um, so dass Sie keine Autorisierung benötigen, wie bei externen HTTP API Zugriffen.
body: Optionaler HTTP body für POST oder PUT.
In der URL und dem body können Sie mittels ${expr} Formeln verwenden, die globale Charging Manager Variablen oder vom jeweiligen Zähler referenzieren. Die Formel 'expr' wird beim Setzen des Outputs ausgewertet und im Text der URL bzw. des body ersetzt. Setzt im obigen Beispiel http://www.example.com?output1=1 den Output und http://www.example.com?output1=0 löscht ihn, können Sie eine Variable 'var1' definieren und diese wie gewünscht auf 1 oder 0 setzen. So können Sie auch numerische Werte zum Steuern von Speicherleistung in Modbus Register schreiben, die Sie vorher mittels Formel in einer Variablen abgelegt haben.
Wenn Sie statt einen numerischen Wert zu übergeben in der URL einen Text je nach Formel gegen einen anderen ersetzen müssen, wie z.B. bei Shelly WLAN Steckdosen, können Sie dies so schreiben: ${if expr`text1`text2}. Das "Apostroph" ist ein backtick (ASCII code 96). Ist die 'expr' != 0, wird text1 eingesetzt, andernfalls text2. Für Shelly WLAN Steckdose sieht die URL dann z.B. so aus: http://<ip-addr>/relay/0?turn=${if expr`on`off}, d.h. bei expr != 0 ruft der Charging Manager dann http://<ip-addr>/relay/0?turn=on auf, andernfalls http://<ip-addr>/relay/0?turn=off.

Geben Sie als URL einen relativen Pfad an, nimmt der Charging Manager die für das jeweilige Gerät konfigurierte Adresse. Geben Sie als Domain 'localhost' an, nimmt der Charging Manager die Adresse des Gerätes auf dem er läuft. Erkennt er dabei einen Zugriff auf sein eigenes API, verwendet er den internen handler, statt einen vollen HTTP Zugriff auszuführen, so dass Sie in der Zählerdefinition keinen Benutzernamen und Passwort hinterlegen müssen. Eine URL, die mit einem * beginnt, veranlasst den Charging Manager dazu, immer einen vollen HTTP Zugriff auszuführen.

Definition der query langage:

Derzeit können in den "query" Such-Ausdrücken member names und die Operatoren "." und "[]" verwendet werden, Beispiele:

testElement namens "test"
name1.name2Element "name2" in Unterobjekt "name1"
name[idx]Element "idx" des Objekt-Elements "name". "idx" kann eine Zahl sein, z.B. für Arrays oder ein String
name["u2"]Element "u2" des Objekt-Elements "name", entspricht "name.u2"
name[{ "el1": "v1", "el2": 3}].valueArray Element, das die Bedingung der Objekt-Notation erfüllt, auswählen und Element namens 'value' auswerten. Hier wird z.B. im Array 'name' das Element ausgewählt, das als Objekt Elemente 'el1' mit Wert 'v1' und 'el2' mit Wert 3 hat und dann von diesem Object der Wert des Elements 'value' zurückgeliefert.

Globale Charging Manager Variablen:

In der Charging Manager Konfiguration können Sie Variablen anlegen. Als Wert können Sie einen festen Wert oder eine Formel verwenden. Am Ende jedes Update-Zyklus berechnet der Charging Manager den Wert dieser Variablen ggf. neu. Diese können Sie dann in (bestimmten) Charging Manager Parametern, Charging Regeln oder zur Steuerung von Outputs heranziehen. Sie können als Variable auch Ex.member oder Mx.member schreiben. Hierbei ist Ex und Mx die Geräte ID einer im Charging Manager eingerichteten Wallbox bzw. Zähler. member ist eine "benutzerdefinierte" Variable, die in dem entsprechenden Gerät gespeichert wird. Manche der Variablen können eine besondere Bedeutung haben: Bei KEBA ist "out1" ein Schaltausgang, bei ABB B23 Zählern sind "out1" und "out2" Schaltausgänge (bei Modellen, die das unterstützen). Eine 1 schaltet den Ausgang, eine 0 schaltet ihn wieder ab.

Globale Charging Manager Outputs:

In der Charging Manager Konfiguration können Sie, wie oben in der Zählerdefinition unter 'Outputs' beschrieben, globale Outputs konfigurieren. Diese werden am Ende jede Update-Zyklus gesetzt, sofern sich ihr Zustand verändert hat. Wenn Sie Schaltausgänge in benutzerdefinierten Geräten ansteuern wollen, empfiehlt sich die obige Konvention (s. Charging Manager Variablen): Sie setzen im Benutzerdefinierten Zähler Variablen mit Namen "out1", "out2", etc. und richten im benutzerdefinierten Zähler outputs ein, die in Abhängigkeit vom Wert dieser Variablen den Output schalten.

Globales Modbus API des Charging Managers:

Das Modbus API des Charging Managers dient dazu, Modbus Geräte anzusteuern, die eine beliebige (vom Charging Manager erreichbare) Modbus RTU oder TCP Adresse haben. Als Adresse für Modbus RTU geben Sie, wie in der Konfiguration der einzelnen Geräte COMx,bd,8,p,s an, wobei x die COM Port Nummer, bd die Baudrate, p die Parität ('N', 'E' oder 'O') und s die Anzahl der Stopbits ist (1 oder 2). Bei Modbus TCP ist die Adressee die IP Adresse des Gerätes im Netzwerk des Charging Managers inklusive Port-Nummer.
Die URL (für HTTP GET) des Modbus API lautet:
/cnf?cmd=modbus_get bzw. /cnf?cmd=modbus_set
Folgende weitere query Parameter unterstützt der cFos Charging Manager:
addr: Die oben genanne Modbus RTU oder TCP Geräte-Adresse.
func: Modbus Funktionsnummer, z.B. für Lesen 3 oder 4, für Schreiben 6 oder 16.
id: Geräte ID des Modbus Gerätes.
reg: Die Modbus Register Nummr. Der Wert kann in dezimal oder hex (mit Präfix 0x) angegeben werden.
val: number, Wert, der in das Register geschrieben werden soll. Weglassen beim Lesen.
type: 'w' 16bit (default), d = 32bit, f = float, q = 64bit, s = string.
cnt: number, die maximal Länge des Strings in Registern, bei anderen Typen weglassen oder auf 1 setzen.
order: String, die byte order, entweder "hl" oder "lh".

Hinweis: Wenn Ihr 'Zähler' in erster Linie Steuerungsaufgaben hat, können Sie in den Einstellungen dieser Kachel die Option 'Gerät verbergen' anhaken, damit dieses Gerät nicht auf der Startseite erscheint.

Hinweis: Manche Zähler, die mittels HTTP gelesen werden, benötigen Benutzername/Passwort als Autorisierung. Dies können sie in der Adresse für den HTTP-Zugriff mit angeben, z.B. mit http://username:password@192.168.2.111. Sollte Ihr Benutzername oder Passwort ein "@" enthalten, müssen Sie dieses durch "%40" ersetzen.