= Zigbee to SENSEI Gateway Cookbook = This document includes instructions about installing and running the Zigbee to SENSEI Gateway in a computer. [[PageOutline(2-3,Table of Contents,inline)]] == 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 resources in the island publishing into the RD (Resource Directory) and implements the RAI (Resource Access Interface) that allows a client to get, actuate and subscribe over the resources. This software runs under Windows Operating System. There are two ways of connecting to a Zigbee island: 1. Through a Zigbee USB dongle attached to the PC. In this case the PC needs to be in the rario coverage of the Zigbee island. 2. Through IP connection to an external concentrator. This concentrator is an element that simple translates the Zigbee binary message into IP and transports it using a TCP/IP socket. [[Image(zb2senseigw_connection.JPG, 40%, center)]] == Requirements == The package requires: * Windows operating system, version XP or upper. * No special computer performance requirements are needed. * External Hardware (one of the following): * 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. After installation, the following libraries should be available on the system path: //STKUSB.dll// and //ZBDLL.dll//. Alternatively these libraries can be copied to the same folder where package is installed. * External concentrator, that convert the Zigbee messages into IP for transmitting using TCP/IP protocol. * IP connection. Make sure that the firewall allows the package establishing a TCP server. == Installation == Package is available [wiki:zbGw-dwload here]. Just unzip the package files in a directory. Previously to run this software, it is necessary to adjust the configuration files (see [#Configuration Configuration section]). === Package Content === ||='''files'''=||='''description'''=|| ||//ZB2SenseiGW.exe//=||Main executable file || ||//./Resources/connect.bmb//, //disconnect.bmp//, //linked.bmp//, //sensei.ico//=||Resource files || ||//ZB2SenseiGW.exe.config//, //rpi.xml//=||Configuration files (more configuration files can be added, see [#rpi.xmlfile Configuration section]) || == Configuration == Two xml files need to be edited for properly configuring the software package before running it. These configuration files allow establishing most of the behaviour of the package without the need of compile the software. Remember that these files are read when application starts. So 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 section before proceed to edit the files. Look for the target name that follow the text "//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: "**//Language//**": Specify language of messages and debug traces. Available languages are "//en//" (English, by default) and "//es//" (Spanish, but still some traces are only in English). "**//AppName//**": Specify the name of the application once connected to the net. By default it is "//Zigbee to Sensei Gateway//" but it can be useful to have different names related to the net if several instances are running. Net MAC will be appending between brackets. "**//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 concentrator. "//autoConnectIndexCh//" indicates the index of "**////**" list to be used. The first index is 0. "**////**" list. It contains a list of ip address that the gateway can connect to an external concentrator. 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 choose local ports used by other software in the computer. "**//netPassword//**": Zigbee net key in hexadecimal format. Leave empty if this security options is not used. "**//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. Fill "Host" as name or IP address, proxy TCP port used and bypass contains local IP addresses 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 Resource Access Interface (RAI ) 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 "/". The text "//myIP//" will be replaced by first computer IP address. If the computer has several IP addresses and you want to use another, put it explicitly instead of "//myIP//". Each resource is acceded through **BaseURL/ //nodeID/[s or a]/number//** (see [#RAIinterface RAI Interface] for more details). "**//Sensei_RPI_RAIBaseURL//**": Base URL that will contain the " " tag when a resource is published in the Resource Directory. If empty it will take previous //Sensei_RAI_BaseURL// variable, but it can be different. It is needed for example if the gateway access through a proxy or a router that changes the local IP (used when mounting an http RAI server) into a public IP (that is the IP seen from outside). Same rules as before apply: End with "/", application will append "//nodeID/[s or a]/number//" to this URL; and "//myIP//" text will be replaced by first computer IP address. "**//Sensei_RPI_URL//**": Target SENSEI Resource Directory URL for publishing. Leave Empty for not publishing resources into Resource Directory. End always with "/". Application will add "rpi", "rli" or "rd" suffix when needed. For example "//http://sensei-dev1.grid.pub.ro:8184/ //". "**//Sensei_RPI_ExpirationTime//**": Expiration time for each resource published into the Resource Directory, in hours from first publication. If empty, one week will apply. "**//Sensei_UnPublishRD_Time//**": If not empty, the gateway will delete a resource after it passes this time in minutes without having any news of this resource. And the gateway will also delete the published resources upon exit. It is convenient not to set this property if mobility is intended, because published resources in RD will be use for knowing the preceding gateway when a resource moves. "**//ZB2SenseiGw_Password//**": This is used for mobility of nodes between islands. It contains a text password that is needed to provide credentials between gateways. The gateways that take part in the mobility of a node need to have the same password. Leave empty if you do not want to implement credentials. For a dongle connection, "**//timeWaitNodes//**" is the timeout in milliseconds of a node response, adjust it to the maximum node latency in the net. "**//timeLinkedGateway//**" is the timeout in milliseconds when linking to the net. "**//timeExecuteOrder//**" is the timeout of a dongle response. For an external concentrator connection, "**//timeSleepNodes//**", "**//timeConnection//**" and "**//timeReadMessages//**" respectively have the same meaning as before. "**// Retries //**": Number of retries that will be tried when a Zigbee node does not respond before discarding this node. === rpi.xml file=== The **// rpi.xml //** file contains the xml text that will be sent to the Resource Directory when 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. This can be done by inserting just a text file with the same structure in the package directory. If an individual file is present it will be considered, if not the generic "rpi.xml" file is considered. The individual files must have the following name (without blanks) "//**nodeID X number . xml**//", where: * "//**nodeID**//" is the node MAC address in hexadecimal format, (exactly 16 characters). * replace "//**X**//" with "s" for a sensor or "a" for an actuator. * "//**number**//" is the index of the sensor or actuator starting by 0. In the "**//*.xml //**" file the following text variables will be replaced with the proper values by the application (case sensitive): * "//**_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 equals to now plus the time of "//Sensei_RPI_ExpirationTime//" variable of the "//Zb2SenseiGw.exe.config//" file. * "//**_ RAI**//": value of the "//Sensei_RPI_RAIBaseURL//" variable of the "//Zb2SenseiGw.exe.config//" file. == Running. User manual == Execute the exe file "Zb2SenseiGw.exe" to run this software. Figure shows the main screen of the application. [[Image(zb2senseigw_mainsreen.jpg, 50%, center)]] On the upper side, the type of connection to the Zigbee island is shown. The "**USB**" is through a dongle and the "**IP**" through an external concentrator. The "**IP/Ch**" select box contains the Zigbee channel for USB or the connection name (see [#Zb2SenseiGw.exe.configfile idNet in Configuration]) for IP. The button "**Connect**" and "**Disconnect**" starts the attaching or detaching to the Zigbee island. The connection process takes a while, firstly it engages in the Zigbee island. Secondly it discovers the nodes and resources. The node list appears on the "**Tree of nodes**" tree box. Details of a node selected in the tree box are shown on the right side of the screen: * Short and MAC address, father node (for sleeping nodes). * Number of resources or devices. * Model and version. * Power transmission, Link Quality Indicator (LQI). * Relative position. For every sensor, actuator or counter (sensor) additional details are shown in the corresponding tags on the "**Node Description**" The upper side tags are used for debugging. It contains **Commands** that can be raised manually to the island for testing purposes, **Events** receives from WS&AN, and traces of **Orders** receives from SENSEI. === Troubleshooting === **It appears the error message: //"Error while connecting to Zigbee dongle"//:** Ensure that a zigbee dongle is properly inserted in the PC. Ensure that no other application is using the dongle. Remove and insert it again. **The gateway does not connect to the Zigbee net:** Ensure that you have configured the right extender PAN id, password, and channel frequency. **Not all the resources appear in the "tree list":** Ensure that you have properly dimensioned the timeout variables in the configuration file according to the node latency. It can also happen that nodes have profiles or attributes not recognized by this version of the application. **It does not publish the resources in the Resource Directory:** Ensure that the proxy variables are properly adjusted depending on your internet connection, and the resource directory URL is properly filled in the configuration file. == Specification == The two ways of connecting to a Zigbee island (dongle or concentrator) are quite similar, the dongle and external concentrator have primitives for connecting to a Zigbee island and for interchanging messages. In the case of dongle it is done through a library (*.dll). In the case of the external concentrator it is done using a TCP/IP messaging. The software engages to the island, discovers nodes, and for each node it discovers resources, that is, sensors and actuators. This software operates under the following Zigbee configuration: * It has been tested upon Zigbee 2006. Zigbee Pro should work depending on the Zigbee dongle or concentrator. * It is needed to known a priori physical Zigbee parameters: * Frequency channel number (11 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, proprietary location sensors and electricity on/off actuator. The Gateway has the following features regarding **Resource End Point (REP) implementation**: * Allows **publication** of individual resources (sensors and actuators) into a Resource Directory, using the [wiki:RpResDescription Resource Description Format]. * Allows **getting** data from resources and **acting** over them 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 after "period time" passes without having sent a notification. * **Value change**. If active, it sends a notification when detected that the value has 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 the case that the Zigbee island allows nodes to move, both gateways communicate each other to properly handle the mobility. In order to not saturate the islands with possible huge requests coming from the internet world, the gateway do not bypass all the requests to the island. For that reason the gateways stores the last value of the resources in order to respond by itself to requests targeting the same resource that arrives at the same time. === RAI interface === This Gateway creates a REST interface for allowing applications to iterate with the Zigbee island resources. This interface is defined in [wiki:RpObservationMeasurement Observation & Measurement]. Each resource has its one URL, with the following format: "//**BASE_URL/nodeMAC/X/number**//" * //nodeMAC// is the node MAC address in hexadecimal capital letters (16 characters). * //X// is the letter "s" for a sensor or "a" for an actuator. * //number// is the number of sensor or actuator, starting with "0". Over this resource URL the following operations can be done: * GET http method is used for getting an "xml" with the sensor or actuator value. An xml with the format explained in [wiki:RpObservationMeasurement Observation & Measurement] is obtained. * PUT http method is used for changing a parameter, or acting over an actuator. === Subscriptions === A POST http method over the resource URL is used for adding a new subscription. For that, the URL must contain after the resource URL the subscription identity: "//**BASE_URL/nodeMAC/X/number/SubscriptionID**//". //"SubscriptionID"// is whatever text allowed in the URL names. To test the Subscription Module you have to issue a post request to a resource url (i.e. http://localhost:8081/2098765432142017/sensei/resources/rai/s/0/sub_id ) with the following xml text: {{{ where you want to receive notifications maximum time between notifications in ms 0: equal to, 1: greater than, or 2: less than Send a notification when this threshold has been passed If present, send notification only if the value has changed }}} * A PUT http method over this subscription URL is used for modifying it. * A GET http method over this subscription URL returns the subscription xml information. * A DELETE http method over this subscription URL is used for deleting it. * A POST http method over this subscription URL returns an error if it exist or add a new subscription if it does not exist. * GET over "//BASE_URL/nodeMAC/X/number**?Subscription**//" can be used for getting the list of subscriptions of a resource. * GET over "//**BASE_URL/nodeMAC **//" returns an html page with node information, sensors and actuators, and links for the subscriptions. === Mobility === Zigbee gateway resolves the mobility of a node between several gateways. In the case of Zigbee there is no possibility of storing information inside nodes that helps to the mobility. So gateways need to resolve the problem by themselves. Figure shows how mobility is treated by Zigbee gateways. [[Image(zb2senseigw_mobility.jpg, 25%, center)]] 1. (and 4.) When the node connects to a new island, the gateway forms the Resource End Point of the node resources. **Resource identification** formed by the gateway is **always the same** independently of the gateway. The identification depends only on node parameters. In our case it is used the node MAC address, that is unique, and the sensor number position. 2. (and 5.) Previously to publish in the Resource Directory, it discovers if the resource is already present using the RLI interface. 3. If the resource does not exist, it is published into the Resource Directory. 4. Node moves to gateway B. See 1 5. Resource is already present in the Resource Directory. In the response the old gateway URL is obtained. 6. As the resource exists in the Resource Directory, it is updated. No duplication of the same resource can be found in the Resource Directory. 7. The new gateway informs the old gateway about the new location (URL) of the resource. In the response, the old gateway sends all the subscription information that this resource has, and it is implemented by the new gateway. 8. The old gateway in addition will redirect whatever access to this resource to the new URL using the http redirect response. This redirection is transparent to applications. The final result is that applications do not notice at all (if they do not want) that a resource has been moved. For optimization, mobility commands interchanged between gateways are not sent at a resource basis, but only once for all the resources of a node. === Mobility format interchanged between gateways=== This section details the message (7.) of previous figure. The new gateway informs about node mobility to the old gateway with a PUT http method addressing the node id (not resource id) with the following xml content: {{{ new URL of the resource password }}} In the response, if the credentials are accepted, the old gateway informs about all the subscriptions that the resources of the node contains, with the following xml format: {{{ content described in Subscriptions section content described in Subscriptions section content described in Subscriptions section }}}