From 366ad7bece0cd87f75a880f617e157ba2cfeb655 Mon Sep 17 00:00:00 2001 From: adamdunkels Date: Sat, 7 Mar 2009 11:15:46 +0000 Subject: [PATCH] Added Rime documentation from the Rime/Chameleon paper (SenSys 2007) --- core/net/rime/broadcast.h | 11 +++++++++-- core/net/rime/ipolite.h | 38 ++++++++++++++++++++++++++++++++++++-- core/net/rime/multihop.h | 12 +++++++++++- core/net/rime/netflood.h | 19 ++++++++++++++++++- core/net/rime/polite.h | 36 +++++++++++++++++++++++++++++++++++- core/net/rime/runicast.h | 25 +++++++++++++++++++++++-- core/net/rime/stunicast.h | 19 +++++++++++++++++-- core/net/rime/unicast.h | 9 +++++++-- doc/rime-doc.txt | 35 ++++++++++++++++++++++++++++++++++- 9 files changed, 190 insertions(+), 14 deletions(-) diff --git a/core/net/rime/broadcast.h b/core/net/rime/broadcast.h index 03ab4c4c9..1d01191f2 100644 --- a/core/net/rime/broadcast.h +++ b/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 $ */ /** diff --git a/core/net/rime/ipolite.h b/core/net/rime/ipolite.h index 9c39b047a..57da1386d 100644 --- a/core/net/rime/ipolite.h +++ b/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. diff --git a/core/net/rime/multihop.h b/core/net/rime/multihop.h index 884353b0d..fe4b64eb0 100644 --- a/core/net/rime/multihop.h +++ b/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 $ */ /** diff --git a/core/net/rime/netflood.h b/core/net/rime/netflood.h index 6d1576824..eaf14e8c8 100644 --- a/core/net/rime/netflood.h +++ b/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 $ */ /** diff --git a/core/net/rime/polite.h b/core/net/rime/polite.h index 5e557fb09..f9ba9733f 100644 --- a/core/net/rime/polite.h +++ b/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 $ */ /** diff --git a/core/net/rime/runicast.h b/core/net/rime/runicast.h index 369c47965..ab8c4bf17 100644 --- a/core/net/rime/runicast.h +++ b/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 $ */ /** diff --git a/core/net/rime/stunicast.h b/core/net/rime/stunicast.h index dd4790abd..cb9831e36 100644 --- a/core/net/rime/stunicast.h +++ b/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 $ */ /** diff --git a/core/net/rime/unicast.h b/core/net/rime/unicast.h index a74ddd729..2c1ad3c16 100644 --- a/core/net/rime/unicast.h +++ b/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 $ */ /** diff --git a/doc/rime-doc.txt b/doc/rime-doc.txt index 4e4eb64bc..4c155cc33 100644 --- a/doc/rime-doc.txt +++ b/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 + * */ - /** @} */ /** @} */