Modbus

• Jednoduchá konfigurace pomocí šablon

Úvod do Modbusu#

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 Vystavit 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ů:

SH a SC jsou starší hodnoty, které skripty stále přijímají; nové skripty používají H a C — Typy registrů.

Číslo registru (adresa registru) je 16bitové, to znamená, že může mít hodnotu od 0 do 65535. Adresu registru je možné zadat desítkově (např. 20) nebo šestnáctkově (např. 0x14). Na registrech je možné provádět operace:

• č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}

Slave ID, Unit ID a adresování registrů. Každé Modbus zařízení na sběrnici má jedinečné Slave ID (u Modbus TCP se mu někdy říká Unit ID). Pro čtení nebo zápis hodnoty potřebujete z Modbus tabulky zařízení tři údaje: typ registru (H = Holding, C = Coil, D = Discrete Input, A = Analog Input — funkční kód je odvozen od typu), adresu registru (0 až 65535, zadanou desítkově 20 nebo šestnáctkově 0x14) a datový typ (Int16, UInt16, Float atd.). TapHome používá adresu registru přesně tak, jak je uvedena v dokumentaci zařízení — pokud vaše zařízení dokumentuje čísla registrů od 1, odečtěte 1, abyste získali adresu od 0, kterou TapHome očekává. Slave ID, typ registru a adresa registru dohromady jednoznačně identifikují libovolnou hodnotu na Modbus zařízení.

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 Ruční operace 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.

Hierarchie#

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. TapHome organizuje Modbus komunikaci do tří úrovní: Rozhraní → Modul → Zařízení. Slave ID se nastavuje na úrovni Modulu, zatímco typ registru a adresa registru použité pro čtení nebo zápis každé hodnoty se definují v rámci skriptu jednotlivého Zařízení.

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
• Vícehodnotový 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ů.

Pro komunikaci s Modbus zařízeními jsou na nich definovány skriptovací sekce — co která dělá a kdy se spouští, popisuje stránka Skripty Modbus a prefetch:

• Inicializační skript: spustí se, když se zařízení spustí (např. po restartu řídicí jednotky)
• Skript pro čtení: nastavení hodnot globálních proměnných nebo čtení chybových stavů
• Skript pro č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 pro zápis hodnoty: zapíše hodnotu do Modbus zařízení

Funkce skriptu pro Modbus — MODBUSR, MODBUSW, MODBUSWNE a blokové funkce MODBUSRBLOCK, MODBUSWBLOCK, MODBUSWBLOCKNE — jsou s parametry a příklady popsány na stránce Funkce Modbus, datové typy (Int16, Float, varianty pořadí bajtů, 64bitové typy, String) na stránce Datové typy Modbus. Jednotlivé bity registru a hodnoty BCD (GETBIT, GETBITS, TOBCD, FROMBCD) jsou na stránce Bitové operace.

MODBUSR(H, 20, Int16) / 100

Přečte holding registr s adresou 20 jako 16bitové celé číslo se znaménkem a vydělí ho 100 (posune desetinnou čárku o 2 místa doleva). Adresu registru lze zadat i šestnáctkově, např. 0x14.

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 Periodický zápis.

Definice chybových stavů ze skriptů

Ve skriptech pro čtení zařízení nebo modulu Modbus vyvolají ADDERROR, ADDWARNING a ADDINFO na zařízení chybu, varování nebo informaci. TapHome je zobrazuje stejně jako své interní zprávy, volitelně s číselným kódem pro servis zařízení — ADDERROR, ADDWARNING, ADDINFO. Příklad zpráv na zařízení:

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.

Inicializační skript

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

Skript pro čtení

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

Skript pro zápis

Spuštění:

• při změně proměnné zařízení
• pokud je povolen atribut “Periodický zápis”, 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

Servisní atributy modulu

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
• ⚠️ Podpora chybového stavu: ne

Servisní akce modulu

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, uživatelem zadané parametry
• ⚠️ Podpora chybového stavu: ne

Skripty a pomocné proměnné na zařízení#

Globální proměnné zařízení

Proměnné definované na zařízení jsou použitelné ve všech skriptech definovaných na tomto zařízení a nejsou použitelné nikde mimo zařízení. Zařízení v nich může ukládat svůj stav, sdílet je mezi svými skripty a podobně.

Inicializační skript zařízení

Volitelný. Spustí se při startu zařízení. 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, globální proměnné zařízení
• ⚠️ Podpora chybového stavu: ne

Skript pro čtení zařízení

Spustí se při každém dotazu zařízení, před „Skripty pro čtení hodnoty“.

• 💬 Návratová hodnota: ignorovaná
• ⚙️ Přístup k proměnným: globální proměnné modulu, globální proměnné zařízení
• ⚠️ Podpora chybového stavu: ano. Chyby se týkají celého zařízení (např. celého termostatu, ne jen jeho nastavené hodnoty nebo aktuální teploty).

Skript pro zápis hodnoty

Spuštění:

• při každé změně hodnoty
• pokud je povolen atribut “Periodický zápis”, tak i při každém dotazu
• 💬 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

Skript pro čtení hodnoty

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 zařízení

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 zařízení

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

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

Ruční 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

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”.

Pokročilé nastavení#

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ů.