• Simple configuration using templates

Einführung in Modbus

Modbus ist ein einfaches Kommunikationsprotokoll, das häufig zur Integration von HLK-Geräten verwendet wird. Es verwendet die Master-Slave-Kommunikation, wenn mehrere Geräte an den gemeinsamen Bus angeschlossen werden können, jedes eine eindeutige Slave-ID haben muss und das Master-Gerät immer die einzelnen Slave-Geräte abfragt, die ihm antworten.

Master-Slave-Topologie

In den meisten Fällen wird TapHome in dem Modus verwendet, in dem die Core-Steuereinheit Modbus Master und die angeschlossenen Geräte Modbus Slave sind. Dies wird im Abschnitt Hardware → Modbus RTU oder Modbus TCP eingestellt. Es ist jedoch auch möglich, die umgekehrte Richtung zu verwenden, wenn TapHome Core einem anderen übergeordneten System Informationen über seine Geräte zur Verfügung stellt. Sie wird im Abschnitt Geräte freigeben → Modbus RTU oder Modbus TCP definiert.

Physikalische Schichten

Modbus kann über verschiedene physikalische Schichten kommunizieren:

• über eine serielle Leitung, typischerweise RS485. Dies wird als Modbus RTU bezeichnet
• über das LAN-Netzwerk über das TCP/IP-Protokoll
• über das LAN-Netzwerk über das UDP-Protokoll - derzeit nicht vom TapHome-System unterstützt

Modbus-Registrierungen

Modbus definiert 4 Arten von Registern:

Die Registernummer ist 16 Bit lang, d. h. sie kann einen Wert von 0 bis 65535 annehmen. An den Registern können Operationen durchgeführt werden:

• Lesen mehrerer Register
• Registrierung eines Registers
• Registrierung mehrerer Register

Informationen darüber, was in welchem Register und in welchem Format gespeichert wird, sind Bestandteil der Gerätedokumentation, die vom Gerätelieferanten oder -hersteller bereitgestellt wird. Ein Beispiel für eine Modbus-Dokumentation von einem Anbieter von Modbus-Geräten:

Registertyp C (Coil), Index 58, da es nur 2 Werte (offen/geschlossen) hat und zusätzlich zum Lesen und Schreiben erlaubt, ist der geeignete TapHome-Gerätetyp Digitalausgang.

Beschleunigte Anweisungen zur Integration eines Modbus-Geräts in TapHome

1. Schließen Sie das Gerät an den entsprechenden Bus (für Modbus RTU und ASCII) oder an das LAN (für Modbus TCP) an. Stellen Sie bei einem TCP-Gerät sicher, dass es sich im selben Netzwerk wie der TapHome Core-Controller befindet, z. B. mit Fing (iOS, Android) oder IP Scanner (Windows).
2. Fügen Sie in TapHome → Hardware eine neue Modbus RTU- oder Modbus TCP-Schnittstelle hinzu und stellen Sie die Kommunikationsparameter gemäß der Dokumentation ein. Für Modbus RTU ist es Baudrate, Stoppbits, Parität, Datenbits, für Modbus TCP ist es IP-Adresse.
3. Finden Sie in der Modbus-Dokumentation des Geräts heraus, welche Slave-ID es verwendet. Im Fall von Modbus TCP wird dies manchmal als Einheiten-ID bezeichnet. Wenn Sie mehrere Geräte an einem Bus mit Modbus RTU verwenden möchten, müssen Sie die Slave-ID jedes einzelnen so ändern, dass sie für die jeweilige Buslinie eindeutig ist.
4. Kommunikationstest – versuchen Sie mit dem Tool „Manuelle Operationen“, einige Informationen gemäß der Dokumentation (Modbus-Tabelle) für das jeweilige Gerät zu lesen. Wenn alles funktioniert, sollten Sie eine Anzeige sehen.
5. Wenn der Kommunikationstest erfolgreich war, erstellen Sie ein Modul, das das Modbus-Gerät darstellt
6. Wählen Sie aus der Modbus-Dokumentation aus, welche Informationen Sie im TapHome-System präsentieren möchten, und erstellen Sie die entsprechenden Geräte. Beginnen Sie mit dem Lesen der Werte (Read script) und fahren Sie bei Aktoren mit dem Schreiben fort (Write script).
7. Wenn die Grundfunktionen des Geräts funktionieren, fügen Sie den Skripten Definitionen für Fehler, Warnungen oder Informationen hinzu.
8. Bei Bedarf können Sie auch Dienstattribute und Dienstaktionen für TapHome-Geräte und -Module definieren
9. Wenn alles abgestimmt ist und korrekt kommuniziert, exportieren Sie das Modul in eine XML-Datei, damit Sie es das nächste Mal verwenden können. Sie können auch unter github.com/taphome-official/modbus_templates zur Community beitragen

