Added Rime documentation from the Rime/Chameleon paper (SenSys 2007)

core/net/rime/broadcast.h

@@ -4,12 +4,19 @@
  */
 
 /**
- * \defgroup rimeibc Identified best-effort local area broadcast
+ * \defgroup rimeibc Best-effort local area broadcast
  * @{
  *
  * The broadcast module sends packets to all local area neighbors with an a
  * header that identifies the sender.
  *
+ * The broadcast module sends a packet to all local neighbors.  The
+ * module adds the single-hop sender address as a packet attribute to
+ * outgoing packets.  All Rime primitives that need the identity of
+ * the sender in the outgoing packets use the broadcast primitive,
+ * either directly or indirectly through any of the other
+ * communication primitives that are based on the broadcast primitive.
+ *
  * \section channels Channels
  *
  * The broadcast module uses 1 channel.
@@ -46,7 +53,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: broadcast.h,v 1.1 2008/06/26 11:19:22 adamdunkels Exp $
+ * $Id: broadcast.h,v 1.2 2009/03/07 11:15:46 adamdunkels Exp $
  */
 
 /**

core/net/rime/ipolite.h

@@ -11,6 +11,40 @@
  * time interval. If a packet with the same header is received from a
  * neighbor within the interval, the packet is not sent.
  *
+ * The polite primitive is a generalization of the polite gossip
+ * algorithm from Trickle (Levis et al, NSDI 2004).  The polite gossip
+ * algorithm is designed to reduce the total amount of packet
+ * transmissions by not repeating a message that other nodes have
+ * already sent.  The purpose of the polite broadcast primitive is to
+ * avoid that multiple copies of a specific set of packet attributes
+ * is sent on a specified logical channel in the local neighborhood
+ * during a time interval.
+ *
+ * The polite broadcast primitive is useful for implementing broadcast
+ * protocols that use, e.g., negative acknowledgements.  If many nodes
+ * need to send the negative acknowledgement to a sender, it is enough
+ * if only a single message is delivered to the sender.
+ *
+ * The upper layer protocol or application that uses the polite
+ * broadcast primitive provides an interval time, and message along
+ * with a list of packet attributes for which multiple copies should
+ * be avoided.  The polite broadcast primitive stores the outgoing
+ * message in a queue buffer, stores the list of packet attributes,
+ * and sets up a timer.  The timer is set to a random time during the
+ * second half of the interval time.
+ *
+ * During the first half of the time interval, the sender listens for
+ * other transmissions.  If it hears a packet that matches the
+ * attributes provided by the upper layer protocol or application, the
+ * sender drops the packet.  The send timer has been set to a random
+ * time some time during the second half of the interval.  When the
+ * timer fires, and the sender has not yet heard a transmission of the
+ * same packet attributes, the sender broadcasts its packet to all its
+ * neighbors.
+ *
+ * The polite broadcast module does not add any packet attributes to
+ * outgoing packets apart from those added by the upper layer.
+ *
  * \section channels Channels
  *
  * The ipolite module uses 1 channel.
@@ -47,7 +81,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: ipolite.h,v 1.6 2009/02/07 16:15:37 adamdunkels Exp $
+ * $Id: ipolite.h,v 1.7 2009/03/07 11:15:46 adamdunkels Exp $
  */
 
 /**
@@ -80,7 +114,7 @@ struct ipolite_callbacks {
   /**
    * Called when a packet is received on the connection.
    */
