História stránky

Podporované typy a verzie zariadení
O protokole MQTT Sparkplug
Konfigurácia komunikačnej linky
Parametre protokolu linky
Konfigurácia komunikačnej stanice
Konfigurácia meraných bodov
Literatúra
Revízie dokumentu

...

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). MQTT server sa nazýva aj MQTT broker.
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.
KotvaqosqosProtokol definuje tieto úrovne potvrdzovania PUBLISH správ - QoS (Quality of Service):

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

...

Čiastočne je podporený aj Sparkplug 3.0.0 štandard (Sparkplug B MQTT Payload). Podpora zahŕňa:

čítanie jednoduchých typov hodnôt
čítanie polí (s podporou Cieľového stĺpca štruktúry)
zápis jednoduchých typov hodnôt

Nie je podporená práca so šablónami (UDT).

Komunikácia bola testovaná/nasadená voči:

cloudu www.TheThings.network
cloudu Loriot.io
cloudu Slovanet
Pixii PowerShaper (energy storage solution)
cloudu liveobjects.orange-business.com
test.mosquitto.org (Sparkplug B)

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
	qos

Protokol definuje tieto úrovne potvrdzovania PUBLISH správ - QoS (Quality of Service):

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ý 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é.

Kotva
sparkplug
sparkplug
O protokole MQTT Sparkplug

Protokol MQTT Sparkplug definuje 3 skupiny aplikácií:

Edge Node - má podporu MQTT protokolu a pripája sa k MQTT serveru. Posiela mu údaje získané z Device alebo vlastné, prípadne agregované
Device/Sensor - reprezentuje fyzické alebo logické zariadenie pripojené k Edge Node a poskytujúce údaje, procesné dáta alebo metriky
Host Application - reprezentuje spotrebiteľa dát (SCADA/MES systém, Historian, analytický nástroj), ktorý sa pripája k MQTT serveru a prijíma MQTT dáta od Edge Node/Device a prípadne poveluje. D2000 je Host Application.

Image Added

MQTT Sparkplug definuje nasledovné typy správ:

NBIRTH – Birth certificate for Sparkplug Edge Nodes (informácia o pripojení sa Edge Node k MQTT Serveru)
NDEATH – Death certificate for Sparkplug Edge Nodes (informácia o strate spojenia MQTT Servera s Edge Node)
DBIRTH – Birth certificate for Devices (informácia o pripojení sa Device k Edge Node)
DDEATH – Death certificate for Devices (informácia o strate spojenia Edge Node s Device)
NDATA – Edge Node data message (dáta od Edge Node)
DDATA – Device data message (dáta od Device)
NCMD – Edge Node command message (príkaz Host Application pre Edge Node)
DCMD – Device command message (príkaz Host Application pre Device)
STATE – Sparkplug Host Application state message (informácia od stave Host Application pre Edge Node/Device [online / offline]).

MQTT Sparkplug definuje pre všetky typy správ syntax tém (Topic), ktorý má tvar namespace/group_id/message_type/edge_node_id/[device_id], kde:

namespace je konštanta spBv1.0 (pre Sparkplug B)
group_id je ľubovolný názov logickej skupiny (napr. podľa typu zariadenia, prevádzky, organizačnej štruktúry atď)
message_type je typ správy
edge_node_id je identifikátor Edge Node
device_id je identifikátor Device (iba ak je správa od/pre Device)

Príklady:

spBv1.0/Sparkplug Devices/DDATA/Marvin/Sensor1
pBv1.0/MIMIC/DDATA/20:19:AB:F4:0E:0D/sensor11
spBv1.0/SparkplugDevices/NBIRTH/JsonScada

Poznámka: správy typu STATE majú Topic v tvare spBv1.0/STATE/sparkplug_host_id, kde sparkplug_host_id je unikátny názov hostiteľskej aplikácie.

Príklady:

spBv1.0/STATE/CFGHUB2023
spBv1.0/STATE/D2Kom