Implementierung in TapHome

Diese Dokumentation ist für das Szenario vorgesehen, in dem die TapHome Core-Steuereinheit ein Modbus-Master ist und die physischen Geräte, die dem Abschnitt Hardware → Modbus RTU / TCP hinzugefügt werden, Modbus-Slaves sind.

Hierarchie

Schnittstelle

Hardware → Modbus RTU: Geräte sind an einigen BUS angeschlossen, die grundlegenden Parameter der RS485-Übertragung sind definiert, wie z Baudrate, Parität, Stoppbits oder ob die Daten ASCII oder Binär sind. An diesem Bus können nur Geräte mit den gleichen Kommunikationseinstellungen angeschlossen werden. Außerdem kann eine korrekte Kommunikation nur funktionieren, wenn die A- und B-Kabel richtig angeschlossen sind. Hardware → Modbus TCP: Geräte sind mit demselben LAN wie die Core-Steuereinheit verbunden. Es wird ein TCP-Port definiert, der allen an dieser Schnittstelle angeschlossenen Geräten gemeinsam ist.

Modul

Eine Schnittstelle kann ein oder mehrere Module enthalten, die in den meisten Fällen die Kommunikation mit dem gesamten physikalischen Gerät abdecken. Aus Konfigurationssicht definiert das Modul die eindeutige Slave-ID des angeschlossenen Geräts für Modbus RTU und zusätzlich die IP-Adresse für Modbus TCP.

Gerät

Stellt ein bestimmtes Bedienelement oder einen Sensor im TapHome-System dar. Es muss immer Teil eines übergeordneten Moduls sein.

Unterstützte Geräte:

• Digitaler Ausgang
• Analogausgang -Thermostat
• Mehrwertschalter
• Temperatursensor
• Stromzähler
• Statuskontakt
• Taste
• Eine Variable

Skripte zum Lesen und Schreiben von Modbus-Werten

TapHome-Geräte kommunizieren mithilfe von Skripten mit physischen Modbus-Geräten.

Für die Kommunikation mit Modbus-Geräten sind darauf Skriptabschnitte definiert:

• Initialisierungsskript: wird beim Start des Geräts ausgeführt (z. B. nach einem Neustart der Steuereinheit)
• Skript lesen: Werte globaler Variablen setzen oder Fehlerzustände lesen
• Read Value script: Skript zum Lesen eines bestimmten Werts (Menge) von einem Modbus-Gerät (z. B. eingestellte Temperatur am Thermostat oder gemessene Temperatur am Thermostat)
• Write Value script: Schreibt den Wert auf das Modbus-Gerät

Funktionen zur Kommunikation mit Modbus-Geräten

MODBUSR (Modbus lesen) Funktion zum Lesen von Registern aus Modbus. Je nach Datentyp kann es 1 Register (für 16-Bit-Datentypen), 2 Register (für 32-Bit-Datentypen) oder mehr Register (für String-Datentypen) sein.

