Komunikační protokol MQTT

Od verze Domat IDE 2.8.0.x.

Popis komunikačního protokolu

MQTT je komunikační protokol typu publish/subscribe využívající tzv. brokera pro výměnu zpráv. Klienti na brokera odesílají zprávy v libovolném formátu, který je pak rozposílá ostatním klientům. Klienti si dle topicu vybírají, jaké zprávy chtějí přijímat.

Základní pojmy

• Broker - server (prostředník) klientů. Jeho úkolem je rozesílat publikované zprávy.

• Topic - Cesta k hodnotám, které chceme číst/zapisovat.

  • Názvy úrovní jsou libovolné (formát řetězce UTF-8).
  • Úrovně jsou oddělené znakem lomítka (/).
  • Podporuje následující vzorce (wildcard):
  • • + - jedna úroveň
    • • Např. "budova/mistnosti/+/teplota" vybere všechny topicy teplota na úrovni budova/mistnosti/ (budova/mistnosti/kotelna/teplota, budova/mistnosti/sklad/teplota, atd.)
    • # - více úrovní
    • • Např. "budova/mistnosti/#" vybere celou podřazenou hierarchii topiců pod úrovní budova/mistnosti/

• Příznak Retain - Pokud má zpráva při publikování tento příznak nastavený, je na brokeru uchována pod daným topicem a lze ji číst (subscribe), i pokud nedochází k novým publikacím na daný topic.
• QoS - Quality of Service. Určuje úroveň ověřování doručení zpráv.
  • 0 - Je odeslána pouze zpráva. Doručení není ověřené
  • 1 - Je odesláno potvrzení o přijetí zprávy (PUBLISH - PUBACK)
  • 2 - Je provedena obousměrná výměna zaručující doručení (PUBLISH - PUBREC - PUBREL - PUBCOMP)

Průběh komunikace dle nastaveného QoS

Tento komunikační protokol je podporovaný na platformách:

• mark130.2
• mark220LX
• mark320LX
• mark520
• markMX.2
• markMX.3
• markMXL
• IMIO110.2
• IMIO105.2
• ICIO205.2
• Windows RT
• Wall - všechny typy

Vytvoření kanálu

Pro vytvoření nového kanálu klikneme pravým tlačítkem myši na PLC a vybereme "Přidat kanál". Na tomto kanálu poté vybereme protokol MQTT.

Vlastnosti kanálu

Název - obvykle se pojmenuje podle zařízení, která jsou na něj připojena, nebo sběrnice v projektu.

Povolit - kanál musí být povolen (True), aby komunikoval.

Interval čtení / zápis - jak často má kanál zakomunikovat. Pro trvalou komunikaci, tj. co nejrychleji za sebou, nechte 0 ms.

Linkový protokol - v aktuální verzi podporovaný pouze TCP

Pauza mezi telegramy - doba neaktivity mezi odesíláním jednotlivých dotazů

• Je-li nastaveno na vysokou hodnotu (>2s), může dojít k nenavázání spojení s brokerem (záleží na nastavení brokera).

Vytvoření komunikačního zařízení

Vytvoříme zařízení pod daným kanálem a vyplníme jeho vlastnosti.

Vlastnosti zařízení

• Název - obvykle se pojmenuje podle zařízení, která jsou na něj připojena, nebo sběrnice v projektu.
• Povolit - kanál musí být povolen (True), aby komunikoval.
• Interval čtení / zápis - jak často má zařízení zakomunikovat. Pro trvalou komunikaci, tj. co nejrychleji za sebou, nechte 0 ms.
• Je specifický box - informace o tom, zda je zařízení z knihovny, nebo ho lze upravovat.

Konfigurace subscription

• QoS - Viz. QoS
• Retain podle publikace - je-li True, tak zprávy s příznakem retain budou přijaty s hodnotou platnou v okamžiku jejich publikování

  ---

• Zpracování retain - Určuje zpracování zpráv s příznakem Retain (Viz. Retain)
  • Přijmout vše - Veškeré zprávy s příznakem Retain jsou zpracované
  • Přijmout nové - Pouze zprávy odlišné od již přijatých s příznakem Retain jsou zpracované
  • Ignorovat retain - Zpráva je vždy zpracována jako kdyby neměla příznak Retain
