Gateway

Reference Manual

Gateway

Reference Manual


Contents

​1.​ Overview  3

​1.1.​ Supported models  3

​2.​ Configuration files  4

​2.1.​ Service configuration  4

​2.2.​ Subscribe configuration  10

​2.3.​ Scheduler configuration  13

​2.4.​ LTE configuration  15

​3.​ IQRF network topic message payloads  17

​4.​ MQTT control topic message payloads  20

​4.1.​ Gateway info  20

​4.2.​ Ping  23

​4.3.​ Reset RF module  23

​4.4.​ Restart unid service  25

​4.5.​ Reboot gateway  26

​4.6.​ File manager  27

​4.7.​ Run scripts  31

​4.8.​ Scheduler pause  32

​4.9.​ Scheduler force resume  33

​4.10.​ Scheduler info  34

​5.​ Application message payloads  35

​6.​ Appendix  36

​6.1.​ Status messages  36

​6.2.​ QoS - Quality of Service  37

​6.3.​ Cron expression  37

​6.4.​ Topics  38

​6.5.​ Location information  39

​6.8.​ MQTT payload string content  40

​6.9.​ Login  40

​6.10.​ LTE RSSI value  41

​6.11.​ Ports  42

​6.12.​ USB drive automount  42


​1.​ Overview

This reference manual targets application developers. It provides complete information on how to configure and use the GW-UNI-01 and GW-IND-01 gateway families communication protocol and communication interfaces.

The communication protocol is based on the gateway main service (unid) form version 2.0.0.

​1.1.​ Supported models

The table below shows the list of supported devices described in this document. The table contains the Model ID, the product name and the main features.

Model ID

Product name

ETH

4G/LTE

GPS

GW-UNI-01

Universal Gateway

GW-IND-01

Industrial Gateway with Ethernet connection

GW-IND-01-4GO

Industrial with 4G support only

GW-IND-01-4G

Industrial with Ethernet + 4G/LTE connection

GW-IND-01-4GL

Industrial with Ethernet + 4G & GPS support

GW-IND-01-4GLO

Industrial with 4G & GPS support only

​1.2.​ Supported firmwares

This document cover devices with the following firmware versions:

unid: 2.6.0


​2.​ Configuration files

The configuration files determines the operation of the gateway.

CAUTION!

The device can become inoperable cause the improper configuration!

​2.1.​ Service configuration

Configuration file path: /etc/unid/conf.s0/unid.conf

Name

Type

Default value

Options

Description

mqtt

enable

Boolean

false

Enable/Disable MQTT service.

host

String

mqtt.iqhome.org

Hostname or IP address of the MQTT broker.

port

Integer

8883

MQTT Broker service port

username

Null,String

Username

password

Null,String

Password

clientid_source

String

auto

auto

Auto

Set client ID automatically from selected source or set manually.

manual

Manual

clientid

String

serial

Client ID used by the MQTT service and further can be used to insert this id into topic names.

keepalive_interval_sec

Integer

60

The number of seconds after which the broker should send a PING message to the client if no other messages have been exchanged in that time.

cleansession

Boolean

true

Set to true to instruct the broker to clean all messages and subscriptions on disconnect, false to instruct it to keep them.

version

String

mqtt311

mqtt31

MQTT v3.1

MQTT protocol version.

mqtt311

MQTT v3.1.1

will_topic

Null,String

The topic on which to publish the will.

will_payload

Null,String

The will message.

will_qos

Integer

0

0

0 - at most once

The quality of service for will messages.

1

1 - at least once

2

2 - exactly once

will_retain

Boolean

false

Set to true to make the will a retained message.

queue_size

Integer

1000

MQTT publish queue size for network messages.

queue_overwrite

Boolean

true

Enable/Disable queue to overwrite the oldest item when the queue is full.

mqtt > tls

enable

Boolean

true

Enable MQTT TLS

type

String

ca_signed

ca_signed

CA signed server certificates

TLS type

ca_file

CA certificate file

self_signed

Self-signed certificates

capath

Null,String

/etc/ssl/certs

Certificate folder path for CA signed server certificates.

cafile

Null,String

/etc/unid/conf.k0/rootCA.pem

CA certificate file path

certfile

Null,String

/etc/unid/conf.k0/certificate.pem.crt

Self-signed certificate private key file path

keyfile

Null,String

/etc/unid/conf.k0/private.pem.key

Self-signed certificate file path

version

String

tlsv1.2

tlsv1

TLS v1.0

TLS Version.

tlsv1.1

TLS v1.1

tlsv1.2

TLS v1.2

verify_hostname

Boolean

true

Configure verification of the server hostname in the server certificate. This can be useful to disable in initial server testing but must be enabled in a real system!.

scheduler

enable

Boolean

false

Enable/Disable scheduler.

iqrfide_interface

enable

Boolean

true

Enable IQRF IDE interface

port

Integer

55300

IQRF IDE UDP port

enable_reset_module

Boolean

true

Enable/Disable TR module reset from IDE.

enable_reset_gateway

Boolean

true

Enable/Disable gateway reboot from IDE.

enable_remote_access

Boolean

false

Enable direct access from IQRF IDE.

application_interface

enable

Boolean

false

Enable/Disable UDP user application interface.

port_listen

Integer

55001

User Network Interface service port.

port_send

Integer

55000

User Network Interface service port.

enable_remote_access

Boolean

false

Enable direct access by other devices on the network.

filemanager

enable_download

Boolean

true

Enable/Disable remote access for download (read) files in the service folders.

enable_upload

Boolean

true

Enable/Disable remote access for upload (write) files in the service folders.

enable_create

Boolean

true

Enable/Disable remote access for create files in the service folders.

enable_remove

Boolean

true

Enable/Disable remote access for remove files in the service folders.

script

enable_exec

Boolean

true

Enable/Disable remote execute scripts in the service folder.

max_exectime_sec

Integer

900

Max execute time for each script in seconds.

iqrf

queue_size

Integer

100

RF network request queue size.

queue_overwrite

Boolean

false

Enable/Disable queue to overwrite the oldest item when the queue is full.

queue_maxpriority

Integer

2

Number of max priority level. e.g.: 2 → priority levels: 0,1,2.

async_response_topic

Null,String

Response topic for asynchronous IQRF messages.

timeout_coordinator_discovery_sec

Integer

5400

Timeout in seconds for discovery requests

timeout_coordinator_sec

Integer

90

Timeout in seconds for coordinator requests: Bonding, FRC.

timeout_node_sec

Integer

3

Timeout in seconds for every nodes.

frc_extraresult_autorequest

Boolean

true

Enable/Disable auto request for extra result. If enabled the response forwarded as one concatenated packet.

packet_sniffing

Boolean

true

Enable/disable packet sniffing. If enabled the RF network packets forwarded to the IQRF IDE for debug purposes if the IQRF is IDE connected to the GW.

message

show_type

Boolean

false

Add message type to MQTT payloads response: Response messages error: Error messages.

message > response

dpa_request

Boolean

true

Add dpa_request to response message.

dpa_confirm

Boolean

true

An explanation about purpose of this instance.

timestamp_mqtt_receive

Boolean

true

Add timestamp_mqtt_receive to response message. Timestamp when MQTT request message received.

timestamp_rfnet_send

Boolean

true

Add timestamp_rfnet_send to response message. Timestamp when request sent to RF network.

timestamp_rfnet_receive

Boolean

true

Add timestamp_rfnet_receive to response message. Timestamp when MQTT message received from broker.

timestamp_mqtt_send

Boolean

true

Add timestamp_mqtt_send to response message. Timestamp when MQTT message published.

localization

enable

Boolean

true

Enable/Disable localization.

tcp_proxy

enable

Boolean

true

Enable/Disable TCP forwarding over MQTT.

max_socket_num

Integer

50

Number of maximum opened sockets.

max_payload_size_kib

Integer

120

Maximum payload size in KiB. Larger messages will splitted into multiple messages with the size of the set value.

enabled_ports

Array

22

Comma separated list of enabled ports.

modbus_tcp

enable

Boolean

false

Enable/Disable Modbus TCP interface.

port

Integer

502

Modbus TCP server port

max_client

Integer

64

Maximum number of connected clients.

acknowledge_response

Boolean

false

Enable acknowledge response

(0x05 Modbus TCP exception code).

WARNING: Not supported by all Modbus devices!

enable_remote_access

Boolean

false

Enable remote access for Modbus TCP server.

service

enable_restart

Boolean

true

Enable/Disable service restart.

enable_reboot

Boolean

true

Enable/Disable gateway reboot.

loglevel

Integer

0

0

Warning & Error

Service log level.

1

Info

2

Debug

3

