Zigbee to SENSEI Gateway Cookbook

UNDER CONSTRUCTION

This document includes instructions about installing and running the Zigbee to SENSEI Gateway in a computer.

Table of Contents

1. Introduction
2. Installation
   1. Requirements
   2. Package Content
3. Specification
4. Configuration
   1. Zb2SenseiGw.exe.config file
   2. rpi.xml file
5. User manual
6. Troubleshooting
7. Mobility

Introduction

The Zigbee to SENSEI gateway is a software that allows connecting a zigbee WS&AN island into the SENSEI framework. The gateway implements the REP (Resource End Point) of the island resources publishing into the RD (Resource Directory) and implements the RAI (Resource Access Interface) that allows a client to get and actuate over resources together with subscribe for notify.

This software runs under Windows Operating System, and needs a zigbee USB dongle.

Installation

There is not an installation package available. To run this software is it needed to paste the files in a directory and run the exe file “Zb2SenseiGw.exe”. Prior to that it is convenient to adjust the configuration file (see Configuration section).

Requirements

The package requires

• Windows XP operating system version or upper.
• No special requirements of memory speed or hard disk needed. It is very light.
• External Hardware: Zigbee dongle. It has been tested the zigbee dongle of “Integration” model “IA DAUB-DK1 2400”.
  • Drivers of this dongle should be properly installed before running the package.
• IP connection. Make sure that the firewall allows the package to establish a TCP server.

Package Content

• Main executable file:
  • ZB2SenseiGW.exe
• Resource files:
  • connect.bmb, disconnect.bmp, linked.bmp
• Configuration files:
  • ZB2SenseiGW.exe.config, rpi.xml (more configuration files can be added, see Configuration section)
• Libraries of zigbee dongle:
  • STKUSB.dll, ZB.dll

Specification

Two ways of connecting to a zigbee gateway, with zigbee dongle or throw a external ip gateway …

UNDER CONSTRUCTION

1. Throw a zigbee dongle
2. Throw an external gateway

The software discovers nodes of the zigbee net, and for each node it discovers sensors and actuators. This software operates under the following zigbee configuration:

• It has been tested upon zigbee 2007. Zigbee Pro should work depending on the zigbee dongle
• It is needed to known a priori physical zigbee parameters
  • Frequency channel number (1 to 26)
  • zigbee net password
  • extended PAN Identification helps but not needed.
• Not all the zigbee profiles are detected. It have been tested under temperature, light, human presence, acceleration sensors and electricity on/off actuator.

The Gateway has the following features regarding Resource End Point implementation

• Allows publication against a Resource Directory
• Allows getting data from sensor and acting over an actuator using RESTful access
• Allows subscription to resources. Notification can be requested upon one or several of the following conditions:
  • Periodic time. If active, it sends a new notification when it takes the specified time after the last sent notification.
  • Value change. If active, it sends a notification when the value changed
  • Threshold. When the value goes beyond a threshold a notification is sent.
• Allows mobility. Several gateways can be located in the vicinity and in case the Zigbee Island allows nodes to move, both gateway communicates each other to properly handle the mobility.

In order to not saturate the islands with possible huge requests from the internet world, the gateway do not bypass the entire requests to the island. For that reason the gateways stores the last value of the resources in order to respond by itself to request targeting the same resource that arrives in a short period of time.

Configuration

Two xml files need to be edited for properly configuring the software package before running it. These configuration files allows to establish most of the behaviour of the package without the needed of compile the software.

Remember that these files are read when application starts. If you change a value, it will not be considered after restarting the application.

It is not needed special editor for changing these files. Whichever text editor used is enough. But special care should be followed for not modifying the overall xml structure, and the rest of the tags. Read this manual before proceed to edit the files.

Do not worry if you are not familiar with xml basis. Look for the target name that follow “key=”, and you must edit only the text between double apostrophes after the “value=” text.

Zb2SenseiGw.exe.config file

The "Zb2SenseiGw.exe.config" file allows establishing:

"autoConnectType" and "autoConnectIndexCh": Indicates if you want to connect to the Zigbee island automatically when the application starts. It is very useful for non attended servers if the computer or application restarts for whatever reason. The possible values of "autoConnectType" are:

• "off": do not connect automatically. Manually connection needed after application start. "autoConnectIndexCh" value is ignored.
• "ch": connect automatically using zigbee dongle. "autoConnectIndexCh" indicates the frequency channel; allowed values are from 11 to 26.
• "ip": connect automatically to a ip zigbee gateway. "autoConnectIndexCh" indicates the index "<netConn>" list to be used. The first index is 0.