• Ignorovat lokální - Je-li True, čtecí skupiny budou ignorovat zprávy publikované z tohoto zařízení.

Parametry TCP

• Adresa zařízení - adresa IP nebo název hostitele brokera, se kterým chceme komunikovat (například mqtt.test.com, 192.168.1.250..)
• Ověřovat certifikát - možnost povolení ověření certifikátu. Pokud není certifikát ověřen, spojení se nenaváže - je-li tato volba True, v PLC musí být nahrány potřebné certifikáty a klíče a PLC musí mít přístup k příslušným certifikačním autoritám.
• Port zařízení - port brokera, se kterým chceme komunikovat.
• SSL povoleno - povolení šifrované komunikace. Pokud je povolena, v PLC musí být nahrány potřebné certifikáty a klíče.

Parametry zařízení MQTT

• Název klienta - Název, pod kterým se PLC hlásí brokeru.
• Uživatel - Uživatelské jméno pro přihlášení (pokud vyžadováno brokerem).
• Heslo - Heslo pro přihlášení (pokud vyžadováno brokerem).
• Časový limit KeepAlive - Maximální interval pro odesílání zpráv ping pro udržení spojení.
• Časový limit QoS - Doba čekání pro potvrzení QoS zprávy před chybou komunikace a resetem komunikace.
• Interval vypršení relace - Doba, po kterou broker a klient uchovávají nepotvrzené zprávy.

Definice prototypu

• ID modelu - volně definovatelné, poznámka pro konkrétní typ zařízení.
• ID verze přístroje - volně definovatelné, poznámka pro konkrétní verzi zařízení.
• ID výrobce - volně definovatelné, poznámka pro jméno výrobce zařízení.
• Zámek pro linkový protokol - má být False.
• **Verze prototypu **- volitelný text, formát "Vx_y"
• Stav - poznámka pro fázi vývoje.

Informace o zařízení

• Model - volně definovatelné, poznámka pro název hardwaru.
• Verze - volně definovatelné, poznámka pro verzi hardwaru.
• Výrobce - volně definovatelné, poznámka pro název výrobce
• Cesta kategorie - cesta, kde se zobrazí prototyp zařízení v menu "Přidat zařízení z knihovny", používá se pro lepší orientaci ve stromu uživatelsky definovaných zařízení.

Editor zařízení

Po otevření editoru zařízení je zde možnost klasického přidání skupiny a datových bodů. Další možností pro vytváření datových bodů je z editoru šablony, popsáno dále.

Postup pro přidání skupiny:

• Pravým kliknutím na pracovní plochu v editoru zařízení otevřeme kontextové menu
• Vybereme "Přidat skupinu"
• Vyplníme parametry skupiny

Vlastnosti skupiny

• Název - jméno skupiny.
• Interval čtení/zápis - jak často má skupina zakomunikovat. Pro trvalou komunikaci, tj. co nejrychleji za sebou, nechte 0 ms.
• Typ skupiny - volba mezi ReadOnly (pouze pro čtení, Subscribe) a WriteOnly (pouze pro zápis, Publish).

Parametry skupiny MQTT (ReadOnly)

• Topic - viz. Topic

  ---

• Šablona těla zprávy
  • SimpleJPath
    • Slouží pro práci s hodnotami ve formátu JSON

      ---

  • TextFormatter
    • Slouží pro práci s hodnotami v obecných textových formátech

Parametry skupiny MQTT (WriteOnly)

• Will zpráva - označuje skupinu jako zapisovací pro tzv. Will zprávu. Jedná se o speciální typ zprávy, kterou broker hned po přijetí neposílá ostatním klientům. Místo toho ji má uloženou až do okamžiku odpojení daného klienta, teprve pak ji publikuje dál.
• Topic - viz. Topic
• QoS - viz. QoS
  • Poznámka: S nastaveným QoS 1 nebo 2 je frekvence publikování zpráv několikanásobně vyšší než u QoS 0. Jedná se o vlastnost driveru.
  • Není-li toto chování chtěné, například kvůli omezené rychlosti připojení nebo limitu počtu zpráv za vteřinu brokera, nastavte na kanále vyšší interval Pauza mezi telegramy (např. 500ms).
