Supported device types and versions
Communication line configuration
Communication line parameters
Communication station configuration
Station parameters
I/O tag configuration
Literature
Document revisions
The protocol allows communication with devices communicating using the LoRaWAN and Sigfox protocols.
The LoRaWAN protocol is a protocol designed for occasional, energy-efficient wireless transmission of a small amount of data called payload (typically several bytes) over long distances between linked objects - in LoRaWAN terminology called mote (typically battery-powered sensors) and LoRaWAN gateway.
The gateway can then communicate directly with the D2000 COM process or send the payload to the network servers or to the cloud, where data processing is performed (deduplication, filtration), followed by the data sent to the D2000 COM process. In any case, the payload is packed in an envelope (e. g. such as a field in a JSON message or in a CSV file) and transferred up to the D2000 COM process. The payload is decoded there (using Base64 encoding or Base64 + Base16 encoding) and processed.
Payload processing is dependent on device type (defined in parameter of Device Type protocol).
The communication was tested between sensors and LoRaWAN gateway Kerlink IoT Station 868. It was, depending on the installed firmware:
The Sigfox protocol is similar to LoRaWAN, and it uses different frequency bands. It uses the infrastructure built by Sigfox and its partners and messages (with a maximum payload size of 12 bytes, and a maximum frequency of 140 messages per day) are transmitted to the cloud (backend.sigfox.com) from which they can be obtained through the REST API.
The communication was tested between sensors and the Sigfox cloud using curl utility to retrieve data via https.
Configuration for LoRaWAN protocol:
Configuration for Sigfox protocol:
Communication line - configuration dialog - Protocol parameters tab.
The parameters influence some optional protocol parameters. The following protocol line parameters can be used:
Table 1
Parameter | Description | Unit / size | Default Value |
---|---|---|---|
Type of connection between D2000 KOM process and other party (LoRaWAN gateway, network server, cloud). Currently supported are:
| - | Kerlink IoT Station SPN | |
Name of field with identifier of LoRaWAN device (mote). | - | rx.moteeui | |
Name of field with payload. See the notes next to the Mote Field Name parameter. | - | rx.userdata.payload | |
A method of payload encoding in the message. Supported encoding:
| - | Base16 + Base64 encoding | |
Name of field with time stamp. If the field is not found, the current time is assigned to the values. See the notes next to the Mote Field Name parameter. | - | rx.gwrx[1].time | |
Mask for parsing a value in field with time stamp. Note: from settings of time station parameters depends whether the time is interpreted as local or UTC with configured offset. Special masks are:
| - | yyyy-mm-dd hh:mi:ss | |
The name of field that indicates the message type. If the value is empty, the message type is not distinguished. (For example, cloud Loriot sends messages of a various types.) | - | ||
If the message type differentiation is active (non-empty value of Frame Type Field Name parameter), the message type must match the specified value, otherwise, the message is ignored. | - | ||
Enabling the detailed statements about sending and receiving values. | YES/NO | NO | |
Parameters specific for Connection Type=MQTT Client. | |||
See the description of the User Name parameter in the MQTT protocol documentation. | |||
See the description of the Password parameter in the MQTT protocol documentation. | |||
See the description of the Topic Filter parameter in the MQTT protocol documentation. | +/+/+/up | ||
See the description of the Subscribe QoS parameter in the MQTT protocol documentation. | |||
See the description of the Client ID parameter in the MQTT protocol documentation. | |||
See the description of the Clean Session Flag parameter in the MQTT protocol documentation. | |||
Format of JSON message used while writing a value. The content of I/O tag of Write type will be encoded (depending on the Payload Encoding parameter) and inserted into the message, where it will replace the #PAY# string. The default value "{"port":1, "confirmed":false, "payload_raw":#PAY#} was tested when sending data to cloud TheThings.Network. | - | "{"port":1, "confirmed":false, "payload_raw":#PAY#} | |
See the description of the Publish QoS parameter in the MQTT protocol documentation. | |||
See the description of the Ping Interval parameter in the MQTT protocol documentation. | |||
See the description of the Reply Timeout parameter in the MQTT protocol documentation. | |||
See the description of the Wait Timeout parameter in the MQTT protocol documentation. | |||
See the description of the Max. Wait Retry parameter in the MQTT protocol documentation. |
Line parameters tested for Connection Type=Kerlink IoT Station SPN for Kerlink IoT Station 868 with firmware SPN
Parameter | Value |
---|---|
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 |
Line parameters tested for Connection Type=MQTT client for TheThings.network
Parameter | Value |
---|---|
Connection Type | MQTT client |
Mote Field Name | dev_id or 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 |
Line parameters tested for Connection Type=MQTT client for Loriot.io with following setup:
Parameter | Value |
---|---|
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 |
Line parameters tested for Connection Type=MQTT client towards 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 |
* Note.: Timestamp is sent in local time. Station time settings are to be configured accordingly.
Line parameters tested for Connection Type=Sigfox Client (JSON via HTTPS) towards Sigfox cloud
Parameter | Hodnota |
---|---|
Connection Type | Sigfox Client (JSON via HTTPS) |
Mote Field Name | data[].device |
Payload Field Name | data[].data |
Payload Encoding | Base16 encoding (Slovanet, Loriot, Sigfox) |
Time Field Name | data[].time |
Time Mask | UNIX |
Frame Type Field Name | |
Frame Type Field Required Value |
Dialog station configuration - Protocol Parameter field.
They affect some optional protocol parameters. The following station parameter parameters can be entered:
Table 2
Parameter | Description | Unit | Default Value |
Type of device. Each device type may have its own structure of transmitted data (payload). The list of supported devices will gradually increase. Currently supported devices are:
| - | None | |
Name of external DLL library with code for payload parsing for Device Type=OEM device. | - | ||
Timeout after which the station goes into communication error state if no data has been received. | hh:mi:ss | 01:00:00 | |
| Topic used when writing the value (for Connection Type=MQTT client). Note: for ipesoft-test user and fieldtestdevice device writing was tested towards TheThings.network with MQTT_TOPIC=ipesoft-test/devices/fieldtestdevice/down. | - | |
| For Sigfox: path to the file for downloading data from the Sigfox cloud to the input directory (specified by parameter Input file of the File I/O line) together with possible parameters. The path may contain (like the Input File parameter) the symbolic constant #APPDIR# (application directory) as well as #ADDR# (station address) so that a single file can be used to handle multiple stations. Example for Windows platform - file get.bat (download is via proxy server, server identity verification is disabled, xxx:yyy is user name and password for Sigfox cloud): rem default count=1, possible to download upto 100 values Example for Linux platform - file get.sh (it is necessary to explicitly specify that files are downloaded e.g. to Sigfox_input directory): #/bin/sh# default count=1, possible to download upto 100 values Note: if command files are edited prior to running KOM process, parameter count can be increased upto 100, resulting in downloading not only the latest value, but also previous (upto 99) historical values. Then, after the first polling, parameter count can be decreased to 1. | ||
| For Sigfox: timeout for downloading data via Sigfox Download Command File. If downloading takes longer, station will go to error. | sec | 30 |
Possible value types of I/O tags: Ai, Di, Ci, TxtI, Qi, TxtO.
Value type | Address (address type) | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ai, Di, Ci, Qi, TxtI | I/O tags parsed from payload. Address (Address) depends on device type (Device Type parameter). Address is not case sensitive.
Payload addresses for device type Codea WZU-SG (Landis+Gyr Ultraheat T550)
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Ai, Di, Ci, Qi, TxtI | I/O tag parsed from envelope of message. The address is the name of the field in the envelope of message. Note: For JSON messages that can be structured, the syntax level1.level2.level3 ... is supported, e.g. rx.moteeui and if they contain fields (indexed from 1) then also level1[index1].level2[index2].level3 ... syntax, e.g. rx.gwrx[1].time. Example of JSON message for Connection Type=Kerlink IoT Station SPN (added spacing and alignment for better legibility): { "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 } ] } }I/O tags of envelope may have addresses e.g. rx.moteeui, rx.userdata.seqno, rx.userdata.motetx.freq, rx.gwrx[1].time. Example of JSON message for Connection Type=MQTT Client (JSON via MQTT) (added spacing and alignment for better legibility): { "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 } ] } }I/O tags of envelope may have addresses e.g. dev_id, metadata.time, metadata.gateways[1].latitude. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TxtI | I/O tag, that will contain the complete received message - the whole envelope (e.g. JSON message). The I/O tag is intended for debugging purposes and for eventual processing of the entire message in the script. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TxtO | I/O tag for writing. Currently implemented just for Connection Type=MQTT client and tested towards cloud TheThings.Network. The value of I/O tag is considered to be a payload that will be encoded (depending on the Payload Encoding parameter) and inserted into the message template defined by the MQTT Publish Format parameter, where it will replace the #PAY# string. The resulting message will be sent to the MQTT server. |
Links
Official website of LoRaWAN alliance https://www.lora-alliance.org/technology
Official website of MQTT protocol http://mqtt.org
Specifications and Standards
MQTT 3.1.1 specification 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
Descriptions of Data Formats and 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