• Simple configuration using templates

Úvod do Modbusu

Modbus je jednoduchý komunikační protokol, často využívaný k integraci HVAC zařízení. Využívá master - slave komunikaci, kdy na společné sběrnici může být připojeno více zařízení, každé musí mít unikátní Slave ID, a vždy se master zařízení poptává jednotlivých slave zařízení, která mu odpovídají.

Master - slave topologie

TapHome se ve většině případů využívá v režimu kde řídicí Core jednotka je Modbus Master, a připojená zařízení jsou Modbus Slave. Toto se nastavuje v sekci Hardware → Modbus RTU nebo Modbus TCP. Je ale možné využít i opačného směru, kdy TapHome Core poskytuje nějakému jinému nadřazenému systému informaci o svých zařízeních. Definuje se to v sekci Expose devices (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, typickou RS485. Toto se označuje jako Modbus RTU
• po LAN síti přes TCP/IP protokol
• po LAN síti přes UDP protokol - v současnosti není podporováno systémem TapHome

Modbus registry

Modbus definuje 4 typy registrů:

Číslo registru je 16 bitové, čili může mít hodnotu od 0 po 65535. Nad registry lze provést operace:

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

Informace o tom, co je ve kterém registru uloženo a v jakém formátu, je součástí dokumentace k zařízení, kterou poskytuje dodavatel nebo výrobce zařízení. Příklad Modbus dokumentace od dodavatele Modbus zařízení:

Typ registru C (Coil), index 58, jelikož má pouze 2 hodnoty (otevřeno / zavřeno), a povoluje kromě čtení i zápis, vhodný typ TapHome zařízení je Digitální výstup.

Zrychlený návod k integraci Modbus zařízení do TapHome

1. Připojte zařízení na příslušnou sběrnici (u Modbus RTU a ASCII), nebo na LAN (u Modbus TCP). U TCP zařízení se ujistěte, že je na stejné síti jako TapHome Core řídicí jednotka, například pomocí nástroje 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 je Baud rate, Stop bits, Parity, Data bits, pro Modbus TCP je IP adresa.
3. Najděte v Modbus dokumentaci zařízení jaké Slave ID používá. V případě Modbus TCP se to někdy zvykne označovat také jako Unit ID. Chcete-li u Modbus RTU používat více zařízení na jedné sběrnici, každému musíte změnit Slave ID aby bylo unikátní pro danou sběrnicovou linku.
4. Test komunikace - pomocí nástroje Manuální operace zkuste přečíst některou informaci podle dokumentace (Modbusové tabulky) k danému zařízení. Pokud vše funguje, měli byste vidět vyčtenou hodnotu.
5. Pokud test komunikace proběhl úspěšně, vytvořte Modul, který představuje Modbus zařízení
6. Vyberte si, 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), av případě aktorů pokračujte zápisem (Write script).
7. Pokud základní funkce zařízení fungují, přidejte do skriptů definice Chyb, Varování nebo Informací.
8. Pokud je to nutné, k TapHome zařízením a modulům můžete definovat i Servisní atributy a servisní akce
9. Pokud je vše vyladěno a komunikuje správně, exportujte si Modul do XML souboru, abyste jej 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 TapHome Core řídicí jednotka je Modbus master, a fyzická zařízení, která se přidávají do sekce Hardware → Modbus RTU / TCP jsou Modbus slave.

Hierarchie

Interface

Hardware → Modbus RTU: zařízení jsou připojena na některém BUSu, definují se základní parametry RS485 přenosu, jako například. baudrate, parita, stop bits, nebo zda data jsou ASCII nebo binární. Na této sběrnici mohou být připojena pouze zařízení, která mají stejná komunikační nastavení. Také korektní komunikace může fungovat pouze pokud jsou správně zapojeny A a B kabely. Hardware → Modbus TCP: zařízení jsou připojena na stejné LAN síti jako Core řídicí jednotka. Definuje se jeden TCP port, který je společný pro všechna zařízení připojená na tento interface.

Modul

Interface může obsahovat jeden nebo více modulů, které ve většině případů zastřešují komunikaci s celým fyzickým zařízením. Z konfiguračního hlediska Modul definuje unikátní Slave ID připojeného zařízení u Modbus RTU, a navíc i IP adresu u Modbus TCP.

