IoT over LoRaWAN

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:

posielal údaje priamo D2000 KOM procesu (JSON správy v UDP packetoch)
posielal údaje do cloudu TheThings.Network, odkiaľ ich D2000 KOM proces čítal (JSON správy v MQTT protokole cez TCP spojenie)
posielal údaje do cloudu Loriot.io, ktorý ich preposielal protokolom MQTT do iot.eclipse.org, odkiaľ ich D2000 KOM proces čítal (JSON správy v MQTT protokole cez TCP spojenie)

Konfigurácia komunikačnej linky

Kategória komunikačnej linky: SerialOverUDP Device Redundant, TCP/IP-TCP.
Konfigurácia linky SerialOverUDP Device Redundant:

Lokálny port: port na ktorom D2000 KOM proces prijíma UDP pakety
Primárne/záložné zariadenia: IP adresa LoRaWAN gatewaya
(pre Connection Type=Kerlink IoT Station SPN)
Port: port na ktorom LoRaWAN gateway prijíma pakety (v súčasnosti nevyužité, keďže nie je implementovaný zápis)

Konfigurácia linky TCP/IP-TCP:

Host: IP adresa servera, ku ktorému sa D2000 KOM proces pripája, prípadne redundantné adresy oddelené čiarkou alebo bodkočiarkou
(pre Connection Type=MQTT client)
Port: port servera, ku ktorému sa D2000 KOM proces pripája

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
Connection Type	Typ 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 Name	Ná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 Name	Názov poľa s payloadom. Viď poznámku pri parametri Mote Field Name.	-	rx.userdata.payload
Payload Encoding	Spôsob kódovania payloadu v správe. Podporené kódovania: Base16 + Base64 encoding (Kerlink SPN) - pre Connection Type=Kerlink IoT Station SPN Base64 encoding (TheThings.network) - pre Connection Type=MQTT Client pri komunikácii s cloudom TheThings.network Base16 encoding (Loriot, Slovanet) - pre Connection Type=MQTT Client pri komunikácii s cloudami Loriot a Slovanet None - správa obsahuje priamo payload - zatiaľ nevyužité	-	Base16 + Base64 encoding
Time Field Name	Ná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 Mask	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ú: 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 Name	Ná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 Value	Ak 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 Debug	Zapnutie podrobných výpisov o posielaní a prijímaní hodnôt.	YES/NO	NO
Parametre špecifické pre Connection Type=MQTT Client.
MQTT User Name	Viď popis parametra User Name v dokumentácii MQTT protokolu.
MQTT Password	Viď popis parametra Password v dokumentácii MQTT protokolu.
MQTT Topic Filter	Viď popis parametra Topic Filter v dokumentácii MQTT protokolu.		+/+/+/up
MQTT Subscribe QoS	Viď popis parametra Subscribe QoS v dokumentácii MQTT protokolu.
MQTT Client ID	Viď popis parametra Client ID v dokumentácii MQTT protokolu.
MQTT Clean Session Flag	Viď popis parametra Clean Session Flag v dokumentácii MQTT protokolu.
MQTT Publish Format	Formá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 QoS	Viď popis parametra Publish QoS v dokumentácii MQTT protokolu.
MQTT Ping Interval	Viď popis parametra Ping Interval v dokumentácii MQTT protokolu.
MQTT Reply Timeout	Viď popis parametra Reply Timeout v dokumentácii MQTT protokolu.
MQTT Wait Timeout	Viď popis parametra Wait Timeout v dokumentácii MQTT protokolu.
MQTT Max. Wait Retry	Viď 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

Parameter	Hodnota
Connection Type	Kerlink IoT Station SPN
Mote Field Name	rx.moteeui
Payload Field Name	rx.userdata.payload
Payload Encoding	Base16 + Base64 encoding
Time Field Name	rx.gwrx[1].time
Time Mask	yyyy-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

