Advanced w.iLab-t experiment tutorial

In this tutorial we will use the more advanced features of the w.iLab-t testbed by benchmarking a channel switching protocol for wireless sensor networks (WSN) in a wireless environment we create by using linux scripts.

We will use 4 embedded PCs to generate the wireless interference for the wireless sensor network, together with a full zone of sensor nodes that use a simple reporting method to send periodical data to a sensor node sink.

The example topology used for this experiment is shown below, with the 4 embedded PCs being node 46,52,53 and 54. The server is the 802.11g access point, with the other 3 embedded PCs fulfilling the role of stations. All green nodes are the sensor nodes, reporting to node 48.

During this tutorial, we will upload scripts to W-iLab.t to manage the behavior of the PCs, and install a TinyOS image to control the WSN nodes. The goal of this tutorial is to familiarize yourself with the extended features of wilab, including WSN benchmarking, controlling the embedded PCs and visualizing experiment data on the w.iLab-t website.

1. Basic Tutorial

Please go through the basic tutorial before continuing with this advanced tutorial.

2. Create the sensor job

An experiment on Wilab.t can be run on both the sensor nodes and the embedded (Alix) PCs. The sensor part of the experiment is mandatory in the current version of Wilab.t. If you just want to perform an experiment on the embedded PCs, it is allowed to use dummy sensor code. For this tutorial however, we will make full use of the sensor and embedded PC capabilities. This part describes how you can upload your own sensor binaries and create your sensor job.

Go to the job page to create your sensor job.
Click the Create new job button and fill in a name and description. Click next or go to the files tab.

In the files tab you must select at least one Program file and one Class File. The Program File contains the firmware that will be programmed on the sensor nodes. Sensor nodes can send messages to the w.iLab-t server which will be logged in the database. The Class Files define which messages, that are sent by the sensor node, will be logged in the database.

For this tutorial, we will upload our own sensor binaries and message classes. You can find all the necessary files here. After downloading these files, please scroll down to the bottom of the files tab and click Browse.... Now select the file you want to upload, provide a reference name (will be used to show the file in the list) and add a description (optional). Click the Upload button to start uploading. Repeat this step for every file you want to upload.

Now select the binary and message classes you just uploaded in the list on the left and click the Add>> button. Please note the ID (e.g. 6791) displayed to the right of the message class you just added, you will need this later.



Click Next or go to the motes tab.

You can choose to run the firmware on all available sensor nodes, or pick some specific nodes out of the list. The right plane shows the nodes excluded from the job whilst the left plane shows participating nodes. For this experiment, we can just run the experiment on all available sensor nodes.



The scenario tab will not be used in this tutorial. For more info on this feature, please read the howto.
We will get back to the platform tab at the end of the next section.

Just click the Submit button at the bottom of the page if you are done setting up your sensor job.

3. Define an iPlatform

Hint:In case you never scheduled a Wi-Fi enabled experiment before, it is a good idea to first check the general info on iNodes and iPlatforms and possibly the tutorial on Wi-Fi experiments.

The previous section described how you can run experiments on the sensor nodes. This part will go into detail on how to run linux scripts and/or binaries on the embedded PC's on Wilab.t.

Go to the iPlatform page and click New Platform. On the description tab you can insert a name and a description(optional). Be sure NOT to insert any whitespace in the name field. Now click Next or go to the mounts tab.

Every Wilab.t user has his own user directory on the Wilab.t fileserver (Wilabfs). Please log in to wilabfs using your Wilab.t database name (see the user info page if you cannot remember it). An example command for the fictional "crewuser" account : ssh crewuser@wilabfs.atlantis.ugent.be



Step into the iPlatform directory and create a new folder for your new iPlatform (you might want to choose the same name you inserted on the web page).
You can find the files to create your iPlatform here. Please copy all the files to your newly created directory and make the scripts executable using the chmod +x scriptname command.

Have a look at the start_mount_code file. This script will be executed automatically when your iPlatform is started. So everything you want to execute in your experiment should be called from this script. You can ofcourse create your own script and call it from the start_mount_code script as it is done in this tutorial. Please change the user credentials in the "variables" script so that it reflects your settings. Feel free to look at how the scripts interact with the database and log directories, but a complete decomposition is out of scope for this tutorial.

We can now go back to the web interface and select the nfs-mount to upload to Wilab.t. If you named your iPlatform e.g. "tutorial", your nfs-mount will probably look like this : wilabfs.atlantis.ugent.be:/home/crewuser@crew-project.eu/iPlatform/tutorial. The directory you define here MUST contain the start_mount_code script! Otherwise your iPlatform will not be executed.



Just provide a reference name and a description(optional) and click Upload.
The iPlatform can also contain a kernel. If you select this option, the kernel will be uploaded to the embedded PC's and will be executed when your iPlatform is started. We will not use this feature in this tutorial.

After uploading the nfs-mount, you can select it from the list on top of the mounts tab and click Add>>.

Proceed to the nodes tab to select the nodes on which you want to execute the iPlatform. This is the same as for the sensor nodes. Please note that in the current version of Wilab.t the sensor node must be included in the experiment in order to be able to run an iPlatform on the embedded PC connected to the sensor node.

Click Submit to save your iPlatform.

The last step in creating your job is to link your iPlatform to the sensor job. So go back to the job page, select the job you created in the previous section and click Edit Job.
Proceed to the platform tab and select your iPlatform from the dropdown list.



