Gateway User Guide
The SENSEI Gateway is a Linux daemon which acts as a resource proxy between the SENSEI System and one or more WSAN Islands. This guide shows how to use, configure and test the Gateway. In addition to its own resources offered by the management and code update plugins, the Gateway acts as a resource proxy between embedded resources offered by WSAN nodes running the CoAP protocol and eRAI/eRPI interfaces and full HTTP RAI/RPI to the SENSEI System.
SENSEI System (RU, RD) <----http://nodeX/-----> SENSEI Gateway <------coap://-----> WSAN Island (node1, node2 ...)
Table of Contents
- Download the Package
- Requirements
- How to build it
- Running the Gateway
- Configuration
- Sensei Plugin
- Performance
Download the Package
The SENSEI Native Gateway is available here.
Requirements
- Linux
- g++, make
- Sockets C++ library (Also included in lib/Sockets-2.3.7; make; make install)
- IPv6 support (for local UDP/IPv6 communications)
- libxml2
- openssl, openssl-dev
How to build it
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.
make ./bin/sensei-executable
To clean everything do
make clean
To build the Sockets++ library
cd ./lib/Sockets-2.3.7 make sudo make install
Running the Gateway
The gateway must be run from the root of the project
./bin/sensei-gateway
Command line options: -p HTTPD port (default 8000) -s HTTPD hostname for inserting in resource desciptions as &ipaddress (default localhost)
The SENSEI HTTP server runs by default on port 8000. Just browse http://localhost:8000 to test it. After resources are registered you can test a GET with you browser for the registered URL by e.g.:
Configuration
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.
Sensei Plugin
The SENSEI Plugin handles CoAP 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.
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.
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.
The gateway runs on UDP port 61626 and all nodes on UDP port 61628.
Built-in Reources
The plugin registers the following resources for management and testing use:
- /stats - XML output of statistics from the plugin
- /rd - List of all resource descriptions published by the plugin
- /localhost/s/temp - Test resource which always requests /s/temp from ::1
eRPI Interface
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).
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 CoAP message POSTed to /rpi must contain the string:
file://filename.xml
where filename.xml is a valid resource description without the <xml> and DOCTYPE ENTITY blocks. See /xml/telosb.xml as an example. The following DOCTYPE ENTITY variables are automatically added by the gateway to individualize the resource description template:
<!DOCTYPE Resources [ <!ENTITY eui64 "Node's EUI64 or IPv6 identifier"> <!ENTITY ipaddress "Gateway's HTTPd hostname or IP address"> <!ENTITY nodeid "The nodeXX prefix for this node"> ]>
Example of a resource description template (telosb.xml):
<Resources xsi:noNamespaceSchemaLocation="ResourceDescription.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Resource-Description> <Identifier>urn:telosb:temp:&eui64;</Identifier> <Description>Temperature sensor</Description> <Rai-Description> <URL>http://&ipaddress;/&nodeid;/s/temp</URL> <Document-Link>urn:sensei:rai:sensor</Document-Link> </Rai-Description> <Cacheable>1200</Cacheable> </Resource-Description> <Resource-Description> <Identifier>urn:telosb:light:&eui64;</Identifier> <Description>Light sensor</Description> <Rai-Description> <URL>http://&ipaddress;/&nodeid;/s/light</URL> <Document-Link>urn:sensei:rai:sensor</Document-Link> </Rai-Description> <Cacheable>600</Cacheable> </Resource-Description> </Resources>
The plugin is not 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):
/s/temp /s/light
eRAI Interface
Requests coming from the RAI interface are matched with registered URLs (registered from resource descriptions sent by nodes), and then as CoAP requests to the corresponding WSAN node and URL. The response is returned to the resource user. When caching is implemented a cache for each resource will be checked first before making a CoAP request.
Sensor nodes may also make CoAP requests outside the WSAN island (proxied to HTTP) by including a full FQDN URL (www.example.com/test) in the URL field of the CoAP request header. This feature is not yet supported.
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.
Performance
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.
The Gateway is stable under maximum load and has a mean response time of 1.65 ms (Sensei Plugin including CoAP 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.
