History

OMF Main Page » OMF User Guide » BasicTutorials-5-3 »

1. "Hello World" - Wireless

This tutorial presents a simple example, which shows you all the basic steps to quickly develop, run, and access the result of an experiment with OMF. Subsequent tutorials will build on this one to show you how to use other OMF features.

If you are a new OMF users, you may want to read the short OMF System Overview and/or the Experiment Life-cycle Overview

Experiment Scenario:

Figure 1 shows the simple experiment scenario, which we will use as the example for this basic tutorial.

Figure 1. Simple experiment scenario

  • This experiment involves two wireless PC-based nodes, i.e. Node 1 and Node 2
  • Node 1 is running a simple UDP traffic generator application (OTG2)
  • Node 2 is running a simple traffic receiver application (OTR2)
  • Node 1 is the "Sender" and will generate and send traffic to the "Receiver" node 2, over a wireless 802.11g channel.

Note: At NICTA and WINLAB, these 2 applications (OTG2 & OTR2) are already pre-installed on the default baseline disk image for the wireless nodes. If you are using another OMF testbeds, you can find and install these applications from the OML Application pages.

2. Accessing and Reserving resources on an OMF-enabled testbed

This tutorial assumes that you are using either one of the NICTA testbeds or one of the WINLAB ORBIT testbeds.

The OMF Experiment Controller (EC) is the software that will interpret your Experiment Description (ED) and execute it accordingly. You can either:

  • Use the already installed EC, which is present on the consoles of any of the NICTA or WINLAB testbeds
  • Download, install, and configure the EC on your own machine (Supported OS: Ubuntu/Debian, Fedora, Mac OSX)

This tutorial assumes the former, i.e. you will be using the EC installed on your NICTA/WINLAB testbed's console:

  • log on to the console machine corresponding to this testbed, during your reserved time slot:
Example at NICTA:
   ssh myUsername@norbit.npc.nicta.com.au
   password:

Example at WINLAB:
   ssh myUsername@console.sb1.orbit-lab.org
   password:
  • Install a baseline disk image on the 2 resources, which you have reserved and which we will use in this tutorial. Here we assume that these two nodes are: omf.nicta.node2 and omf.nicta.node3 (if you are using other nodes, replace these names accordingly).
omf-5.3 load -t omf.nicta.node2,omf.nicta.node3 -i baseline.ndz

3. Developing the "Hello World" Experiment Description

To run an experiment with OMF, you need first to describe it into an Experiment Description (ED) file. An Experiment Description (ED) is a script that is supplied as an input to the OMF Experiment Controller (EC). It contains detailed descriptions of the resources involved in an experiment and the sets of actions to perform in order to realize that experiment. An ED is written using the OMF Experiment Description Language (OEDL).

The ED describing this simple "Hello World" experiment is (download it here: hello-world.rb):

 1 defGroup('Sender', "omf.nicta.node2") do |node|
 2   node.addApplication("test:app:otg2") do |app|
 3     app.setProperty('udp:local_host', '192.168.0.2')
 4     app.setProperty('udp:dst_host', '192.168.0.3')
 5     app.setProperty('udp:dst_port', 3000)
 6     app.measure('udp_out', :interval => 3)
 7   end
 8   node.net.w0.mode = "adhoc" 
 9   node.net.w0.type = 'g'
10   node.net.w0.channel = "6" 
11   node.net.w0.essid = "helloworld" 
12   node.net.w0.ip = "192.168.0.2" 
13 end
14 
15 defGroup('Receiver', "omf.nicta.node3") do |node|
16   node.addApplication("test:app:otr2") do |app|
17     app.setProperty('udp:local_host', '192.168.0.3')
18     app.setProperty('udp:local_port', 3000)
19     app.measure('udp_in', :interval => 3)
20   end
21   node.net.w0.mode = "adhoc" 
22   node.net.w0.type = 'g'
23   node.net.w0.channel = "6" 
24   node.net.w0.essid = "helloworld" 
25   node.net.w0.ip = "192.168.0.3" 
26 end
27 
28 onEvent(:ALL_UP_AND_INSTALLED) do |event|
29   info "This is my first OMF experiment" 
30   wait 10
31   allGroups.startApplications
32   info "All my Applications are started now..." 
33   wait 30
34   allGroups.stopApplications
35   info "All my Applications are stopped now." 
36   Experiment.done
37 end

