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

Podporované typy a verzie zariadení


Protokol umožňuje komunikáciu so zariadeniami komunikujúcimi pomocou LoRaWAN - protokolu. Protokol LoRaWAN je protokol určený na občasný, energeticky efektívny bezdrôtový prenos malého množstva dát nazývaných payload (typicky niekoľko bajtov) na dlhé vzdialenosti medzi prepojenými objektami - v terminológii LoRaWAN nazývanými mote (typicky senzory napájané batériou) a LoRaWAN gatewayom.
Gateway následne môže komunikovať priamo s D2000 KOM procesom alebo posielať payload na sieťové servery resp. do cloudu, kde sa vykoná spracovanie údajov (deduplikácia, filtrácia) a následne sú údaje poslané procesu D2000 KOM. V každom prípade je payload zabalený do obálky (napr. ako pole v JSON správe alebo v CSV súbore) a prenesený až do procesu D2000 KOM. Tam je payload dekódovaný (používa sa napr. Base64 kódovanie alebo Base64 + Base16 kódovanie) a spracovaný.
Spracovanie payloadu je závislé od typu zariadenia (definovaného v parametri protokolu Device Type).

Komunikácia bola testovaná medzi senzormi a LoRaWAN gatewayom Kerlink IoT Station 868. Ten v závislosti od inštalovaného firmware:


Konfigurácia komunikačnej linky




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

ParameterPopisJednotka / rozmerNáhradná hodnota
Connection TypeTyp spojenia medzi D2000 KOM procesom a druhou stranou (LoRaWAN gateway, sieťový server, cloud).
Aktuálne podporené sú:
  • Kerlink IoT Station SPN (JSON via UDP packets): komunikácia s Kerlink IoT Station s firmware SPN (Small Private Network). Linka musí byť typu SerialOverUDP Device Redundant.
  • MQTT Client (JSON via MQTT): komunikácia so sieťovým serverom alebo cloudom pomocou MQTT protokolu. Linka musí byť typu TCP/IP-TCP
-Kerlink IoT Station SPN
Mote Field NameNázov poľa s identifikátorom LoRaWAN zariadenia (mote).
Pozn: Pre JSON správy, ktoré môžu byť štruktúrované, je podporená syntax level1.level2.level3 ..., napr. rx.moteeui 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.
-rx.moteeui
Payload Field NameNázov poľa s payloadom. Viď poznámku pri parametri Mote Field Name.-rx.userdata.payload
Payload EncodingSpôsob kódovania payloadu v správe. Podporené kódovania:-Base16 + Base64 encoding
Time Field NameNázov poľa s časovou značkou. Ak pole nie je nájdené, hodnotám je priradený aktuálny čas. Viď poznámku pri parametri Mote Field Name.-rx.gwrx[1].time
Time MaskMaska 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ú:
  • 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.
-yyyy-mm-dd hh:mi:ss
Frame Type Field NameNázov poľa, ktoré označuje typ správy. Ak je hodnota prázdna, typ správy sa nerozlišuje. (Napr. cloud Loriot posiela správy rozličného typu.)- 
Frame Type Field Required ValueAk je rozlišovanie typu správy aktívne (vyplnený parameter Frame Type Field Name), typ správy musí byť zhodný s uvedenou hodnotou. Inak je správa ignorovaná.- 
Full DebugZapnutie podrobných výpisov o posielaní a prijímaní hodnôt.YES/NONO
Parametre špecifické pre Connection Type=MQTT Client.
MQTT User NameViď popis parametra User Name v dokumentácii MQTT protokolu.
MQTT PasswordViď popis parametra Password v dokumentácii MQTT protokolu.
MQTT Topic FilterViď popis parametra Topic Filter v dokumentácii MQTT protokolu.+/+/+/up
MQTT Subscribe QoSViď popis parametra Subscribe QoS v dokumentácii MQTT protokolu.
MQTT Client IDViď popis parametra Client ID v dokumentácii MQTT protokolu.
MQTT Clean Session FlagViď popis parametra Clean Session Flag v dokumentácii MQTT protokolu.
MQTT Publish FormatFormát JSON správy použitej pri zápise hodnoty. Obsah meraného bodu typu Write bude zakódovaný (v závislosti od parametra Payload Encoding) a vložený do tejto správy, kde nahradí reťazec #PAY#.
Náhradná hodnota "{"port":1, "confirmed":false, "payload_raw":#PAY#} bola vyskúšaná pri posielaní údajov do cloudu TheThings.Network.
-"{"port":1, "confirmed":false, "payload_raw":#PAY#}
MQTT Publish QoSViď popis parametra Publish QoS v dokumentácii MQTT protokolu.
MQTT Ping IntervalViď popis parametra Ping Interval v dokumentácii MQTT protokolu.
MQTT Reply TimeoutViď popis parametra Reply Timeout v dokumentácii MQTT protokolu.
MQTT Wait TimeoutViď popis parametra Wait Timeout v dokumentácii MQTT protokolu.
MQTT Max. Wait RetryViď popis parametra Max. Wait Retry v dokumentácii MQTT protokolu.