MODBUSR(register_type, register_address, data_type, [OPTIONAL: number_of_characters if data_type=String])
Example: MODBUSR(H, 20, Int16)/100

Lesen Sie die H-Registernummer (oder Adresse) 20 und interpretieren Sie sie als 16-Bit-Integer (eine ganze Zahl mit einem +-Zeichen). Teilen Sie abschließend diesen Wert durch die Zahl 100 (verschieben Sie das Komma um 2 Stellen nach links).

MODBUSW (Modbus-Schreiben)

MODBUSW(register_type, register_address, data_type, value_to_write)
Example: MODBUSW(H, 20, Int16, Te * 100)

Schreiben Sie in das Register H mit der Adresse 20 den Wert der Variablen Te multipliziert mit der Zahl 100 (Verschiebung des Dezimalpunktes um 2 nach rechts).

MODBUSWNE (Modbus schreiben, wenn nicht gleich)

Dasselbe wie MODBUSW mit dem Unterschied, dass es den Wert vor dem Schreiben aus dem Register liest und ihn nur schreibt, wenn der geschriebene Wert sich vom gelesenen unterscheidet. Der gesamte Vorgang dauert länger und wird typischerweise beim Einstellen der Eigenschaften eines Modbus-Geräts verwendet, bei dem die Konfiguration mit einer begrenzten Anzahl von Schreibvorgängen in den EEPROM-Speicher geschrieben wird.

Modbus-Datentypen

Die Inhalte der Register sind in der Modbus-Tabelle definiert. Da die Größe eines Modbus-Registers 16 Bit beträgt, werden am häufigsten 16-Bit-Int16- oder UInt16-Werte verwendet, und Dezimalstellen werden durch Divisionen von 10 oder 100 heruntergezählt. Einige Modbus-Geräte verwenden jedoch auch 16-Bit-Register mit Floating -Punktzahlen (Float), oder sie haben eine veränderte Bitreihenfolge (Big Endian, Little Endian), sie schreiben eine Zahl in zwei Register (32-Bit-Variationen). Manchmal ist es am einfachsten, den richtigen Datentyp herauszufinden, indem Sie das Dienstprogramm direkt in der TapHome-Anwendung (manuelle Operationen) verwenden, wo Sie 1 oder mehrere Register laden und den Datentyp dynamisch wechseln können.

• Int16 (-32,768 bis 32,767)
• Uint16 (0 bis 65.535)
• Int32 (-2.147.483.648 bis 2.147.483.647)
• Uint32 (0 bis 4.294.967.295)
• Float (IEEE 754 Single Precision Floating Point)
• Bool 0 = falsch, 1 = wahr
• BigEndianInt16 = Int16 -LittleEndianInt16
• BigEndianUint16 = Uint16 -LittleEndianUint16
• BigEndianInt32 / BigEndianInt32ByteSwap
• LittleEndianInt32 / LittleEndianInt32ByteSwap
• BigEndianUint32 / BigEndianUint32ByteSwap
• LittleEndianUint32 / LittleEndianUint32ByteSwap
• BigEndianFloat / BigEndianFloatByteSwap
• LittleEndianFloat / LittleEndianFloatByteSwap

• Schnur

  Dank der Funktionen TOBCD() und FROMBCD() kann auch das BCD-Format verwendet werden

Aktualisierungs- und Abfrageintervall