3.1 Resource Description and Configuration (Line 1 to 26)

  • Line 1: we define a new group of resources, called Sender. This group includes a unique node, which is identified by a unique id: omf.nicta.node2.
  • Line 2-7: we associate an existing application called test:app:otg2 to this group. This application will be installed and run on each node of this group (here, only omf.nicta.node2). In this tutorial, this application is already installed on the baseline disk image, which you previously loaded on the node. This application is a simple traffic generator, which by default generates fixed-sized UDP packets at a constant bitrate.
    • More precisely:
      • Line 3: we set the parameter udp:local_host of the application to the IP address that we give to the experimental interface of omf.nicta.node2 (i.e the sender)
      • Line 4: we set the parameter udp:dst_host of the application to the IP address that we give to the experimental interface of omf.nicta.node3 (i.e. the receiver)
      • Line 5: we set the parameter udp:dst_port of the application to the port that node omf.nicta.node3 will listen on
      • Line 6: we request the collection of the measurements from the udp_out Measurement Point provided by the application, at a regular interval of 3 sec
  • Line 8-12: we configure some properties for this group, i.e. all the nodes in this group will share these properties (here, only node omf.nicta.node2)
    • More precisely:
      • Line 8: the first wireless interface (named w0) of the node is placed in ad-hoc mode
      • Line 9: this same interface is configured to operate in 802.11g type
      • Line 10: this same interface is configured to operate on channel 6
      • Line 11: the Extended Service Set ID (ESSID) of this interface is set to helloworld
      • Line 12: finally, the IP address of this interface is set to 192.168.0.2
  • Line 15-26: we define a similar group, called Receiver, which will only include node omf.nicta.node3 running the existing application test:app:otr2. This application is a simple traffic sink, which should also be installed on the baseline disk image. Similar to the previous OTG2 applications, we further set properties for OTR2, and request the data from the udp_in Measurement Points to be captured. We also configure the interface of the nodes in this group in a similar manner as for the Sender group.
  • Note:
    • More details about how to define groups and topologies, or configure resources can be found on the other tutorial pages.
    • More details about all the available options of the above defGroup, addApplication, etc... commands can be found on the OEDL reference pages.

3.2 Event-based Action Descriptions (Line 28 to 37)

OMF uses an event-based approach to describe the different actions required to perform during an experiment. Basically, you can define events and the sets of actions to execute when they are triggered. Events can be characterise by many different conditions. For example, an event can be "when nodes in group X are all powered ON", or "when measured data Z reaches a threshold X", or "when interface of node Y is configured", ...

In this simple experiment, we are only interested in 1 event, which is :ALL_UP_AND_INSTALLED = "when all the nodes are ON, and all the required applications are installed on them".

OMF comes with a set of default events, which have already been defined for you, and :ALL_UP_AND_INSTALLED is one of them. All we have to do here is specify the tasks that we would like to do when that event occurs, which is the call to onEvent(...) on line 26.

  • Line 28-37: here we declare what to do when the event :ALL_UP_AND_INSTALLED happens:
    • line 29, 32, 35: print some messages on the standard output when our experiment is running
    • Line 30: instruct the controller to pause for 10 sec
    • Line 31: tell all the Groups of this experiment to start all the applications associated to them. In this tutorial, this command will tell all the nodes in the groups "Sender" and "Receiver" to start their associated applications.
    • Line 33: wait for 30 sec. Basically, here we are giving time for UDP traffic to be exchanged from "Sender" to "Receiver". This is in fact the experiment.
    • Line 34: tell all the Groups to stop all the applications running on all the nodes associated to them.
    • Line 36: declare the end of the Experiment. This will trigger some "cleaning" actions on the nodes (e.g. turn off the network interfaces, stop receiving commands for this experiment, etc...)
  • Note:
    • More details about how to define other states or actions to perform within them can be found on the other tutorial pages.
    • More details about all the available options of the above commands can be found on the OEDL reference pages.

4. Running the "Hello World" Experiment

4.1. How do you run it?

Please refer to the above Section 2 to find out how to access an OMF-enabled testbed and how to reserve resources on it, if necessary. The rest of this section assumes that you are using an NICTA or WINLAB testbeds, and that you have installed a baseline image on your resources (i.e. NICTA's and WINLAB's baseline image have the applications OTG2 and OTR2 pre-installed).

The command line omf exec invokes the Experiment Controller (EC) application, which will be orchestrating the experiment execution on your behalf. As explained on the OMF Introduction page, the EC will interprets your ED and send commands to the various Resource Controllers (RCs) and Aggregate Manager (AM) related to the resources in your experiment. These commands will configure the resources and instruct them to perform actions.

  • First you need to create an file, which will hold your experiment description:
    • use your favorite editor to create a new file in your home directory on the console of the testbed (e.g. hello-world.rb)
    • cut-and-paste the above "Hello World" ED into this file and save it
    • or download the experiment file directly from here: hello-world.rb
  • Now invoke the EC to run your experiment
omf-5.3 exec hello-world.rb
  • You can use the command omf-5.3 help exec to get a full list of options for the omf-5.3 exec command.

4.2. What you should see on the console:

When running the EC with the above command, you should see an output similar to this (note that in this particular instance, we are using node28 and node29):

 1  INFO NodeHandler: OMF Experiment Controller 5.3.634
 2  INFO NodeHandler: Slice ID: testing_slice (default)
 3  INFO NodeHandler: Experiment ID: testing_slice-2010-09-03t09.41.43+10.00
 4  INFO NodeHandler: Message authentication is disabled
 5  INFO NodeHandler: Web interface available at: http://10.0.0.200:4000
 6  INFO Experiment: load system:exp:stdlib
 7  INFO property.resetDelay: value = 210 (Fixnum)
 8  INFO property.resetTries: value = 1 (Fixnum)
 9  INFO Experiment: load system:exp:eventlib
10  INFO Experiment: load hello-world.rb
11  INFO Topology: Loading topology 'omf.nicta.node28'.
12  INFO Topology: Loading topology 'omf.nicta.node29'.
13  INFO ALL_UP_AND_INSTALLED: Event triggered. Starting the associated tasks.
14  INFO exp: This is my first OMF experiment
15  INFO exp: Request from Experiment Script: Wait for 10s....
16  INFO omf.nicta.node29: Device 'net/w0' reported 02:0B:6B:57:BA:04
17  INFO omf.nicta.node28: Device 'net/w0' reported 02:0B:6B:57:BA:04
18  INFO exp: All my Applications are started now...
19  INFO exp: Request from Experiment Script: Wait for 30s....
20  INFO exp: All my Applications are stopped now.
21  INFO EXPERIMENT_DONE: Event triggered. Starting the associated tasks.
22  INFO NodeHandler: 
23  INFO NodeHandler: Shutting down experiment, please wait...
24  INFO NodeHandler: 
25  INFO run: Experiment testing_slice-2010-09-03t09.41.43+10.00 finished after 1:36
26
  • Line 1-5: some information about the EC and your experiment:
    • line 1: the EC's version & revision number
    • line 2: the name of your slice, here: testing_slice
    • line 3: the ID of your experiment, here: testing_slice-2010-09-03t09.41.43+10.00
    • line 4: the EC says that it is running without message authentication
    • line 5: the EC starts a web server (more description on this below), you can observe your experiment by pointing your browser to mentioned URL, in this case: http://10.0.0.200:4000
  • Line 6-12: some information about the properties of your experiment
  • Line 13: indicates that the :ALL_UP_AND_INSTALLED event has been triggered, thus the EC will now execute the commands declared in the associated onEvent block, which we described in the above ED
  • Line 15: indicates that your experiment is waiting for 10sec as you requested in the ED
  • Line 16-17: some information coming directly from the nodes in your experiment, here the nodes say that their wireless interface w0 joined the BSSID identified by the address 02:0B:6B:57:BA:04
  • Line 18-20: some information about the execution of your experiment
  • Line 21: indicates that your experiment has reached the Experiment.Done statement in the ED, i.e. the event :EXPERIMENT_DONE has been triggered
  • Note:
    • your experiment will generate a log file, which will be located at: /tmp/Your_Experiment_ID.log
    • the EC in your experiment will also keep a XML tree describing the state of your experiment, which will be located at /tmp/Your_Experiment_ID-state.xml
    • in the case of the above experiment run, here are two examples of these files:

5. Accessing the Results from the Experiment

In the above ED, we requested the collection of measurements from two Measurement Points (MP):
  • the udp_out MP provided by the OTG2 application
  • the udp_in MP provided by the OTR2 application

Thus, while the experiment was running, these applications were forwarding measurements to the OML framework (refer to the OMF Introduction page for more details). The OML server stored these measurements in a SQL database.

5.1 How do you access the measurement database after the experiment stops?

Currently the collected measurements are stored in a SQLite database, which is located on the server that runs the OML Measurement Collection Server. For each new experiment execution, an measurement database is created with the same name as the Experiment ID. In this example, the experiment database has the name testing_slice-2010-09-03t09.41.43+10.00.

Every OMF installation has one or more Aggregate Manager(s) providing a range of services to manage the testbed resources. One of these services is called result, and as its name implies, it provides an easy access to experiment results. One of the possible ways to access your result database, is to request a database dump of it from the result AM service.

  • First, find out the hostname and port of the result AM service on your OMF-enalbed testbed
    • For NICTA, this service is running on the console of your testbed. Its host & port are: "localhost:5053"
    • For WINLAB, this services is running on the server at the host & port: "oml:5053"
  • To request a dump of your result database from the console:
## At NICTA
wget "http://localhost:5053/result/dumpDatabase?expID=testing_slice-2010-09-03t09.41.43%2B10.00" -O myDatabase

