Setting up an Experiment

Users will be able to setup an experiment using jFed. After the user sends the login information, the AM will authenticate the user, tell him/her which resources will be available to them through RSpecs, and interact with the CBTM on behalf of the user in order to instantiate the available resources.The AM uses the GENI v3 API which is written as a wrapper of the reference AM.

Experiments with Virtual Machine

Experiments with USRP

The USRP (Universal Software Radio Peripheral) is a software-defined radio, which is able to run arbitrary code using an FPGA as well as on the CPU of the server. It can be used to run any wireless standard (including existing standards or even a protocol that has been created by the experimenter), as long as the operating frequency and other parameters of the communication are within the accepted range of the USRP card. This section describes how to book an USRP and how to run a very simple experiment that checks for the spectrum usage on a certain frequency.

    RSpec Description

    The USRP nodes are allocated as virtual machines containing USRP boards attached via USB. Each MiniPC on the testbed can support one USRP node at a time. The RSPEC for allocating an USRP node must contain the following tags: 

    1. <node client_id="node1" exclusive="false"
    2. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    3. 	<sliver_type name="usrp-vm">
    4. 		<disk_image name="urn:publicid:IDN+futebol.dcc.ufmg.br+image+IMG_TYPE"/>
    5. 	</sliver_type>
    6. </node>

    The bold part inside of the “node” tag indicates that this node is being allocated in the UFMG FUTEBOL testbed. It is automatically filled with this information when the UFMG testbed is selected on the dropdown menu on jFed. The name component on the “sliver_type” tag indicates that this node is composed of a virtual machine containing an USRP board attached to it via USB. Inside the “sliver_type” tag is the “disk_image” tag. This tag selects the type of virtual machine that will be allocated. The “name” component inside this tag indicates which type of virtual machine is being allocated, and also reinforces that this machine is being allocated inside of the UFMG Testbed. The string on the “name” component must follow the structure pre sented above. The IMG_TYPE can be one of the following:


    • gnuradio: Selects a machine with the basic gnuradio software installed
    • openlte: Selects a machine with the basic gnuradio software and the OpenLTE software installed
    The “disk_image” tag is optional. When the “sliver_type” selected is “usrp-vm”, the default image selected for the machine is “gnuradio”.

    Example Experiment

    In this experiment we are going to run a spectrum analyser, which will use the USRP to show how is the usage of the medium on a certain frequency. To that end, we will instantiate a USRP resource on the UFMG FUTEBOL testbed. The following RSPEC can be used to instantiate a single VM with a USRP: 

    1. <?xml version='1.0'?>
    2. <rspec xmlns="http://www.geni.net/resources/rspec/3" type="request"
    3. generated_by="jFed RSpec Editor" generated="2017-06-09T13:54:59.535-03:00"
    4. xmlns:emulab="http://www.protogeni.net/resources/rspec/ext/emulab/1"
    5. xmlns:jfedBonfire="http://jfed.iminds.be/rspec/ext/jfed-bonfire/1"
    6. xmlns:delay="http://www.protogeni.net/resources/rspec/ext/delay/1"
    7. xmlns:jfed-command="http://jfed.iminds.be/rspec/ext/jfed-command/1"
    8. xmlns:client="http://www.protogeni.net/resources/rspec/ext/client/1"
    9. xmlns:jfed-ssh-keys="http://jfed.iminds.be/rspec/ext/jfed-ssh-keys/1"
    10. xmlns:jfed="http://jfed.iminds.be/rspec/ext/jfed/1"
    11. xmlns:sharedvlan="http://www.protogeni.net/resources/rspec/ext/shared-vlan/1"
    12. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    13. xsi:schemaLocation="http://www.geni.net/resources/rspec/3 
    14. http://www.geni.net/resources/rspec/3/request.xsd">
    15. 	<node client_id="node0" exclusive="false"
    16. 	component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    17. 		<sliver_type name="usrp-vm">
    18. 			<disk_image 
    19. 			name="urn:publicid:IDN+futebol.dcc.ufmg.br+image+gnuradio"/>
    20. 		</sliver_type>
    21. 		<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="396.0"
    22. 		y="77.5"\>
    23. 	</node>
    24. 	<node> client_id="node1" exclusive="false"
    25. 	component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    26. 		<sliver_type name="usrp-vm">
    27. 			<disk_image 
    28. 			name="urn:publicid:IDN+futebol.dcc.ufmg.br+image+gnuradio"/>
    29. 		</sliver_type>
    30. 		<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="52.5"
    31. 		y="76.5"/>
    32. 	</node>
    33. </rspec>

    Download our example

    After the VM is instantiated, you can execute commands to perform experiments in the USRP. The first basic command is to check if the equipment is detected. To do this, run the command uhd_find_devices. This command output will indicate the model, serial number and name of the USRP that is connected to the virtual resource that you allocated.

    On the ‘rx_node’, run the following code. This code will run a frequency analyzer at 2.55GHz, sampling the medium at a rate of 2MHz. This frequency analyzer runs on the command line (because it may be too slow to open a graphic user interface from the testbed). 

    1. cd /usr/lib/uhd/examples
    2. ./rx_ascii_art_dft --freq 2550000000 --rate 2000000 --ref-lvl -50

    You should be able to see the ascii representation of the transmitted waveform spectrum, as illustrated below:

Experiments with Raspberry Pi

The Raspberries PI are single board computers, used in this testbed to simulate Access Points, Wireless Stations or plain computers. This sectiondescribes how to allocate a Raspberry PI and how to run simple experiments to check the operability of the devices.

    Raspberry Pi RSpec Description

    The Raspberry Pi nodes can be allocated as Access Points, Wireless Stations or Without Both Configurations. Note that the raspberry Pi is selected by using the sliver type raw raspberry. The example below presents an RSPEC for a Raspberry Pi mote operating as an Access Point: 
    1. <node client_id="node1" exclusive="true"
    2. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    3. 	<sliver_type name="raw-raspberry" mode="ap">
    4. 		<wifi-settings ssid="eee" psk="iii" auth="jjj" channel="www"
    5. 		tx_power="xxx" sens="yyy" rts="zzz"/>
    6. 	</sliver_type>
    7. </node>

    The example below shows an RSPEC for allocating a Raspberry Pi as a Wireless Station (note that the mode of the WiFi card is defined by the mode parameter of the sliver, being either ap or sta): 

    1. <node client_id="node1" exclusive="true"
    2. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    3. 	<sliver_type name="raw-raspberry" mode="sta">
    4. 		<wifi-settings ssid="eee" psk="iii" auth="jjj" tx_power="xxx"
    5. 		sens="yyy"/>
    6. 	</sliver_type>
    7. </node>

    The wifi-settings tag holds the configuration items for the Wireless interface. The options in this tag are:
    • ssid: Defines the SSID for the network
    • psk: Defines the password for the network
    • auth: Defines the authentication type for the network, should be one o f the following:
      • WEP/WEP2
      • WPA-PSK/WPA2-PSK
    • channel: Defines in which channel the network is going to be distributed
    • tx_power: Defines the transmission power for the antenna (in dBm)
      • “auto” for automatically chosen transmission power
      • A numeric (integer) value
    • sens: set the sensitivity threshold
      • “auto” for automatically chosen sensitivity threshold
      • A numeric (integer) value
    • rts: adds a RTS/CTS handshake before each packet transmission to make sure that the channel is clear.The Arduino is programmed through raspberry pi terminal or IDE where the experimenter can upload the arduino software to manage the sensors. The sensor are plugged on pins X, Y and Z for luminosity, humidity and temperature, respectively. A default arduino software is provided with sensor data update period of W ms.
      • “off” for no RTS
      • A numeric (integer) value
    The example below shows an RSPEC for allocating the Raspberry Pi without configuring its WiFi interface: 
    1. <node client_id="node1" exclusive="true"
    2. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    3. 	<sliver_type name="raw-raspberry">
    4. 	</sliver_type>
    5. </node>

    Examples of a Raspberry Pi Experiments

      Plain Raspberry Pi

      The example below show a complete RSpec to allocate a plain Raspberry Pi. 
      1. <?xml version='1.0'?>
      2. <rspec xmlns="http://www.geni.net/resources/rspec/3" type="request"
      3. generated_by="jFed RSpec Editor" generated="2017-11-10T09:40:59.688-02:00"
      4. xmlns:emulab="http://www.protogeni.net/resources/rspec/ext/emulab/1"
      5. xmlns:delay="http://www.protogeni.net/resources/rspec/ext/delay/1"
      6. xmlns:jfed-command="http://jfed.iminds.be/rspec/ext/jfed-command/1"
      7. xmlns:client="http://www.protogeni.net/resources/rspec/ext/client/1"
      8. xmlns:jfed-ssh-keys="http://jfed.iminds.be/rspec/ext/jfed-ssh-keys/1"
      9. xmlns:jfed="http://jfed.iminds.be/rspec/ext/jfed/1"
      10. xmlns:sharedvlan="http://www.protogeni.net/resources/rspec/ext/shared-vlan/1"
      11. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      12. xsi:schemaLocation="http://www.geni.net/resources/rspec/3 
      13. http://www.geni.net/resources/rspec/3/request.xsd">
      14. 	<node client_id="node0" exclusive="true" 
      15. 	component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
      16. 		<sliver_type name="raw-raspberry">
      17. 		</sliver_type>
      18. 		<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="282.0"
      19. 		y="109.5"/>
      20. 	</node>
      21. </rspec>

      After the allocation of the Raspberry Pi node is done, the device can be tested using the simple code below: 
      1. #include <stdio.h>
      2. #include <stdlib.h>
      4. int main(){
      5. 	printf ("Hello World!\n");
      6. 	return 0;
      7. }

      The example code can be downloaded, compiled and executed as follows: 
      1. wget futebol.dcc.ufmg.br/documentation/examples/helloword_raspberrypi.c
      2. gcc -c helloword_raspberrypi.c
      3. gcc helloworld -o helloword_raspberrypi.o
      4. ./helloworld

      TERMINAL OUTPUT 
      1. Hello World!

    For more examples of experiments with raspberry pi, see our User Guide.

