= WiMAX Tutorial 2: OMF based WiMAX experiments =


[[TOC(Tutorials/WiMAX/*, depth=2)]] 

This is a continuation of the [wiki:Tutorials/WiMAX/Tutorial1 WiMAX Tutorial and Primer].

== Prerequisites == 

This tutorial series assumes you have an [http://www.orbit-lab.org/userManagement/register ORBIT account], have [https://www.orbit-lab.org/schedule/ scheduled a session] on the ORBIT test bed, are familiar with [http://en.wikipedia.org/wiki/Secure_Shell SSH]'ing [http://www.orbit-lab.org/wiki/Tutorial/HelloWorld#a4.RunningtheHelloWorldexperiment into the test bed itself, and are familiar with the basics of running ORBIT experiments]. If you have not done these things yet, you may wish to do so before taking a look at this slightly more advanced experiment. If you are unfamiliar with or are entirely new to ORBIT, you may wish to start [http://www.orbit-lab.org/ here].


== Difficulty ==

This tutorial is of intermediate difficulty. In addition to the knowledge from the previous tutorial, basic understanding of the [http://mytestbed.net/projects/omf/wiki/OEDL-5-3 ORBIT Experiment Description Language] (OEDL) and its source language, [http://www.ruby-lang.org/en/ Ruby] (and especially [http://rubylearning.com/satishtalim/ruby_blocks.html blocks] within Ruby), are '''strongly''' recommended. Furthermore, fluency in low-level computer networking concepts such as IP is assumed. Familiarity with the networking diagnostic tool ''iperf'' will be helpful but is not required.
----

== About This Experiment ==

This tutorial section is adapted from the tutorials at [http://witestlab.poly.edu/index.php/tutorial.html NYU Poly WITest lab] and expanded from the more concise [http://wimax.orbit-lab.org/wiki/WiMAX/30/07#a18.GEC13:TutorialsfromPolyNYU ORBIT adaptations] done previously. As before, we will perform our experiment on Sandbox 4, providing some background information at each step. For more information, see the relevant documentation for each step at one of the source websites. '''This experiment uses OMF Version 5.3, also known as omf-5.3.'''

----

= Experiment: Check Connection Status, Then Send TCP Packets =

----
=== The Code ===

The following are the links to experiment Description script and the underlying codes. In the interest of saving space, they are not posted directly to this page.

 * [http://www.orbit-lab.org/attachment/wiki/Tutorials/WiMAX/Tutorial2/wimax_ed.rb Experiment Description] [[BR]]
 * [http://www.orbit-lab.org/attachment/wiki/Tutorials/WiMAX/Tutorial2/iperf.rb iperf app description] [[BR]]
 * [http://www.orbit-lab.org/attachment/wiki/Tutorials/WiMAX/Tutorial2/wimaxcu_app.rb wimaxcu_app description] [[BR]]
 * [http://www.orbit-lab.org/attachment/wiki/Tutorials/WiMAX/Tutorial2/wmxstat wmxstat program] [[BR]]


At this point, we will give a primer on OMF and some of the functions inside the experiment. To skip to the experiment itself, [http://www.orbit-lab.org/wiki/Tutorials/WiMAX/Tutorial2#LaunchExperiment click here].

----
== Background Information ==

Experiments performed on ORBIT (specifically) and all GENI wireless test-beds are managed by what was once called the ORBIT Management Framework, now simply known as [http://mytestbed.net/projects/omf/wiki/OMF_Main_Page OMF]. (For background information on frameworks, see [http://en.wikipedia.org/wiki/Software_framework Wikipedia].) Simply put, a framework provides programs which perform all the generic functions a programmer would otherwise need to code at a given ''layer'' to obtain functional applications. This includes programs that check various paths, run subprograms, collect data, check validity, sanitize inputs, and more. Together with its sister program, formerly known as the ORBIT Measurement Library (now known as OML), OMF is used to run experiments from start to finish.

But how is an experiment defined? At ORBIT, the aforementioned OEDL is used to mark up a script describing an experiment. Instead of having to manually define every subject and action, though, the framework (OMF) "knows" how to generically do most tasks. The experimenter simply uses OEDL functions and syntax to delineate a specific experiment. The script is then loaded onto a testbed and executed using OMF. 

----

== Dissecting the Experiment ==

{{{
#!ruby
defGroup('first_node', 'node1-4.sb4.orbit-lab.org')
}}}

''defGroup'' is a method which creates groups of resources (usually nodes), gives them a URI for later identification (first parameter), and identifies these resources by the second parameter (in OMF version 5.3, they are identified as above). The (optional) third parameter is a block argument. 
 * We do not pass a block as an explicit parameter here, because it follows the method. 

{{{
#!ruby
defGroup('first_node', 'node1-4.sb4.orbit-lab.org') do |node|
  node.net.x0.profile = '51'
  node.net.x0.ip = '10.41.14.4'
  node.net.x0.netmask = '255.255.0.0'
  node.addApplication("wimaxcu_app") do |app|
    app.measure('status_link')
  end
  ...
end
}}}

 * As those familiar with ''Ruby'' will note, this method receives additional instructions from a block. Here, ''node'' is a dummy variable referring to the group itself, although the exact behavior of ''Ruby'' blocks is outside the scope (pun intended) of this discussion.

 * Here, ''net.x0.profile'' configures the WiMAX network profile default as 51. The node will prefer this network when searching for available connections. This is the same as the command ''"wimaxcu connect network 51"''.

 * ''net.x0.ip'', ''net.x0.netmask'', and ''net.x0.up'' all perform the eponymous ''ifconfig'' operations.

''addApplication'' gives a group instructions to use the defined application in the specified manner. The principle parameter is the URI of the predefined application. 

 * The ''wimaxcu_app'' application tells OMF to load the application described in the ''wimaxcu_app.rb'' - in this case, the ''wmxstat'' application.

 * ''app.measure('status_link')'' tells this application to use its predefined code to measure the 'status_link' property. OML will save these data for later. The exact behavior of this application is outside the scope of this discussion; suffice it to say that the implementation of the application is defined in the ''wimaxcu_app.rb'' and ''wmxstat'' programs mentioned previously.

{{{
#!ruby
  node.addApplication("test:app:iperf") do |app|
    app.setProperty('client', '10.41.14.6', true)
    app.setProperty('mss', 536) # Do not raise above 600
    app.setProperty('interval', 1)
    app.setProperty('bind', "10.41.14.4")
    app.measure('TCP_Info', samples => 1)
  end
}}}


This adds the ''iperf'' application functionality to the group. ''iperf'' is an application which measures connectivity by sending data packets between groups. To see a complete list of possible parameters and measurements available, examine the source code of the ''iperf'' wrapper applications. 

The ''iperf'' application contains two types of functions: properties (parameters) and measurements (different data collection tools). Properties simply add various optional and required parameters to the ''iperf'' call. Measurements specify data to be collected by OML, and are the "interesting" part of the experiment.

''setProperty'' is fairly self-explanatory. It simply configures individual parameters germane to the operation of iperf, as defined in the wrapper application.

''app.measure'' collects the data and leverages OML to save them to an external service. A measurement type should be specified to ensure that data is collected properly.
----
== Launch Experiment ==

Before launching the experiment, please download the experiment description file (wimax_ed.rb) and the application description files (iperf.rb and wimaxcu_app.rb) to the console:

{{{
wget http://www.orbit-lab.org/raw-attachment/wiki/Tutorials/WiMAX/Tutorial2/iperf.rb
wget http://www.orbit-lab.org/raw-attachment/wiki/Tutorials/WiMAX/Tutorial2/wimaxcu_app.rb
wget http://www.orbit-lab.org/raw-attachment/wiki/Tutorials/WiMAX/Tutorial2/wimax_ed.rb
}}}

Reset the base station to default settings, and then image the nodes, as before. 

{{{
omf load -i wmx-tutorial.ndz -t node1-6.sb4.orbit-lab.org,node1-4.sb4.orbit-lab.org
}}}

Optionally, double check that the image loaded correctly.

Now, turn the nodes on and launch the experiment!

{{{
omf tell -a on -t node1-4.sb4.orbit-lab.org,node1-6.sb4.orbit-lab.org
omf exec wimax_ed.rb
}}}

[http://orbit-lab.org/wiki/Tutorials/WiMAX/Tutorial2#RetrievingResults Skip to Retrieving Data]

----
== Troubleshooting Runtime Problems ==

There are a few problems which may arise during the course of attempting to run this experiment. Usually, they are the result of fragmentation of framework/operational code. Below are some errors encountered, and suggested solutions.

 * The node handler gives an error stating the network profile failed to configure, but then the raised error describes an ongoing connection status -- this is most likely a false alarm caused by running an experiment over a predefined configuration. The node reconfigures, but believes that the configuration status is an error message. 

[[Image(profileerror.png)]]


 * The experiment "hiccups" and groups/nodes cannot be accessed or configured -- sometimes this is nothing more than a hiccup in accessing a node. However, occasionally it means you've forgotten to turn the nodes on. The worst-case scenario is that the nodes are experiencing connectivity issues. The best way to confirm it is the latter and not the former is to return to the previous experiment and confirm whether it is possible to ping the nodes. (They need to be manually configured despite having the experiment script run partially.)
----

== Retrieving Results ==

Data is collected during experimentation and pushed to a server using an experiment ID indicated during the initiation and conclusion of each experiment. This ID is important, as it is used to recover experiment results and even view them in real-time. (Server names vary with test beds. This server name is specific to ORBIT.)

To recover experiment data to the local machine, and using the experiment ID:

{{{
wget "http://oml:5054/result/dumpDatabase?expID=<your_experiment_ID>" -O myDatabase
}}}

 * If the experiment ID contains non-alphanumeric ASCII characters, it is necessary to escape each of them using "%" followed by the ASCII code.

You're almost done. In order to get SQLite to recognize the database, it first must be told that the information '''is''' a database. 

{{{
sqlite3 -init myDatabase myDatabase.sq3
}}}

You can also view the results in a web browser by visiting the following URL:
{{{
http://console.sb4.orbit-lab.org:5054/result/dumpDatabase?expID=<your_experiment_ID>
}}}

----

== Final Observations == 

Due to the highly experimental nature of ORBIT and its OMF and OML, it is possible that this experiment may eventually be broken by future design changes. Please bear this in mind.

If this experiment does not work for you, and the above troubleshooting suggestions did not resolve your difficulties, you may need to contact an administrator. Unfortunately, it is difficult to tell the difference between the system being down and simply misconfigured for an end user. Therefore, you should attempt to debug the experiment using the above troubleshooting tips to ensure that the error is not from the configuration.

----