• Simple configuration using templates

Inleiding tot Modbus

Modbus is een eenvoudig communicatieprotocol dat vaak wordt gebruikt om HVAC-apparatuur te integreren. Het maakt gebruik van master-slave-communicatie, wanneer meerdere apparaten op de gemeenschappelijke bus kunnen worden aangesloten, moet elk een uniek slave-ID hebben en het masterapparaat vraagt altijd de individuele slave-apparaten die erop reageren.

Master - slave-topologie

In de meeste gevallen wordt TapHome gebruikt in de modus waarin de Core-besturingseenheid Modbus Master is en de aangesloten apparaten Modbus Slave zijn. Dit wordt ingesteld in de sectie Hardware → Modbus RTU of Modbus TCP. Het is echter ook mogelijk om de tegenovergestelde richting te gebruiken, wanneer TapHome Core een ander superieur systeem voorziet van informatie over zijn apparaten. Het wordt gedefinieerd in sectie Apparaten blootleggen → Modbus RTU of Modbus TCP.

Fysieke lagen

Modbus kan communiceren via verschillende fysieke lagen:

• via een seriële lijn, typisch RS485. Dit wordt Modbus RTU . genoemd
• via het LAN-netwerk via het TCP/IP-protocol
• via het LAN-netwerk via het UDP-protocol - momenteel niet ondersteund door het TapHome-systeem

Modbus-registers

Modbus definieert 4 soorten registers:

Het registernummer is 16 bits, dat wil zeggen dat het een waarde kan hebben van 0 tot 65535. Bewerkingen kunnen op de registers worden uitgevoerd:

• meerdere registers lezen
• registratie van één register
• registratie van meerdere registers

Informatie over wat er in welk register en in welk formaat is opgeslagen, maakt deel uit van de apparatuurdocumentatie die wordt verstrekt door de leverancier of fabrikant van de apparatuur. Een voorbeeld van Modbus-documentatie van een leverancier van Modbus-apparaten:

Registreer type C (spoel), index 58, omdat het slechts 2 waarden heeft (open / gesloten) en naast lezen en schrijven het juiste type TapHome-apparaat digitale uitvoer mogelijk maakt.

Versnelde instructies voor het integreren van een Modbus-apparaat in TapHome

1. Sluit het apparaat aan op de juiste bus (voor Modbus RTU en ASCII) of op het LAN (voor Modbus TCP). Zorg er bij een TCP-apparaat voor dat het zich op hetzelfde netwerk bevindt als de TapHome Core-controller, bijvoorbeeld met Fing (iOS, Android) of IP Scanner (Windows).
2. Voeg in TapHome → Hardware een nieuwe Modbus RTU- of Modbus TCP-interface toe en stel de communicatieparameters in volgens de documentatie. Voor Modbus RTU is dit baudrate, stopbits, pariteit, databits, voor Modbus TCP is dit het IP-adres.
3. Zoek in de Modbus-documentatie van het apparaat welke Slave-ID het gebruikt. In het geval van Modbus TCP wordt dit soms Unit-ID genoemd. Als u met Modbus RTU meerdere apparaten op één bus wilt gebruiken, moet u de Slave-ID van elk apparaat wijzigen zodat deze uniek is voor de gegeven buslijn.
4. Communicatietest - probeer met behulp van de tool Handmatige bewerkingen wat informatie te lezen volgens de documentatie (Modbus-tabel) voor het gegeven apparaat. Als alles werkt, zou u een uitlezing moeten zien.
5. Als de communicatietest succesvol was, maak dan een module aan die het Modbus-apparaat vertegenwoordigt
6. Kies welke informatie uit de Modbus-documentatie u in het TapHome-systeem wilt presenteren en maak de bijbehorende apparaten aan. Begin met het lezen van de waarden (Lees script), en in het geval van acteurs, ga verder met schrijven (Schrijf script).
7. Als de basisfuncties van het apparaat werken, voegt u fout-, waarschuwings- of informatiedefinities toe aan de scripts.
8. Indien nodig kunt u ook servicekenmerken en serviceacties voor TapHome-apparaten en -modules definiëren
9. Als alles is afgestemd en correct communiceert, exporteert u de module naar een XML-bestand zodat u het de volgende keer kunt gebruiken. Je kunt ook bijdragen aan de community op github.com/taphome-official/modbus_templates

