Revision of Experiments Tutorials and 'Theoretically Working' adaptations to OMF6

.gitignore

@@ -11,4 +11,4 @@
 tags
 **/coverage
 documentation
-omf_common/example/auth
+omf_common/example/auth

doc/tutorials/TUTORIAL_00.mkd → doc/tutorials/Experiment01.mkd

@@ -1,9 +1,10 @@
-# Tutorial 00
+# Experiment 01
 
-1. "Hello World" Tutorial
+
+1. "Hello World" *Experiment Tutorial*
 ---------------------------
 
-This simple tutorial presents all the basic steps to develop, run, and
+This simple experiment tutorial presents all the basic steps to develop, run, and
 access the result of an experiment with OMF 6.
 Subsequent tutorials will build on this one to introduce further OMF
 features.
@@ -27,7 +28,7 @@ Description Language
 **Files**
 
 The experiment description (aka script) is:
-{file:doc/tutorials/tutorial00.rb tutorial00.rb}
+{file:doc/tutorials/experiment01.rb experiment01.rb}
 
 **Experiment Scenario**
 
@@ -135,69 +136,85 @@ 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 {file:doc/tutorials/tutorial00.rb tutorial00.rb}. It is composed of 3 distinct
+The ED describing this simple “Hello World” experiment is {file:doc/tutorials/experiment01.rb experiment01.rb}. It is composed of 3 distinct
 parts, described in the following listing and subsections below.
 
-    # A. Define an OMF Application Definition for the ping-oml2 application
-    # The OMF entities are using this definition to know where to find the
-    # application, what are its configurable parameters, and what are the
-    # OML2 measurement points that it provides.
-    # This ping-oml2 application will be known by OMF entities as 'ping_oml2'
-    #
-    defApplication('ping_oml2') do |app|
-      app.description = 'Simple Definition for the ping-oml2 application'
-      # Define the path to the binary executable for this application
-      app.binary_path = '/usr/bin/ping-oml2'
-      # Define the configurable parameters for this application
-      # For example if target is set to foo.com and count is set to 2, then the
-      # application will be started with the command line:
-      # /usr/bin/ping-oml2 -a foo.com -c 2
-      app.defProperty('target', 'Address to ping', '-a', {:type => :string})
-      app.defProperty('count', 'Number of times to ping', '-c', {:type => :integer})
-      # Define the OML2 measurement point that this application provides.
-      # Here we have only one measurement point (MP) named 'ping'. Each measurement
-      # sample from this MP will be composed of a 4-tuples (addr,ttl,rtt,rtt_unit)
-      app.defMeasurement('ping') do |m|
+
+<pre class="code ruby"><code class="ruby">    
+#Welcome to Experiment 01
+#This ED allows experimenters to ping a specified host and collect the output it recieves as measurement points
+
+#Section 1
+#Define oml2 application file-paths
+#Define experiment parameters and measurement points
+
+defApplication('ping_oml2') do |app|
+
+    #Application description and binary path
+    app.description = 'Simple definition of ping-oml2 application'
+    app.binary_path = '/usr/bin/ping-oml2'
+
+    #Configurable parameters of Experiment
+    app.defProperty('target', 'Address to ping', '-a', {:type => :string})
+    app.defProperty('count', 'Number of times to ping', '-c', {:type => :integer})
+
+
+    #Define measurement points that application will output
+    app.defMeasurement('ping') do |m|
         m.defMetric('dest_addr',:string)
         m.defMetric('ttl',:uint32)
         m.defMetric('rtt',:double)
         m.defMetric('rtt_unit',:string)
-      end
+        
     end
-
-    # B. Define a group of resources which will run the ping-oml2 application
-    # Here we define only one group (Sender), which has only one resource in it
-    # (omf6.nicta.node8)
-    #
-    defGroup('Sender', 'omf6.nicta.node8') do |g|
-      # Associate the application ping_oml2 defined above to each resources
-      # in this group
-      g.addApplication("ping_oml2") do |app|
-        # Configure the parameters for the ping_oml2 application
+end
+
+#Section 2
+#Define resources and nodes used by oml2 application
+
+#Create the group 'Sender' with specified nodes
+defGroup('Sender', 'omf.nicta.node9') do |g|
+
+    #Associate oml2 application to group (?)
+    g.addApplication("ping_oml2") do |app|
+
+        #Configure target of application (Ping target)
         app.setProperty('target', 'www.nicta.com.au')