## At WINLAB
wget "http://oml:5053/result/dumpDatabase?expID=testing_slice-2010-09-03t09.41.43%2B10.00" -O myDatabase
  • Note that as we are using an HTTP interface in this example and our experiment ID has a "+" in this example, we need to escape it with is ascii code "%2B"
  • You should now have a file named "myDatabase" which is a SQLite dump of your result database. The database dump for this Hello World experiment is attached here: myDatabase
  • You can open this database, an run queries on it (refer to the SQLITE3 website for more information on how to do this)
sqlite3 -init myDatabase myDatabase.sq3
  • Alternatively, you may want to install the "SQLite manager" extension for the Firefox browser from here . It allows you to open the SQLite binary database file or the dump file directly and gives you various options for viewing your results and exporting them into other formats such as comma-separated or XML.
  • Note: the result AM service provides more functions than just "dump a database", a list of its other functions is available on the Result AM page.
  • Also please refer to the OML Documentation pages to learn more about the different tables and fields in any OML generated measurement database

5.2 How do you observe the evolution of the measurements while the experiment is running?

EC Web feature will be deprecated in OMF version 5.4

As mentioned above, while your experiment is running the EC provides a web page, which you could use to observe your experiment. You can augment your experiment description to have some graphs of your measured metrics being displayed live on that web page, as your experiment is running.

Another tutorial provides a full description on How to define graphs to plot during your experiment's runtime on the EC web page.

In this example:

  • first we change lines 6 and 19 in our ED, to request the collection of all samples, instead of the previous interval of 3 sec. Although you can still plot graphs with the previous 3-sec interval measurement collection, we would have a less frequent updates.
Replace line 6 in the ED by  : app.measure('udp_out', :samples => 1)
Replace line 19 in the ED by : app.measure('udp_in', :samples => 1)
  • now we need to add the following additional lines at the end of the ED in order to have the EC dynamically plot graphs during the experiment runtime:
 1 # Define a graph to display while the experiment is running
 2 #
 3 addTab(:defaults)
 4 addTab(:graph2) do |tab|
 5   opts = { :postfix => %{This graph shows the Sequence Number from the UDP traffic.}, :updateEvery => 1 }
 6   tab.addGraph("Sequence_Number", opts) do |g|
 7     dataOut = Array.new
 8     dataIn = Array.new
 9     mpOut = ms('udp_out')
10     mpIn = ms('udp_in')
11     mpOut.project(:oml_ts_server, :seq_no).each do |sample|
12       dataOut << sample.tuple
13     end
14     mpIn.project(:oml_ts_server, :seq_no).each do |sample|
15       dataIn << sample.tuple
16     end
17     g.addLine(dataOut, :label => "Sender (outgoing UDP)")
18     g.addLine(dataIn, :label => "Receiver (incoming UDP)")
19   end
20 end
  • The extended Experiment Description for including this graph definition is available here: hello-world-graph.rb
  • Now run this new experiment as we described above, e.g. omf-5.3 exec hello-world-graph.rb
  • Note the URL reported by the EC and at which you can access its runtime web page, e.g. http://10.0.0.200:4000
  • Point your web browser to that URL, and you should see a page similar to this:

  • Note that the current OMF 5.3 release displays lots of messages on the EC output when you interact with the web page, please disregard these messages. We will soon provide a "cleaner" EC update.
  • Click on the Graph tab, and you should see a graph similar to this:

  • Note:
    • here we are looking at the sequence number added to the UDP packets by the OTG2 application
    • in this particular experiment run, the loss and delay on the wireless link between the 2 nodes are very minimal, and thus the sequence number lines for outgoing and incoming UDP traffic are drawn on top of each others on the graph
    • in another run with other wireless link conditions the two lines would be separated, and the receiver one may have steps or gaps

6. What is Next?

Now that you know how to develop and run a simple experiment, you may want to read the following basic OMF tutorials. Each one of them is introducing an OMF feature, using this simple "Hello World" experiment as a base. You do not need to follow them in the order suggested below.

And finally, a "Conference Room" scenario which combines all of the above features:

screenshot1.png (63.2 kB) Thierry Rakotoarivelo, 09/03/2010 12:13 pm

screenshot2.png (108.7 kB) Thierry Rakotoarivelo, 09/03/2010 12:13 pm

myDatabase (4.8 kB) Thierry Rakotoarivelo, 09/03/2010 12:19 pm

hello-world.EC.log (85.2 kB) Thierry Rakotoarivelo, 09/03/2010 12:31 pm

OMF-HelloWorld.png (43.5 kB) Thierry Rakotoarivelo, 09/06/2010 04:28 pm

hello-world.rb (1.2 kB) Thierry Rakotoarivelo, 09/08/2010 02:49 pm

hello-world-graph.rb (1.7 kB) Thierry Rakotoarivelo, 09/08/2010 02:49 pm

hello-world.EC-state.xml (11.3 kB) Thierry Rakotoarivelo, 09/24/2010 03:40 pm