Implementatie in TapHome

Deze documentatie is bedoeld voor het scenario waarin de TapHome Core-besturingseenheid een Modbus-master is en de fysieke apparaten die worden toegevoegd aan de sectie Hardware → Modbus RTU / TCP Modbus-slaves zijn.

Hiërarchie

Koppel

Hardware → Modbus RTU: apparaten zijn aangesloten op sommige BUS, de basisparameters van RS485-transmissie zijn gedefinieerd, zoals baudrate, pariteit, stopbits, of dat de gegevens ASCII of binair zijn. Op deze bus kunnen alleen apparaten met dezelfde communicatie-instellingen worden aangesloten. Ook kan correcte communicatie alleen werken als de A- en B-kabels correct zijn aangesloten. Hardware → Modbus TCP: apparaten zijn aangesloten op hetzelfde LAN als de Core-besturingseenheid. Er is één TCP-poort gedefinieerd, die gemeenschappelijk is voor alle apparaten die op deze interface zijn aangesloten.

Module

Een interface kan een of meer modules bevatten, die in de meeste gevallen de communicatie met het hele fysieke apparaat dekken. Vanuit een configuratieoogpunt definieert de module de unieke Slave-ID van het aangesloten apparaat voor Modbus RTU, en bovendien het IP-adres voor Modbus TCP.

Apparaat

Vertegenwoordigt een specifiek bedieningselement of sensor in het TapHome-systeem. Het moet altijd deel uitmaken van één bovenliggende module.

Ondersteunde apparaten:

• Digitale uitgang
• Analoge uitgang
• Thermostaat
• Meerwaardenschakelaar
• Temperatuursensor
• Elektriciteits meter
• Statuscontact
• Knop
• Een variabele

Scripts voor het lezen en schrijven van Modbus-waarden

TapHome-apparaten communiceren met fysieke Modbus-apparaten via scripts.

Voor communicatie met Modbus-apparaten zijn daarop scriptsecties gedefinieerd:

• Script initialiseren: wordt uitgevoerd wanneer het apparaat start (bijv. nadat de besturingseenheid opnieuw is opgestart)
• Leesscript: instellingswaarden van globale variabelen of leesfoutstatussen
• Read Value script: script voor het uitlezen van een specifieke waarde (hoeveelheid) van een Modbus-apparaat (bijv. ingestelde temperatuur op de thermostaat of gemeten temperatuur op de thermostaat)
• Write Value script: schrijf de waarde naar het Modbus-apparaat

Functies voor communicatie met Modbus-apparaten

MODBUSR (Modbus lezen) Functie voor het uitlezen van register uit Modbus. Afhankelijk van het datatype kan dit 1 register zijn (voor 16-bit datatypes), 2 registers (voor 32-bits datatypes) of meer registers (voor String datatypes)

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

Lees het H-registernummer (of adres) 20 en interpreteer het als een 16-bits geheel getal (een geheel getal met een +- teken). Deel tot slot deze waarde door het getal 100 (schuif de komma 2 plaatsen naar links).

MODBUSW (Modbus Schrijven)

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

Schrijf in register H met adres 20 de waarde van de variabele Te vermenigvuldigd met het getal 100 (de komma met 2 naar rechts verschuivend).

MODBUSWNE (Modbus schrijven indien niet gelijk)

Hetzelfde als MODBUSW met het verschil dat het de waarde uit het register leest voordat het wordt geschreven, en het alleen schrijft als de geschreven waarde verschilt van de gelezen waarde. De hele operatie duurt langer en wordt meestal gebruikt bij het instellen van de eigenschappen van een Modbus-apparaat, waarbij de configuratie met een beperkt aantal schrijfbewerkingen naar het EEPROM-geheugen wordt geschreven.

Modbus-gegevenstypen