+
+        #Configure amount of times to ping host
         app.setProperty('count', 3)
-        # Request the ping_oml2 application to collect measurement samples
-        # from the 'ping' measuremnt point (as defined above), and send them
-        # to an OML2 collection point
+
+        #Request application to collect measurement point output data
         app.measure('ping', :samples => 1)
-      end
+        
     end
+end
+
+#Section  3
+#Execution of application events
+
+onEvent(:ALL_UP_AND_INSTALLED) do |event|
+
+    # Print information message on commandline
+    info "Initializing first OMF experiment event"
+
+    # Start all the Applications associated to all the Group
+    allGroups.startApplications
+
+    # Wait for 5 sec (allowing time for 3 pings)
+    after 5
+
+    # Stop all the Applications associated to all the Groups
+    allGroups.stopApplications
+
+    # Tell the Experiment Controller to terminate the experiment now
+    Experiment.done
+end
+</code>
+</pre>
+
+
 
-    # C. Define the sequence of tasks to perform when the event
-    # "all resources are up and all applications are install" is being triggered
-    #
-    onEvent(:ALL_UP_AND_INSTALLED) do |event|
-      # Print some information message
-      info "This is my first OMF experiment"
-      # Start all the Applications associated to all the Groups
-      allGroups.startApplications
-      # Wait for 5 sec
-      wait 5
-      # Stop all the Applications associated to all the Groups
-      allGroups.stopApplications
-      # Tell the Experiment Controller to terminate the experiment now
-      Experiment.done
-    end
 
 ### 3a) Application Definition
 
@@ -208,7 +225,7 @@ information is provided in the block of instructions defined between the
 'do' and 'end' markers following the 'defApplication' commands:
 
     defApplication('ping_oml2') do |app|
-      app.description = 'Simple Definition for the ping-oml2 application'
+      app.description = 'Simple definition of ping-oml2 application'
       ...
     end
 
@@ -253,13 +270,13 @@ Groups. A named Group can be itself viewed as a resource holding other
 resources. A given resource can belong to many groups at the same time, and
 a group itself may be part of another group.
 In this example, we define a single group named 'Sender', which contains a
-single resource 'omf6.nicta.node8'.
+single resource 'omf.nicta.node9'.
 
 > **IMPORTANT** When running this experiment using your own resource and testbed
-please change 'omf6.nicta.node8' in the ED to the actual name of your
+please change 'omf.nicta.node9' in the ED to the actual name of your
 own resource.
 
-    defGroup('Sender', 'omf6.nicta.node8') do |g|
+    defGroup('Sender', 'omf.nicta.node9') do |g|
       ...
     end
 
@@ -294,7 +311,7 @@ triggered
 For example, your experiment might involve 2 events:
 
 - 'when my PC node is ready' and
-- 'when my application has finished running'. You would then a
+- 'when my application has finished running'.
 
 You would then associate the following tasks to each of these events:
 
@@ -329,9 +346,9 @@ The set of consecutive tasks that we define are:
 - wait for 5 seconds
 - stop all the applications associated with all the groups
 
-        info "This is my first OMF experiment"
+        info "Initializing first OMF experiment event"
         allGroups.startApplications
-        wait 5
+        after 5
         allGroups.stopApplications
 
 As OMF experiment are fully event driven, you have to explicitly tell the OMF
@@ -356,14 +373,14 @@ section 2, and that you have the EC software installed on your own computer,
 then to run your experiment you have to:
 
 - save its description in a file on your computer, thus either
-  - cut-and-paste the above ED listing into a new file named 'tutorial00.rb'
+  - cut-and-paste the above ED listing into a new file named 'experiment01.rb'
   - download the ED directly:
-{file:doc/tutorials/tutorial00.rb tutorial00.rb}
+{file:doc/tutorials/experiment01.rb experiment01.rb}
 
 - open a terminal and navigate to the folder/directory where you saved that file
 - start the EC software and tell it to execute the experiment described in your ED file, using the command line:
 
-        omf_ec -u xmpp://usr:pwd@my_xmpp.com exec --oml_uri tcp:srv:port tutorial00.rb
+        omf_ec -u xmpp://usr:pwd@my_xmpp.com exec --oml_uri tcp:srv:port experiment01.rb
 
   - **replace** *xmpp://usr:pwd@srv* with the credentials for your user on the
   xmpp pubsub server that is used to communicate with the resources