• Retain - Zpráva bude publikovaná s příznakem Retain
• Typ obsahu - Určuje hlavičku zapsanou do zprávy. Příjemci podává informaci o typu obsahu.
  • None - žádná hlavička
  • Text - obecný text (text/plain)
  • Json - formát JSON (application/json)
  • Xml - formát XML (application/xml)
  • Raw - binární data (application/octet-stream)
• Šablona těla zprávy
  • SimpleJPath
    • Slouží pro práci s hodnotami ve formátu JSON

      ---

  • TextFormatter
    • Slouží pro práci s hodnotami v obecném textovém formátu

Šablona SimpleJPath

Textové pole slouží pro vytváření šablony samotné. Panel vpravo nahoře umožňuje vytváření a linkování proměnných z kontextového menu (pravé kliknutí -> Přidat datový bod), zároveň zobrazuje výsledný vzorec JPath hledaných hodnot. Panel vpravo dole slouží k vytváření vazby klíčů na datové body, popsáno dále. Možnost "Zobrazit všechny znaky" zapne vykreslování neviditelných znaků (mezera, tabulátor, nový řádek...) v textovém poli. V šabloně SimpleJPath jsou názvy mapovaných proměnných ohraničené složenými závorkami v uvozovkách. Při publikování je též možné mapovat více proměnných znakem svislé čáry (|), např. "{promenna_1|promenna2}", naformátované hodnoty datových bodů se pak zapíší za sebe. Příklad šablony SimpleJPath

Klíče

Pro přidání klíče klikneme pravým tlačítkem na vlastnost objektu a vybereme "Přidat klíč". Vlastnosti objektů, které lze využít jako klíče jsou automaticky podbarveny.

Klíčů se dá využít pro získání hledané hodnoty z pole objektů. V následujícím příkladu je použit pro vybrání hodnoty temperature z objektu v poli, pouze pokud se vlastnost city rovná řetězci "Frankfurt".

Příklad použití klíčů SimpleJPath

Možnost "Považovat za řetězec/hodnotu"

Chceme-li například publikovat hexadecimální hodnotu jako řetězec, klikneme pravým tlačítkem na mapovaný datový bod v editoru a vybereme "Považovat za řetězec."

Vybraná hodnota se zobrazí v panelu vpravo dole, který u publish skupin SimpleJPath slouží pro tento účel.

Výsledná hodnota ve zprávě pak bude zapsaná jako řetězec, tedy např. "hodnota": "0xFF00" místo "hodnota": 0xFF00. Pokud není publikovaná hodnota zaručeně číslo v desítkové soustavě anebo binární true/false, např. u formátovačů Hexadecimal či Mapping, tak je nutné tuto hodnotu nastavit jako řetězcovou, jinak může být struktura výsledného JSONu neplatná!

Šablona TextFormatter

Textové pole slouží pro vytváření šablony samotné. Pole Start marker a End marker slouží pro nastavování znaků, které v šabloně označují proměnnou. Panel vpravo umožňuje vytváření a linkování proměnných z kontextového menu (pravé kliknutí -> Přidat datový bod). Možnost "Zobrazit všechny znaky" zapne vykreslování neviditelných znaků (mezera, tabulátor, nový řádek...) v textovém poli. V šabloně TextFormatter jsou volně nastavitelné znaky co označují proměnnou, nemusí být v uvozovkách. Text lze uspořádat v podstatě do jakéhokoliv neměnného textového formátu (CSV, XML, Line Protocol, apod.) Při publikování je též možné mapovat více proměnných znakem svislé čáry (|), např. [promenna_1|promenna2], naformátované hodnoty datových bodů se pak zapíší za sebe (má stejný efekt jako [promenna_1][promenna_2]). Je též možné vytvářet statické šablony pro publikování, čili neměnný text (bez mapovaných proměnných). Příklad šablony TextFormatter

V další části definujeme datové body, do nichž bude driver načítat hodnoty, vyčtených při komunikaci skupiny.

Vlastnosti datového bodu

