[[TOC(Tutorials/a0Basic*)]]

== WiSHFUL Tutorial: Basic Controller-Agent Interaction ==

=== Prerequisites === 

This tutorial series assumes you have an [http://www.orbit-lab.org/userManagement/register ORBIT account], have [https://www.orbit-lab.org/schedule/ scheduled a session] on the ORBIT testbed, are familiar with [http://en.wikipedia.org/wiki/Secure_Shell SSH]'ing [http://www.orbit-lab.org/wiki/Tutorial/HelloWorld#a4.RunningtheHelloWorldexperiment into the testbed 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 [http://www.orbit-lab.org/ here].

=== About This Experiment ===

This tutorial illustrates basic usage of [http://www.wishful-project.eu/ WiSHFUL experimentation platform]. The actual experiment script assumes usage of reference [wiki:Documentation/cImages/wishful WiSHFUL image ('''wishful.ndz''')] and is explicitly designed for use in [wiki:Hardware/bDomains/cSandboxes/dSB4 SB4] (if you want to run this tutorial on a different domain or with a different set of nodes, you have to modify controller configuration file in the image).

=== Experiment Script ===

The basic OMF experiment script for running the WiSHFUL Simple example is in the [attachment:wishful_simple.rb wishful_simple.rb attachment]

Relevant sections of the script code are:

'''1. Define the set of nodes and path for the WiSHFUL scripts directory:'''

The node set and the script path match the configuration on the default WiSHFUL image.
{{{
defProperty('contr', 'node2-1', 'WiSHFUL Controller Node')
defProperty('agent', 'node1-1', 'WiSHUL Agent Node')
defProperty('path','/root/wishful/examples/simple/',"Path to WiSHFUL configuration directory")
defProperty('duration', 60, "Seconds to run the application")
}}}

'''2. Define WiSSHFUL Controller and Agent applications that will run on the nodes:'''

Use ''defApplication'' to create two reference application names: ''controller'' and ''agent'' that are used later in the script to actually execute corresponding WiSHFUL components (in this case the path is based on WiSHFUL image installation location in ''/root/wishful'' and the execution of an example scripts and configurations that are in the ''examples/simple'' sub-directory). Each application receives configuration file name as the (only) command line option. 
{{{
defApplication('controller') do |app|
  app.description = 'WiSHFUL Simple Controller Program'
  app.path = property.path+'wishful_simple_controller'
  app.defProperty('config', 'Configuration file', '--config', {:type => :string})
end

defApplication('agent') do |app|
  app.description = 'WiSHFUL Simple Agent Program'
  app.path = property.path+'wishful_simple_agent'
  app.defProperty('config', 'Configuration file', '--config', {:type => :string})
end
}}}

 Define twor groups of nodes (in this case having a single node in each) and adding corresponding controller and agent applications and their configuration file name.
{{{
defGroup( 'Controllers', property.contr ) do |node|
  node.addApplication( "controller" ) do |app|
    app.setProperty('config', property.path+'controller_config.yaml')
  end
end

defGroup( 'Agents', property.agent ) do |node|
  node.addApplication( "agent" ) do |app|
    app.setProperty('config', property.path+'agent_config.yaml')
  end
end
}}}

The actual experiment has the 10 second delay before the call to ''startApplications'' (to "warm up" nodes) that is followed by 60 seconds of run-time during which WiSHFUL controller manages corresponding agent. Finally all applications are stopped and the experiment exits. 

=== Executing the Experiment Script ===
An overview on running experiment scripts on the ORBIT testbed can be found on the [wiki:Documentation/CGettingStarted Getting Started Page]. 

In order to run this experiment script, connect to the console of the SB4 for which you have an active and approved reservation for and load the ''wishfull.ndz'' image onto experiment nodes.
{{{
user@console:~$ omf load -i wishful.ndz -t node1-1,node2-1
}}}

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
}}}
Wait about 1 minute before proceeding to allow the nodes time to boot up.

