Integration of IRIS in OMF

OMF IRIS Architecture

The NITOS team has developed the appropriate extensions for supporting the IRIS (Implementing Radio in Software) platform with OMF.

More information about IRIS platform and guidelines of installing it to your testbed can be found here.

Our extensions have been bundled in .deb packages available in NITLab's repository. Target platforms are only debian based. For any other platform you can overwrite the default OMF files with the source files found in NITLab's git repository. You can clone the files with the following command, if you have an account in the NITLab server:

 git clone This email address is being protected from spambots. You need JavaScript enabled to view it.
 :/home/git/repos/iris.git

In order to install our package, you need to initially setup the official OMF version (our extensions currently support version 5.4).

Instructions on how to install OMF-5.4 in your testbed are available here.

In order to install our extensions, add the following repository in your your target machines (server and nodes), in the respective "/etc/apt/sources.list" file.

 deb http://nitlab.inf.uth.gr/ubuntu precise/

You can now install our extensions for the Experiment Controller (EC) at the server with the following command:

apt-get update && apt-get install omf-expctl-iris

The EC contains some more configuration lines in the configuration file included in /etc/omf-expctl-5.4/omf-expctl.yaml

Depending on your setup, you need to configure a folder which will be used for transferring the IRIS configuration files to the RCs of the nodes, and the default network interface that communicates with the node network.

If any errors occur during an experiment execution (regarding the FTP service used), you might consider reinstalling the "ftpd" gem. This is included in the .deb file but errors might occur in a different machine.

In order to install the OMF RC for IRIS on the nodes you will have to issue the following commands:

 apt-get update && apt-get install omf-resctl-iris

Installing this package on a node will unpack a Launcher.cpp file at the root directory of the node. (/root/Launcher.cpp). This file needs to replace the default launcher used by IRIS in the iris_core package. The file can be found at "iris_core/src/Launcher.cpp". The custom launcher is used to receive commands via socket messages from the RC, making interoperable with OMF. You will have to compile/recompile the IRIS framework with the new Launcher file.

If the nodes are up and running, you can now use a simple OMF Experiment Definition (ED) to configure the IRIS components running on multiple nodes.

Here is an example script that highlights the syntax adopted for configuring IRIS through OMF.

# Configure a group of the nodes which we will be used for the experiment
defGroup("Usrp","omf.nitos.node045"){ |node|

        # Set the full path were the configuration file can be found in the server.
        # This file will be transfered to the node before the experiment begins.
        node.net.u0.path_file="/root/omf_iris/ofdm_rx_usrp_to_file.xml"
}

onEvent(:ALL_UP_AND_INSTALLED){ |event|

        info "Starting an experiment with IRIS components"
        wait 6        
        
        info ("Trying to execute a Quit function for IRIS without it having started. It should raise an exception") 
        group("Usrp").usrpQuit()
        wait 15

        info ("Starting IRIS...") 
        group("Usrp").usrpStart()
        wait 15
        
        info ("Reconfiguring IRIS with a new configuration file..")         
        group("Usrp").usrpReconf("/root/omf_iris/ofdm_rx_usrp_to_file_reconf.xml")
        wait 15
        
        info ("Finally we stop IRIS execution..")
        group("Usrp").usrpQuit()
        wait 15 

        info "End of the Experiment."
        Experiment.done
}

The experiment lifecycle from an administrator's view is:

1. Experiment submitted to the OMF EC. If a device noted as "uX" (eg. u0, u1, etc) is included in the OMF ED, start an FTP service which will serve to the node included in the specific group the IRIS configuration file.

2. The specified resource (omf.nitos.node045 in our example), downloads the file from the FTP server in the /tmp directory. It setups the "eth1" port with an IP address able to communicate with the USRP device.

3. When the GROUP_NAME.usrpStart() command is issued, IRIS will be executed on the node with the following aruments:

 /usr/local/bin/iris -p /usr/local/lib/iris_modules/components/gpp/phy/ -t /usr/local/lib/iris_modules/components/gpp/stack/ -c /usr/local/lib/iris_modules/controllers/ /tmp/iris.xml

where iris.xml is the sample configuration file for IRIS transfered to the node.

4.When the GROUP_NAME.usrpReconf("conf file") command is issued, the node downloads a new configuration file, rewrites the old and sends the Reconfigure command to the IRIS platform.

5. When the GROUP_NAME.usrpQuit() command is issued, IRIS is terminated.

The experiment illustrated is just a sample experiment that involves only one resource with a USRP.

You can save it in a file (eg. iris.rb) and execute the script from the testbed server with the command:

 omf exec iris.rb

You can enhance this example by combining multiple IRIS resources and including traffic generators which are already OMF compatible such as iperf.