• Simple configuration using templates

Úvod do Modbus-u

Modbus je jednoduchý komunikačný protokol, často využívaný na integráciu HVAC zariadení. Využíva master - slave komunikáciu, kedy na spoločnej zbernici môže byť pripojených viacero zariadení, každé musí mať unikátne Slave ID, a vždy sa master zariadenie dopytuje jednotlivých slave zariadení, ktoré mu odpovedajú.

Master - slave topológia

TapHome sa vo väčšine prípadov využíva v režime, kde riadiaca Core jednotka je Modbus Master a pripojené zariadenia sú Modbus Slave. Toto sa nastavuje v sekcii Hardware → Modbus RTU alebo Modbus TCP. Je ale možné využiť aj opačný smer, kedy TapHome Core poskytuje nejakému inému nadradenému systému informáciu o svojich zariadeniach. Definuje sa to v sekcii Expose devices (Vystaviť zariadenia) → Modbus RTU alebo Modbus TCP.

Fyzické vrstvy

Modbus môže komunikovať cez rôzne fyzické vrstvy:

• cez sériovú linku, typický RS485. Toto sa označuje ako Modbus RTU
• po LAN sieti cez TCP/IP protokol
• po LAN sieti cez UDP protokol - v súčasnosti nie je podporované systémom TapHome

Modbus registre

Modbus definuje 4 typy registrov:

Číslo registra je 16 bitové, čiže môže mať hodnotu od 0 po 65535. Nad registrami sa dajú vykonať operácie:

• čítanie viacerých registrov
• zápis jedného registra
• zápis viacerých registrov

Informácie o tom, čo je v ktorom registri uložené a v akom formáte, je súčasťou dokumentácie k zariadeniu, ktorú poskytuje dodávateľ alebo výrobca zariadenia. Príklad Modbus dokumentácie od dodávateľa Modbus zariadenia:

Typ registra C (Coil), index 58, keďže má iba 2 hodnoty (otvorené / zatvorené), a povoľuje okrem čítania aj zápis, vhodný typ TapHome zariadenia je Digitálny výstup.

Zrýchlený návod na integráciu Modbus zariadenia do TapHome

1. Pripojte zariadenie na príslušnú zbernicu (pri Modbus RTU a ASCII), alebo na LAN (pri Modbus TCP). V prípade TCP zariadenia sa uistite, že je na tej istej sieti ako TapHome Core riadiaca jednotka, napríklad pomocou nástroja Fing (iOS, Android) alebo IP Scanner (Windows).
2. V TapHome → Hardware pridajte nové rozhranie Modbus RTU alebo Modbus TCP, a nastavte komunikačné parametre podľa dokumentácie. Pre Modbus RTU je to Baud rate, Stop bits, Parity, Data bits, pre Modbus TCP je to IP adresa.
3. Nájdite v Modbus dokumentácii zariadenia aké Slave ID používa. V prípade Modbus TCP sa to niekedy zvykne označovať aj ako Unit ID. Ak chcete pri Modbus RTU používať viacero zariadení na jednej zbernici, každému musíte zmeniť Slave ID aby bolo unikátne pre danú zbernicovú linku.
4. Test komunikácie - pomocou nástroja Manuálne operácie skúste prečítať niektorú informáciu podľa dokumentácie (Modbusovej tabuľky) k danému zariadeniu. Ak všetko funguje, mali by ste vidieť vyčítanú hodnotu.
5. Ak test komunikácie prebehol úspešne, vytvorte Modul, ktorý predstavuje Modbus zariadenie
6. Vyberte si, ktoré informácie z Modbus dokumentácie chcete prezentovať v systéme TapHome, a vytvorte zodpovedajúce zariadenia. Začnite čítaním hodnôt (Read script), a v prípade aktorov pokračujte zápisom (Write script).
7. Ak základné funkcie zariadenia fungujú, pridajte do skriptov definície Chýb, Varovaní, alebo Informácií.
8. Ak je to potrebné, k TapHome zariadeniam a modulom môžete definovať aj Servisné atribúty a servisné akcie
9. Ak je všetko vyladené a komunikuje správne, exportujte si Modul do XML súboru, aby ste ho mohli použiť nabudúce. Taktiež môžete prispieť do komunity na github.com/taphome-official/modbus_templates