Grab the experiment script with:
{{{
  wget ''
}}}

Run the experiment:
{{{
user@console:~$ omf exec wishful_simple.rb --duration 60
}}}

The output of this script should be similar to the following:
{{{
user@console.sb4:~# omf exec wishful_simple.rb
 
 INFO NodeHandler: OMF Experiment Controller 5.4 (git 861d645)
 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: Add domain http - http://internal2dmz.orbit-lab.org:5054/
 INFO NodeHandler: Add domain http - http://external1.orbit-lab.org:5054/
 INFO NodeHandler: Slice ID: default_slice (default)
 INFO NodeHandler: Experiment ID: default_slice-2016-06-10t07.29.39.183-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 wishful_simple.rb
 INFO property.contr: contr = "node2-1" (String)
 INFO property.agent: agent = "node1-1" (String)
 INFO property.path: path = "/root/wishful/examples/simple/" (String)
 INFO property.duration: duration = 60 (Fixnum)
 INFO exp: Controller will be on node2-1.
 INFO exp: Agent will be on node1-1.
 INFO ALL_UP_AND_INSTALLED: Event triggered. Starting the associated tasks.
 INFO exp: Wait for all nodes to come up
 INFO exp: Request from Experiment Script: Wait for 10s....
 INFO BRING_UP: Event triggered. Starting the associated tasks.
 INFO Experiment: Bringing up resources
 INFO exp: Both controller and agent started...
 INFO exp: Request from Experiment Script: Wait for 60s....
 INFO exp: Both controller and agent stopped...
 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-2016-06-10t07.29.39.183-04.00 finished after 1:20
}}}

=== Retrieving Results ===

