Modbus

Modbus je jednoduchý komunikační protokol, často používaný pro integraci zařízení HVAC. Využívá komunikaci master-slave, kdy na společnou sběrnici může být připojeno několik zařízení, přičemž každé musí mít jedinečné Slave ID a master zařízení vždy dotazuje jednotlivá slave zařízení, která mu odpovídají.

Topologie Master - Slave

Ve většině případů se TapHome používá v režimu, kdy je řídicí jednotka Core Modbus Master a připojená zařízení jsou Modbus Slave. Toto se nastavuje v sekci Hardware → Modbus RTU nebo Modbus TCP. Je však možné použít i opačný směr, kdy TapHome Core poskytuje jinému nadřízenému systému informace o svých zařízeních. To je definováno v sekci Zpřístupnit zařízení → Modbus RTU nebo Modbus TCP.

Fyzické vrstvy

Modbus může komunikovat přes různé fyzické vrstvy:

• přes sériovou linku, typicky RS485. To se označuje jako Modbus RTU
• přes LAN síť pomocí TCP/IP protokolu
• přes LAN síť pomocí UDP protokolu – v současné době systémem TapHome nepodporované

Modbus registry

Modbus definuje 4 typy registrů:

• čtení více registrů
• zápis jednoho registru
• zápis více registrů

Některé implementace Modbus přidávají další příkazy: report slave id, bitové maskování, zápis a čtení najednou apod., ale tyto TapHome nepodporuje. {.is-warning}

Informace o tom, co je uloženo v kterém registru a v jakém formátu, jsou součástí dokumentace zařízení poskytnuté dodavatelem nebo výrobcem zařízení. Příklad Modbus dokumentace od dodavatele Modbus zařízení:

Typ registru C (Coil), index 58, protože má jen 2 hodnoty (otevřeno / zavřeno) a kromě čtení umožňuje i zápis, odpovídající typ TapHome zařízení je digitální výstup.

Zrychlené pokyny pro integraci Modbus zařízení do TapHome

1. Připojte zařízení k příslušné sběrnici (pro Modbus RTU a ASCII) nebo k LAN (pro Modbus TCP). U TCP zařízení se ujistěte, že je ve stejné síti jako řídicí jednotka TapHome Core, například pomocí Fing (iOS, Android) nebo IP Scanner (Windows).
2. V TapHome → Hardware přidejte nové rozhraní Modbus RTU nebo Modbus TCP a nastavte komunikační parametry podle dokumentace. Pro Modbus RTU jsou to Baud rate, Stop bits, Parity, Data bits, pro Modbus TCP je to IP adresa.
3. V dokumentaci Modbus zařízení zjistěte, jaké Slave ID používá. V případě Modbus TCP se to někdy označuje jako Unit ID. Pokud chcete použít více zařízení na jedné sběrnici s Modbus RTU, musíte změnit Slave ID každého z nich tak, aby bylo jedinečné pro danou sběrnicovou linku.
4. Test komunikace – pomocí nástroje Manual operations zkuste přečíst některé informace podle dokumentace (Modbus tabulky) pro dané zařízení. Pokud vše funguje, měli byste vidět přečtenou hodnotu.
5. Pokud byl test komunikace úspěšný, vytvořte Modul, který představuje Modbus zařízení.
6. Vyberte, které informace z Modbus dokumentace chcete prezentovat v systému TapHome a vytvořte odpovídající zařízení. Začněte čtením hodnot (Read script) a v případě aktorů pokračujte zápisem (Write script).
7. Pokud základní funkce zařízení fungují, přidejte definice Error, Warning nebo Information do skriptů.
8. V případě potřeby můžete také definovat Service Attributes a Service Actions pro TapHome zařízení a moduly.
9. Pokud je vše naladěno a komunikuje správně, exportujte Modul do XML souboru, abyste ho mohli použít příště. Můžete také přispět do komunity na github.com/taphome-official/modbus_templates.

Implementace v TapHome

Tato dokumentace je určena pro scénář, kdy je řídicí jednotka TapHome Core Modbus master a fyzická zařízení, která jsou přidána do sekce Hardware → Modbus RTU / TCP, jsou Modbus slave.

Rozhraní

Hardware → Modbus RTU: zařízení jsou připojena na určitou sběrnici, jsou definovány základní parametry přenosu RS485, jako je baudrate, parita, stop bity, nebo zda jsou data ASCII nebo binární. Na tuto sběrnici mohou být připojena pouze zařízení se stejnými komunikačními nastaveními. Správná komunikace může fungovat jen tehdy, pokud jsou A a B kabely správně připojené. Hardware → Modbus TCP: zařízení jsou připojena na stejné LAN jako řídicí jednotka Core. Je definován jeden TCP port, který je společný pro všechna zařízení připojená k tomuto rozhraní.