Trace

ping_host

String

8.8.8.8

Ping host to check active internet connection.

ping_interval_min

Integer

1

Ping interval in minutes.

ping_timeout_sec

Integer

5

Ping timeout in seconds.

service > logsource

iqrf

Boolean

false

Enable/Disable log messages.

mqtt

Boolean

false

Enable/Disable log messages.

control

Boolean

false

Enable/Disable log messages.

scheduler

Boolean

false

Enable/Disable log messages.

iqrfide_interface

Boolean

false

Enable/Disable log messages.

application_interface

Boolean

false

Enable/Disable log messages.

modbus_tcp

Boolean

false

Enable/Disable log messages.

​2.2.​ 2.2.Subscribe configuration

Configuration file for automatically subscribe MQTT topics and determine the target of the received request messages and setup default response behaviour for each topic.

Configuration file path: /etc/unid/conf.s0/subscribe.conf

Name

Type

Default value

Options

Description

topics

subscribe_topic

String

iqhome/gateway/%c/network/request

Subscribe topic name.

subscribe_qos

Integer

0

0

0 - at most once

Subscribe QoS.

1

1 - at least once

2

2 - exactly once

message_topic

String

$GW/sensnet

The target topic of request messages.

topics > publish

publish_topic

String

Use $GW/application or any MQTT topic name

publish_qos

Integer

1

0

0 - at most once

Publish QoS.

1

1 - at least once

2

2 - exactly once

retain

Boolean

false

Retain.

broadcast_request_topic

String

Broadcast request topic.

broadcast_response_topic

String

Broadcast response topic.

Example

{

  "topics": [

    {

      "subscribe_topic": "iqhome/gateway/%c/network/request",

      "subscribe_qos": 1,

      "message_topic": "$GW/iqrf",

      "publish": [

        {

          "publish_topic": "iqhome/gateway/%c/network/response",

          "publish_qos": 1,

          "retain": false

        }

      ]

    },

    {

      "subscribe_topic": "iqhome/gateway/%c/linkit/request",

      "subscribe_qos": 1,

      "message_topic": "$GW/control",

      "publish": [

        {

          "publish_topic": "iqhome/gateway/%c/linkit/response",

          "publish_qos": 1,

          "retain": false

        }

      ],

      "broadcast_request_topic": “iqhome/gateway/broadcast/linkit/request",

      "broadcast_response_topic": "iqhome/gateway/broadcast/linkit/response"

    }

  ]

}


​2.3.​ Scheduler configuration

Scheduler configuration file determine the automatically scheduled request messages as scheduled jobs. The defined scheduled jobs in the same matching cron expression will be sent in the same order as defined in the configuration file.

Configuration file path: /etc/unid/conf.s0/scheduler.conf

Name

Type

Default value

Options

Description

scheduler

cron_expression

String,Array

0 */15 * * * *

Cron expression when the request should be sent.

cron_expression_except

Null,String,Array

Cron expression when the request should be skipped.

scheduler > request

message_topic

String

$GW/sensnet

Target message topic.

scheduler > request > message

id

String,Number

Message ID

dpa_request

String

DPA request

timeout

Integer

2

Node timeout in seconds

priority

Integer

2

Message priority

type

String

sensor

sensor

Sensor

Request type

modbus

Modbus

command

String

read

read

Read

Request type

send

Send

calibration

Calibration

option

String

sensor

all

All values

Request type

temperature

Temperature [°C]

relative_humidity

Relative Humidity [%rH]

co2

CO2 [ppm]

mbslave

Integer

1

Modbus slave address

mbpdu

String

Modbus PDU Hex String. Example read 2 holding registers from address 0x6000: '03.60.00.00.02'

device_address

Null,String,Integer

all

All

Device Address

1-63

1-63

sleep

Integer

true

Enable node deep sleep with automatic sleep time calculation

scheduler > request > message > publish

publish_topic

String

Publish topic

publish_qos

Integer

1

0

0 - at most once

Publish QoS

1

1 - at least once

2

2 - exactly once

retain

Boolean

false

Publish retain

Example

