Modbus útmutató a TapHome készülékekhez

Modbus egy egyszerű kommunikációs protokoll, amelyet gyakran használnak HVAC eszközök integrálására. Tömb master-slave kommunikációt használ, ahol egy közös buszhoz több eszköz is csatlakozhat, mindegyiknek egyedi Slave ID-vel kell rendelkeznie, és a master eszköz mindig lekérdezi az egyes slave eszközöket, amelyek válaszolnak.

Master–Slave topológia

Általában a TapHome olyan üzemmódban használható, ahol a Core Modbus Master a vezérlőegység, és a csatlakoztatott eszközök Modbus Slave-ek. Ezt a Hardware → Modbus RTU vagy Modbus TCP szekcióban állítják be. Lehet azonban fordított irányt is használni, amikor a TapHome Core információkat szolgáltat egy felügyeleti rendszernek a saját eszközeiről. Ezt az Eszközök megosztása → Modbus RTU vagy Modbus TCP szekcióban definiálják.

Fizikai rétegek

A Modbus különböző fizikai rétegekben kommunikálhat:

• soros vonalon keresztül, tipikusan RS485. Ezt Modbus RTU-nak nevezik
• LAN hálózaton keresztül TCP/IP protokollal
• LAN hálózaton UDP protokollal – ezt a TapHome rendszer jelenleg nem támogatja

Modbus regiszterek

A Modbus négy típusú regisztert határoz meg:

• több regiszter olvasása
• egy regiszter olvasása
• több regiszter írása

Néhány Modbus-implementáció további parancsokat ad hozzá: Slave ID riportálása, bitmaszkolás, írás és olvasás egyszerre stb., de ezeket a TapHome nem támogatja. {.is-warning}

Az, hogy melyik regiszterben mi van tárolva és milyen formátumban, a gyártó által adott Modbus dokumentáció része. Példa Modbus dokumentációra egy Modbus eszközhöz:

A C típusú regiszter (Coil), index 58, mivel csak 2 értéke van (nyitva/zárva), és az olvasáson felül írási lehetőség is van, a TapHome eszközök között ennek megfelelő típusa a digitális kimenet.

Gyors integrációs útmutató Modbus eszköz TapHome-ba

1. Csatlakoztassa az eszközt a megfelelő zárbuszhoz (Modbus RTU és ASCII) vagy a LAN-hoz (Modbus TCP). TCP eszköz esetén győződjön meg róla, hogy ugyanabban a hálózatban van, mint a TapHome Core vezérlő, például a Fing (iOS, Android) vagy IP Scanner (Windows) alkalmazásokkal.
2. A TapHome → Hardware menüpont alatt adjon hozzá egy új Modbus RTU vagy Modbus TCP interfészt, és állítsa be a kommunikációs paramétereket a dokumentáció szerint. Modbus RTU esetén ezek a Baud rate, Stop bitek, Paritás, Data bitek; Modbus TCP esetén pedig az IP cím.
3. A Modbus eszköz dokumentációjából derítse ki, mely Slave ID-t használ. Modbus TCP esetén ezt néha Unit ID-nek nevezik. Ha több eszközt kíván használni ugyanazon a buszon Modbus RTU-ban, minden eszköz Slave ID-jét úgy kell megváltoztatni, hogy az adott buszvonalon egyedi legyen.
4. Kommunikáció tesztelése – a Manual operations eszközzel próbálja ki, olvassa be néhány információt a dokumentáció (Modbus táblázat) alapján a kiválasztott eszközhöz. Ha minden rendben, meg kell jelennie a kiolvasott értéknek.
5. Ha a kommunikációs teszt sikeres, hozzon létre egy Modbus eszközt reprezentáló Modult.
6. Válassza ki, mely információkat szeretné megjeleníteni a TapHome rendszerben a Modbus dokumentációból, és hozzon létre hozzájuk megfelelő eszközöket. Kezdje értékek olvasásával (Read script), és ha aktorokról van szó, folytassa írással (Write script).
7. Ha az alapvető funkciók rendben működnek, adjon meg hibát, figyelmeztetést vagy információt a scriptben.
8. Szükség szerint definiálhat Service Attributes és Service Actions-t a TapHome eszközökhöz és modulokhoz.
9. Ha minden beállítás kész és a kommunikáció rendben van, exportálja a Modult XML fájlba, hogy legközelebb is használhassa. Csatlakozhat a közösséghez a github.com/taphome-official/modbus_templates oldalon is.

