--- /dev/null
+===================================
+CC2420 Radio Stack
+===================================
+
+:TEP: 126
+:Group: Core Working Group
+:Type: Documentary
+:Status: Draft
+:TinyOS-Version: 2.x
+:Author: David Moss, Jonathan Hui, Philip Levis, and Jung Il Choi
+
+:Draft-Created: 5-Mar-2007
+:Draft-Version: $Revision$
+:Draft-Modified: $Date$
+:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
+
+.. Note::
+
+ This memo documents a part of TinyOS for the TinyOS Community, and
+ requests discussion and suggestions for improvements. Distribution
+ of this memo is unlimited. This memo is in full compliance with
+ TEP 1.
+
+
+Abstract
+====================================================================
+
+This TEP documents the architecture of the CC2420 low power listening
+radio stack found in TinyOS 2.x. Radio stack layers and implementation
+details of the CC2420 stack will be discussed. Readers will be better
+informed about existing features, possible improvements, and limitations
+of the CC2420 radio stack. Furthermore, lessons learned from
+the construction of the CC2420 radio stack can help guide development
+of future TinyOS radio stacks.
+
+
+1. Introduction
+====================================================================
+
+The TI/Chipcon CC2420 radio is a complex device, requiring a rather
+complex software radio stack implementation. Although much of the
+functionality is available within the radio chip itself, there are
+still many factors to consider when implementing a flexible,
+general radio stack.
+
+The software radio stack that drives the CC2420 radio consists of
+many layers that sit between the application and hardware. The highest
+levels of the radio stack modify data and headers in each packet, while
+the lowest levels determine the actual send and receive behavior.
+By understanding the functionality at each layer of the stack, as well
+as the architecture of a layer itself, it is possible to easily extend
+or condense the CC2420 radio stack to meet project requirements.
+
+Some details about the CC2420 are out of the scope of this document.
+These details can be found in the CC2420 datasheet [1]_.
+
+
+2. CC2420 Radio Stack Layers
+====================================================================
+
+2.1 Layer Architecture
+--------------------------------------------------------------------
+
+The CC2420 radio stack consists of layers of functionality stacked
+on top of each other to provide a complete mechanism that
+modifies, filters, transmits, and controls inbound and outbound messages.
+Each layer is a distinct module that can provide and use three sets of
+interfaces in relation to the actual radio stack: Send, Receive, and
+SplitControl. If a general layer provides one of those interfaces, it
+also uses that interface from the layer below it in the stack. This
+allows any given layer to be inserted anywhere in the stack through
+independant wiring. For example:::
+
+ provides interface Send;
+ uses interface Send as SubSend;
+
+ provides interface Receive;
+ uses interface Receive as SubReceive;
+
+ provides interface SplitControl;
+ uses interface SplitControl as subControl;
+
+The actual wiring of the CC2420 radio stack is done at the highest level
+of the stack, inside CC2420ActiveMessageC. This configuration defines
+three branches: Send, Receive, and SplitControl. Note that not all
+layers need to provide and use all three Send, Receive, and SplitControl
+interfaces:::
+
+ // SplitControl Layers
+ SplitControl = LplC;
+ LplC.SubControl -> CsmaC;
+
+ // Send Layers
+ AM.SubSend -> UniqueSendC;
+ UniqueSendC.SubSend -> TransportC;
+ TransportC.SubSend -> LplC.Send;
+ LplC.SubSend -> CC2420DispatchC.Send;
+ CC2420DispatchC.SubSend -> CsmaC;
+
+ // Receive Layers
+ AM.SubReceive -> LplC;
+ LplC.SubReceive -> UniqueReceiveC;
+ UniqueReceiveC.SubReceive -> CC2420DispatchC.Receive;
+ CC2420DispatchC.SubReceive -> CsmaC;
+
+If another layer were to be added, CC2420ActiveMessageC would need
+to be modified to wire it into the correct location.
+
+
+2.1 Layer Descriptions
+--------------------------------------------------------------------
+The main layers we see in this version of the stack are:
+
+- ActiveMessageP: This is the highest layer in the stack, responsible
+ for filling in details in the packet header and providing information
+ about the packet to the application level [2]_. Because the CC2420 radio
+ chip itself uses 802.15.4 headers in hardware [1]_, it is not possible
+ for the layer to rearrange header bytes.
+
+- UniqueSend: This layer generates a unique data sequence
+ number (DSN) byte for the packet header. This byte is generated once
+ per outgoing packet. A receiver can detect duplicate packets by comparing
+ the source and DSN byte of a received packet with previous packets.
+ DSN is defined in the 802.15.4 specification [3]_.
+
+- MessageTransportP: This layer provides the MessageTransport
+ interface, and is responsible for retrying a packet transmission if no
+ acknowledgement was heard from the receiver. MessageTransport is
+ activated on a per-message basis, meaning the outgoing packet will
+ not use MessageTransport unless it is configured ahead of time to do so.
+ MessageTransport is most reliable when software acknowledgements are enabled,
+ as opposed to hardware auto acknowledgements.
+
+- LowPowerListeningP [4]_: This layer provides the asynchronous low
+ power listening functionality of the radio. It is broken up into
+ two parts: CC2420LowPowerListeningP and CC2420DutyCycleP. The
+ DutyCycleP component is responsible for turning the radio on
+ and off and performing detections. After a detection occurs,
+ DutyCycleP is hands off responsibility to LowPowerListeningP to turn
+ the radio off and continue duty cycling when convenient. Low power listening
+ transmissions are activated on a per-message basis, and the layer
+ will retransmit the full outbound packet over and over until either a
+ response from the receiver is heard or the transmit time expires.
+
+- UniqueReceive: This layer maintains a history of the source address
+ and DSN byte of the past few packets it has received, and helps
+ filter out duplicate received packets.
+
+- DispatchC: This layer allows the TinyOS 2.x radio stack to interoperate
+ with other non-TinyOS networks. The 6LowPAN specifications include
+ a network identifier byte after the standard 802.15.4 header [5]_.
+ If interoperability frames are used, the dispatch layer provides
+ functionality for setting the network byte on outgoing packets
+ and filtering non-TinyOS incoming packets.
+
+- CsmaC: This layer is responsible for defining 802.15.4 FCF
+ byte information in the outbound packet, providing default
+ backoff times when the radio detects a channel in use, and
+ defining the power-up/power-down procedure for the radio.
+
+- TransmitP/ReceiveP: These layers are responsible for interacting
+ directly with the radio through the SPI bus, interrupts, and GPIO lines.
+
+
+3. CC2420 Packet Format and Specifications
+====================================================================
+
+The CC2420 Packet structure is defined in CC2420.h. The default
+I-Frame CC2420 header takes on the following format:::
+
+ typedef nx_struct cc2420_header_t {
+ nxle_uint8_t length;
+ nxle_uint16_t fcf;
+ nxle_uint8_t dsn;
+ nxle_uint16_t destpan;
+ nxle_uint16_t dest;
+ nxle_uint16_t src;
+ nxle_uint8_t network;
+ nxle_uint8_t type;
+ } cc2420_header_t;
+
+All fields up to 'network' are 802.15.4 specified fields, and are
+used in the CC2420 hardware itself. The 'network' field is a 6LowPAN
+interoperability specification [5]_. The 'type' field is a
+TinyOS specific field.
+
+The TinyOS T-Frame packet does not include the 'network' field, nor
+the functionality found in the Dispatch layer to set and check
+the 'network' field.
+
+No software footer is defined for the CC2420 radio. A 2-byte
+CRC byte is auto-appended to each outbound packet by the CC2420 radio
+hardware itself.
+
+The CC2420 hardware has three RAM buffers: TXFIFO, RXFIFO, and a
+security RAM buffer. The TXFIFO and RXFIFO are both 128 bytes,
+while the security RAM buffer is 112 bytes. Therefore, the maximum size
+of a packet is 128 bytes including its headers and CRC. Increasing
+the packet size will increase data throughput and RAM consumption
+in the TinyOS application, but will also increase the probability
+that interference will cause the packet to be destroyed and need
+to be retransmitted, which wastes energy. The TOSH_DATA_LENGTH
+preprocessor variable can be altered to increase the size
+of the message_t payload at compile time [2]_.
+
+
+4. CSMA/CA
+====================================================================
+
+4.1 Clear Channel Assessment
+--------------------------------------------------------------------
+By default, the CC2420 radio stack performs a clear channel assessment
+(CCA) before transmitting. If the channel is not clear, the radio backs
+off for some short, random period of time before attempting to transmit
+again. The CC2420 chip itself provides a strobe command to transmit
+the packet if the channel is currently clear.
+
+To specify whether or not to transmit with clear channel assessment,
+the CC2420TransmitP component provides two commands::
+
+ async command error_t Send.sendCCA( message_t* p_msg )
+ async command error_t Send.send( message_t* p_msg )
+
+It is up to the CC2420CsmaP component to select the correct method of
+transmission. Sending a packet without CCA will transmit it as quickly
+as possible, but interference from other transmitters will prevent
+it from being delivered in many cases. Transmitting without CCA will
+also effectively jam other DSSS transmitters on the same channel.
+
+Future implementations should allow the application layer to specify
+the use of CCA on a per-packet basis, similar to how the application
+layer has the option to specify the backoff period for an outgoing
+message.
+
+
+4.2 Radio Backoff
+--------------------------------------------------------------------
+A backoff is a period of time where the radio pauses before attempting
+to transmit. When the radio needs to backoff, it can choose one of three
+backoff periods: initialBackoff, congestionBackoff, and lplBackoff.
+These are implemented through the RadioBackoff interface, which signals
+out a request to specify the backoff period. Unlike the CsmaBackoff
+interface, components that are interested in adjusting the backoff can
+call back using commands in the RadioBackoff interface. This allows
+multiple components to adjust the backoff period for packets they are
+specifically listening to adjust. The lower the backoff period, the
+faster the transmission, but the more likely the transmitter is to hog
+the channel. Also, backoff periods should be as random as possible
+to prevent two transmitters from sampling the channel at the same
+moment.
+
+InitialBackoff is the shortest backoff period, requested on the first
+attempt to transmit a packet.
+
+CongestionBackoff is a longer backoff period used when the channel is
+found to be in use. By using a longer backoff period in this case,
+the transmitter is less likely to unfairly tie up the channel.
+
+LplBackoff is the backoff period used for a packet being delivered
+with low power listening. Because low power listening requires
+the channel to be modulated as continuously as possible while avoiding
+interference with other transmitters, the low power listening
+backoff period is intentionally short.
+
+
+5. Acknowledgements
+====================================================================
+
+5.1 Hardware vs. Software Acknowledgements
+--------------------------------------------------------------------
+
+Originally, the CC2420 radio stack only used hardware generated
+auto-acknowledgements provided by the CC2420 chip itself. This led
+to some issues, such as false acknowledgements where the radio chip
+would receive a packet and acknowledge its reception and the
+microcontroller would never actually receive the packet.
+
+The current CC2420 stack uses software acknowledgements, which
+have a higher drop percentage. When used with the UniqueSend
+and UniqueReceive interfaces, dropped acknowledgements are more desirable
+than false acknowledgements. Received packets are always acknowledged
+before being filtered as a duplicate.
+
+Use the PacketAcknowledgements or MessageTransport interfaces
+to determine if a packet was successfully acknowledged.
+
+
+5.2 Data Sequence Numbers - UniqueSend and UniqueReceive
+--------------------------------------------------------------------
+The 802.15.4 specification identifies a Data Sequence Number (DSN)
+byte in the message header to filter out duplicate packets [3]_.
+
+The UniqueSend interface at the top of the CC2420 radio stack is
+responsible for setting the DSN byte. It is set exactly one time
+per outgoing message. Even if lower levels such as MessageTransport
+or LowPowerListening retransmit the packet, the DSN byte stays the
+same.
+
+The UniqueReceive interface at the bottom of the CC2420 radio stack
+is responsible for filtering out duplicate messages based on
+source address and DSN. The UniqueReceive interface is not meant
+to stop sophisticated replay attacks.
+
+
+6. Message Transport Implementation
+====================================================================
+Message transport is a layer added to the CC2420 radio stack to help unicast
+packets get delivered successfully. In previous version of TinyOS radio
+stacks, it was left up to the application layer to retry a message
+transmission if the application determined the message was not properly
+received. The Message Transport layer helps to remove the reliable delivery
+responsibility and functional baggage from application layers.
+
+
+6.1 Compiling in the Message Transport layer
+--------------------------------------------------------------------
+Because the Message Transport layer uses up extra memory footprint,
+it is not compiled in by default. Developers can simply define
+the preprocessor variable MESSAGE_TRANSPORT to compile the functionality
+of the Message Transport layer in with the CC2420 stack.
+
+
+6.2 Implementation and Usage
+--------------------------------------------------------------------
+To send a message using Message Transport, the MessageTransport
+interface must be called ahead of time to specify two fields in the outbound
+message's metadata:::
+
+ command void setRetries(message_t *msg, uint16_t maxRetries);
+ command void setRetryDelay(message_t *msg, uint16_t retryDelay);
+
+The first command, setRetries(..), will specify the maximum number
+of times the message should be sent before the radio stack stops
+transmission. The second command, setRetryDelay(..), specifies
+the amount of delay in milliseconds between each retry. The combination
+of these two commands can set a packet to retry as many times as needed
+for as long as necessary.
+
+Because Message Transport relies on acknowledgements, false
+acknowledgements from the receiver will cause Message Transport to fail.
+
+
+7. Asynchronous Low Power Listening Implementation
+====================================================================
+Because the Low Power Listening layer uses up extra memory footprint,
+it is not compiled in by default. Developers can simply define
+the preprocessor variable LOW_POWER_LISTENING to compile the functionality
+of the Low Power Listening layer in with the CC2420 stack.
+
+7.1 Design Considerations
+--------------------------------------------------------------------
+The CC2420 radio stack low power listening implementation relies
+on clear channel assessments to determine if there is a transmitter
+nearby. This allows the receiver to turn on and determine there are no
+transmitters in a shorter amount of time than leaving the radio on
+long enough to pick up a full packet.
+
+The transmitters perform a message delivery by transmitting
+the full packet over and over again for twice the duration of the receiver's
+duty cycle period. Transmitting for twice as long increases the
+probability that the message will be detected by the receiver, and
+allows the receiver to shave off a small amount of time it needs to
+keep its radio on.
+
+Typically, the transmission of a single packet takes on the following
+form over time:
+
++--------------+---------------------------------------+----------+
+| LPL Backoff | Packet Transmission | Ack Wait |
++--------------+---------------------------------------+----------+
+
+To decrease the amount of time required for a receive check, the channel
+must be modulated by the transmitter as continuously as possible.
+The only period where the channel is modulated is during the
+Packet Transmission phase. The receiver must continuosly sample the CCA pin
+a moment longer than the LPL Backoff period and Ack Wait period combined
+to overlap the Packet Transmission period. By making the LPL backoff
+period as short as possible, we can decrease the amount of time a receiver's
+radio must be turned on when performing a receive check.
+
+If two transmitters attempt to transmit using low power listening,
+one transmitter may hog the channel if its LPL backoff period
+is set too short. Both nodes transmitting at the same time
+will cause interference and prevent each other from
+successfully delivering their messages to the intended recipient.
+
+To allow multiple transmitters to transmit low power listening packets
+at the same time, the LPL backoff period needed to be increased
+greater than the desired minimum. This increases the amount of time
+receiver radios need to be on to perform a receive check because
+the channel is no longer being modulated as continuously as possible.
+In other words, the channel is allowed to be shared amongst multiple
+transmitters at the expense of power consumption.
+
+
+7.2 Minimizing Power Consumption
+--------------------------------------------------------------------
+There are several methods the CC2420 radio stack uses to minimize
+power consumption:
+
+1. Invalid Packet Shutdown
+ Typically, packets are filtered out by address at the radio hardware
+ level. When a receiver wakes up and does not receive any
+ packets into the low power listening layer of the radio stack, it
+ will automatically go back to sleep after some period of time. As a
+ secondary backup, if address decoding on the radio chip is disabled,
+ the low power listening implementation will shut down the radio if
+ three packets are receive that do not belong to the node. This helps
+ prevent against denial of sleep attacks or the typical transmission
+ behavior found in an ad-hoc network with many nodes.
+
+2. Early Transmission Completion
+ A transmitter typically sends a packet for twice the amount of time
+ as the receiver's receive check period. This increases the probability
+ that the receiver will detect the packet. However, if the transmitter receives
+ an acknowledgement before the end of its transmission period, it
+ will stop transmitting to save energy. This is an improvement
+ over previous low power listening implementations, which transmitted
+ for the full period of time regardless of whether the receiver has
+ already woken up and received the packet.
+
+3. Auto Shutdown
+ If the radio does not send or receive messages for some period of
+ time while low power listening is enabled, the radio will automatically
+ turn off and begin duty cycling at its specified duty cycle period.
+
+4. CCA Sampling Strategy
+ The actual receive check is performed in a loop inside a function,
+ not a spinning task. This allows the sampling to be performed
+ continuously, with the goal of turning the radio off as quickly as
+ possible without interruption.
+
+
+8. CC2420 Settings and Registers
+====================================================================
+
+To interact with registers on the CC2420 chip, the SPI bus must be
+acquired, the chip selecct (CSn) pin must be cleared, and then the
+interaction may occur. After the interaction completes, the
+CSn pin must be set high.
+
+All registers and strobes are defined in the CC2420.h file, and most
+are accessible through the CC2420SpiC component. If your application
+requires access to a specific register or strobe, the CC2420SpiC component
+is the place to add access to it.
+
+Configuring the CC2420 requires the developer to access the CC2420Config
+interface provided by CC2420ControlC. First call the CC2420Config commands to
+change the desired settings of the radio. Next, call CC2420Config.sync()
+to commit these changes to the radio chip. If the radio is currently
+off, the changes will be committed at the time it is turned on.
+
+RSSI can be sampled directly by calling the ReadRssi interface provided
+by CC2420ControlC. See page 50 of the CC2420 datasheet for information
+on how to convert RSSI to LQI and why it may not be such a good idea [1]_.
+
+
+
+9. Cross-platform Portability
+====================================================================
+To port the CC2420 radio to another platform, the following interfaces
+need to be implemented:::
+
+ // GPIO Pins
+ interface GeneralIO as CCA;
+ interface GeneralIO as CSN;
+ interface GeneralIO as FIFO;
+ interface GeneralIO as FIFOP;
+ interface GeneralIO as RSTN;
+ interface GeneralIO as SFD;
+ interface GeneralIO as VREN;
+
+ // SPI Bus
+ interface Resource;
+ interface SpiByte;
+ interface SpiPacket;
+
+ // Interrupts
+ interface GpioCapture as CaptureSFD;
+ interface GpioInterrupt as InterruptCCA;
+ interface GpioInterrupt as InterruptFIFOP;
+
+The GpioCapture interface is tied through the Timer to provide a relative time
+at which the interrupt occurred. This is useful for timestamping received
+packets for node synchronization.
+
+If the CC2420 is not connected to the proper interrupt lines,
+interrupts can be emulated through the use of a spinning task
+that polls the GPIO pin. The MICAz implementation, for example, does this
+for the CCA interrupt.
+
+
+10. Future Improvement Recommendations
+====================================================================
+
+Many improvements can be made to the CC2420 stack. Below are some
+recommendations:
+
+10.1 AES Encryption
+--------------------------------------------------------------------
+The CC2420 chip itself provides AES-128 encryption. The implementation
+involves loading the security RAM buffers on the CC2420 with the information
+to be encrypted - this would be the payload of a packet, without
+the header. After the payload is encrypted, the microcontroller reads
+out of the security RAM buffer and concatenates the data with the
+unencrypted packet header. This full packet would be uploaded again to the CC2420
+TXFIFO buffer and transmitted.
+
+Because the CC2420 cannot begin encryption at a particular offset
+and needs to be written, read, and re-written, use of the AES-128 may be
+inefficient and will certainly decrease throughput.
+
+
+10.2 Authentication
+--------------------------------------------------------------------
+In many cases, authentication is more desirable than encryption.
+Encryption significantly increases energy and decreases packet throughput,
+which does not meet some application requirements. A layer could be
+developed and added toward the bottom of the radio stack that validates
+neighbors, preventing packets from invalid neighbors from reaching the
+application layer. Several proprietary authentication layers have
+been developed for the CC2420 stack, but so far none are available to
+the general public.
+
+A solid authentication layer would most likely involve the use of a
+neighbor table and 32-bit frame counts to prevent against replay attacks.
+Once a neighbor is verified and established, the node needs to ensure that
+future packets are still coming from the same trusted source. Again,
+some high speed low energy proprietary methods to accomplish this exist, but
+encryption is typically the standard method used.
+
+
+10.3 Synchronous Low Power Listening
+--------------------------------------------------------------------
+A synchronous low power listening layer can be transparently built on
+top of the asynchronous low power listening layer. One implementation
+of this has already been done on a version of the CC1000 radio stack.
+Moteiv's Boomerang radio stack also has a synchronous low power listening
+layer built as a standalone solution.
+
+In the case of building a synchronous layer on top of the asynchronous
+low power listening layer, a transmitter's radio stack can detect when
+a particular receiver is performing its receive checks by verifying the
+packet was acknowledged after a sendDone event. The transmitter can then
+build a table to know when to begin transmission for that particular receiver.
+Each successful transmission would need to adjust the table with updated
+information to avoid clock skew problems.
+
+The asynchronous low power listening stack needs to be altered a bit
+to make this strategy successful. Currently, duty cycling is started
+and stopped as packets are detected, received, and transmitted. The
+stack would need to be altered to keep a constant clock running in the
+background that determines when to perform receive checks. The
+clock should not be affected by normal radio stack Rx/Tx behavior. This
+would allow the receiver to maintain a predictable receive check cycle
+for the transmitter to follow.
+
+If the synchronous low power listening layer loses synchronization,
+the radio stack can always fall back on the asynchronous low power listening
+layer for successful message delivery.
+
+
+10.4 Neighbor Tables
+--------------------------------------------------------------------
+Moteiv's Boomerange Sensornet Protocol (SP) implementation is a very
+good model to follow for radio stack architecture. One of the nice features
+of SP is the design and implementation of the neighbor table. By
+providing and sharing neighbor table information across the entire
+CC2420 radio stack, RAM can be conserved throughout the radio stack
+and TinyOS applications.
+
+
+10.5 Radio Independant Layers
+--------------------------------------------------------------------
+The best radio stack architecture is one that is completely radio independant.
+Many of the layers in the CC2420 stack can be implemented independant
+of the hardware underneath if the radio stack architecture was redesigned
+and reimplemented. The low power listening receive check strategy may need a
+hardware-dependant implementation, but other layers like MessageTransport,
+UniqueSend, UniqueReceive, ActiveMessage, Dispatch, etc. do not require
+a CC2420 underneath to operate properly. The ultimate TinyOS radio
+stack would be one that forms an abstraction between radio-dependant
+layers and radio-independant layers, and operates with the same
+behavior across any radio chip.
+
+
+10.6 Extendable Metadata
+--------------------------------------------------------------------
+Layers added into the radio stack may require extra bytes of metadata.
+The MessageTransport layer, for example, requires two extra fields
+in each message's metadata to hold the message's max retries and
+delay between retries. The low power listening layer requires
+an extra field to specify the destination's duty cycle period for
+a proper delivery.
+
+If layers are not included in the radio stack during compile time,
+their fields should not be included in the message_t's metadata.
+
+One version of extendable metadata was implementing using an array at the end
+of the metadata struct that would adjust its size based on which layers were
+compiled in and what size fields they required. A combination of
+compiler support in the form of unique(..) and uniqueCount(..) functions
+made it possible for the array to adjust its size.
+
+Explicit compiler support would be the most desirable solution to add
+fields to a struct as they are needed.
+
+
+10.7 Error Correcting Codes (ECC)
+--------------------------------------------------------------------
+When two nodes are communicating near the edge of their RF range,
+it has been observed that interference may cause the packet to be
+corrupted enough that the CRC byte and payload actually passes
+the check, even though the payload is not valid. There is a one
+in 65535 chance of a CRC byte passing the check for a corrupted
+packet. Although this is slim, in many cases it is unacceptable.
+Some work arounds have implemented an extra byte of software generated
+CRC to add to the reliability, and tests have proven its effectiveness.
+Taking this a step further, an ECC layer in the radio stack would help
+correct corrupted payloads and increase the distance at which nodes
+can reliably communicate.
+
+
+
+11. Author's Address
+====================================================================
+
+| David Moss
+| Rincon Research Corporation
+| 101 N. Wilmot, Suite 101
+| Tucson, AZ 85750
+|
+| phone - +1 520 519 3138
+| email ? dmm@rincon.com
+|
+|
+| Jonathan Hui
+| 657 Mission St. Ste. 600
+| Arched Rock Corporation
+| San Francisco, CA 94105-4120
+|
+| phone - +1 415 692 0828
+| email - jhui@archedrock.com
+|
+|
+| Philip Levis
+| 358 Gates Hall
+| Stanford University
+| Stanford, CA 94305-9030
+|
+| phone - +1 650 725 9046
+| email - pal@cs.stanford.edu
+|
+|
+| Jung Il Choi
+| <contact>
+| phone -
+| email -
+
+
+12. Citations
+====================================================================
+.. [1] TI/Chipcon CC2420 Datasheet. http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf
+.. [2] TEP111: message_t
+.. [3] IEEE 802.15.4 Specification: http://standards.ieee.org/getieee802/802.15.html
+.. [4] TEP105: Low Power Listening
+.. [5] TEP125: TinyOS 802.15.4 Frames
--- /dev/null
+===================================
+Packet Link Layer
+===================================
+
+:TEP: 127
+:Group: Core Working Group
+:Type: Documentary
+:Status: Draft
+:TinyOS-Version: 2.x
+:Author: David Moss, Philip Levis
+
+.. Note::
+
+ This memo documents a part of TinyOS for the TinyOS Community, and
+ requests discussion and suggestions for improvements. Distribution
+ of this memo is unlimited. This memo is in full compliance with
+ TEP 1.
+
+
+Abstract
+====================================================================
+
+This TEP describes the behavior and interfaces of the TinyOS 2.x
+Packet Link Layer. The Packet Link Layer is an optional radio stack
+layer responsible for the reliable delivery of a packet from node to
+node. Packet Link provides error correction functionality found in
+Layer 2 of the OSI model [1]_.
+
+
+1. Introduction
+====================================================================
+
+In wireless networks, packets are regularly dropped between point to point
+communications due to interference or RF range. Correcting these dropped
+packets requires the transmitter to first recognize that the packet was
+not acknowledged, and then retransmit that packet.
+
+Retransmitting the packet adds its own set of issues. Specifically, the
+receiver will receive duplicate packets due to its own dropped acknowledgements.
+Logic is therefore required to allow receiver to recognize and dump duplicate
+packets, but only after the acknowledgement has been sent back to the
+transmitter.
+
+With these two pieces of functionality: the ability for a transmitter to
+keep retrying until it gets an acknowledgement and the ability
+for a receiver to accept only a single copy of the packet, a Packet Link Layer
+can be formed to reliably deliver a single packet from point to point.
+
+
+2. Design Considerations
+====================================================================
+
+2.1 Time spent retrying a delivery
+--------------------------------------------------------------------
+Some networks have different timing characteristics than others.
+Consider a person carrying a wireless device while walking in and out
+of RF range of another node. In this case, the device may want to
+retry the transmission a few times over the course of a few seconds before
+declaring the delivery unsuccessful. A robust Packet Link Layer should
+allow the developer to specify the amount of time spent retrying as well
+as the number of retries to send.
+
+
+2.2 Setting the packet sequence number
+--------------------------------------------------------------------
+To detect duplicate packets, a sequence number byte can be used
+within the packet to verify against previously received
+packets. If the source address and sequence number of a newly received
+packet matches that of a previously received packet, then the newly received
+packet is a duplicate and may be dumped. To prevent the packet sequence
+number byte from changing on each retransmission, the byte should be set
+at or above the Packet Link Layer and never changed below.
+
+
+2.3 False Acknowledgements
+--------------------------------------------------------------------
+The low levels of a radio stack or the radio chip itself are typically
+responsible for generating packet acknowledgements. It has been
+observed in some platforms that the radio chip will generate false
+auto-acknowledgements. This occurs when the radio receives the packet and
+sends an acknowledgement but the microcontroller never gets the message
+due to some error. In this case, the transmitter would believe the
+packet got to the destination successfully but the receiver would have
+no knowledge that a packet was received. Software initiated
+acknowledgements prevent this issue by removing the possibility of
+false acknowledgements.
+
+
+
+3. Interface
+====================================================================
+
+3.1 PacketLink Interface
+--------------------------------------------------------------------
+
+The TEP proposes this PacketLink interface:::
+
+ interface PacketLink {
+ command void setRetries(message_t *msg, uint16_t maxRetries);
+ command void setRetryDelay(message_t *msg, uint16_t retryDelay);
+ command uint16_t getRetries(message_t *msg);
+ command uint16_t getRetryDelay(message_t *msg);
+ command bool wasDelivered(message_t *msg);
+ }
+
+
+setRetries(message_t *msg, uint16_t maxRetries)
+ - Sets the maximum number of times to retry the transmission of the message
+
+setRetryDelay(message_t *msg, uint16_t retryDelay)
+ - Set the delay, in milliseconds, between each retransmission
+
+getRetries(message_t *msg)
+ - Returns the maximum number of retries configured for the given message
+
+getRetryDelay(message_t *msg)
+ - Returns the delay, in milliseconds, between each retransmission for the
+ given message
+
+wasDelivered(message_t *msg)
+ - This command may be called after the sendDone() event is signaled. It
+ is the equivalent of PacketAcknowledgements.wasAcked(message_t *msg), so
+ is only a helper function to make the PacketLink interface easier to use.
+
+
+
+3.2 Expected Behavior
+--------------------------------------------------------------------
+
+The PacketLink interface is accessed by the application layer before
+the packet is passed to the radio stack for transmission. The application
+layer will call setRetries(...) and setRetryDelay(...), passing in the
+message it is about to send.
+
+The interface MUST configure metadata for the packet to specify the maximum
+number of retries and the amount of delay between each retry. When the
+send process reaches the Packet Link Layer, it MUST automatically check the
+packet's metadata and retry sending the packet as previously configured.
+
+For example, to configure a packet to be retried a maximum of 50 times
+over the next 5 seconds, the developer would execute the following commands
+before sending the packet:::
+
+ call PacketLink.setRetries(msg, 50);
+ call PacketLink.setRetryDelay(msg, 100);
+
+By placing a 100 ms delay between each retry and allowing up to 50 retries
+maximum, the maximum amount of time the message will be transmitted is
+(50 * 100) ms, or 5000 ms.
+
+When transmitting a packet configured for reliable delivery to the
+broadcast address, the Packet Link Layer SHOULD allow the packet to be
+retried. This will let the transmitter know that at least one node
+received the message.
+
+
+4. Author's Address
+====================================================================
+
+| David Moss
+| Rincon Research Corporation
+| 101 N. Wilmot, Suite 101
+| Tucson, AZ 85750
+|
+| phone - +1 520 519 3138
+| email ? dmm@rincon.com
+|
+|
+| Philip Levis
+| 358 Gates Hall
+| Stanford University
+| Stanford, CA 94305-9030
+|
+| phone - +1 650 725 9046
+| email - pal@cs.stanford.edu
+|
+
+5. Citations
+====================================================================
+.. [1] "OSI model" http://en.wikipedia.org/wiki/OSI_model
projects / tinyos-2.x.git / commitdiff