De inhoud van de registers wordt gedefinieerd in de modbus-tabel. Aangezien de grootte van één Modbus-register 16 bits is, worden 16-bits Int16- of UInt16-waarden het vaakst gebruikt en worden decimalen afgeteld in delen van 10 of 100. Maar sommige Modbus-apparaten gebruiken ook 16-bits registers met zwevende -puntnummers (Float), of ze hebben een gewijzigde bitvolgorde (big endian, little endian), ze schrijven één nummer in twee registers (32-bits variaties). Soms is de gemakkelijkste manier om het juiste gegevenstype te achterhalen, het hulpprogramma rechtstreeks in de TapHome-toepassing (Handmatige bewerkingen) te gebruiken, waar u 1 of meer registers kunt laden en dynamisch van gegevenstype kunt wisselen.

• Int16 (-32.768 tot 32.767)
• Uint16 (0 tot 65.535)
• Int32 (-2.147.483.648 tot 2.147.483.647)
• Uint32 (0 tot 4.294.967.295)
• Float (IEEE 754 Single Precision floating point)
• Bool 0 = onwaar, 1 = waar
• BigEndianInt16 = Int16
• LittleEndianInt16
• BigEndianUint16 = Uint16
• LittleEndianUint16
• BigEndianInt32 / BigEndianInt32ByteSwap
• LittleEndianInt32 / LittleEndianInt32ByteSwap
• BigEndianUint32 / BigEndianUint32ByteSwap
• LittleEndianUint32 / LittleEndianUint32ByteSwap
• BigEndianFloat / BigEndianFloatByteSwap
• LittleEndianFloat / LittleEndianFloatByteSwap

• Snaar

  Het BCD-formaat kan ook worden gebruikt, dankzij de functies TOBCD() en FROMBCD()

Update en poll-interval

Elk apparaat in de Modbus-interface heeft een gedefinieerd Poll Interval-attribuut. Dit bepaalt hoe vaak de TapHome-regeleenheid moet pollen naar nieuwe Modbus-apparaatwaarden. Modbus-communicatie is van het Master-Slave-type, en dus kan informatie van het Modbus-apparaat TapHome alleen bereiken wanneer TapHome daarom vraagt. Hoe langer het poll-interval, hoe later de waarde in TapHome wordt vernieuwd. Een te kort poll-interval kan betekenen dat TapHome onnodig wordt belast met het verkrijgen van onnodige waarden en mogelijk geen tijd heeft om alle apparaten binnen het gegeven tijdsinterval te bedienen. Bijvoorbeeld met Modbus RTU en lagere baudrate-snelheden, b.v. 9600, één vraag/antwoord kan tientallen ms duren. Voor thermometers is in de meeste gevallen een interval van 15000ms (15s) voldoende, voor knoppen juist zo min mogelijk, b.v. 50 ms. Sommige Modbus-apparaten verwachten dat de master periodiek de huidige waarde naar het register schrijft. Dit is waar het attribuut Periodiek schrijven voor is.

Definitie van foutstatussen van scripts

In sommige scripts is het mogelijk om een fout / waarschuwing / informatie op het apparaat te definiëren, op basis van de informatie die wordt gelezen uit de Modbus-registers van het apparaat. Deze berichten worden in TapHome op dezelfde manier weergegeven als interne TapHome-foutmeldingen. Optioneel kan een numerieke foutcode worden toegevoegd aan de foutmelding als dit praktisch is voor onderhoud aan het Modbus-apparaat.

ADDERROR(), ADDWARING(), ADDINFO()

ADDERROR([Optional: custom_code], text)

Voorbeeld: in de sectie Script lezen van het analoge uitvoerapparaat staat een 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");

...wat op het apparaat wordt weergegeven door berichten:

Servicekenmerken en acties

Naast een waarde (of meerdere waarden, zoals een thermostaat) van een aangesloten Modbus-apparaat, kunnen TapHome-modules en apparaten ook serviceattributen uitlezen of serviceacties uitvoeren. Deze zijn dan niet toegankelijk op de desktop voor andere gebruikers van het systeem, maar dienen alleen voor meer gedetailleerde informatie over het Modbus-apparaat, zonder het systeem onnodig te overbelasten met een groot aantal variabelen en acties.