Experiments with WI-FI

It is possible to use the MiniPCs to perform experiments using WiFi. The Mini PCs use a Dell Dual band Wireless AC 8620 chipset, which has 2x2 MIMO and supports IEEE 802.11 a, b, g, n and ac standards. The Raspberry Pis can also be used for WiFi experiments (please check the appropriate section), however the Mini PCs have a much wider configuration range.


Besides using the command line tools to configure the WiFi, it is also possible to use a SDN interface called Ethanol to control them. Ethanol is able to control a number of parameters of the wireless interface from a SDN controller. Those can be used in SDN based experiments, or as a tool to control the WiFi links in your experiment. For example, you can force a node disconnect using Ethanol, to emulate a node failure. The full documentation of the Ethanol API can be found in github: https://github.com/h3dema/ethanol_controller/tree/master/ethanol/documentation

    RSpec Description

    The WiFi nodes can be allocated as a machine with wireless network card.Note that the WiFi node is selected by using the sliver type raw-wifi. The example below presents an RSPEC for WiFi node, using Ubuntu 16.04: 

    1. <node client_id="node0" exclusive="true"
    2. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    3. 	<sliver_type name="raw-wifi">
    4. 		<disk_image name=
    5. 		"urn:publicid:IDN+futebol.dcc.ufmg.br+image+ubuntu16"/>
    6. 	</sliver_type>
    7. 	<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="176.0"
    8. 	y="117.0"/>
    9. </node>

    The example below shows an RSPEC for allocating the WiFi node using Ethanol: 
    1. <node client_id="node0" exclusive="true"
    2. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    3. 	<sliver_type name="raw-wifi">
    4. 		<disk_image name=
    5. 		"urn:publicid:IDN+futebol.dcc.ufmg.br+image+ethanol"/>
    6. 	</sliver_type>
    7. 	<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="50.0"
    8. 	y="544.7097400940887"/>
    9. </node>

    Example Experiments - WiFi node without Ethanol

    Below shows an RSPEC for allocating the WiFi node for this experiment: 
    1. <?xml version='1.0'?>
    2. <rspec xmlns="http://www.geni.net/resources/rspec/3" type="request"
    3. generated_by="jFed RSpec Editor" generated="2017-09-18T15:37:48.662-03:00"
    4. xmlns:emulab="http://www.protogeni.net/resources/rspec/ext/emulab/1"
    5. xmlns:delay="http://www.protogeni.net/resources/rspec/ext/delay/1"
    6. xmlns:jfed-command="http://jfed.iminds.be/rspec/ext/jfed-command/1"
    7. xmlns:client="http://www.protogeni.net/resources/rspec/ext/client/1"
    8. xmlns:jfed-ssh-keys="http://jfed.iminds.be/rspec/ext/jfed-ssh-keys/1"
    9. xmlns:jfed="http://jfed.iminds.be/rspec/ext/jfed/1"
    10. xmlns:sharedvlan="http://www.protogeni.net/resources/rspec/ext/shared-vlan/1"
    11. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    12. xsi:schemaLocation="http://www.geni.net/resources/rspec/3 
    13. http://www.geni.net/resources/rspec/3/request.xsd">
    14. 	<node client_id="node0" exclusive="true"
    15. 	component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    16. 		<sliver_type name="raw-wifi">
    17. 			<disk_image name=
    18. 			"urn:publicid:IDN+futebol.dcc.ufmg.br+image+ubuntu16"/>
    19. 		</sliver_type>
    20. 		<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="176.0"
    21. 		y="117.0"\>
    22. 	</node>
    23. 	<node client_id="node1" exclusive="true"
    24. 	component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    25. 		<sliver_type name="raw-wifi">
    26. 			<disk_image name=
    27. 			"urn:publicid:IDN+futebol.dcc.ufmg.br+image+ubuntu16"/>
    28. 		</sliver_type>
    29. 		<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="539.0"
    30. 		y="106.0"/>
    31. 	</node>
    32. 	<node client_id="node2" exclusive="true"
    33. 	component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
    34. 		<sliver_type name="raw-wifi">
    35. 			<disk_image name=
    36. 			"urn:publicid:IDN+futebol.dcc.ufmg.br+image+ubuntu16"/>
    37. 		</sliver_type>
    38. 		<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="358.0"
    39. 		y="257.0"/>
    40. 	</node>
    41. </rspec>

    Download our example

    After allocating the machines with wifi, follow the steps below:

    1. Define the IP addresses so that the hosts are on the same network.

    1. root@<node 0>Ifconfig wlp2s0 192.168.0.1 netmask 255.255.255.0 up
    2. root@<node 1>Ifconfig wlp2s0 192.168.0.10 netmask 255.255.255.0 up
    3. root@<node 2>Ifconfig wlp2s0 192.168.0.100 netmask 255.255.255.0 up

    2. Using hostAPd it is possible to create an access point using a configuration file, for example named hostapd.conf, such as the one below:

    1. interface=wlp2s0
    2. hw_mode=a
    3. channel=149
    4. ieee80211d=1
    5. country_code=BR
    6. ieee80211n=1
    7. ieee80211ac=1
    8. wmm_enabled=1
    9. ssid=test

    3. Then run hostapd on the AP machine with this file.

    1. hostapd hostapd.conf

    4. Next, establish a connection between the hosts and the access point.

    1. iwconfig wlp2s0 essid test mode managed

    5. You can test the performance with the Iperf tool, which comes pre-installed in the image. In the server, run: 
    1. iperf -s

    In the client, please run:

    1. iperf -c 192.168.0.100 (server_IP) -d

    For more examples of experiments with WiFi, see our User Guide.

