WiFi Tutorial: Access point with multiple clients

Prerequisites

This tutorial series assumes you have an ​ORBIT account, have ​scheduled a session on the ORBIT test bed, are familiar with ​SSH'ing ​into the test bed itself, and are familiar with the basics of running ORBIT experiments. If you have not done these things yet, you may wish to do so before taking a look at this slightly more advanced experiment. If you are unfamiliar with or are entirely new to ORBIT, you may wish to start ​here.

About This Experiment

This tutorial shows how an experiment script configures multiple nodes to work as an access point (AP) and multiple clients for performance testing with ​iperf. In this experiment script, we'll use an OMF feature to define an application header for iperf and run this application on the AP and access points.

Experiment Script

The experiment script is available below for reference. It is already accessible from the console of the domain you will be working on, so there is no need download it there.

• Experiment Script​

Dissecting the Experiment

Below you will find a step by step explanation of how the experiment script is structured and what each section does.

1. Define experiment properties:

​Lines 4 - 6

We use defProperty to define a few experiment properties along with their default values which allows the script to be executed with arguments passed from the command line.

defProperty('accesspoint', 'node1-1', "node ID for access point")
defProperty('client', 'node1-2', "node ID for client nodes")
defProperty('duration', 60, "Seconds to run the application.")

2. Define application that will run on nodes:

​Lines 8 - 81

We use defApplication to define the application header for iperf. This creates a reference name iperf that can be used later in the script.

defApplication('iperf', 'iperf-oml2') do |app|

The actual path to the iperf application in the node is defined as follows.

app.path = "/usr/bin/iperf-oml2"

The numerous defProperty that follow define references to the various arguments for the application. For example, in the following definition, the reference name interval is mapped to the application argument specified with the -i flag. The default value and the other properties can also be specified.

app.defProperty('interval', 'pause n seconds between periodic bandwidth reports', '-i',
                  :type => :double, :unit => "seconds", :default => '1.')

3. Define properties for group of nodes that will act as WiFi APs:

​Lines 83 - 92

The first group (AP) consists of a single node to be configured as an access point. In practice, these property definitions can be applied to multiple nodes (as we will see in the next section). However, for the purposes of this tutorial we will write this particular set of properties assuming it will apply to a single node.

We first define a group name AP using defGroup which will apply the subsequent properties to the node specified inthe property.accesspoint reference.

defGroup('AP', property.accesspoint) do |node|

Now we define various properties that will be applied to the AP node.

First, node.addApplication connects the previously defined iperf application to this node with the specified arguments and values using setProperty. On the AP node, the iperf application will be configured as a server.

node.addApplication("iperf") do |app|
  app.setProperty('server', true)
end

Next, The wireless card properties are set with the node.net.w0 parameters. Here we set node.net.w0.mode to master to configure the 1st wireless card in the node as an access point. Other relevant parameters are also set here as well, such as channel and SSID.

node.net.w0.mode = "master"
node.net.w0.type = 'g'
node.net.w0.channel = "6"
node.net.w0.essid = "TEST1234"
node.net.w0.ip = "192.168.0.254"

4. Define properties for group of nodes that will act as WiFi clients:

​Lines 94 - 105

The second group (client) consists of a single or multiple node(s) that will be configured as WiFi clients.

Like the AP group, we use defGroup again to define a reference name client for the client node(s) specified in property.client reference.

defGroup('client', property.client) do |node|

Now we configure iperf for the client node(s), but this time iperf will be running as a client connecting to the previously defined iperf server with the appropriate properties set accordingly.

node.addApplication("iperf") do |app|
  app.setProperty('client', "192.168.0.254")
  app.setProperty('time', 20)
  app.setProperty('interval', 5)
end

The wireless card properties are then set with the node.net.w0 parameters. Note that we set node.net.w0.mode to managed to configure the wireless card as a client. Other relevant parameters are also set here as well. Since we can have multiple nodes in a group we specify node.net.w0.ip with the last byte of the IP address as %index%. This way, each node will automatically be assigned a unique address.

node.net.w0.mode = "managed"
node.net.w0.type = 'g'
node.net.w0.channel = "6"
node.net.w0.essid = "TEST1234"
node.net.w0.ip = "192.168.0.%index%"

5. Define event that will occur once all nodes are setup and ready:

​Lines 107 - 116

At the end of the script, once all the nodes are at the same point and all applications have been initialized, an event is triggered to continue and execute the remaining steps.

onEvent(:ALL_UP_AND_INSTALLED) do |event|

The remaining commands execute the actual experiment. The 10 second delay before the call to startApplications allows time for the clients to establish a WiFi connection with the access point before continuing. Then iperf is started on all the nodes (AP and clients). Execution of the experiment script is once delayed again, this time for a period defined by property.duration, giving time to collect experiment data. Finally all applications are stopped and the experiment exits out.