• Název - jméno proměnné, pod ním bude proměnná identifikovaná v programu
• Skupina - vybereme skupinu, do níž proměnná přísluší.
• Typ skupiny - vyplní se automaticky po vybrání skupiny.
• Typ mapované kom. hodnoty - výběr mezi BuiltIn a Bit. Typ Array není u MQTT podporovaný!
• Typ ST - vybereme typ proměnné, která vznikne touto definicí.
• Transformace - Mezi načtením hodnoty a přiřazením do proměnné je možné hodnotu přepočítat - transformovat. Využívá se to např. v případě, že se přenáší analogová hodnota (teplota), pro větší rozlišení násobená 10 nebo 100 (formát tzv. HVAC Integer).

Autogen

• Povolit autogen - Povolením Autogenu (automatického generování) se při kompilaci automaticky vytvoří globální proměnné a namapují se na vstupní a výstupní proměnné. Teprve s globálními proměnnými je možné pracovat v programech a vkládat je do žebříčků FUPLA. Pokud není Autogen povolen, je nutné globální proměnné vytvářet a přiřazovat vstupním a výstupním proměnným manuálně. Doporučuje se nastavit Povolit Autogen = True.

Mapování

• IO => ST - mapování vstupní proměnné na globální proměnnou ("vstup - výstup na strukturovaný text či FUPLA").
• ST => IO - mapování globální proměnné na výstupní proměnnou ("strukturovaný text či FUPLA na vstup - výstup").

Parametry datových bodů zařízení MQTT

Obecné parametry formátovačů

• Prefix - Po vyplnění se tento řetězec bude u subscribe očekávat před hodnotou. U publish se bude před hodnotu dodatečně zapisovat.
• Suffix - Po vyplnění se tento řetězec bude u subscribe očekávat za hodnotou. U publish se bude za hodnotu dodatečně zapisovat.
• Automatické mezery  - pokud je True, tak mezi hodnotou a prefixem/sufixem je u publish doplněna mezera. U subscribe se mezery budou očekávat mezi specifikovaným prefixem/sufixem
• Vynutit znaménko - (pouze publish) - číselná hodnota se vždy zapisuje se znaménkem (např. "+45" místo "45")
• Minimální délka - (pouze publish) - minimální délka výsledného textu čísla (doplněno nulami na začátku, pokud je počet nul čísla menší než nastavená hodnota)
  • Doplnit mezerami - (pouze publish) - doplní mezerami místo nul
• Počet desetinných míst - (pouze publish) - počet zapisovaných desetinných míst čísla. Pokud je hodnota vyšší než dovoluje přesnost datového typu, je doplněno nulami

Formátovač

• None
  • Hodnota je ignorována

• Integer - Převod celočíselné hodnoty

  • Obecné parametry: Prefix, Suffix, Automatické mezery, Vynutit znaménko, Minimální délka, Doplnit mezerami (viz. výše)
  • Kompatibilní se všemi celočíselnými i neceločíselnými datovými typy
    • Při použití s desetinnými čísly je hodnota zaokrouhlena!
  • Převáděná textová hodnota čísla může být řetězcem ("hodnota": "16") nebo volným číslem ("hodnota": 16)

• FloatingPoint - Převod desetinného čísla

  • Obecné parametry: Prefix, Suffix, Automatické mezery, Vynutit znaménko, Minimální délka, Doplnit mezerami, Počet desetinných míst (viz. výše)
  • Kompatibilní se všemi celočíselnými i neceločíselnými datovými typy
    • Při použití s celočíselnými datovými typy je hodnota zaokrouhlena!
  • Převáděná textová hodnota čísla může být řetězcem ("hodnota": "16.9") nebo volným číslem ("hodnota": 16.9)

• Hexadecimal - Převod čísla mezi zápisem šestnáctkové a desítkové soustavy

  • Obecné parametry: Prefix, Suffix, Automatické mezery, Doplnit mezerami (viz. výše)
  • Hexadecimální prefix - Žádný, 0x, nebo 0X. Zapisuje se před číslo - např. 0xAB3C
  • Velká písmena - je-li True, zapisuje velkými písmeny (např. 00AB3C)
  • Kompatibilní se všemi celočíselnými i neceločíselnými datovými typy