{

  "scheduler": [

    {

      "cron_expression": "*/15 * * * * *",

      "request": {

        "message_topic": "$GW/iqrf",

        "message": {

          "id": 1,

          "dpa_request": "0000.0D.00.FFFF.F0.00.00",

          "timeout": 0,

          "priority": 0,

          "publish": [

            {

              "publish_topic": "iqhome/sensor/%c/response",

              "publish_qos": 1,

              "retain": false

            }

          ]

        }

      }

    },

    {

      "cron_expression": "*/15 * * * * *",

      "cron_expression_except": ["0 0 0 * * *", "0 0 4 * * *"],

      "request": {

        "message_topic": "$GW/iqrf",

        "message": {

          "id": "string-id",

          "dpa_request": "0000.0D.00.FFFF.F0.00.00",

          "timeout": 0,

          "priority": 0,

          "publish": [

            {

              "publish_topic": "$GW/application"

            },

            {

              "publish_topic": "iqhome/sensor/%c/response",

              "publish_qos": 1,

              "retain": false

            }

          ]

        }

      }

    }

  ]

}


​2.4.​ LTE configuration

Only for GW-IND-01-4G* models.

/etc/unid/conf.s0/lte.conf

Name

Type

Default value

Options

Description

apn

String

internet

APN

username

String

Username

password

String

Password

pin

String

PIN code. Leave blank if it is disabled.

roaming

String

auto

auto

Auto

Enable/Disable roaming.

enable

Enable

disable

Disable

scanmode

String

auto

auto

Auto

Scanmode

2g

2G only

3g

3G only

4g

4G only

ping_host

String

8.8.8.8

Hostname that use to check network connection.

ping_timeout_sec

Integer

5

Check network connection ping timeout.

ping_count

Integer

3

Check network connection ping count.

ping_interval_min

Integer

5

Check network connection interval.

use_gps

Boolean

false

Enable GPS on GPS capable devices.

loglevel

Integer

0

0

Warning & Error

Loglevel

1

Debug

Example

{

    "version": "1.0",

    "apn": "internet",

    "username": "",

    "password": "",

    "pin": "",

    "roaming": "auto",

    "scanmode": "auto",

    "ping_host": "8.8.8.8",

    "ping_timeout_sec": 5,

    "ping_count": 3,

    "ping_interval_min": 5,

    "use_gps": false,

    "loglevel": 0

}


​3.​ IQRF network topic message payloads

Target gateway topic: $GW/iqrf

Request

Name

Type

Default

Options

Description

id

Number,String

Message ID
The same ID will be sent in the response messages

dpa_request

String

timeout

Number

0

Set the default timeout values from unid.conf

Timeout value means the maximum processing time for each node. The full timeout calculated from network parameters (hops and time slot values) and added to the timeout value.

Default values:

  • coordinator (addr: 00000): 90sec
  • node(each) (addr: 0100-F900): 5sec

1-65535

priority

Number

0

0-255

Priority of message queue

publish (Array)

publish_topic

String

topic

Override of the default response topic name.

publish_qos

Number

0,1,2

Override default response publish_qos parameter.

retain

Boolean

false

Override default response retain parameter.

Example

Basic

{

  "dpa_request": "0000.0D.00.FFFF.F0.00.00",

}

Extended

{

  "id": "messageid",

  "dpa_request": "0000.0D.00.FFFF.F0.00.00",

  "timeout": 0,

  "priority": 0,

  "publish":[

    {

      "publish_topic":"$GW/application"

    },

    {

      "publish_topic": "iqhome/sensor/%s/%n/response" ,

      "publish_qos":1,

      "retain":false

    }

  ]

}

Response

Name

Type

Default value

Options

Description

id

Number,
String

Message ID

message_type

String

response

Available only if showType enabled in unid.conf

IQRF DPA request HEX string

status

String

Can be disabled in unid.conf

Status message

dpa_request

Can be disabled in unid.conf

IQRF DPA request

dpa_confirm

String

Can be disabled in unid.conf

IQRF coordinator DPA confirm HEX string

dpa_response

String

IQRF node DPA response HEX string

timestamp_mqtt_receive

Number

Can be disabled in unid.conf

Timestamp at enqueue message into RF network queue, when put into IQRF message queue.

timestamp_rfnet_send

Number

Can be disabled in unid.conf

Timestamp at dequeue message from RF network queue, when send to IQRF network.

timestamp_rfnet_receive

Number

Can be disabled in unid.conf

Timestamp at enqueue message into cloud queue, when received from IQRF network.

timestamp_mqtt_send

Number

Can be disabled in unid.conf

Timestamp at dequeue message from MQTT queue, when publish the message.

Example

