= Tutorial 1: Hello World Example =
[wiki:Tutorial Back]
[[TOC(heading=Tutorial TOC, Tutorial, Tutorial/Testbed, Tutorial/HowtoWriteScripts, Tutorial/HelloWorld,   Tutorial/CollectMeasurements, Tutorial/AnalyzeResults, depth=2)]]

In the "Hello World" experiment, a ''sender'' node sends a data stream to a ''receiver'' node.  The script for this experiment is shown below.

{{{

#
# Define nodes used in experiment
#
defNodes('sender', [1,1]) {|node|
  node.prototype("test:proto:sender", {
    'destinationHost' => '192.168.1.2',
    'packetSize' => 1024,
    'rate' => 300,
    'protocol' => 'udp'    
  })
  node.net.w0.mode = "managed"
}

defNodes('receiver', [1,2]) {|node|
  node.prototype("test:proto:receiver" , {
    'protocol' => 'udp'
  })
  node.net.w0.mode = "master"
}

allNodes.net.w0 { |w|
  w.type = 'b'
  w.essid = "helloworld"
  w.ip = "%192.168.%x.%y"
}

#
# Now, start the application
#
whenAllInstalled() {|node|
  wait 30 

  allNodes.startApplications
  wait 40

  Experiment.done
}
}}}

Figure 1.  Script for "Hello World" Experiment

== Understanding the Hello World ==

The first part of the script creates a group called ''sender'' and assigns node1-1 to it.
Next, we instruct nodehandler to assign the prototype [http://www.orbit-lab.org/wiki/Documentation/OTG/ScriptsRepository/ProtoDefSender ''test:proto:sender'']  to node1-1. A prototype is similar to a function or macro in conventional programming languages and defines in this case a re-usable configuration. The prototypes are normally defined in separate files.  In this case, the prototype contains instructions to install a traffic generator, but we will learn about this later. What is important here is that a prototype can define properties which allows us to customize it for the specific experiment. In this experiment, we can set the address of the sender, and various properties of the traffic generator itself, such as packet size, rate, and the protocol over which to send the traffic. 

{{{
defNodes('sender', [1,1]) {|node|                   
  node.prototype("test:proto:sender", {
    'destinationHost' => '192.168.1.2',
    'packetSize' => 1024,
    'rate' => 300,
    'protocol' => 'udp'
  })
  node.net.w0.mode = "managed"
}
}}}
The last line 'node.net.w0.mode' configures the first wireless interface ''w0'' to be used in ''managed'' mode.

The next block of code defines node1-2 as a receiver in similar fashion. We are using the ''receiver'' prototype here which installs a traffic sink. In addition, we are setting the receiver's first wireless interface to ''master'' mode.

{{{
defNodes('receiver', [1,2]) {|node|
  node.prototype("test:proto:receiver" , {
    'protocol' => 'udp'
  })
  node.net.w0.mode = "master"
}
}}}

What follows is an example on how to configure interfaces on all nodes in one place to ensure consistency. The command ''allNodes.net.w0'' describes the first wireless interface on all nodes in the experiment. The code inside the curly braces configures various parameters of these interfaces. In this specific example we configure the interface as an 802.11b type, set the ''essid'' to a common string, and set it's IP address. We obviously do not want to set all the interfaces to the same IP address, but any string beginning with a '%' is ''personalized'' for each node by replacing characters preceeded by a '%' with a local string. In this specific example, '%y' is replaced by the 'y' coordinate of the node. For this specific experiment setup, the IP address of node1_1 will be 192.168.1.1, while node1_2 will have 192.168.1.2 assigned.

{{{
allNodes.net.w0 { |w|
  w.type = 'b'
  w.essid = "helloworld"
  w.ip = "%192.168.%x.%y"
}
}}}

This concludes the configuration steps and we will now describe the experiment itself. The experiment script basically defines a state machine, or more precisely, what sequence of commands should be executed if the experiments enters a particular state. The only state we will use in this experiment is ''whenAllInstalled'' which the experiment controller reaches when all nodes are configures and all requested applications are installed and ready to go.
{{{
whenAllInstalled() {|node|
  wait 30 

  allNodes.startApplications
  wait 40

  Experiment.done
}
}}}
The first command 'wait 30' will block for an additional 30 seconds to ensure that indeed everything has settled. The ''allNodes.startApplications'' will send a command to all nodes to start the applications defined in the above 'defNodes' block, or more precisly the used prototypes. In our experiment, this command will start a traffic generator in node1_2 and a corresponding sink in node1_2. The rate and packet size parameters for the traffic generator are taken from the above definition as well.

The next line 'wait 40' will instruct the experiment controller to wait for 40 seconds before concluding the experiment (''Experiment.done'').

== Running Hello World ==
Reserve a time slot on one of the sandboxes, log into the appropriate console machine, image the nodes and run "nodehandler --tutorial".
Your console output should look something like this:

{{{
console.grid:~/topology# nodehandler4 -d grid --tutorial
DEBUG Experiment: Domain: grid
 INFO init: NodeHandler Version 4.2.0 (1272)
 INFO init: Experiment ID: grid_2007_11_19_19_15_19
 INFO ExecApp: Starting application 'commServer': /opt/nodehandler4-4.2.0/sbin/commServer --logfile /tmp/commServer-grid_2007_11_19_19_15_19.log -d 4 --iface eth1
 INFO Experiment: load system:exp:stdlib
 INFO prop.resetDelay: resetDelay = 210:Fixnum
 INFO prop.resetTries: resetTries = 1:Fixnum
 INFO Experiment: load test:exp:tutorial-1a
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO stdlib: Waiting for nodes (Up/Down/Total): 0/2/2 - (still down: n_1_2,n_1_1)
 INFO n_1_1: Device 'net/w0' reported Not-Associated
 INFO stdlib: Waiting for nodes (Up/Down/Total): 1/1/2 - (still down: n_1_2)
 INFO whenAll: *: 'apps/app/status[@value='INSTALLED.OK']' fires
 INFO n_1_1: Device 'net/w0' reported 00:60:B3:25:BF:F5
 INFO n_1_2: Device 'net/w0' reported 00:60:B3:25:BF:F5
 INFO OML: Started: {"port"=>"7600", "iface"=>"eth2", "addr"=>"224.0.0.6"}
 INFO Experiment: DONE!
 INFO ExecApp: Application 'commServer' finished
 INFO run: Experiment grid_2007_11_19_19_15_19 finished after 3:41
console.grid:~/topology#                                          
}}}
 
== Prototypes and application definitions used with helloworld ==

 * [wiki:Documentation/OTG/ScriptsRepository/otg.rb otg.rb]
 * [wiki:Documentation/OTG/ScriptsRepository/OtrAppdef otr.rb]
 
 * [wiki:Documentation/OTG/ScriptsRepository/ProtoDefSender sender.rb]
 * [wiki:Documentation/OTG/ScriptsRepository/ProtoDefReceiver receiver.rb]