= Sensei Node Cookbook = 

This document includes a short description and instructions on how to install and run the SENSEI native-island node software on a sample WSN platform (telosb).

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

== Outline == 
SENSEI native nodes include a full IPv6-based protocol stack to demonstrate a sample of future Internet communication. Communication with the SENSEI native-island nodes is available also through standard Internet technologies using the SENSEI Application Level Gateway.


The implementation is based upon a modified version of a TinyOS 6LowPAN module named `6lowpan`.

SENSEI native node stack is composed by:
* Modified `6lowpan` component
* CoAP component, implementing client/server capabilities
* RPI component
* RAI component
* Sensor resources components: Light (Visible and IR), Temperature, Humidity, User button
* System parameter resource component: Battery
* Actuator resources components: various Leds (0,1,2)
* Subscription component: handling RAI resource subscription

'''CoAP''' Module implements a CoAP server and client that are used to communicate
with the rest of the network.
Native node resources receive requests using REST methods ( GET, PUT, POST, DELETE ) and provide responses through the CoAP component/protocol.

'''RPI''' - Resource Publication Interface takes care of node publication on SENSEI upper layers.

'''RAI''' - Resource Access Interface is in charge of handling resource access request, route it to the requested resource component or to the subscription component when a Subscribe message is received. 

'''Resources''' - Each resource offers specific functions based on the REST method involved, directly operate on the lower-level resource, handle data involved in the request (if applicable) and sends a response with the data involved in the exchange.

'''Subscription''' - TODO

{{{

+--------------+   +--------------+
|  Resources   |   | Subscription |
+--------------+   +--------------+
       |         /
+--------------+   +--------------+
|     Rai      |   |      Rpi     |
+--------------+   +--------------+
       |                   |
+--------------+   +--------------+
|  CoAPServer  |---|  CoAPClient  |
+--------------+   +--------------+


}}}


== Installation steps: Ubuntu 10.04==
=== Setup TinyOS ===
To install the software on telosb motes need a tinyOS 2.1 working copy
see: http://www.tinyos.net for informations on tinyOS installation.

Add the following line to /etc/apt/sources.list
{{{
deb http://tinyos.stanford.edu/tinyos/dists/ubuntu lucid main
}}}
{{{
sudo apt-get update
sudo apt-get install tinyos-2.1.1
sudo apt-get install subversion
}}}
Set up your .bashrc variables to enable tinyos compilation toolchain:
{{{
# add the following lines at the end of the file
source /opt/tinyos-2.1.1/tinyos.sh
CLASSPATH=$TOSROOT/support/sdk/java/tinyos.jar:.
}}}


{{{
#!comment
In this example tos is installed in $HOME/tos
export TOSROOT=$HOME/tos
export TOSDIR=$TOSROOT/tos
export CLASSPATH=$TOSROOT/support/sdk/java/tinyos.jar:$TOSROOT/support/sdk/java/
export MAKERULES=$TOSROOT/support/make/Makerules
export PATH=$PATH:/opt/msp430/bin
}}}

To use tinyOS's java utilities you need sun java6:
enable PARTNER repository: menu->system->administration->Software sources

install java6
{{{
sudo apt-get install sun-java6-jdk

# setting sun-java as default java provider
sudo update-alternatives --set java /usr/lib/jvm/java-6-sun/jre/bin/java
sudo update-alternatives --set javac /usr/lib/jvm/java-6-sun/bin/javac
#
sudo tos-install-jni
}}}


=== Install SENSEI software ===
To test the software you will need 3 things:
* one or many nodes equipped with node-tinyos software
* a program called "gateway" that needs to be running on a local machine
* a bridge program that connects your sensei node with your local machine using another mote compiled with BaseStation App

TODO: insert picture here?


You can checkout a copy of this software at:
{{{
$ svn --username [username]  co https://svn-batch.grid.pub.ro/svn/Sensei-WP5/

[The above command if ask for some security certificate exchange; Accept it [yes]]
[otherwise it prompt for the password for svn access]
Enter your password.
}}}