@@ -376,7 +393,7 @@ furthermore want to use the OML2 server with hostname 'my_oml.com at port
 3003 to collect the measurement of your experiment, then you would use the
 command:
 
-        omf_ec -u xmpp://foo:bar@my_xmpp.com exec --oml_uri tcp:my_oml.com:3003 tutorial00.rb
+        omf_ec -u xmpp://foo:bar@my_xmpp.com exec --oml_uri tcp:my_oml.com:3003 experiment01.rb
 
 If you would like to know more about the other options of the OMF EC software
 please run the commands:
@@ -394,15 +411,15 @@ similar to this:
       INFO  Object: Connected
       INFO  Object: Start experiment: 2013-03-14T03:48:48Z
       INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
-      INFO  OmfEc: Subscribed to omf6.nicta.node8
-      INFO  OmfEc: Config omf6.nicta.node8 to join Sender
-      INFO  OmfEc: Newly discovered resource >> omf6dev.node8
+      INFO  OmfEc: Subscribed to omf.nicta.node9
+      INFO  OmfEc: Config omf.nicta.node9 to join Sender
+      INFO  OmfEc: Newly discovered resource >> omfdev.node9
       INFO  OmfEc: Event triggered: 'ALL_UP'
       INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a_application
       INFO  OmfEc: Resource xmpp://[email protected] created
       INFO  OmfEc: Newly discovered resource >> bd9c68d5-1469-41a0-9a33-4bdba501f7b0
       INFO  OmfEc: Event triggered: 'ALL_UP_AND_INSTALLED'
-      INFO  Object: This is my first OMF experiment
+      INFO  Object: Initializing first OMF experiment event
       INFO  Object: Request from Experiment Script: Wait for 10s....
       WARN  Object: Calling 'wait' or 'sleep' will block entire EC event loop. Please try 'after' or 'every'
       INFO  OmfEc: APP_EVENT STARTED from app ping_oml2_cxt_0 - msg: env -i /usr/bin/ping-oml2 -a www.nicta.com.au -c 3 --oml-config /tmp/bd9c68d5.xml
@@ -421,8 +438,8 @@ similar to this:
 
 The above screen output was optained when running the EC on the NICTA testbed,
 with the experiment described in
-{file:doc/tutorials/tutorial00.rb tutorial00.rb}
-and using the resource named 'omf6.nicta.node8'
+{file:doc/tutorials/experiment01.rb experiment01.rb}
+and using the resource named 'omf.nicta.node9'
 
 ### 4c) What does that screen output mean?
 
@@ -435,17 +452,17 @@ this experiment (ID, xmpp server used, resource used,...):
         INFO  Object: Connected
         INFO  Object: Start experiment: 2013-03-14T03:48:48Z
         ...
-        INFO  OmfEc: Subscribed to omf6.nicta.node8
-        INFO  OmfEc: Config omf6.nicta.node8 to join Sender
+        INFO  OmfEc: Subscribed to omf.nicta.node9
+        INFO  OmfEc: Config omf.nicta.node9 to join Sender
 
 - It also provides us some feedback about its communication with the xmpp
 server and other OMF entities:
 
         ...
         INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
-        INFO  OmfEc: Subscribed to omf6.nicta.node8
+        INFO  OmfEc: Subscribed to omf.nicta.node9
         ...
-        INFO  OmfEc: Newly discovered resource >> omf6dev.node8
+        INFO  OmfEc: Newly discovered resource >> omfdev.node9
         ...
         INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a_application
         ...
@@ -469,7 +486,7 @@ results/outputs:
 
         ...
         INFO  OmfEc: Event triggered: 'ALL_UP_AND_INSTALLED'
-        INFO  Object: This is my first OMF experiment
+        INFO  Object: Initializing first OMF experiment event
         INFO  Object: Request from Experiment Script: Wait for 10s....
         WARN  Object: Calling 'wait' or 'sleep' will block entire ...
         INFO  OmfEc: APP_EVENT STARTED from app ping_oml2_cxt_0 - ...
@@ -533,7 +550,7 @@ use that tool, please refer to the [omf_web documentation]
 6. What should I do next?
 -------------------------
 
-We will soon release more tutorials on how to use all the features of OMF6
+We will soon release more tutorials on how to use all the features of omf
 from the experimenter's perspective.
 
 In the meantime, you may have a look at the OMF 5.4 documentation, which