Implementáció a TapHome-ban

Ez a dokumentáció olyan esetet ír le, ahol a TapHome Core Modbus Master, és a Hardware → Modbus RTU / TCP részhez hozzáadott fizikai eszközök Modbus Slave-ek.

Felület

Hardware → Modbus RTU: az eszközök egy adott BUS-hoz vannak csatlakoztatva, meghatározzák az RS485 átviteli paramétereit, például baud rate, paritás, stop bitek, vagy hogy az adatok ASCII vagy bináris formátumban kerülnek átvitelre. Ezen a buszon csak olyan eszközök lehetnek, amelyek ugyanazokkal a kommunikációs beállításokkal rendelkeznek. A helyes kommunikáció csak akkor működik, ha az A és B vezetékek megfelelően vannak csatlakoztatva. Hardware → Modbus TCP: az eszközök ugyanabban a LAN-ban vannak, mint a TapHome Core vezérlő. Meghatároznak egy közös TCP portot, amely minden ehhez a felülethez csatlakozó eszközre érvényes.

Modul

A felület tartalmazhat egy vagy több modult, amelyek legtöbbször a fizikai eszköz teljes Modbus kommunikációját fedik le. Konfiguráció szempontjából a modul határozza meg a Modbus RTU-hoz csatlakozó eszköz egyedi Slave ID-jét, illetve a Modbus TCP-hez tartozó IP címet.

Eszköz

Kifejezett vezérlőelem vagy szenzor a TapHome rendszerben. Mindig egy magasabb szintű Modullal kell rendelkeznie.

5 klímaberendezés egy buszon közös Modbus RTU interfészt használ, amely meghatározza a buszportot, az átviteli sebességet és egyéb kommunikációs paramétereket. A felület 5 modulból áll, amelyek mindegyike egy-egy klímaberendezést reprezentál egyedi Slave ID-vel. Minden modul alatt olyan eszközök találhatók, mint például termosztát, hűtési/fűtési mód, ventilátor teljesítmény vagy a lamellák döntése. Az egyes eszközök olvasó és/vagy Modbus értékírási parancsokkal rendelkeznek.

Támogatott eszközök:

• Digitális kimenet
• Analóg kimenet
• Termosztát
• Többértékű kapcsoló
• Hőmérséklet-érzékelő
• Elektromérő
• Állapotkapcsoló
• Gomb
• Változó

Szkriptek Modbus-értékek olvasására és írására

A TapHome eszközök fizikai Modbus eszközökkel a szkriptjeiken keresztül kommunikálnak.

További információ a szkriptnyelvről, különösen a Bitműveletek szekcióról

A Modbus eszközökkel történő kommunikációhoz a következő szkript szekciók tartoznak:

• Init szkript: fut, amikor az eszköz elindul (például a vezérlőegység újraindítása után)
• Read szkript: beolvasási értékek beállítása vagy hibás állapotok olvasása
• Read value szkript: a Modbus eszközről konkrét érték (mennyiség) olvasása (például a termosztát beállított hőmérséklete vagy mért hőmérséklete)
• Write value szkript: érték írása a Modbus eszközbe

Funkciók Modbus eszközökkel való kommunikációhoz

MODBUSR (Modbus Read)

Modbus regiszter olvasására szolgáló függvény. A adattípustól függően lehet 1 regiszter (16 bites típusokhoz), 2 regiszter (32 bites típusokhoz) vagy több regiszter (String típusokhoz).