Modul

Rozhraní může obsahovat jeden nebo více modulů, které ve většině případů pokrývají komunikaci s celým fyzickým zařízením. Z konfiguračního hlediska modul definuje jedinečné Slave ID připojeného zařízení pro Modbus RTU a navíc IP adresu pro Modbus TCP.

Zařízení

Představuje specifický řídicí prvek nebo senzor v systému TapHome. Musí být vždy součástí jednoho nadřazeného Modulu.

[NOTE] 5 klimatizačních jednotek připojených na jedné sběrnici používá společné rozhraní Modbus RTU, které definuje port sběrnice, přenosovou rychlost a další komunikační parametry. Rozhraní obsahuje 5 modulů, z nichž každý představuje jednu klimatizační jednotku s jedinečným Slave ID. Každý modul má pod sebou definovaná zařízení, jako například termostat, režim chlazení/ohřev, výkon ventilátoru nebo naklápění lamel. Jednotlivá zařízení mají definované příkazy pro čtení a/nebo zápis Modbus hodnot.

Podporovaná zařízení:

• Digitální výstup
• Analogový výstup
• Termostat
• Dvouhodnotový spínač
• Teplotní senzor
• Elektroměr
• Stavový kontakt
• Tlačítko
• Proměnná

Skripty pro čtení a zápis Modbus hodnot

Zařízení TapHome komunikují s fyzickými Modbus zařízeními pomocí skriptů.

Více informací o skriptovacím jazyce, zejména sekce Bitové operace

Pro komunikaci s Modbus zařízeními jsou na nich definovány skriptovací sekce:

• Inicializační skript: spustí se, když se zařízení spustí (např. po restartu řídicí jednotky)
• Skript na čtení: nastavení hodnot globálních proměnných nebo čtení chybových stavů
• Skript na čtení hodnoty: skript pro čtení specifické hodnoty (veličiny) z Modbus zařízení (např. nastavená teplota na termostatu nebo naměřená teplota na termostatu)
• Skript na zápis hodnoty: zapíše hodnotu do Modbus zařízení

Funkce pro komunikaci s Modbus zařízeními

MODBUSR (Modbus Read)

Funkce pro čtení registru z Modbus. V závislosti na datovém typu to může být 1 registr (pro 16bitové datové typy), 2 registry (pro 32bitové datové typy) nebo více registrů (pro datové typy String).

MODBUSR(typ_registru, adresa_registru, datový_typ, [VOLITELNÉ: počet_znaků, pokud data_type=String])

Příklad: MODBUSR(H, 20, Int16)/100
Přečtěte registr H číslo (nebo adresu) 20 a interpretujte ho jako 16bitové celé číslo (celé číslo se znaménkem +/-). Na závěr tuto hodnotu vydělte číslem 100 (posuňte desetinnou čárku o 2 místa doleva).

Adresu registru je možné zadat i v hexadecimálním formátu, např. hodnota 20 lze zapsat jako 0x14.

MODBUSW (Modbus Write)

MODBUSW(typ_registru, adresa_registru, datový_typ, hodnota_na_zápis)

Příklad: MODBUSW(H, 20, Int16, Te * 100)
Do registru H s adresou 20 zapište hodnotu proměnné Te vynásobenou číslem 100 (posunutí desetinné čárky o 2 doprava).

MODBUSWNE (Modbus Write if Not Equal)

Stejné jako MODBUSW s tím rozdílem, že přečte hodnotu z registru před zápisem a zapíše ji jen tehdy, pokud se zapisovaná hodnota liší od přečtené. Celá operace trvá déle a její typické použití je při nastavování vlastností Modbus zařízení, kde se konfigurace zapisuje do EEPROM paměti s omezeným počtem zápisů.

Funkce MODBUSR, MODBUSW a MODBUSWNE lze použít jen v Modbus skriptech. Pokud se použijí v jiných skriptech, považují se za chybu.

Typy dat Modbus

Obsah registrů je definován v Modbus tabulce. Protože velikost jednoho Modbus registru je 16 bitů, nejčastěji se používají 16bitové hodnoty Int16 nebo UInt16 a desetinná místa se určují dělením 10 nebo 100. Některá Modbus zařízení však používají i 16bitové registry s čísly s pohyblivou desetinnou čárkou (Float), nebo mají změněné pořadí bitů (big endian, little endian), zapisují jedno číslo do dvou registrů (32bitové variace). Někdy je nejjednodušší způsob, jak zjistit správný datový typ, použít nástroj přímo v aplikaci TapHome (Ručné operace), kde můžete načíst 1 nebo více registrů a dynamicky přepínat datový typ.