Jedes Gerät in der Modbus-Schnittstelle hat ein definiertes Poll-Intervall-Attribut, das bestimmt, wie oft die TapHome-Steuereinheit neue Modbus-Gerätewerte abfragen soll. Die Modbus-Kommunikation ist vom Master-Slave-Typ, und daher können Informationen vom Modbus-Gerät TapHome nur dann erreichen, wenn TapHome sie anfordert. Je länger das Poll-Intervall, desto später wird der Wert in TapHome aktualisiert. Ein zu kurzes Abfrageintervall kann dazu führen, dass TapHome unnötig belastet wird, indem es unnötige Werte erhält, und möglicherweise keine Zeit hat, alle Geräte innerhalb des angegebenen Zeitintervalls zu bedienen. Zum Beispiel mit Modbus RTU und niedrigeren Baudratengeschwindigkeiten, z. 9600 kann eine Abfrage / Antwort mehrere zehn Millisekunden dauern. Bei Thermometern ist in den meisten Fällen ein Intervall von 15000ms (15s) ausreichend, bei Tastern dagegen so wenig wie möglich, z.B. 50 ms. Einige Modbus-Geräte erwarten, dass der Master regelmäßig den aktuellen Wert in das Register schreibt. Dafür ist das Attribut Periodic Write da.

Definition von Fehlerzuständen aus Skripten

In einigen Skripten ist es möglich, einen Fehler / eine Warnung / eine Information auf dem Gerät zu definieren, basierend auf den Informationen, die aus den Modbus-Registern des Geräts gelesen werden. Diese Meldungen werden in TapHome genauso angezeigt wie interne TapHome-Fehlermeldungen. Optional kann der Fehlermeldung ein numerischer Fehlercode hinzugefügt werden, wenn dies für die Wartung des Modbus-Geräts praktikabel ist.

ADDERROR(), ADDWARING(), ADDINFO()

ADDERROR([Optional: custom_code], text)

Beispiel: Im Abschnitt „Skript lesen“ des Analogausgabegeräts befindet sich ein Code:

ADDERROR("Error without code");
ADDWARNING("Warning without code");
ADDINFO("Info without code");

ADDERROR(1, "Error with code");
ADDWARNING(1, "Warning with code");
ADDINFO(1,"Info with code");

...was sich auf dem Gerät durch Meldungen widerspiegelt:

Dienstattribute und Aktionen

Zusätzlich zu einem Wert (oder mehreren Werten, z. B. einem Thermostat) von einem angeschlossenen Modbus-Gerät können TapHome-Module und -Geräte auch Serviceattribute lesen oder Serviceaktionen ausführen. Diese sind dann auf dem Desktop für andere Benutzer des Systems nicht zugänglich, sondern dienen lediglich der näheren Information über das Modbus-Gerät, ohne das System unnötig mit einer Vielzahl von Variablen und Aktionen zu überlasten.

Dienstattribute werden in den Diensteinstellungen des TapHome-Moduls oder -Geräts angezeigt. Typischerweise werden sie verwendet, um Informationen über das Gerät anzuzeigen, wie z. B. Modell, Seriennummer, Firmware-Version, Hardware-Version, Zeit seit dem letzten Neustart usw. Dies sind nützliche Informationen aus Sicht der Wartung eines Modbus-Geräts, aber es macht keinen Sinn, separate TapHome-Geräte für sie zu erstellen.

Dienstaktionen werden in den Diensteinstellungen des TapHome-Moduls oder -Geräts ganz unten als Schaltflächen angezeigt. Wenn sie gedrückt werden, führen sie eine voreingestellte Modbus-Aktion aus, die die erforderlichen Informationen in das Register schreibt. Anwendungsbeispiel: Einstellen oder Ändern der Slave-ID, Austausch des Filters, Setzen des Zählers auf den erforderlichen Wert, Zurücksetzen des Geräts und dergleichen.

Hilfreiche Dienstprogramme

Aus Vorlage hinzufügen

Es ermöglicht Ihnen, die Modbus-Kommunikation mit dem Gerät ohne Kenntnisse des Modbus-Protokolls oder dessen Konfiguration in TapHome zu konfigurieren. Vorgefertigte Vorlagen finden Sie unter:

