Using the embedded PC and Wi-Fi: tutorial

Before completing this tutorial, read the embedded PC and Wi-Fi (iNode) basics, and familiarize yourself with the w-iLab.t basics by running a sensor-only experiment.

This information applies to the w-iLab.t office testbed only.

Step 1: the basics

When working with iPlatforms and iNodes, you will typically follow an iterative approach, in which you modify your iPlatform(s) until your iNodes are behaving just as you want them to behave.  As a reminder, an iPlatform will contain all information (scripts, binaries, etc.) to configure and operate your node.

• After enabling your OpenVPN connection (No VPN connection or w-iLab.t account yet? Check the w-iLab.t basics tutorial ), connect via your favorite SSH tool to wilabfs.atlantis.ugent.be using your w-ilab.t credentials.
• Go to your iPlatform directory (cd iPlatform), create a new directory named "tutorial" (mkdir tutorial), and go to this new directory (cd tutorial).  Every time you will design a new platform, it is a good idea to create a new directory. [Note - when running more advanced experiments: as the entire iPlatform directory will be mounted on your iNodes anyway, you could e.g. also make a directory with custom libraries or binaries that you use across several of your iPlatforms].
• Now we are creating an iPlatform through the web GUI. Log in, select iPlatform from the top menu. And click on "New Platform".
• Name your experiment (e.g. tutorial_wifi) and provide a description of this platform (e.g. "my tutorial iPlatform"). Click "next".
• On the Mounts tab, you can select which NFS mount should be used for this particular iPlatform.  Use the fields below the "next" button to specify a new NFS mount, pointing to the "tutorial" directory you created before on the wilabfs file server.
  • nfs mount: wilabfs.atlantis.ugent.be:/home/<insert your own directory here, an example is provided on the GUI>/iPlatform/tutorial
  • name: tutorial_mount
  • comment: e.g. "my tutorial mount"
  • leave the box unticked and click the "upload" button
• Your new mount (called "tutorial_mount") should now be in the list on top. Select it (you will see the description of this mount to the right) and click the "add" button to add it to your experiment. Click "next" again.
• On the last tab of the iPlatform section, you can select on which nodes your mount(s) should be loaded.  In this case, we only defined a single mount, so we will simply run the "tutorial_mount" on all available nodes.  Click "submit" to save your platform.
  • [Note1]: once you will have created multiple mounts, and you want to use them a single experiment on a different set of nodes, do not forget to add the mounts to your experiment in the previous step; otherwise the mounts cannot be assigned to nodes. 
  • [Note2]: if you ever select specific individual nodes, be sure to schedule your experiment in the zone(s) where these nodes are mounted. Otherwise, the experiment will not be executed as planned.  The location of the nodes and the zones can be found via the toolbox (Visual_Zones).
• In a final step, we will link the iPlatform to a particular job.
  • Create a new job as described the w-iLab.t basics tutorial via the "job" menu op top of the page (create a new job called "wifi_tutorial_job").
  • On the "files" tab, a sensor firmware image and class file (mainly needed for sensor result processing) _needs_ to be added, even when not using sensor nodes. This is just an implementation issue that will disappear in a next major release of w-iLab.t; just select the "RadioPerf" image (the name is a bit longer but changes when the file is updated), and the "Sniffer" class file (name is also slightly different). Click next, leave the "motes" tab unchanged - this again is related to sensors, which we will not be using.
  • Also leave the "scenario" tab unchanged, click next
  • On the final tab, "platform", the platform you defined before can now be assigned to the job: select the tutorial_wifi platform from the list and Submit (or, if you want, next / submit - we will not be using the "options" tab in this example).
• That's it, your first iNode experiment is now fully defined and can be scheduled via the "schedule" tab.  But what does your experiment do?  Read on in the next section.

Step 2: scheduling the iNode job