Service-attributen worden weergegeven in de service-instellingen van de TapHome-module of het apparaat. Meestal worden ze gebruikt om informatie over het apparaat weer te geven, zoals model, serienummer, firmwareversie, hardwareversie, tijd sinds de laatste keer opnieuw opstarten, enz. Dit is nuttige informatie voor het onderhoud van een Modbus-apparaat, maar het heeft geen zin om er aparte TapHome-apparaten voor te maken.

Serviceacties worden weergegeven in de service-instellingen van de TapHome-module of het apparaat, helemaal onderaan als knoppen. Als ze worden ingedrukt, voeren ze een vooraf ingestelde Modbus-actie uit die de vereiste informatie naar het register schrijft. Gebruiksvoorbeeld: Slave-ID instellen of wijzigen, filter vervangen, teller op gewenste waarde instellen, apparaat resetten en dergelijke.

Handige hulpprogramma's

Toevoegen vanuit sjabloon

Hiermee kunt u Modbus-communicatie met het apparaat configureren zonder enige kennis van het Modbus-protocol of hoe u het in TapHome moet configureren. Vooraf gemaakte sjablonen zijn te vinden:

• direct in de applicatie: Toevoegen vanuit sjabloon → selecteer een specifiek apparaat → vul de basisinformatie in en bevestig. Al deze sjablonen worden onderhouden in een community git-project op https://github.com/taphome/modbus_templates en iedereen kan daar nieuwe mods voorstellen. Wat in de apps terechtkomt, moet rechtstreeks worden goedgekeurd door het TapHome-team
• in uw eigen XML-bestand: Toevoegen vanuit sjabloon → Toevoegen vanuit bestand. U kunt uw eigen XML-bestand maken dat de volledige sjabloon definieert, rechtstreeks op de Modbus-module, in het contextmenu (3 stippen rechtsboven), Opslaan als sjabloonactie. We zullen blij zijn als je ons helpt om het aantal ondersteunde apparaten uit te breiden en je XML-bestand bij te dragen aan het gezamenlijke community git-project.

Meer informatie over het configureren van Modbus-communicatie met behulp van sjablonen

Handmatige bewerkingen

Een praktisch hulpmiddel voor een snelle eerste verificatie van de Modbus-tabel. Staat toe:

• laad de volgende X-registers in de tabel vanuit een specifiek register en schakel de leeswaarden vervolgens dynamisch in verschillende gegevenstypen
• schrijf de waarde naar het opgegeven register

Scan Slave-ID's

Een gebruikelijke praktijk bij het opzetten van communicatie met een Modbus-apparaat is dat de standaard Slave-ID in de fabriek anders is dan 1, en het is niet eenvoudig om het juiste nummer te bepalen. Daar is dit hulpprogramma voor. Het kan het gespecificeerde Slave-ID-bereik scannen door altijd met het geteste Slave-ID te proberen uit het geselecteerde register te lezen.

Informatie over registers

Deze bevindt zich in het onderste deel van de Modbus-module. Voor elk gebruikt register bevat het informatie over:

• De TapHome-naam van het apparaat dat ernaar leest of ernaar schrijft
• Datum en tijd van de laatste succesvolle lezing van het register
• De laatste waarde gelezen uit het register
• Datum en tijd van de laatste succesvolle registratie in het register
• De laatste waarde die naar het register is geschreven

Geavanceerde instellingen

Prefetch

TapHome maakt een lijst met registers om van te lezen en naar Modbus-apparaten te schrijven, afhankelijk van het ingestelde Poll-interval. Prefetch is een proces waardoor de besturingseenheid vooraf de waarden in de buffer ophaalt die het tijdens de update nodig heeft. Het doel is om het aantal aanvragen en retourvluchten te minimaliseren.

Prefetch wordt beïnvloed door 2 instellingen:

• Max prefetch register group size (te vinden in de service-instellingen van de module): bepaalt het maximum aantal registers dat kan worden gelezen of geschreven via Modbus-communicatie met één verzoek.
• Prefetch-modus (instelbaar voor elk apparaat):
• Geen prefetch. Er wordt niet vooraf geladen voor dit apparaat. Dit betekent dat de waarden afzonderlijk en precies worden gelezen wanneer het script wordt uitgevoerd. Gebruiksvoorbeeld: bij communicatie met een DALI-converter kan de waarde van een specifieke lamp niet direct worden uitgelezen, maar moet deze zo snel mogelijk worden aangevraagd, de converter zal deze voorbereiden en pas daarna retourneren. Voorladen is in dit geval zinloos.
• Geïsoleerde prefetch. Het laadt meerdere registers tegelijk, maar alleen de registers die in dit apparaat zijn gedefinieerd. Bijvoorbeeld wanneer ik registers 3 en 4 in het thermostaatapparaat nodig heb, worden registers 1, 2, 5, 6 gebruikt in de andere apparaten, dus de aanvraag voor registers 3 en 4 zal alleen voor deze 2 registers apart worden gedaan. Sommige Modbus-apparaten hebben dit nodig.
• Normaal vooraf ophalen. Alle aangevraagde registers van de te herstellen apparaten worden geprobeerd te lezen met een minimum aantal verzoeken. In het geval van een niet-continue reeks registers leest het ook registers die niet worden gebruikt, als ze in het verleden met succes zijn gelezen. Voorbeeld: Er wordt gevraagd om register 99 en 101. Als register 100 in het verleden met succes is gelezen en de maximale grootte van de prefetch-registergroep 3 of meer is, worden 3 registers gelezen met één verzoek van register 99. Als register 100 nergens wordt gebruikt en nooit met succes is gelezen, bestaat het risico dat het doorlezen van een dergelijk register een Modbus-uitzondering kan opleveren, b.v. "Illegaal gegevensadres" als antwoord op het gehele verzoek.

Prefetch kan ook rechtstreeks vanuit het script worden beïnvloed: als we het SC- of SH-register (in plaats van C of H) gebruiken bij het lezen, dan wordt de waarde register voor register gelezen tijdens de uitvoering van het script en wordt deze niet opgehaald uit het cachegeheugen. Evenzo, wanneer we schrijven, als we SC- of SH-register gebruiken (in plaats van C of H), wordt de waarde register voor register geschreven en door een andere modbus-functie. Modbus-protocol ondersteunt 4 schrijffuncties: schrijven van meerdere H, meerdere C, schrijven van één H- of één C-register tegelijk. Let op: mogelijk ondersteunen niet alle apparaten al deze functies. Zo kunnen lezen en schrijven, indien nodig, "één voor één" met elkaar worden gecombineerd.

TCP-poort (Modbus TCP)

In de meeste gevallen is de standaardwaarde 502, maar het is mogelijk dat sommige apparaten op een andere poort luisteren.

Lees/Schrijf Time-out

De tijd waarna TapHome het wachten op een reactie opgeeft en een "Time-out"-fout meldt, wat betekent dat het apparaat niet binnen het opgegeven tijdsinterval op het verzoek heeft gereageerd. Langzame Modbus-apparaten kunnen mogelijk niet snel reageren en het is noodzakelijk om dit interval te verlengen tot de orde van 1 of enkele seconden. Maar pas op voor onnodig hoge waarden, want als om de een of andere reden de communicatie met een Modbus-apparaat uitvalt, vertraagt dit onnodig andere Modbus-apparaten die wachten op een reactie.

Vertraging tussen verzoeken

De vertraging die TapHome invoegt tussen individuele verzoeken aan een Modbus-apparaat. Voor Modbus TCP is dit standaard 0 ms, voor Modbus RTU is deze vertraging volgens de specificatie gebaseerd op de communicatiesnelheid (baudrate) van minimaal 3,5 tekens. Er zijn echter Modbus TCP-apparaten die tot 5000 ms nodig hebben tussen verzoeken, of omgekeerd, sommige Modbus RTU-apparaten kunnen zelfs kortere vertragingen aan en kunnen daarom sneller communiceren.

Gebruik ASCII-communicatie

Modbus ASCII is een minder gebruikte standaard waarbij de communicatie niet binair is, maar met ASCII-tekens. De meeste van deze apparaten gebruiken ook de instelling "7 databit".