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

This commit is contained in:
adamdunkels 2009-03-07 11:15:46 +00:00
parent 4519f07a9b
commit 366ad7bece
9 changed files with 190 additions and 14 deletions

View file

@ -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 * The broadcast module sends packets to all local area neighbors with an a
* header that identifies the sender. * 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 * \section channels Channels
* *
* The broadcast module uses 1 channel. * The broadcast module uses 1 channel.
@ -46,7 +53,7 @@
* *
* This file is part of the Contiki operating system. * 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 $
*/ */
/** /**

View file

@ -11,6 +11,40 @@
* time interval. If a packet with the same header is received from a * time interval. If a packet with the same header is received from a
* neighbor within the interval, the packet is not sent. * 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 * \section channels Channels
* *
* The ipolite module uses 1 channel. * The ipolite module uses 1 channel.
@ -47,7 +81,7 @@
* *
* This file is part of the Contiki operating system. * 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. * 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. * Called when a packet is sent on the connection.

View file

@ -12,6 +12,16 @@
* up routes is done with another Rime module such as the \ref * up routes is done with another Rime module such as the \ref
* routediscovery "route-discovery module". * 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 * \section channels Channels
* *
* The multihop module uses 1 channel. * The multihop module uses 1 channel.
@ -48,7 +58,7 @@
* *
* This file is part of the Contiki operating system. * 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 $
*/ */
/** /**

View file

@ -9,6 +9,23 @@
* *
* The netflood module does best-effort flooding. * 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 * \section channels Channels
* *
* The netflood module uses 1 channel. * The netflood module uses 1 channel.
@ -45,7 +62,7 @@
* *
* This file is part of the Contiki operating system. * 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 $
*/ */
/** /**

View file

@ -11,6 +11,40 @@
* time interval. If a packet with the same header is received from a * time interval. If a packet with the same header is received from a
* neighbor within the interval, the packet is not sent. * 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 * \section channels Channels
* *
* The polite module uses 1 channel. * The polite module uses 1 channel.
@ -47,7 +81,7 @@
* *
* This file is part of the Contiki operating system. * 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 $
*/ */
/** /**

View file

@ -7,7 +7,28 @@
* \defgroup rimerunicast Single-hop reliable unicast * \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 * \section channels Channels
* *
@ -45,7 +66,7 @@
* *
* This file is part of the Contiki operating system. * 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 $
*/ */
/** /**

View file

@ -7,8 +7,23 @@
* \defgroup rimestunicast Stubborn unicast * \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 * \section channels Channels
* *
* The stunicast module uses 1 channel. * The stunicast module uses 1 channel.
@ -45,7 +60,7 @@
* *
* This file is part of the Contiki operating system. * 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 $
*/ */
/** /**

View file

@ -7,7 +7,12 @@
* \defgroup rimeuc Single-hop unicast * \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 * \section channels Channels
* *
@ -45,7 +50,7 @@
* *
* This file is part of the Contiki operating system. * 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 $
*/ */
/** /**

View file

@ -11,7 +11,40 @@
* communication primitives ranging from best-effort anonymous local area * communication primitives ranging from best-effort anonymous local area
* broadcast to reliable network flooding. * 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
*
*/ */
/** @} */ /** @} */
/** @} */ /** @} */