MODBUSR(typ_registra, adresa_registra, dátový_typ, [VOLITEĽNÉ: počet_znakov ak data_type=String])

Példa: MODBUSR(H, 20, Int16)/100
Olvassa be a H típusú, 20-as számú (vagy című) regisztert, és értelmezze 16 bites előjeles egész számként. Végül ossza el 100-zal (ez a tizedesvesszőt 2 helyet tolja jobbra).

A regiszter címe hex formátumban is megadható, például a 20 címet 0x14-ként is fel lehet tüntetni.

MODBUSW (Modbus Write)

MODBUSW(typ_registra, adresa_registra, dátový_typ, hodnota_na_zápis)

Példa: MODBUSW(H, 20, Int16, Te * 100)
Írja be a Te változó értékét a H típusú, 20-as című regiszterbe, és szorozza meg 100-zal (a tizedesvessző két hellyel jobbra tolása).

MODBUSWNE (Modbus Write if Not Equal)

Ugyanaz, mint a MODBUSW, de az értéket először beolvassa, és csak akkor írja be, ha a beírandó érték különbözik a beolvasott értéktől. A teljes művelet hosszabb időt vesz igénybe, és tipikusan moduláris beállítások EEPROM-ba történő írására használják korlátozott írási ciklusokkal.

A MODBUSR, MODBUSW és MODBUSWNE csak Modbus szkriptben használható. Más szkriptekben használva hibát okoznak.

Modbus adatformátumok

A regiszterek tartalma a Modbus táblázatban van meghatározva. Mivel egy Modbus regiszter 16 bit, a leggyakoribb a 16 bites értékek Int16 vagy Uint16, és a tizedes helyek osztással kerülnek meghatározásra 10 vagy 100 értékkel. Néhány eszköz azonban 16 bites regisztereket használ lebegőpontos értékekkel (Float), vagy megváltoztatott bitrendezéssel (big endian, little endian), egy számot két regiszterbe írva (32 bites variációk). Néha a legegyszerűbb módja annak, hogy megtudja a helyes adattípust, a TapHome alkalmazáson belüli (Kézi műveletek) eszköz használata, ahol 1 vagy több regisztert be lehet tölteni, és az adattípust dinamikusan lehet váltani.

• Int16: -32,768 és 32,767 között
• Uint16: 0 és 65,535 között
• Int32: -2 147 483 648 és 2 147 483 647 között
• Uint32: 0 és 4 294 967 295 között
• Float: IEEE 754 egyszeres pontosságú lebegőpontos szám
• Bool: 0 = hamis, 1 = igaz
• BigEndianInt16 = Int16
• LittleEndianInt16
• BigEndianUint16 = Uint16
• LittleEndianUint16
• BigEndianInt32 / BigEndianInt32ByteSwap
• LittleEndianInt32 / LittleEndianInt32ByteSwap
• BigEndianUint32 / BigEndianUint32ByteSwap
• LittleEndianUint32 / LittleEndianUint32ByteSwap
• BigEndianFloat / BigEndianFloatByteSwap
• LittleEndianFloat / LittleEndianFloatByteSwap
• String: A BCD formátum szintén használható a TOBCD() és FROMBCD() függvényekkel

Frissítés és lekérdezés intervalluma

Minden Modbus interfészen lévő eszköz rendelkezik egy definiált attribútummal: a Poll Interval-lal. Ez határozza meg, milyen gyakran kérdezze le a TapHome a Modbus eszköz új értékeit. A Modbus kommunikáció Master-Slave típusú, ezért a Modbus eszköz adatai csak akkor érkezhetnek a TapHome-ba, amikor azokat a TapHome lekéri. Minél hosszabb a Poll Interval, annál később frissül az érték a TapHome-ban. Túl rövid Poll Interval esetén a TapHome feleslegesen terhelheti a buszt a lekérdezésekkel, és nem biztos, hogy minden eszközt el tud látni a megadott időkereten belül. Például Modbus RTU és alacsony Baud Rate esetén a kérések/válaszok akár tizedmásodpercek is lehetnek. Hőmérők esetén általában elegendő a 15000 ms (15 s) intervallum, a gomboknál pedig a lehető legkisebb, pl. 50 ms. Néhány Modbus eszköz megköveteli, hogy a master periodikusan beírja az aktuális értéket a regiszterbe. Ezt szolgálja a Periodic Write attribútum.

