This page and its sub-pages presents some information related to the previous OMF 5.2 release

Please visit the pages linked from the Main User Guide page for the documentation on the latest OMF version

---

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 and example.

2. Goal¶

As mentioned on the usage overview page, to be able to use these applications in you OMF experiment, you need to write an OMF Application Definition for them.

Basically, this Application Definition can be viewed as an interface that makes OMF entities aware of your application, i.e. which parameters it does accept, which measurement points it does provide, or where to find the package/archive files that contains your software.

• 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 and example.

• Instead of modifying this simple "Hello Wolrd" experiment description, we will show you how we created the OMF Application Definition for the 2 simple applications used in this "Hello World" example.

4. Developing the OMF Application Definition for the OTG Application¶

 1 defApplication('otg2application', 'otg2') {|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') { |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   }
32 
33 }

• Line 1: declare the URI and name for your OMF Application definition
  • Syntax: defApplication (URI, name)
  • URI = "otg2application"
    • This application definition is saved in a file named "otg2application.rb", located in the same directory where you would execute your Experiment Description
    • Alternatively, the URI can also refer to a different directory
      • For example: "dir1:dir2:filename" means that this Application definition is in the file "filename" which is either in the local directory "./dir1/dir2" or in OMF's bundled directory "dir1/dir2".
  • name = "otg2"

• Line 3: declare the absolute path where your application resides on the experiment resources (e.g. on the disk of the testbed nodes)

• Line 4: (optional) If your application is not already installed on the experiment resources, this tells OMF where to find the TAR archive with the binaries to install. The path that you give here is a local path to the TAR archive on the local machine on which you are running this experiment description. OMF will copy this local TAR archive from your local machine to each resources as required. This TAR archive will then be extracted at the ROOT "/" of the filesystem on these resources. Therefore, you must layout the directory structure in your TAR archive in the exact way you would like its content to be placed within each node's filesystem.

For example, the TAR archive may contain the following 
directory layout (use: 'tar -tf myArchive.tar'):
    usr/
    usr/bin/
    usr/bin/otg2
    etc...

• Line 5-7: more information about your application

• Line 9-22: declare the properties of your applications, i.e. these are the command line parameter of your applications which you would like to set within your OMF 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

Examples:

  - If your application command line is:  "myapp --cbr:size 123" 
    And the "cbr:size" argument can be changed dynamically
    Then:  
        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" 
    Then:  
       app.defProperty("--debug-level", "Version of this application", "d", 
                       {:dynamic => false, :type => :integer})

  - If your application command line is:  "myapp someValue" 
    Then:  
       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.
  • These are the MP and metrics that were previously added to your application source code
  • Please refer to The Quick Start OML Tutorial from the OML project, to learn how to that
  • A complete description of the defMeasurement command is given in the OEDL reference manual. Note that this step is optional if you do not wish to collect any measurement from your application.

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 Basic "Hello World" example shows how to use an OMF Application Definition within your Experiment Description in order to use your application in your experiment.

Note: For an easier reading, this example has the application URI set "otg2application" in the above line 1. The URI of the real otg2 application definition, which is used by the "Hello World" example is "test:app:otg2".

5. Running the experiment¶

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

You should also see the exact same type of output as for the Basic "Hello World" example.

6. The Results¶

Again here, you should obtain the exact same type of result as in the Basic "Hello World" example, and you should be able to do the same processing to obtain a similar graph.

7. What is Next?¶

Now that you have learnt how to develop an Application Definition in order to use your application with OMF, you can:

- either go back to refer to the Basic "Hello World" tutorial and example

- or continue reading the following basic OMF tutorials. Each one of them is introducing a new basic OMF feature, incrementally building on the simple "Hello World" example. You do not need to follow them in the order suggested below.

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

• Configure/Send actions to all resources in one/many group(s), with substitutions

• How to use Measurement Filters to customise your Measurement

• How to use Prototypes to specify particular Applications

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

• The Conference Room tutorial

---

This page and its sub-pages presents some information related to the previous OMF 5.2 release

Please visit the pages linked from the Main User Guide page for the documentation on the latest OMF version