Implementácia v TapHome

Táto dokumentácia je určená pre scenár, kedy TapHome Core riadiaca jednotka je Modbus master, a fyzické zariadenia, ktoré sa pridávajú do sekcie Hardware → Modbus RTU / TCP sú Modbus slave.

Hierarchia

Interface

Hardware → Modbus RTU: zariadenia sú pripojené na niektorom BUSe, definujú sa základné parametre RS485 prenosu, ako napr. baudrate, parita, stop bits, alebo či dáta sú ASCII alebo binárne. Na tejto zbernici môžu byť pripojené iba zariadenia, ktoré majú rovnaké komunikačné nastavenia. Taktiež korektná komunikácia môže fungovať iba ak sú správne zapojené A a B káble. Hardware → Modbus TCP: zariadenia sú pripojené na rovnakej LAN sieti ako Core riadiaca jednotka. Definuje sa jeden TCP port, ktorý je spoločný pre všetky zariadenia pripojené na tento interface.

Modul

Interface môže obsahovať jeden alebo viac modulov, ktoré vo väčšine prípadov zastrešujú komunikáciu s celým fyzickým zariadením. Z konfiguračného hľadiska Modul definuje unikátne Slave ID pripojeného zariadenia pri Modbus RTU, a navyše aj IP adresu pri Modbus TCP.

Zariadenie

Predstavuje konkrétny ovládací prvok alebo senzor v systéme TapHome. Vždy musí byť súčasťou jedného nadradeného Modulu.

Podporované zariadenia:

• Digitálny výstup
• Analógový výstup
• Termostat
• Viachodnotový prepínač
• Teplotný senzor
• Elektromer
• Stavový kontakt
• Tlačidlo
• Premenná

Skripty na čítanie a zápis Modbus hodnôt

TapHome zariadenie komunikujú s fyzickými Modbus zariadeniami pomocou skriptov.

Pre komunikáciu s Modbus zariadeniami sú na nich definované skriptovacie sekcie:

• Initialize script: spúšťa sa pri štarte zariadenia (napr. po reštarte riadiacej jednotky)
• Read script: nastavenie hodnôt globálnych premenných, alebo čítanie chybových stavov
• Read Value script: skript na čítanie konkrétnej hodnoty (veličiny) z Modbus zariadenia (napr. nastavená teplota na termostate, alebo meraná teplota na termostate)
• Write Value script: zápis hodnoty do Modbus zariadenia 

Funkcie na komunikáciu s Modbus zariadeniami

MODBUSR (Modbus Read) Funkcia na čítanie registra z Modbus-u. Podľa datového typu môže ísť o 1 register (pre 16 bitové datové typy), 2 registre (pre 32 bitové datové typy), alebo viac registrov (pre String datový typ)

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

Prečítaj H register číslo (alebo s adresou) 20, a interpretuj ho ako 16-bitový Integer (celé číslo so znamienkom +-). Túto hodnotu nakoniec vydeľ číslom 100 (posun desatinnej čiarky o 2 miesta doľava).

MODBUSW (Modbus Write)

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

Do registra H s adresou 20, zapíš hodnotu premennej Te vynásobenú číslom 100 (posun desatinnej čiarky o 2 doprava).

MODBUSWNE (Modbus Write if Not Equal)

To isté ako MODBUSW s rozdielom, že pred zápisom si hodnotu z registra prečíta, a zapíše ju iba vtedy, ak zapisovaná hodnota je rozdielna od čítanej. Celá operácia trvá dlhšie, a jej typické využitie je pri nastavovaní vlastností Modbus zariadenia, kde konfigurácia sa zapisuje do EEPROM pamäte s obmedzeným počtom zápisov.