Zařízení

Představuje konkrétní ovládací prvek nebo senzor v systému TapHome. Vždy musí být součástí jednoho nadřazeného Modulu.

Podporovaná zařízení:

• Digitální výstup
• Analogový výstup
• Termostat
• Vícehodnotový přepínač
• Teplotní senzor
• Elektroměr
• Stavový kontakt
• Tlačítko
• proměnná

Skripty pro čtení a zápis Modbus hodnot

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

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

• Initialize script: spouští se při startu zařízení (např. po restartu řídící jednotky)
• Read script: nastavení hodnot globálních proměnných, nebo čtení chybových stavů
• Read Value script: skript pro čtení konkrétní hodnoty (veličiny) z Modbus zařízení (např. nastavená teplota na termostatu, nebo měřená teplota na termostatu)
• Write Value script: zápis hodnoty do Modbus zařízení

Funkce pro komunikaci s Modbus zařízeními

MODBUSR (Modbus Read) Funkce pro čtení registru z Modbusu. Podle datového typu může jít o 1 registr (pro 16 bitové datové typy), 2 registry (pro 32 bitové datové typy), nebo více registrů (pro String datový typ)

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

Přečti H rejstřík číslo (nebo s adresou) 20, a interpretuj ho jako 16bitový Integer (celé číslo se znaménkem +-). Tuto hodnotu nakonec vyděl číslem 100 (posun desetinné čárky o 2 místa doleva).

MODBUSW (Modbus Write)

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

Do registru H s adresou 20, zapiš hodnotu proměnné Te vynásobenou číslem 100 (posun desetinné čárky o 2 doprava).

MODBUSWNE (Modbus Write if Not Equal)

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

Modbus datové typy

Obsah registrů je definován v modbusové tabulce. Jelikož velikost jednoho Modbus registru je 16 bitů, nejčastěji se využívají 16 bitové hodnoty Int16 nebo UInt16, a desetinná místa jsou odpočítávána dělení číslem 10 nebo 100. Některá Modbus zařízení ale využívají i 16 bitové registry s čísly s plovoucí desetinnou čárkou (Float), nebo mají pozměněné pořadí bitů (big endian, little endian), jedno číslo zapisují do dvou registrů (32 bitové variace). Někdy je nejjednodušší způsob zjištění správného datového typu využití utility přímo v TapHome aplikaci (Manual Operations), kde lze načíst 1 nebo více registrů, a dynamicky si přepínat datový typ.

• Int16 (-32,768 to 32,767)
• Uint16 (0 to 65,535)
• Int32 (-2,147,483,648 to 2,147,483,647)
• Uint32 (0 to 4,294,967,295)
• Float (IEEE 754 Single precision floating point)
• Bool 0 = false, 1 = true
• BigEndianInt16 = Int16
• LittleEndianInt16
• BigEndianUint16 = Uint16
• LittleEndianUint16
• BigEndianInt32 / BigEndianInt32ByteSwap
• LittleEndianInt32 / LittleEndianInt32ByteSwap
• BigEndianUint32 / BigEndianUint32ByteSwap
• LittleEndianUint32 / LittleEndianUint32ByteSwap
• BigEndianFloat / BigEndianFloatByteSwap
• LittleEndianFloat / LittleEndianFloatByteSwap

• String

  BCD formát lze použít také, díky funkcím TOBCD() a FROMBCD()

Update a Poll Interval

Každé zařízení v Modbus rozhraní má definovaný atribut Poll Interval. Tento určuje, jak často se má TapHome řídicí jednotka dotazovat na nové hodnoty Modbus zařízení. Modbus komunikace je typu Master – Slave, a tedy informace z Modbus zařízení se může dostat do TapHome pouze tehdy, když si ji TapHome vyžádá. Čím je Poll Interval delší, tím později se obnoví hodnota v TapHomu. Příliš krátký Poll Interval ale může znamenat, že TapHome bude zbytečně vytěžen získáváním zbytečných hodnot, a nemusí stihnout obsloužit všechna zařízení v rámci daného časového intervalu. Například při Modbus RTU a nižších rychlostech Baud Rate, například. 9600, může jedna poptávka / odpověď trvat desítky ms. Pro teploměry ve většině případů stačí interval 15000ms (15s), pro tlačítka zase naopak co nejméně, například. 50ms. Některá Modbus zařízení očekávají, že master jim bude periodicky zapisovat současnou hodnotu do registru. K tomu 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í vyčtených z registrů Modbus zařízení. Tyto hlášky se v TapHome zobrazují stejně jako interní TapHome chybová hlášení. Volitelně může být k chybové hlášce přidán i číselný kód chyby, pokud je to praktické z hlediska servisování Modbus zařízení.

