Uniconnect

Das Uniconnect-Plugin bietet eine leistungsstarke Schnittstelle zur Kommunikation zwischen dem Controme Miniserver und verschiedenen externen Geräten, die Modbus TCP oder HTTP-APIs unterstützen. Es ermöglicht sowohl das Auslesen als auch das Senden von Daten, wodurch eine flexible und dynamische Steuerung unterschiedlichster Systeme möglich wird. Durch die Integration dieser Technologien wird eine erweiterte Systemsteuerung ermöglicht, die nicht nur auf Modbus basiert, sondern auch auf HTTP-APIs zugreifen kann, um Daten zu erfassen und Befehle an kompatible Geräte zu senden.

Dank der breiten Kompatibilität von Uniconnect lassen sich nahezu alle in der Modbus- oder HTTP-Dokumentation der jeweiligen Endgeräte definierten Werte auslesen und steuern. Dies eröffnet neue Möglichkeiten, Energieeffizienz und Automatisierung in Systemen wie Heizungen, Photovoltaikanlagen, Wärmepumpen und vielen weiteren Anwendungen zu optimieren.

Beispiel für das Abfragen eines Wertes:

Ein typisches Anwendungsbeispiel ist das Abfragen des Batterieladezustands eines Photovoltaiksystems. Auf der Grundlage dieses Parameters lässt sich eine adaptive Steuerung der Raumtemperaturen umsetzen – etwa durch die Erhöhung der Temperaturen bei hohem Batterieladezustand. So kann die überschüssige Energie effizient genutzt werden, um das Raumklima zu verbessern.

Dieses kurze Video einer frühen Entwicklerversion zeigt, wie die aktuelle Batterieladung von einem Fronius-Wechselrichter mit angebundenem Batteriespeicher abgefragt wird, um diesen Anwendungsfall zu veranschaulichen.

Beispiel für das Senden eines Wertes:

Ein weiteres Beispiel ist das Senden der Vorlauftemperaturvorgabe an eine Wärmepumpe. Anhand des aktuellen PV-Ertrags kann das System die Wärmepumpe so steuern, dass überschüssige Energie nicht ins Netz eingespeist, sondern von der Wärmepumpe genutzt wird. Dadurch lässt sich der Energieverbrauch effizienter gestalten.

Verbindungsobjekt anlegen

Im UniConnect Plugin wird über die untere Schaltfläche „Verbindungsobjekt anlegen“ (alt „Modbus anlegen“) ein Konfigurationsfenster geöffnet, welches je nach Objekttyp relevante Konfigurationsfelder anzeigt.

Der Name benennt das Verbindungsobjekt. Dieser Bezeichner kann frei gewählt werden und wird als lesbare Referenz in anderen Plugin verwendet.

Als nächstes wird der Typ des Verbindungsobjektes gewählt – diese drei Typen werden dabei unterschieden:

• Modbus TCP – Read
  löst einen zyklischen Modbus TCP Client (Master) Lesebefehl aus für einen externen Modbus TCP Registerwert, welcher von einem Modbus TCP Server (Slave) zur Verfügung gestellt wird
• Modbus TCP – Write
  löst einen zyklischen Modbus TCP Client (Master) Schreib- und Lesebefehl aus für einen externen Modbus TCP Registerwert, welcher von einem Modbus TCP Server (Slave) zur Verfügung gestellt wird
• HTTP-Get
  löst einen zyklischen HTTP-Get Lesebefehl auf eine externe API / REST Schnittstelle aus, welcher von einem Web-Server zur Verfügung gestellt wird

Die Konfiguration dieser Objekttypen werden in Folgenden näher erläutert.

Konfiguration Modbus TCP

Verbindungsobjekte vom Typ Modbus TCP – read oder Modbus TCP – write fragen Registerwerte von einem externen Gerät über eine Modbus TCP Schnittstelle ab. Verbindungsobjekte vom Typ Modbus TCP – write können zusätzlich auch Werte der Controme Steuerung in diese Register schreiben.
Die Konfiguration dieses Typs erfordert die Eingabe der folgenden Parameter:

Variable wählen (nur Modbus TCP – Write)

• Beschreibung: Wählen Sie hier aus, in welchem Plugin der auszugebenden Wert bereitgestellt wird.
  Der Standard ist hier „individuelle Berechnung per FPS Formel“. Wird hier nichts anderes gewählt, definiert das folgende Feld FPS-Formelfeld den Ausgabewert.
• Beispiel: Soll an das externe Gerät die aktuelle Außentemperatur (ermittelt vom Wetter Pro Plugin) gesendet werden, dann wählen Sie hier die entsprechend konfigurierten und benannten Wetter Pro Eintrag aus – also z.B.:
  wetterpro – Außentemperatur

FPS-Formelfeld (nur Modbus TCP – Write)

• Beschreibung: Geben Sie hier eine gültige FPS Formel ein. Diese Formel kann (wie hier beschrieben) Operatoren, Funktionen, Festwerte und/oder Variablennamen von definierten FPS-, Uniconnect-, Wetter Pro-Abfragen, Differenzregelungen, Vorlauftemperaturregelungen und Sensoren enthalten. Mehr zu Variablennamen finden Sie hier
• Beispiel: Wenn Sie der Wärmepumpe eine Heizkreis Vorlauftemperatur vorgeben wollen, die um 5K  höher ist als die aktuelle FBH-Vorlauftemperatur der Vorlauftemperaturregelung 2 , wäre eine mögliche Formel:
  vtr_2_ziel + 5

Partner-IP-Adresse

• Beschreibung: Geben Sie hier die genaue URL der Modbus TCP Schnittstelle des externen Geräts an.
• Beispiel: Wenn das externe Geräts unter der lokalen IP-Adresse 192.168.1.100 im Router aufgelistet ist, geben Sie ein:
  192.168.1.100

Partner-Port

• Beschreibung: Geben Sie hier die Portnummer ein, den die Modbus TCP Schnittstelle des externen Geräts verwendet.
• Hinweis: Der Modbus TCP Port ist in der Regel in den Geräten auf den Modbus TCP Standardwert 502 vorkonfiguriert. Sollte Ihr Gerät von dem Standard abweichen, dann finden Sie die Angabe entweder in der Geräte Dokumentation oder den aktuellen Konfigurationsdaten Ihres Gerätes.

Datenabfrageintervall in Sekunden

• Beschreibung: Legen Sie hier fest, in welchem Zeit Intervall (in Sekunden) die Daten vom externen Gerät abgefragt werden sollen. Je kürzer das Intervall, desto häufiger werden die Daten aktualisiert.
• Beispiel: Wenn Sie den Wert auf 60 setzen, wird alle 60 Sekunden eine neue Abfrage an die Modbus TCP Schnittstelle gesendet.

Registeradresse

• Beschreibung: Geben Sie hier die genaue Adresse des abzufragenden (bzw. zu schreibenden) Registers der Modbus TCP Schnittstelle des externen Geräts an. Diese finden Sie zusammen mit den wichtigen Registertypdaten in der Modbus TCP Dokumentation Ihres Geräteherstellers.
• Beispiel: Wenn die aktuelle abgegebene Leistung Ihres Wechselrichters über die Registeradresse 4023 auszulesen ist, geben Sie ein:
  4023
• Hinweis: Da die kleinste abfragbare Registeradresse auf dem Modbus 1 ist, kann es sein, dass zu den Registeradress-Angaben in der jeweiligen Modbus TCP Dokumentation, jeweils 1 addiert werden muss, wenn die Modbus TCP Schnittstellenbeschreibung vom Gerät intern bei 0 anfängt zu zählen!

Registertyp

• Beschreibung: Geben Sie hier den genauen Registertyp des abzufragenden (bzw. zu schreibenden) Registers der Modbus TCP Schnittstelle des externen Geräts an. Diese finden Sie meist als Zusatzinformation bei der Registeradresse in der Modbus TCP Dokumentation Ihres Geräteherstellers. Folgende Registertypen werden unterstützt:
  • Holding Register
  • Input Register
  • Discrete Inputs
  • Coils
