= WiMAX Tutorial =

This is a continuation of the [http://www.orbit-lab.org/wiki/WiMAX_Tutorial-1/ 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 are assumed.
----

== About This Experiment ==

This tutorial section is adapted from the tutorials at [http://witestlab.poly.edu/index.php/tutorials.html NYU-Polytech] 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. This experiment very well may fail for other versions of OMF.'''

----

= Experiment: Check Connection Status, Then Send UDP 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/WiMAX_Tutorial-2/nyupoly_mcsmod.rb Experiment Description] [[BR]]
 * [http://www.orbit-lab.org/attachment/wiki/WiMAX_Tutorial-2/iperf.rb iperf app] [[BR]]
 * [http://www.orbit-lab.org/attachment/wiki/WiMAX_Tutorial-2/wimaxcu_app.rb wimaxcu_app wrapper] [[BR]]
 * [http://www.orbit-lab.org/attachment/wiki/WiMAX_Tutorial-2/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/WiMAX_Tutorial-2#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
defProperty('firstMCS',"http://wimaxrf:5052/wimaxrf/dlprofile?dlprof1=13","Set MCS to profile 13 - QPSK (CTC) 1/2 ")
defProperty('secondMCS',"http://wimaxrf:5052/wimaxrf/dlprofile?dlprof1=16","Set MCS to profile 16 - 16-QAM (CTC) 1/2")
defProperty('thirdMCS',"http://wimaxrf:5052/wimaxrf/dlprofile?dlprof1=21","Set MCS to profile 21 - 64-QAM (CTC) 5/6")
defProperty('noMCS',"http://wimaxrf:5052/wimaxrf/dlprofiledlprof2=255&dlprof3=255dlprof4=255&dlprof5=255&dlprof6=255&
            dlprof7=255&dlprof8=255&dlprof9=255&dlprof10=255&dlprof11=255&dlprof12=255","Set other MCS to none")
}}}

''defProperty'' is a method which appears in different scopes within OMF. In this global case, it creates methods of the ''property'' with the name of the first input (as a string), stores and releases the value of the second input, and takes the third input as a description. 

 * As shown in the previous experiment, this URI accesses the base station and assigns it certain values.

{{{
#!ruby
defGroup('first_node', 'node1-1.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-1.sb4.orbit-lab.org') do |node|
  node.net.x0.profile = '51'
  node.net.x0.ip = '10.41.14.1'
  node.net.x0.netmask = '255.255.0.0'
  node.net.x0.up
  node.addApplication("test:app: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.

 * ''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 is actually already installed in the experiment image here, and "test:app:..." instructs OMF to search in the /test/app/ subdirectory of its primary directory of applications.

 * ''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('udp', true)
    app.setProperty('server', true)
    app.setProperty('interval', "1")
    app.setProperty('bind', "10.41.255.255")
    app.measure('UDP_Rich_Info', :samples =>1)
  end
}}}

 * As before, this application is contained in a subdirectory accessed through ''/test/app/''. 

This adds the ''iperf'' application functionality to the group. ''iperf'' is an application which measures connectivity by sending data packets between groups. 

''setProperty'' is fairly self-explanatory. It simply configures individual parameters germane to the operation of iperf.

Here, ''app.measure'' is interesting because it is only one of the possible measurements that can be taken by the iperf app. For the others, see the ''iperf.rb'' code.
----
== Launch Experiment ==

Before launching the experiment, please ensure that the experiment description file is on the local machine.

Image the nodes, as before.

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

Optionally, double check that the image loaded correctly.

Now, launch the experiment!

{{{
omf-5.3 exec <experimentname>.rb
}}}

----

== 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:5053/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
}}}