wiki:Documentation/OtherApps/DITG

Orbit > Other Applications? > Integrating D-ITG with ORBIT

==================
D-ITG Integration
==================

This document covers the general details of integrating sample applications with the ORBIT tesbed setup. A specific example (D-ITG) is chosen as a candidate application and the steps are described in the document. The readers are referred to the ORBIT architecture document for the individual software component details. 

To summarize, nodeHandler is the experiment controller software that is used to choreograph the experiment. It is used to power on, initialize interfaces, launch the applications simultaneously on the nodes involved in the experiment, as well as create databases consistent with the measurements for that particular experiment.

OML (ORBIT Measurement Library) is used to collect measurements at run-time from the nodes. It consists of an OML-client on the nodes and the collection server on the experiment controller machine that is used to collect the measurements sent by the clients and insert into appropriate columns of the database.

Integrating a new application with this setup mainly consists of the following steps



.. contents::
.. sectnum::

-----




Integrating with measurement collection
========================================
In order to initiate measurement collection using OML, the following steps need to be taken

Identifying the measurements reported by Iperf
------------------------------------------------

The first step is to identify what are the measurements reported by the application and finding the right files in the source code corresponding to these measurement reports. For D-ITG, the statistics for UDP (and TCP?!) are throughput, packet loss, delay and jitter 

For ITG, this was traced to the file ITGDec/ITGDecod.cpp 

         
Create the application definition XML file
--------------------------------------------

The application definition file for Iperf is defined to capture the outputs that the program reports. This file is later used to auto-generate OML library and headers for this application. The following application definition file has been written for D-ITG(using a subset of command line inputs)

[wiki:Documentation/OtherApps/Iperf/ITGAppDefXML ITG Application Definition Schema]

Verify that the XML file is syntactically correct by correct by checking if it opens correctly in an XML enabled browser (IE or Mozilla)

Creating OML shared library and headers for Iperf
---------------------------------------------------

After defining the application definition file as above, use the following command to submit the application definition file to a wrapper utility

'''wget -q http://www.orbit-lab.org/oml/client_wrapper --post-file <app-def.xml>'''

In response to the <app-def>.xml file, the OML application service returns a tar file containing:  oml_<app-def>.h  and liboml_<app-def>.a. 

Iperf is then compiled against this library.

Include header files and function calls in source code
--------------------------------------------------------

The statistics reports are generated by the application, ITGDec and hence we modify the file ITGDec/ITGDecod.cpp to include the following

 ''#include oml_orbit_winlab_itg.h''

  ''initialize_oml(&argc, argv, NULL)''

   and add the function call as follows to report collected measurements

  ''oml_receiverport((int)flow_no,(int)src_port, (int)dst_port, (float) throughput,  (float) jitter, (float)delay, (float)pkt_loss)''

Note that the src port and dst port help to distinguish between two different flows at the receiver 

Modify Makefile and build application
---------------------------------------

Linker options: -loml_client -lomltx
   
LDFLAGS = -L/usr/lib/ -Lpath_to/liboml_orbit_winlab_itg.a

The oml client package with the required libraries can be obtained from the orbit repository (apt-get oml-client). It will install oml-client and oml_transport libraries in /usr/lib/

Note that the OML client is already present on the nodes (so the second step can be ignored)

Now, ITG can be rebuilt using the Makefile.

Miscellaneous
---------------
Note that the application will need the following environment variables to be set

'''LD_LIBRARY_PATH = /usr/lib/'''
'''OML_NAME=<node-id>'''
'''OML_CONFIG=<OML configuration file>'''

All these variables are set automatically when the experiment is run using the nodeHandler.



Integrating with Nodehandler – Launching the application
==========================================================

This section includes the details of how to integrate ITG with the experiment controller (nodeHandler) so that it can be launched on all the nodes involved in the experiment.

Create application definitions for ITG sender and receiver
------------------------------------------------------------
The following two sample files for Iperf sender and receiver show the details of how to create definitions for any application. The definition mainly contains the command line options that can be set during launching the application as well as the output statistics reported by the application

ITG Sender 
--------------
[http://www.orbit-lab.org/wiki/Documentation/OtherApps/DITG/ITGSender ITG Sender Application Script]


ITG Receiver
-----------------
[http://www.orbit-lab.org/wiki/Documentation/OtherApps/DITG/ITGReceiver ITG Receiver Application Script]


Create prototypes using previously defined applications
----------------------------------------------------------
Using the previously defined ITG client and server application definitions, the next step is to create prototypes that use these applications. Each of these will use ITG as the underlying application; however their properties can be customized as shown below  

ITG CBR Sender
------------------
[http://www.orbit-lab.org/wiki/Documentation/OtherApps/DITG/ITGCBRSender ITG CBR Sender Prototype Script]

ITG CBR Receiver
--------------------
[http://www.orbit-lab.org/wiki/Documentation/OtherApps/DITG/ITGCBRReceiver ITG CBR Receiver Prototype Script]

ITG CBR Decoder
--------------------
[http://www.orbit-lab.org/wiki/Documentation/OtherApps/DITG/ITGDecoder ITG CBR Decoder Prototype Script]


Write experiment script using the previously defined application and prototype definitions
---------------------------------------------------------------------------------------------
The final step is to write the actual experiment script as shown below

Experiment Script
-------------------
[http://www.orbit-lab.org/wiki/Documentation/OtherApps/DITG/ExpScript Experiment Script]

Parameters and statistics supported
=======================================
Sender Side
--------------
 * Measurement type (one-way delay or RTT
 * Receiver port
 * Protocol type (TCP or UDP)
 * TTL
 * Duration of traffic generation

Traffic Generation Parameters
------------------------------
 * Constant interarrival b/w packets
 * Exponential distribution
 * Poisson distribution

Packet Size Options
------------------------------
 * Constant Payload Size
 * Exponential distribution
 * Poisson distribution

Application Level Options
------------------------------
Usage: To select VoIP use ./ITGSend –a <recvIP> -i <codec> -h <transport>
 * VoIP (different codec-types:G.711.1, G.711.2, G.723.1, G.729.2, G.729.3)
 * Control (RTP or CRTP)

 
Receiver Side
--------------
 * Log file to store measurements

Decoder
----------
The decoder basically extracts the log file and reports information to OML server. It takes the following options

 * Jitter report interval
 * Throughput report interval
 * Packet loss report interval
 * Delay report interval
 * Log file used by receiver

Statistics Reported
-----------------------
Note that the delay measurements depend on the synchronization between the two nodes (resolution of NTP, for now)
 * Throughput (UDP and TCP)
 * Average Jitter (UDP and TCP)
 * Packet loss (UDP and TCP)
 * Average One- way delay (UDP and TCP)
 * RSSI (UDP)
 * Phy Rate (UDP)



 
Last modified 11 years ago Last modified on 09/05/06 17:49:11