Hibakezelési definíciók a szkriptből

Bizonyos szkriptekben hiba / figyelmeztetés / információ definiálható az eszközön, a Modbus regiszterekből olvasott információk alapján. Ezek a Reportok a TapHome-ban ugyanúgy jelennek meg, mint a belső hibajelzések. Opcionálisan a hibához számkód is rendelhető, ha ez hasznos a Modbus eszköz szervizelése szempontjából.

Az eszközön csak egy kód nélküli hibaüzenet vagy egy adott hibakódhoz tartozó hibaüzenet definiálható.

ADDERROR(), ADDWARNING(), ADDINFO()
ADDERROR([custom_code], text)

Példa: az Analog Output Read Script szekciójában a kód:

1
2
3
4
5
6
7

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");

…ami a készüléken ilyen üzenetekként jelenik meg:

Szerviz attribútumok és műveletek

A modulok és TapHome eszközök nemcsak értékeket olvashatnak Modbus eszközökről, hanem szerviz attribútumokat is olvashatnak, illetve szerviz műveleteket is végrehajthatnak. Ezek a munkafelületen nem érhetők el más felhasználók számára, csak a Modbus eszközről adnak részletes információkat, és nem terhelik meg a rendszert sok változóval és művelettel.

Szerviz attribútumok a modul vagy TapHome eszköz szerviz beállításainál jelennek meg. Általában az eszközről származó információk megjelenítésére szolgálnak, például Model, Szerelési szám, Firmware verzió, Hardver verzió, az utolsó újraindítás óta eltelt idő stb. Hasznos információk a Modbus eszköz szervizelése szempontjából, de nem érdemes belőlük önálló TapHome eszközt létrehozni.

Szerviz műveletek a modul vagy TapHome eszköz szerviz beállításainál jelennek meg alul, gombként. Megnyomásuk után végrehajtják a beállított Modbus műveletet, amely a kívánt információkat beírja a regiszterbe. Például Slave ID beállítása vagy cseréje, szűrőcsere jelzése, egy számláló beállítása a kívánt értékre, eszköz resetelése és hasonlók.

Szkriptek és segédváltozók a modulhoz

Globális modulváltozók

A modulhoz definiált változók minden, a modulhoz rendelt szkriptben elérhetők, és megoszthatók a modulhoz rendelt összes eszközzel.

Init szkript

Szabadon választható. A modul indulásakor fut le. Ha meg van adva és még nem futott le, nem futtathatók további szkriptek.

• 💬 Visszatérési érték: figyelmen kívül hagyva
• ⚙️ Változókhoz való hozzáférés: a modul globális változói
• ⚠️ Hibakezelés támogatott: nem

Read szkript

Minden lekérdezéskor lefut a modulnál.

• 💬 Visszatérési érték: figyelmen kívül hagyva
• ⚙️ Változókhoz való hozzáférés: a modul globális változói
• ⚠️ Hibakezelés támogatott: igen

Write szkript

Indítási mód:

• eszközváltozó módosításakor
• ha engedélyezett a “Periodic Write” attribútum, akkor automatikusan lefut
• 💬 Visszatérési érték: figyelmen kívül hagyva
• ⚙️ Változókhoz való hozzáférés: a modul globális változói, az adott modulhoz tartozó eszközök globális változói (figyelem: ezek nem az eszköz globális változói – a modul szkriptje nem fér hozzájuk). Ezt használják, ha több eszköz értékeit egyetlen regiszterbe kell írni.
• ⚠️ Hibakezelés támogatott: nem

Szerviz attribútumok