-  void (* recv)(struct ipolite_conn *c, rimeaddr_t *from); 
+  void (* recv)(struct ipolite_conn *c, rimeaddr_t *from);
 
   /**
    * Called when a packet is sent on the connection.

core/net/rime/multihop.h

@@ -12,6 +12,16 @@
  * up routes is done with another Rime module such as the \ref
  * routediscovery "route-discovery module".
  *
+ * The multihop sends a packet to an identified node in the network by
+ * using multi-hop forwarding at each node in the network.  The
+ * application or protocol that uses the multihop primitive supplies a
+ * routing function for selecting the next-hop neighbor.  If the
+ * multihop primitive is requested to send a packet for which no
+ * suitable next hop neighbor is found, the caller is immediately
+ * notified of this and may choose to initiate a route discovery
+ * process.
+ *
+ *
  * \section channels Channels
  *
  * The multihop module uses 1 channel.
@@ -48,7 +58,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: multihop.h,v 1.2 2009/01/15 22:15:51 adamdunkels Exp $
+ * $Id: multihop.h,v 1.3 2009/03/07 11:15:46 adamdunkels Exp $
  */
 
 /**

core/net/rime/netflood.h

@@ -9,6 +9,23 @@
  *
  * The netflood module does best-effort flooding.
  *
+ * The netflood primitive sends a single packet to all nodes in the
+ * network. The netflood primitive uses polite broadcasts at every hop
+ * to reduce the number of redundant transmissions.  The netflood
+ * primitive does not perform retransmissions of flooded packets and
+ * packets are not tagged with version numbers.  Instead, the netflood
+ * primitive sets the end-to-end sender and end-to-end packet ID
+ * attributes on the packets it sends.  A forwarding node saves the
+ * end-to-end sender and packet ID of the last packet it forwards and
+ * does not forward a packet if it has the same end-to-end sender and
+ * packet ID as the last packet.  This reduces the risk of routing
+ * loops, but does not eliminate them entirely as the netflood
+ * primitive saves the attributes of the latest packet seen only.
+ * Therefore, the netflood primitive also uses the time to live
+ * attribute, which is decreased by one before forwarding a packet.
+ * If the time to live reaches zero, the primitive does not forward
+ * the packet.
+*
  * \section channels Channels
  *
  * The netflood module uses 1 channel.
@@ -45,7 +62,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: netflood.h,v 1.2 2009/01/15 22:15:51 adamdunkels Exp $
+ * $Id: netflood.h,v 1.3 2009/03/07 11:15:46 adamdunkels Exp $
  */
 
 /**

core/net/rime/polite.h

@@ -11,6 +11,40 @@
  * time interval. If a packet with the same header is received from a
  * neighbor within the interval, the packet is not sent.
  *
+ * The polite primitive is a generalization of the polite gossip
+ * algorithm from Trickle (Levis et al, NSDI 2004).  The polite gossip
+ * algorithm is designed to reduce the total amount of packet
+ * transmissions by not repeating a message that other nodes have
+ * already sent.  The purpose of the polite broadcast primitive is to
+ * avoid that multiple copies of a specific set of packet attributes
+ * is sent on a specified logical channel in the local neighborhood
+ * during a time interval.
+ *
+ * The polite broadcast primitive is useful for implementing broadcast
+ * protocols that use, e.g., negative acknowledgements.  If many nodes
+ * need to send the negative acknowledgement to a sender, it is enough
+ * if only a single message is delivered to the sender.
+ *
+ * The upper layer protocol or application that uses the polite
+ * broadcast primitive provides an interval time, and message along
+ * with a list of packet attributes for which multiple copies should
+ * be avoided.  The polite broadcast primitive stores the outgoing
+ * message in a queue buffer, stores the list of packet attributes,
+ * and sets up a timer.  The timer is set to a random time during the
+ * second half of the interval time.
+ *
+ * During the first half of the time interval, the sender listens for
+ * other transmissions.  If it hears a packet that matches the
+ * attributes provided by the upper layer protocol or application, the
+ * sender drops the packet.  The send timer has been set to a random
+ * time some time during the second half of the interval.  When the
+ * timer fires, and the sender has not yet heard a transmission of the
+ * same packet attributes, the sender broadcasts its packet to all its
+ * neighbors.
+ *
+ * The polite broadcast module does not add any packet attributes to
+ * outgoing packets apart from those added by the upper layer.
+ *
  * \section channels Channels
  *
  * The polite module uses 1 channel.
@@ -47,7 +81,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: polite.h,v 1.5 2009/02/07 16:15:37 adamdunkels Exp $
+ * $Id: polite.h,v 1.6 2009/03/07 11:15:46 adamdunkels Exp $
  */
 
 /**

core/net/rime/runicast.h

@@ -7,7 +7,28 @@
  * \defgroup rimerunicast Single-hop reliable unicast
  * @{
  *
- * The runicast module implements a single-hop reliable unicast mechanism.
+ * The reliable single-hop unicast primitive (runicast) reliably sends
+ * a packet to a single-hop neighbor.  The runicast primitive uses
+ * acknowledgements and retransmissions to ensure that the neighbor
+ * successfully receives the packet.  When the receiver has
+ * acknowledged the packet, the ruc module notifies the sending
+ * application via a callback.  The ruc primitive uses the stubborn
+ * single-hop unicast primitive to do retransmissions.  Thus, the ruc
+ * primitive does not have to manage the details of setting up timers
+ * and doing retransmissions, but can concentrate on dealing with
+ * acknowledgements.
+ *
+ * The runicast primitive adds two packet attributes: the single-hop
+ * packet type and the single-hop packet ID.  The runicast primitive
+ * uses the packet ID attribute as a sequence number for matching
+ * acknowledgement packets to the corresponding data packets.
+ *
+ * The application or protocol that uses the runicast primitive can
+ * specify the maximum number of transmissions that the ruc module
+ * should attempt before the packet times out.  If a packet times out,
+ * the application or protocol that sent the packet is notified with a
+ * callback.
+ *
  *
  * \section channels Channels
  *
@@ -45,7 +66,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: runicast.h,v 1.3 2009/03/03 12:19:46 fros4943 Exp $
+ * $Id: runicast.h,v 1.4 2009/03/07 11:15:46 adamdunkels Exp $
  */
 
 /**

core/net/rime/stunicast.h

@@ -7,8 +7,23 @@
  * \defgroup rimestunicast Stubborn unicast
  * @{
  *
- * The stunicast module takes one packet and sends it repetedly.
+ * The stubborn single-hop unicast primitive (stunicast) repeatedly
+ * sends a packet to a single-hop neighbor using the unicast
+ * primitive.  The stunicast primitive sends and resends the packet
+ * until an upper layer primitive or protocol cancels the
+ * transmission.  While it is possible for applications and protocols
+ * that use Rime to use the stubborn single-hop unicast primitive
+ * directly, the stuc primitive is primarily used by the reliable
+ * single-hop unicast (runicast) primitive.
  *
+ * Before the stunicast primitive sends a packet, it allocates a queue
+ * buffer, to which the application data and packet attributes is
+ * copied, and sets a timer.  When the timer expires, the stuc
+ * primitive copies the queue buffer to the Rime buffer and sends the
+ * packet using the uc primitive.  The stuc primitive sets the number
+ * of retransmissions for a packet as a packet attribute on outgoing
+ * packets.
+
  * \section channels Channels
  *
  * The stunicast module uses 1 channel.
@@ -45,7 +60,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: stunicast.h,v 1.1 2008/07/03 21:35:46 adamdunkels Exp $
+ * $Id: stunicast.h,v 1.2 2009/03/07 11:15:46 adamdunkels Exp $
  */
 
 /**

core/net/rime/unicast.h

@@ -7,7 +7,12 @@
  * \defgroup rimeuc Single-hop unicast
  * @{
  *
- * The uc module sends a packet to a single receiver.
+ * The unicast module sends a packet to an identified single-hop
+ * neighbor.  The unicast primitive and adds the single-hop receiver
+ * address attribute to the outgoing packets. For incoming packets,
+ * the unicast module inspects the single-hop receiver address
+ * attribute and discards the packet if the address does not match the
+ * address of the node.
  *
  * \section channels Channels
  *
@@ -45,7 +50,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: unicast.h,v 1.1 2008/06/26 11:19:22 adamdunkels Exp $
+ * $Id: unicast.h,v 1.2 2009/03/07 11:15:46 adamdunkels Exp $
  */
 
 /**

doc/rime-doc.txt

@@ -11,7 +11,40 @@
  * communication primitives ranging from best-effort anonymous local area
  * broadcast to reliable network flooding.
  *
+ * The protocols in the Rime stack are arranged in a layered fashion,
+ * where the more complex protocols are implemented using the less
+ * complex protocols.
+ *
+ * We have chosen the communication primitives in the Rime stack based
+ * on what typical sensor network protocols use. Applications or
+ * protocols running on top of the Rime stack attach at any layer of
+ * the stack and use any of the communication primitives.
+ *
+ * The Rime stack supports both single-hop and multi-hop communication
+ * primitives. The multi-hop primitives do not specify how packets are
+ * routed through the network. Instead, as the packet is sent across
+ * the network, the application or upper layer protocol is invoked at
+ * every node to choose the next-hop neighbor. This makes it possible
+ * to implement arbitrary routing protocols on top of the multi-hop
+ * primitives.
+ *
+ * Protocols or applications running on top of the Rime stack can
+ * implement additional protocols that are not in the Rime stack. If a
+ * protocol or application running on top of the Rime stack would need
+ * a communication primitive that is not currently in the Rime stack,
+ * the application or protocol can implement it directly on top of
+ * other communication primitive in the stack.
+ *
+ * For more information, see:
+ *
+ * Adam Dunkels, Fredrik Österlind, and Zhitao He. An adaptive
+ * communication architecture for wireless sensor networks. In
+ * Proceedings of the Fifth ACM Conference on Networked Embedded
+ * Sensor Systems (SenSys 2007), Sydney, Australia, November 2007.
+ *
+ * http://www.sics.se/~adam/dunkels07adaptive.pdf
+ * http://www.sics.se/~adam/slides/dunkels07adaptive.ppt
+ *
  */
-
 /** @} */
 /** @} */