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 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.
- These 2 applications (OTG2 & OTR2) are already pre-installed on the baseline disk image of the wireless nodes on the NICTA and WINLAB testbeds.
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.
- Using a testbed at NICTA? Please refer to the OMF at NICTA Getting Starting page
- Using a testbed at WINLAB? Please refer to the OMF at WINLAB Getting Starting page
- Using another OMF-enabled testbed? Please refer to the Getting Started page or contact the operator of your testbed
- If you are using your own freshly installed testbed with OMF, just skip the first 2 points below, and replace host and username below with your specific details.
Before you run the "Hello World" experiment, you need to:
- 1. get an account on an OMF-enabled testbed. If not, register for an account.
- Read the OMF @ NICTA page to find out how to register to use the Norbit testbed
- 2. make a reservation for a time slot to use the nodes 2 and 3 of the testbed
- Read the OMF @ NICTA page to find out how to reserve a time slot on the Norbit testbed
- 3. log on to the console machine corresponding to this testbed, during your time slot
ssh myUsername@norbit.npc.nicta.com.au password:- If you cannot login, contact a testbed administrator at NICTA.
- 4. install a baseline disk image on the 2 nodes, which we will use in this tutorial
omf load [[1,2],[1,3]] baseline.ndzYou should see an output similar to this example of omf load outputs on your screen. Also, please refer to the "How To Install a Disk Image" tutorial to learn more about loading disk images on nodes. Finally, you may also want to have a look at the manual pages for the "omf" command.
3. Developing the "Hello World" Experiment Description¶
As explained on the Introduction page earlier, to run an experiment with OMF, you need to describe it into an Experiment Description (ED). An Experiment Description (ED) is a script that is supplied as an input to the OMF Experiment Controller (EC). It contains detailed descriptions of resources required by 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:
1 defGroup('Sender', [1,2]) {|node|
2 node.addApplication("test:app:otg2") {|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 }
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 }
14
15 defGroup('Receiver', [1,3]) {|node|
16 node.addApplication("test:app:otr2") {|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 }
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 }
27
28 whenAllInstalled() {|node|
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 }
3.1 Resource Description and Configuration (Line 1 to 24)¶
- Line 1: we define a new group of resources, called "Sender". This group includes a unique node, which is identified by a unique id: [1,2].
- Line 2-7: we associate an existing application called "test:app:otg2" to this group, i.e. the application "test:app:otg2" will be installed and run on each node of this group (here, only [1,2]). In the context of this tutorial, this application is already installed on the baseline disk image, which you loaded on the node in the previous section 2. 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 property "udp:local_host" of the application to the IP address that we will give to node [1,2] (i.e the traffic sender) for the duration of our experiment
- Line 4: we set the property "udp:dst_host" of the application to the IP address that we will give to node [1,3] (i.e. the traffic receiver) for the duration of our experiment
- Line 5: we set the property "udp:dst_port" of the application to the port that node [1,3] (i.e. the traffic receiver) will listen on for the duration of our experiment
- Line 6: we request that the application measure the data from the "udp_out" Measurement Point, and collect that data for us at a regular interval of 3 sec
- More precisely:
- 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 [1,2])
- More precisely:
- Line 8: we request that 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 the type "g" of the 802.11 standard (i.e. 802.11g)
- Line 10: this same interface is configured to operate on channel "6"
- Line 11: we set the Extended Service Set ID (ESSID) of this interface to the name "helloworld"
- Line 12: finally, we set the IP address of this interface to "192.168.0.2"
- More precisely:
- Line 15-26: we define a similar group, called "Receiver", which will only include node [1,3] running the existing application "test:app:otr2". This application is a simple traffic sink, which should also be already 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 Action Descriptions as a State Machine (Line 28 to 37)¶
OMF has adopted a state machine approach to describe the different actions required to perform the experiment scenario. Basically, actions are associated to states, and are performed when that state is reached. States can be characterise by many different conditions. For example, a state can be "when nodes in group X are all powered ON", or "when measured data Z reaches a threshold X", etc...
In this simple experiment, we only declare one state, which is "when all the nodes are ON, and all the required applications are installed on them". This translates into the call to "whenAllInstalled()", as shown on line 26.
- Line 28-37: here we declare a unique state, named "whenAllInstalled()", which is followed by the sequential list of actions to perform when this state is reached:
- More precisely:
- line 29, 32, 35: we print some messages on the standard output when our experiment is running
- Line 30: instruct the Experiment Control to pause for 10 sec. This is recommended to ensure that all the nodes have been configured, e.g. there may be a lag between the moment a node receives a command to change its IP address, and the moment when this does happen. To be fully consistent with the "state-machine" approach, we should use here a state declaration such as "when all nodes are configured". However, OMF does not support state nesting yet, this will be added in a future release.
- Line 31: tell all the Groups of this experiment to start all the applications associated to them. In this particular example, this command will tell all the nodes in the groups "Sender" and "Receiver" (i.e. [1,2] and [1,3]) to start their associated applications (i.e. OTG2 and OTR2).
- 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...)
- More precisely:
- 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?¶
To be able to run this experiment, first make sure that you have:- booked a time slot and some resources on an OMF-enabled testbed,
- accessed the console of that testbed,
- installed an disk image, which contains the OTG2 and OTR2 applications (e.g. the baseline image at NICTA and WINLAB)
Section 2 above describes how to complete these steps.
The command line "omf exec" invokes the Experiment Controller (EC) application, which will be responsible to perform the experiment on your behalf. As explained on the OMF Introduction page, the EC will interprets your ED, and send the relevant requests to the Aggregate Manager (AM) of the testbed and the various Resource Controllers (RCs) on the resources, in order to allocate and configure the resources and perform the experiment actions.
You have two ways to run the "Hello World" experiment:
- Option 1: Run the "Hello World" experiment as you would run any other OMF experiments
- (1) use your favorite editor to create a new file with a ".rb" extension in your home directory on the console of the testbed
- (2) cut-and-paste the above "Hello World" ED into this file and save it
- (3) invoke the Experiment Controller with this file
## (1) create a new file (e.g. here we use vi) vi myFirstExperiment.rb ## (2) here cut-and-paste the above ED into the myFirstExperiment.rb file ## (3) invoke the Experiment Controller omf exec myFirstExperiment.rb
- Option 2: Run the "Hello World" experiment using the bundled tutorials
- For your convenience, the "Hello World" ED has been bundled with the omf application. More precisely, the Experiment Controller has a bundled repository of almost all the ED used in the tutorials.
- To run "Hello World" using the bundled ED, use the following command:
omf exec --tutorial -- --tutorialName tutorial0
4.2. What you should see on the console:¶
Using either of the two options above to run your experiment, you should see an output similar to this:
1 INFO NodeHandler: init OMF Experiment Controller 5.2.290
2 INFO NodeHandler: init Experiment ID: npc_2009_11_04_14_27_33
3 INFO NodeHandler: Web interface available at: http://10.0.0.200:4000
4 INFO Experiment: load system:exp:stdlib
5 INFO property.resetDelay: value = 210 (Fixnum)
6 INFO property.resetTries: value = 1 (Fixnum)
7 INFO Experiment: load tutorial0.rb
8 INFO whenAll: *: 'apps/app/status/@value' fires
9 INFO exp: Request from Experiment Script: Wait for 10s....
10 INFO n_1_2: Device 'net/w0' reported 06:0B:6B:84:3C:1B
11 INFO n_1_3: Device 'net/w0' reported 06:0B:6B:84:3C:1B
12 INFO exp: Request from Experiment Script: Wait for 30s....
13 INFO Experiment: DONE!
14 INFO run: Experiment npc_2009_11_04_14_27_33 finished after 1:1
- Line 2: gives you the ID of your experiment, in this example: "npc_2009_11_04_14_27_33"
- Line 3: gives you the URL, where you can view some information about your experiment
- Line 4-7: give you some information about the properties of your experiment
- Line 8: indicates that your experiment has entered the "whenAllInstalled" state, which we described in the above section 3.2
- Line 9: indicates that your experiment is waiting for 10sec as you requested in the ED
- Line 10-11: give you some information coming directly from the nodes in your experiment
- Line 12: indicates that your experiment is waiting for 30sec as you requested in the ED
- Line 13: indicates that your experiment has reached the Experiment.Done statement in the ED
- Note:
- your experiment will generate a log file, which will be located at: /tmp/yourExperimentID.log
- In the above example, the log file will be at: "/tmp/npc_2009_11_04_14_27_33.log"
5. Accessing the Results from the Experiment¶
In the ED described above (section 2.1), we requested OMF to measure some data from two Measurement Points (MP), one ("udp_out") provided by the OTG2 application, and the other ("udp_in") provided by the OTR2 application.
Thus, as our experiment was running, some measurements were made and collected by the OML framework (refer to the OMF Introduction page for more details). In this example:- measurements from "udp_out" MP: information from the OTG2 application, about the UDP packets that are about to be sent
- measurements from "udp_in" MP: information from the OTR2 application, about the UDP packets that have been received
5.1 How do you access these measurements?¶
These collected measurements are stored in SQLite database, which is located on the machine 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. Thus, in the above execution example, our experiment database will have the name: "npc_2009_11_04_14_27_33".
Every OMF installation should have one or more Aggregate Manager(s) running, which provides 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 HTTP-based API to access 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 what are the hostname and port of the result AM service on your OMF-enalbed testbed.
- For NICTA testbeds, this service is running on the console of your testbed, thus its host & port are: "localhost:5052"
- For WINLAB testbeds, this services is running on a separate server at the following host & port: "oml:5052"
- Now assuming your experiment ID is "npc_2009_11_04_14_27_33", you request a dump of your result database with the command on the console:
## At NICTA wget "http://localhost:5052/result/dumpDatabase?expID=npc_2009_11_04_14_27_33" -O myDatabase ## At WINLAB wget "http://oml:5052/result/dumpDatabase?expID=npc_2009_11_04_14_27_33" -O myDatabase
- You should now have a file named "myDatabase" which is a SQLite dump of your result database (you can open it and see the SQL statements)
- The SQLite database dump, which you obtained should be similar to the dump shown on this page.
- Note: the result AM service allows you to request more than just a database dump, a complete list of its other functions are available on the Result AM page.
5.1 What do you do with this measurement database?¶
This measurement database is an SQLite database.- Thus you can import it within a SQL database software, and run queries against it.
- Furthermore, you should also be able to import it within a large number of data processing software, e.g. MatLab, Excel, etc...
- Finally, this database file ("myDatabase" in the previous example) is just a text readable file with SQL statement in it. Therefore, you should also be able to parse the information you need with some scripts and do more processing, using tools such as Gnuplot to generate figures and graphs.
Here is an examples of things you can do:
- Import the database into an SQLite client, and run query to get the Timestamp and Sequence Number of the received packets on the Receiver side:
## Retrieve the database dump wget "http://localhost:5052/result/dumpDatabase?expID=npc_2009_11_04_14_27_33" -O myDatabase ## Assuming you have sqlite3 installed ## Load it into sqlite3 myDatabase, run a query to get the field we are interested in, and save the result in a text file sqlite3 -separator " " -init myDatabase db "select oml_ts_server,seq_no_max from otr2_udp_in;" | sed '1d' >mySelection.txt ## You now have a file "mySelection.txt" which contains timestamps and sequence number
- Use Gnuplot to plot a graph of received Sequence Number versus received Time:
## Assuming you have gnuplot installed gnuplot gnuplot> set term postscript gnuplot> set output "hello_graph.eps" gnuplot> set xlabel "Time since experiment start (sec)" gnuplot> set ylabel "Packet Sequence Number at Receiver" gnuplot> plot 'mySelection.txt' using 2:1 notitle with points gnuplot> quit
- You should then get a graph similar to this:
- Please refer to the OML Documentation pages to learn more about the different standard tables and fields in any OML generated measurement database
6. What is Next?¶
Now that you have learnt how to develop and run a simple experiment, you can continue reading the following basic OMF tutorials.
Each one of them is introducing a new basic OMF feature, using this simple "Hello World" experiment as a base. Thus each one of them is building incrementally on this "Hello World". 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:
