= OTG FAQ =

== General ==

=== What is OTG? ===

OTG is a software package which contains at least two executable programs in Unix/Linux environment: ''otg'' and ''otr''.

=== Is OTG free software? ===

OTG is open-source software and could be downloaded by everyone. However, by default, OTG/OTR 
are supposed to be used in ORBIT testbed to take advantage of Orbit measurement framework. 

=== How can I install it? ===

The installation of Orbit Traffic Generator is simple. On any node of Orbit Testbed, give command
{{{
apt-get install otg
}}}
three binary files "otg" "otr", "otf" will be copied to /usr/local/bin directory.

=== Where do I get the source code? ===
For orbit developers, latest sourcecode of OTG software can be checked out by this command
{{{
svn co http://svn.orbit-lab.org/svn/orbit/otg/trunk otg
}}}

=== Where can I find documentation of OTG/OTR? ===

Simply saying, this FAQ and the [wiki:OTG/UserManual User Manual] is enough for ordinary users. For developer, the [wiki:OTG/ArchitectureDesign Architecture design] document and the function specifications would be important descriptive sources for understanding the whole design.

If you want a real detailed documentation of code, it can be generated by the [http://www.doxygen.org Doxygen] tool
{{{
cd otg/doc/
doxygen otgdoc.cfg
}}}
Note: If Doxygen generates contradictory descriptions against Fucntion Specification, Function Sepcifiactions are actual implementation guidelines.
 
=== What is OTF? ===

OTF is the Orbit Traffic Forwarder. It is designed in order to enable layer-2 packet forwarding by MAC address. It could be used as a means to avoid routing protocols.

== Using OTG with NodeHandler ==

=== Why I have to write nodeHandler scripts to use OTG? ===

Basically, nodeHandler is a comprehensive tool to control the whole experiment in Orbit-testbed, including power on/off nodes, setup/break wire/wireless links. As OTG software can be used to test a link only after the link is eatablished. It is not a bad idea to also use "nodehandler"  to give command-line options and run-time options for OTG/OTR program.  Also, with this, users do not need to SSH to everynode and run the OTR program one by one manually.

=== When using nodehandler, where can I find the outputs of OTG/OTR during the experiment?
It is the experiment log, which is put in /tmp directory of console and named with your expeiment-id.log. [[BR]]
Some stdout output of otg/otr could be found:
{{{
2005-09-22 16:58:54 DEBUG nodeHandler::comm: process message (0): '/r_1/c_2 3 APP_EVENT STDOUT app:otg "packet size parameter is set as 1024"}'
2005-09-22 16:58:54 DEBUG nodeHandler::NodeHandler: Process message '/r_1/c_2 3 APP_EVENT STDOUT app:otg packet size parameter is set as 1024'
2005-09-22 16:58:54 DEBUG nodeHandler::agentCmd::APP_EVENT: STDOUT' from 'app:otg' executing on n_1_2: 'packet size parameter is set as 1024'
2005-09-22 16:58:54 DEBUG nodeHandler::node::n_1_2: Message for app 'app:otg'
2005-09-22 16:58:54 DEBUG nodeHandler::comm: process message (2): '/r_1/c_2 4 APP_EVENT STDOUT app:otg "Destination Hostname: 192.168.1.4"}'
2005-09-22 16:58:54 DEBUG nodeHandler::NodeHandler: Process message '/r_1/c_2 4 APP_EVENT STDOUT app:otg Destination Hostname: 192.168.1.4'
2005-09-22 16:58:54 DEBUG nodeHandler::agentCmd::APP_EVENT: STDOUT' from 'app:otg' executing on n_1_2: 'Destination Hostname: 192.168.1.4'
2005-09-22 16:58:54 DEBUG nodeHandler::node::n_1_2: Message for app 'app:otg'
2005-09-22 16:58:54 DEBUG nodeHandler::comm: process message (2): '/r_1/c_2 5 APP_EVENT STDOUT app:otg "Rate is set as 300000bps"}'
2005-09-22 16:58:54 DEBUG nodeHandler::NodeHandler: Process message '/r_1/c_2 5 APP_EVENT STDOUT app:otg Rate is set as 300000bps'
2005-09-22 16:58:54 DEBUG nodeHandler::agentCmd::APP_EVENT: STDOUT' from 'app:otg' executing on n_1_2: 'Rate is set as 300000bps'
....
2005-09-22 16:58:54 DEBUG nodeHandler::node::n_1_1: Message for app 'app:otr'
2005-09-22 16:58:54 DEBUG nodeHandler::comm: process message (0): '/r_1/c_1 4 APP_EVENT STDOUT app:otr "binding to port: 4000......"}'
2005-09-22 16:58:54 DEBUG nodeHandler::NodeHandler: Process message '/r_1/c_1 4 APP_EVENT STDOUT app:otr binding to port: 4000......'
2005-09-22 16:58:54 DEBUG nodeHandler::agentCmd::APP_EVENT: STDOUT' from 'app:otr' executing on n_1_1: 'binding to port: 4000......'
}}}

=== where can I see the experimetn XML files ? ===
It is generated dynamically and put in the /tmp directory of the console. The naming convention for this file is "experimentname+timestamp".
The oml_experiment XML files are stored in /tmp directory of  the nodes participating the experiment. For example, if a node is running OTG during the experiment, an XML configuration file, which tells OTG where to send OML measuremeents, should be existing in the /tmp/ directory of that node. The name of that file consists of some random characters.


== Writing Scripts for OTG Application ==

=== I need to specify the OTG sender port in the experiment file, what all do I need to modify? ===

you can check if the otg.rb already list "port" as a property or not? If yes, then go to sender.rb to see if
the "port" property is binded to the sender object or not?
if both are done, you can configure this property as same as other property in your experiment script.

== Trouble shouting ==
=== why the OML database for my experiment has empty tables (0 records)? ===
The OTG/OTR is only used to test link performance. The user has to ensure the link availabilty before running OTG/OTR programs. One plausible reason for empty table is the link does not exists at all (wrong channel setting, cell id mismatch...). This is surprisingly frequent in wireless tests. Check your experiment scripts carefully.

=== Why I get "bind error" when starting otg/otr? ===
Be sure a port in one machine can only used by one program. If you run multiple OTG programs in one machine, use different "--port" settings.


=== Why I get an "rx_timestamp" earler than "tx_timestamp" ? ===
Timestamp shows the time offset since the program is started.
If you start OTR later than OTG, it is possible to see a smaller rx_timestamp than tx_timestamp.