Experiments with Advanticsys Sensor Nodes

The Advanticsys MTM-CM5000-MSP is a wireless sensor node with limited processing and network resources. It is recommended for experiments on wireless sensor networks or related to Internet of Things with very resource constrained devices. The nodes transmit wirelessly using the standard IEEE 802.15.4. In order to program the nodes, the programmer must create a binary integrating his/her own code with one operating system, which is either TinyOS or Contiki. The Advanticsys is a node that is compatible to any software developed for the TelosB platform. It has temperature, relative humidity and light sensors. They are connected via an USB interface. More information at https://www.advanticsys.com/shop/mtmcm5000msp-p-14.html.
At the moment, the FUTEBOL UFMG testbed supports programming the Advanticsys using the TinyOS operating system. In the future we lan to support Contiki as well.


RSpec Description

Sensor nodes must be allocated together with a virtual machine that contains the system responsible for managing the sensor nodes. To do this, the sliver_type attribute is set to telosb-vm and disk_image as telosb. For each instance of the sensor nodes, just configure the sliver_type as raw-telosb. Note that it is not necessary to use the disk_image attribute for the sensor nodes.
You can specify which node to allocate according to the ID shown in Figure 2 by configuring the component_id attribute of each node tag with the specific number of the sensor node.
The example below shows an RSPEC with one virtual machine (named node 0) and two sensor nodes (60 and 66, named node 1 and node 2). 

  1. <node client_id="node0" exclusive="true"
  2. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am">
  3. 	<sliver_type name="telosb-vm">
  4. 		<disk_image name=
  5. 		"urn:publicid:IDN+futebol.dcc.ufmg.br+image+telosb"/>
  6. 	</sliver_type>
  7. 	<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="176.0"
  8. 	y="117.0"/>
  9. </node>
  11. <node client_id="node1" exclusive="true"
  12. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am"
  13. component_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am+node+60">
  14. 	<sliver_type name="raw-telosb"/>
  15. 	<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="176.0"
  16. 	y="117.0"/>
  17. </node>
  19. <node client_id="node2" exclusive="true"
  20. component_manager_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am"
  21. component_id="urn:publicid:IDN+futebol.dcc.ufmg.br+authority+am+node+66">
  22. 	<sliver_type name="raw-telosb"/>
  23. 	<location xmlns="http://jfed.iminds.be/rspec/ext/jfed/1" x="176.0"
  24. 	y="117.0"/>
  25. </node>
