Benutzerdefinierte Zähler

Hinweis: Der HEM2 / DLM Pro 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 HEM2 / DLM Pro 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 HEM2 / DLM Pro MQTT topics und parst Nachrichten, die unter dem topic veröffentlicht werden, als JSON. Zum Parsen verwendet der HEM2 / DLM Pro hierbei eine kleine „query language“. Hier noch die Dokumentation der MQTT Fähigkeiten im HEM2 / DLM Pro.

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 HEM2 / DLM Pro Variablen und globalen HEM2 / DLM Pro 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 HEM2 / DLM Pro alles steuern und es hilft uns, den HEM2 / DLM Pro 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 HEM2 / DLM Pro 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. 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 HEM2 / DLM Pro 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 HEM2 / DLM Pro 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 HEM2 / DLM Pro 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.
user_info: Soforn vorhanden, wird hier ein beliebiger zusätzlicher Wert in der Kachel angezeigt, z.B. die Temperatur eines Batteriespeichers.
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.
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 HEM2 / DLM Pro, 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 HEM2 / DLM Pro 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.
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 HEM2 / DLM Pro 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 HEM2 / DLM Pro 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 HEM2 / DLM Pro 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 HEM2 / DLM Pro verwenden. Der HEM2 / DLM Pro 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 HEM2 / DLM Pro 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 HEM2 / DLM Pro 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 HEM2 / DLM Pro die für das jeweilige Gerät konfigurierte Adresse. Geben Sie als Domain ‚localhost‘ an, nimmt der HEM2 / DLM Pro 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 HEM2 / DLM Pro 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.

Definition der query langage:

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

test	Element namens „test“
name1.name2	Element „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}].value	Array 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 HEM2 / DLM Pro Variablen:

In der HEM2 / DLM Pro 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 HEM2 / DLM Pro den Wert dieser Variablen ggf. neu. Diese können Sie dann in (bestimmten) HEM2 / DLM Pro 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 HEM2 / DLM Pro 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 HEM2 / DLM Pro Outputs:

In der HEM2 / DLM Pro 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. HEM2 / DLM Pro 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 HEM2 / DLM Pro:

Das Modbus API des HEM2 / DLM Pro dient dazu, Modbus Geräte anzusteuern, die eine beliebige (vom HEM2 / DLM Pro 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 HEM2 / DLM Pro 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