Modbus dátové typy

Obsah registrov je definovaný v modbusovej tabuľke. Keďže veľkosť jedného Modbus registra je 16 bitov, najčastejšie sa využívajú 16 bitové hodnoty Int16 alebo UInt16, a desatinné miesta sú odpočítavané delenia číslom 10 alebo 100. Niektoré Modbus zariadenia ale využívajú aj 16 bitové registre s číslami s plávajúcou desatinnou čiarkou (Float), alebo majú pozmenené poradie bitov (big endian, little endian), jedno číslo zapisujú do dvoch registrov (32 bitové variácie). Niekedy je najjednoduchší spôsob zistenia správneho dátového typu využitie utility priamo v TapHome aplikácii (Manual Operations), kde sa dá načítať 1 alebo viac registrov, a dynamicky si prepínať dátový 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 je možné použiť tiež, vďaka funkciám TOBCD() a FROMBCD()

Update a Poll Interval

Každé zariadenie v Modbus rozhraní má definovaný atribút Poll Interval. Tento určuje, ako často sa má TapHome riadiaca jednotka dopytovať na nové hodnoty Modbus zariadenia. Modbus komunikácia je typu Master - Slave, a teda informácia z Modbus zariadenia sa môže dostať do TapHome iba vtedy, keď si ju TapHome vyžiada. Čím je Poll Interval dlhší, tým neskôr sa obnoví hodnota v TapHome. Príliš krátky Poll Interval ale môže znamenať, že TapHome bude zbytočne vyťažený získavaním zbytočných hodnôt, a nemusí stihnúť obslúžiť všetky zariadenia vrámci daného časového intervalu. Napríklad pri Modbus RTU a nižších rýchlostiach Baud Rate, napr. 9600, môže jeden dopyt / odpoveď trvať desiatky ms. Pre teplomery vo väčšine prípadov stačí interval 15000ms (15s), pre tlačítka zase naopak čo najmenej, napr. 50ms. Niektoré Modbus zariadenia očakávajú, že master im bude periodicky zapisovať súčasnú hodnotu do registra. Na to slúži atribút Periodic Write.

Definícia chybových stavov zo skriptov

V niektorých skriptoch je možné definovať chybu / varovanie / informáciu na zariadení, na základe informácií vyčítaných z registrov Modbus zariadenia. Tieto hlášky sa v TapHome zobrazujú rovnako ako interné TapHome chybové hlásenia. Voliteľne môže byť k chybovej hláške pridaný aj číselný kód chyby, ak je to praktické z hľadiska servisovania Modbus zariadenia.

ADDERROR(), ADDWARING(), ADDINFO()

ADDERROR([Optional: custom_code], text)

Príklad: v Read Script sekcii zariadenia 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");

...čo sa na zariadení prejaví hláškami:

Servisné atribúty a akcie

TapHome moduly a zariadenia môžu okrem hodnoty (alebo viacerých hodnôt, ako napríklad Termostat) z pripojeného Modbus zariadenia navyše čítať servisné atribúty, alebo vykonávať servisné akcie. Tieto potom nie sú prístupne na ploche pre ďalších užívateľov systému, ale slúžia iba na detailnejšie informácie o Modbus zariadení bez toho, aby sa zbytočne zahlcoval systém veľkým množstvom premenných a akcií.

Servisné atribúty sa zobrazujú v servisných nastaveniach TapHome modulu alebo zariadenia. Typicky slúžia na zobrazovanie informácii o zariadení, ako napríklad Model, Sériové číslo, Verzia Firmware, Verzia Hardware, Čas od posledného reštartu a podobne. Sú to užitočné informácie z pohľadu servisovania Modbus zariadenia, ale nemá pre ne zmysel vytvárať samostatné TapHome zariadenia.

