= 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 ...)

[[PageOutline(2-3,Table of Contents,inline)]]

== Download the Package ==

The SENSEI Native Gateway is available [wiki:NativeGateway-dwl here].

== Requirements ==

 * Linux
 * g++, make
 * [http://www.alhem.net/Sockets/ 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.:

http://localhost:8000/test/1

== 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 /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.