This particular experiment does not generate any data but rather illustrates how to run WiSHFUL based experiment. The primary observable output from both experiment script execution as well as output of the controller/agent interaction are aggregated on the console in a log file: /tmp/''<Experiment ID>''.log
As can be observed in the execution output above (''Experiment ID: default_slice-2016-06-10t07.29.39.183-04.00''), this log file is in '''/tmp/default_slice-2016-06-10t07.29.39.183-04.00.log'''. As can be seen in the partial dump of this file, the controller is instruction agent to execute various commands on the target node:
{{{
2016-06-10 07:29:54 DEBUG nodeHandler::set::Controllers: Start all applications
2016-06-10 07:29:54 DEBUG nodeHandler::AppContext: Starting application 'controller#1'
2016-06-10 07:29:54 DEBUG nodeHandler::set::Controllers: Send ('Controllers') - '<EXECUTE><TARGET>Controllers</TARGET><APPID>controller#1</APPID><PATH>/root/wishful/examples/simple/wishful_
simple_controller</PATH><ENV></ENV><CMDLINEARGS>--config /root/wishful/examples/simple/controller_config.yaml</CMDLINEARGS></EXECUTE>'
2016-06-10 07:29:54 DEBUG nodeHandler::set::Agents: Start all applications
2016-06-10 07:29:54 DEBUG nodeHandler::AppContext: Starting application 'agent#1'
2016-06-10 07:29:54 DEBUG nodeHandler::set::Agents: Send ('Agents') - '<EXECUTE><TARGET>Agents</TARGET><APPID>agent#1</APPID><PATH>/root/wishful/examples/simple/wishful_simple_agent</PATH><
ENV></ENV><CMDLINEARGS>--config /root/wishful/examples/simple/agent_config.yaml</CMDLINEARGS></EXECUTE>'
2016-06-10 07:29:54 DEBUG nodeHandler::AgentCommands: APP_EVENT STARTED from: 'controller#1' (node2-1.sb4.orbit-lab.org) - msg: ''
2016-06-10 07:29:54 INFO nodeHandler::exp: Both controller and agent started...
2016-06-10 07:29:54 INFO nodeHandler::exp: Request from Experiment Script: Wait for 60s....
2016-06-10 07:29:54 DEBUG nodeHandler::AgentCommands: APP_EVENT STARTED from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: ''
2016-06-10 07:29:55 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:29:55,152 - SimpleModule2.myFunc_1() - INFO - This f
unction is executed on agent start'
2016-06-10 07:29:57 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:29:57,030 - pyre_discovery_module.main.discovery_tas
k() - INFO - Discovered Controller DL-tcp://10.14.2.1:8990, UL-tcp://10.14.2.1:8989'
2016-06-10 07:29:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:29:59,038 - pyre_discovery_module.main.discovery_tas
k() - INFO - Discovered Controller DL-tcp://10.14.2.1:8990, UL-tcp://10.14.2.1:8989'
2016-06-10 07:29:59 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:29:59,186 - SimpleModule2.myFunc_3() - INFO - This f
unction is executed on connection to global controller'
2016-06-10 07:30:05 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:05,027 - SimpleModule2.myFunc_5() - INFO - This f
unction is executed before first UPI call to module'
2016-06-10 07:30:05 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:05,032 - SimpleModule2.send_to_module() - WARNING
 - Exception: function radio.clean_per_flow_tx_power_table was not correctly executed; error msg: wrong'
2016-06-10 07:30:07 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:07,850 - SimpleModule2.before_set_channel() - INF
O - This function is executed before set_channel'
2016-06-10 07:30:07 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:07,851 - SimpleModule2.set_channel() - INFO - Sim
ple Module sets channel: 4 on interface: wlan1'
2016-06-10 07:30:07 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:07,851 - SimpleModule2.after_set_channel() - INFO
 - This function is executed after set_channel'
2016-06-10 07:30:15 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:15,045 - SimpleModule2.send_to_module() - WARNING
 - Exception: function radio.clean_per_flow_tx_power_table was not correctly executed; error msg: wrong'
2016-06-10 07:30:17 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:17,867 - SimpleModule2.before_set_channel() - INF
O - This function is executed before set_channel'
2016-06-10 07:30:17 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:17,867 - SimpleModule2.set_channel() - INFO - Sim
ple Module sets channel: 4 on interface: wlan1'
2016-06-10 07:30:17 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:17,867 - SimpleModule2.after_set_channel() - INFO
 - This function is executed after set_channel'
2016-06-10 07:30:25 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:25,058 - SimpleModule2.send_to_module() - WARNING
 - Exception: function radio.clean_per_flow_tx_power_table was not correctly executed; error msg: wrong'
2016-06-10 07:30:27 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:27,879 - SimpleModule2.before_set_channel() - INF
O - This function is executed before set_channel'
2016-06-10 07:30:27 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:27,879 - SimpleModule2.set_channel() - INFO - Sim
ple Module sets channel: 4 on interface: wlan1'
2016-06-10 07:30:27 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:27,879 - SimpleModule2.after_set_channel() - INFO
 - This function is executed after set_channel'
2016-06-10 07:30:35 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:35,071 - SimpleModule2.send_to_module() - WARNING
 - Exception: function radio.clean_per_flow_tx_power_table was not correctly executed; error msg: wrong'
2016-06-10 07:30:37 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:37,892 - SimpleModule2.before_set_channel() - INF
O - This function is executed before set_channel'
2016-06-10 07:30:37 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:37,892 - SimpleModule2.set_channel() - INFO - Sim
ple Module sets channel: 4 on interface: wlan1'
2016-06-10 07:30:37 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:37,892 - SimpleModule2.after_set_channel() - INFO
 - This function is executed after set_channel'
2016-06-10 07:30:45 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:45,083 - SimpleModule2.send_to_module() - WARNING
 - Exception: function radio.clean_per_flow_tx_power_table was not correctly executed; error msg: wrong'
2016-06-10 07:30:47 DEBUG nodeHandler::AgentCommands: APP_EVENT STDERR from: 'agent#1' (node1-1.sb4.orbit-lab.org) - msg: '2016-06-10 07:30:47,904 - SimpleModule2.before_set_channel() - INF
O - This function is executed before set_channel'
}}}