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 drei Typen: Modbus-Zähler, HTTP/JSON-Zähler und MQTT/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. Bei MQTT/JSON-Zählern abonniert der cFos Charging Manager MQTT topics und parst Nachrichten, die unter dem topic veröffentlicht werden, als JSON. Zum Parsen verwendet der cFos Charging Manager hierbei eine kleine "query language". Hier noch die Dokumentation der MQTT Fähigkeiten im cFos Charging Manager.

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 einfache Beispiel-Definition für Modbus, die ein einzelnes Register für die Wirkleistung ausliest. Die Registernummer können Sie für Ihre konkrete Anwendung einfach abwandeln:
Beispiel-Definition für ein einzelnes Register.

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.

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, 2 = MQTT/JSON. 'mtype' bestimmt den Gerätetyp: 0 = Anderes Gerät, 1 = Zähler, 2 = Wechselrichter, 4 = Batteriespeicher.

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: 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: Der Charging Manager nutzt diese Variablen, um import_wh und export_wh anzuzeigen. Bei unidirektionalen Zählern (z.B. Wechselrichtern) sollten Sie immer nur import_wh definieren. Nur bei bidirektionalen Zählern (wie Speicher oder Netzbezugszählern) solllte export_wh definiert werden.

soc: Soforn vorhanden, wird hier der State of Charge eines Batteriespeichers in % in der Kachel angezeigt.
Zusätzlich können Sie weitere Variablen mit anderem Namen definieren, die bei jedem Update ausgelesen bzw. mittels Formeln berechnet werden. Wenn Sie Variablen definieren, die mit CM. beginnen, z.B. CM._set_price, werden die zugewiesenen Werte in den globalen Charging Manager Variablen (s.u.) abgelegt und können entsprechend abgefragt werden.
Variablen mit *: Wenn Sie Variablen definieren, die mit * beginnen, werden diese im UI in der Kachel des Zählers unter erweiterten Information angezeigt, z.B. die Temperatur eines Batteriespeichers.

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, uint16, int32, uint32, float, int64, string. Dies ist für Modbus wichtig, um die Register im richtigen Format auszulesen. uint16 und uint32 sind Typen, die nur positive Zahlen annehmen können. 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.
once: bool (true oder false), falls true, wird der Wert nur einmal bei Initialisierung des Gerätes gelesen, sonst periodisch.
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' bzw 'uint16' trennt der Charging Manager low und high byte durch Punkt, bei 'int32' bzw. 'uint32' low und high word, bei 'int64' low und high dword. Bei 'lenth' 4 und 'int32' bzw. 'uint32', zerlegt der Charging Manager den Wert in 4 durch Punkt getrennte bytes. Bei 'int64' die 4 words entsprechend.
regex: String. Wird eine regular expression angegeben, braucht die Antwort des Zählers nicht in JSON vorzuliegen. Als Ergebnis wird entweder der gesamte match der regular expression oder die erste group ausgewertet. Bitte nur verwenden, wenn das Gerät kein JSON zurückliefert. Hier die Liste der features unserer regular expressions:
any char: .
named classes: \d \s \w \D \S \W
anonymous classes: [a-z0-9_], [^0-9], [^\d]
groups with alternatives: (ab|cd|ef)
non-captured groups: (?:ab|cd)
(greedy) once or none: a?, a??
(greedy) many or none: a*, a*?
(greedy) once or more: a+, a+?
begin of string: ^
end of string: $

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. Outputs werden in unter "outputs" als JSON array von Output Objekten definiert. Alle Outputs werden am Ende jedes Update Zyklus geschaltet, sofern sich der Zustand des jeweiligen Output geändert hat.
Pro Output müssen Sie in dem Output Objekt 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. Ist die URL nach allen Ersetzungen leer, wird kein Output gesetzt. So kann man z.B. Outputs nur dann schalten, wenn bestimmte Variablen existieren (s. Formeln: exists() Funktion). In der Adresse können Sie zusätzlich ${address} und ${id} angeben. Dies ist die aktuelle Geräte Adresse und Modbus ID, wie in den Einstellungen festgelegt. Address und id dienen vor allem zur Benutzung des Modbus APIs (s.u.).
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.

Outputs zurücksetzen: Zusätzlich zu einem "outputs" array können Sie auch noch ein wie das "outputs" array aufgebautes array names "resets" definieren. Damit können Outputs beim Deaktivieren des Gerätes auf ihre Ausgangswerte zurück gesetzt werden. Hiermit können Sie in Kombination mit benutzerdefinierten Variablen und "once": true das Gerät wieder in seinen Ausgangszustand versetzen.
Outputs periodisch schreiben: Bei einigen Geräten müssen die Outputs periodisch geschrieben werden, andernfalls setzt das Gerät die Werte wieder auf "Standard". Beispielsweise verwendet der Kostal Speicher wieder seine Standardregeln, wenn die Speichersteuerung eine zeitlang nicht aktiv geschrieben wurde. Um periodisch Outputs zu setzen, können Sie der Adresse ein #xxx# voranstellen, wobei xxx angibt, alle wieviel Sekunden der Output neu geschrieben wird, auch wenn der zu schreibende Wert gleich geblieben ist. Wenn beispielsweise die Adresse /cnf?cmd=set_cm_vars&name=test&val=42 lautet, können Sie mit #30#/cnf?cmd=set_cm_vars&name=test&val=42 dafür sorgen, dass dieser Wert alle 30 Sekunden geschrieben wird.

Definition der query langage:

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

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.

Falls Sie Geräte haben, die bei bestimmten Bedingungen eingeschaltet werden müssen, dann aber eine zeitlang laufen müssen (z.B. Waschmaschine, Spülmaschine), können Sie die Variable auch als "Trigger" definieren. Dann ist die Formel der Variablen die Bedingung, mit der die Variable auf 1 gesetzt wird. Nach einer einstellbaren Zeit, wird sie dann wieder auf 0 gesetzt. Eine "Retrigger-Bedingung" erlaubt die Zeit bis zum Abschalten (d.h. Setzen der Variablen auf 0) immer wieder zu verlängern, solange die Bedingung erfüllt ist.

Zu Testzwecken können Sie sich Charging Manager- und Zählervariablen anzeigen lassen, hier z.B. die aktuellen Preise von Awattar:

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.