Servisné akcie sa zobrazujú v servisných nastaveniach TapHome modulu alebo zariadenia, úplne dole ako tlačítka. Po stlačení vykonajú prednastavenú Modbusovú akciu, ktorá zapíše požadované informácie do registra. Príklad použitia: Nastavenie alebo zmena Slave ID, Výmena filtra, Nastavenie počítadla na požadovanú hodnotu, Reset zariadenia a podobne.

Pomocné utility

Pridať zo šablóny

Umožňuje nakonfigurovať Modbus komunikáciu so zariadením bez akýchkoľvek znalostí Modbus protokolu, alebo spôsobu konfigurovania v TapHome. Predvytvorené šablóny sa nachádzajú:

• priamo v aplikácii: Add from template → vybrať konkrétne zariadenie → vyplniť základné informácie a potvrdiť. Všetky tieto šablóny sú spravované v komunitnom git projekte na adrese https://github.com/taphome/modbus_templates a každý tam môže navrhnúť nové úpravy. To čo sa dostane do aplikácií musí byť schválené priamo TapHome tímom
• vo vlastnom XML súbore: Add from template → Add from file. Vlastný XML súbor, ktorý definuje celú šablónu, si môžete vytvoriť priamo na Modbusovom module, v kontextovom menu (3 bodky vpravo hore), akcia Save as template. Budeme radi, keď nám pomôžete rozšíriť počet podporovaných zariadení, a prispejete Váš XML súbor do spoločného komunitného git projektu.

Viac info o konfigurovaní Modbus komunikácie pomocou šablón

Manual Operations

Praktický nástroj na rýchle prvotné overenie Modbusovej tabuľky. Umožňuje:

• z konkrétneho registra načítať nasledujúcich X registrov do tabuľky, a následne si dynamicky prepínať načítané hodnoty do rôznych datových typov
• zapísať hodnotu na daný register

Scan Slave IDs

Bežná prax pri spojazdňovaní komunikácie s Modbus zariadením je, že od výroby je prednastavené Slave ID iné ako hodnota 1, a nie je jednoduché sa dopracovať k správnemu číslu. Na to práve slúži táto utilita. Dokáže skenovať zadaný rozsah Slave ID tak, že sa pokúša čítať z vybaného registra vždy s testovaným Slave ID.

Informácie o registroch

Nachádza sa v dolnej časti Modbus modulu. Pre každý použitý register vypíše informáciu o:

• Názve TapHome zariadenia, ktoré ho číta alebo doňho zapisuje
• Dátum a čas posledného úspešného čítania z registra
• Posledná načítaná hodnota z registra
• Dátum a čas posledného úspešného zápisu do registra
• Posledná zapísaná hodnota do registra

Rozširené nastavenia

Prefetch (prednačítanie)

TapHome si vytvára zoznam registrov, ktoré ide čítať z, a zapisovať do Modbus zariadení, v závislosti od nastaveného Poll intervalu. Prefetch je proces, vďaka ktorému si riadiaca jednotka prednačíta do vyrovnávacej pamäte hodnoty, ktoré bude potrebovať počas updatovania. Cieľom je minimalizácia počtu požiadaviek a round tripov. Prefetch ovplyvňujú 2 nastavenia:

• Max prefetch register group size (nachádza sa v servisných nastaveniach modulu): určuje maximálny počet registrov, ktoré sa môžu jednou požiadavkou prečítať alebo zapísať cez Modbus komunikáciu.
• Prefetch režim (nastaviteľný pre každé zariadenie):
• No prefetch. Pre toto zariadenie sa nebude vykonávať prednačítanie. To znamená že hodnoty sa budú čítať jednotlivo a presne vtedy, keď sa vykonáva skript. Príklad použitia: pri komunikácii s DALI prevodníkom sa nedá vyčítať priamo hodnota konkrétneho svetla, ale treba najskor o ňu požiadať, on prevodník si ju pripraví, a až potom ju vráti. Akékoľvek prednačítanie v tomto prípade nemá zmysel.
• Isolated prefetch. Prednačítava síce viaceré registre naraz, ale iba tie, ktoré sú definované v tomto zariadení. Napr. keď v zariadení termostat potrebujem registre 3 a 4, v ostatných zariadeniach sa využívajú registre 1, 2, 5, 6, tak požiadavka pre registre 3 a 4 bude vykonaná samostatne iba pre tieto 2 registre. Niektoré Modbus zariadenia toto vyžadujú.
• Normal prefetch. Všetky žiadané registre zo zariadení ktoré majú byť obnovené, sa snaží prečítať s minimálnym počtom požiadaviek. V prípade nesúvislého sledu registrov prečíta aj registre ktoré sa nevyužívajú, ak boli niekedy v minulosti úspešne vyčítané. Príklad: Žiadaný je register 99 a 101. Pokiaľ register 100 bol v minulosti úspešne prečítaný, a Max prefetch register group size je 3 alebo viac, tak prečíta jednou požiadavkou od registra 99 3 registre. Ak register 100 nie je nikde použitý, a nikdy nebol úspešne prečítaný, je riziko, že čítanie cez takýto register by mohlo vrátiť Modbus exception, napr. "Illegal data address" ako odpoveď na celú požiadavku.

Prefetch sa dá ovplyvňovať aj priamo zo skriptu: Ak pri čítaní použijeme ako register SC alebo SH (namiesto C alebo H), tak hodnota je prečítaná po jednom registri v čase vykonávania skriptu, a neťahá sa z cache pamäte. Podobne pri zápise, ak použijeme ako register SC alebo SH (namiesto C alebo H), tak hodnota sa zapisuje po jednom registri a inou modbusovou funkciou. Modbus protokol podporuje 4 funkcie na zápis: zápis viacerých H, viacerých C, zápis jedného H, alebo jedného C registra naraz. Pozor: nie všetky zariadenia musia podporovať všetky tieto funkcie. Takýmto spôsobom sa dá v prípade potreby kombinovať čítanie a zápis združene a "po jednom".

TCP Port (Modbus TCP)

Vo väčšine prípadov je default hodnota 502, je však možné, že niektoré zariadenia počúvajú na inom porte.

Read / Write Timeout

Čas, po uplynutí ktorého TapHome vzdá čakanie na odpoveď, a ohlási chybu "Timeout", ktorá znamená že zariadenie neodpovedalo v danom časovom intervale na požiadavku. Pomalé Modbus zariadenia nemusia stihnúť odpovedať promptne, a je potrebné tento interval predĺžiť na rádovo 1 alebo niekoľko sekúnd. Pozor ale na zbytočne vysoké hodnoty, pretože keď z nejakého dôvodu vypadne komunikácia s Modbus zariadením, tak zbytočne zdržuje ostatné Modbus zariadenia čakaním na odpoveď.

Delay Between Requests

Oneskorenie, ktoré TapHome vkladá medzi jednotlivé požiadavky na Modbus zariadenie. Pre Modbus TCP je to štandardne 0ms, pre Modbus RTU toto oneskorenie podľa špecifikácie vychádza z rýchlosti komunikácie (baud rate) na minimálne 3,5 znaku. Existujú však Modbus TCP zariadenia, ktoré vyžadujú až 5000ms medzi požiadavkami, alebo naopak, niektoré Modbus RTU zariadenia zvládajú aj kratšie oneskorenia, a tým pádom sú schopné komunikovať rýchlejšie.

Use ASCII communication

Modbus ASCII je menej používaný štandard, kde komunikácia neprebieha binárne, ale pomocou ASCII znakov. Väčšinou tieto zariadenia využívajú aj nastavenie "7 data bit".