Changes between Version 4 and Version 5 of ZigbeeGateway


Ignore:
Timestamp:
Sep 19, 2010, 5:14:57 PM (14 years ago)
Author:
Sensei
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • ZigbeeGateway

    v4 v5  
    11= Zigbee to SENSEI Gateway Cookbook =
    22
    3 **UNDER CONSTRUCTION**
    43
    54This document includes instructions about installing and running the Zigbee to SENSEI Gateway in a computer.
    … …  
    87
    98== Introduction ==
    10 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.
    11 
    12 This software runs under Windows Operating System, and needs a zigbee USB dongle.
     9The 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.
     10
     11This software runs under Windows Operating System. There are two ways of connecting to a Zigbee island:
     121. 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.
     132. 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.
     14[[Image(ZB2SenseiGwConnection.JPG, 50%, center)]]
     15 
    1316
    1417== Installation ==
    15 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 Configuration section]).
     18There is not an installation package available. To run this software just copy and paste the files contain in the [#PakageContent package] in a directory and run the exe file “Zb2SenseiGw.exe”. Prior to that, it is convenient to adjust the configuration file (see [#Configuration Configuration section]).
    1619
    1720=== Requirements ===
    18 The package requires
     21The package requires:
    1922* Windows XP operating system version or upper.
    20 * No special requirements of memory speed or hard disk needed. It is very light.
    21 * External Hardware: Zigbee dongle. It has been tested the zigbee dongle of “Integration” model “IA DAUB-DK1 2400”.
    22        * Drivers of this dongle should be properly installed before running the package.
     23* No special computer performance requirements are needed.
     24* External Hardware:
     25       * Zigbee dongle. It has been tested the Zigbee dongle of “Integration” model “IA DAUB-DK1 2400”.
     26              * Drivers of this dongle should be properly installed before running the package.
     27       * External concentrator, that convert the Zigbee messages into IP for transmitting using TCP/IP protocol.
    2328* IP connection. Make sure that the firewall allows the package to establish a TCP server.
    2429
    … …  
    3035* Configuration files:
    3136       * //ZB2SenseiGW.exe.config//, //rpi.xml// (more configuration files can be added, see [#Configuration Configuration section])
    32 * Libraries of zigbee dongle:
     37* Libraries of Zigbee dongle:
    3338       * //STKUSB.dll//, //ZB.dll//
    3439
     40=== Compilation ===
     41The sources are written in C# language. Microsoft Visual Studio 2010.
     42Open “ZB2SenseiGW.sln” solution and compile the project.
     43The executable files will be located on “.\bin\release” or “.\bin\debug” (depending on the configuration) directory.
     44
    3545== Specification ==
    3646
    37 Two ways of connecting to a zigbee gateway, with zigbee dongle or throw a external ip gateway … 
    38  UNDER CONSTRUCTION
    39 
    40 1. Throw a zigbee dongle
    41 2. Throw an external gateway
    42 
    43 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:
    44 * It has been tested upon zigbee 2007. Zigbee Pro should work depending on the zigbee dongle
    45 * It is needed to known a priori physical zigbee parameters
     47The 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.
     48
     49The software engage to the island, discovers nodes, and for each node it discovers sensors and actuators. This software operates under the following Zigbee configuration:
     50* It has been tested upon Zigbee 2007. Zigbee Pro should work depending on the Zigbee dongle or concentrator
     51* It is needed to known a priori physical Zigbee parameters
    4652       * Frequency channel number (1 to 26)
    47        * zigbee net password
     53       * Zigbee net password
    4854       * extended PAN Identification helps but not needed.
    49 * Not all the zigbee profiles are detected. It have been tested under temperature, light, human presence, acceleration sensors and electricity on/off actuator.
    50 
     55* Not all the Zigbee profiles are detected. It have been tested under temperature, light, human presence, acceleration sensors and electricity on/off actuator.
    5156
    5257The Gateway has the following features regarding Resource End Point implementation
    … …  
    5459* Allows **getting** data from sensor and **acting** over an actuator using **RESTful** access
    5560* Allows **subscription** to resources. Notification can be requested upon one or several of the following conditions:
    56        * Periodic time. If active, it sends a new notification when it takes the specified time after the last sent notification.
    57        * Value change. If active, it sends a notification when the value changed
     61       * Periodic time. If active, it sends a new notification after the period time passes without having sent a notification.
     62       * Value change. If active, it sends a notification when detected that the value has changed
    5863       * Threshold. When the value goes beyond a threshold a notification is sent.
    59 * 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.
    60 
    61 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.
     64* 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.
     65
     66In order to not saturate the islands with possible huge requests coming 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 requests targeting the same resource that arrives in a short period of time.
    6267
    6368
    6469
    6570== Configuration ==
    66 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.
     71Two xml files need to be edited for configuring properly 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.
    6772
    6873Remember that these files are read when application starts. If you change a value, it will not be considered after restarting the application.
    … …  
    7782"**//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:
    7883* "//off//": do not connect automatically. Manually connection needed after application start. "//autoConnectIndexCh//" value is ignored.
    79 * "//ch//": connect automatically using zigbee dongle. "//autoConnectIndexCh//" indicates the frequency channel; allowed values are from 11 to 26.
    80 * "//ip//": connect automatically to a //ip// zigbee gateway. "//autoConnectIndexCh//" indicates the index "**//<netConn>//**" list to be used. The first index is 0.
    81 
    82 "**//<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:
     84* "//ch//": connect automatically using Zigbee dongle. "//autoConnectIndexCh//" indicates the frequency channel; allowed values are from 11 to 26.
     85* "//ip//": connect automatically to a //ip// Zigbee gateway. "//autoConnectIndexCh//" indicates the index "**//<netConn>//**" list to be used. The first index is 0.
     86
     87"**//<netConn>//**" list. It contains a list of ip address that the gateway can connect to an external concentrator. Each element in the list contains:
    8388* "//idNet//": description or name that appears in the application.
    8489* "//remoteip//": ip adress.
    8590* "//remoteport//": remote server tcp port.
    8691* "//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.
    87 * "//com//": if local rs232 modem is used, it indicated the port number. Not implemented.
    88 * "//remotetelephone//": for communication using SMS instead of ip. Not implemented.
    89 * "//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.
    90 
    91 "**//netPassword//**": zigbee net key in hexadecimal format. Leave empty for no security options.
    92 
    93 "**//netExtPANid//**": target zigbee extended PAN identifier in hexadecimal format: leave empty for any (example: "//20DB765432144010//").
     92
     93"**//netPassword//**": Zigbee net key in hexadecimal format. Leave empty if this security options is not used.
     94
     95"**//netExtPANid//**": target Zigbee extended PAN identifier in hexadecimal format: leave empty for any (example: "//20DB765432144010//").
    9496
    9597"**//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//"
    9698
    97 "**//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.
     99"**//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. Each resource is acceded throw BaseURL/ //nodeID/[s or a]/number // (see [RaiInterface RAI Interface] for more details).
    98100
    99101"**//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/ //".
    100102
    101 "**//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.
     103"**//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 the gateway access through 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.
    102104
    103105"**//Sensei_RPI_ExpirationTime//**": Expiration date for each resource published into the Resource Directory, in hours from first publication. If empty, one week will apply.
    104106
    105 "**//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.
     107"**//ZB2SenseiGw_Password//**": This is used in case of mobility. 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.
    106108
    107109=== rpi.xml file===
    108 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.
    109 
    110 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 "//**nodeID**s**number.xml**//" for a sensor or "//**nodeID**a**number**.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.
    111 
    112 The "**//*.xml //**" file can include the following text that will be replaced with the proper values by the application:
     110The **// 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.
     111
     112In 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 "//**nodeID**s**number.xml**//" for a sensor or "//**nodeID**a**number**.xml//" for an 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.
     113
     114The "**//*.xml //**" file can include the following text variables that will be replaced with the proper values by the application (case sensitive):
    113115* "//**_ResT**//": name of the resource, for example temperature, light, etc.
    114 * "//**_NODE **//": node id, that is the MAC address in hexadecimal format with capital letters (16 characters).
    115 * "//**_NET **//": net id, that is, coordinator MAC address in hexadecimal format with capital letters (16 characters).
     116* "//**_NODE**//": node id, that is, the MAC address in hexadecimal format with capital letters (16 characters).
     117* "//**_NET**//": net id, that is, coordinator MAC address in hexadecimal format with capital letters (16 characters).
    116118* "//**_RES**//": will be replaced by "a" for an actuator or "s" for a sensor.
    117 * "//**_NUMBER **//": number of the sensor or actuator, starting by 0. If the node contains several, the order of appearance is considered.
    118 * "//**_TYPE **//": will be replaced by "actuator" for an actuator or "sensor" for a sensor.
     119* "//**_NUMBER**//": number of the sensor or actuator, starting by 0. If the node contains several, the order of appearance is considered.
     120* "//**_TYPE**//": will be replaced by "actuator" for an actuator or "sensor" for a sensor.
    119121* "//**_TIME**//": expiration time contained in the "//Sensei_RPI_ExpirationTime//" variable of the "//Zb2SenseiGw.exe.config//" file.
    120122* "//**_ RAI**//": value of the "// Sensei_RPI_URL //" variable of the "//Zb2SenseiGw.exe.config//" file.
    … …  
    122124== User manual ==
    123125
     126Figure shows the main screen of the application.
     127[[Image(ZB2SenseiGw.JPG, 50%, center)]]
     128 On the upper side, appears the type of connection to the Zigbee island. 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 [#Configuration <netConn> idNet in Configuration]) for IP. The button “**Connect**” and “**Disconnect**” allows to attach or detach to the Zigbee island.
     129The connection process takes a while, firtsly it engages in the Zigbee island. Secondly it discovers the nodes and resources. The node list appears on the “**Tree of nodes**” tree box.
     130Details of a node selected in the tree box are shown on the right side of the screen:
     131* Short and MAC address, father node (for sleeping nodes).
     132* Number of resources or devices.
     133* Model and version.
     134* Power transmission, Link Quality Indicator (LQI).
     135* Relative position.
     136
     137For every sensor, actuator or counter (sensor) additional details are shown in the corresponding tags on the “**Node Description**”
     138
     139
     140The upper side tags are used for debugging. It contains traces about orders receives from SENSEI, events receives from WS&AN, and commands that can be raised manually to the island.
     141
    124142== Troubleshooting ==
     143**UNDER CONSTRUCTION**
    125144
    126145== Mobility ==
     146Zigbee gateway resolves the mobility of a node between several gateways. In the case of Zigbee there is no possibility of storing information in nodes that helps to the mobility. So gateways need to resolve the problem by themselves.
     147Figure shows how mobility is resolved by Zigbee gateways.
     148
     149**Put figure**
     150
     151Resource identification formed by the gateway is always the same as depend on node parameters only as MAC address.
     152In that way Resource Directory can be used for knowing if this resource was previously attached to other gateway, and the old URL.
     153No replication of the same resource is found in the Resource Directory. If it exists, it is updated.
     154The all gateway is informed about the new location of the resource. In the response, the all gateway sends all the subscription information that these resource had, and these are implemented by the new gateway.
     155The all gateway in addition will redirect access this resource to the new URL using the http redirect response. This redirection is transparent to applications.
     156The result is that applications do not notice if they do not want that a resource has been moved.
     157For optimization, mobility commands interchanged between gateways are not resource by resource, but for all the resources of a node.
     158=== Mobility format interchanged between gateways===
     159The new gateway informs the all gateway with a PUT http method addressing node id (not resource id) with the following xml content
     160{{{
     161<Mobility>
     162        <newREP-Locator> newURL </newREP-Locator>
     163        <Credentials>
     164                <URL ZB2SENSEI_PASSWD> password </URL ZB2SENSEI_PASSWD>
     165        </Credentials>
     166</Mobility>
     167}}}
     168
     169In 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 format:
     170{{{
     171<SubscriptionNodeInfo>
     172        <SubscriptionInfo sensor=”0”>
     173                <Subscription>
     174                         … Subscription info
     175                <Subscription>
     176                <Subscription>
     177                         … Subscription info
     178                <Subscription>
     179        </SubscriptionInfo>
     180        <SubscriptionInfo actuator=”0”>
     181                <Subscription>
     182                         … Subscription info
     183                <Subscription>
     184                …
     185        </SubscriptionInfo>
     186</SubscriptionNodeInfo>
     187}}}
     188
     189== RAI interface ==
     190This Gateway uses a REST interface for iterate with the Zigbee island. This interface is defined here (**PUT LINK** to the xml specification).
     191Each resource has its one URL, which format is “//**BASE_URL/nodeMAC/X/number**//”
     192* nodeMAC is the node MAC address in hexadecimal capital letters (16 characters).
     193* X is the letter “s” for a sensor or “a” for an actuator.
     194* number is the number of sensor or actuator, starting with “0”.
     195
     196Over this URL the following operations can be done:
     197GET http method is used for getting a sensor or actuator value
     198PUT http method is used for changing a value; logically it works only in actuators.
     199
     200=== Subscriptions ===
     201A POST http method over the resource URL is used for adding a new subscription. In this case it should be add at the end of the resource URL the subscription identity: 
     202“//**BASE_URL/nodeMAC/X/number/SubscriptionID**//”
     203* SubscriptionID is whatever text allowed in the URL names.
     204
     205A PUT http method over this subscription URL is used for modify it.
     206A GET http method over this subscription URL returns the subscription xml information
     207A DELETE http method over this subscription URL is used for deleting it
     208A POST http method over this subscription URL returns an error.
     209
     210GET over “//**BASE_URL/nodeMAC/X/number?Subscription**//” for getting the list of subscriptions of a resource.
     211GET over “//**BASE_URL/nodeMAC **//” returns an html page with node information, sensors and actuators, and links for the subscriptions. Ideally for a browser
     212
     213