= 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 -t".

== Prototypes and application definitions used with helloworld ==

 * [http://www.orbit-lab.org/attachment/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]