...
Protokol je implementáciou štandardu MQTT 3.1.1 (október 2014). MQTT protokol je klient/server protokol typu subscribe/publish. Je jednoduchý, má malú réžiu a je ľahko implementovateľný. Používa sa na komunikáciu M2M (Machine to Machine) a v kontexte IoT (Internet of Things).
D2000 KOM implementuje klientskú časť protokolu. Protokol je implementovaný na TCP/IP linke.
Pre prenos LoRaWAN dát v rámci MQTT protokolu pozri popis protokolu LoRaWan.Každá PUBLISH správa obsahuje tému (Topic), samotné dáta (Payload) a úroveň potvrdzovania (QoS). PUBLISH správy môže odosielať klient aj server. Klient na začiatku komunikácie použije správu SUBSCRIBE na oznámenie, o aké témy (parameter protokolu Topic Filter) má záujem. Kotva
- QoS_0 - správa PUBLISH nie je potvrdzovaná, môže dôjsť ku strate
- QoS_1 - správa PUBLISH je druhou stranou potvrdzovaná PUBACK, môže dôjsť k duplicite
- QoS_2 - správa PUBLISH je druhou stranou potvrdzovaná PUBREC, tá je spätne potvrdzovaná správou PUBREL a tá finálne správou PUBCOMP
Úroveň potvrdzovania správ posielaných procesom D2000 KOM definuje parameter protokolu Publish QoS. D2000 KOM proces považuje zápis výstupného meraného bodu za úspešne ukončený v závislosti od QoS:
- QoS_0 - po úspešnom odoslaní dát cez TCP spojenie
- QoS_1 - po prijatí PUBACK
- QoS_2 - po prijatí PUBCOMP
Komunikácia bola testovaná/nasadená voči:
- cloudu TheThings.Network
- cloudu Loriot.io
- cloudu Slovanet
- Pixii PowerShaper (energy storage solution)
- cloudu liveobjects.orange-business.com
Pozn: bola otestovaná aj komunikácia voči cloudu liveobjects.orange-business.com cez websockety (wss://liveobjects.orange-business.com:443/mqtt). Ako WSS wrapper bol použitý program https://github.com/jimparis/unwebsockify.git. Tento bol spustený s parametrami:
./unwebsockify.py --port 1883 --listen 172.16.0.1 wss://liveobjects.orange-business.com:443/mqtt
D2000 KOM proces sa pripájal k adrese 172.16.0.1 na port 1883. WSS wrapper sa pripojil na definovanú URL a zabalil dáta MQTT komunikácie do websocket obálky.
Každá PUBLISH správa obsahuje tému (Topic), samotné dáta (Payload) a úroveň potvrdzovania (QoS). PUBLISH správy môže odosielať klient aj server. Klient na začiatku komunikácie použije správu SUBSCRIBE na oznámenie, o aké témy (parameter protokolu Topic Filter) má záujem.
Kotva | ||||
---|---|---|---|---|
|
- QoS_0 - správa PUBLISH nie je potvrdzovaná, môže dôjsť ku strate
- QoS_1 - správa PUBLISH je druhou stranou potvrdzovaná PUBACK, môže dôjsť k duplicite
- QoS_2 - správa PUBLISH je druhou stranou potvrdzovaná PUBREC, tá je spätne potvrdzovaná správou PUBREL a tá finálne správou PUBCOMP
Úroveň potvrdzovania správ posielaných procesom D2000 KOM definuje parameter protokolu Publish QoS. D2000 KOM proces považuje zápis výstupného meraného bodu za úspešne ukončený v závislosti od QoS:
- QoS_0 - po úspešnom odoslaní dát cez TCP spojenie
- QoS_1 - po prijatí PUBACK
- QoS_2 - po prijatí PUBCOMP
Komunikácia MQTT sa začína správou CONNECT, ktorú pošle klient (D2000 KOM). Správa obsahuje prihlasovacie meno (User Name), heslo (Password) a ďalšie parametre, z ktorých sa dá nastaviť Clean Session Flag a Client ID (parameter Will Flag sa nevyužíva, podobne ako Will QoS a Will Retain, parameter Keep Alive je nastavený na 0). Server odpovedá správou CONNACK s návratovým kódom, ktorý obsahuje informáciu o úspešnosti pripojenia.
Následne klient pošle správu SUBSCRIBE s filtrom tém (parameter Topic Filter), o ktoré má záujem a požadovanou maximálnou úrovňou potvrdzovania (parameter Subscribe QoS).
Server odpovedá návratovým kódom, ktorý obsahuje informáciu o úspešnosti a maximálny QoS, ktorý Komunikácia MQTT sa začína správou CONNECT, ktorú pošle klient (D2000 KOM). Správa obsahuje prihlasovacie meno (User Name), heslo (Password) a ďalšie parametre, z ktorých sa dá nastaviť Clean Session Flag a Client ID (parameter Will Flag sa nevyužíva, podobne ako Will QoS a Will Retain, parameter Keep Alive je nastavený na 0). Server odpovedá správou CONNACK s návratovým kódom, ktorý obsahuje informáciu o úspešnosti pripojenia.
Následne klient pošle správu SUBSCRIBE s filtrom tém (parameter Topic Filter), o ktoré má záujem a požadovanou maximálnou úrovňou potvrdzovania (parameter Subscribe QoS).
Server odpovedá návratovým kódom, ktorý obsahuje informáciu o úspešnosti a maximálny QoS, ktorý bol pre požadované témy pridelený.
Nasleduje bežná komunikácia, počas ktorej klient aj server posielajú PUBLISH správy (klient s ľubovoľnou témou, server s témami zodpovedajúcimi filtru tém prijatej SUBSCRIBE správy) a podľa hodnoty parametra QoS prijatých správ PUBLISH ich potvrdzujú.
Pokiaľ server nepošle žiadnu správu dlhšie ako Ping Interval sekúnd, klient pošle PING request správu, na ktorú server musí odpovedať PING response správou (do času špecifikovaného parametrom Reply Timeout).
Pokiaľ dôjde k zmene parametrov na linke, spojenie je zavreté a znovu vytvorené.
Komunikácia bola otestovaná voči MQTT serveru www.TheThings.network.
...
Parameter | Popis | Jednotka / rozmer | Náhradná hodnota | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Zapnutie podrobných výpisov o posielaní a prijímaní hodnôt. | YES/NO | NO | |||||||||||||||||||||||||
| Užívateľské meno použité v správe CONNECT na pripojenie sa k MQTT serveru. | - | ||||||||||||||||||||||||||
| Heslo použité v správe CONNECT na pripojenie sa k MQTT serveru. | - | ||||||||||||||||||||||||||
| Meno jednej témy alebo filter pre viacero tém posielaný v rámci SUBSCRIBE správy. Filtrom špecifikuje MQTT klient témy, v rámci ktorých chce prijímať správy. Pozn: témy sú zoradené hierarchicky, ako oddeľovač slúži lomka (/), ako maska jednej úrovne slúži plus (+), ako maska pre viacero úrovní znak hash (#). Príklady filtra: a/b , level1/+ , # , +/+/+/up | - | # | |||||||||||||||||||||||||
Kotva | sq | sq | Subscribe QoSPožadovaná maximálna úroveň potvrdzovania (QoS) posielaná v rámci SUBSCRIBE správy. MQTT server môže následne posielať PUBLISH správy s takouto alebo nižšou úrovňou potvrdzovania (ale nie vyššou). PUBLISH správy posielané MQTT serverom budú potvrdzované procesom D2000 KOM podľa úrovne potvrdzovania v nich špecifikovanej. Čím vyššia je úroveň potvrdzovania, tým viac správ je medzi klientom a serverom vymenených (1 pri QoS_0, 2 pri QoS_1 a 4 pri QoS_2). | QoS_0 QoS_1 QoS_2 | QoS_1 | |||||||||||||||||||||||
Kotva | ci | ci | Client IDUnikátny identifikátor klienta (Client Identifier) posielaný v rámci CONNECT správy. Pozn: je možné zadať aj prázdny reťazec - v tom prípade server môže klientovi prideliť unikátne meno (pokiaľ takúto funkcionalitu podporuje) alebo vráti chybu. Pokiaľ nie je zadaný Client ID, bude ale ignorované nastavenia parametra Clean Session Flag (keďže server pridelí zakaždým unikátne meno). Testovaný MQTT server (thethings.network) vrátil chybu, pokiaľ bolo Client ID prázdne a Clean Session Flag=NO. | - | ||||||||||||||||||||||||
Kotva | cs | cs | Clean Session Flagrámci SUBSCRIBE správy. Filtrom špecifikuje MQTT klient témy, v rámci ktorých chce prijímať správy. Pozn: témy sú zoradené hierarchicky, ako oddeľovač slúži lomka (/), ako maska jednej úrovne slúži plus (+), ako maska pre viacero úrovní znak hash (#). Príklady filtra: a/b , level1/+ , # , +/+/+/up | - | # | |||||||||||||||||||||||
| Požadovaná maximálna úroveň potvrdzovania (QoS) posielaná v rámci SUBSCRIBE správy. MQTT server môže následne posielať PUBLISH správy s takouto alebo nižšou úrovňou potvrdzovania (ale nie vyššou). PUBLISH správy posielané MQTT serverom budú potvrdzované procesom D2000 KOM podľa úrovne potvrdzovania v nich špecifikovanej. Čím vyššia je úroveň potvrdzovania, tým viac správ je medzi klientom a serverom vymenených (1 pri QoS_0, 2 pri QoS_1 a 4 pri QoS_2). | QoS_0 QoS_1 QoS_2 | QoS_1 | |||||||||||||||||||||||||
| Unikátny identifikátor klienta (Client Identifier) posielaný v rámci CONNECT správy. Pozn: je možné zadať aj prázdny reťazec - v tom prípade server môže klientovi prideliť unikátne meno (pokiaľ takúto funkcionalitu podporuje) alebo vráti chybu. Pokiaľ nie je zadaný Client ID, bude ale ignorované nastavenia parametra Clean Session Flag (keďže server pridelí zakaždým unikátne meno). Testovaný MQTT server (thethings.network) vrátil chybu, pokiaľ bolo Client ID prázdne a Clean Session Flag=NO. Pozn: konkrétny MQTT broker (PIXII.COM) identifikoval klientov iba podľa Client ID. V praxi to spôsobovalo, že dva rôzne D2000 systémy, ktoré sa pripájali k jednému brokerovi, boli považované za jedného klienta a broker pri vytvorení spojenia zrušil existujúce spojenie, ktoré považoval za staré. Po nastavení Client ID na unikátnu hodnotu začali komunikácie fungovať bez rozpadov spojení. | - | ||||||||||||||||||||||||||
| Parameter Clean Session Flag správy CONNECT. Hodnota No znamená, že server použije aktuálny stav session (spojenia) - napr. po rozpade a znovuobnovení TCP spojenia. Znamená to, že sú zaslané všetky nepotvrdené PUBLISH správy s QoS_1 a QoS_2 (a voliteľne aj QoS_0 v závislosti na implementácii). Hodnota Yes znamená, že sa session vytvorí nanovo a žiadne nepotvrdené PUBLISH správy nie sú opakované. | YES/NO | NO | |||||||||||||||||||||||||
| Úroveň potvrdzovania (QoS) použitá pri posielaní PUBLISH správ procesom D2000 KOM. Poslanie PUBLISH správy je dôsledok zápisu do výstupného meraného bodu s adresou OUT_VALUE. Čím vyššia je úroveň potvrdzovania, tým viac správ medzi klientom a serverom poslaných (1 pri QoS_0, 2 pri QoS_1 a 4 pri QoS_2). | QoS_0 QoS_1 QoS_2 | QoS_0 | |||||||||||||||||||||||||
| Nastavenie príznaku Retain použité pri posielaní PUBLISH správ procesom D2000 KOM. Aktivácia príznaku Retain spôsobí, že posledná správa poslaná procesom D2000 KOM bude na MQTT serveri dostupná iným klientom okamžite po ich pripojení, ako aj po odpojení D2000 KOM procesu | Parameter Clean Session Flag správy CONNECT. Hodnota No znamená, že server použije aktuálny stav session (spojenia) - napr. po rozpade a znovuobnovení TCP spojenia. Znamená to, že sú zaslané všetky nepotvrdené PUBLISH správy s QoS_1 a QoS_2 (a voliteľne aj QoS_0 v závislosti na implementácii).. | YES/NO | NO | ||||||||||||||||||||||||
| Úroveň potvrdzovania (QoS) použitá pri posielaní PUBLISH správ procesom D2000 KOM. Poslanie PUBLISH správy je dôsledok zápisu do výstupného meraného bodu s adresou OUT_VALUE. Čím vyššia je úroveň potvrdzovania, tým viac správ medzi klientom a serverom poslaných (1 pri QoS_0, 2 pri QoS_1 a 4 pri QoS_2). | QoS_0 QoS_1 QoS_2 | QoS_0 | |||||||||||||||||||||||||
Kotva | pr | pr | Publish RetainNastavenie príznaku Retain použité pri posielaní PUBLISH správ procesom D2000 KOM. Aktivácia príznaku Retain spôsobí, že posledná správa poslaná procesom D2000 KOM bude na MQTT serveri dostupná iným klientom okamžite po ich pripojení, ako aj po odpojení D2000 KOM procesu. | YES/NO | NO | |||||||||||||||||||||||
Kotva | pi | pi | Ping IntervalPokiaľ MQTT server neposlal za špecifikovaný časový interval žiadnu správu, D2000 KOM proces pošle výzvu PING request a očakáva odpoveď PING response (do času Reply Timeout). Hodnota 0 posielanie PING request správ vypína. Parameter umožňuje detekovať rozpadnutie TCP spojenia. | sec | 60 | |||||||||||||||||||||||
Kotva | pt | pt | Payload TypePing Interval | Pokiaľ MQTT server neposlal za špecifikovaný časový interval žiadnu správu, D2000 KOM proces pošle výzvu PING request a očakáva odpoveď PING response (do času Reply Timeout). Hodnota 0 posielanie PING request správ vypína. Parameter umožňuje detekovať rozpadnutie TCP spojenia. | sec | 60 | ||||||||||||||||||||||
| Nastavenie parsovania správy:
| Text only JSON | Text only | |||||||||||||||||||||||||
| Ak Payload Type=JSON, tak názov poľa s časovou značkou. Ak názov nie je zadaný alebo pole nie je nájdené, hodnotám je priradený aktuálny čas. | - | - | |||||||||||||||||||||||||
| Maska pre parsovanie hodnoty v poli s časovou značkou. Pozn: od nastavení časových parametrov stanice závisí, či je čas interpretovaný ako lokálny alebo UTC s nakonfigurovaným offsetom. Špeciálne masky sú:
| - | yyyy-mm-dd hh:mi:ss.mss | |||||||||||||||||||||||||
Nastavenie parsovania správy:
| Text only JSON | Text only |
| Parameter Will Flag správy CONNECT. Hodnota Yes znamená, že server pošle záujemcom správu Last Will v prípade straty spojenia s D2000 KOM procesom. | YES/NO | NO | ||||||||||||||||||||||
| Úroveň potvrdzovania (QoS) použitá pri posielaní správy Last Will v prípade straty spojenia s D2000 KOM procesom. | QoS_0 QoS_1 QoS_2 | QoS_0 | |||||||||||||||||||||||||
| Nastavenie príznaku Retain použité pri posielaní správy Last Will v prípade straty spojenia s D2000 KOM procesom. | YES/NO | NO | |||||||||||||||||||||||||
| Topic použitý pri posielaní správy Last Will v prípade straty spojenia s D2000 KOM procesom. | - | ||||||||||||||||||||||||||
| Obsah správy Last Will v prípade straty spojenia s D2000 KOM procesom. | - | ||||||||||||||||||||||||||
| Pokiaľ do požadovaného času MQTT server neodpovie na správy SUBSCRIBE, UNSUBSCRIBE a PING request, prípadne sa nepodarí načítať ľubovoľnú správu (a je načítaná iba jej časť), D2000 KOM proces vyhlási chybu, zavrie spojenie a znovu ho otvorí. Hodnota 0 vypína časový limit. Parameter umožňuje reagovať na problematické chovanie MQTT servera. | sec | 20 | |||||||||||||||||||||||||
| Timeout čakanie pri jednom čítaní z TCP spojenia. D2000 KOM opakuje čítanie spontánnych dát Max. Wait Retry krát a pokiaľ nenačíta žiadne dáta, je vyhlásený timeout a čítanie je ukončené (a môže nasledovať ďalšie čítanie alebo prípadne zápis). Zmenšením parametrov Wait Timeout a Max. Wait Retry je možné dosiahnuť rýchlejšiu odozvu D2000 KOM procesu na zápis na úkor vyššej záťaže CPU, pokiaľ MQTT server nemá žiadne dátaD2000 KOM procesu na zápis na úkor vyššej záťaže CPU, pokiaľ MQTT server nemá žiadne dáta. Pozn: ak od MQTT servera prichádza veľa správ a D2000 KOM potrebuje aj zapisovať hodnoty, odporúčame nižšu hodnotu parametra (napr. 0.005 sec), aby zápis nebol blokovaný čítaním (v každom prípade ale po 10 prijatých správach nasleduje prerušenie, počas ktorého sa môžu vykonať nahromadené zápisy). | sec | 0.100 | |||||||||||||||||||||||||
| Počet opakovaní čítania z TCP spojenia. Pozri popis parametra Wait Timeout. | - | 3 |
...
Možné typy hodnôt meraných bodov: Ci, Co, TxtI, TxtO, TxtI, TxtO, Qi, Ci, Co, Ai, Ao, Di, Do, TiR, ToR, TiA, ToA.
Typ bodu | Adresa | Popis | ||||||
---|---|---|---|---|---|---|---|---|
Body pre čítanie dát poslaných MQTT serverom správou PUBLISH. Pozn: hodnoty bodov sú nastavené D2000 KOM procesom v poradí IN_TOPIC, IN_DATA a IN_ID. Nie je nutné, aby konfigurácia obsahovala všetky tri body. | ||||||||
TxtI |
| Téma (Topic) prijatej správy PUBLISH. | ||||||
TxtI |
| Dáta (Payload) prijatej správy PUBLISH. | ||||||
Ci |
| Identifikátor paketu (Packet Identifier) správy PUBLISH, ktorý závisí od úrovne potvrdzovania (QoS). Pre správy posielané s QoS_0 je identifikátor nulový, pre QoS_1 a QoS_2 je to kladné 16-bitové číslo. Pozn: ak MQTT server posiela aj správy s úrovňou potvrdzovania QoS_0 a je nakonfigurovaný bod ACK_ID, odporúčame v záložke Filter aktivovať voľbu Nová hodnota pri zmene času, aby opakovaný zápis hodnoty 0 spôsobil generovanie novej hodnoty líšiacej sa iba časovou značkou. | ||||||
Body pre parsovanie JSON správ | ||||||||
TxtI, TxtO, Qi, |
| Pokiaľ Payload Type=JSON, správa je parsovaná ako JSON dáta. Hodnota json_address udáva názov JSON poľa, ktorého hodnota sa má priradiť do meraného bodu. Príklady viď popis meraných bodov typu Envelope protokolu LoRaWAN. | ||||||
Bod pre potvrdenie prijatia dát MQTT serveru. | ||||||||
Co |
| Ak je definovaný výstupný meraný bod s adresou ACK_ID, D2000 KOM očakáva potvrdenie spracovania každej správy zápisom kópie hodnoty bodu IN_ID. Až následne nastaví do bodov IN_TOPIC, IN_DATA a IN_ID (v tomto poradí) hodnoty z ďalšej prijatej PUBLISH správy (ak bola medzitým prijatá). V prípade úrovne potvrdzovania QoS_0 je teda nutné opakovane zapisovať do bodu hodnotu 0. Pokiaľ meraný bod ACK_ID neexistuje, hodnoty do bodov IN_TOPIC, IN_DATA a IN_ID sú nastavované ihneď po spracovaní PUBLISH správy. Pozn: pre správy prijaté s úrovňou potvrdzovania QoS_0 sa neposiela žiadne potvrdenie MQTT serveru, iba sa zverejnia hodnoty ďalšej prijatej PUBLISH správy. | ||||||
Body pre posielanie hodnôt MQTT serveru správou PUBLISH. Pozn: ak má D2000 KOM proces posielať MQTT serveru správy PUBLISH, musia byť definované obidva body v rámci jednej stanice. | ||||||||
TxtO |
| Téma (Topic) v rámci posielanej správy PUBLISH. | ||||||
TxtO |
| Dáta (Payload) v rámci posielanej správy PUBLISH. Pozn: poslanie správy sa uskutoční ako reakcia na zápis do bodu OUT_VALUE (t.j. pokiaľ sa Topic nemení, tak stačí bod OUT_TOPIC nastaviť jednorazovo - napr. pomocou štartovacej hodnoty). |
...
- Ver. 1.0 - 8. august 2017 - vytvorenie dokumentu.
- Ver. 1.1 - 15. október 2021 - podpora parametrov pre LastWill a Retain
- Ver. 1.2 - 27. október 2021 - podpora parsovania JSON správ
- Ver. 1.3 – 1. február 2022 – podpora časových značiek v správach JSON
Info | ||
---|---|---|
| ||
...