{

  "id": 123456,

  "message_type": "response",

  "status": "ok",

  "dpa_response": "010020A11202002903",

  "dpa_request": "01002021FFFF0202",

  "dpa_confirm": "01002021FFFFFF38010801",

  "timestamp_mqtt_receive": 1451642400,

  "timestamp_rfnet_send": 1451649604,

  "timestamp_rfnet_receive": 1451649608,

  "timestamp_mqtt_send": 1451649610

}


​4.​ MQTT control topic message payloads

Target gateway topic: $GW/control

​4.1.​ Gateway info

Request

Name

Type

Value

Description

id

String

Message ID

command

String

system

option

String

info

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

system

option

String

info

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

info

serial

String

Message ID

mid

String

MID (Module ID) of RF module

hostname

String

Gateway hostname

model

String

Model name

interface

String

Active network interface connected to internet

mac

String

MAC address of active network interface connected to internet

ipv4

String

IPv4 address of active network interface

ipv6

String

IPv6 address of active network interface

firmware

Object

Installed gateway packages version

control_request_topic

String

Name of the gateway’s unique request MQTT topic

control_response_topic

String

Name of the gateway’s unique response MQTT topic

tcp_proxy_ports

Array

Enabled TCP Proxy ports

tcp_proxy_max_size_kib

Integer

Maximum size of TCP proxy payloads in KiB

uptime_seconds

Gateway uptime in seconds

current_timestamp

Gateway UNIX Epoch timestamp

timezone_numeric

UTC offset numeric e.g.: "+0100"

timezone_alphabetic

Time zone abbreviations e.g.: "CET"

info > monitoring*

voltage_1v8

Float

Voltage of the gateway 1.8V

voltage_3v3

Float

Voltage of the gateway 3.3V

voltage_5v0

Float

Voltage of the gateway 5.0V

voltage_powerin

Float

Voltage of the gateway power

powerin_online

Boolean

Power source of the gateway. If false the gateway powered from battery, otherwise from power line.

temperature_board

Float

Temperature of the gateway main board

temperature_core

Float

Temperature of the gateway CPU

info > wwan**

model

String

Model of WWAN interface device

version

String

Version of WWAN interface device

rssi

Integer

LTE RSSI value 

operator

String

Operator name

access_mode

Integer

Access mode value

0,3

2G

2,4,5,6

3G

7

4G

info > location*

Object

Location inforamtion

*   Only at industrial models

**  Only at 4G/LTE models

Example

Request

Response

{

  "id": "jctKZwRx1ZpiJh",

  "command": "system",

  "option": "info"

}

{

  "id": "jctKZwRx1ZpiJh",

  "command": "system",

  "option": "info",

  "info": {

    "serial": "GW-3E70000",

    "model": "GW-IND-01-4G",

    "mid": "811018AF",

    "hostname": "raspberrypi",

    "interface": "eth0",

    "mac": "B8:27:EB:C6:78:30",

    "ipv4": "192.168.6.164",

    "ipv6": "fe80::81b0:b2b4:c4fd:c2ba",

    "firmware": "2.3.4-0",

    "control_request_topic": "iqhome/gateway/GW-3E70000/linkit/request",

    "control_response_topic": "iqhome/gateway/GW-3E70000/linkit/response",

    "uptime_seconds": 6555,

    "current_timestamp": 1520421349,

    "timezone_numeric": "+0000",

    "timezone_alphabetic": "UTC",

    "monitoring": {

      "voltage_3v3": 3.28,

      "voltage_1v8": 1.83,

      "voltage_5v0": 5.05,

      "voltage_powerin": 13.67,

      "powerin_online": true,

      "temperature_board": 33.06,

      "temperature_core": 41.16

    },

    "wwan": {

      "model": "EC20",

      "version": "EC20EQAR02A11E2G",

      "rssi": 19,

      "operator": "T-Mobile H Telekom HU",

      "access_mode": 7

    },

    "location": {

      "timestamp": 0,

      "latitude": 0,

      "longitude": 0,

      "type": "cbsp",

      "valid": true

    }

  },

  "status": "ok",

  "timestamp_mqtt_send": 1520421350

}

​4.2.​ Ping

Request

Name

Type

Value

Description

id

String

Message ID

command

String

system

option

String

ping

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

system

option

String

ping

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

Example

Request

Response

{

  "id": 1,

  "command": "system",

  "option": "ping"

}