• Beispiel: Wenn das relevante Register in der Liste der Holding Register aufgelistet ist, wählen Sie:
  Holding Register

Datentyp

• Beschreibung: Wählen Sie den Datentyp den das Modbus TCP Register verwendet. Diese Information entnehmen Sie der MOdbus TCP Dokumentation des Herstellers des externen Gerätes.
  Folgende Datentypen werden unterstützt:

  Datentyp	Datentyp Beschreibung	Wertebereich
  UInt8	8-Bit Ganzzahl ohne Vorzeichen	0 bis 255
  UInt16	16-Bit Ganzzahl ohne Vorzeichen	0 bis 65.535
  UInt32	32-Bit Ganzzahl ohne Vorzeichen	0 bis 4.294.967.295
  UInt64	64-Bit Ganzzahl ohne Vorzeichen	0 bis 18.446.744.073.709.551.615
  Int8	8-Bit Ganzzahl mit Vorzeichen	-128 bis 127
  Int16	16-Bit Ganzzahl mit Vorzeichen	-32.768 bis 32.767
  Int32	32-Bit Ganzzahl mit Vorzeichen	-2.147.483.648 bis 2.147.483.647
  Int64	64-Bit Ganzzahl mit Vorzeichen	-9.223.372.036.854.775.808 bis 9.223.372.036.854.775.807
  Float32	32-Bit Dezimalzahl mit Vorzeichen	ca. ±3.402823 × 10³⁸, 7 signifikante Stellen
  Float64	64-Bit Dezimalzahl mit Vorzeichen	ca. ±1.797693 × 10³⁰⁸, 15–16 signifikante Stellen
  String8	Zeichenkette mit 8-Bit Zeichenkodierung (z. B. ASCII)	Zeichenfolge aus 1–255 Zeichen
  String16	Zeichenkette mit 16-Bit Zeichenkodierung (z. B. UTF‑16)	Zeichenfolge aus 1–65.535 Zeichen
  String32	Zeichenkettemit 32-Bit Zeichenkodierung (z. B. UTF‑32)	Zeichenfolge aus 1–4.294.967.295 Zeichen
  String64	Zeichenkettemit erweiterten 64-Bit Zeichenlängen	Zeichenfolge aus 1–18.446.744.073.709.551.615 Zeichen
  Bool	Boolescher (logischer) Wert	Wahr (True) oder Falsch (False)
  DateTime	Datum-Zeit-Typ	typischerweise 1.1.0001 00:00:00 bis 31.12.9999 23:59:59 (implementierungsabhängig)
  Enum16H256	16-Bit Enumeration mit Hash256-Bezug	Ganzzahlwert 0–65.535 plus zugehöriger 256‑Bit Hash (symbolischer Schlüssel)

• Beispiel: Wenn das Modbus TCP Register ein Word (16bit Wert) ohne Vorzeichen zurückgibt, wählen Sie UInt16.

Weiterleitungs-IP-Adresse (optional)