Všetky typy správ výnimkou STATE majú binárny Sparkplug payload. Správy STATE majú JSON payload (obsahuje iba položky "online" (hodnota True/False) a "timestamp" (časová značka v milisekundách).

Sparkplug payload obsahuje metriky - každú požadovanú metriku je možné nakonfigurovať do jedného meraného bodu. Metrika obsahuje textový identifikátor (zadávaný v konfigurácii meraného bodu ako sparkplug_address), typ hodnoty, hodnotu (jednoduchá/pole/štruktúrovaná), voliteľne časovú značku a ďalšie atribúty. D2000 podporuje prácu s jednoduchými hodnotami a hodnotami typu pole - do meraného bodu sa uloží prvá položka poľa; je možné na meranom bode nakonfigurovať Cieľový stĺpec štruktúry, do ktorého sa uložia všetky položky poľa (resp. prvých N, ak nemá štruktúra dostatočný počet riadkov).
Pozn: ak príde metrika, ktorá má nastavený príznak is_null, meraný bod bude mať Invalid hodnotu.

Kotva

	komunikacna_linka
	komunikacna_linka

Konfigurácia komunikačnej linky

...

Kategória komunikačnej linky: TCP/IP-TCP.
Host: IP adresa MQTT servera (prípadne redundantné adresy oddelené čiarkou alebo bodkočiarkou).
Port: číslo portu je štandardne 1883 alebo 8883 pre kryptovanú SSL/TLS variantu.
Číslo linky: nepoužité, nastavte hodnotu 0.

Pozn: Štandardný port pre MQTT protokol je 1883 resp. 8883 pre SSL/TLS verziu. D2000 KOM neobsahuje implementáciu SSL/TLS varianty protokolu, ale je možné ju nakonfigurovať s použitím utility stunnel http://www.stunnel.org pracujúcej v klientskom móde (client = yes). Stunnel bežiaci na rovnakom počítači ako D2000 KOM by mal počúvať na lokálnom porte 1883 a po pripojení sa D2000 KOM procesu na tento port by mal komunikáciu zakryptovať pomocou SLL/TLS a poslať na cieľový MQTT server (typicky na port 8883).

Pozn: pri použití SSL/TLS spojenia je treba dať pozor na expiráciu použitých certifikátov. Dátum expirácie je možné na Linuxe zistiť príkazom

openssl x509 -text -in file.crt | grep "After"

Vynútené prerušenie spojenia: Keď sa všetky stanice na linke dostanú do simulácie alebo majú zastavenú komunikáciu, linka sa odpojí (dôjde ku zavretiu komunikačného socketu). Keď aspoň jedna stanica bude mať vypnutú simuláciu a nebude mať zastavenú komunikáciu (záložka Parametre objektu Stanica), linka sa znovu pripojí.

Kotva
linka_parametre
linka_parametre
Parametre protokolu linky

...

Dialóg konfigurácia linky - záložka Parametre protokolu.
Ovplyvňujú niektoré voliteľné parametre protokolu. Môžu byť zadané nasledovné parametre protokolu linky:

Tab. č. 1

Parameter

Popis

Jednotka / rozmer

Náhradná hodnota

Kotva

	fd
	fd

Full Debug

Zapnutie podrobných výpisov o posielaní a prijímaní hodnôt.

YES/NO

NO

Kotva

	un
	un

User Name

Užívateľské meno použité v správe CONNECT na pripojenie sa k MQTT serveru.

-

Kotva

	pw
	pw

Password

Heslo použité v správe CONNECT na pripojenie sa k MQTT serveru.

-

Kotva

	tc
	tc

Topic Filter

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
Pozn: zmena parametra Topic Filter sa prejaví po reštarte komunikácie - napr. v dôsledku rozpadnutia TCP spojenia, pokiaľ sú všetky stanice na linke vypnuté (StOff) a znovu zapnuté, prípadne po reštarte KOM procesu. V prvých dvoch prípadoch sa posiela správa UNSUBSCRIBE na pôvodný Topic Filter a následne SUBSCRIBE na nový Topic Filter (to môže byť dôležité pri tzv. perzistentných sessions, keď je zadaný parameter Client ID a MQTT server si pamätá stav klienta aj po rozpade TCP spojenia).
Pozn: pre Payload Type=Sparkplug postačuje filter spBv1.0/# na príjem všetkých Sparkplug správ.

-

#

Kotva

	sq
	sq

Subscribe QoS

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

Kotva

	ci
	ci

Client ID

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: niektoré MQTT brokery (PIXII.COM, Eclipse Mosquitto) identifikovali 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é, prípadne nedovolil vytvoriť nové spojenie a vrátil chybu Connection Refused, identifier rejected (2). Po nastavení Client ID na unikátnu hodnotu začali komunikácie fungovať bez rozpadov spojení.

-

D2000kom

Kotva

	cs
	cs

Clean Session Flag

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é.
Pozn: Ak Payload Type=Sparkplug a parameter Sparkplug Host ID nie je prázdny, tento parameter je ignorovaný a Clean Session Flag sa nastaví na YES (viď popis parametra Sparkplug Host ID).

YES/NO

NO

Kotva

	pq
	pq

Publish QoS

Ú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 Retain

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.

YES/NO

NO

Kotva

	ka
	ka

Keep Alive

Parameter Keep Alive posielaný v rámci CONNECT správy.
Ak je nenulový, udáva interval v sekundách, do ktorého musí klient poslať nejakú správu (ak ju nepošle, MQTT broker ho môže odpojiť). Ak nemá dáta, ktoré by mohol poslať, pošle aspoň výzvu PING request. Nulová hodnota znamená, žte MQTT broker nevyžaduje periodické posielanie správ.

Odporúčaná hodnota Keep Alive je niekoľko minút.

D2000 KOM proces posiela PING výzvy podľa nastavení parametrov Keep Alive a Ping Interval (podľa toho, ktorý interval uplynie skôr).

0-65535 sec

0

Kotva

	pi
	pi

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

0-3600 sec

60

Kotva

	pt
	pt

Payload Type

Nastavenie parsovania správy:

Text only - správa nie je parsovaná, priradí sa do meraného bodu s adresou IN_TOPIC
JSON - správa sa parsuje ako JSON dáta. Ak existuje meraný bod s adresou IN_TOPIC, celá správa bude priradená do neho.
Ak existujú body s adresami JA=json_address, budú naplnené príslušnými dátami z JSON správy. Ak v správe také adresy neexistujú, budú merané body zneplatnené.
Sparkplug - správa sa parsuje ako Sparkplug B payload (binárne kódovaný).

Text only
JSON
Sparkplug

Text only

Kotva

	tf
	tf

Time Field Name

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.
Viac informácii o formáte názvu poľa viď body s adresami JA=json_address.

-

Kotva

	tm
	tm

Time Mask

Maska pre parsovanie hodnoty v poli s časovou značkou. Špeciálne masky sú:

UNIX - číselná hodnota vyjadruje počet sekúnd od epochy 00:00:00 01.01.1970 UTC.
UNIXMS - číselná hodnota vyjadruje počet milisekúnd od epochy 00:00:00.000 01.01.1970 UTC.

Pozn: od nastavení časových parametrov stanice závisí, či je čas interpretovaný ako lokálny alebo UTC s nakonfigurovaným offsetom.

-

yyyy-mm-dd hh:mi:ss.mss

Kotva

	imt
	imt

Ignore Missing Time

Ignorovanie chýbajúcej časovej značky - pokiaľ sa v JSON payloade nevyskytuje, nevypíše sa varovanie.

YES/NO

NO

Kotva

	wf
	wf

Will Flag

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.
Pozn: Ak Payload Type=Sparkplug a parameter Sparkplug Host ID nie je prázdny, tento parameter je ignorovaný a Last Will sa posiela (viď popis parametra Sparkplug Host ID).

YES/NO

NO

Kotva

	wq
	wq

Will QoS

Úroveň potvrdzovania (QoS) použitá pri posielaní správy Last Will v prípade straty spojenia s D2000 KOM procesom.
Pozn: Ak Payload Type=Sparkplug a parameter Sparkplug Host ID nie je prázdny, tento parameter je ignorovaný a nastaví sa QoS_1 (viď popis parametra Sparkplug Host ID).

QoS_0
QoS_1
QoS_2

QoS_0

Kotva

	wr
	wr

Will Retain

Nastavenie príznaku Retain použité pri posielaní správy Last Will v prípade straty spojenia s D2000 KOM procesom.
Pozn: Ak Payload Type=Sparkplug a parameter Sparkplug Host ID nie je prázdny, tento parameter je ignorovaný a Retain sa nastaví na YES (viď popis parametra Sparkplug Host ID).

YES/NO

NO

Kotva

	wtp
	wtp

Will Topic

Topic použitý pri posielaní správy Last Will v prípade straty spojenia s D2000 KOM procesom.
Pozn: Ak Payload Type=Sparkplug a parameter Sparkplug Host ID nie je prázdny, tento parameter je ignorovaný (viď popis parametra Sparkplug Host ID).

-

Kotva

	wm
	wm

Will Message

Obsah správy Last Will v prípade straty spojenia s D2000 KOM procesom.
Pozn: Ak Payload Type=Sparkplug a parameter Sparkplug Host ID nie je prázdny, tento parameter je ignorovaný (viď popis parametra Sparkplug Host ID).

-

Kotva

	rt
	rt

Reply Timeout

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

Kotva

	wt
	wt

Wait Timeout

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á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

Kotva

	mwr
	mwr

Max. Wait Retry

Počet opakovaní čítania z TCP spojenia. Pozri popis parametra Wait Timeout.

-

3

Kotva

	pe
	pe

Payload Encoding

Kódovanie poľa Payload. MQTT protokol nešpecifikuje obsah poľa Payload, štandardné kódovanie ISO-8859-1 je vhodné na textový aj binárny obsah, UTF-8 je vhodné, ak sú prenášané UTF-8 kódované texty. Aktuálne podporované kódovania sú:

UTF-8
ISO-8859-1
Windows-1250

-

ISO-8859-1

Kotva

	bs
	bs

Buffer Size

Veľkosť prijímacieho buffra na TCP sockete. Veľkosť musí byť dostatočná, aby sa MQTT správa celá zmestila do prijímacieho buffra.

byte

65536

Sparkplug parametre

Kotva

	rum
	rum

Report Unknown Metrics

Parameter aktivuje výpisy neznámych metrík a tém (Topicov), ktoré nemajú vlastné stanice, ale skončia na stanici s adresou ".*" (ak taká existuje). Výpisy budú v logu linky ako chybové hlášky aj keď je debug na linke vypnutý (na uľahčenie pridávania meraných bodov).

YES/NO

NO

Kotva

	nt
	nt

Nonstandard Topic

Aktivácia parsovania neštandardných SparkPlug topicov.
Štandardný topic má tvar 'namespace/group_id/message_type/edge_node_id/[device_id]' napr. 'spBv1.0/Owner/DDATA/devicebase1/local_inputs'.
Neštandardný topic má namiesto group_id niekoľko úrovní, napr. 'spBv1.0/Basel/Packaging/DDATA/Falcon11/plannedProductionQuantity'.
Pozn: zápis do meraných bodov na staniciach s neštandardným SparkPlug topicom nie je podporený.

YES/NO

NO

Kotva

	hi
	hi

Sparkplug Host ID

Identifikátor Host aplikácie. Ak je zadaný, D2000 KOM proces pošle podľa MQTT Sparkplug štandardu správu STATE po pripojení sa k MQTT serveru. Touto správou oznamuje, že žije (ekvivalent NBIRTH a DBIRTH správ, ktoré posielajú zariadenia typu Edge Node a Device). Zároveň nastaví v CONNECT správe Will Topic/Will Message podľa Sparkplug štandardu, s Will QoS=QoS_1, Will Retain=YES, Clean Session Flag=YES.

Ak identifikátor zadaný nie je, D2000 KOM správu STATE neposiela (a nastavenie Will parametrov je konfigurovateľné).

-

Kotva
komunikacna_stanica
komunikacna_stanica
Konfigurácia komunikačnej stanice

...

Komunikačný protokol "MQTT Client Protocol".
Adresa stanice: adresa stanice zodpovedá poľu Topic v správe PUBLISH prijatej od MQTT servera. Adresou môže byť konkrétna téma (Topic), regulárny výraz, znak # reprezentujúci všetky témy, alebo topic .* reprezentujúci všetky témy, ktoré nie sú vhodné pre iné stanice. Priorita spracovania je takáto:
- Pokiaľ je na linke stanica s adresou #, všetky správy sú smerované na jej merané body a ďalej sa nehľadá.
- Ďalej sú prehľadávané všetky ostatné stanice na linke (s výnimkou adresy .*). Ak s Topic zhoduje s adresou stanice, správa je určená pre ňu a ďalej sa nehľadá.
- Ďalej sú prehľadávané všetky ostatné stanice na linke (s výnimkou adresy .*), pričom ich adresa je vyhodnocovaná ako regulárny výraz. Ak s Topic zhoduje s adresou stanice, správa je určená pre ňu a ďalej sa nehľadá. Stanice sú prehľadávané v zostupnom poradí (podľa adresy stanice), takže špecifickejšie výrazy idú ako prvé (napr. status/battery pred status/batt.*)
- Nakoniec ak existuje stanica s adresou .*, správa je určená pre ňu.
Parametre pollingu na záložke Časové parametre - odporúčaná je hodnota Delay=0.

Poznámka: v prípade SparkPlug MQTT servera má Topic tvar 'namespace/group_id/message_type/edge_node_id/[device_id]', kde message_type udáva typ správy (napr. DDATA, DBIRTH, DDEATH).
Je možné použiť namiesto message_type regulárny výraz (napr. spBv1.0/Sparkplug Devices/.*/MyDevice/Sensor2), aby boli pokryté všetky typy správ.
Ak Payload Type=Sparkplug, je možné vynechať časti namespace aj message_type a zapísať Topic v skrátenom tvare 'group_id/edge_node_id/[device_id]' (napr. Sparkplug Devices/MyDevice/Sensor2).

Kotva

	komunikacna_stanica_pozn
	komunikacna_stanica_pozn

Pozn: Ak je adresa stanice v skrátenom tvare, nespracúvajú sa pre ňu príkazy (DCMD, NCMD). Ak je v tvare regulárneho výrazu ('namespace/group_id/.*/edge_node_id/[device_id]'), stanica spracúva aj príkazy (včítane príkazu posielaného D2000 KOM procesom, ak Send Node Control/Rebirth=YES). Preto odporúčame adresu stanice v skrátenom tvare. Pokiaľ je potrebné spracovávať aj príkazy (od inýchHost Applications), tak vytvoriť inú stanicu s adresou v tvare regulárneho výrazu (napr. spBv1.0/Sparkplug Devices/DCMD/MyDevice).
Parametre protokolu stanice
Dialóg konfigurácia stanice - pole "Parameter protokolu".
Ovplyvňujú niektoré voliteľné parametre protokolu. Môžu byť zadané nasledovné parametre protokolu stanice:
Tab. č. 2
Kľúčové slovo Plný názov Popis Jednotka Náhradná hodnota
Kotva
swt
swt
SWT
Station Will Topic Will topic zariadenia. Ak je tento parameter nastavený a je prijatá správa so zhodným topicom, stanica prejde do komunikačnej chyby (StHardErr) a hodnoty meraných bodov sa zneplatnia. Takto je možné emulovať štandardné správanie, ktoré nastane pri chybe komunikácie so zariadením (aj keď komunikácia medzi procesom D2000 Kom a MQTT brokerom je funkčná).

Kotva
swp
swp
SWP
Station Will Payload Obsah Will správy. Ak je tento parameter nastavený a je prijatá správa so zhodným topicom ako definuje parameter Station Will Topic, musí byť navyše zhodný aj Payload. Ak tento parameter je prázdny reťazec, stačí zhoda topiccu s parametrom Station Will Topic.
Pozn: tento parameter bol implementovaný kvôli MQTT brokerom, ktorí posielajú správy s rovnakým Topic pri pripojení/odpojení zariadenia, pričom rozdiel je iba v Payloade.

Sparkplug parametre

Kotva
sr
sr
SR
Send Node Control/Rebirth Pri štarte D2000 KOM procesu sa pošle na SparkPlug stanicu príkaz (NCMD alebo DCMD) s metrikou 'Node Control/Rebirth'. Odpoveďou by mala byť správa (NBIRTH/DBIRTH) so všetkými aktuálnymi metrikami. YES/NO YES
Kotva
merany_bod
merany_bod
Konfigurácia meraných bodov
...
Možné typy hodnôt meraných bodov: Ci, Co, TxtI, TxtO, Qi, Ci, Co, Ai, Ao, Di, Do, TiR, ToR, TiA, ToA.
MQTT implementácia podporuje tri režimy práce:
Textový režim: Pôvodná implementácia MQTT protokolu obsahovala iba vstupné textové merané body s adresami IN_TOPIC, IN_DATA a voliteľne dvojicu bodov s adresami IN_ID a ACK_ID. Prvé dva body slúžili na zverejnenie prijatého Topicu a Payloadu (ktorý bolo následne potrebné parsovať v skripte), druhé dva body slúžili na zverejnenie identifikátora paketu a potvrdenie spracovania paketu. Tak bolo možné zabezpečiť, že pre dáta posielané s QoS > QoS_0 bolo poslané potvrdenie až po spracovaní dát v skripte.
Na zápis slúžia výstupné body s adresami OUT_TOPIC a OUT_VALUE.
JSON režim: Rozšírenie pre spracovanie Payloadu s JSON dátami (Payload Type=JSON) bolo implementované s pomocou vstupných meraných bodov s adresami JA=json_address. D2000 KOM proces priamo parsuje JSON payload a nastavuje hodnoty meraných bodov s JSON adresami. Merané body s adresamiIN_TOPIC, IN_DATA, IN_ID a ACK_ID vôbec nemusia existovať.
Na zápis slúžia výstupné body s adresami OUT_TOPIC a OUT_VALUE.
Sparkplug režim: Rozšírenie pre spracovanie Payloadu so Sparkplug dátami (Payload Type=Sparkplug) bolo implementované s pomocou vstupných meraných bodov s adresami SA=sparkplug_address. D2000 KOM proces priamo parsuje Sparkplug payload a nastavuje hodnoty meraných bodov so Sparkplug adresami. Merané body s adresami IN_TOPIC, IN_DATA, IN_ID a ACK_ID vôbec nemusia existovať.
Zápis jednoduchých hodnôt je možný pomocou výstupných bodov s adresami ST=type;SA=sparkplug_address, kde type je definícia Sparkplug dátového typu (napr. Int8, UInt16, DateTime, String atď). Výstupné body musia byť na stanici so Sparkplug adresou, keďže Topic pri zápise sa odvodzuje od nej.
Pozn: správy typu STATE, ktoré majú JSON payload, je možné parsovať s meranými bodmi s JSON adresou (typicky meraný bod typu Di s adresou JA=online)

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
Kotva
in_topic
in_topic
IN_TOPIC
Téma (Topic) prijatej správy PUBLISH.
TxtI
Kotva
in_data
in_data
IN_DATA
Dáta (Payload) prijatej správy PUBLISH.
Ci
Kotva
in_id
in_id
IN_ID
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 na 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.
Bod pre potvrdenie prijatia dát MQTT serveru.
Co
Kotva
ack_id
ack_id
ACK_ID
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
Kotva
out_topic
out_topic
OUT_TOPIC
Téma (Topic) v rámci posielanej správy PUBLISH.
TxtO
Kotva
out_value
out_value
OUT_VALUE
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)
...
Kategória komunikačnej linky: TCP/IP-TCP.
Host: IP adresa MQTT servera (prípadne redundantné adresy oddelené čiarkou alebo bodkočiarkou).
Port: číslo portu je štandardne 1883 alebo 8883 pre kryptovanú SSL/TLS variantu.
Číslo linky: nepoužité, nastavte hodnotu 0.
Pozn: Štandardný port pre MQTT protokol je 1883 resp. 8883 pre SSL/TLS verziu. D2000 KOM neobsahuje implementáciu SSL/TLS varianty protokolu, ale je možné ju nakonfigurovať s použitím utility stunnel http://www.stunnel.org pracujúcej v klientskom móde (client = yes). Stunnel bežiaci na rovnakom počítači ako D2000 KOM by mal počúvať na lokálnom porte 1883 a po pripojení sa D2000 KOM procesu na tento port by mal komunikáciu zakryptovať pomocou SLL/TLS a poslať na cieľový MQTT server (typicky na port 8883).
...
Dialóg konfigurácia linky - záložka Parametre protokolu.
Ovplyvňujú niektoré voliteľné parametre protokolu. Môžu byť zadané nasledovné parametre protokolu linky:
Tab. č. 1
...
Nastavenie parsovania správy:
Text only - správa nie je parsovaná, priradí sa do meraného bodu s adresou IN_TOPIC
JSON - správa sa parsuje ako JSON dáta. Ak existuje meraný bod s adresou IN_TOPIC, celá správa bude priradená do neho.
Ak existujú body s adresami JA=json_address, budú naplnené príslušnými dátami z JSON správy. Ak v správe také adresy neexistujú, budú zneplatnené
...
Komunikačný protokol "MQTT Client Protocol".
Adresa stanice: adresa stanice zodpovedá poľu Topic v správe PUBLISH prijatej od MQTT servera. Adresou môže byť konkrétna téma (Topic), regulárny výraz, znak # reprezentujúci všetky témy, alebo topic .* reprezentujúci všetky témy, ktoré nie sú vhodné pre iné stanice. Priorita spracovania je takáto:
Pokiaľ je na linke stanica s adresou #, všetky správy sú smerované na jej merané body a ďalej sa nehľadá.
Ďalej sú prehľadávané všetky ostatné stanice na linke (s výnimkou adresy .*). Ak s Topic zhoduje s adresou stanice, správa je určená pre ňu a ďalej sa nehľadá.
Ďalej sú prehľadávané všetky ostatné stanice na linke (s výnimkou adresy .*), pričom ich adresa je vyhodnocovaná ako regulárny výraz. Ak s Topic zhoduje s adresou stanice, správa je určená pre ňu a ďalej sa nehľadá. Stanice sú prehľadávané v zostupnom poradí (podľa adresy stanice), takže špecifickejšie výrazy idú ako prvé (napr. status/battery pred status/batt.*)
Nakoniec ak existuje stanica s adresou .*, správa je určená pre ňu.
Parametre pollingu na záložke Časové parametre - odporúčaná je hodnota Delay=0.
...
Možné typy hodnôt meraných bodov: Ci, Co, TxtI, TxtO.
IN_TOPICIN_DATAIN_IDIdentifiká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.ACK_IDOUT_TOPICOUT_VALUEDá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
).
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
Kotva
in_topic in_topic Téma (Topic) prijatej správy PUBLISH. TxtI
Kotva
in_data in_data Dáta (Payload) prijatej správy PUBLISH. Ci
Kotva
in_id in_id
Body pre parsovanie JSON správ
TxtI, TxtO, Qi,
Ci, Co,
Ai, Ao,
Di, Do,
TiR, ToR, TiA, ToA
Kotva
ja
ja
JA=json_address
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.
Pre JSON správy, ktoré môžu byť štruktúrované, je podporená syntax level1.level2.level3 ..., napr. rx.current a pokiaľ obsahujú polia (indexované od 1) tak aj level1[index1].level2[index2].level3 ..., napr. rx.gwrx[
1].time. Príklady viď popis meraných bodov typu Envelope protokolu LoRaWAN.
Bod pre potvrdenie prijatia dát MQTT serveru.
Co
Kotva
ack_id ack_id 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.
1].time.
Keďže samotná JSON správa môže byť pole, adresa môže začínať aj indexom, napr. JA=[1].batt_cell_v_avg
Príklady viď popis meraných bodov typu Envelope protokolu LoRaWAN.
Body pre parsovanie Sparkplug správ
TxtI, TxtO, Qi,
Ci, Co,
Ai, Ao,
Di, Do,
TiR, ToR, TiA, ToA
Kotva
sa
sa
Vstupné body:
SA=sparkplug_address
Výstupné body:
ST=type;SA=sparkplug_address
Pokiaľ Payload Type=Sparkplug, správa je parsovaná ako Sparkplug dáta (binárny formát postavený na Google Protocol Buffers). Sparkplug dáta obsahujú metriky, ktoré majú textové identifikátory (sparkplug_address).