Parametre linky otestované pre Connection Type=Kerlink IoT Station SPN voči Kerlink IoT Station 868 s firmware SPN

ParameterHodnota
Connection TypeKerlink IoT Station SPN
Mote Field Namerx.moteeui
Payload Field Namerx.userdata.payload
Payload EncodingBase16 + Base64 encoding
Time Field Namerx.gwrx[1].time
Time Maskyyyy-mm-dd hh:mi:ss
Frame Type Field Name
Frame Type Field Required Value

Parametre linky otestované pre Connection Type=MQTT client voči TheThings.network

ParameterHodnota
Connection TypeMQTT client
Mote Field Namedev_id alebo hardware_serial
Payload Field Namepayload_raw
Payload EncodingBase64 encoding
Time Field Namemetadata.time
Time Maskyyyy-mm-dd hh:mi:ss.mss
Frame Type Field Name
Frame Type Field Required Value
MQTT User Nameipesoft-test
MQTT Password***
MQTT Topic Filter+/+/+/up
MQTT Client IDD2000kom
MQTT Clean Session FlagNO
MQTT Publish Format{"port":1, "confirmed":false, "payload_raw":#PAY#}
MQTT Publish QoSQoS_0, QoS_1, QoS_2
MQTT Ping Interval60
MQTT Reply Timeout20
MQTT Wait Timeout00.100
MQTT Max. Wait Retry3

Parametre linky otestované pre Connection Type=MQTT client voči Loriot.io s nastavením:

ParameterHodnota
Connection TypeMQTT client
Mote Field NameEUI
Payload Field Namedata
Payload EncodingBase16 encoding
Time Field Namets
Time MaskUNIXMS
Frame Type Field Namecmd
Frame Type Field Required Valuerx
MQTT User Name
MQTT Password
MQTT Topic Filtercom/ipesoft/iot
MQTT Client IDD2000kom
MQTT Clean Session FlagNO
MQTT Publish Format
MQTT Publish QoSQoS_1
MQTT Ping Interval60
MQTT Reply Timeout20
MQTT Wait Timeout00.100
MQTT Max. Wait Retry3

Parametre linky otestované pre Connection Type=MQTT client voči LoraLINK Slovanet:

ParameterHodnota
Connection TypeMQTT client
Mote Field NamedevEUI
Payload Field NamedataHex
Payload EncodingBase16 encoding
Time Field NametimeStamp
Time Mask *yyyy-mm-ddThh:mi:ss.mss
Frame Type Field Name
Frame Type Field Required Value
MQTT User Name(podľa AppEUI)
MQTT Password***
MQTT Topic Filterapp/(appEUI)/node/+/rxdata
MQTT Client IDD2000kom
MQTT Clean Session FlagYES
MQTT Publish Format{"reference":"","confirmed":true,"fPort":3,"dataHex":#PAY#}
MQTT Publish QoSQoS_0
MQTT Ping Interval60
MQTT Reply Timeout20
MQTT Wait Timeout00.100
MQTT Max. Wait Retry3

* Pozn.: Odoslaná hodnota je v lokálnom čase, je potrebné podľa toho nastaviť časové parametre príslušných staníc.

Konfigurácia komunikačnej stanice


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

ParameterPopisJednotkaNáhradná hodnota
Device TypeTyp LoRaWAN zariadenia. Každý typ zariadenia môže mať vlastnú štruktúru prenášaných dát (payload). Zoznam podporovaných zariadení bude postupne narastať.
Aktuálne podporené zariadenia sú:
  • None - žiadne zariadenie
  • OEM device - parsovanie payloadu je vykonávané externou dll knižnicou
  • Adeunis RF Field Test Device - testovacie zariadenie posielajúce GPS údaje o polohe a údaje o teplote
  • SolidusTech IndoorUNI Sensor - bytový merač teploty a vlhkosti
  • SolidusTech miniUNI DS18B20 Sensor - merač teploty pre vonkajšie prostredie
  • Adeunis RF LoRaWAN TEMP (ARF8180BA) - exteriérový merač teploty s dvomi nezávislými čidlami.
-None
External Dll NameNázov externej DLL knižnice s kódom pre parsovanie payloadu pre Device Type=OEM device.- 
No Data TimeoutTimeout, po ktorom stanica prejde do chybového stavu, ak neboli prijaté žiadne dáta.hh:mi:ss01:00:00
MQTT Topic (for writing)Topic použitý pri zápise hodnoty (pre Connection Type=MQTT client).
Pozn: pre užívateľa ipesoft-test a zariadenie fieldtestdevice bol otestovaný voči TheThings.network zápis s MQTT_TOPIC=ipesoft-test/devices/fieldtestdevice/down.
- 

Konfigurácia meraných bodov


Možné typy hodnôt meraných bodov: Ai, Di, Ci, TxtI, Qi, TxtO.

Typ hodnotyAddress
(typ adresy)
Popis
Ai, Di, Ci, Qi, TxtIPayload

Merané body parsované z payloadu. Adresa (Address) závisí od typu zariadenia (parameter Device Type). Adresa nie je citlivá na malé/veľké písmená.
Špeciálnym prípadom je nevyplnená adresa - takýto meraný bod bude obsahovať celý payload (po príslušnom dekódovaní v závislosti od parametra Payload Encoding).
Nasledujúce tabuľky udávajú adresy pre jednotlivé typy zariadení:

Adresy payloadu pre typ zariadenia OEM Device
adresa záleží od konkrétnej implementácie (dll knižnice).

Adresy payloadu pre typ zariadenia Adeunis RF Field Test Device

AddressPopis
StatusStavový bajt zariadenia.
TriggerAccelerometerHodnota True znamená, že poslanie správy bolo iniciované akcelerometrom.
TriggerButtonHodnota True znamená, že poslanie správy bolo iniciované tlačidlom.
TemperatureNameraná teplota (-128 °C .. 127°C).
GpsLatitudeZemepisná šírka (0-90 stupňov) z GPS snímača.
Pozn: GPS údaje môžu chýbať, ak zariadenie nemá žiaden GPS signál.
HemisphereSouthHodnota True znamená, že zemepisná šírka je južná (zariadenie je na južnej pologuli).
GpsLongitudeZemepisná dĺžka (0-180 stupňov) z GPS snímača.
HemisphereWestHodnota True znamená, že zemepisná dĺžka je západná (zariadenie je na západnej pologuli).
GpsQualityReceptionKvalita príjmu GPS signálu: 1 Good, 2 Average, 3 Poor
QpsQualitySatellitesPočet viditeľných GPS satelitov.
UplinkCounterPočítadlo uplink paketov (paketov poslaných zo zariadenia na LoRaWAN gateway).
DownlinkCounterPočítadlo downlink paketov (paketov poslaných zariadeniu z LoRaWAN gatewaya).
BatteryLevelNapätie batérie v mV.
RSSIIndikátor sily prijatého signálu (Received Signal Strength Indicator ) - hodnota 0-255. Payload obsahuje toto pole iba ak predtým došlo k zápisu do zariadenia (poslaniu dát z LoRaWAN gatewaya do zariadenia).
SNRSignal Noise Ratio v dB (-128 .. 127). Payload obsahuje toto pole iba ak predtým došlo k zápisu do zariadenia (poslaniu dát z LoRaWAN gatewaya do zariadenia).



Adresy payloadu pre typ zariadenia SolidusTech IndoorUNI Sensor

AddressPopis
ADRAdaptive Data Rate (optimalizácia rýchlosti prenosu dát a spotreby energie). Hodnota True znamená, že ADR je zapnutý.
DataRateData Rate (rýchlosť vysielania dát) 0-5.
SNRSignal Noise Ratio v dB (-128 .. 128).
BatteryLevelNapätie batérie v mV.
TemperatureTeplota (-125.99°C .. 125.99°C) s rozlíšením 0.1°C.
HumidityRelatívna vlhkost (0.0%-100%) s rozlíšením 0.1%.
PowerAdapterHodnota True znamená, že je zariadenie pripojené na napájací adaptér, hodnota False, že je napájané batériou (vždy False pre verziu firmware FW 0.2.2 a nižší).
ContactHodnota True znamená, že je zopnutý pomocný kontakt (vždy False pre verziu firmware FW 0.2.2 a nižší).



Adresy payloadu pre typ zariadenia SolidusTech miniUNI DS18B20 Sensor

AddressPopis
BatteryLevelNapätie batérie v mV.
SNRSignal Noise Ratio predchádzajúceho payloadu v dB. Platí po prijatí ACK. Hodnota 127 znamená nedefinovanú hodnotu (nebol prijatý ACK alebo downlink paket od LoRaWAN gatewaya).
TemperatureTeplota (-25°C .. 85°C) s rozlíšením 0.1°C.


Adresy payloadu pre typ zariadenia Adeunis RF LoRaWAN TEMP (ARF8180BA)

AddressPopis
FrameCounterInterné počítadlo správ nadobúdajúce hodnoty 0 .. 7.
BatteryLowIndikátor slabej batérie. Nadobúda hodnoty True alebo False.
HWErrorIndikátor hardvérovej chyby v zariadení (chyba teplotného čidla a pod.).
InternalTempHodnota teplotného čidla umiestneného v puzdre zariadenia s rozlíšením 0.1 °C.
ExternalTempHodnota teplotného čidla umiestneného na vyvedenom vodiči s rozlíšením 0.1 °C.


Ai, Di, Ci, Qi, TxtIEnvelopeMeraný bod parsovaný z obálky správy. Adresa je názov poľa v obálke správy.
Pozn: Pre JSON správy, ktoré môžu byť štruktúrované, je podporená syntax level1.level2.level3 ..., napr. rx.moteeui a pokiaľ obsahujú polia (indexované od 1) tak aj level1[index1].level2[index2].level3 ..., napr. rx.gwrx[1].time.

Príklad JSON správy pre Connection Type=Kerlink IoT Station SPN (doplnené medzery a zarovanie kvôli lepšej čitateľnosti):
{ 
  "rx": {
    "moteeui": "00-00-00-00-00-1e-fc-1d", 
    "userdata": {
        "seqno": 77, 
        "port": 1, 
        "payload": "NzM3RjAwZTgwMA==", 
        "motetx": {
            "freq": 868500000,
	    "modu": "LoRa",
	    "datr": "SF7BW125",
	    "codr": "4/5"
	}
     },
     "gwrx": [
        {
         "time": "2017-07-05 16:06:52",
	 "chan": 2,
	 "rfch": 0,
	 "rssi": -33,
	 "lsnr": 7.5
        }
     ]
  }
}
	
Merané body obálky môžu mať adresy napr. rx.moteeui, rx.userdata.seqno, rx.userdata.motetx.freq, rx.gwrx[1].time.

Príklad JSON správy pre Connection Type=MQTT Client (JSON via MQTT) (doplnené medzery a zarovanie kvôli lepšej čitateľnosti):
{
  "app_id":"ipesoft-test",
  "dev_id":"fieldtestdevice",
  "hardware_serial":"0018B2000000147D",
  "port":2,
  "counter":549,
  "payload_raw":"niNJElVwAYQ5UBYfBBBN",
  "metadata":{
    "time":"2017-08-10T08:12:26.06860368Z",
    "frequency":867.5,
    "modulation":"LORA",
    "data_rate":"SF7BW125",
    "coding_rate":"4/5",
    "gateways":[
      {
        "gtw_id":"eui-000000000003080b",
	"timestamp":705621508,
	"time":"2017-08-10T08:12:26.434682Z",
	"channel":5,
	"rssi":-34,
	"snr":7.8,
	"latitude":49.20927,
	"longitude":18.73184,
	"altitude":359
      }
    ]
  }
}
	
Merané body obálky môžu mať adresy napr. dev_id, metadata.time, metadata.gateways[1].latitude.
TxtIAll dataMeraný bod, ktorý bude obsahovať kompletnú prijatú správu - celú obálku (napr. JSON správu). Tento bod je určený na ladiace účely a pre prípadné spracovanie celej správy v skripte.
TxtOWrite (MQTT)Meraný bod na zápis. V súčasnosti implementované iba pre Connection Type=MQTT client a vyskúšané voči cloudu TheThings.Network.
Hodnota meraného bodu je považovaná za payload, ktorý bude zakódovaný (v závislosti od parametra Payload Encoding) a vložený do šablóny správy definovanej parametrom MQTT Publish Format, kde nahradí reťazec #PAY#. Výsledná správa bude poslaná MQTT serveru.

Literatúra


Odkazy
Oficiálna stránka LoRaWAN aliancie https://www.lora-alliance.org/technology
Oficiálna stránka MQTT protokolu http://mqtt.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

Revízie dokumentu


Komunikačné protokoly