Parameter	Hodnota
Connection Type	MQTT client
Mote Field Name	dev_id alebo hardware_serial
Payload Field Name	payload_raw
Payload Encoding	Base64 encoding
Time Field Name	metadata.time
Time Mask	yyyy-mm-dd hh:mi:ss.mss
Frame Type Field Name
Frame Type Field Required Value
MQTT User Name	ipesoft-test
MQTT Password	***
MQTT Topic Filter	+/+/+/up
MQTT Client ID	D2000kom
MQTT Clean Session Flag	NO
MQTT Publish Format	{"port":1, "confirmed":false, "payload_raw":#PAY#}
MQTT Publish QoS	QoS_0, QoS_1, QoS_2
MQTT Ping Interval	60
MQTT Reply Timeout	20
MQTT Wait Timeout	00.100
MQTT Max. Wait Retry	3

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

Výstup protokolom MQTT
MQTT broker: iot.eclipse.org
MQTT topic: com/ipesoft/iot

Parameter	Hodnota
Connection Type	MQTT client
Mote Field Name	EUI
Payload Field Name	data
Payload Encoding	Base16 encoding
Time Field Name	ts
Time Mask	UNIXMS
Frame Type Field Name	cmd
Frame Type Field Required Value	rx
MQTT User Name
MQTT Password
MQTT Topic Filter	com/ipesoft/iot
MQTT Client ID	D2000kom
MQTT Clean Session Flag	NO
MQTT Publish Format
MQTT Publish QoS	QoS_1
MQTT Ping Interval	60
MQTT Reply Timeout	20
MQTT Wait Timeout	00.100
MQTT Max. Wait Retry	3

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

Parameter	Hodnota
Connection Type	MQTT client
Mote Field Name	devEUI
Payload Field Name	dataHex
Payload Encoding	Base16 encoding
Time Field Name	timeStamp
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 Filter	app/(appEUI)/node/+/rxdata
MQTT Client ID	D2000kom
MQTT Clean Session Flag	YES
MQTT Publish Format	{"reference":"","confirmed":true,"fPort":3,"dataHex":#PAY#}
MQTT Publish QoS	QoS_0
MQTT Ping Interval	60
MQTT Reply Timeout	20
MQTT Wait Timeout	00.100
MQTT Max. Wait Retry	3

* 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

Komunikačný protokol "IoT over LoRaWAN".
Adresa stanice: adresa stanice je identifikátor konkrétneho zariadenia (mote), ktorý sa nachádza v poli Mote Field Name.
- pre Connection Type=Kerlink IoT Station SPN je adresa textová reprezentácia 8-bajtovej LoRaWAN adresy (napr. 00-00-00-00-21-1a-e3-c8)
- Pre Connection Type=MQTT Client môže byť adresa textová reprezentácia 8-bajtovej LoRaWAN adresy (napr. 0018B2000000147D) alebo symbolická adresa definovaná v rámci MQTT servera (napr. fieldtestdevice)

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

Parameter	Popis	Jednotka	Náhradná hodnota
Device Type	Typ 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 Name	Názov externej DLL knižnice s kódom pre parsovanie payloadu pre Device Type=OEM device.	-
No Data Timeout	Timeout, po ktorom stanica prejde do chybového stavu, ak neboli prijaté žiadne dáta.	hh:mi:ss	01: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 hodnoty

Address
(typ adresy)

Popis

Ai, Di, Ci, Qi, TxtI

Payload

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

Address	Popis
Status	Stavový bajt zariadenia.
TriggerAccelerometer	Hodnota True znamená, že poslanie správy bolo iniciované akcelerometrom.
TriggerButton	Hodnota True znamená, že poslanie správy bolo iniciované tlačidlom.
Temperature	Nameraná teplota (-128 °C .. 127°C).
GpsLatitude	Zemepisná šírka (0-90 stupňov) z GPS snímača. Pozn: GPS údaje môžu chýbať, ak zariadenie nemá žiaden GPS signál.
HemisphereSouth	Hodnota True znamená, že zemepisná šírka je južná (zariadenie je na južnej pologuli).
GpsLongitude	Zemepisná dĺžka (0-180 stupňov) z GPS snímača.
HemisphereWest	Hodnota True znamená, že zemepisná dĺžka je západná (zariadenie je na západnej pologuli).
GpsQualityReception	Kvalita príjmu GPS signálu: 1 Good, 2 Average, 3 Poor
QpsQualitySatellites	Počet viditeľných GPS satelitov.
UplinkCounter	Počítadlo uplink paketov (paketov poslaných zo zariadenia na LoRaWAN gateway).
DownlinkCounter	Počítadlo downlink paketov (paketov poslaných zariadeniu z LoRaWAN gatewaya).
BatteryLevel	Napätie batérie v mV.
RSSI	Indiká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).
SNR	Signal 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

Address	Popis
ADR	Adaptive Data Rate (optimalizácia rýchlosti prenosu dát a spotreby energie). Hodnota True znamená, že ADR je zapnutý.
DataRate	Data Rate (rýchlosť vysielania dát) 0-5.
SNR	Signal Noise Ratio v dB (-128 .. 128).
BatteryLevel	Napätie batérie v mV.
Temperature	Teplota (-125.99°C .. 125.99°C) s rozlíšením 0.1°C.
Humidity	Relatívna vlhkost (0.0%-100%) s rozlíšením 0.1%.
PowerAdapter	Hodnota 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žší).
Contact	Hodnota 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

Address	Popis
BatteryLevel	Napätie batérie v mV.
SNR	Signal 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).
Temperature	Teplota (-25°C .. 85°C) s rozlíšením 0.1°C.

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

Address	Popis
FrameCounter	Interné počítadlo správ nadobúdajúce hodnoty 0 .. 7.
BatteryLow	Indikátor slabej batérie. Nadobúda hodnoty True alebo False.
HWError	Indikátor hardvérovej chyby v zariadení (chyba teplotného čidla a pod.).
InternalTemp	Hodnota teplotného čidla umiestneného v puzdre zariadenia s rozlíšením 0.1 °C.
ExternalTemp	Hodnota teplotného čidla umiestneného na vyvedenom vodiči s rozlíšením 0.1 °C.

Ai, Di, Ci, Qi, TxtI

Envelope

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

TxtI

All data

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

TxtO

Write (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

Ver. 1.0 - 10. august 2017 - vytvorenie dokumentu.
Ver. 1.1 - 25. august 2017 - doplnená konfigurácia linky (Frame Type, Time Mask - UNIX, UNIXMS, PayloadEncoding - Base16), podpora zariadenia AdeunisRF LoRaWAN TEMP a komunikácie s Loriot.io.

Súvisiace stránky:

Komunikačné protokoly

Strom stránky