ADDERROR(), ADDWARING(), ADDINFO()

ADDERROR([Optional: custom_code], text)

Příklad: v Read Script sekci zařízení Analog Output je kód:

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í projeví hláškami:

Servisní atributy a akce

TapHome moduly a zařízení mohou kromě hodnoty (nebo více hodnot, jako například Termostat) z připojeného Modbus zařízení navíc číst servisní atributy, nebo provádět servisní akce. Tyto pak nejsou přístupné na ploše pro další uživatele systému, ale slouží pouze k detailnějším informacím o Modbus zařízení, aniž by se zbytečně zahlcoval systém velkým množstvím proměnných a akcí.

Servisní atributy se zobrazují v servisních nastaveních TapHome modulu nebo zařízení. Typicky slouží k zobrazování informací o zařízení, jako například Model, Sériové číslo, Verze Firmware, Verze Hardware, Čas od posledního restartu a podobně. Jsou to užitečné informace z pohledu servisování Modbus zařízení, ale nemá pro ně smysl vytvářet samostatná TapHome zařízení.

Servisní akce se zobrazují v servisních nastaveních TapHome modulu nebo zařízení, zcela dolů jako tlačítka. Po stisku provedou přednastavenou Modbusovou 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, Reset zařízení a podobně.

Pomocné utility

Přidat ze šablony

Umožňuje nakonfigurovat Modbus komunikaci se zařízením bez jakýchkoli znalostí Modbus protokolu, nebo způsobu konfigurování v TapHome. Předvytvořené šablony se nacházejí:

• přímo v aplikaci: Add from template → vybrat konkrétní zařízení → vyplnit základní informace a potvrdit. Všechny tyto šablony jsou spravovány v komunitním git projektu na adrese https://github.com/taphome/modbus_templates a každý tam může navrhnout nové úpravy. To co se dostane do aplikací musí být schváleno přímo TapHome týmem

• ve vlastním XML souboru: Add from template → Add from file. Vlastní XML soubor, který definuje celou šablonu, si můžete vytvořit přímo na Modbusovém modulu, v kontextovém menu (3 tečky vpravo nahoře), akce Save as template. Budeme rádi, když nám pomůžete rozšířit počet podporovaných zařízení, a přispějete Váš XML soubor do společného komunitního git projektu.

  Více info o konfigurování Modbus komunikace pomocí šablon

Manual Operations

Praktický nástroj pro rychlé prvotní ověření Modbusovy tabulky. Umožňuje:

• z konkrétního registru načítat následujících X registrů do tabulky, a následně si dynamicky přepínat načtené hodnoty do různých datových typů
• zapsat hodnotu na daný rejstřík

Scan Slave IDs

Běžná praxe při zpojezdňování komunikace s Modbus zařízením je, že od výroby je přednastaveno Slave ID jiné než hodnota 1, a není snadné se dopracovat ke správnému číslu. K tomu právě slouží tato utilita. Dokáže skenovat zadaný rozsah Slave ID tak, že se pokouší číst z vybaného registru vždy s testovaným Slave ID.

Informace o registrech

Nachází se v dolní části Modbus modulu. Pro každý použitý rejstřík vypíše informaci o:

• názvu TapHome zařízení, které ho čte nebo do něj zapisuje
• Datum a čas posledního úspěšného čtení z registru
• Poslední načtená hodnota z registru
• Datum a čas posledního úspěšného zápisu do rejstříku
• Poslední zapsaná hodnota do registru

Rozšířená nastavení

Prefetch (přednačtení)

