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 KOM 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 KOM 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 KOM process. The payload is decoded there (using Base64 encoding or Base64 + Base16 encoding) and processed.
Payload processing is dependent on device type (defined in the Device Type protocol parameter).
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, however, 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 connection.
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 |
---|---|---|---|
Connection Type | Type of connection between the D2000 KOM process and the other party (LoRaWAN gateway, network server, cloud). Currently supported are:
| - | Kerlink IoT Station SPN |
Mote Field Name | Name of the field with an identifier of the LoRaWAN device (mote). | - | rx.moteeui |
Payload Field Name | Name of the field with the payload. See the notes next to the Mote Field Name parameter. | - | rx.userdata.payload |
Payload Encoding | A method of payload encoding in the message. Supported encoding:
| - | Base16 + Base64 encoding |
Time Field Name | Name of the field with a timestamp. 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 |
Time Mask | Mask for parsing a value in the field with a timestamp. 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 |
Frame Type Field Name | The name of the field indicating the message type. If the value is empty, the message type is not distinguished. (For example, cloud Loriot sends messages of various types.) | - | |
Frame Type Field Required Value | 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. | - | |
Full Debug | Writing detailed information about sending and receiving values in a log file. | YES/NO | NO |
Parameters specific for Connection Type=MQTT Client. | |||
MQTT User Name | See the description of the User Name parameter in the MQTT protocol documentation. | ||
MQTT Password | See the description of the Password parameter in the MQTT protocol documentation. | ||
MQTT Topic Filter | See the description of the Topic Filter parameter in the MQTT protocol documentation. | +/+/+/up | |
MQTT Subscribe QoS | See the description of the Subscribe QoS parameter in the MQTT protocol documentation. | ||
MQTT Client ID | See the description of the Client ID parameter in the MQTT protocol documentation. | ||
MQTT Clean Session Flag | See the description of the Clean Session Flag parameter in the MQTT protocol documentation. | ||
MQTT Publish Format | Format of JSON message used while writing a value. The content of the 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#} |
MQTT Publish QoS | See the description of the Publish QoS parameter in the MQTT protocol documentation. | ||
MQTT Ping Interval | See the description of the Ping Interval parameter in the MQTT protocol documentation. | ||
MQTT Reply Timeout | See the description of the Reply Timeout parameter in the MQTT protocol documentation. | ||
MQTT Wait Timeout | See the description of the Wait Timeout parameter in the MQTT protocol documentation. | ||
MQTT Max. Wait Retry | 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 the 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 |
Device Type | 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 |
External Dll Name | Name of external DLL library with code for payload parsing for Device Type=OEM device. | - | |
No Data Timeout | Timeout after which the station goes into a communication error state if no data has been received. | hh:mi:ss | 01:00:00 |
MQTT Topic (for writing) | The 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. | - | |
Sigfox Download Command File | For Sigfox: the 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 a proxy server, server identity verification is disabled, xxx:yyy is user name and password for Sigfox cloud): rem default count=1, possible to download up to 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 the D2000 KOM process, parameter count can be increased up to 100, resulting in downloading not only the latest value but also previous (up to 99) historical values. Then, after the first polling, the parameter count can be decreased to 1. | ||
Sigfox Download Timeout | For Sigfox: timeout for downloading data via Sigfox Download Command File. If downloading takes longer, the 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 | Payload | I/O tags parsed from the payload. Address (Address) depends on the device type (Device Type parameter). The address is not case sensitive.
Payload addresses for device type Codea WZU-SG (Landis+Gyr Ultraheat T550)
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Ai, Di, Ci, Qi, TxtI | Envelope | I/O tag parsed from the envelope of the message. The address is the name of the field in the envelope of the 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 | All data | 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 | Write (MQTT) | I/O tag for writing. Currently implemented just for Connection Type=MQTT client and tested towards cloud TheThings.Network. The value of the 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