{

  "id": 1,

  "command": "system",

  "option": "ping",

  "status": "ok"

}

​4.3.​ Reset RF module

Request

Name

Type

Value

Description

id

String

Message ID

command

String

system

option

String

reset_rf_module

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

system

option

String

reset_rf_module

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

Example

Request

Response

{

  "id": 1,

  "command": "system",

  "option": "reset_rf_module"

}

{

  "id": 1,

  "command": "system",

  "option": "reset_rf_module",

  "status": "ok"

}


​4.4.​ Restart unid service

Request

Name

Type

Value

Description

id

String

Message ID

command

String

system

option

String

restart

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

system

option

String

restart

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

Example

Request

Response

{

  "id": 9,

  "command": "system",

  "option": "restart"

}

{

  "id": 9,

  "command": "system",

  "option": "restart",

  "status": "ok"

}


​4.5.​ Reboot gateway

Request

Name

Type

Value

Description

id

String

Message ID

command

String

system

option

String

reboot

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

system

option

String

reboot

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

Example

Request

Response

{

  "id": 9,

  "command": "system",

  "option": "reboot"

}

{

  "id": 9,

  "command": "system",

  "option": "reboot",

  "status": "ok"

}


​4.6.​ File manager

Request

Name

Type

Options

Description

info <Object>

id

String

Message ID

command

String

filemanager

option

String

upload

Create/Modify/Remove files

download

Read file contents

list

List files

folders <Array>

name

String

dynamic

/etc/unid/conf.d0

Dynamically modified config files e.g. scheduler.conf

static

/etc/unid/conf.s0

Static config files e.g. unid.conf

log

/var/log/unid

Log files

files <Object Array, String [ * - all files]>

name

String

log

/var/log/unid

Log files

content

String

log

/var/log/unid

Log files

action

String

modify

Modify file contents

create

Create file with content (only script)

remove

Remove file (only script or log)

Response

Name

Type

Options

Description

info <Object>

id

String

Message ID

command

String

filemanager

option

String

upload

download

list

status

String

Request status

Status message

folders <Array>

name

String

dynamic

/etc/unid/conf.d0

Dynamically modified config files e.g. scheduler.conf

static

/etc/unid/conf.s0

Static config files e.g. unid.conf

log

/var/log/unid

Log files

script

/etc/unid/script

Script files

status

String

Folder status action
Status message

files <Array, String [ * - all files]>

name

String

log

/var/log/unid

Log files

content

String

log

/var/log/unid

Log files

action

String

modify

Modify file contents

create

Create file with content (only script)

remove

Remove file (only script or log)

status

String

File action status

Status message

encode

String

none

Optional encode field. Default is not encode as equal with no encode field defined.  

base64

Base64 encode for example for gz log files.

Example

Download all available files

Request

Response

{

  "id": 100,

  "command": "filemanager",

  "option": "download",

  "folders": [

    {

      "name": "static",

      "files": "*"

    },

    {

      "name": "dynamic",

      "files": "*"

    },

    {

      "name": "log",

      "files": "*"

    },

    {

      "name": "script",

      "files": "*"

    }

  ]

}

{

  "id": 100,

  "command": "filemanager",

  "option": "download",

  "status": "ok",

  "folders": [

    {

      "name": "static",

      "status": "ok",

      "files": [

        {

          "name": "unid.conf",

          "content": "<content>",

          "status": "ok"

        }

      ]

    },

    {

      "name": "dynamic",

      "status": "ok",

      "files": [

        {

          "name": "scheduler.conf",

          "content": "<content>",

          "status": "ok"

        }

      ]

    },

    {

      "name": "log",

      "status": "ok",

      "files": [

        {

          "name": "unid.log",

          "content": "<content>",

          "status": "ok"

        }

      ]

    },

    {

      "name": "script",

      "status": "ok",

      "files": [

        {

          "name": "sysinfo.sh",

          "content": "<content>",

          "status": "ok"

        }

      ]

    }

  ]

}


Example

Upload/modify files

Request

Response

{

  "id": 7,

  "command": "filemanager",

  "option": "upload",

  "folders": [

    {

      "name": "script",

      "files": [

        {

          "name": "test.sh",

          "action": "create",

          "content": "<content>"

        }

      ]

    }

  ]

}

{

  "id": 7,

  "command": "filemanager",

  "option": "upload",

  "status": "ok",

  "folders": [

    {

      "name": "script",

      "status": "ok",

      "files": [

        {

          "name": "test.sh",

          "action": "create",

          "status": "ok"

        }

      ]

    }

  ]

}


