How to use your own or a 3rd party application with OMF¶

1. Prerequisites¶

• Make sure that you understand how OMF works from a user's point of view.
• Make sure that you have completed and understood the basic "Hello World" tutorial.

2. Goal¶

• As mentioned earlier, to be able to use your own applications (or 3rd party applications) in your OMF experiment, you need to write an OMF Application Definition for them.

• An Application Definition can be viewed as an interface that makes the OMF Experiment Controller aware of your application, i.e. which parameters it accepts, which measurement points it provides, or where to find the package files that contains it.

• This tutorial shows you:
  • how to write an OMF Application Definition
  • how to use it within your Experiment Description

3. Scenario¶

• Here we are using the same simple scenario as in the basic "Hello World" tutorial.

• This tutorial will show you how we created the OMF Application Definition for the OTG2 application used in the "Hello World" experiment.

4. Developing the Application Definition for the example OTG2 Application¶

• Following is an example of a valid application definition for the OTG2 Application:
• Note: the real application definition for OTG2 from the OMF packages may differ from this example. Indeed, some of the configurable parameters or properties of OTG2 were omitted from this example to make it clearer to explain.

 1 defApplication('otg2application', 'otg2') do |app|
 2 
 3   app.path = "/usr/bin/otg2" 
 4   app.appPackage = "/home/myUsername/myArchive.tar" 
 5   app.version(1, 1, 2)
 6   app.shortDescription = "OMF Traffic Generator v2" 
 7   app.description = "OTG is a configurable traffic generator." 
 8 
 9   app.defProperty('udp:broadcast', 'Broadcast', nil, 
10                   {:type => :integer, :dynamic => false})
11   app.defProperty('udp:dst_host', 'IP address of the Destination', nil, 
12                   {:type => :string, :dynamic => false})
13   app.defProperty('udp:dst_port', 'Destination Port to send to', nil, 
14                   {:type => :integer, :dynamic => false})
15   app.defProperty('udp:local_host', 'IP address of this Source node', nil, 
16                   {:type => :string, :dynamic => false})
17   app.defProperty('udp:local_port', 'Local Port of this source node', nil, 
18                   {:type => :integer, :dynamic => false})
19   app.defProperty("cbr:size", "Size of packet [bytes]", nil, 
20                   {:dynamic => true, :type => :integer})
21   app.defProperty("cbr:rate", "Data rate of the flow [bps]", nil, 
22                   {:dynamic => true, :type => :integer})
23 
24   app.defMeasurement('udp_out') do |mp|
25     mp.defMetric('ts',:float)
26     mp.defMetric('flow_id',:long)
27     mp.defMetric('seq_no',:long)
28     mp.defMetric('pkt_length',:long)
29     mp.defMetric('dst_host',:string)
30     mp.defMetric('dst_port',:long)
31   end
32 
33 end

• Line 1: declares the URI and name for your OMF Application definition:

Syntax:   defApplication (URI, name)
          - URI     The URI where your Application Definition resides
          - name    The human-readable name of your Application Definition

Examples of valid URIs:
- "otg2application"   => This Application Definition is saved in a file "otg2application.rb", 
                         which is located in the same directory as the Experiment Description
                         that is using this Application Definition
- "dir1:dir2:otg2"    => This Application Definition is saved in a file "otg2.rb", which is 
                         located in the sub-directories "dir1/dir2" of the same directory as the
                         Experiment Description using this Application Definition

Note:   1) About the URI search path
           The EC will first assume that the URI is relative to the current directory where it
           is being invoked, then it will search for it in two predefined default OMF paths where 
           the EC-bundled Application Definition reside.
           A future version of OMF (>5.3) will allow the use of absolute URIs which for example 
           could refer to Application Definitions hosted on some webservers

        2) The Application Definition can also be directly added in the top of your OMF Experiment
           description, instead of being saved in a separate file. In such case, OMF will directly
           load your Application Definition before it loads your Experiment Description, and thus 
           it will not try to resolve the URI as described in 1) above.

• Line 3: declare the absolute path where your application resides on the resources
  • Here the application otg2 is located in /usr/bin/ on the nodes

• Line 4: (optional) Specify an automatic method to install your application the resource
  • OMF 5.3 supports 3 types of installation schemes:

- "TAR-based Install" - Your application is packaged in a TAR archive, which will be uploaded
                        to each resource. This TAR archive will be extracted at the root @/@
                        directory of the filesystem of each resource. Therefore, you must layout 
                        the directory structure in your TAR archive in the exact way you would 
                        like its content to be placed in the resource's filesystem.

                        Syntax:   appPackage = URI

                        where URI points to where your TAR file resides, e.g. it could be a local
                        file or a complete URL. For example:
                           appPackage = "/home/me/mydir/my_application_archive.tar" 
                        or 
                           appPackage = "http://mytestbed.net/my_application_archive.tar" 

- "DEB Install" - Your application is packaged as a Debian/Ubuntu DEB package

                  Syntax:    debPackage = MyPackageName

                  Note: OMF assumes that the resource on which the package will be installed 
                  has a properly configured APT tool

- "RPM Install" - Your application is packaged as a Fedora RPM package

                  Syntax:    rpmPackage = MyPackageName

                  Note: OMF assumes that the resource on which the package will be installed 
                  has a properly configured YUM tool

• Line 5-7: more information about your application

• Line 9-22: declare the properties of your applications. These are the command-line parameters of the applications, that you would like to set within your Experiment Description.

Syntax: defProperty(name, description, mnemonic = nil, options = nil)

  - name: the long name parameter for this property (i.e. called with "--")
  - description: some text describing this property
  - mnemonic: a mnemonic for this property (i.e. called with "-")
  - options: a list of options associated with this property
     Currently, the following options are defined:
       :type => type             Checks if property value is of 'type'. If type is 'Boolean', only the name, or mnemonic is used if 'true'
       :dynamic => true|false    Id true property can be changed at run-time
       :order => int             Uses the int to order the properties when forming command line
       :use_name => true|false   If false only use value, not name (important mnemonic must be se to 'nil')

Examples:

  - If your application command line is:  "myapp --cbr:size 123" 
    and the "cbr:size" argument can be changed dynamically

        app.defProperty("cbr:size", "Size of packet [bytes]", nil, {:dynamic => true, :type => :integer})

  - If your application command line is:  "myapp --cbr:size 123" 
    and the "cbr:size" argument cannot be changed at runtime, then:

        app.defProperty("cbr:size", "Size of packet [bytes]", nil, {:dynamic => false, :type => :integer})

  - If your application command line is:  "myapp -d 4" 

       app.defProperty("--debug-level", "Version of this application", "d", {:dynamic => false, :type => :integer})

  - If your application command line is:  "myapp someValue" 

       app.defProperty("--some-parameter", "Some Other Parameter", nil, {:dynamic => false, :type => :string, :use_name => false})

• A complete description of the defProperty command is given in the OEDL reference manual.

• Line 24-31: declare a OML Measurement Point (MP) and the associated metrics that your application is providing.
  • This step is optional if you do not wish to collect any measurement from your application
  • These are the MP and metrics that were previously added to your application source code
    • the Quick Start OML tutorial shows you how to add Measurement Point to your application's source code
    • the OML-enabled Ruby Wrapper tutorial shows you how to write an OML-enabled wrapper around an existing application for which you do not have the source code
  • A complete description of the defMeasurement command is given in the OEDL reference manual

Syntax: defMeasurement(id)
  - id: the identification of the Measurement Point (MP), 
        as defined in your application source code

Syntax: defMetric(name, type)
  - name: the name of a metric associated with your MP, 
          as defined in your application source code
  - type: the type of this metric 
          (e.g. :float, :integer, :string)

5. Using your Application with OMF¶

• The "Hello World" tutorial shows how to use an application in your experiment, via its Application Definition

• Here is the relevant code snippet from the "Hello World" experiment description:

 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   ...
 9 end

• Note:
  • OMF 5.3 has a default installation of the OTG2 Application Definition, hence the URI test:app:otg2 in the above snippet
  • If you wanted to use the Application Definition which we described above, then you should replace Line 2 in the above snippet by:

1   ...
2   node.addApplication("otg2application") do |app|
3   ... 

6. Running the experiment¶

To run this experiment you should use the exact same commands and instructions as for the "Hello World" tutorial.

You should also see a similar type of output as for the "Hello World" tutorial.

7. The Results¶

Again here, you should obtain some similar type of results as in the "Hello World" example, and you should be able to obtain a similar graph either by processing the result database with your own tools, or by using the EC's graph capabilities.

6. What is Next?¶

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

• How to describe and run a simple wireless experiment - (wired version)

• How to pass parameters to your experiment, and change them at run-time

• How to configure or address all resources within a defined group, and use simple substitutions

• How to use your own or a 3rd party application with OMF

• How to use Measurement Filters to customise your Measurement

• How to use Prototypes to specify particular Applications

• How to save a disk image

• How to load a disk image

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

• The Conference Room tutorial

---