info "Wifi Multi Client Iperf Experiment"
wait 10
allGroups.startApplications
info "All my Applications are started now..."
wait property.duration
allGroups.stopApplications
info "All my Applications are stopped now."
Experiment.done

Executing the Experiment Script

An overview on running experiment scripts on the ORBIT testbed can be found on the Getting Started Page.

In order to run this experiment script, connect to the console of the domain for which you have an active and approved reservation for and load the baseline.ndz image onto nodes with WiFi cards. Check the Status Page in the ​Control Panel to find nodes with a WiFi card.

user@console:~$ omf load -i baseline.ndz -t node1-1,node1-2,node1-3

After the nodes have finished imaging, turn the nodes on. The topology used here is system:topo:imaged which selects the prior set of nodes that were successfully imaged.

user@console:~$ omf tell -a on -t system:topo:imaged

To run this experiment with 2 clients nodes (assuming the domain has more than 2 compatible nodes):

user@console:~$ omf exec test:exp:tutorial:wifi-ap-iperf.rb -- --accesspoint node1-1 --client node1-2,node1-3 --duration 60

The output of this script should be similar to the following:

 INFO NodeHandler: OMF Experiment Controller 5.4 (git 3fb37b9)
 INFO NodeHandler: Reading configuration file /etc/omf-expctl-5.4/services.yaml
 INFO NodeHandler: Add domain http - http://internal1.orbit-lab.org:5054/
 INFO NodeHandler: Add domain http - http://repository1.orbit-lab.org:5054/
 INFO NodeHandler: Slice ID: default_slice (default)
 INFO NodeHandler: Experiment ID: default_slice-2014-10-09t10.15.22.101-04.00
 INFO NodeHandler: Message authentication is disabled
 INFO Experiment: load system:exp:stdlib
 INFO property.resetDelay: resetDelay = 230 (Fixnum)
 INFO property.resetTries: resetTries = 1 (Fixnum)
 INFO Experiment: load system:exp:eventlib
 INFO Experiment: load system:exp:winlib
 INFO Experiment: load wifi-ap-iperf.rb
 INFO property.accesspoint: accesspoint = "node15-1" (String)
 INFO property.client: client = "node16-1,node17-1" (String)
 INFO property.duration: duration = 60 (Fixnum)
 INFO ALL_UP_AND_INSTALLED: Event triggered. Starting the associated tasks.
 INFO exp: Wifi Multi Client Iperf Experiment
 INFO exp: Request from Experiment Script: Wait for 10s....
 INFO node17-1.grid.orbit-lab.org: Device 'net/w0' reported Not-Associated
 INFO node16-1.grid.orbit-lab.org: Device 'net/w0' reported 00:60:B3:AC:2B:D5
 INFO exp: All my Applications are started now...
 INFO exp: Request from Experiment Script: Wait for 60s....
 INFO node17-1.grid.orbit-lab.org: Device 'net/w0' reported 00:60:B3:AC:2B:D5
 INFO exp: All my Applications are stopped now.
 INFO EXPERIMENT_DONE: Event triggered. Starting the associated tasks.
 INFO NodeHandler:
 INFO NodeHandler: Shutting down experiment, please wait...
 INFO NodeHandler:
 INFO run: Experiment default_slice-2014-10-09t10.15.22.101-04.00 finished after 1:20

Retrieving Results

The experiment script generates a lot of data that contains not only results, but also information useful for debugging. This detailed output of the experiment along with iperf's output are aggregated on the console in a log file: /tmp/Experiment ID.log

For this example, the file would be: /tmp/default_slice-2014-10-09t10.15.22.101-04.00.log

Partial contents of this file (specifically iperf results) are shown below:

2014-10-09 10:15:38 INFO nodeHandler::exp: All my Applications are started now...
2014-10-09 10:15:38 INFO nodeHandler::exp: Request from Experiment Script: Wait for 60s....
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STARTED from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: ''
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STARTED from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: ''
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STARTED from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: ''
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: '------------------------------------------------------------'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '------------------------------------------------------------'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: 'Server listening on TCP port 5001'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: 'TCP window size: 85.3 KiByte (default)'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: 'Client connecting to 192.168.0.254, TCP port 5001'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: 'TCP window size: 21.0 KiByte (default)'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: '------------------------------------------------------------'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: '[  7] local 192.168.0.254 port 5001 connected with 192.168.0.2 port 45466'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '------------------------------------------------------------'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '[  6] local 192.168.0.2 port 45466 connected with 192.168.0.254 port 5001'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '------------------------------------------------------------'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: '[  8] local 192.168.0.254 port 5001 connected with 192.168.0.3 port 47013'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: 'Client connecting to 192.168.0.254, TCP port 5001'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: 'TCP window size: 21.0 KiByte (default)'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '------------------------------------------------------------'
2014-10-09 10:15:39 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '[  6] local 192.168.0.3 port 47013 connected with 192.168.0.254 port 5001'
2014-10-09 10:15:40 DEBUG nodeHandler::AgentCommands: DEV_EVENT CELL_ID from: 'net/w0' (node17-1.grid.orbit-lab.org) - msg: '00:60:B3:AC:2B:D5'
2014-10-09 10:15:40 INFO nodeHandler::node::node17-1.grid.orbit-lab.org: Device 'net/w0' reported 00:60:B3:AC:2B:D5
2014-10-09 10:15:44 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '[ ID] Interval       Transfer     Bandwidth'
2014-10-09 10:15:44 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '[  6]  0.0- 5.0 sec  2.88 MiBytes  4.82 Mbits/sec'
2014-10-09 10:15:44 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '[ ID] Interval       Transfer     Bandwidth'
2014-10-09 10:15:44 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '[  6]  0.0- 5.0 sec  4.62 MiBytes  7.76 Mbits/sec'
2014-10-09 10:15:49 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '[  6]  5.0-10.0 sec  2.00 MiBytes  3.36 Mbits/sec'
2014-10-09 10:15:49 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '[  6]  5.0-10.0 sec  4.38 MiBytes  7.34 Mbits/sec'
2014-10-09 10:15:54 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '[  6] 10.0-15.0 sec  2.62 MiBytes  4.40 Mbits/sec'
2014-10-09 10:15:54 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '[  6] 10.0-15.0 sec  2.75 MiBytes  4.61 Mbits/sec'
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '[  6] 15.0-20.0 sec  3.00 MiBytes  5.03 Mbits/sec'
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: '[  6]  0.0-20.1 sec  10.6 MiBytes  4.43 Mbits/sec'
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT DONE.OK from: 'iperf#2' (node16-1.grid.orbit-lab.org) - msg: 'status: 0'
2014-10-09 10:15:59 DEBUG nodeHandler::NodeApp: Application 'iperf#2' on 'node16-1.grid.orbit-lab.org' finished successfully (end of application)
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: '[ ID] Interval       Transfer     Bandwidth'
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: '[  7]  0.0-20.3 sec  10.6 MiBytes  4.40 Mbits/sec'
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '[  6] 15.0-20.0 sec  3.75 MiBytes  6.29 Mbits/sec'
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: '[  6]  0.0-20.1 sec  15.6 MiBytes  6.51 Mbits/sec'
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDOUT from: 'iperf#1' (node15-1.grid.orbit-lab.org) - msg: '[  8]  0.0-20.2 sec  15.6 MiBytes  6.49 Mbits/sec'
2014-10-09 10:15:59 DEBUG nodeHandler::AgentCommands: APP_EVENT DONE.OK from: 'iperf#2' (node17-1.grid.orbit-lab.org) - msg: 'status: 0'
2014-10-09 10:15:59 DEBUG nodeHandler::NodeApp: Application 'iperf#2' on 'node17-1.grid.orbit-lab.org' finished successfully (end of application)
2014-10-09 10:16:38 DEBUG nodeHandler::nodeSetPath: Stop all applications

Troubleshooting

• When you login to the domain's console at the start of your approved time slot, do not assume the nodes you will be using have a working image on them. Load the appropriate image onto the nodes you will be using before attempting your experiment.

• Make sure the nodes that you are trying to run the experiment on are actually powered on. You can use the omf stat command or view the Status page in the Control Panel to check this. Please note that the Status page is only periodically refreshed and may not show immediate changes in node power state.

• Make sure the nodes (and domain) you are using for this experiment have compatible WiFi cards. Refer to the Status page in the Control Panel to find nodes that have compatible !Wifi cards (either ath9k or ath5k).

• If you are attempting this tutorial with more than 1 client node, please make a reservation on Grid or SB4. All other compatible domains only have 2 nodes, which will only allow for 1 AP and 1 client node.

• It is not recommended to attempt this tutorial on SB4 unless you have completed the tutorial on configuring the attenuator matrix. The experiment will fail or produce errors if the attenuators are set beyond certain values.

• If you are trying this tutorial on SB9, you are going to have a bad time because that sandbox does not have ANY wireless devices.

Final Observations

You have now, hopefully, succeeded in executing the experiment script in this tutorial. Try to run this experiment again but with more client nodes. Additionally, if you are trying this tutorial on the ORBIT grid, try using nodes in different locations to see those effects on performance.