Minden modulnak tetszőleges számú szerviz attribútuma definiálható. A szkriptjeik akkor hajtódnak végre, amikor a felhasználó (szerviz jogosultsággal) megnyitja a modul szerviz beállításainak képernyőjét az alkalmazásban. Ezek a modul felett jelennek meg, közvetlenül a Modbus eszköz olvasása után.

• 💬 Visszatérési érték: az adott attribútum értéke jelenik meg
• ⚙️ Változókhoz való hozzáférés: a modul globális változói
• ⚠️ Hibakezelés támogatott: nem

Szerviz műveletek

Minden modulnak és eszköznek tetszőleges számú szerviz művelete definiálható. A szkriptek akkor futnak le, amikor a felhasználó (szerviz jogosultsággal) megnyitja az alkalmazásban a szerviz beállítások képernyőjét, és megnyomja a szerviz művelet nevű gombot. Minden szerviz művelet a saját nevével, paramétereivel és végrehajtó szkriptjével van definiálva.

• 💬 Visszatérési érték: figyelmen kívül hagyva
• ⚙️ Változókhoz való hozzáférés: a modul globális változói, a felhasználó által megadott paraméterek
• ⚠️ Hibakezelés támogatott: nem

Hasznos eszközök

Sablonból hozzáadni

Lehetővé teszi a Modbus kommunikáció modulhoz való konfigurálását a Modbus protokoll részletes ismerete nélkül. Előre elkészített sablonokat talál:

• közvetlenül az alkalmazásban: Sablonból hozzáadás → válassza ki a konkrét eszközt → töltse ki az alapadatokat és erősítse meg. Ezeket a sablonokat a közösségi git projektben a https://github.com/taphome/modbus_templates oldalon kezelik, és bárki javasolhat új módosításokat. Ami az alkalmazásokba kerül, azt közvetlenül a TapHome csapata hagyja jóvá.
• saját XML fájlban: Sablonból hozzáadás → Fájlból hozzáadás. Létrehozhat saját XML fájlt, amely a teljes sablont közvetlenül a Modbus modulhoz definiálja, a Kontextus menüben (3 pont a jobb felső sarokban) a Sablonként mentés funkcióval. Örömmel vesszük, ha bővíti a támogatott eszközök körét, és XML fájljával hozzájárul a közösségi git projekthez.

További információ a Modbus konfigurálásáról sablonok segítségével

Manuális műveletek

Gyakorlati eszköz a Modbus táblázat gyors ellenőrzéséhez. Lehetővé teszi:

• a következő X regiszter beolvasását egy adott regisztertől kezdve, majd a beolvasott értékek dinamikus átváltását különböző adattípusokra
• érték írását a megadott regiszterbe

Slave azonosítók szkennelése

A Modbus eszközzel való kommunikáció beállításakor a gyártói alapértelmezett Slave ID gyakran nem 1, és nehéz meghatározni a megfelelő számot. Ezt a célt szolgálja ez az eszköz. Képes a megadott Slave ID-tartományban végigkeresni és megkísérelni egy adott regiszter olvasását a kiválasztott Slave ID-vel.

Regiszterinformációk

A Modbus modul alján található. Minden használt regiszter esetében a következő információk találhatók:

• annak a TapHome eszköznek a neve, amely ebből olvas vagy erre ír
• az utolsó sikeres regiszterolvasás dátuma és időpontja
• a regiszterből olvasott utolsó érték
• az utolsó sikeres írás dátuma és időpontja a regiszterben
• az utolsó regiszterbe írt érték

Haladó beállítások

Prefetch

A TapHome egy listát hoz létre azokról a regiszterekről, amelyeket a beállított Poll intervallum alapján Modbus eszközökről olvasni vagy írni kell. A Prefetch az a folyamat, amelynek során a vezérlő előre betölti a frissítés közben szükséges értékeket a gyorsítótárba. Célja a kérések és a kölcsönös üzenetváltások számának minimalizálása. A Prefetchet két beállítás befolyásolja:

• Max prefetch regiszter csoport mérete (a modul szerviz beállításai között): meghatározza az egyszerre Modbus kommunikációval olvasható vagy írható regiszterek maximális számát.
• Prefetch mód (minden eszköznél testre szabható):
  • No prefetch. Ennél az eszköznél nem történik előolvasás. Ez azt jelenti, hogy az értékeket egyesével olvassák ki, éppen akkor, amikor a szkript lefut. Például DALI átalakítóval az adott fény értékének közvetlen olvasása nem lehetséges, ezt az értéket minél hamarabb meg kell kérni; a konverter előkészíti, és ezt csak utána adja vissza. Ebben az esetben az előolvasás értelmetlen.
  • Isolated prefetch. Több regisztert olvas egyszerre, de csak azokat a regisztereket, amelyeket ebben az eszközben definiáltunk. Például ha az adott termosztátnál a 3-as és 4-es regiszterek szükségesek, míg az 1, 2, 5, 6 más eszközöknél vannak használva, akkor a 3-as és 4-es regiszterek lekérése önállóan történik ennél a két regiszternél. Néhány Modbus eszköz ezt megköveteli.
  • Normal prefetch. Minden, a frissítésre váró eszközök által igényelt regisztert a lehető legkevesebb kéréssel olvas. Abban az esetben, ha nem összefüggő regisztersorozatról van szó, akkor a nem használt regiszterek is beolvasásra kerülhetnek, ha korábban már sikeresen olvashatók voltak. Példa: 99-es és 101-es regiszterek kérése. Ha a 100-as regiszter korábban sikeresen olvasva volt, és a Max prefetch regiszter csoport mérete 3 vagy több, akkor egyetlen kérésben három regisztert olvas a 99-es regisztertől kezdve. Ha a 100-as regisztert senki nem használja, és soha nem volt sikeresen olvasva, fennáll a kockázata annak, hogy egy ilyen regiszteren végzett olvasás Modbus kivételt dobhat a teljes kérésre.

A Prefetch közvetlenül is befolyásolható a szkript által: ha olvasáskor az SC vagy SH regisztert használjuk (a C vagy H helyett), az érték egyesével olvasódik a szkript futása közben, és nem a gyorsítótárból kerül kiolvasásra. Írás esetén, ha a regiszterhez az SC vagy SH típust használjuk (a C vagy H helyett), az értéket egyesével írják be, és más Modbus funkcióval. A Modbus protokoll 4 írási funkciót támogat: több H írása, több C írása, egy H regiszter írása vagy egy C regiszter írása egyszerre. Figyelem: nem minden eszköz támogatja mind a négy funkciót. Így, ha szükséges, az olvasás és írás összevonható és „egyenként” végrehajtható.

TCP Port (Modbus TCP)

A legtöbb esetben az alapértelmezett érték 502, de előfordulhat, hogy egyes eszközök más porton hallgatnak.

Időkorlát olvasás/írás

Az az idő, amely után a TapHome feladja a válaszra várást, és hibát jelez: „Timeout”. Ez azt jelenti, hogy az eszköz nem válaszolt a megadott időn belül.

• Lassú Modbus eszközök esetén hosszabb időkorlátokra lehet szükség (1+ másodperc).
• Magas időkorlátok felesleges késleltetést okozhatnak a többi Modbus eszköz számára, amelyek válaszra várnak.

Kérések közötti késleltetés

Az a késleltetés, amelyet a TapHome beépít a Modbus eszközökhöz tartó egyes kérések között.

📌 Fontos információk az eszközökről:

• Néhány Modbus TCP eszköz akár 5000 ms-t is igényel a kérések között.
• Néhány Modbus RTU eszköz rövidebb késleltetéseket tesz lehetővé és gyorsabban kommunikál.

ASCII kommunikáció használata

A Modbus ASCII kevésbé gyakori szabvány, ahol a kommunikáció nem bináris formátumban, hanem ASCII karakterekkel történik.

• Ezek az eszközök általában 7 adatbit beállítást igényelnek.