• direkt in der Anwendung: Aus Vorlage hinzufügen → bestimmtes Gerät auswählen → Basisdaten ausfüllen und bestätigen. Alle diese Vorlagen werden in einem Community-Git-Projekt unter https://github.com/taphome/modbus_templates gepflegt und jeder kann dort neue Mods vorschlagen. Was in die Apps gelangt, muss direkt vom TapHome-Team genehmigt werden
• in eigener XML-Datei: Aus Vorlage hinzufügen → Aus Datei hinzufügen. Sie können Ihre eigene XML-Datei erstellen, die die gesamte Vorlage direkt auf dem Modbus-Modul definiert, im Kontextmenü (3 Punkte oben rechts), Aktion Als Vorlage speichern. Wir freuen uns, wenn Sie uns helfen, die Anzahl der unterstützten Geräte zu erweitern und Ihre XML-Datei in das gemeinsame Community-Git-Projekt einbringen.

Weitere Informationen zur Konfiguration der Modbus-Kommunikation mithilfe von Vorlagen

Manuelle Operationen

Ein praktisches Tool zur schnellen Erstverifizierung der Modbus-Tabelle. Erlaubt:

• Laden Sie die folgenden X-Register aus einem bestimmten Register in die Tabelle und schalten Sie dann die gelesenen Werte dynamisch in verschiedene Datentypen um
• Wert in das angegebene Register schreiben

Slave-IDs scannen

Eine gängige Praxis beim Einrichten der Kommunikation mit einem Modbus-Gerät ist, dass die werkseitige Standard-Slave-ID nicht 1 ist und es nicht einfach ist, die richtige Nummer zu ermitteln. Dafür ist dieses Dienstprogramm da. Es kann den angegebenen Slave-ID-Bereich scannen, indem es versucht, aus dem ausgewählten Register immer mit der getesteten Slave-ID zu lesen.

Informationen zu Registern

Es befindet sich im unteren Teil des Modbus-Moduls. Für jedes verwendete Register werden Informationen aufgeführt über:

• Der TapHome-Name des Geräts, das darauf liest oder schreibt
• Datum und Uhrzeit des letzten erfolgreichen Auslesens aus dem Register
• Der letzte aus dem Register gelesene Wert
• Datum und Uhrzeit der letzten erfolgreichen Eintragung in das Register
• Der letzte in das Register geschriebene Wert

Erweiterte Einstellungen

Vorabruf

TapHome erstellt eine Liste von Registern zum Lesen und Schreiben auf Modbus-Geräten, abhängig vom eingestellten Poll-Intervall. Prefetch ist ein Prozess, dank dem die Steuereinheit die Werte, die sie während des Updates benötigt, in den Puffer vorab holt. Ziel ist es, die Anzahl der Anfragen und Roundtrips zu minimieren. Der Prefetch wird von 2 Einstellungen beeinflusst:

• Max. Prefetch-Registergruppengröße (zu finden in den Diensteinstellungen des Moduls): bestimmt die maximale Anzahl von Registern, die über die Modbus-Kommunikation mit einer Anfrage gelesen oder geschrieben werden können.
• Prefetch-Modus (für jedes Gerät einstellbar):
• Kein Vorabruf. Für dieses Gerät wird kein Vorabladen durchgeführt. Das bedeutet, dass die Werte einzeln und genau dann ausgelesen werden, wenn das Skript ausgeführt wird. Anwendungsbeispiel: Bei der Kommunikation mit einem DALI-Konverter kann der Wert einer bestimmten Leuchte nicht direkt gelesen werden, sondern muss so schnell wie möglich angefordert werden, der Konverter bereitet ihn auf und sendet ihn erst dann zurück. Jegliches Vorladen ist in diesem Fall sinnlos.
• Isolierter Prefetch. Es lädt mehrere Register auf einmal vor, aber nur die, die in diesem Gerät definiert sind. Zum Beispiel Wenn ich die Register 3 und 4 im Thermostatgerät benötige, werden die Register 1, 2, 5, 6 in den anderen Geräten verwendet, sodass die Anforderung für die Register 3 und 4 nur für diese 2 Register separat erfolgt. Einige Modbus-Geräte erfordern dies.
• Normaler Vorabruf. Es wird versucht, alle angeforderten Register von den wiederherzustellenden Geräten mit der minimalen Anzahl von Anforderungen zu lesen. Bei einer nicht kontinuierlichen Folge von Registern liest er auch nicht verwendete Register, wenn diese in der Vergangenheit erfolgreich gelesen wurden. Beispiel: Register 99 und 101 werden angefordert Wenn Register 100 in der Vergangenheit erfolgreich gelesen wurde und die Max. Prefetch-Registergruppengröße 3 oder mehr beträgt, werden 3 Register mit einer Anforderung aus Register 99 gelesen. Wenn Register 100 nirgendwo verwendet wird und noch nie erfolgreich gelesen wurde, besteht die Gefahr, dass das Lesen über ein solches Register eine Modbus-Ausnahme zurückgeben könnte, z. „Unzulässige Datenadresse“ als Antwort auf die gesamte Anfrage.