==== Compile and install the bridge ====
{{{
# you have to be root to do this
sudo -i
# you need tinyos paths for a short while
source /opt/tinyos-2.1.1/tinyos.sh
apt-get install build-essential automake
cd /opt/tinyos-2.1.1/support/sdk/c/sf/
./bootstrap
./configure
make
cd /opt/tinyos-2.1.1/support/sdk/c/6lowpan/serial_tun/
make
exit
}}}

now you should have a working copy of "serial_tun" 

==== Compile SENSEI gateway ====
The steps to compile the gateway are quite straightforward
{{{
# move to gateway folder

cd Sensei-WP5/gateway/
sudo apt-get install g++ libssl-dev libxml2-dev

# Install socket++ library
gateway$ cd lib/Socket-2.3.7
gateway/lib/Sockets-2.3.7$ make clean
gateway/lib/Sockets-2.3.7$ make 
gateway/lib/Sockets-2.3.7$ sudo make install

# compile the gateway
gateway/lib/Sockets-2.3.7$ cd ../../
gateway$ make
}}}

== Usage: ==
=== Launch the bridge ===
To test the software you have to equip a node with BaseStation App that can be found in:
{{{
Sensei-WP5$ cd node-tinyos/BaseStation
Sensei-WP5/node-tinyos/BaseStation$  make telosb install.0 bsl,/dev/ttyUSB0
}}}
Now you can create the Bridge
{{{
$ sudo /opt/tinyos-2.1.1/support/sdk/c/6lowpan/serial_tun/serial_tun /dev/ttyUSB0 telosb
}}}

=== Start the Gateway ===
To start the SENSEI gateway you have to:
{{{
Sensei-WP5$ cd gateway
# start the gateway
Sensei-WP5/gateway$ ./bin/sensei-gateway
}}}

=== Compile SENSEI tinyOS-node ===
To compile and install the node App on as many nodes as you like:
{{{
Sensei-WP5$ cd node-tinyos/node
Sensei-WP5/node-tinyos/node$ make install.NODE_ADDRESS bsl,NODE_USB_DEVICE
}}}

=== Test It! ===
If nothing went wrong you can visit
http://localhost:8000 
to see the list of available nodes
==== GET request example ====
To get the temperature from a node just visit the corresponding url:
http://localhost:8000/0000-0000-fffe-0005/s/temp

==== PUT request example ====
Using the PUT HTTP/CoAP method you can actuate on mote's leds.

If you send a PUT request to a node 
using for example http://localhost:8000/0000-0000-fffe-0005/a/led0

And using this XML in the request body
{{{
#!xml
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:res="urn:sensei:rai">
  <res:LED rdf:about="0" res:hasBooleanValue=1/>
</rdf:RDF>
}}}

This will turn led0 On

==== POST request example ====
To test the Subscription Module you have to issue a post request to a resource url 
(i.e.  http://localhost:8000/0000-0000-fffe-0005/s/temp )
with a body that similar to this one:
{{{ 
!xml
<?xml version="1.0" encoding="UTF-8"?>
<sub:Subscription xmlns:sub="subscription">
        <sub:URL>http://where_you_want_to_recieve_requests</sub:URL>
        <sub:ID>0</sub:ID>
        <sub:Period>time_in_milliseconds</sub:Period>
        <sub:OnlyOnChange>0</sub:OnlyOnChange>
</sub:Subscription>
}}}

The node will recieve the request and answer with a 200 OK status code.

Later after "Period" milliseconds it will start to send post request tu "URL" 
with an xml like this one in the body:
{{{
#!xml
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:res="urn:sensei:rai">
  <res:Temperature rdf:about="0" res:hasDecimalValue="VALUE"/>
</rdf:RDF>
}}}

With a period of "Period" the node issues an internal get request to the resource recieved in the post request and than forwards the response body into a new request (XXX  ok. this HAS to be rewrite )