Changes between Initial Version and Version 1 of OMFWiMAXExperiments


Ignore:
Timestamp:
09/07/11 17:17:22 (11 years ago)
Author:
agosain@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • OMFWiMAXExperiments

    v1 v1  
     1[[PageOutline]]
     2
     3
     4= GENI WiMAX Experiments Using OMF/OML =
     5
     6== 1.  GENI WiMAX deployment goals  ==
     7
     8The goals of GENI WiMAX meso-scale deployments at campus sites are to:
     9
     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.)
     11
     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.)
     13
     14 - Support access to network applications using WiMAX-connected mobile stations on the campus.  (This is equivalent to providing 4G service on the campus.)
     15
     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:
     17
     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.
     19
     20 - Provide a common environement for WiMAX experiments, which should facilitate sharing experiment design and scripts among GENI WiMAX experimenters.
     21
     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.
     23
     24 - Provide a way for a WiMAX site to be shared (i.e., virtualized or sliced) among several experiments at the same time.
     25
     26== 2.  Guide to this document ==
     27
     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:
     29
     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.
     31
     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.
     33
     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.
     35
     36For all users of this document:
     37
     38 - Section 3 provides an overview of the OMF/OML configuration and experiment process.
     39
     40 - Section 4 provides an overview of the GENI WiMAX base station configuration and the expected use cases.
     41
     42 - Section 5 provides an overview of a basic WiMAX throughput experiment.
     43
     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:
     45
     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.
     47
     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.
     49
     50 - Section 8 explains several variations on the basic WiMAX throughput experiment that have been written and tested.
     51
     52 - Section 9  explains how to load the archived image for an experiment onto a mobile station node.
     53
     54 - Section 10 explains how to conduct an experiment.
     55
     56 - Section 11 explains how to process and plot measurement data using OML and some additional scripts.
     57
     58 - Section 12 provides a brief overview of WiMAX throughput data from recent experiments at the Raytheon BBN site
     59
     60For an experimenter who wants to get started using OMF/OML, they should follow these sections:
     61
     62 - 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.
     63
     64 - Section 9  explains how to load the archived image for an experiment onto a mobile station node.
     65
     66 - Section 10 explains how to conduct an experiment.
     67
     68 - Section 11 explains how to process and plot measurement data using OML and some additional scripts.
     69
     70 - Section 12 provides a brief overview of WiMAX throughput data from recent experiments at the Raytheon BBN site
     71
     72For an experimenter that want to take the basic experiment and extend it to meet their own needs, they should consult these sections:
     73
     74 - Section 13 explains how to write an experiment script for a new experiment
     75
     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.
     77
     78
     79 
     80== 3.  OMF/OML configuration and experiment process  ==
     81
     82The following sections use material from the OMF/OML wikis to explain the OMF/OML framework, components and experiment steps.
     83
     84=== 3.1  OMF/OML framework ===
     85
     86OMF is a generic framework for controlling and managing networking testbeds.
     87
     88The main motivation behind using OMF/OML is that they provide for a unified and standard way of performing experiments and collecting data.
     89
     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 [http://mytestbed.net/projects/omf/wiki/UsageOverview  usage overview].
     91
     92[[Image(http://mytestbed.net/attachments/download/203)]]
     93
     94OMF is written in Ruby.
     95
     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.
     97
     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.
     99
     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.
     101
     102Creating an OMF-enabled testbed involves installing various OMF components whose tasks we briefly describe next.
     103
     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.
     105
     106For more detailed information on OMF, OML and their applications and use-cases please refer to [http://mytestbed.net/ my testbed wiki].
     107
     108===  3.2  OMF/OML components ===
     109
     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 [http://mytestbed.net/projects/omf/wiki/Glossary glossary].
     111
     112[[Image(http://mytestbed.net/attachments/download/201)]]
     113
     114===  3.3  OMF/OML experiment steps  ===
     115
     116These are the steps and interactions that occur when an experiment is ran with OMF:
     117
     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.
     119
     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
     121
     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...)
     123
     124    * When the resources are ready, the EC sends commands to the Resource Controllers (RCs), which run on each of these resources
     125
     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.
     127
     128    * At this stage the experiment is "running"...
     129
     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.
     131   
     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.
     133
     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: [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.
     135
     136
     137
     138
     139== 4.  GENI WiMAX base station configuration and use cases  ==
     140
     141The GENI WiMAX base station configuration is summarized in [http://wimax.orbit-lab.org/ base station configuration].
     142 
     143[[Image(Visio-062811b_pp5-6_WiMAXSystemOverview_Page_1.jpg, 90%)]]
     144
     145
     146The WiMAX base station (BS) includes:
     147
     148 - NEC base station transceiver system (BTS) indoor and outdoor units, with connections from the outdoor unit to the antenna.
     149
     150 - Base station server, that hosts the data path software
     151
     152 - Data network, that connects data path to the GENI backbone network.
     153
     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.
     155
     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.
     157
     158 - Control network, that carries control messages within the base station, between the base station, experiment control and authentication servers.
     159
     160Each base station is installed at a campus site by the PI/staff, and operated for use by local and/or remote experimenters.
     161
     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).
     163
     164There are three use cases which each base station should support:
     165
     166 - Use Case 1:  Service from a local or Internet application
     167
     168 - Use Case 2:  Experiment with a “fixed” mobile node/station using OMF/OML
     169
     170 - Use Case 3:  Experiment with a “roaming” mobile node/station using OMF/OML
     171
     172
     173[http://groups.geni.net/geni/wiki/GENIWimaxUseCases  continue to more on the use cases]
     174
     175
     176
     177== 5.  Basic WiMAX throughput experiment  ==
     178
     179This section provides a high-level view of designing, configuring and conducting a basic WiMAX throughput measurement.
     180
     181=== 5.1  Configuration for experiment with a “roaming” mobile node/station (use case 3) ===
     182
     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.
     184
     185[http://groups.geni.net/geni/wiki/GENIWimaxUseCases#a4.3UseCase3:ExperimentwitharoamingmobilenodestationusingOMFOML continue for more details on this use case]
     186
     187The "roaming" mobile node/station:
     188
     189 - Platform is a netbook, the Dell Inspiron Mini 10 (iM1012-1091OBK), which has a built-in Intel 6250 WiMAX modem card. 
     190
     191 - 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.
     192
     193 - Contains a complete OMF/OML instance, with script, and runs iperf client for performance measurements.
     194 
     195The fixed node in the base station:
     196
     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. 
     198
     199 - Contains an OMF/OML Resource Controller, and runs iperf client for performance measurements.
     200
     201               
     202=== 5.2 Design throughput experiment using iperf client and server  ===
     203
     204Multiple options;  all use script running in mobile node using iperf client in "dual mode".
     205
     206[http://groups.geni.net/geni/wiki/OMF5.3Experiment  continue for more details on throughput experiment design]
     207
     208
     209=== 5.3  Load fixed node and mobile node images, and select experiment script ===
     210
     211
     212A local experimenter logs into BS, and uses an Ex Cntrl Srvc on the BS to:
     213
     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 http://wimax.orbit-lab.org/downloads/GPO_omfexperimentimage.ndz
     216
     217 - Load "fixed" image onto fixed node (within the BS).
     218
     219[http://groups.geni.net/geni/wiki/OMFWiMAXExperiments#a9.Loadingsoftwareonthemobilenode   continue for more details on loading images]
     220
     221
     222
     223
     224=== 5.4 Setup and conduct experiment ===
     225
     226The local experimenter logged into the BS, and uses the Ex Cntrl Srvc on the BS to:
     227
     228 - Configure the BTS for wireless parameters, VLAN tags, access list of mobile stations;  also directs info from BTS to local Meas Srvc.
     229
     230 - Starts the experiment within the BTS and the fixed node.
     231   
     232Then, the local experimenter uses an Exp Cntrl Srvc on the mobile node to:
     233
     234 - Run the experiment in the mobile node while the roaming, storing data on a Meas Srvr on the mobile node.
     235
     236 - While roaming, the local experimenter can start measurement at a point, and view data as it is collected, using visualization service.
     237
     238 - Next, the script pauses after the measurements at a point are completed.
     239
     240 - Next, the local experimenter can interact with the Exp Cntrl Srvc to repeat measurement, or start measurement at next point.
     241
     242 - Finally the experiment ends, and the roaming data is in the Meas Srvc on the mobile node/station.
     243
     244Finally, the local experimenter reconnects the mobile node to BS to:
     245
     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. 
     247
     248 - At the end, all data is contained on the Meas Srvc on the BS, which can now be processed and plotted.
     249
     250[http://groups.geni.net/geni/wiki/OMF5.3Experiment continue for more details on conducting experiment]
     251
     252=== 5.5  Process data in local OML server to plot experiment throughput data ===
     253
     254When finished, have data in local OML server;  can process data there, are transfer to another Linux server for processing.
     255
     256Use Ruby script to process data.
     257
     258Use R to plot experiment throughput data.
     259
     260[http://groups.geni.net/geni/wiki/OMF5.3ExperimentAnalysis  continue for more details on processing and plotting throughput data]
     261
     262
     263
     264
     265== 6. Building and installing software on the WiMAX mobile node == 
     266
     267[http://groups.geni.net/geni/wiki/OMF5.3Installation  continue]
     268
     269== 7. Writing experiment script, and throughput experiment example  ==
     270
     271[http://groups.geni.net/geni/wiki/OMF5.3Experiment  continue]
     272
     273
     274
     275==   8. Multiple Throughput Experiments for the "Roaming" MS ==
     276
     277The experiments are divided into two categories based on the version of oml_iperf they are running.
     278
     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 http://software.geni.net/local-sw/
     280
     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 http://software.geni.net/local-sw/
     282
     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 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/
     284
     285||'''Experiment'''||'''GPS Logging'''||'''WiMAX Link-state Logging'''||'''Uplink BW'''||'''Downlink BW'''||'''Simul. Dual-mode BW'''||'''Jitter'''||'''Loss'''||'''Delay'''||'''protocol'''||
     286||'''tcp-ul'''||yes||yes||yes||no||no||no||no||no||tcp||
     287||'''tcp-dl'''||yes||yes||no||yes||no||no||no||no||tcp||
     288||'''tcp-dual'''||yes||yes||no||no||yes||no||no||no||tcp||
     289||'''udp-dl'''||yes||yes||no||yes||no||yes||yes||no||udp||
     290||'''udp-ul'''||yes||yes||no||yes||no||yes||yes||no||udp||
     291||'''udp-dual'''||yes||yes||no||no||yes||yes||yes||no||udp||
     292||'''ping-test'''||no||no||no||no||no||no||no||yes||icmp||
     293
     294
     295
     296
     297==  9.  Loading software on the mobile node ==
     298
     299        OMF load of disk image, from archive, using PXE service and Frisbee server
     300
     301
     302'''WARNING''': all partitions and all data on the node's disk will be overwritten when you load an image!
     303
     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
     305
     306- 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.
     307
     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.
     309
     310- Note the <node_name> provided by your system administrator.
     311 
     312- Load the baseline image onto a set of nodes by running
     313
     314{{{
     315omf load -t <node_name1> <node_name2> -i <image_file>
     316}}}
     317
     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.
     319
     320- After loading has finished, the nodes should boot from their local hard drives.
     321
     322
     323----
     324
     325
     326
     327
     328
     329
     330==  10.  Conducting an experiment ==
     331
     332
     333=== 10.1 Setting up the BS ===
     334
     335Directly 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
     336
     337
     338
     339=== 10.2 Executing the experiment on the MS  ===
     340
     341Depending on which image you download, the home directory will have the experiment sub directories.
     342
     343omf-bidirectionalexperiments.tgz
     344{{{
     345
     346README  pingtest  proto  tcp-down  tcp-dual  tcp-up  udp-down  udp-dual  udp-up
     347
     348}}}
     349
     350omf-unidirectionalexperiments.tgz
     351
     352{{{
     353README  dl-tcp-test  dl-udp-test  ul-tcp-test
     354}}}
     355
     356
     357Change the directory to whichever experiment you want to execute
     358
     359{{{
     360cd udp-dual
     361omf exec udp-dual.rb
     362}}}
     363
     364
     365The following shows the interaction amongst the different components of the OMF/OML system for the "roaming" MS image.
     366
     367[[Image(OMFCase3Diagram.png, 50%)]]
     368
     369To get a detailed look at OMF please refer to http://mytestbed.net/projects/omf .
     370
     371       
     372Each of the OMF throughput experiments follow these steps:
     373
     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.
     382
     383
     384== 11. Processing and plotting measurement data  ==
     385
     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 [http://groups.geni.net/geni/wiki/OMF5.3ExperimentAnalysis  continue] to proceed to this section.
     388
     389
     390
     391== 12.  WiMAX throughput data  ==
     392
     393Here are sample graphs from the TCP and UDP experiments conducted around the BBN campus that are generated in Section 11.
     394
     395[[Image(udpgraph1.png, 50%)]]   
     396[[Image(tcpgraph1.png, 50%)]]   
     397[[Image(tcpgraph2.png, 50%)]]   
     398
     399
     400=== 12.1 Saving the Experiment Image ===
     401                 
     402         
     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.
     404         
     405        - On the OMF aggregate manager machine
     406                 
     407        {{{
     408        omf save -n <node_name>
     409        }}}
     410                 
     411        - Restart the Wimax MS and the MS will boot from PXE
     412         
     413        - The image will be saved on the OMF aggregate manager machine under /var/lib/omf-images-5.3
     414                 
     415        - Rename the image and re-use if needed.
     416 
     417
     418
     419
     420== 13.  Next steps  ==
     421
     422        a)  Complete use case 3
     423
     424                Use script and EC in BS to configure BTS, and to configure fixed node
     425
     426                Gather data from BTS (NEC hardware) into OML server
     427
     428                Merge data from OML servers in BS and mobile node, and process
     429
     430        b)  Fix Login service, setup remote access to the base station
     431
     432        c)  Finish use case 2
     433
     434
     435
     436
     437
     438
     439
     440
     441
     442
     443
     444
     445
     446
     447
     448
     449
     450
     451
     452
     453
     454
     455
     456
     457
     458
     459
     460
     461
     462
     463
     464
     465
     466
     467
     468
     469
     470
     471
     472
     473
     474
     475
     476
     477