• You now defined the tutorial job, which is currently still empty; although you created an iPlatform directory and made sure that this directory will be mounted on all iNodes that are included in your job.
• Since we will be login in over SSH to the nodes in on of the next bullets, be sure to configure your IP on the wilab user info page (section following the "wilabfs/ iNode user name").
• Now schedule the job via the "schedule" tab, run it in the sandbox zone "1A + Sandbox" (take into account the Wi-Fi policy: no Wi-Fi experiments are allowed outside of the sandbox in w-iLab.t Office from 6am to 8pm CET). Wait for the experiment to start.
  • On the fileserver wilabfs (see above), notice how a directory is automatically created inside your ~/iPlatform/tutorial/ directory: a log/job_<jobid> directory will automatically be created.  In this directory, there will be a directory for every node that is part of the experiment (in this case, these will be nodes from the "1A + Sandbox" zone. Note that it is possible that not all nodes you had expected there to be are listed; this is possible in case some nodes are down (e.g. node failure, maintenance, ...)
  • Now that your experiment is running, it should also be possible to SSH to the nodes that are part of your experiment (if you don't know how to do this, check the information on the wilab user info page  - DO configure your IP before scheduling your job.  In case you are connecting via openVPN, this will probably be in the range 192.168.126.0/24 - you can read your IP from the OpenVPN console or enter the 192.168.126.0/24 range in the field on the wilab user info page, although the latter is less secure).  You may have to wait a few minutes before the node is accepting connections. 
  • After you are succesfully connected to an iNode, you will notice that:
    • your iPlatform directory is mounted on your node (~/iPlatform)
    • the specific iPlatform mount of this tutorial (your iPlatform/tutorial directory) is mounted under /tmp/mnt
    • the log directory for the specific job and specific node is mounted under the /tmp/log directory; put otherwise: whatever you write from your node to the /tmp/log directory on your node with nodeID <nodeID>, will be available after your experiment on the wilabfs fileserver under your ~/iPlatform/tutorial/log/job_<jobid>/<nodeID> directory.  If you want to test this, you can e.g. create a simple file on your node, e.g. by executing "touch /tmp/log/test.log" via the ssh connection on your node.
• Technically, this (empty) tutorial job could now already be used to make reservations on the testbed, and then to subsequently run manual experiments.  While this may be useful sometimes, this is of course not the most ideal way of interfacing with the testbed in case you want to repeat your experiments.
• When you want to stop your experiment before your reservation runs out, click "delete" on the schedule page. This will not remove the data on wilabfs that was saved so far.
• Leave at least a 5 minute slot unreserved between two consecutive experiments, to ensure proper dismantling of your old experiment and set-up of your new experiment.

Step 3: automate your experiment

• Now, on the wilabfs file server, go back to your tutorial directory (cd ~iPlatform/tutorial) and create/edit a file called start_mount_code (you could e.g. execute nano start_mount_code).  When you schedule your job linked to this iPlatform next time, this script will be started automatically.  So, whatever commands you could execute manually on the node when loggin in via SSH, can now be scripted in this file. Do not forget to use "sudo" when needed!
  • as a simple example, add following lines to the script (without the "1", "2" etc, these are just line numbers):
  1. #!/bin/bash
  2. date >> /tmp/log/hello
  • Exit and save the file (in nano, use CTRL-X, then Y - Enter)
  • Make the file executable (chmod +x start_mount_code)
• Go back to the web GUI and schedule the tutorial experiment again (delete your previous experiment if necessary, leave in any case 5 minutes between your last job and the new job).
• Verify that the job is scheduled, and that the scripts are executed, by monitoring the log directories of your job under the ~iPlatform/tutorial directory

Step 4: extend your script (and run useful WiFi experiments)

• Now, you basically have all information available to run simple and complex experiments on top of the iNodes.  So far, no actual Wi-Fi traffic was sent or received. For this, you will need to configure the Wi-Fi interfaces of the iNodes.  It is important to understand that the way in which you configure and use your iNodes is part of your experiment and not part of the testbed control.  For example, although you might use the madwifi driver to configure wireless interfaces, you might also create your own way of interfacing with the Wi-Fi cards.  However, some general hints are provided to get good results in your experiments:
  • when needing to call a lot of commands, it might be useful to write multiple (executable) scripts and then refer to these scripts from the start_mount_code file.
  • to debug, try to run your start_mount_code script manually by logging in to the node over SSH (remember: you will find this script in the /tmp/mnt directory and you can also edit it there, the changes are made on the NFS share, not on your local node!
  • Sometimes, when you need some nodes to behave differently from some other nodes, instead of configuring multiple iPlatform mounts and assigning these to the different roles, you might find it easier to include multiple options in one start_mount_code script.  An example is included in following file: example_select.  Comments are included in this file to make it understandable.  (Of course you would need to rename this file to start_mount_code if you would actually want to use it).
  • The Wi-Fi office nodes have only one antenna per interface. This means you have to disable antenna diversity. This can be done by adding this script (rename .txt to .sh if you use it) to your iPlatform and referring to this script from your start_mount_code file. In this example script, an ad-hoc interface is created in 802.11g mode.  See the madwifi website for more info on configuring wireless interfaces.