CONTACT:
=======
Hongwei Zhang, Ph.D.
Assistant Professor
Dept. of Computer Science
Wayne State University
Tel: 313 577 0731
E-mail: hzhang@cs.wayne.edu



REFERENCES:
===========
* For the basic design of ReliableComm, please refer to the paper and
  .ppt presentation at the following links:
     http://www.cs.wayne.edu/~hzhang/group/publications/RBC.pdf
     http://www.cs.wayne.edu/~hzhang/group/publications/RBC.ppt



CONFIGURATION:
==============
1) In real deployment, make sure to comment out the following line 
          #define TOSSIM_SYSTIME 1
   in file ReliableComm.h 

2) TOSH_DATA_LENGTH (defined in AM.h) should be no less than
                aggregatedACK * sizeof(Base_Ack_Msg)
   By default, 4 * 6 = 24.

3) If EXPLICIT_ACK is not defined (by default), the length of payload of
   packets sent to ReliableComm should be no more than (TOSH_DATA_LENGTH - 19)
   bytes.

  (If EXPLICIT_ACK is defined, the length of payload of packets sent to
  ReliableComm should be no more than (TOSH_DATA_LENGTH - 11) bytes. Note
  that the 11 bytes are used for congestion and contention control.)

4) If need be, increase constant TOSH_MAX_TASKS (defined in sched.c) to
   increase the size of the TASK queue. This is could be useful if there
   are many tasks in an application.

5) The active message handler-id used for ReliableComm must be between
   HANDLER_ID_LOWER_BOUND and HANDLER_ID_UPPER_BOUND which are defined
   in ReliableComm.h. 

   No other module is using any handler-id between HANDLER_ID_LOWER_BOUND
   and HANDLER_ID_UPPER_BOUND. 

   (With exception for communication via UART for a base station, where
    any handler id is acceptable.)

6) If you want to use explicit ACK at the MAC layer, let EXPLICIT_ACK in
   ReliableComm.h uncommented; 

   if you want to use implicit ack provided by ReliableComm itself, let
   EXPLICIT_ACK commented in ReliableComm.h.



USE RELIABLECOM TO TRANSMIT & RECEIVE PACKETS:
==============================================
1) The interfaces provided by ReliableComm are defined in ../interface/: 
    - ReliableCommControl.nc
    - ReliableSendMsg.nc
    - ReliableReceiveMsg.nc

2) When a component calls 
       ReliableSendMsg.send(uint16_t address, uint8_t length, TOS_MsgPtr msg),
   the component must append 0xffff to the end of the payload of "msg", that is,
   make sure both msg->data[length] and msg-> data[length+1] be 0xff. 

3) In the event handler for 
     event TOS_MsgPtr receive(TOS_MsgPtr m),
   bytes from m->data[m->length] to m->data[m->length+1] should not be modified
   before the message is forwared, i.e., the components using ReliableComm should
   only operate on the payload of its own. 

4) By default, ReliableComm does not enable snooping. If a component wants to
   snoop messages, the component should call ReliableCommControl.setSnooping(TRUE).
   Higher layer could check the addr of the received message to know whether a
   received message is snooped or not. 

   Note: ReliableCommControl.setSnooping(TRUE) should be called after the
   initialization of ReliableComm and  before "call ReliableComm.start()".

5) To set a node as a base station, call ReliableCommControl.setBase(TRUE) before 
   "call ReliableComm.start()". 

   Note: ReliableCommControl.setBase(TRUE) should be called after the initialization
   of ReliableComm and  before "call ReliableComm.start()".

6) The component that uses ReliableComm should make sure that a node knows whether
   it is a child of a base station, via the exposed command 
   "ReliableCommControl.setBaseChildren(...)".

7) When receiving a packet, forward as soon as possible (to avoid unnecessary retransmission
   at the sender).

8) It is recommened that base stations use GenericComm instead of UARTComm directly.

9) Add 
    "includes ReliableComm;" 
   in configuration file for an application, so that application can use parameters 
   such as "SEND_QUEUE_SIZE" (defining the maximum number of outstanding packets).



REMARKS:
========
1) For the simplicity of higher-layers (not the performance), ReliableComm locally copy/store
   the packets from higher-layers, and signal the corresponding sendDone (as SUCCESS, even
   though the packet may not be guaranteed to be delivered to its receiver successfully)
   immediately after enqueuing the packet. 

2) Only support one-to-one reliable unicast communication with implicit acknowledgement.

3) If a node is a base station, ReliableComm provides (SEND_QUEUE_SIZE - NUM_BASE_ACK_BUFFERS)
   queue positions to queue and send packets to UART interface. 

   For higher performance, however, it is better for BASE STATION not to use RelibleComm
   to send message to UART interface, since BASE STATION does not require reliable
   transmission across UART interface. 



CODE EXAMPLES:
==============
   For ReliableComm itself, an example code exists in TestReliableComm.