TapHome si vytváří seznam registrů, které lze číst z, a zapisovat do Modbus zařízení, v závislosti na nastaveném Poll intervalu. Prefetch je proces, díky kterému si řídící jednotka přednačte do vyrovnávací paměti hodnoty, které bude potřebovat během updatování. Cílem je minimalizace počtu požadavků a round tripů. Prefetch ovlivňují 2 nastavení:

• Max prefetch registr group size (nachází se v servisních nastaveních modulu): určuje maximální počet registrů, které se mohou jedním požadavkem přečíst nebo zapsat přes Modbus komunikaci.
• Prefetch režim (nastavitelný pro každé zařízení):
• No prefetch. Pro toto zařízení se nebude provádět přednačtení. To znamená, že hodnoty se budou číst jednotlivě a přesně tehdy, když se provádí skript. Příklad použití: při komunikaci s DALI převodníkem nelze vyčítat přímo hodnotu konkrétního světla, ale je třeba nejdříve o ni požádat, on převodník si ji připraví, a teprve poté ji vrátí. Jakékoliv přednačtení v tomto případě nemá smysl.
• Isolated prefetch. Přednačítá sice několik registrů najednou, ale pouze ty, které jsou definovány v tomto zařízení. Např. když v zařízení termostat potřebuji registry 3 a 4, v ostatních zařízeních se využívají registry 1, 2, 5, 6, tak požadavek pro registry 3 a 4 bude proveden samostatně pouze pro tyto 2 registry. Některá Modbus zařízení toto vyžadují.
• Normal prefetch. Všechny žádané registry ze zařízení které mají být obnoveny, se snaží přečíst s minimálním počtem požadavků. V případě nesouvislého sledu registrů přečte i registry, které se nevyužívají, pokud byly někdy v minulosti úspěšně vyčteny. Příklad: Žádán je rejstřík 99 a 101. Pokud rejstřík 100 byl v minulosti úspěšně přečten, a Max prefetch registr group size je 3 nebo více, tak přečte jedním požadavkem od registru 99 3 registry. Pokud registr 100 není nikde použit, a nikdy nebyl úspěšně přečten, je riziko, že čtení přes takový registr by mohlo vrátit Modbus exception. "Illegal data address" jako odpověď na celý požadavek.

Prefetch lze ovlivňovat i přímo ze skriptu: Pokud při čtení použijeme jako registr SC nebo SH (namísto C nebo H), tak hodnota je přečtena po jednom registru v době provádění skriptu, a netáhne se z cache paměti. Podobně při zápisu, použijeme-li jako registr SC nebo SH (místo C nebo H), tak hodnota se zapisuje po jednom registru a jinou modbusovou funkcí. Modbus protokol podporuje 4 funkce pro zápis: zápis více H, více C, zápis jednoho H, nebo jednoho C registru najednou. Pozor: ne všechna zařízení musí podporovat všechny tyto funkce. Takovým způsobem lze v případě potřeby kombinovat čtení a zápis sdruženě a "po jednom".

TCP Port (Modbus TCP)

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

Read / Write Timeout

Čas, po jehož uplynutí TapHome vzdá čekání na odpověď, a ohlásí chybu "Timeout", která znamená že zařízení neodpovědělo v daném časovém intervalu na požadavek. Pomalé Modbus zařízení nemusí stihnout odpovídat promptně, a je třeba tento interval prodloužit na řádově 1 nebo několik vteřin. Pozor ale na zbytečně vysoké hodnoty, protože když z nějakého důvodu vypadne komunikace s Modbus zařízením, tak zbytečně zdržuje ostatní Modbus zařízení čekáním na odpověď.

Delay Between Requests

Zpoždění, které TapHome vkládá mezi jednotlivé požadavky na Modbus zařízení. Pro Modbus TCP je to standardně 0ms, pro Modbus RTU toto zpoždění podle specifikace vychází z rychlosti komunikace (baud rate) na minimálně 3,5 znaku. Existují však Modbus TCP zařízení, která vyžadují až 5000ms mezi požadavky, nebo naopak, některá Modbus RTU zařízení zvládají i kratší zpoždění, a tím pádem jsou schopny komunikovat rychleji.

Use ASCII communication

Modbus ASCII je méně používaný standard, kde komunikace neprobíhá binární, ale pomocí ASCII znaků. Většinou tato zařízení využívají také nastavení "7 data bit".