• Int16: -32 768 až 32 767
• Uint16: 0 až 65 535
• Int32: -2 147 483 648 až 2 147 483 647
• Uint32: 0 až 4 294 967 295
• Float: IEEE 754 jednoduchá přesnost s pohyblivou desetinnou čárkou
• Bool: 0 = false, 1 = true
• BigEndianInt16 = Int16
• LittleEndianInt16
• BigEndianUint16 = Uint16
• LittleEndianUint16
• BigEndianInt32 / BigEndianInt32ByteSwap
• LittleEndianInt32 / LittleEndianInt32ByteSwap
• BigEndianUint32 / BigEndianUint32ByteSwap
• LittleEndianUint32 / LittleEndianUint32ByteSwap
• BigEndianFloat / BigEndianFloatByteSwap
• LittleEndianFloat / LittleEndianFloatByteSwap
• String: formát BCD může být také použit díky funkcím TOBCD() a FROMBCD()

Interval aktualizace a dotazování

Každé zařízení v Modbus rozhraní má definovaný atribut Poll Interval. Ten určuje, jak často má řídicí jednotka TapHome dotazovat nové hodnoty Modbus zařízení. Modbus komunikace je typu Master-Slave, a proto informace z Modbus zařízení mohou do TapHome přijít jen tehdy, když si je TapHome vyžádá. Čím delší je Poll Interval, tím později se hodnota v TapHome aktualizuje. Příliš krátký Poll Interval může znamenat, že TapHome bude zbytečně zatěžován získáváním nepotřebných hodnot a nemusí mít čas obsloužit všechna zařízení v daném časovém intervalu. Například u Modbus RTU a nižších rychlostí Baud Rate, např. 9600, může jedna žádost/odpověď trvat desítky ms. Pro teploměry je ve většině případů postačující interval 15000 ms (15 s), pro tlačítka naopak co nejkratší, např. 50 ms. Některá Modbus zařízení očekávají, že master bude periodicky zapisovat aktuální hodnotu do registru. Na to slouží atribut Periodic Write.

Definice chybových stavů ze skriptů

V některých skriptech je možné definovat chybu / varování / informaci na zařízení na základě informací přečtených z Modbus registrů zařízení. Tyto zprávy se zobrazují v TapHome stejně jako interní chybové zprávy TapHome. Volitelně je možné k chybové zprávě přiřadit numerický kód chyby, pokud je to praktické pro servis Modbus zařízení.

Na zařízení je možné definovat pouze jednu chybovou zprávu bez kódu nebo pouze jednu chybovou zprávu na jeden chybový kód.

ADDERROR(), ADDWARNING(), ADDINFO()
ADDERROR([Volitelné: custom_code], text)

Příklad: v sekci Read Script zařízení Analog Output je 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");

…což se na zařízení projevuje zprávami:

Servisní atributy a akce

Kromě hodnoty (nebo více hodnot, jako například termostat) z připojeného Modbus zařízení mohou moduly a zařízení TapHome číst i servisní atributy nebo vykonávat servisní akce. Tyto potom nejsou přístupné na pracovní ploše pro ostatní uživatele systému, ale slouží jen k podrobnějším informacím o Modbus zařízení, bez zbytečného přetěžování systému velkým množstvím proměnných a akcí.

Servisní atributy se zobrazují v servisních nastaveních modulu nebo zařízení TapHome. Typicky se používají k zobrazení informací o zařízení, jako jsou Model, Sériové číslo, Verze firmwaru, Verze hardwaru, Čas od posledního restartu atd. Jsou to užitečné informace z hlediska servisu Modbus zařízení, ale nemá smysl pro ně vytvářet samostatná zařízení TapHome.

Servisní akce se zobrazují v servisních nastaveních modulu nebo zařízení TapHome, úplně dole jako tlačítka. Po stisknutí vykonají přednastavenou Modbus akci, která zapíše požadované informace do registru. Příklad použití: Nastavení nebo změna Slave ID, výměna filtru, nastavení počítadla na požadovanou hodnotu, resetování zařízení a podobně.

Skripty a pomocné proměnné na modulu

Globální proměnné modulu

Proměnné definované na modulu jsou použitelné ve všech skriptech na modulu a jsou sdílené se všemi zařízeními přiřazenými k tomuto modulu.

Init Script