Download our example

    Example Experiment

    In this experiment we will demonstrate the operation of the applications Oscilloscope and BaseStation which are both examples of the TinyOS Operating System. The first is a simple demo of data collection responsible for periodically the voltage sensor and transmitting on the radio a message with 10 consecutive readings. The second application receives messages from the radio and forwards them to the PC through the USB port. Below we demonstrate the experience, being allocated node 60 for oscilloscope,node 66 for BaseStation and a virtual machine.

    1 - Program submission.

    After the nodes are allocated, you must first send your to the allocated virtual machine, compile it through the TinyOS operating system, and compress the resulting files with a .zip extension. We then send the Oscilloscope and BaseStation folders through the Transfer Files option in Jfed.

    Now, access the virtual machine allocated through the terminal (node 0 in Jfed), navigate to the folder of your application and execute the command make telosb to generate the executable that will be installed in advanticsys nodes.

    The build folder will be automatically created, containing the executable and other necessary files. Navigate to it and run the command below to compress the files.

    As an alternative, you can compile 2 and compress the data on your own computer and transfer the .zip file through the Jfed Transfer File function for this, see how to install the TinyOS Operating System on your computer.

    2 -Installation of applications on sensor nodes.

    To perform the installation of the applications on the sensor nodes, simply run the command below on the terminal of the virtual machine (node 0 in the example allocation). 

    1. submit - node 60 -file osciloscope.zip
    2. submit - node 66 -file basestatio.zip

    Note that the -node and -file parameters specify which node to install the application and the file name, respectively.

    On your terminal you will receive a success message or some error message. In the event of an error, repeat the installation procedure. On success, the sensor nodes will be working according to their application and the collected data will be saved in text files during the useful period of the experiment.

    3 - Download your experiment data.

    At any time during your experiment time you can request the data collected through the receiving node, by means of the command below, which should be executed in the terminal of the virtual machine. 

    1. recv -node 66

    Notice that the recv command calls the procedure for receiving the files, and the -node parameter specifies which node you want to receive the data from. The procedure is responsible for sending to the allocated virtual machine a compressed file that contains the data of the experiment. You can view this file in the VM's personal folder or download it through Jfed.

    4 - Output file - Experiment data Your application should be able to write the data collected on the sensor's USB port. Below are the fields that are in the output file for our example experiment. 
    1. destination:[] source:[] length:[] group:[] type:[] data:[]

    To know more about the fields on this experiment,please visit the official page of tinyos. For our example, see the output file.