"<netConn>" list. Contains a list of ip address that the gateway can connect to when non local connection is used. Each element in the list contains:

• "idNet": description or name that appears in the application.
• "remoteip": ip adress.
• "remoteport": remote server tcp port.
• "localport": local server tcp port to be used when connected. Used for receiving responses. Beware not to use local ports used by other software in the computer.
• "com": if local rs232 modem is used, it indicated the port number. Not implemented.
• "remotetelephone": for communication using SMS instead of ip. Not implemented.
• "manufacturer", "model", "imei", "imsi", " msisdn ": Parameters of other end modem, if a modem is used. These is for information only and it is not used at all. Leave empty, but do not delete.

"netPassword": zigbee net key in hexadecimal format. Leave empty for no security options.

"netExtPANid": target zigbee extended PAN identifier in hexadecimal format: leave empty for any (example: "20DB765432144010").

"Sensei_RPI_ProxiHost","Sensei_RPI_ProxiPort","Sensei_RPI_ProxiBypass": If proxy is used for accessing internet both for publication and notification, proper configuration is needed here. If not, leave empty. Insert Host as name or IP address, TCP port to be used and bypass contains local IP address ranges that do not use the proxy, as for example "192.168.0.0/192.168.255.255"

"Sensei_RAI_BaseURL": Base URL for the SENSEI RAI Resource Access Interface server. For example "​http://myIP:8081/sensei/rai/resources/ ". If empty, the application will not implement the RAI server. It is mandatory to include the port event if the default port is used. It is also mandatory to end in "/". "myIP" text will be replaced by first real computer IP address. If the computer has several IP address and you want to use another, put it explicitly. Finally, the application will append the nodeID/[s or a]/number to this URL.

"Sensei_RPI_URL": SENSEI Target Resource Directory URL for Publishing. Leave Empty for not publishing resources into Resource Directory. End with "/". Application will add "rpi", "rli" or "rd" suffix when needed. For example "​http://sensei-dev1.grid.pub.ro:8184/ ".

"Sensei_RPI_RAIBaseURL": URL published in "<Rai-Description> <REP-Locator>" into Resource Directory for each resource. If empty it will take Sensei_RAI_BaseURL, but it can be different if needed for example if gateway fo throw a proxy or a router that changes the local IP into a public IP. End with "/". Application will append nodeID/[s or a]/number to this URL. "myIP" text will be replaced by first real computer IP address.

"Sensei_RPI_ExpirationTime": Expiration date for each resource published into the Resource Directory, in hours from first publication. If empty, one week will apply.

"ZB2SenseiGw_Password": This is used in case of mobility. Contains a text password that it is needed to provide from one gateway for credentials. The gateways that take part in the mobility of a node need to be the same password.

rpi.xml file

The rpi.xml file indicates what exactly format should be sent to the resource directory for publishing a resource. In that way format can be completely changed for new versions without the need of compilation.

In addition " rpi.xml " is a generic file for all the resources, but you can specify individual files for each resource. Simple insert a file with the same structure in the package directory and with the name equals to "nodeIDsnumber.xml" for a sensor or "nodeIDanumber.xml" for and actuator. Where "nodeID" is the node MAC address in hexadecimal format, (16 characters), and "number" is the index of the sensor or actuator starting by 0. If an individual file is present it will be considered, if not, the generic one is considered.

The "*.xml " file can include the following text that will be replaced with the proper values by the application:

• "_ResT": name of the resource, for example temperature, light, etc.
• "_NODE ": node id, that is the MAC address in hexadecimal format with capital letters (16 characters).
• "_NET ": net id, that is, coordinator MAC address in hexadecimal format with capital letters (16 characters).
• "_RES": will be replaced by "a" for an actuator or "s" for a sensor.
• "_NUMBER ": number of the sensor or actuator, starting by 0. If the node contains several, the order of appearance is considered.
• "_TYPE ": will be replaced by "actuator" for an actuator or "sensor" for a sensor.
• "_TIME": expiration time contained in the "Sensei_RPI_ExpirationTime" variable of the "Zb2SenseiGw.exe.config" file.
• "_ RAI": value of the " Sensei_RPI_URL " variable of the "Zb2SenseiGw.exe.config" file.

User manual

Troubleshooting

Mobility