== WiMAX "Hello World" Tutorial ==

This tutorial presents a simple example of using WiMAX devices that are available in ORBIT. The tutorial assumes basic understanding of OMF. If you are not familiar with it, please read the short [http://mytestbed.net/projects/omf/wiki/An_Introduction_to_OMF OMF System Overview] to familiarize yourself with the testbed control framework.

=== Experimental Scenario ===

The experimental scenario is fairly simple: our goal is to measure RTT of basic WiMAX link (single hop). This will be achieved by processing the output of a simple ping command. The output of the ping command will be passed through a regular expression and the results stored in an sqlite database. 

=== Experiment Description ===
The expirment has two phases: setup and collection. In the setup phase we prime the interfaces with the necessary layer 3 information. In the collection phase we run the ping command and process the results.

==== Configuring WiMAX inteface ====
We need to connect each node to the basestation. We will use wimaxcu userspace utility for that. This application definition will invoke the the wimaxcu utility on each node with the arguments necessary to authenticate to the base station.

{{{
defApplication('wimaxcu', 'wimaxcu') {|a|
   a.name = "wimaxcu" 
     a.version(0, 0, 1)
     a.path = "/usr/bin/wimaxcu" 
     a.defProperty('args', "Arguments for wimaxcu command", nil,  {:order => 1, 
:dynamic => false, :type => :string, :use_name => false
}}}

==== Assigning the WiMAX IP Address ====
We will use dhclient command on the node to assign the IP address to the WiMAX interface. The following code snippet is the dhclient command wrapper that is used for ip address assignment on each individual node.

{{{
defApplication('dhclient', 'dhclient') {|a|
   a.name = "dhclient" 
     a.version(0, 0, 1)
     a.path = "/sbin/dhclient -q" 
     a.defProperty('interface', "DHCP client interface name", nil,  {:order => 1
, :dynamic => false, :type => :string, :use_name => false
}}}


==== Ping Application ====

This application definition wraps code around the ping command running on an individual node. Unlike the dhclient application definition, we're interested in it's output. We've defined a few measurement metrics (pieces of data we're interested in). When we examine the results in the sqlite database produced from this experiment the field will be labeled with these metric names. This wrapper is based on the OML4R command wrapper library (it's included in a require statement).

{{{
defApplication('pingtest_app', 'pingtest') do |a|
  a.path = "/usr/bin/pingtest.rb"
  a.version(0, 0, 1)
  a.shortDescription = "Wrapper around Ping -c"
  a.description = <<TEXT
This is a wrapper around the ping command.
This application is using OML4R part of OML v2.3 or v2.4
TEXT
  a.defProperty('ip', 'Ip address to ping', 'i', 
                {:type => :string, :dynamic => false})

  # List the Measurement Points and associated metrics that are available 
  # for this application
  #
  a.defMeasurement('pingtest') do |m|
    m.defMetric('ip',:string)
    m.defMetric('time',:string)
    m.defMetric('x',:string)
    m.defMetric('y',:string)
  end
end
}}}

==== Experiment Code ====
The last phase of the experiment description requires a script that coordinates all the elements.  This code snippet specifies the nodes involved in the experiment and declares the applications and parameters required to run them.

{{{
defGroup('tester', [1,1]) do |node|
  node.addApplication('wimaxcu') { |app|
    app.setProperty('args','connect network 51')
  }
  node.addApplication('dhclient') { |app|
    app.setProperty('interface',"wmx0")
  }
  node.addApplication("pingtest_app") { |a|
    a.setProperty('ip',"10.41.0.1")
    a.measure('pingtest')
  }
end
}}}

Now that all the setup is done the actual experiment code is pretty simple. It  boots the nodes, waits for 10 seconds for them to warm up and then runs the ping/collection.

{{{
whenAllInstalled() {|node|
   info "Give machines some time to warm up" 
   wait 10
   allGroups.startApplications
   info "Colect measurements for 100 seconds" 
   wait 100
   info "Finish it." 
   Experiment.done
}
}}}