Volitelný. Spustí se při startu modulu. Pokud je vyplněn a ještě neběžel, nebudou povoleny žádné další skripty.

• 💬 Návratová hodnota: ignorovaná
• ⚙️ Přístup k proměnným: globální proměnné modulu
• ⚠️ Podpora chybového stavu: ne

Read Script

Spustí se při každém dotazu modulu.

• 💬 Návratová hodnota: ignorovaná
• ⚙️ Přístup k proměnným: globální proměnné modulu
• ⚠️ Podpora chybového stavu: ano

Write Script

Spuštění:

• při změně proměnné zařízení
• pokud je povolen atribut “Periodic Write”, tak se spustí automaticky
• 💬 Návratová hodnota: ignorovaná
• ⚙️ Přístup k proměnným: globální proměnné modulu, globální proměnné zařízení, specifická hodnota veličiny, která se má zapsat přes Modbus do zařízení
• ⚠️ Podpora chybového stavu: ne

Read Value Script

Spustí se při každém dotazu zařízení.

• 💬 Návratová hodnota: se automaticky přiřadí jako hodnota daného zařízení
• ⚙️ Přístup k proměnným: globální proměnné modulu, globální proměnné zařízení, naposledy načtená hodnota proměnné, která se má přečíst (užitečné například, pokud zařízení indikuje, že ještě nebylo načtené atd.)
• ⚠️ Podpora chybového stavu: ano. Chybové zprávy by se měly vztahovat na danou veličinu na zařízení. Například, pokud je příkaz ADDERROR(1, "Senzor není připojený") ve skriptu Read Temperature v zařízení Termostat, uživatel uvidí chybovou zprávu v aplikaci na termostatu se třemi informacemi: Teplota, kód 1, text “Senzor není připojený”.

Servisní atributy

Každé zařízení může mít definovaný neomezený počet servisních atributů. Skripty se vykonávají vždy, když uživatel (se servisními oprávněními) otevře obrazovku servisních nastavení zařízení v aplikaci. Jsou zapsané nahoře, ihned po přečtení z Modbus zařízení.

• 💬 Návratová hodnota: zobrazuje se jako hodnota daného atributu
• ⚙️ Přístup k proměnným: globální proměnné modulu, globální proměnné zařízení
• ⚠️ Podpora chybového stavu: ne

Servisní akce

Každé zařízení může mít definovaný neomezený počet servisních akcí. Skripty se vykonávají, když uživatel (se servisními oprávněními) otevře aplikaci na obrazovce servisních nastavení zařízení a stiskne jedno z definovaných tlačítek s názvem servisní akce. Každá servisní akce je definovaná svým názvem, parametry a vykonávacím skriptem.

• 💬 Návratová hodnota: ignorovaná
• ⚙️ Přístup k proměnným: globální proměnné modulu, globální proměnné zařízení, uživatelem zadané parametry
• ⚠️ Podpora chybového stavu: ne

Užitečné nástroje

Přidat ze šablony

Umožňuje konfiguraci Modbus komunikace se zařízením bez jakýchkoliv znalostí Modbus protokolu nebo toho, jak ji konfigurovat v TapHome. Předpřipravené šablony naleznete:

• přímo v aplikaci: Přidat ze šablony → vyberte konkrétní zařízení → vyplňte základní informace a potvrďte. Všechny tyto šablony jsou spravovány v komunitním git projektu na https://github.com/taphome/modbus_templates a kdokoliv tam může navrhnout nové modifikace. Co se dostane do aplikací, musí být schválené přímo týmem TapHome.
• ve vlastním XML souboru: Přidat ze šablony → Přidat ze souboru. Můžete si vytvořit vlastní XML soubor, který definuje celou šablonu přímo na Modbus modul, v kontextovém menu (3 tečky vpravo nahoře), akci Uložit jako šablonu. Budeme rádi, pokud nám pomůžete rozšířit počet podporovaných zařízení a přispějete svým XML souborem do společného komunitního git projektu.

Více informací o konfiguraci Modbus komunikace pomocí šablon

Manuální operace

Praktický nástroj pro rychlé počáteční ověření Modbus tabulky. Umožňuje:

• načíst následujících X registrů do tabulky ze specifického registru a poté dynamicky přepínat čtené hodnoty do různých datových typů
• zapsat hodnotu do daného registru

Skenovat Slave ID

Běžnou praxí při nastavování komunikace s Modbus zařízením je, že továrně předvolené Slave ID je jiné než 1, a není snadné zjistit správné číslo. Na to slouží tento nástroj. Může skenovat zadaný rozsah Slave ID pokusem o čtení z vybraného registru vždy se zkoušeným Slave ID.

