IQ Home GW-UNI-01 User manual

© 2016 IQ HOME Kft. www.iqhome.org
User Manual
Universal Gateway
Model
GW-UNI-01
Software package version
1.02
DPA version
2.23
HWPID
0x0213
DPA Custom Handler version
1.00 (HWPIDver: 0x0100)
Date
2016-02-25
Document revision
1.0

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 2 / 21
Contents
1Overview ........................................................................................................................................3
1.1 Software architecture ............................................................................................................3
1.2 Use cases................................................................................................................................5
1.2.1 Onboard custom applications............................................................................................5
1.2.2 MQTT applications .............................................................................................................6
2Interfaces .......................................................................................................................................7
2.1 UNetIf –UDP User Network Interface...................................................................................8
2.2 MQTT Interface......................................................................................................................9
2.2.1 MQTT Client Interface configuration ...............................................................................10
2.3 IQRF IDE Interface................................................................................................................11
2.3.1 IQRF IDE Interface packet sniffer service.........................................................................11
2.4 DPA compatibility mode ......................................................................................................12
2.4.1 FRC commands.................................................................................................................12
3Daemon configuration .................................................................................................................13
3.1 System configuration [system] ............................................................................................13
3.2 MQTT Client Interface configuration [mqtt]........................................................................14
3.3 IQRF IDE Interface configuration [ide].................................................................................16
3.4 User Network Interface configuration [unetif]....................................................................16
3.5 IQRF communication configuration [network]....................................................................17
4Demo examples ...........................................................................................................................18
5Release Notes ..............................................................................................................................19
5.1 v1.01.....................................................................................................................................19
5.2 v1.02.....................................................................................................................................19
6Troubleshooting...........................................................................................................................20
Document revisions .............................................................................................................................21

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 3 / 21
1Overview
Universal Gateway enables for developers to connect and manage IQRF IQMESH network with their
custom application in simply way. The Universal Gateway based on a Single Board Computer. The
gateway comes with Linux operating system. The preinstalled software contains custom-developed
daemon which manages the onboard IQRF module and provides some easy to use communication
interfaces. The gateway can be used like transparent network bridge between IQRF mesh network
and TCP/IP network or like a custom programmable device.
1.1 Software architecture
The Universal Gateway is shipped with a preinstalled SD card image. This image contains the
preinstalled unid daemon. The unid daemon manages the communication between the IQRF
module and user interfaces. The daemon provides easy access to the IQRF network. The
communication interfaces can be enabled or disabled in configuration file detailed in chapter.
Figure 1 shows the default communication architecture of Universal Gateway.
Interfaces establish connection between IQRF module and user applications. The unid daemon has
multiple interfaces:
1. IQRF IDE UDP Interface: Enables connection between onboard IQRF module and IQRF IDE on
TCP/IP network.
2. User Network Interface (UNetIf): Enables connection between onboard IQRF module and custom
local host application by simplified UDP protocol.
3. MQTT Client Interface: Simple MQTT 3.1.1 compliant interface.
The onboard Real Time Clock Calendar and EEPROM is accessible via IQRF module preprogrammed
with custom DPA handler. The peripherals can be used with standard DPA commands described in
DPA Commands document.
Various application running methods available via the Linux operating system, a Web server and PHP
interpreter is preinstalled with some example project.
The gateway by default comes with Ethernet connection. User has the possibility to change network
interface such as use a compatible USB WiFi dongle if wireless network connectivity is necessary.

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 4 / 21
Figure 1 Communication architecture of Universal Gateway

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 5 / 21
1.2 Use cases
The Universal Gateway is applicable to most automation fields. This part of the documentation help
to find the most fit solution for custom applications.
1.2.1 Onboard custom applications
The onboard applications scenario means the custom application runs alongside the unid daemon on
the Universal Gateway’s Linux OS. The custom application communicates with unid daemon across
User Network Interface on UDP protocol. Figure 2 shows the Universal Gateway with onboard custom
application scenario.
Figure 2 Universal Gateway with onboard custom application
At WEB application scenario the users can manage and control the IQRF network through the
onboard installed WEB server application. In this scenario the custom WEB application communicate
with the unid daemon. Figure 3 shows the Universal Gateway with custom WEB application scenario.
Figure 3 Universal Gateway with custom WEB application

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 6 / 21
1.2.2 MQTT applications
MQTT (Message Queuing Telemetry Transport) is an ISO standard (ISO/IEC 20922) publish-subscribe
based light-weight messaging protocol for use on top of the TCP/IP protocol. It is designed for
connections with remote locations. The publish-subscribe messaging pattern requires a message
broker. The broker is responsible for distributing messages to interested clients based on the topic
of a message.
The Universal Gateway MQTT Interface is provides a bi-directional secure communication between
the broker end the gateway. This solution allows that applications can access to the gateway through
the internet.
The Figure 4 shows the Universal Gateway in a MQTT based solution.
Figure 4 Universal Gateway with MQTT application
The MQTT Client interface is transparent for the IQRF network that means the MQTT message
payloads contains the IQRF packet payloads in both directions (see 2.2.1 Example)
The Universal Gateway MQTT Client Interface is fully compatible with Amazon AWS IoT or can use
open source brokers such as Mosquitto. To setup Universal Gateway to AWS IoT see Quick start
guide - 6.2 Amazon AWS IoT.
The MQTT Client Interface setup described in details at section 2.2.

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 7 / 21
2Interfaces
The Universal Gateway has three main interface to interact with applications. The IQRF IDE Interface
can connect to the IQRF IDE and perform UDP device services. The UNetIf –User Network Interface
is a transparent interface to the IQRF coordinator. The transparency means the user application can
send and receive IQRF DPA packets in HEX string format. The MQTT Interface is also a transparent
interface. The MQTT message payload handled as well as at the UNetIf. Figure 5 shows the unid
daemon interfaces architecture.
Figure 5 Universal Gateway Interfaces

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 8 / 21
2.1 UNetIf –UDP User Network Interface
The User Network Interface enables transparent access to the IQRF network via UDP communication.
The UNetIf interface provides a UDP server. The client application should send UDP packets with HEX
strings to the UNetIf and the interface send back the IQRF responses. By this solution the UNetIf
interface want to reproduce the simple operation of the IQRF USB programmer.
For example, if requests for the addressing information send the following request:
00000000FFFF
The response should be something similar:
00000080120300000215
The interface accept separated HEX strings. The UNetIf removes all non-HEX string compliant
characters before attempting to transmit to the IQRF module. It is simplify the separation for human
readings.
The UNetIf interface accept HEX string like:
0000.00.00.FFFF.
0000-00-00-FFFF
0000#00#00#FFFF#
The response always sent back without separation. The separated examples above results the same
response:
00000080120300000215
This feature only for simplify human reading for set constant values in the client side applications
source or directly sent messages for operators.
Caution!
The UNetIf interface not cares about the IQRF packets collisions and timings. The packet timing and
collision avoidance must be managed in the client application!
For the simple start with the UNetIf interface see the example codes at chapter Demo examples.
The IQRF DPA Framework documentation can be found at http://www.iqrf.org/DpaTechGuide/.

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 9 / 21
2.2 MQTT Interface
The Universal Gateway MQTT Interface is a MQTT 3.1.1 compliant interface with SSL/TLS support.
This interface designed to enables all MQTT features to IQRF IQMESH networks via a transparent
interface. The IQRF requests and responses transferred directly in HEX string format to simplify data
processing in high-level programming or script languages. The interface in addition handles the MQTT
traffic topics according to the configurations. The Figure 6 shows the operation of the MQTT
interface.
Figure 6 MQTT Client Interface
The basic operation shown on Figure 6 and work simple as:
1. Subscribe for all topics specified in the /etc/unid/subscribe.conf configuration file (“subscribe”
parameter)
2. If any message received to any specific subscribed topic and the target is set to network the
daemon sends the message to the IQRF module on the gateway
3. If response option is set true the daemon send the IQRF response to the specified publish topic
(“publish” parameter)
Caution!
The current version of the Universal Gateway firmware not handle timing. It must be managed on
the application side.

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 10 / 21
2.2.1 MQTT Client Interface configuration
The MQTT client by default uses the /etc/unid/subscribe.conf configuration file to describe the
interface communication. The file path can be modified as the subconf parameter in the unid.conf
configuration file. The MQTT parameters also can be modified in the unid.conf file described in
section 3.2.
{
"topics":
[
{
// subscribed topic name, %c, %u used for automatic replacement
// of clientId or username
"subscribe": "iqrf/gateway/%c/network/request",
// value 0, 1 or 2, the requested Quality of Service
// for this subscription
"sub_qos": 0
"target": "network", // default
"message" : "raw", // default
// set response true if the subscribed topic needs a response
"response": true,
// the response message topic name to publish,
// %c, %u used for automatic replace clientId username
"publish": "iqrf/gateway/%c/network/response",
// value 0, 1 or 2 indicating the Quality of Service
// to be used for the message
"pub_qos": 0,
// if true the broker will keep the message even after
// sending it to all current subscribers
"retain": false
}
]
}
The topic names can handle some automatic replacement. In the unid.conf file the MQTT username
and client ID can be configured (3.2). The client ID can be configured as an automatically filled value
like MID of the IQRF or the MAC address or the NetBIOS name of the gateway. With %u the username
and with the %c the client ID can be automatically replaced.
For example by default the client ID source set automatic and specified to hwid (MID of the IQRF) the
topics will be as follows:
iqrf/gateway/%c/network/request -> iqrf/gateway/81001122/network/request
iqrf/gateway/%c/network/response -> iqrf/gateway/81001122/network/response
Example:
# Request
topic: iqrf/gateway/81001122/network/request
message: 00000000FFFF
# Response
topic: iqrf/gateway/81001122/network/response
message: 00000080120300000215

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 11 / 21
2.3 IQRF IDE Interface
The IQRF IDE Interface enables the Universal Gateway to connect to the IQRF IDE as a UDP device
similar to other IQRF gateways. The IQRF IDE Interface provides more possibility than a simple UDP
device.
2.3.1 IQRF IDE Interface packet sniffer service
The Universal Gateway has a packet sniffing service option. This service very useful for develop,
debug or testing new applications. The packet sniffing is forwarding IQRF network data stream to the
IQRF IDE. The IQRF data stream can be observed in real time in the IQRF IDE terminal log (Figure 7).
Figure 7 IQRF IDE –Packet sniffing log
The Rx/Tx IQRF data stream is shown as all data are received!
The packet sniffing service just add an extra option to the interface. If the packet sniffing service is
enabled (“morroring” parameter in the configuration file set true) the IQRF IDE Interface should
forwards all packets which transferred via IQRF. Figure 8 shows all packets from the UNetIf or MQTT
Interface can be forwarded to the IQRF IDE.
Figure 8 Enabled packet sniffing

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 12 / 21
2.4 DPA compatibility mode
In DPA compatibility mode the daemon can capture DPA commands and make some helper methods.
2.4.1 FRC commands
The DPA FRC response can be captured the daemon automatically requests for the Extra result and
the user get the concatenated FRC response with Extra result PData. The FRC response message looks
like:
[FRC response][Extra result response PData]
Without DPA compatibility mode: (64 byte)
00.00.0D.80.12.03.00.00.00.00.00.00.00.00.00.00.
00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.
00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.
00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.
With DPA compatibility mode: (73 byte –total 64 byte PData)
00.00.0D.80.12.03.00.00.00.00.00.00.00.00.00.00.
00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.
00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.
00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.00.
00.00.00.00.00.00.00.00.DC.

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 13 / 21
3Daemon configuration
The unid operation is based on of the daemon configuration file at /etc/unid/unid.conf. To modify
the configuration file login to the gateway via SSH or serial console and open the daemon
configuration file with a text editor.
$ sudo nano /etc/unid/unid.conf
3.1 System configuration [system]
# network interface
netiface = eth0
The network interface parameter is important to determine the main interface MAC address of the
gateway.
# netbios daemon
netbios = true
The NetBIOS name is created from the last 4 digits of Raspberry Pi B+ MAC address i.e.:
GW-UNI-01-CAFE.
When IDE port is enabled NetBIOS service starts automatically!
# logfile path
# for use default log path leave it blank
# it is useful if you use read only file system
# or mounted external drives
logpath =
Caution!
The default log path is /tmp/unid.log for decrease SD card write cycles to avoid early damage in the
development phase. Set non-volatile log path in production is highly recommended!
# daemon log level
# 0: warn/error
# 1: info
# 2: debug
# 3: trace
loglevel = 0
The loglevel determines what kind of information should be logged. For the simpler development
you can run the daemon directly from command line. If loglevel set to debug or trace most of the
daemon processing information can be observed in real time.

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 14 / 21
First stop the daemon:
$ sudo service unid stop
After that run from command line with the -v connector for verbose mode. Logging into the log file
is disabled in verbose mode.
$ sudo unid -v
3.2 MQTT Client Interface configuration [mqtt]
# the hostname or IP address of the broker to connect
host = broker.example.com
# the network port to connect to, default is 1883
# to disable this interface set to 0
mqttport = 8883
# keepalive 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
keepalive = 60
# clientid source select
# auto: the daemon set the client ID automatically
# manual: custom string
clientidsource = auto
The client ID is can be set automatically by the daemon. It is useful for mass production to identify
the gateways.
# clientidsource-> manual: any string without whitespaces
# clientidsource-> auto: hwid, mac, netbios
# in auto mode the daemon set the client ID automatically:
# hwid: MID of the attached IQRF modul (i.e. 8100CAFE)
# mac: MAC address of the gateway (i.e. B8-27-EB-00-BE-AF)
# netbios: NetBIOS name of the device (i.e. GW-UNI-01-BEAF)
clientid = hwid
# set to true to instruct the broker to clean all messages
# and subscriptions on disconnect, false to instruct it to keep them
cleansession = true
# username
username =

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 15 / 21
# password
password =
# mqtt enable ssl
usessl = true
If usessl set to false the TLS options will be ignored.
# CA file
cafile = /etc/unid/certs/rootCA.pem
# cert file
certfile = /etc/unid/certs/certificate.pem.crt
# private key
keyfile = /etc/unid/certs/private.pem.key
# configure verification of the server hostname in the
# server certificate
# this can be useful in initial server testing
# MUST BE SET TO "false" IN A REAL SYSTEM!!!
insecure = false
# the topic on which to publish the will
will_topic =
If will_topic leaved blank the testament options will be ignored.
# will messag
will_payload =
# will quality of service
# values: 0,1,2
will_qos = 0
# set to true to make the will a retained message
will_retain = false
# file path with predefined topics for subscribe
subconf = /etc/unid/subscribe.conf
The subscribe configuration details described in section 2.2.1.

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 16 / 21
3.3 IQRF IDE Interface configuration [ide]
# IDE UDP port
# to disable this interface set to 0
# default is 55300
ideport = 55300
# enable/disable gateway reset from IDE
gwreset = true
# enable/disable TR module reset from IDE
modulereset = true
The communication between the gateway and the IQRF IDE is not secure. The gateway and TR
module reset can be disabled.
3.4 User Network Interface configuration [unetif]
# user network interface UDP port
# to disable this interface set to 0
# default is 5000
unetifport = 5000
# user network interface accessed by other devices
# if remoteaccess is true
# (bind to netiface, if false bind to loopback)
remoteaccess = false
Configure user network interface external availability (internal from localhost only, or internal and
external)
Caution!
Because of some security reasons, we recommend to activate remote access only for development
purposes!

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 17 / 21
3.5 IQRF communication configuration [network]
# network command queue size limit
networkqsize = 100
# enable queue to overwrite the oldest item when the queue is full
# the overwrite is logged
networkqoverwrite = true
# compatibility modes
# available compatibility modes: dpa
# if not used comment out or leave it empty
compatibility = dpa
In compatibility mode enables some useful features:
dpa: IQRF DPA helper features
# mirroring is enables packet sniffing in the daemon
# the RF network packets forwarded to the IQRF IDE
# false - no mirroring
mirroring = true

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 18 / 21
4Demo examples
The Universal Gateway has some example applications with source codes. These sources are on the
preinstalled image and the latest version also available on GitHub repository at
https://github.com/iqhome/unigw.
The examples contains some dummy example on different programming language for simplify the
start of the development process with the Universal Gateway. The examples shows how to
communicate from your custom application with the IQRF DPA network via unid daemon on the
gateway. Available examples:
C
Java
PHP
Python
For more details go to https://github.com/iqhome/unigw or see the README.md file.

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 19 / 21
5Release Notes
5.1 v1.01
New features
Automatic SPI fast mode detect for IQRF TR-7x modules
5.2 v1.02
Changes
UNetIf accept separated HEX string request formats (i.e 0000.00.00.FFFF or 0000#00#00#FFFF)
New features
MQTT Client Interface

GW-UNI-01 User Manual
© 2016 IQ HOME Kft. www.iqhome.org 20 / 21
6Troubleshooting
Problem
Possible cause
Solution
No lights on the gateway
The unit is turned off
Power on the unit
Check power supply
Gateway status LED light is
steady blue
There is a problem around the
gateway daemon or
Linux OS problem
Log in to the gateway and try to
restart the daemon
Power cycle the gateway
Raspberry Pi’s LEDs are
working, but gateway status
LED is off
The unid daemon is not
running.
Log in and issue
/etc/init.d/unid restart
command