• Date - Převod řetězce datumu

  • Obecné parametry: Prefix, Suffix, Automatické mezery (viz. výše)
  • Kompatibilní s datovými typy datumu
  • Formátovací řetězec
    • d - dny
    • M - měsíce
    • y - roky

• Time - Převod řetězce času

  • Obecné parametry: Prefix, Suffix, Automatické mezery (viz. výše)
  • Kompatibilní s datovými typy času
  • Formátovací řetězec
    • h - hodiny
    • m - minuty
    • s - vteřiny
    • f - desetinná část vteřiny (podporováno až na 9 míst)

• DateTime - převod řetězce datumu a času

  • Obecné parametry: Prefix, Suffix, Automatické mezery (viz. výše)
  • Kompatibilní s datovými typy datumu, času a DT
  • Formátovací řetězec
    • d - dny
    • M - měsíce
    • y - roky
    • h - hodiny
    • m - minuty
    • s - vteřiny
    • f - desetinná část vteřiny (podporováno až na 9 míst)
  • Příklad: 2024-10-09_14:09:06.1255 -> yyyy-MM-dd_hh:mm:ss.ffff

• Mapping - Mapování stavů

  • Obecné parametry: Prefix, Suffix, Automatické mezery (viz. výše)
  • Umožňuje mapovat číselné hodnoty na textové při publikování anebo opačně při zápisu
  • Kompatibilní se všemi celočíselnými datovými typy
  • Bez ohledu na datový typ mapované proměnné je maximální podporovaný rozsah mapování -2147483648 až +2147483647, čili rozsah datového typu LINT.
  • Příklad mapování:
  • 

• Length - Délka řetězce

  • Nelze použít u publish
  • Typ měření
    • Délka vyrovnávací paměti - počet bajtů pole, které tvoří řetězec
    • ASCII řetězec - délka po převedení na řetězec ASCII (v tomto formátu jsou znaky kódované fixně jedním bajtem)
    • UTF-8 řetězec - délka po převedení na řetězec UTF-8 (v tomto formátu jsou znaky kódované v proměnné délce 1-4 bajtů)
    • UTF-16LE řetězec - délka po převedení na řetězec UTF-16 - malý endian (v tomto formátu jsou znaky kódované v proměnné délce 2 nebo 4 bajtů)
    • UTF-16BE řetězec - délka po převedení na řetězec UTF-16 - velký endian (v tomto formátu jsou znaky kódované v proměnné délce 2 nebo 4 bajtů)

• Raw - Přímé kopírování bajtů
  • Varování: jelikož tento formátovač může produkovat neplatné nebo řídící znaky, jeho použití v publikované zprávě s dalším textem (např. JSON) může mít za následek obsah, který zprávu pravděpodobně znehodnotí!
  • Přímo kopíruje bajty, ze kterých se proměnná skládá. Např. text "abc1" -> 0x61626331 (kódování ASCII)
  • Offset dat (Parser) - Číslováno od 0; určuje, na kolikátém bytu začínají data proměnné. 
  • Bitový offset (Parser) - Posouvání v bajtu mezi jednotlivými bity. Např. pro čtení nebo zápis 3. bitu v bajtu. Počítá se od 0, tedy pro čtení 4. bitu (bit 3) bude Bitový offset = 3. Nastavuje se v intervalu 0 až 7.
  • Délka Multibyte (Parser) - Kolik bajtů se má zapisovat/číst z/do proměnné
  • Pořadí Multibyte (Parser) - V tomto řetězci je možné zvolit pořadí bajtů, v jakém se budou z telegramu mapovat na datový typ proměnné. Řeší se tím různé varianty formátů typu "rotate", "non-rotate", "byte swap", "word swap", "Intel byte order" atd. Výchozí hodnota je "12345678", obvykle ji není nutné měnit.

Poznatky z testování

Testováno na brokerech:

• RabbitMQ
  • V současné době nepodporuje QoS 2. Klienti, kteří se pokouší připojit s QoS 2 jsou okamžitě odpojeni. Jedná se o vlastnost brokera samotného.
• LavinMQ
• EMQX
• HiveMQ
• Mosquitto