iMinds WLAN Course installation package

The iMinds WLAN course contains all necessary files to deploy your own FORGE course. All content used in the iMinds WLAN course is included, and can be used as a template or inspiration to deploy your own course.
The actual experiment execution is based on OMF, with scripts and config files provided for OMF 5.4 and 6. By default everything is preconfigured to run on OMF 5.4, but switching to OMF 6 is as simple as calling the respective omf6* scripts.

REQUIREMENTS
------------
To run this course 3 wireless capable nodes are required, with 2 wireless cards each (1 card can be omitted if the AdHoc exercises are skipped). A separate web server with connectivity to the wireless nodes is required to host the course content and run the necessary scripts to perform the experiments. All machines should be able to run OMF, primarily requiring Ruby. Further details are provided in the INSTALL document.

PACKAGE STRUCTURE (only relevant files are shown)
-----------------
<omf>    #contains all OMF OEDL Experiment Description files (accessed by toolbox scripts)
    <omf54>            #OMF 5.4 ED
        wlan1-1.rb    #ED for exercise 1
        wlan1-2.rb    #ED for exercise 2
        wlan1-3.rb    #ED for exercise 3
        ...
        iperf.rb    #OMF Application Definition of OML2 Iperf
    <omf6>            #OMF 6 ED - note: not all exercises are available as OMF6 ED, but the first six are provided as examples
        wlan1-1.rb    #ED for exercise 1
        wlan1-2.rb    #ED for exercise 2
        wlan1-3.rb    #ED for exercise 3
        ...
        iperf6.rb    #OMF Application Definition of OML2 Iperf

<toolbox>                    #contains Bash toolbox scripts for managing and starting the OMF EC (only one instance allowed) and one script for managing the OMF6 RC
    omf54config.sh             #shared configuration for all OMF 5.4 scripts
    omf54ec_start.sh         #starts an OMF EC instance with given arguments (first being the name of the ED file) - stops a previous running EC if present
    omf54ec_status.sh         #gives information about the last or running OMF EC job (running status, experiment id, last 5 lines of EC log)
    omf54ec_stop.sh         #stops the running OMF EC (if present)
    omf6config.sh             #shared configuration for all OMF 6 scripts
    omf6ec_start.sh         #starts an OMF6 EC instance with given arguments (first being the name of the ED file) - stops a previous running EC if present
    omf6ec_status.sh         #gives information about the last or running OMF6 EC job (running status, experiment id, last 5 lines of EC log)
    omf6ec_stop.sh             #stops the running OMF EC (if present)
    <resources>                    #contains toolbox scripts and config files to be used by experiment resources
        omf6rc_watchdog.sh         #Watchdog script to ensure always up OMF6 RC, must be ran on the testbed resources (currently very OS specific, only guaranteed to work on Ubuntu 12.04)
        ap.sh                    #script for starting the Access Point through hostapd
        inf_hostapd.conf        #hostapd settings for the AP, contains infrastructure channel setting
        sta1.sh                    #script for associating station 1 to the AP (must be ran after the AP is up) and setting up an AdHoc network (contains AdHoc channel setting)
        sta2.sh                    #script for associating station 2 to the AP (must be ran after the AP is up) and setting up an AdHoc network (contains AdHoc channel setting)

<web>    #contains the actual course, to be served by a web server. Built on the Bootstrap framework (http://getbootstrap.com/)
    <css>            #contains all css files for styling the course, mostly Bootstrap related
        main.css    #specific course styling (loader, status bar, graphical tweak)
    <exercises>            #contains the title and description of each exercise widget, processed by exercise.php
        wlan1-1.php        #title and description of the first exercise
        wlan1-2.php        #title and description of the second exercise
        ...
    <js>                        #contains all javascript for the course, mostly cosmetic, except for following two files
        experimentcontrol.js     #first attempt to group generic experiment control. Responsible for communication between web client and the php scripts.
        wlan.js                 #course specific javascript, styling and callbacks from experimentcontrol.js
        ilabt.js                #testbed specific javascript, used only for processing experiment availability information, not required for course execution.
    index.php                        #main course page, contains the entire course
    widget.php                        #contains a single exercise widget
    exercise.php                    #generates the content of an exercise, based on the query parameter (e.g. ?id=wlan1-1) and the contents of the files in the exercises folder
    expstatus.php                    #returns a JSON status object, containing all the information from the omf54ec_status.sh script
    getresults_iperf_jitter.php        #handles local PostgreSQL calls to the OML2 database to visualize iperf jitter data, needs to be provided with an experiment id (obtainable from expstatus.php)
    getresults_iperf_transfer.php    #handles local PostgreSQL calls to the OML2 database to visualize iperf throughput data, needs to be provided with an experiment id (obtainable from expstatus.php)
    infup.php                        #simple ping check to test if the experiment resources of this course are up
    startexp.php                    #starts an experiment, mainly a sanity check before calling the omf54ec_start.sh script (checks userqueue.php to test if it's the user's turn)
    stopexp.php                        #stops the running experiment (if userqueue.php confirms the user is the active user)
    userqueue.php                    #custom user queue implementation based on APC shared memory, can be called from any other php script to test the UID or modify the queue

INSTALLATION
------------
See INSTALL document

BUILDING YOUR OWN COURSE
------------------------
If you want to use this course as inspiration/building blocks for your own course it is suggested to first install and this course, so you can start from a working baseline.

To create your own exercises, first start by creating your own OMF Experiment Descriptions, use the provided EDs in <omf> as inspiration. Try to run the experiments manually through OMF to work out the bugs and see if you get the required behavior.

for each OMF ED you create, create a php file under <web/exercises> with the same name, containing the name of the exercise and the description (can be any HTML content).

Some custom JavaScript for your course might be required, have a look at experimentcontrol.js in <web/js> and the description of getArguments(expId), getGraphType(expId), initChart(placeholder,plotdata,type) placeholders. To look how it's implemented for this course, see wlan.js in the same directory. Once you have created your own custom JavaScript, make sure this is loaded after experimentcontrol.js in both index.php and widget.php (instead of wlan.js).

Finally, you should modify index.php to contain your supporting course material.

August 20, 2014