​4.7.​ Run scripts

Request

Name

Type

Value

Description

id

String

Message ID

command

String

script

option

String

run

script

String

Script name in the gateway script folder

arg

String

Script argument list

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

script

option

String

run

echo

String

ping

Output of script

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

Example

Request

Response

{

  "id": 14123,

  "command": "script",

  "option": "run",

  "command": "script",

  "script": "test.sh"

  "arg": "-t now"

}

{

  "id": 14123,

  "command": "script",

  "option": "run",

  "status": "ok",

  "echo": "<stdout>"

}


​4.8.​ Scheduler pause

Request

Name

Type

Value

Description

id

String

Message ID

command

String

scheduler

option

String

pause

Pause scheduler

timeout

Integer

Timeout value in seconds.

The maximum timeout should be 90 minutes. If the timeout is greater than 5400 (90 min) the scheduler automatically set the timeout to 90 minute.

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

scheduler

option

String

pause

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

Example

Request

Response

{

  "id": 8,

  "command": "scheduler",

  "option": "pause",

  "timeout": 300

}

{

  "id": 8,

  "command": "scheduler",

  "option": "pause",

  "status": "ok"

}


​4.9.​ Scheduler force resume

Request

Name

Type

Value

Description

id

String

Message ID

command

String

scheduler

option

String

resume

Pause scheduler

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

scheduler

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

Example

Request

Response

{

  "id": 9,

  "command": "scheduler",

  "option": "resume"

}

{

  "id": 9,

  "command": "scheduler",

  "option": "resume",

  "status": "ok"

}


​4.10.​ Scheduler info

Request

Name

Type

Value

Description

id

String

Message ID

command

String

scheduler

option

String

info

Pause scheduler

Response

Name

Type

Value

Description

id

String

Message ID

message_type

String

Available only if showType enabled in unid.conf

command

String

info

timestamp

UNIX Epoch timestamp when info requested

timeout

Remaining timeout seconds until scheduler will be resumed

status

String

Status message

timestamp_mqtt_send

Integer

Available only if timestamp_mqtt_send enabled in unid.conf

Example

Request

Response

{

  "id": 9,

  "command": "scheduler",

  "option": "info"

}

{
   "id": 9,
   "command": "scheduler",
   "option": "info",
   "paused": true,
   "timestamp": 1506414303,
   "timeout": 292,
   "status": "ok"
}


​5.​ UDP Application interface message payloads

Target gateway topic: $GW/application 

Request

Name

Type

Description

message_topic

String

Source topic of the message

message

Object

Response message from GW or custom object via MQTT

Response

Name

Type

Description

message_topic

String

Target topic of the message

message

Object

Valid  Request message object or custom message for only MQTT

publish_qos

Only for MQTT target topic. Quality of Service for publish QoS

retain

Only for MQTT target topic

Example

Request

Response

{

  "message_topic": "topic_received",

  "message": "msg"

}

{

  "message_topic": "topic_publish",

  "message": "msg",  

  "publish_qos":1,

  "retain":false

}


​6.​ Appendix

​6.1.​ Status messages

Request

Response

ok

Status ok

error

General error

empty_payload

empty message payload

invalid_target

Request interface target is missing or invalid

invalid_command

control command is missing or invalid

invalid_option

control option is missing or invalid

invalid_action

control action is missing or invalid

request_format_error

Request message payload invalid format

content_format_error

Request content error

folder_access_error

File download/upload no access to folder

file_access_error

File download/upload no access to file

file_read_error

File read error

file_write_error

File write error

store_nofreespace

No free space left on storage (only with eeRAID)

store_hwerror

Storage hardware error (only with eeRAID)

interface_busy

Interface busy

interface_blocked

Interface blocked ( IQRF IDE Network management mode active)

script_exceeds_limit

Number of running scripts is exceeds limit

network_queue_full

RF network queue is full

feature_disabled

Requested feature is disabled in configuration file

timeout

$GW/iqrf request timeout

communication_error

$GW/iqrf communication error

framework_error

$GW/iqrf DPA framework error

modbus_timeout_error

$GW/iqrf Modbus device timeout error

modbus_response_too_long_error

$GW/iqrf Modbus device response too long

modbus_frame_error

$GW/iqrf Modbus device frame error