Informace o registrech

Nachází se v dolní části Modbus modulu. Pro každý použitý registr uvádí informace o:

• názvu zařízení TapHome, které z něj čte nebo do něj zapisuje
• datu a čase posledního úspěšného přečtení z registru
• poslední hodnotě přečtené z registru
• datu a čase posledního úspěšného zápisu do registru
• poslední hodnotě zapsané do registru

Pokročilé nastavení

Prefetch

TapHome vytváří seznam registrů pro čtení a zápis z Modbus zařízení v závislosti na nastaveném Poll intervalu. Prefetch je proces, díky kterému řídicí jednotka přednačítá do vyrovnávací paměti hodnoty, které bude potřebovat během aktualizace. Cílem je minimalizovat počet požadavků a zpětných cest. Prefetch je ovlivněn 2 nastaveními:

• Max prefetch register group size (umístěné v servisních nastaveních modulu): určuje maximální počet registrů, které je možné přečíst nebo zapsat pomocí Modbus komunikace jednou žádostí.
• Prefetch mode (nastavitelné pro každé zařízení):
  • No prefetch. Přednačítání se pro toto zařízení nebude provádět. To znamená, že hodnoty se budou číst jednotlivě a přesně tehdy, když se skript provede. Příklad použití: při komunikaci s DALI konvertorem není možné přečíst hodnotu konkrétního světla přímo, ale musí se o ni co nejdříve požádat, konvertor ji připraví a až potom ji vrátí. Jakékoliv přednačítání je v tomto případě zbytečné.
  • Isolated prefetch. Přednačítá najednou několik registrů, ale jen ty, které jsou definovány v tomto zařízení. Například, když potřebuji registry 3 a 4 v zařízení termostatu, registry 1, 2, 5, 6 se používají v jiných zařízeních, takže žádost o registry 3 a 4 se uskuteční samostatně jen pro tyto 2 registry. Některá Modbus zařízení to vyžadují.
  • Normal prefetch. Všechny požadované registry ze zařízení, která se mají obnovit, se pokusí přečíst s minimálním počtem požadavků. V případě nesouvislé sekvence registrů se přečtou i registry, které se nepoužívají, pokud byly v minulosti úspěšně přečteny. Příklad: Požadují se registry 99 a 101. Pokud byl registr 100 v minulosti úspěšně přečten a Max prefetch register group size je 3 nebo více, přečtou se 3 registry jednou žádostí z registru 99. Pokud se registr 100 nikde nepoužívá a nikdy nebyl úspěšně přečten, existuje riziko, že čtení přes takový registr by mohlo vrátit Modbus výjimku, např. “Illegal data address” jako odpověď na celou žádost.

Prefetch může být ovlivněn i přímo ze skriptu: Pokud při čtení použijeme registr SC nebo SH (namísto C nebo H), potom se hodnota čte jeden registr po druhém během vykonávání skriptu a nevybírá se z vyrovnávací paměti. Podobně při zápisu, pokud použijeme registr SC nebo SH (namísto C nebo H), hodnota se zapisuje jeden registr po druhém a jinou Modbus funkcí. Modbus protokol podporuje 4 funkce zápisu: zápis více H, více C, zápis jednoho H nebo jednoho C registru najednou. Pozor: ne všechna zařízení mohou podporovat všechny tyto funkce. Tímto způsobem, pokud je to potřeba, je možné kombinovat čtení a zápis “jeden po druhém”.

TCP Port (Modbus TCP)

Ve většině případů je výchozí hodnota 502, ale je možné, že některá zařízení poslouchají na jiném portu.

Časový limit čtení / zápisu

Čas, po kterém TapHome vzdá čekání na odpověď a nahlásí chybu „Timeout“. To znamená, že zařízení neodpovědělo v daném intervalu.

• Pomalá Modbus zařízení mohou vyžadovat delší časové limity (1+ s).
• Vysoké hodnoty časového limitu mohou zbytečně zdržovat ostatní Modbus zařízení čekající na odpověď.

Zpoždění mezi požadavky

Zpoždění, které TapHome vkládá mezi jednotlivé žádosti na Modbus zařízení.

📌 Důležité informace o zařízeních:

• Některá zařízení Modbus TCP vyžadují až 5000 ms mezi požadavky.
• Některá zařízení Modbus RTU umožňují kratší zpoždění a komunikují rychleji.

Použít ASCII komunikaci

Modbus ASCII je méně častý standard, kde komunikace není binární, ale používá znaky ASCII.

• Tato zařízení typicky vyžadují nastavení 7 datových bitů.