Version 8 (modified by, 13 years ago) (diff)


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:

  • 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 usage overview.

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 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 glossary.

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: 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 base station configuration.

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

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.

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.
  • 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 server 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".

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 "fixed" image onto fixed node (within the BS).

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.

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.

continue for more details on processing and plotting throughput data

6. Building and installing software on the WiMAX mobile node


7. Writing experiment script, and throughput experiment example


8. Multiple throughput experiments for the "roaming" MS

The following table describes the whole range of experiments developed for the "Roaming" MS use case.

ExperimentGPS LoggingWiMAX Link-state LoggingUplink BWDownlink BWSimul. Dual-mode BWJitterLossDelayprotocol

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
  1. 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

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

  • 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 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.


README  pingtest  proto  tcp-down  tcp-dual  tcp-up  udp-down  udp-dual  udp-up


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.

To get a detailed look at OMF please refer to .

Each of the OMF throughput experiments follow these steps:

  • runs on a mobile node with stand-alone OMF installation.
  • connects to the GENI WiMAX base-station using the OMF wimax driver.
  • measures RSSI, CINR, and Avg. Transmit Power using the OMF wimax driver.
  • Asks the experimenter for a manual prompt to start the iperf server/client.
  • 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.
  • 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 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.

13. Developing a new experiment and 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.

14. 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

c) Finish use case 2

Attachments (5)

Download all attachments as: .zip