Changes between Initial Version and Version 1 of OMFWiMAXExperiments

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



  • OMFWiMAXExperiments

    v1 v1  
     4= GENI WiMAX Experiments Using OMF/OML =
     6== 1.  GENI WiMAX deployment goals  ==
     8The goals of GENI WiMAX meso-scale deployments at campus sites are to:
     10 - 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.)
     12 - 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.)
     14 - Support access to network applications using WiMAX-connected mobile stations on the campus.  (This is equivalent to providing 4G service on the campus.)
     16A 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:
     18 - Provide access to the extensive OMF/OML experiment control and measurement features that have been developed at WINLAB and NICTA specifically for wireless testbeds.
     20 - Provide a common environement for WiMAX experiments, which should facilitate sharing experiment design and scripts among GENI WiMAX experimenters.
     22 - 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.
     24 - Provide a way for a WiMAX site to be shared (i.e., virtualized or sliced) among several experiments at the same time.
     26== 2.  Guide to this document ==
     28Like 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:
     30 - 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.
     32 - 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.
     34 - 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.
     36For all users of this document:
     38 - Section 3 provides an overview of the OMF/OML configuration and experiment process.
     40 - Section 4 provides an overview of the GENI WiMAX base station configuration and the expected use cases.
     42 - Section 5 provides an overview of a basic WiMAX throughput experiment.
     44For 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:
     46 - 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.
     48 - 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.
     50 - Section 8 explains several variations on the basic WiMAX throughput experiment that have been written and tested.
     52 - Section 9  explains how to load the archived image for an experiment onto a mobile station node.
     54 - Section 10 explains how to conduct an experiment.
     56 - Section 11 explains how to process and plot measurement data using OML and some additional scripts.
     58 - Section 12 provides a brief overview of WiMAX throughput data from recent experiments at the Raytheon BBN site
     60For an experimenter who wants to get started using OMF/OML, they should follow these sections:
     62 - Request an orbit account at, if you don't already have one to get access to the experiment image.
     64 - Section 9  explains how to load the archived image for an experiment onto a mobile station node.
     66 - Section 10 explains how to conduct an experiment.
     68 - Section 11 explains how to process and plot measurement data using OML and some additional scripts.
     70 - Section 12 provides a brief overview of WiMAX throughput data from recent experiments at the Raytheon BBN site
     72For an experimenter that want to take the basic experiment and extend it to meet their own needs, they should consult these sections:
     74 - Section 13 explains how to write an experiment script for a new experiment
     76 - 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.
     80== 3.  OMF/OML configuration and experiment process  ==
     82The following sections use material from the OMF/OML wikis to explain the OMF/OML framework, components and experiment steps.
     84=== 3.1  OMF/OML framework ===
     86OMF is a generic framework for controlling and managing networking testbeds.
     88The main motivation behind using OMF/OML is that they provide for a unified and standard way of performing experiments and collecting data.
     90The 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 [  usage overview].
     94OMF is written in Ruby.
     96The 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.
     98OML 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.
     100OMF and OML are independent from each other, but it is recommended that you use OML if you want to set up an OMF testbed.
     102Creating an OMF-enabled testbed involves installing various OMF components whose tasks we briefly describe next.
     104Later 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.
     106For more detailed information on OMF, OML and their applications and use-cases please refer to [ my testbed wiki].
     108===  3.2  OMF/OML components ===
     110The 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 [ glossary].
     114===  3.3  OMF/OML experiment steps  ===
     116These are the steps and interactions that occur when an experiment is ran with OMF:
     118    * 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.
     120    * 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
     122    * 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...)
     124    * When the resources are ready, the EC sends commands to the Resource Controllers (RCs), which run on each of these resources
     126    * 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.
     128    * At this stage the experiment is "running"...
     130    * 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.
     132    * 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.
     134    * 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: [ analyzing results]. Later in this document, we describe how we use a combination of Ruby/bash scripts and R scripts to plot collected data.
     139== 4.  GENI WiMAX base station configuration and use cases  ==
     141The GENI WiMAX base station configuration is summarized in [ base station configuration].
     143[[Image(Visio-062811b_pp5-6_WiMAXSystemOverview_Page_1.jpg, 90%)]]
     146The WiMAX base station (BS) includes:
     148 - NEC base station transceiver system (BTS) indoor and outdoor units, with connections from the outdoor unit to the antenna.
     150 - Base station server, that hosts the data path software
     152 - Data network, that connects data path to the GENI backbone network.
     154 - 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.
     156 - 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.
     158 - Control network, that carries control messages within the base station, between the base station, experiment control and authentication servers.
     160Each base station is installed at a campus site by the PI/staff, and operated for use by local and/or remote experimenters.
     162In 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).
     164There are three use cases which each base station should support:
     166 - Use Case 1:  Service from a local or Internet application
     168 - Use Case 2:  Experiment with a “fixed” mobile node/station using OMF/OML
     170 - Use Case 3:  Experiment with a “roaming” mobile node/station using OMF/OML
     173[  continue to more on the use cases]
     177== 5.  Basic WiMAX throughput experiment  ==
     179This section provides a high-level view of designing, configuring and conducting a basic WiMAX throughput measurement.
     181=== 5.1  Configuration for experiment with a “roaming” mobile node/station (use case 3) ===
     183This 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.
     185[ continue for more details on this use case]
     187The "roaming" mobile node/station:
     189 - Platform is a netbook, the Dell Inspiron Mini 10 (iM1012-1091OBK), which has a built-in Intel 6250 WiMAX modem card. 
     191 - Optional: external USB-connected Intel 6250 WiMAX modemx card, the USBMA-6250 (;  this permits a large, external antenna with improved range.
     193 - Contains a complete OMF/OML instance, with script, and runs iperf client for performance measurements.
     195The fixed node in the base station:
     197 - 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. 
     199 - Contains an OMF/OML Resource Controller, and runs iperf client for performance measurements.
     202=== 5.2 Design throughput experiment using iperf client and server  ===
     204Multiple options;  all use script running in mobile node using iperf client in "dual mode".
     206[  continue for more details on throughput experiment design]
     209=== 5.3  Load fixed node and mobile node images, and select experiment script ===
     212A local experimenter logs into BS, and uses an Ex Cntrl Srvc on the BS to:
     214 - Load "roaming" image onto “roaming” mobile node (that is connected to BS), and select desired experiment script.
     215   The "roaming image is available at
     217 - Load "fixed" image onto fixed node (within the BS).
     219[   continue for more details on loading images]
     224=== 5.4 Setup and conduct experiment ===
     226The local experimenter logged into the BS, and uses the Ex Cntrl Srvc on the BS to:
     228 - Configure the BTS for wireless parameters, VLAN tags, access list of mobile stations;  also directs info from BTS to local Meas Srvc.
     230 - Starts the experiment within the BTS and the fixed node.
     232Then, the local experimenter uses an Exp Cntrl Srvc on the mobile node to:
     234 - Run the experiment in the mobile node while the roaming, storing data on a Meas Srvr on the mobile node.
     236 - While roaming, the local experimenter can start measurement at a point, and view data as it is collected, using visualization service.
     238 - Next, the script pauses after the measurements at a point are completed.
     240 - Next, the local experimenter can interact with the Exp Cntrl Srvc to repeat measurement, or start measurement at next point.
     242 - Finally the experiment ends, and the roaming data is in the Meas Srvc on the mobile node/station.
     244Finally, the local experimenter reconnects the mobile node to BS to:
     246 - 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. 
     248 - At the end, all data is contained on the Meas Srvc on the BS, which can now be processed and plotted.
     250[ continue for more details on conducting experiment]
     252=== 5.5  Process data in local OML server to plot experiment throughput data ===
     254When finished, have data in local OML server;  can process data there, are transfer to another Linux server for processing.
     256Use Ruby script to process data.
     258Use R to plot experiment throughput data.
     260[  continue for more details on processing and plotting throughput data]
     265== 6. Building and installing software on the WiMAX mobile node == 
     267[  continue]
     269== 7. Writing experiment script, and throughput experiment example  ==
     271[  continue]
     275==   8. Multiple Throughput Experiments for the "Roaming" MS ==
     277The experiments are divided into two categories based on the version of oml_iperf they are running.
     2791. 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
     2812. 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
     283The 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  and the source code of the experiments can be downloaded from
     285||'''Experiment'''||'''GPS Logging'''||'''WiMAX Link-state Logging'''||'''Uplink BW'''||'''Downlink BW'''||'''Simul. Dual-mode BW'''||'''Jitter'''||'''Loss'''||'''Delay'''||'''protocol'''||
     297==  9.  Loading software on the mobile node ==
     299        OMF load of disk image, from archive, using PXE service and Frisbee server
     302'''WARNING''': all partitions and all data on the node's disk will be overwritten when you load an image!
     304This 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
     306- Download the default baseline image  and place it in /var/lib/omf-images-5.3 on the central OMF Aggregate Manager machine.
     308- 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.
     310- Note the <node_name> provided by your system administrator.
     312- Load the baseline image onto a set of nodes by running
     315omf load -t <node_name1> <node_name2> -i <image_file>
     318- 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.
     320- After loading has finished, the nodes should boot from their local hard drives.
     330==  10.  Conducting an experiment ==
     333=== 10.1 Setting up the BS ===
     335Directly configure BTS, for wireless parameters, VLAN tags and access list of mobile staions;  refer to Section 9 [ here] for details
     339=== 10.2 Executing the experiment on the MS  ===
     341Depending on which image you download, the home directory will have the experiment sub directories.
     346README  pingtest  proto  tcp-down  tcp-dual  tcp-up  udp-down  udp-dual  udp-up
     353README  dl-tcp-test  dl-udp-test  ul-tcp-test
     357Change the directory to whichever experiment you want to execute
     360cd udp-dual
     361omf exec udp-dual.rb
     365The following shows the interaction amongst the different components of the OMF/OML system for the "roaming" MS image.
     367[[Image(OMFCase3Diagram.png, 50%)]]
     369To get a detailed look at OMF please refer to .
     372Each of the OMF throughput experiments follow these steps:
     374 - runs on a mobile node with stand-alone OMF installation.[[BR]]
     375 - connects to the GENI WiMAX base-station using the OMF wimax driver.[[BR]]
     376 - measures RSSI, CINR, and Avg. Transmit Power using the OMF wimax driver. [[BR]]
     377 - Asks the experimenter for a manual prompt to start the iperf server/client. [[BR]]
     378 - The experimenter can either coordinate with a fellow experimenter to start the corresponding iperf client/server.
     379 - Otherwise, The experimenter can use the iperf dual mode experiments which do not require coordination between the client and server.
     380 - Log GPS Coordinates of the MS while it performs simultaneous or non-simultaneous uplink and downlink UDP throughput/jitter/loss measurements.[[BR]]
     381 -  At the end of the experiment,Copy measurements to a given folder.
     384== 11. Processing and plotting measurement data  ==
     386The 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"
     387Click [  continue] to proceed to this section.
     391== 12.  WiMAX throughput data  ==
     393Here are sample graphs from the TCP and UDP experiments conducted around the BBN campus that are generated in Section 11.
     395[[Image(udpgraph1.png, 50%)]]   
     396[[Image(tcpgraph1.png, 50%)]]   
     397[[Image(tcpgraph2.png, 50%)]]   
     400=== 12.1 Saving the Experiment Image ===
     403        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.
     405        - On the OMF aggregate manager machine
     407        {{{
     408        omf save -n <node_name>
     409        }}}
     411        - Restart the Wimax MS and the MS will boot from PXE
     413        - The image will be saved on the OMF aggregate manager machine under /var/lib/omf-images-5.3
     415        - Rename the image and re-use if needed.
     420== 13.  Next steps  ==
     422        a)  Complete use case 3
     424                Use script and EC in BS to configure BTS, and to configure fixed node
     426                Gather data from BTS (NEC hardware) into OML server
     428                Merge data from OML servers in BS and mobile node, and process
     430        b)  Fix Login service, setup remote access to the base station
     432        c)  Finish use case 2