Prefetch kann auch direkt aus dem Skript beeinflusst werden: Wenn wir beim Lesen das SC- oder SH-Register (statt C oder H) verwenden, dann wird der Wert während der Ausführung des Skripts Register für Register gelesen und nicht gezogen aus dem Cache-Speicher. Wenn wir beim Schreiben das SC- oder SH-Register (anstelle von C oder H) verwenden, wird der Wert in ähnlicher Weise von einem Register nach dem anderen und von einer anderen Modbus-Funktion geschrieben. Das Modbus-Protokoll unterstützt 4 Schreibfunktionen: Schreiben mehrerer H, mehrerer C, Schreiben eines H- oder eines C-Registers gleichzeitig. Achtung: Möglicherweise unterstützen nicht alle Geräte alle diese Funktionen. Auf diese Weise können bei Bedarf Lesen und Schreiben miteinander und „nacheinander“ kombiniert werden.

TCP-Port (Modbus TCP)

In den meisten Fällen ist der Standardwert 502, aber es ist möglich, dass einige Geräte auf einem anderen Port lauschen.

Zeitüberschreitung beim Lesen/Schreiben

Die Zeit, nach der TapHome das Warten auf eine Antwort aufgibt und einen „Timeout“-Fehler meldet, was bedeutet, dass das Gerät nicht innerhalb des angegebenen Zeitintervalls auf die Anfrage geantwortet hat. Langsame Modbus-Geräte können möglicherweise nicht sofort antworten, und es ist notwendig, dieses Intervall auf eine Größenordnung von 1 oder mehreren Sekunden zu verlängern. Achten Sie jedoch auf unnötig hohe Werte, denn wenn aus irgendeinem Grund die Kommunikation mit einem Modbus-Gerät fehlschlägt, verzögert dies unnötigerweise andere Modbus-Geräte, die auf eine Antwort warten.

Verzögerung zwischen Anfragen

Die Verzögerung, die TapHome zwischen einzelnen Anfragen an ein Modbus-Gerät einfügt. Bei Modbus TCP beträgt sie standardmäßig 0ms, bei Modbus RTU beträgt diese Verzögerung laut Spezifikation bezogen auf die Kommunikationsgeschwindigkeit (Baudrate) mindestens 3,5 Zeichen. Es gibt jedoch Modbus TCP-Geräte, die bis zu 5000 ms zwischen Anfragen benötigen, oder umgekehrt, einige Modbus RTU-Geräte können sogar noch kürzere Verzögerungen verarbeiten und sind daher in der Lage, schneller zu kommunizieren.

ASCII-Kommunikation verwenden

Modbus ASCII ist ein weniger verwendeter Standard, bei dem die Kommunikation nicht binär ist, sondern ASCII-Zeichen verwendet. Die meisten dieser Geräte verwenden auch die Einstellung "7 Datenbit".