Pri výstupných bodoch je nutné uviesť aj typ hodnoty. Podporované sú jednoduché typy:
Int8
Int16
Int32
Int64
UInt8
UInt16
UInt32
UInt64
Float
Double
Boolean
String
DateTime
Text
PUBLISH správa vytvorená pri zápise obsahuje Topic odvodený od adresy stanice. Typ správy závisí od adresy stanice - či sa jedná o Edge Node (NCMD) alebo Device/Sensor (DCMD). Payload obsahuje časovú značku, typ hodnoty (type) zapisovanú hodnotu (zakódovanú podľa špecifikovaného typu hodnoty) a názov metriky (sparkplug_address
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
Kotva
out_topic out_topic Téma (Topic) v rámci posielanej správy PUBLISH. TxtO
Kotva
out_value out_value
Kotva
literatura
literatura
Literatúra
...
Odkazy
Oficiálna stránka MQTT protokolu http://mqttmqtt.org
Stránka MQTT Sparkplug protokolu https://sparkplug.eclipse.org

Špecifikácie a štandardy
MQTT 3.1.1 špecifikácia http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
ISO/IEC 20922:2016 http://www.iso.org/standard/69499.html
Popisy dátových formátov a API
www.loriot.io - Application API Data Format https://www.loriot.io/home/documentation.html#docu/app-data-format
www.thethingsnetwork.org - API Reference https://www.thethingsnetwork.org/docs/applications/mqtt/api.html .org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
ISO/IEC 20922:2016 http://www.iso.org/standard/69499.html

Popisy dátových formátov a API
www.loriot.io - Application API Data Format https://www.loriot.io/home/documentation.html#docu/app-data-format
www.thethingsnetwork.org - API Reference https://www.thethingsnetwork.org/docs/applications/mqtt/api.html

Info
title Príklad komunikácie
Priložený ZIP obsahuje konfiguráciu dvoch liniek a dvoch staníc s MQTT protokolom a definíciu schémy S.MqttTest. Dáta zapísané cez jednu linku sú prijaté cez druhú linku. Funkčnosť bola overená voči brokeru Mosquitto inštalovanému lokálne na Windows, počúvajúcemu na TCP porte 1883.
View file
name Mosquito_test.zip
height 150
Image Added

Info
title Blog
O protokole MQTT si môžete prečítať blog
Komunikácia - MQTT v praxi

Kotva
revizie
revizie
Revízie dokumentu
...
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
title Súvisiace stránky:
Komunikačné protokoly
...

Strom stránky

Porovnávané verzie

Stará verzia 10

Nová verzia Aktuálny

Kľúč

Kotva
sparkplug
sparkplug
O protokole MQTT Sparkplug

Kotva
linka_parametre
linka_parametre
Parametre protokolu linky

Kotva
komunikacna_stanica
komunikacna_stanica
Konfigurácia komunikačnej stanice

Parametre protokolu stanice

Kotva
merany_bod
merany_bod
Konfigurácia meraných bodov

Kotva
literatura
literatura
Literatúra

Kotva
revizie
revizie
Revízie dokumentu

Strom stránky

História stránky

Porovnávané verzie

Stará verzia 10

Nová verzia Aktuálny

Kľúč

KotvasparkplugsparkplugO protokole MQTT Sparkplug

Kotvalinka_parametrelinka_parametreParametre protokolu linky

Kotvakomunikacna_stanicakomunikacna_stanicaKonfigurácia komunikačnej stanice

Parametre protokolu stanice

Kotvamerany_bodmerany_bodKonfigurácia meraných bodov

KotvaliteraturaliteraturaLiteratúra

KotvarevizierevizieRevízie dokumentu

Kotva
sparkplug
sparkplug
O protokole MQTT Sparkplug

Kotva
linka_parametre
linka_parametre
Parametre protokolu linky

Kotva
komunikacna_stanica
komunikacna_stanica
Konfigurácia komunikačnej stanice

Kotva
merany_bod
merany_bod
Konfigurácia meraných bodov

Kotva
literatura
literatura
Literatúra

Kotva
revizie
revizie
Revízie dokumentu