Changes between Initial Version and Version 1 of OMFWiMAXExperiments

Timestamp:

09/07/11 17:17:22 (13 years ago)

Author:

agosain@bbn.com

Comment:

--

OMFWiMAXExperiments

@@ +1 @@
+[[PageOutline]]
+
+
+= GENI WiMAX Experiments Using OMF/OML =
+
+== 1.  GENI WiMAX deployment goals  ==
+
+The goals of GENI WiMAX meso-scale deployments at campus sites are to:
+
+ - Support WiMAX experiments, including mobile experiments, by experimenters located at a site.  (Mobile experiments typically require someone to physically move mobile stations within the coverage area of the site.) 
+
+ - Support WiMAX experiments at a site by remote experimenters.  (Remote experimenters should be able to conduct some experiments without a local support person, or participate in mobile experiments with the help of a local support person.) 
+
+ - Support access to network applications using WiMAX-connected mobile stations on the campus.  (This is equivalent to providing 4G service on the campus.)
+
+A important goal of the GENI WiMAX meso-scale deployments is to use OMF (ORBIT Management Framework) and OML (ORBIT Measurement Library), initially developed by WINLAB and NICTA to support the ORBIT testbed at Rutgers WINLAB.  This use of OMF/OML will:
+
+ - Provide access to the extensive OMF/OML experiment control and measurement features that have been developed at WINLAB and NICTA specifically for wireless testbeds.
+
+ - Provide a common environement for WiMAX experiments, which should facilitate sharing experiment design and scripts among GENI WiMAX experimenters.
+
+ - Provide a way for remote experimenters to use OMF to gain access to a GENI WiMAX site, schedule resources for their experiment, and fully orchestrate their experiment, including measurements.
+
+ - Provide a way for a WiMAX site to be shared (i.e., virtualized or sliced) among several experiments at the same time.
+
+== 2.  Guide to this document ==
+
+Like all comprehensive tool sets, OMF/OML has a significant "learning curve", i.e., there are complexities in installation and use that must be conquered and understood before the advantages during use can be appreciated.  The purposes of this wiki document are to:
+
+ - Help the PI/staff at each site understand and install a complete OMF/OML instance at their site, that will be able to support all of the intended use cases for each site.
+
+ - Help the PI/staff at each site understand how to write and conduct a WiMAX experiment;  this is done by presenting an example of writing and conducting a basic WiMAX throughput experiment.
+
+ - Help an experimenter learn how to write and conduct a WiMAX experiment, by first downloading a basic throughput experiment (the WiMAX equivalent of a "hello world" experiment), and then explaining how to extend this to a new experiment.
+
+For all users of this document:
+
+ - Section 3 provides an overview of the OMF/OML configuration and experiment process.
+
+ - Section 4 provides an overview of the GENI WiMAX base station configuration and the expected use cases.
+
+ - Section 5 provides an overview of a basic WiMAX throughput experiment.
+
+For the PI/staff who want to understand how to install a complete OMF/OML instance, including writing and conducting a WiMAX experiment, they should follow these sections:
+
+ - Section 6 provides a detailed step-by-step procedure for building an OMF/OML image for a mobile station node, and then archiving the image;  this requires the inclusion of a WiMAX experiment script, written in OEDL (OMF Experiment Description Language).  The end result of this procedure is a mobile station node image, that can be archived for later use.
+
+ - Section 7 provides a detailed step-by-step procedure for designing a WiMAX experiment, using the example of a basic throughput experiment, and then writing the experiment script in OEDL.
+
+ - Section 8 explains several variations on the basic WiMAX throughput experiment that have been written and tested.
+
+ - Section 9  explains how to load the archived image for an experiment onto a mobile station node.
+
+ - Section 10 explains how to conduct an experiment.
+
+ - Section 11 explains how to process and plot measurement data using OML and some additional scripts.
+
+ - Section 12 provides a brief overview of WiMAX throughput data from recent experiments at the Raytheon BBN site
+
+For an experimenter who wants to get started using OMF/OML, they should follow these sections:
+
+ - Request an orbit account at http://www.orbit-lab.org/userManagement/register, if you don't already have one to get access to the experiment image.
+
+ - Section 9  explains how to load the archived image for an experiment onto a mobile station node.
+
+ - Section 10 explains how to conduct an experiment.
+
+ - Section 11 explains how to process and plot measurement data using OML and some additional scripts.
+
+ - Section 12 provides a brief overview of WiMAX throughput data from recent experiments at the Raytheon BBN site
+
+For an experimenter that want to take the basic experiment and extend it to meet their own needs, they should consult these sections:
+
+ - Section 13 explains how to write an experiment script for a new experiment
+
+ - Section 7 provides a detailed step-by-step procedure for designing a WiMAX experiment, using the example of a basic throughput experiment, and then writing the experiment script in OEDL.
+
+
+ 
+== 3.  OMF/OML configuration and experiment process  ==
+
+The following sections use material from the OMF/OML wikis to explain the OMF/OML framework, components and experiment steps.
+
+=== 3.1  OMF/OML framework ===
+
+OMF is a generic framework for controlling and managing networking testbeds. 
+
+The main motivation behind using OMF/OML is that they provide for a unified and standard way of performing experiments and collecting data. 
+
+The following picture shows the experiment life-cycle when OMF is used in conjunction with OML (Orbit Measurement Library) to collect measurements. The experiment life-cycle shown in the diagram is explained in detail at [http://mytestbed.net/projects/omf/wiki/UsageOverview  usage overview].
+
+[[Image(http://mytestbed.net/attachments/download/203)]]
+
+OMF is written in Ruby. 
+
+The OMF application definition and OMF experiment description also have to be written in a Ruby-based language called OEDL (Orbit Experiment Description Language) by the Experimenter.
+
+OML is a measurement library. You identify measurement points in your test application (e.g. iperf) and compile/link it with OML headers/libraries. Your OMLized application communicates with an OML-Server during run-time to collect the measurements you specified in the code. The OML-Server creates sqlite3 files, containing databases with tables whose schemas are based on the measurement points you identified in your original code.
+
+OMF and OML are independent from each other, but it is recommended that you use OML if you want to set up an OMF testbed.
+
+Creating an OMF-enabled testbed involves installing various OMF components whose tasks we briefly describe next. 
+
+Later in this document, we show how to install all the relevant components on one single machine (e.g. a netbook). This would facilitate running WiMAX experiments on a mobile node in OMF's standard and unified way.
+
+For more detailed information on OMF, OML and their applications and use-cases please refer to [http://mytestbed.net/ my testbed wiki]. 
+
+===  3.2  OMF/OML components ===
+
+The following picture, shows different components of an OMF system and their interactions with each other as well as the experimenter. Here we show the actions of each component by describing how an experiment gets executed in an OMF system. For more details on please refer to [http://mytestbed.net/projects/omf/wiki/Glossary glossary].
+
+[[Image(http://mytestbed.net/attachments/download/201)]]
+
+===  3.3  OMF/OML experiment steps  ===
+
+These are the steps and interactions that occur when an experiment is ran with OMF:
+
+    * Researcher Alice starts a new instance of an Experiment Controller (EC), and passes her Experiment Description (ED) to it (e.g. running by running the following command in shell: $omf exec my_experiment.rb). The ED is written in OEDL, a ruby-based language, by the experimenter.
+
+    * The EC interprets the ED, and sends some requests to the Aggregate Manager (AM) of the testbed to ask for the initialization and configuration of Alice's required resources specified in ED
+
+    * The multiple services of the AM initialize and configure these resources (e.g. copy an entire disk image or just some application packages on the resources, etc...)
+
+    * When the resources are ready, the EC sends commands to the Resource Controllers (RCs), which run on each of these resources
+
+    * The RCs interpret these commands and execute the actions, such as starting up application M, changing the parameters of application N, etc... (all interactions between the EC and RC happen through a publish-subscribe mechanism using XMPP, and are hidden from the experimenter.
+
+    * At this stage the experiment is "running"...
+
+    * While the experiment is running, the applications may send measurement data to the Measurement Library (ML). It is optional, but recommended to use OML for collecting measurements. For that purpose, the test application has to be OMLized, e.g. have measurement points indicated in its source and be compiled and linked with oml libraries. If the source code of the application is not available or it's written in a language other than C/C++, an OML wrapper has to be created and used. Later in this document we describe creation of a sample OML wrapper.
+    
+    * The ML sends the pre-processed measurements to the Measurement Collection Service, which stores them in a unique database for this experiment. In case of using OML, this service is provided by a running instant of the oml-server.
+
+    * After the experiment is finished and measurements are collected, the experimenter can post-process the collected data. This step is independent of OMF. To see different ways of looking at experiment results please see: [http://mytestbed.net/wiki/omf/Analysing_Results analyzing results]. Later in this document, we describe how we use a combination of Ruby/bash scripts and R scripts to plot collected data. 
+
+
+
+
+== 4.  GENI WiMAX base station configuration and use cases  ==
+
+The GENI WiMAX base station configuration is summarized in [http://wimax.orbit-lab.org/ base station configuration].
+  
+[[Image(Visio-062811b_pp5-6_WiMAXSystemOverview_Page_1.jpg, 90%)]]
+
+
+The WiMAX base station (BS) includes:
+
+ - NEC base station transceiver system (BTS) indoor and outdoor units, with connections from the outdoor unit to the antenna.
+
+ - Base station server, that hosts the data path software
+
+ - Data network, that connects data path to the GENI backbone network.
+
+ - Experiment control server, that holds the OMF/OML software necessary for experiment control, and includes an Internet connection for experimenters to access the base station.
+
+ - Authentication server, that holds the services necessary to control access to the base station by experimenters;  these services are separate from the experiment control server to assure better security.
+
+ - Control network, that carries control messages within the base station, between the base station, experiment control and authentication servers.
+
+Each base station is installed at a campus site by the PI/staff, and operated for use by local and/or remote experimenters.
+
+In addition there are one or more WiMAX-connected mobile station (MS) nodes, and there are typically one or more fixed nodes (contained within the BS).
+
+There are three use cases which each base station should support:
+
+ - Use Case 1:  Service from a local or Internet application
+
+ - Use Case 2:  Experiment with a “fixed” mobile node/station using OMF/OML
+
+ - Use Case 3:  Experiment with a “roaming” mobile node/station using OMF/OML
+
+
+[http://groups.geni.net/geni/wiki/GENIWimaxUseCases  continue to more on the use cases]
+
+
+
+== 5.  Basic WiMAX throughput experiment  ==
+
+This section provides a high-level view of designing, configuring and conducting a basic WiMAX throughput measurement.
+
+=== 5.1  Configuration for experiment with a “roaming” mobile node/station (use case 3) ===
+
+This follows use case 3, with the variation that the Exp Cntrl Services on the BS and MS operate independently, and the experiment is started in both, without a connection between the MS and the BS.   At the end of the experiment, data from the two Meas Srvc's may, or may not, be explicitly merged. 
+
+[http://groups.geni.net/geni/wiki/GENIWimaxUseCases#a4.3UseCase3:ExperimentwitharoamingmobilenodestationusingOMFOML continue for more details on this use case]
+
+The "roaming" mobile node/station:
+
+ - Platform is a netbook, the Dell Inspiron Mini 10 (iM1012-1091OBK), which has a built-in Intel 6250 WiMAX modem card.  
+
+ - Optional: external USB-connected Intel 6250 WiMAX modemx card, the USBMA-6250 (http://www.hwtools.net/Adapter/USBMA-6250.html);  this permits a large, external antenna with improved range.
+
+ - Contains a complete OMF/OML instance, with script, and runs iperf client for performance measurements.
+ 
+The fixed node in the base station:
+
+ - Platform is also a netbook, the Dell Inspiron Mini 10 (iM1012-1091OBK), with a USB-connected Ethernet adaptor, for connection to the WiMAX data network.  
+
+ - Contains an OMF/OML Resource Controller, and runs iperf client for performance measurements. 
+
+                
+=== 5.2 Design throughput experiment using iperf client and server  ===
+
+Multiple options;  all use script running in mobile node using iperf client in "dual mode".
+
+[http://groups.geni.net/geni/wiki/OMF5.3Experiment  continue for more details on throughput experiment design]
+
+
+=== 5.3  Load fixed node and mobile node images, and select experiment script ===
+
+
+A local experimenter logs into BS, and uses an Ex Cntrl Srvc on the BS to:
+
+ - Load "roaming" image onto “roaming” mobile node (that is connected to BS), and select desired experiment script.
+   The "roaming image is available at http://wimax.orbit-lab.org/downloads/GPO_omfexperimentimage.ndz 
+
+ - Load "fixed" image onto fixed node (within the BS).
+
+[http://groups.geni.net/geni/wiki/OMFWiMAXExperiments#a9.Loadingsoftwareonthemobilenode   continue for more details on loading images]
+
+
+
+
+=== 5.4 Setup and conduct experiment ===
+
+The local experimenter logged into the BS, and uses the Ex Cntrl Srvc on the BS to: 
+
+ - Configure the BTS for wireless parameters, VLAN tags, access list of mobile stations;  also directs info from BTS to local Meas Srvc.
+
+ - Starts the experiment within the BTS and the fixed node.
+    
+Then, the local experimenter uses an Exp Cntrl Srvc on the mobile node to:
+
+ - Run the experiment in the mobile node while the roaming, storing data on a Meas Srvr on the mobile node. 
+
+ - While roaming, the local experimenter can start measurement at a point, and view data as it is collected, using visualization service.
+
+ - Next, the script pauses after the measurements at a point are completed. 
+
+ - Next, the local experimenter can interact with the Exp Cntrl Srvc to repeat measurement, or start measurement at next point.
+
+ - Finally the experiment ends, and the roaming data is in the Meas Srvc on the mobile node/station.
+
+Finally, the local experimenter reconnects the mobile node to BS to:
+
+ - Transfer data from the Meas Srvr on the mobile node to the Meas Srvr on the BS, which has been collecting data from the BTS.  
+
+ - At the end, all data is contained on the Meas Srvc on the BS, which can now be processed and plotted.
+
+[http://groups.geni.net/geni/wiki/OMF5.3Experiment continue for more details on conducting experiment]
+
+=== 5.5  Process data in local OML server to plot experiment throughput data ===
+
+When finished, have data in local OML server;  can process data there, are transfer to another Linux server for processing.
+
+Use Ruby script to process data.
+
+Use R to plot experiment throughput data.
+
+[http://groups.geni.net/geni/wiki/OMF5.3ExperimentAnalysis  continue for more details on processing and plotting throughput data]
+
+
+
+
+== 6. Building and installing software on the WiMAX mobile node ==  
+
+[http://groups.geni.net/geni/wiki/OMF5.3Installation  continue]
+
+== 7. Writing experiment script, and throughput experiment example  ==
+
+[http://groups.geni.net/geni/wiki/OMF5.3Experiment  continue]
+
+
+
+==   8. Multiple Throughput Experiments for the "Roaming" MS ==
+
+The experiments are divided into two categories based on the version of oml_iperf they are running.
+
+1. omf-unidirectionalexperiments.tgz contains experiment definitions that use an OMLized iperf which does not support the dual mode. These experiments require explicit coordination between the client and server MS. The software is available at http://software.geni.net/local-sw/
+
+2. omf-bidirectionalexperiments.tgz contains experiment definitions that use the latest OMLized iperf version and customized prototypes, which support the dual or bi-directional mode. These experiments do *not* require explicit coordination between the client and server MS.  The software is available at http://software.geni.net/local-sw/
+
+The following table describes the whole range of experiments developed for the "Roaming" MS use case. The applications such as GPSD and OML_IPERF are part of the image available at http://wimax.orbit-lab.org/downloads/GPO_omfexperimentimage.ndz  and the source code of the experiments can be downloaded from http://software.geni.net/local-sw/ 
+
+||'''Experiment'''||'''GPS Logging'''||'''WiMAX Link-state Logging'''||'''Uplink BW'''||'''Downlink BW'''||'''Simul. Dual-mode BW'''||'''Jitter'''||'''Loss'''||'''Delay'''||'''protocol'''||
+||'''tcp-ul'''||yes||yes||yes||no||no||no||no||no||tcp||
+||'''tcp-dl'''||yes||yes||no||yes||no||no||no||no||tcp||
+||'''tcp-dual'''||yes||yes||no||no||yes||no||no||no||tcp||
+||'''udp-dl'''||yes||yes||no||yes||no||yes||yes||no||udp||
+||'''udp-ul'''||yes||yes||no||yes||no||yes||yes||no||udp||
+||'''udp-dual'''||yes||yes||no||no||yes||yes||yes||no||udp||
+||'''ping-test'''||no||no||no||no||no||no||no||yes||icmp||
+
+
+
+
+==  9.  Loading software on the mobile node ==
+
+        OMF load of disk image, from archive, using PXE service and Frisbee server
+
+
+'''WARNING''': all partitions and all data on the node's disk will be overwritten when you load an image!
+
+This section allows experimenters to load the "roaming" MS image to a Wimax Client e.g. Dell mini netbook ar a stock laptop with a USB Wimax adpater 
+
+- Download the default baseline image http://wimax.orbit-lab.org/downloads/GPO_omfexperimentimage.ndz  and place it in /var/lib/omf-images-5.3 on the central OMF Aggregate Manager machine.
+
+- Ask the system administrator to add the wimax node control mac address to the omf database. For every node in your testbed, you need to add a database record.
+
+- Note the <node_name> provided by your system administrator.
+ 
+- Load the baseline image onto a set of nodes by running 
+
+{{{
+omf load -t <node_name1> <node_name2> -i <image_file>
+}}}
+
+- While you are running omf load for the first time, manually power cycle the nodes that you are imaging. They should now boot into PXE mode and receive instructions to write the hard disk image from the load experiment.
+
+- After loading has finished, the nodes should boot from their local hard drives.
+
+
+----
+
+
+
+
+
+
+==  10.  Conducting an experiment == 
+
+
+=== 10.1 Setting up the BS ===
+
+Directly configure BTS, for wireless parameters, VLAN tags and access list of mobile staions;  refer to Section 9 [http://wimax.orbit-lab.org/ here] for details 
+
+
+
+=== 10.2 Executing the experiment on the MS  ===
+
+Depending on which image you download, the home directory will have the experiment sub directories.
+
+omf-bidirectionalexperiments.tgz
+{{{
+
+README  pingtest  proto  tcp-down  tcp-dual  tcp-up  udp-down  udp-dual  udp-up
+
+}}}
+
+omf-unidirectionalexperiments.tgz
+
+{{{
+README  dl-tcp-test  dl-udp-test  ul-tcp-test
+}}}
+
+
+Change the directory to whichever experiment you want to execute
+
+{{{
+cd udp-dual
+omf exec udp-dual.rb
+}}}
+
+
+The following shows the interaction amongst the different components of the OMF/OML system for the "roaming" MS image.
+
+[[Image(OMFCase3Diagram.png, 50%)]]
+
+To get a detailed look at OMF please refer to http://mytestbed.net/projects/omf .
+
+        
+Each of the OMF throughput experiments follow these steps:
+
+ - runs on a mobile node with stand-alone OMF installation.[[BR]]
+ - connects to the GENI WiMAX base-station using the OMF wimax driver.[[BR]]
+ - measures RSSI, CINR, and Avg. Transmit Power using the OMF wimax driver. [[BR]]
+ - Asks the experimenter for a manual prompt to start the iperf server/client. [[BR]]
+ - The experimenter can either coordinate with a fellow experimenter to start the corresponding iperf client/server.
+ - Otherwise, The experimenter can use the iperf dual mode experiments which do not require coordination between the client and server.
+ - Log GPS Coordinates of the MS while it performs simultaneous or non-simultaneous uplink and downlink UDP throughput/jitter/loss measurements.[[BR]]
+ -  At the end of the experiment,Copy measurements to a given folder.
+
+
+== 11. Processing and plotting measurement data  ==
+
+The measurement points captured using OML are stored in a sqlit3 (*.sq3) file. We describe one way of analyzing the measurement points from the sqlite3 file by using the open source utility "R"
+Click [http://groups.geni.net/geni/wiki/OMF5.3ExperimentAnalysis  continue] to proceed to this section.
+
+
+
+== 12.  WiMAX throughput data  ==
+
+Here are sample graphs from the TCP and UDP experiments conducted around the BBN campus that are generated in Section 11.
+
+[[Image(udpgraph1.png, 50%)]]   
+[[Image(tcpgraph1.png, 50%)]]   
+[[Image(tcpgraph2.png, 50%)]]   
+
+
+=== 12.1 Saving the Experiment Image === 
+                 
+         
+        The experiment described above is a sample. The motivation is for experimenters to develop new experiments using the framework described above. Once the experimenters have modified the scripts and created new experiments on the Wimax MS, they will need to save their work for repeating experiments. 
+         
+        - On the OMF aggregate manager machine 
+                 
+        {{{ 
+        omf save -n <node_name> 
+        }}} 
+                 
+        - Restart the Wimax MS and the MS will boot from PXE 
+         
+        - The image will be saved on the OMF aggregate manager machine under /var/lib/omf-images-5.3 
+                 
+        - Rename the image and re-use if needed. 
+ 
+
+
+
+== 13.  Next steps  ==
+
+        a)  Complete use case 3
+
+                Use script and EC in BS to configure BTS, and to configure fixed node
+
+                Gather data from BTS (NEC hardware) into OML server
+
+                Merge data from OML servers in BS and mobile node, and process
+
+        b)  Fix Login service, setup remote access to the base station
+
+        c)  Finish use case 2
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+