Don't forget to press the Submit button to save your job.

4. Scheduling your experiment

Now that we created our first job, we can schedule it to be executed on the testbed.
On the schedule page select the job you want to execute and select a zone (part of the testbed) in which you want it to run. You should choose between 1A/1B/2A/2B/3A/3B, but the default configuration has been done for 3B. If you wish to run the experiment on a different level, you can change the 3 wifi nodes that will generate interference in the "variable" script, inside the iPlatform directory.

It is also possible to adjust the global variables of your sensor code. This can be a huge time saver, since the sensor code needs to be recompiled and uploaded after each change. The provided sensor code for this tutorial needs some parameters tweaked for the actual experiment, so please click on the parameters button.

Now all the global parameters of sensor code are listed using a BNF syntax (please click the bnf button just above the parameters to learn more). For this tutorial, we are only interested in the prefix Benchmarking_P. The following parameters are important for this tutorial:

• Benchmarking_P.target: the nodeID of the WSN sink in the experiment (for 3B: 48)
• Benchmarking_P.node_purpose: does a sensor node partake in the experiment? (for 3B: 50,48:0,1)

For a full API of the benchmarking code, please read more here. After setting the parameters, it is time to schedule our experiment.

(IMPORTANT: the iMinds w.iLab-t does not allow wifi experiments to be performed during office hours. It is advisable that you schedule your experiment from 20u-6u Brussels time or during weekends.)

Now double click the first time slot where you want the experiment to start and select some consecutive blocks to determine the duration of the experiment. For this experiment, 20 minutes should suffice. Click Schedule Job to confirm the selection.



Now the experiment will start at the scheduled slot, you can choose to follow the experiment live or perform an analysis afterwards.

5. Analyse your experiment

There are multiple ways to analyse a running or previous experiment. For this tutorial we will be looking at three methods:

• w.iLab-t visualiser
• w.iLab-t analyser
• log files

Additionally, you can connect directly to your personal mysql database on the wilab server using a mysql library in your own scripts, or directly through the phpmyadmin web interface.

The main difference between the two tools on the w.iLab-t website is that the visualiser provides a spatial view of the testbed, with typically per node characteristics, while the analyser provides different graphs and is most often used for a temporal view of the experiment (line chart, scatterplots and barcharts are supported). Both tools can be used during or after an experiment.

We will now customize two configuration files for both w.iLab-t tools and upload them to our toolbox page. Download the zip file with both xml scripts here, and open them in your favorite xml/text editor. For both xml files 3 parameters have to be changed, preferably with a replace all command:

• ___USERNAME___: your w-iLab.t database name (see the info page if needed)
• ___PASSWORD___: your w-iLab.t password
• ___MSGID___: the ID of the message class you added in the Job page (see the "Create the sensor job" section if needed)

If you would not like to edit the parameters now, you can upload the files as is, and the respective tools will ask you to substitute them at run time.

Go to your toolbox page and scroll to the upload box at the bottom:



Click Choose file to navigate to the xml configuration files and select the correct type (Analyser or Visualiser, corresponding with the first word of the file name) in the box below. Choose a name for your script, for this tutorial the file name will be used. Scroll down and press the upload button.

After uploading the configuration files it is time to familiarize ourselves with the two w-iLab.t analytic tools.

w.iLab-t visualiser

The toolbox page gives access to the visualiser and analyser, where you can select an XML configuration file for the respective tools. These files can be edited or created by yourself to suit your experiment.

Select the Visualiser_BenchReliability XML file and click Start Visual to start the Java applet that will visualise your experiment. Now fill in your database user name (not email) and password, together with the experiment ID you want to visualise.

Once the applet has finished loading, you should now see a colored circle with the sensor node id for every active sensor node in your experiment. After some time, every node should log some info to the database and the circles should change color depending on their individual reliability. The reliability and chosen channel is also included in the text below each node. Nodes that receive messages are indicated with an additional circle, with the total count of received messages in text under the node.



w.iLab-t analyser

The analyser is also located on the toolbox page, where you should select the Analyser_BenchReliability script. This script will present a line chart with different metrics recorded during the experiment. Fill in your database user name (not email) and password, together with the experiment ID you want to visualise when prompted. Please be patient for the graph to load, and you should get a visualisation of the following metrics:

• Cumulative sensor network reliability
• 30 second window average sensor network reliability
• Cumulative wifi traffic
• Zigbee channel of the sensor nodes



The resulting graph will allow you to more thoroughly analyse the performed experiment. The applet supports zooming, just by dragging a box over the area of interest. Be dragging the mouse in a northwest direction the entire x and y range is plotted again.



Additionally, the applet provides advanced customization and export functions using the right click context menu, which can be useful to import the post processed results in your favorite charting program.

log files

In case your experiment fails, has strange results or you want to look under the hood, you can access all the raw log data that your scripts produce in the log directory of the wilabfs server. These log files should be created by yourself if you write your own scripts, but some example convenience functions are provided (for a more extensive list, take a look at the source of the “variables” script included in this tutorial)

• Log directory for the specific node:
  `find ../ -maxdepth 1 -type l -exec ls -l {} \; | cut -f 2 -d '>'`
  
• Log directory for the total experiment:
  JOBDIR=`dirname $NODEDIR`
  

This leads to a hierarchical directory structure inside your iPlatform directory “log” that allows you to store all the desired logs per experiment and per node