• Beschreibung: In diesem Feld können Sie eine URL angeben, an die der abgefragte Wert nach jeder erfolgreichen Datenabfrage weitergeleitet wird. Diese Funktion ermöglicht es, die Werte von externen Sensoren, die über Uniconnect abgefragt werden, an andere Systeme oder Sensoren weiterzugeben. Der Wert kann dabei auf verschiedene Arten gerundet oder formatiert werden, je nach Bedarf.
• Anwendung: Die Werte werden von Uniconnect in verschiedenen Formaten bereitgestellt und können durch Platzhalter in der URL direkt weitergeleitet werden. Diese Platzhalter definieren, wie der Wert formatiert oder gerundet wird, bevor er an das Ziel weitergeleitet wird.
• Verfügbare Platzhalter:
  1. [value]
     • Beschreibung: Gibt den Wert ohne Rundung oder Formatierung zurück.
     • Beispiel: Bei einem Wert von 20.5678 wird 20.5678 zurückgegeben.
  2. [roundedvalue0]
     • Beschreibung: Rundet den Wert auf die nächste ganze Zahl (0 Dezimalstellen).
     • Beispiel: Bei einem Wert von 20.5678 wird 21 zurückgegeben. Bei einem Wert von 20.3 wird 20 zurückgegeben.
  3. [roundedvalue1]
     • Beschreibung: Rundet den Wert auf eine Dezimalstelle.
     • Beispiel: Bei einem Wert von 20.5678 wird 20.6 zurückgegeben. Bei einem Wert von 20.34 wird 20.3 zurückgegeben.
  4. [roundedvalue2]
     • Beschreibung: Rundet den Wert auf zwei Dezimalstellen und formatiert ihn immer auf zwei Stellen.
     • Beispiel: Bei einem Wert von 20.5678 wird 20.57 zurückgegeben. Bei einem Wert von 20 wird 20.00 zurückgegeben.
  5. [roundedvalue3]
     • Beschreibung: Rundet den Wert auf drei Dezimalstellen und formatiert ihn immer auf drei Stellen.
     • Beispiel: Bei einem Wert von 20.56789 wird 20.568 zurückgegeben. Bei einem Wert von 20 wird 20.000 zurückgegeben.
  6. [ceilvalue]
     • Beschreibung: Rundet den Wert immer auf die nächste ganze Zahl auf.
     • Beispiel: Bei einem Wert von 20.1 wird 21 zurückgegeben. Bei einem Wert von 20.9 wird ebenfalls 21 zurückgegeben.
  7. [floorvalue]
     • Beschreibung: Rundet den Wert immer auf die nächste ganze Zahl ab.
     • Beispiel: Bei einem Wert von 20.9 wird 20 zurückgegeben. Bei einem Wert von 20.1 wird ebenfalls 20 zurückgegeben.
  8. [roundedvalueQ]
     • Beschreibung: Rundet den Wert auf das nächste Viertel (0,25-Schritte).
     • Beispiel: Bei einem Wert von 20.37 wird 20.25 zurückgegeben. Bei einem Wert von 20.62 wird 20.75 zurückgegeben.
  9. [roundedvalueH]
     • Beschreibung: Rundet den Wert auf die nächste Hälfte (0,5-Schritte).
     • Beispiel: Bei einem Wert von 20.3 wird 20.5 zurückgegeben. Bei einem Wert von 20.8 wird 21.0 zurückgegeben.
• Beispiel: Angenommen, Sie möchten die Temperatur von einem Homeassistant-Sensor an das Controme-System weiterleiten, so könnte die URL wie folgt aussehen:

http://localhost/set/11_ff_7a_d0_54_15_03_8d/[value]/

Hierbei wird [value] automatisch durch den abgefragten Wert ersetzt, der über die Uniconnect-Schnittstelle ermittelt wurde. Jedes Mal, wenn der Wert gemäß dem definierten „Datenabfrageintervall“ abgefragt wird, wird er über die angegebene URL weitergeleitet.

Sie können auch externe Adressen verwenden, z. B.:

https://1011xx.fwd.controme.com/set/28_ff_7a_d0_54_15_03_8d/[value]/

Hinweis: Diese Funktion unterstützt nicht nur lokale Weiterleitungen (z. B. an localhost), sondern auch die Weiterleitung an externe Server. Dies ermöglicht eine flexible Nutzung externer Sensoren und Datenquellen, die über die Uniconnect-Abfrage eingebunden werden.

Optionalen Fehlerwert festlegen

• Beschreibung: Definieren Sie hier einen Fehlerwert, der zurückgegeben wird, wenn die Modbus TCP Abfrage fehlschlägt oder ungültige Daten erhält. Dies hilft dabei, Fehlermeldungen zu handhaben und das System auf bekannte Werte zurückzusetzen, falls es Probleme gibt.
• Beispiel: Setzen Sie z. B. den Fehlerwert auf -999, um bei einem Fehler eine spezielle Zahl als Platzhalter zu verwenden.

