[Tinyos-2-commits] CVS: tinyos-2.x/doc/html/tutorial lesson12.html, NONE, 1.1.2.1

Fri Nov 3 08:54:30 PST 2006

Update of /cvsroot/tinyos/tinyos-2.x/doc/html/tutorial
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv14653

Added Files:
      Tag: tinyos-2_0_devel-BRANCH
	lesson12.html 
Log Message:
Checking in lesson 12, by Guillermo Barrenetxea (who doesn't have write access)

--- NEW FILE: lesson12.html ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>TinyOS Tutorial Lesson 12: Network Protocols</title>
  <link href="../../stylesheets/tutorial.css" rel="stylesheet"
 type="text/css">
</head>
<body>
<div class="title">Lesson 12: Network Protocols<br>
</div>
<div class="subtitle">Last updated Nov 3 2006</div>
<p>This lesson introduces the two basic network primitives of Tinyos-2:
Dissemination and Collection.<br>
</p>
<h1>Dissemination<br>
</h1>
<p>The goal of a dissemination protocol is to reliably deliver a piece of data to every
node in the network. It allows administrators
to reconfigure, query, and reprogram a network. Reliability is
important because it makes the operation robust to temporary
disconnections or high packet loss.&nbsp; Dissemination is&nbsp; fully
explained in TEP 118.<br>
</p>
<p>In TinyOS 2.x, dissemination provides two interfaces: DisseminationValue and
DisseminationUpdate. Let's take a look at these two interfaces:<br>
</p>

<p>tos/lib/net/DisseminationUpdate.nc:<br>
</p>
<pre>interface DisseminationUpdate&lt;t&gt; {<br>  command void change(t* newVal);<br>}</pre>

<p>tos/lib/net/DisseminationValue.nc:<br>
</p>
<pre>interface DisseminationValue&lt;t&gt; {<br>  command const t* get();<br>  event void changed();<br>}</pre>
<span style="font-family: monospace;"></span>

DisseminationUpdate is used by producers. The command DisseminationUpdate.change() should be
called each time the producer wants to disseminate a new value, passing this
 new value as a parameter. 
DisseminationValue is for consumers. The event DisseminationValue.changed() is
signalled each time the disseminated value is changed (the producer has
called change),
and the command get allows to obtain this new
value. 

We build now a simple application (EasyDissemination) where one node
(the producer) periodically disseminates the value of a counter to rest
of the nodes in the network (consumers).
As a first step, c<code></code>reate a new directory in <tt>apps</tt>
named EasyDissemination:
<pre>$ cd tinyos-2.x/apps $ mkdir EasyDissemination </pre>
Inside this directory, create a file <code>EasyDisseminationC.nc</code>,
which
has this code:
<pre>#include &lt;Timer.h&gt; module EasyDisseminationC { uses interface Boot; uses interface DisseminationValue&lt;uint16_t&gt; as Value; uses interface DisseminationUpdate&lt;uint16_t&gt; as Update; uses interface Leds; uses interface Timer&lt;TMilli&gt;; } implementation { uint16_t counter; task void ShowCounter() { if (counter &amp; 0x1) call Leds.led0On(); else call Leds.led0Off(); if (counter &amp; 0x2) call Leds.led1On(); else call Leds.led1Off(); if (counter &amp; 0x4) call Leds.led2On(); else call Leds.led2Off(); } event void Boot.booted() { counter = 0; if ( TOS_NODE_ID == 1 ) call Timer.startPeriodic(2000); } event void Timer.fired() { counter = counter + 1; // show counter in leds post ShowCounter(); // disseminate counter value call Update.change(&amp;counter); } event void Value.changed() { const uint16_t* newVal = call Value.get(); // show new counter in leds counter = *newVal; post ShowCounter(); } } </pre>
We assume that the&nbsp; base station is the node with ID = 1. First
note that the base station will periodically (every 2 seconds)
increment a 3-bit counter, display the counter using its three leds,&nbsp; and disseminate it
through the network. This is done using the change command provided in
the DisseminationUpdate interface: 
<pre> call Update.change(&amp;counter);</pre>
Second, note that when a node receives a change notification, it
updates its counter value and shows it on the leds: 
<pre> event void Value.changed() { const uint16_t* newVal = call Value.get(); // show new counter in leds counter = *newVal; post ShowCounter(); } </pre>
The <code>EasyDisseminationAppC.nc</code>
provides the needed wiring:
<pre>configuration EasyDisseminationAppC {} implementation { components EasyDisseminationC; components MainC; EasyDisseminationC.Boot -&gt; MainC; components new DisseminatorC(uint16_t, 0x1234) as Diss16C; EasyDisseminationC.Value -&gt; Diss16C; EasyDisseminationC.Update -&gt; Diss16C; components LedsC; EasyDisseminationC.Leds -&gt; LedsC; components new TimerMilliC(); EasyDisseminationC.Timer -&gt; TimerMilliC; } </pre>
Note that both Dissemination interfaces we use are provided by the
module DisseminatorC. 
This module provides&nbsp; the Dissemination service: 

tos/lib/net/Dissemination/DisseminationC.nc:
<prehead></prehead>
<pre> generic configuration DisseminatorC(typedef t, uint16_t key) { provides interface DisseminationValue&lt;t&gt;; provides interface DisseminationUpdate&lt;t&gt;; } </pre>
Note that we need to specify to the Disseminartor module a type t and a
key.&nbsp; In our case, the value we&nbsp; want to&nbsp; disseminate is
just an unsigned&nbsp; two-byte counter. The key allows to have
different instances of DisseminatroC. 
 
To compile this program we use create the following Makefile: 
<pre>COMPONENT=EasyDisseminationAppC CFLAGS += -I$(TOSDIR)/lib/net include $(MAKERULES) </pre>
Now install this program into several nodes (make sure you have one
base station, that is, one node whose ID is 1) and see how the counter
displayed in the base station is "disseminated" to all the nodes
belonging to the network. You will also notice that dissemination works across
resets, i.e., if you reset a node it will rapidly re-'synchronize' and display
the correct value after it reboots.
 
 
For more information, read TEP118 [Dissemination]. 
 
<h1>Collection 
</h1>
Collection is the complementary operation to disseminating and it
consists in "collecting" the data generated in the network into a base
stations. The general approach used is to build one
or more collection trees, each of which is rooted at a base
station. When a node has data which needs to be collected, it
sends the data up the tree, and it forwards collection data that
other nodes send to it. 

We build now a simple application (EasyCollection) where nodes
periodically send information to a base station which collects all the
data. 
As a first step, c<code></code>reate a new directory in <tt>apps</tt>
named EasyCollection:

<pre>$ cd tinyos-2.x/apps $ mkdir EasyCollection </pre>
Inside this directory, create a file <code>EasyCollectionC.nc</code>,
which
has the following code:
<pre>#include &lt;Timer.h&gt; module EasyCollectionC { uses interface Boot; uses interface SplitControl as RadioControl; uses interface StdControl as RoutingControl; uses interface Send; uses interface Leds; uses interface Timer&lt;TMilli&gt;; uses interface RootControl; uses interface Receive; } implementation { message_t packet; bool sendBusy = FALSE; typedef nx_struct EasyCollectionMsg { nx_uint16_t data; } EasyCollectionMsg; event void Boot.booted() { call RadioControl.start(); } event void RadioControl.startDone(error_t err) { if (err != SUCCESS) call RadioControl.start(); else { call RoutingControl.start(); if (TOS_NODE_ID == 1) 	call RootControl.setRoot(); else 	call Timer.startPeriodic(2000); } } event void RadioControl.stopDone(error_t err) {} void sendMessage() { EasyCollectionMsg* msg = (EasyCollectionMsg*)call Send.getPayload(&amp;packet); msg-&gt;data = 0xAAAA; if (call Send.send(&amp;packet, sizeof(EasyCollectionMsg)) != SUCCESS) call Leds.led0On(); else sendBusy = TRUE; } event void Timer.fired() { call Leds.led2Toggle(); if (!sendBusy) sendMessage(); } event void Send.sendDone(message_t* m, error_t err) { if (err != SUCCESS) call Leds.led0On(); sendBusy = FALSE; } event message_t* Receive.receive(message_t* msg, void* payload, uint8_t len) { call Leds.led1Toggle(); return msg; } } </pre>
&nbsp;Lets take a look at this program. First note that all nodes
turn on the radio into the Boot sequence: 


<pre>&nbsp; event void Boot.booted() { &nbsp;&nbsp;&nbsp; call RadioControl.start(); &nbsp; }</pre>
Once we are sure that the radio is on, we start the routing sub-system
(that
is, to generate the collection tree): 

<pre>call RoutingControl.start();</pre>
Next we need need to specify the root of the collection tree, that is,
the node that will receive all the data packets. For this, we use the
interface RootControl: 
tos/lib/net/RootControl.nc 
<pre>interface RootControl { command error_t setRoot(); command error_t unsetRoot(); command bool isRoot(); } </pre>
This interface controls whether the current node is a root of the
tree. Using the setRoot() command and assuming that the base station ID
is 1, we select the root of the collection tree as follows: 

<pre>if (TOS_NODE_ID == 1) &nbsp;&nbsp;&nbsp; call RootControl.setRoot(); else call Timer.startPeriodic(2000);</pre>
The remaining nodes in the network periodically generate some data
and send it to the base station.&nbsp; To send and receive data we use
two interfaces that will be wired to the collection tree. That is, when
we call the send command, the data packet will be sent through the
collection tree.&nbsp; Similarly, the receive event will be only called
in the root of the tree, that is, in the base station. When the base
station receives a "collected" packet it just toggle a led.&nbsp; Now
we will see how to wire these interfaces . 
The <code>EasyCollectionAppC.nc</code>
provides the needed wiring: 

<pre>configuration EasyCollectionAppC {} implementation { components EasyCollectionC, MainC, LedsC, ActiveMessageC; components CollectionC as Collector; components new CollectionSenderC(0xee); components new TimerMilliC(); EasyCollectionC.Boot -&gt; MainC; EasyCollectionC.RadioControl -&gt; ActiveMessageC; EasyCollectionC.RoutingControl -&gt; Collector; EasyCollectionC.Leds -&gt; LedsC; EasyCollectionC.Timer -&gt; TimerMilliC; EasyCollectionC.Send -&gt; CollectionSenderC; EasyCollectionC.RootControl -&gt; Collector; EasyCollectionC.Receive -&gt; Collector.Receive[0xee]; } </pre>
Most of the collection interfaces (RoutingControl, RootControl and
Receive) are provided by the CollectionC module.&nbsp; The send
interface is provided by CollectionSenderC which is
a&nbsp; virtualized collection sender abstraction module. 
This is an extract of the signature of the CollectionC module and
CollectionSenderC: 
tos/lib/net/ctp/CollectionC.nc 

<pre>configuration CollectionC { provides { interface StdControl; interface Send[uint8_t client]; interface Receive[collection_id_t id]; interface Receive as Snoop[collection_id_t]; interface Intercept[collection_id_t id]; interface Packet; interface CollectionPacket; interface CtpPacket; interface CtpInfo; interface CtpCongestion; interface RootControl; } </pre>
tos/lib/net/ctp/CollectionSenderC: 

<pre> generic configuration CollectionSenderC(collection_id_t collectid) { &nbsp; provides { &nbsp;&nbsp;&nbsp; interface Send; &nbsp;&nbsp;&nbsp; interface Packet; &nbsp; }</pre>
Note that the sender and receive interfaces requires a
collection_id_t to differentiate different possible collections trees. 
Note also that the CollectionC module provides some other
interfaces in addition to the ones used in this example. As we explained
previously, the CollectionC module generates a collection tree that
will be using for
the routing. These interfaces can be used get information or modify
this routing tree. For instance, if we want to obtain information about
this tree we use
the CtpInfo interface&nbsp; (see tos/lib/net/ctp/CtpInfo.nc) and if we
want to indicate/query if any node/sink is congested we use the
CtpCongestion interface (see tos/lib/net/ctp/CtpCongestion.nc) 

Finally, to compile this program we create the following
Makefile: 

<pre>COMPONENT=EasyCollectionAppC CFLAGS += -I$(TOSDIR)/lib/net \ -I$(TOSDIR)/lib/net/le \ -I$(TOSDIR)/lib/net/ctp include $(MAKERULES) </pre>
Now install this program into several nodes (make sure you have one
base station, that is, one node whose ID is 1) and see how all the
packets generated in the nodes are collected in the base station. 
 
For more information, read TEP119&nbsp; [Collection]. 
 
<h1>To experiment further 
</h1>
If you want to experiment with a more complex application take a look
at apps/test/TestNetwork/ which combines dissemination and collection
into a single application. 
 
<h1>Related Documentation</h1>
<ul>
 <li><a href="../tep108.html">TEP 118: Dissemination</a></li>
 <li><a href="../tep119.html">TEP 119: Collection</a> 
 </li>
</ul>


<hr> 
<center>
&lt;&nbsp;<a href="lesson1.html">Previous Lesson</a> |&nbsp; <a
 href="index.html">Top</a> &nbsp;|&nbsp; <a href="lesson3.html">Next
Lesson </a>&nbsp;&gt;

</center>
</body>
</html>