View source for SOCIS2013BundleProtocolProject

= Bundle Protocol  =

* Student: [mailto:q5frc@unb.ca Dizhi Zhou]
* Mentors: : [mailto:tommaso.pecorella@unifi.it Tommaso Pecorella], [mailto:luca.ronga@cnit.it Luca Simone Ronga]
* Abstract: this project aims to implement the bundle protocol (BP) in NS-3 which includes the bundle node structure and basic function of BP protocol. It is designed to support BP in IETF and CCSDS standard. First, the bundle node is the node installing bundle layer between application layer and transport layer in NS-3. The bundle node structure in this project is designed to be easily run on varied transport layer protocols and provides a unified socket interface to applications. Second, the basic functions of BP protocol are divided into three parts in this project: bundle transmission operations, custody signal support and bundle status report support(optional). This project also includes the test suites and documentations in BP. 
* Code: the code can be found in [http://code.nsnam.org/dizhizhou/ns-3-dev-socis2013/summary here]
* About me: I'm a Ph.D. student in the University of New Brunswick, Canada. My research interests include Multipath TCP (MPTCP) in cooperative wireless network and network simulation. You can find more information about my research in [http://www.cs.unb.ca/~q5frc/ website] or [http://www.linkedin.com/pub/dizhi-zhou/30/774/477 LinkedIn].

= Protocol structure = 
In NS-3, the bundle protocol (BP) can be seen as a special application, which provides transport layer services to other applications in a delay-tolerant network. The structure of BP in NS-3 is shown below:
          
         applications
              |
      -----------------------------------------
     |        |                                |
     |  BundleProtocol                         |
     |        |                                |
     |  BpClaProtocol   ---- BpRoutingProtocol |
     |        |                                |
      -----------------------------------------
              |
           Sockets                              

The rectangle area represents the main classes of BP in NS-3. 

# BundleProtocol class implements several BP APIs to applications, such as Register (), Open (), Bind () and so on. Applications can use these APIs to transmit bundles between bundle nodes.
# BpClaProtocol class is a pure abstract class for convergence layer adaptor (CLA). For each transport layer protocol, a new CLA class needs to be inherited from BpClaProtocol. In the existing version, only BpTcpClaProtocol is implemented. It uses TCP socket in the transport layer to transmit bundles.
# BpRoutingProtocol class is a pure abstract class, which defines the APIs of bundle routing protocol. In the existing version, only BpStaticRoutingProtocol is implemented, which uses a static map between local endpoint id and internet socket address.

In the existing implementation, multiple bundles can be transmitted between two bundle nodes, which are connected directly by p2p link.

= Bundle protocol APIs =
In this section, we introduce BP APIs supported by BP in NS-3. 

== Open () ==
The Open () API installs the BundleProtocol and BpClaProtocol classes into a bundle node. Open () is always the first API needed to be called.

== Register () ==
Register () API adds an entry in the persistent registration storage. A registration in BP is identified by an endpoint id, which can be get by BuildBpEndpointId () API. If the state field in the register information is "true" (active state), which means that this application desires to receive bundles, Register () triggers the BpClaProtocol to enable a transport layer connection to receive packet (e.g., listen state in TCP).

== Unregister () ==
Unregister () triggers the convergence layer(CLA) to disable the transport layer to receive packets. For example, BpTcpClaProtocol will be called by Unregister to close the tcp connection.

== Bind () ==
Bind () APIs set the registration state of the local endpoint id to "true". If the state in Register () is "true" already, Bind () does nothing in this case.

== Send () ==
Send a bundle from the source endpoint id to the destination endpoint id. The bundle will be stored in the persistent bundle storage in BundleProtocol first. When the first bundle is sent by the source endpoint id, the BpClaProtocol establishes the transport layer connection with peer bundle node. Once the transport layer connection is available, the BpClaProtocol will retrieve the bundle in a FIFO order from the storage and then send it.

== Receive () ==
Applications can use this API to get bundles stored from storage in a FIFO order.

== BuildBpEndpointId () ==
Build an endpoint id for a registration. In BP of NS-3, each registration has a unique endpoint id. a BundleProtocol calss can be served for multiple registrations in a bundle node.

=Usage=

An example script in src/bundle-protocol/examples is created to show the usage of these APIs. In this section, we show a sample code for registering an application in a bundle node to send bundles.

    Ptr<BundleProtocol> sender = CreateObject<BundleProtocol> ();   // create a bundle protocol
    sender->Open (nodes.Get (0));  // install this bundle protocol in a node and install cla into this bundle protocol
    BpEndpointId src = sender->BuildBpEndpointId ("dtn","node0");  // get an endpoint id: dtn:node0
    struct registerInfo info; // create registration information
    info.lifetime = 10;
    info.state = false;
    sender->Register (src, info);  // register this endpoint id to the bundle protocol
    sender->Bind (src);            // set the registration of endpoint id src to active state. 
                                   // So far, the sender can receive bundles from other nodes.
    sender->SetRoutingProtocol (routing); // set the routing protocol for this bundle node
    sender->Send (packet, src, dst);      // send the packet from endpoint id src to endpoint id dst. 
                                          // The src and dst will be transferred into internet socket address
                                          // based on bundle routing protocol.

= Approach =
I divide the functions in this project into three parts: 
* S1: functions to make sure the bundle can be sent from sender to receiver, node structure, send/receive/forward, static routing, naming syntax. 
* S2: control functions for custody transfer, custody signal in AA. 
* S3: error control signals: bundle status report.

= Milestones  =
This project aims to achieve following milestones:
# Send and receive multiple bundles between two directly connected bundle nodes.
# Custody support

= Plan =
12 weeks from Sep.4 to Nov.24: 
* Week1: node structure: the class relationship in NS-3. 
* Week2: node structure: the class relationship in NS-3. 
* Week3: send and receive without forwarding procedure (two bundle nodes case). 
* Week4: send and receive with forwarding procedure (three or more bundle nodes case, forward immediately, not custody transfer scheme). 
* Week5: send and receive with forwarding procedure (three or more bundle nodes case, forward immediately, not custody transfer scheme). 
* Week6: write test code and documentation for S1. 
* Week7: custody signal support  (store-and-forward, custody transfer). 
* Week8: custody signal support  (store-and-forward, custody transfer). 
* Week8: write test code and documentation for S2. 
* Week9: bundle status support* Week10: bundle status support. 
* Week11: write test code and documentation for S3. 
* Week12: wrap up.

=Acknowledgement=
I would like to express my special thanks of gratitude to Tommaso Pecorella and Tom Henderson, also thanks of Lalith Suresh and Luca Simone Ronga. Thanks for their valuable comments and helps on my work. Thanks for all mentors in NS-3 community to give me this opportunity in SOCIS project.