Multiplikator (= Normierungsfaktor)

• Beschreibung: Geben Sie hier optional einen Multiplikator ein, um den abgefragten Wert gemäß den Dokumentation des externen Geräts zu normieren. Wenn kein Multiplikator eingetragen wird, bleibt der kommunizierte Wert unverändert.
  Der Multiplikator wird vom UniConnect Plugin entsprechend auch beim Scheiben von Werten berücksichtigt.
  Wichtiger Hinweis: Wenn das Modbus TCP Register aus ein oder mehreren 16bit Werten (Words) besteht, ermöglicht erst die  Angabe von  Datentyp und Multiplikator die korrekte Interpretation des übertragener Wertes.
• Beispiel: Wenn der von der Modbus TCP Abfrage zurückgegebene Wert 325 ist, aber laut der Dokumentation des Herstellers der Wert mit einer Auflösung von 0,1 übertragen wird, dann tragen Sie als Multiplikator 0.1 ein. Das Ergebnis wäre dann 32,5.

Ausführungszeit

• Beschreibung: Dieses Feld zeigt an, wann der Wert zuletzt erfolgreich abgefragt wurde. Es wird automatisch vom System aktualisiert und dient nur zur Information.
• Beispiel: 18.09.2024 16:53 zeigt an, dass die letzte Abfrage zu diesem Zeitpunkt stattfand.

Daten

• Beschreibung: Dieses Feld zeigt den zuletzt abgefragten Wert an. Hier können Sie überprüfen, welcher Wert aktuell vom externen Gerät über die Modbus TCP Schnittstelle abgerufen wurde.
• Beispiel: Wenn der abgefragte Wert der Batterieladung 85% beträgt, wird dies hier angezeigt.

Konfiguration HTTP-GET

Verbindungsobjekte vom Typ HTTP-GET fragen Daten von einem externen Gerät über eine HTTP-API, bzw. REST Schnittstelle ab. Die Konfiguration dieses Typs erfordert die Eingabe der folgenden Parameter:

Partner-IP-Adresse

• Beschreibung: Geben Sie hier die genaue URL oder den Endpunkt der API des externen Geräts an. Dies ist die Adresse, von der die Daten per HTTP-GET abgerufen werden.
• Beispiel: Wenn die API des Geräts unter der IP-Adresse 192.168.1.100 verfügbar ist, könnte der Endpunkt z. B. so aussehen:
  http://192.168.1.100/api/status
• Stellen Sie sicher, dass der angegebene Endpunkt korrekt ist, damit die Daten erfolgreich abgefragt werden können.

Datenabfrageintervall in Sekunden

• Beschreibung: Legen Sie hier fest, in welchem Zeit Intervall (in Sekunden) die Daten vom externen Gerät abgefragt werden sollen. Je kürzer das Intervall, desto häufiger werden die Daten aktualisiert.
• Beispiel: Wenn Sie den Wert auf 60 setzen, wird alle 60 Sekunden eine neue Abfrage an die API gesendet.

Weiterleitungs-IP-Adresse (optional)

• Beschreibung: In diesem Feld können Sie eine URL angeben, an die der abgefragte Wert nach jeder erfolgreichen Datenabfrage weitergeleitet wird. Diese Funktion ermöglicht es, die Werte von externen Sensoren, die über Uniconnect abgefragt werden, an andere Systeme oder Sensoren weiterzugeben. Der Wert kann dabei auf verschiedene Arten gerundet oder formatiert werden, je nach Bedarf.
• Anwendung: Die Werte werden von Uniconnect in verschiedenen Formaten bereitgestellt und können durch Platzhalter in der URL direkt weitergeleitet werden. Diese Platzhalter definieren, wie der Wert formatiert oder gerundet wird, bevor er an das Ziel weitergeleitet wird.
• Verfügbare Platzhalter:
  1. [value]
     • Beschreibung: Gibt den Wert ohne Rundung oder Formatierung zurück.
     • Beispiel: Bei einem Wert von 20.5678 wird 20.5678 zurückgegeben.
  2. [roundedvalue0]
     • Beschreibung: Rundet den Wert auf die nächste ganze Zahl (0 Dezimalstellen).
     • Beispiel: Bei einem Wert von 20.5678 wird 21 zurückgegeben. Bei einem Wert von 20.3 wird 20 zurückgegeben.
  3. [roundedvalue1]
     • Beschreibung: Rundet den Wert auf eine Dezimalstelle.
     • Beispiel: Bei einem Wert von 20.5678 wird 20.6 zurückgegeben. Bei einem Wert von 20.34 wird 20.3 zurückgegeben.
  4. [roundedvalue2]
     • Beschreibung: Rundet den Wert auf zwei Dezimalstellen und formatiert ihn immer auf zwei Stellen.
     • Beispiel: Bei einem Wert von 20.5678 wird 20.57 zurückgegeben. Bei einem Wert von 20 wird 20.00 zurückgegeben.
  5. [roundedvalue3]
     • Beschreibung: Rundet den Wert auf drei Dezimalstellen und formatiert ihn immer auf drei Stellen.
     • Beispiel: Bei einem Wert von 20.56789 wird 20.568 zurückgegeben. Bei einem Wert von 20 wird 20.000 zurückgegeben.
  6. [ceilvalue]
     • Beschreibung: Rundet den Wert immer auf die nächste ganze Zahl auf.
     • Beispiel: Bei einem Wert von 20.1 wird 21 zurückgegeben. Bei einem Wert von 20.9 wird ebenfalls 21 zurückgegeben.
  7. [floorvalue]
     • Beschreibung: Rundet den Wert immer auf die nächste ganze Zahl ab.
     • Beispiel: Bei einem Wert von 20.9 wird 20 zurückgegeben. Bei einem Wert von 20.1 wird ebenfalls 20 zurückgegeben.
  8. [roundedvalueQ]
     • Beschreibung: Rundet den Wert auf das nächste Viertel (0,25-Schritte).
     • Beispiel: Bei einem Wert von 20.37 wird 20.25 zurückgegeben. Bei einem Wert von 20.62 wird 20.75 zurückgegeben.
  9. [roundedvalueH]
     • Beschreibung: Rundet den Wert auf die nächste Hälfte (0,5-Schritte).
     • Beispiel: Bei einem Wert von 20.3 wird 20.5 zurückgegeben. Bei einem Wert von 20.8 wird 21.0 zurückgegeben.
• Beispiel: Angenommen, Sie möchten die Temperatur von einem Homeassistant-Sensor an das Controme-System weiterleiten, so könnte die URL wie folgt aussehen:

http://localhost/set/11_ff_7a_d0_54_15_03_8d/[value]/

Hierbei wird [value] automatisch durch den abgefragten Wert ersetzt, der über die Uniconnect-Schnittstelle ermittelt wurde. Jedes Mal, wenn der Wert gemäß dem definierten „Datenabfrageintervall“ abgefragt wird, wird er über die angegebene URL weitergeleitet.

Sie können auch externe Adressen verwenden, z. B.:

https://1011xx.fwd.controme.com/set/28_ff_7a_d0_54_15_03_8d/[value]/

Hinweis: Diese Funktion unterstützt nicht nur lokale Weiterleitungen (z. B. an localhost), sondern auch die Weiterleitung an externe Server. Dies ermöglicht eine flexible Nutzung externer Sensoren und Datenquellen, die über die Uniconnect-API eingebunden werden.

Optionalen Fehlerwert festlegen