​6.2.​ QoS - Quality of Service

​6.3.​ Cron expression

┌─────────────  sec (0-59)

│ ┌────────────── min (0 - 59)

│ │ ┌─────────────── hour (0 - 23)

│ │ │ ┌──────────────── day of month (1 - 31)

│ │ │ │ ┌───────────────── month (1 - 12)

│ │ │ │ │ ┌──────────────── day of week (0 - 6)(0to 6 are Sunday to
│ │ │ │ │ │        Saturday 7 is Sunday, the same as 0)
│ │ │ │ │ │        

│ │ │ │ │ │

* * * * * *

Valid cron expression examples:

Expression

Meaning

Example

Run job at

Number

In every Xth unit

0 5 * * * *

Every hour 5 minute

*

In every unit

0 * * * * *

Every minute

*/5

In every 5th unit

*/10 * * * * *

Every 10th second

1,2,3

In every 1,2,3 unit

0 0 0,12 * * *

Twice per day
(midnight and
noon)

1-10

In every unit in the 1-10 interval

0 0-5 * * * *

Every hour 0,1,2,3,4,5th minute


​6.4.​ Topics

Topics start with $GW/ reserved for gateway specific topics.

Name

Description

Request Topic

Response Topic

$GW/iqrf

IQRF network

𝗑

$GW/sensnet

SensNet, IQ Home devices

𝗑

Any topic that does not start with $GW

MQTT

$GW/control

Gateway control

𝗑

$GW/application

UDP Application

Automatic replacements in topics

Name

Description

%h

Hostname (GW Hostname)

%s

Serial ID of the gateway

%m

Module ID of the RF module

%c

Client ID from MQTT config

%u

Username from MQTT config

Example:

iqhome/gateway/%s/response used as iqhome/gateway/GW-3E70000/response


​6.5.​ Location information

Location information available only for 4G/LTE models.

Name

Type

Description

timestamp

Integer

Timestamp of the location information

latitude

Float

Latitude coordinate

longitude

Float

Longitude coordinate

type

String

Invalid - Invalid position information

cbsp - Location information by Cell Base Station Positioning

gnss - Location information by GPS+GLONASS

valid

Boolean

If true the last request for location information was valid


​6.8.​ MQTT payload string content

<content> - ASCII strings with escape characters

E.g.:

1. JSON content

Original:

{

"key":"value"

}

Encoded:

"{\n\"key\": \"value\"}\n"

2. Plain text

  Orinigal:

Test text.

Another line.

Encoded:

"Test text.\nAnother line."

​6.9.​ Login

The default credentials can be found on the sticker on the side of the gateways.


​6.10.​ LTE RSSI value

Value

dBm

Description

0

-113

Bad

1

-111

Bad

2

-109

Marginal

3

-107

Marginal

4

-105

Marginal

5

-103

Marginal

6

-101

Marginal

7

-99

Marginal

8

-97

Marginal

9

-95

Marginal

10

-93

OK

11

-91

OK

12

-89

OK

13

-87

OK

14

-85

OK

15

-83

Good

16

-81

Good

17

-79

Good

18

-77

Good

19

-75

Good

20

-73

Excellent

21

-71

Excellent

22

-69

Excellent

23

-67

Excellent

24

-65

Excellent

25

-63

Excellent

26

-61

Excellent

27

-59

Excellent

28

-57

Excellent

29

-55

Excellent

30

-53

Excellent

31

-51

Excellent

99

Not known or not detectable

255

Can’t read from LTE module

​6.11.​ Ports

Following table shows the listening ports used by gateway services.

Listening ports

Service

Port

Protocol

SSH service

22

TCP

Modbus TCP

502

TCP

Gateway zconf service

1313

UDP

Gateway local connection

13013

TCP

The following table shows the ports used by services in the gateway. These outgoing  ports should be enabled to device in the network firewall.

Outgoing ports

Service

Port

Protocol

NTP client

123

UDP

MQTT client

1883/8883

TCP

​6.12.​ USB drive automount

The gateway can automount USB drives. The hotplug USB drive mounted to /run/media/[LABEL|UUID] folder. The folder created by the LABEL of USB drive if it is set and use the drive UUID otherwise.

For example in the case of USB flash drive labeled with MyDrive the mount point will be /run/media/MyDrive 

Supported automount filesystems:

FAT16

FAT32

©2020 IQHome Kft

www.iqhome.org

 /