Index: src/bundle-protocol/doc/bundle-protocol.rst |
=================================================================== |
new file mode 100644 |
--- /dev/null |
+++ b/src/bundle-protocol/doc/bundle-protocol.rst |
@@ -0,0 +1,181 @@ |
+.. include:: replace.txt |
+ |
+Bundle Protocol |
+--------------- |
+This model implements the base specification of bundle protocol (BP). The |
+implementation is based on [rfc5050]_. |
+ |
+Model Description |
+***************** |
+The source code for the new module lives in the directory ``src/bundle-protocol``. |
+ |
+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 core structure of BP in |ns3| |
+is shown below: |
+ |
+.. _fig-bundle-protocol-structure: |
+ |
+.. figure:: figures/bundle-protocol-structure.* |
+ :align: center |
+ |
+ The core structure of bundle protocol implementation. |
+ |
+The rectangle area represents the main classes of BP in |ns3|. |
+ |
+* Class ``ns3::BundleProtocol`` 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. The name and functions of these APIs are referenced from |
+ a Linux bundle protocol implementation -- [DTN2]_. The other functions implemented in |
+ the class ``ns3::BundleProtocol`` include bundle fragmentation and aggregation, bundle |
+ storage and registration storage. |
+ |
+* Class ``ns3::BpClaProtocol`` is a pure abstract class for the convergence layer adaptor (CLA). |
+ For each transport layer protocol, a new CLA class needs to be inherited from BpClaProtocol. |
+ In the existing implementation, only class ``ns3::BpTcpClaProtocol`` for TCP connection is |
+ implemented. It uses TCP socket in the transport layer to transmit bundles. |
+ |
+* Class ``ns3::BpRoutingProtocol`` is a pure abstract class, which defines the APIs of bundle |
+ routing protocol. In the existing implementation, only a static routing protocol class |
+ ``BpStaticRoutingProtocol`` is implemented, which uses a static map between local endpoint |
+ id and internet socket address. |
+ |
+In addition to above three core classes, the |ns3| bundle protocol model also includes classes: |
+ |
+* Class ``ns3::BundleProtocolHelper`` implements a bundle helper to facilitate users to create |
+ a bundle node. Then endpoint id data structure is supported at a BpEndpointId class; |
+ |
+* Class ``ns3::BundleProtocolContainer`` implements a bundle protocol container, which mimics class |
+ ``ns3::ApplicationContainer``. |
+ |
+* Class ``ns3::BpEndpointId`` implements the endpoint id data structure for bundle protocol; |
+ |
+* Class ``ns3::BpHeader`` implements the primary bundle header. |
+ |
+* Class ``ns3::BpPayloadHeader`` implements the bundle payload header. |
+ |
+Bundle Protocol APIs |
+******************** |
+Bundle protocol model implements several key APIs: |
+ |
+1. Open (): method ``ns3::BundleProtocol::Open ()`` installs the ``ns3::BundleProtocol`` and ``ns3::BpClaProtocol`` |
+classes into a bundle node. This method is always the first API needed to be called; |
+ |
+2. Close (): method ``ns3::BundleProtocol::Close ()`` closes the transport layer connection between two bundle node and |
+delete the registration information; |
+ |
+3. Register (): method ``ns3::BundleProtocol::Register ()`` adds an entry in the persistent registration storage. |
+A registration in BP is identified by an endpoint id, which can be get by ``ns3::BundleProtocol::BuildBpEndpointId ()``. |
+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); |
+ |
+4. UnRegister (): method ``ns3::BundleProtocol::Unregister ()`` triggers the convergence layer(CLA) to disable the transport |
+layer to receive packets; |
+ |
+5. Bind (): method ``ns3::BundleProtocol::Bind ()`` sets the registration state of the local endpoint id to "true". If the |
+state in Register () is "true" already, Bind () does nothing in this case; |
+ |
+6. UnBind (): method ``ns3::BundleProtocol::UnBind ()`` sets the registration state of the local endpoint id to "false"; |
+ |
+7. Send (): method ``ns3::BundleProtocol::Send`` is called by applications to send a application data unit (ADU) from |
+the source endpoint id to the destination endpoint id. If the ADU size is larger than the bundle size, |
+ADU is divided into several bundles while each bundle includes a primary bundle header and a bundle payload |
+header. The bundle will be stored in the persistent bundle storage in BundleProtocol first. Then the BpClaProtocol |
+establishes the transport layer connection with peer bundle node. Once the transport layer connection is |
+available, the BpClaProtocol will retrieve and send the bundle by a FIFO order from the storage; |
+ |
+8. Receive (): method ``ns3::BundleProtocol::Receive ()`` is called by applications to fetch bundles stored from the bundle storage |
+in a FIFO order. The bundle headers are removed before forwarding bundles to the application; |
+ |
+9. BuildBpEndpointId (): method ``ns3::BundleProtocol::BuildBpEndpointId ()`` builds an endpoint id based on scheme and ssp strings, |
+or a single uri strings. In BP of |ns3|, each registration has a unique endpoint id. a BundleProtocol class |
+can be served for multiple registrations in a bundle node; |
+ |
+10. SetBpEndpointId (): method ``ns3::BundleProtocol::BuildBpEndpointId ()`` lets users to build an endpoint id and set the endpoint |
+id to the bundle protocol. |
+ |
+Scope and Limitations |
+********************* |
+The existing bundle protocol model in |ns3| support following functions: |
+ |
+1. Unicast transmitting multiple bundles between two bundle nodes; |
+ |
+2. Bundle fragmentation and aggregation; |
+ |
+3. Static bundle routing protocol; |
+ |
+4. Transmitting bundles via TCP protocol at the transport layer; |
+ |
+5. Generating endpoint id based on a pair of scheme and ssp string, or a uri string; |
+ |
+6. Adding primary bundle header and bundle payload header in a bundle; |
+ |
+7. A bundle protocol helper, which can install bundle protocol to a set of nodes, and set the routing protocol, |
+ endpoint id of bundle protocol; |
+ |
+8. A bundle protocol container, which can set the start and stop time of a set of bundle protocols. |
+ |
+In the existing model, multiple bundle protocols can be installed in a single node. Each application must create its own bundle protocol. |
+Each bundle protocol only has one endpoint id. |
+ |
+Ongong developments |
+=================== |
+1. Adding custody delivery support in bundle protocol model ( from section 5.2 to 5.15, RFC 5050). This includes the header processing |
+ in the sender, relay and receiver bundle nodes; |
+ |
+2. Self-Delimiting Numeric Values (SDNV) in bundle protocol headers (section 4.1, RFC 5050 ). |
+ |
+ |
+Future developments |
+=================== |
+There are two main IETF RFCs for bundle protocol: RFC 4838, which defines the DTN network architecture, and RFC 5050, which details |
+the bundle protocol specification. The bundle protocol model in |ns3| implements the main functions of RFC 5050. |
+ |
+In the future, following left functions of RFC 5050 can be implemented: |
+ |
+1. Administrative record processing (section 5.1 and section 6.0, RFC 5050); |
+ |
+2. Polling (section 5.16, RFC 5050). |
+ |
+In addition, the convergence layer can be extended by: |
+ |
+1. Full TCP convergence layer support [clatcp]_ ; |
+ |
+2. UDP convergence layer support [claudp]_ . |
+ |
+Also, following functions of RFC 4838 can be implemented in the future: |
+ |
+1. Congestion and flow control at the bundle layer (section 3.13, RFC 4838); |
+ |
+2. Bundle routing protocol (section 3.8, RFC 4838); |
+ |
+3. Anycast and multicast (RFC 3.4, RFC 4838). |
+ |
+RFC 4838 only gives the design principle for above functions. The protocol details should be specified by developers. |
+ |
+Usage |
+***** |
+An example script in ``src/bundle-protocol/examples`` is created to show the usage of bundle protocol model. |
+Codes below show an example for registering an application in a bundle node to send bundles.:: |
+ |
+ BpEndpointId eidSender ("dtn", "node0"); // build an endpoint id |
+ BundleProtocolHelper bpSenderHelper; // create a bundle protocol helper |
+ bpSenderHelper.SetBpEndpointId (eidSender); // set endpoint id |
+ bpSenderHelper.SetRoutingProtocol (route); // set bundle routing protocol |
+ BundleProtocolContainer bpSenders = bpSenderHelper.Install (nodes.Get (0)); // install bundle protocol at node 0 |
+ bpSenders.Start (Seconds (1.0)); // start the bundle protocol at seconds 1.0; In this step, the bundle |
+ // protocol will calls the Register API with default register information |
+ bpSenders.Stop (Seconds (5.0)); // stop the bundle protocol, Close API will be called |
+ |
+ /* |
+ * send the packet from endpoint id eidSender to endpoint id eidRecv. The src and dst will be transferred into internet socket address |
+ * based on bundle routing protocol. |
+ */ |
+ bpSender.Get (0)->Send (packet, src, dst); |
+ |
+References |
+********** |
+.. [rfc5050] K. Scott, S. Burleigh, "Bundle Protocol Specification," RFC 5050, Nov. 2007 |
+.. [DTN2] DTN2, "http://www.dtnrg.org/wiki/Code," Dec. 2013 |
+.. [clatcp] M. Demmer, J. Ott, S. Perreault, "Delay Tolerant Networking TCP Convergence Layer Protocol," draft-irtf-dtnrg-tcp-clayer-07, Sep. 2013 |
+.. [claudp] H. Kruse, S. Ostermann, "UDP Convergence Layers for the DTN Bundle and LTP Protocols," draft-irtf-dtnrg-udp-clayer-00, Nov. 2008 |