• Beschreibung: Definieren Sie hier einen Fehlerwert, der zurückgegeben wird, wenn die API-Abfrage fehlschlägt oder ungültige Daten erhält. Dies hilft dabei, Fehlermeldungen zu handhaben und das System auf bekannte Werte zurückzusetzen, falls es Probleme gibt.
• Beispiel: Setzen Sie z. B. den Fehlerwert auf -999, um bei einem Fehler eine spezielle Zahl als Platzhalter zu verwenden.

API-Datentyp

• Beschreibung: Wählen Sie den Datentyp der API-Antwort, die abgefragt wird. Dies kann Boolean, Number oder String sein, abhängig davon, welche Art von Wert die API zurückgibt.
• Beispiel: Wenn die API einen numerischen Wert für die Batterieladung zurückgibt, wählen Sie Number.

Wertpfad

• Beschreibung: Das „Wertpfad“-Feld definiert, welcher Wert aus einem JSON-Objekt extrahiert werden soll, indem der/die  Schlüsselnamen als Pfad zu dem gewünschten Wert angeben werden. Dieser Pfad beschreibt damit, wie durch das JSON-Objekt navigiert werden soll, um den gewünschten Wert zu finden.
  Trennen Sie verschachtelte Schlüsselnamen durch Punkte.
• Beispiel: JSON-Objekt ohne verschachtelte Schlüsselnamen
  Nehmen wir an, die API Abfrage ergibt folgendes JSON-Objekt:

{„temperatur“: 23.25, „solltemperatur“: 21.5, „raum“: „Wohnzimmer“}

Um den Wert  für die Raumtemperatur zu extrahieren, können Sie als Pfad direkt den Schlüsselnamen des gewünschten Wertes verwenden :
temperatur
Auf diese Weise erhalten Sie den Wert 23.25.

• Beispiel: JSON-Objekt mit verschachtelten Schlüsselnamen
  Nehmen wir an, die API Abfrage ergibt (hier gekürzt) folgendes JSON-Objekt:

{...,'data":[{"sensor"...,"battery":{"charge":95}...}]...}

Wenn Sie die Batterieladung ermitteln möchten, dann geben Sie den Pfad durch Punkte zwischen den Schlüsselnamen ein:
data.battery.charge
und Sie erhalten den Wert 95.

• Beispiel: JSON-Objekt mit verschachtelten Listen (Arrays)
  Falls das JSON-Objekt Listen enthält, müssen Sie angeben, auf welches Element innerhalb der Liste Sie zugreifen möchten. Dies geschieht durch Verwendung von Indizes in eckigen Klammern [ ], um das 0 bis n-1-te  Elements in der Liste zu bestimmen. Wenn Sie den ersten Eintrag der Liste ansteuern, ist die Indexangabe optimal und Sie können die eckigen Klammern [0] weglassen.

Nehmen wir folgendes JSON an, in dem sich zwei Sensoren in einer Liste befinden:{„sensoren“:

[{„id“: „28_84_d5_23_05_00_00_69“,„current“: 26.62},{„id“: „28_b9_dd_ee_04_00_00_ff“,„current“: 27.25}]}

Um den Wert current eines Sensors zu extrahieren, können Sie eine der folgenden Methoden verwenden:

Ausführungszeit

• Beschreibung: Dieses Feld zeigt an, wann der Wert zuletzt erfolgreich abgefragt wurde. Es wird automatisch vom System aktualisiert und dient nur zur Information.
• Beispiel: 18.09.2024 16:53 zeigt an, dass die letzte Abfrage zu diesem Zeitpunkt stattfand.

Daten

• Beschreibung: Dieses Feld zeigt den zuletzt abgefragten Wert an. Hier können Sie überprüfen, welcher Wert aktuell vom externen Gerät über die API abgerufen wurde.
• Beispiel: Wenn der abgefragte Wert der Batterieladung 85% beträgt, wird dies hier angezeigt.

Erste Schritte zur Modbus-Integration

Modbus TCP ist ein weit verbreitetes Protokoll zur Kommunikation zwischen einem Steuerungssystem (z. B. Controme) und externen Geräten wie Wärmepumpen, Wechselrichtern oder Energiemessern. Grundsätzlich funktioniert Modbus TCP über ein lokales Netzwerk (LAN), wobei jedes Modbus-fähige Gerät eine eigene IP-Adresse besitzt. Die Kommunikation erfolgt über sogenannte Registeradressen. Jeder Wert – z. B. eine Temperatur, ein Schaltstatus oder ein Energieverbrauch – ist dabei einem bestimmten Register zugewiesen.

Über Modbus können sowohl Daten gelesen (Empfang von Werten) als auch geschrieben (z. B. das Setzen einer Solltemperatur) werden. Dabei ist zu beachten, dass unterschiedliche Registertypen (Input Register, Holding Register) und verschiedene Datentypen (z. B. Integer, Float, 16- oder 32-Bit) verwendet werden. Die genaue Struktur und Bedeutung der Register muss immer aus der herstellerspezifischen Modbus-Dokumentation entnommen werden.

Diese Anleitung soll sicherstellen, dass die einzelnen Schritte in der richtigen Reihenfolge durchlaufen werden, um eine funktionierende Modbus-Kommunikation aufzubauen.

1. Registerliste vom Hersteller besorgen

Bevor eine Modbus-Kommunikation aufgebaut werden kann, ist es notwendig, Zugriff auf die Modbus-Dokumentation des Geräts zu erhalten. Diese wird in der Regel vom Hersteller bereitgestellt, kann aber auch online oder in Anwenderforen verfügbar sein. Die Liste beschreibt die verfügbaren Register und enthält idealerweise folgende Informationen:

• Registeradresse (z. B. 30001 oder 40001)
• Funktionscode (z. B. 03 = Lesen von Holding- oder Input-Registers)
• Datentyp (z. B. INT16, UINT32, FLOAT32)
• Multiplikator bzw. Skalierungsfaktor (z. B. 0.1, wenn 230 = 23,0 °C)
• Einheit (z. B. °C, %, kWh)

2. Integration in Controme UniConnect

Der wichtigste Schritt zur Überprüfung, ob die Modbus-Kommunikation grundsätzlich funktioniert, erfolgt direkt im Controme-System über das UniConnect-Plugin. Ziel ist es zunächst, einen einzelnen Registerwert auszulesen – unabhängig davon, welcher konkrete Wert dahintersteht. Es geht darum, zu prüfen, ob die Verbindung technisch funktioniert. Sofern dies erfolgreich gelingt, wird der Wert in der Zeile „Daten“ angezeigt (Beispiel).

• Im Miniserver den Bereich Software > UniConnect öffnen
• Im Footer auf den Button „Modbus anlegen“ klicken
• „Modbus-Read“ wählen
• Die in Schritt 1 erhaltenen Daten (Registeradresse, Datentyp, Multiplikator) eintragen
• Abfrage speichern (auf „Confirm“ klicken)
• Sobald das zuvor definierte Abfrageintervall verstrichen ist, öffnen Sie die Einstellungsseite erneut und scrollen Sie nach unten. In der Zeile „Daten“ sollte nun der ausgelesene Wert angezeigt werden.

Wenn ein Wert erfolgreich ausgelesen wird, ist die Verbindung grundsätzlich funktionstüchtig. Auf dieser Basis können anschließend gezielt weitere Register hinzugefügt und ggf. „Modbus-Write“-Abfragen eingerichtet werden, z. B. zum Setzen von Sollwerten.

3. Werte interpretieren und skalieren

Nach dem erfolgreichen Auslesen eines Registers sollten Sie überprüfen, ob der Wert plausibel ist. Häufige Hinweise auf Interpretationsprobleme:

• Werte wie 65535 oder 32768 deuten oft auf Fehlercodes oder unplausible Daten hin
• Bei 32-Bit-Werten ist evtl. eine andere Byte-Reihenfolge erforderlich
• Skalierung nach Multiplikator aus der Dokumentation anwenden (z. B. 230 × 0.1 = 23,0 °C)

4. Typische Fehlerquellen und Hinweise