| 11 | | == Requirements == |
| 12 | | |
| 13 | | * Linux |
| 14 | | * g++, make |
| 15 | | * [http://www.alhem.net/Sockets/ Sockets C++ library] (Also included in lib/Sockets-2.3.7; make; make install) |
| 16 | | * IPv6 support (for local UDP/IPv6 communications) |
| 17 | | * libxml2 (not yet in use) |
| 18 | | * openssl, openssl-dev (not in use yet) |
| 19 | | |
| 20 | | == Project Organization == |
| 21 | | |
| 22 | | * [https://ncit-cluster.grid.pub.ro/trac/Sensei-WP5/browser/gateway/bin /bin] sensei-gateway executable |
| 23 | | * [https://ncit-cluster.grid.pub.ro/trac/Sensei-WP5/browser/gateway/src /src] Gateway Core and Plug-in code |
| 24 | | * [https://ncit-cluster.grid.pub.ro/trac/Sensei-WP5/browser/gateway/xml /xml] Location of resource descriptions used by the gateway |
| 25 | | * [https://ncit-cluster.grid.pub.ro/trac/Sensei-WP5/browser/gateway/lib /lib] Sockets++ library |
| 26 | | * [https://ncit-cluster.grid.pub.ro/trac/Sensei-WP5/browser/gateway/config /config] Configuration files (unused) |
| 27 | | * [https://ncit-cluster.grid.pub.ro/trac/Sensei-WP5/browser/gateway/log /log] Log files (unused) |
| 28 | | |
| 29 | | == How to build it == |
| 30 | | |
| 31 | | The top-level Makefile will build everything with the following, which places the executable in ./bin. Note that the executable must be run from the root of the project as shown below. |
| | 11 | The gateway must be run from the root of the project |
| 38 | | To clean everything do |
| | 17 | Command line options: |
| | 18 | -p HTTPD port (default 8000) |
| | 19 | -s HTTPD hostname for inserting in resource desciptions (default localhost) |
| | 20 | |
| | 21 | The SENSEI HTTP server runs by default on port 8000. Just browse |
| | 22 | http://localhost:8000 to test it. After resources are registered you |
| | 23 | can test a GET with you browser for the registered URL by e.g.: |
| | 24 | |
| | 25 | http://localhost:8000/test/1 |
| | 26 | |
| | 27 | == Configuration == |
| | 28 | |
| | 29 | Currently only command-line configuration options are supported. There are also some Makefile options (HAVE_DEBUG, HAVE_LOGGING) and configurable parameters within source code headers. |
| | 30 | |
| | 31 | Configuration files (/config) are planned for the future when the daemon is in stable testbed use. |
| | 32 | |
| | 33 | == Sensei Plugin == |
| | 34 | |
| | 35 | The SENSEI Plugin handles BinaryWS interfaces to 6LoWPAN nodes. The plugin automatically collects published resource descriptions from nodes, registers them with HTTP resource access interfaces, and then handles proxy transformations in both directions. |
| | 36 | |
| | 37 | The plugin prepends HTTP resources with /node{ID} where ID is a generated unsigned integer. Thus a resource from a sensor node on URL /s/temp would be published as e.g. /node1/s/temp to the RD. There is a 1-1 mapping between each node{ID} and the IPv6 address of a 6LoWPAN node. |
| | 38 | |
| | 39 | Currently the plugin supports registered incoming RAI requests, the publication of RD links by sensor nodes on /rpi[0], an automatic notification collector on /notify[1] and arbitrary outgoing requests. The automatic caching of requests in planned. |
| | 40 | |
| | 41 | The gateway runs on UDP port 61626 and all nodes on UDP port 61628. |
| | 42 | |
| | 43 | === Built-in Reources === |
| | 44 | |
| | 45 | The plugin registers the following resources for management and testing use: |
| | 46 | |
| | 47 | * /stats - XML output of statistics from the plugin |
| | 48 | * /rd - List of all resource descriptions published by the plugin |
| | 49 | * /localhost/s/temp - Test resource which always requests /s/temp from ::1 (for use with binaryWS_test) |
| | 50 | |
| | 51 | === eRPI Interface === |
| | 52 | |
| | 53 | Nodes publish their resource description to the Gateway upon initialization and periodically (before Expiration-Time). This is sent to the URL /rpi[0] ([0] refers to compressed URL code 0) on the gateway (port 61626). |
| | 54 | |
| | 55 | The gateway stores resource descriptions locally in /xml and supports fetching descriptions from an http:// URL (not yet implemented). Sensor nodes do not send full resource descriptions, but instead only a Document-Link to the description. The body of the bws message POSTed to /rpi must contain the string: |
| 47 | | cd ./lib/Sockets-2.3.6 |
| 48 | | make |
| 49 | | sudo make install |
| | 64 | <!DOCTYPE Resources [ |
| | 65 | <!ENTITY eui64 "Node's EUI64 or IPv6 identifier"> |
| | 66 | <!ENTITY ipaddress "Gateway's HTTPd hostname or IP address"> |
| | 67 | <!ENTITY nodeid "The nodeXX prefix for this node"> |
| | 68 | ]> |
| | 69 | }}} |
| | 70 | |
| | 71 | Example of a resource description template (telosb.xml): |
| | 72 | |
| | 73 | {{{ |
| | 74 | <Resources xsi:noNamespaceSchemaLocation="ResourceDescription.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> |
| | 75 | <Resource-Description> |
| | 76 | <Identifier>urn:telosb:temp:&eui64;</Identifier> |
| | 77 | <Description>Temperature sensor</Description> |
| | 78 | <Rai-Description> |
| | 79 | <URL>http://&ipaddress;/&nodeid;/s/temp</URL> |
| | 80 | <Document-Link>urn:sensei:rai:sensor</Document-Link> |
| | 81 | </Rai-Description> |
| | 82 | <Cacheable>1200</Cacheable> |
| | 83 | </Resource-Description> |
| | 84 | <Resource-Description> |
| | 85 | <Identifier>urn:telosb:light:&eui64;</Identifier> |
| | 86 | <Description>Light sensor</Description> |
| | 87 | <Rai-Description> |
| | 88 | <URL>http://&ipaddress;/&nodeid;/s/light</URL> |
| | 89 | <Document-Link>urn:sensei:rai:sensor</Document-Link> |
| | 90 | </Rai-Description> |
| | 91 | <Cacheable>600</Cacheable> |
| | 92 | </Resource-Description> |
| | 93 | </Resources> |
| | 94 | }}} |
| | 95 | |
| | 96 | The plugin is not (yet) intelligent enough to extract the resource URLs from the XML description. Instead, a file named filename.xml.resources must be provided with each URL from the corresponding description as a line (telosb.xml.resources): |
| | 97 | |
| | 98 | {{{ |
| | 99 | /s/temp |
| | 100 | /s/light |
| 59 | | The following features are currently part of the Gateway development version as of r517. |
| 60 | | |
| 61 | | === Current === |
| 62 | | |
| 63 | | * Gateway: HTTP server with configurable port |
| 64 | | * Gateway: RAI support (GET, POST, PUT, DELETE on registered URLs) |
| 65 | | * Gateway: Resource directory RPI publication support |
| 66 | | * Sensei Plugin: BinaryWS v0.8 |
| 67 | | * Sensei Plugin: eRPI support of Document-Link file:// type |
| 68 | | * Sensei Plugin: file:// resource descriptions read from /xml and DOCTYPE ENTITY block added |
| 69 | | * Sensei Plugin: Automatic node and resource management (unlimited number) |
| 70 | | * Sensei Plugin: Built-in statistics (/stats) and resource description (/rd) resources |
| 71 | | |
| 72 | | === Planned === |
| 73 | | |
| 74 | | * Gateway: Support for TLS |
| 75 | | * Gateway: Support for Sensei AAA |
| 76 | | * Gateway: Logging to a file |
| 77 | | * Gateway: RD RPI delete, update and refresh support |
| 78 | | * Sensei Plugin: Caching support for resources. |
| 79 | | * Sensei Plugin: Support for eRPI Document-Link URLs containing http:// in addition to file:// |
| 80 | | * Sensei Plugin: BinaryWS retransmission support |
| 81 | | * Sensei Plugin: libEXI integration |
| 82 | | * Management Plugin |
| 83 | | * Code Update Plugin |
| 84 | | |
| 85 | | == Plug-in design and how to make a new plug-in == |
| 86 | | |
| 87 | | The gateway uses a modular plug-in design based on the Plugin class and managed by the PluginHandler class. Each Plugin uses the Sockets++ Thread class to automatically run as an independent thread. To create a new Plugin simply copy the /src/plugin-skeleton directory to your own /src/plugin-xxx directory and add includes to the /src Makefile. |
| | 110 | Sensor nodes may send evenets without a subscription to a notification collector on the gateway by POSTing to /notify[1]. The evenet is POSTed to a default event collection service on the SENSEI Management Web-page. The body may be any O&M content or even text/plain. |
| 90 | | |
| | 113 | == Testing the Gateway == |
| | 114 | |
| | 115 | Go to the binaryWS_test tool script directory: |
| | 116 | |
| | 117 | cd ../binaryWS_test/scripts |
| | 118 | |
| | 119 | First register a fake resource description with: |
| | 120 | |
| | 121 | ./rpi_client_publishRD.sh ::1 |
| | 122 | |
| | 123 | You should see the plug-in receive the registration, then the Gateway will do |
| | 124 | an HTTP post automatically to the RD (currently over IPv4 to the RD running on |
| | 125 | the VM in Romania). |
| | 126 | |
| | 127 | Now try an RAI event to the plug-in notification collector: |
| | 128 | |
| | 129 | ./notify.sh ::1 content/temp.rdf_SCHEMA_BYTEALIGNED.exi |
| | 130 | |
| | 131 | You can make an RAI request from the gateway by going to e.g. |
| | 132 | |
| | 133 | http://localhost:8000/localhost/s/temp |
| | 134 | |
| | 135 | == Performance == |
| | 136 | |
| | 137 | The performance of the Gateway is only reasonable buit without HAVE_DEBUG and HAVE_LOGGING are not defined in the Makefile. The debugging messages cause huge delays and even timeouts for requests under high load. |
| | 138 | |
| | 139 | The Gateway is stable under maximum load and has a mean response time of 1.65 ms (Sensei Plugin including BinaryWS to ::1) using the Apache Benchmark tool with arbitrary numbers of concurrent clients. The Gateway core uses a single thread, and therefore does serial handling of requests. |
| | 140 | |
