vis_help.txt

simulator for ad hoc

/* 
 * Glomosim is COPYRIGHTED software.  It is freely available without fee for
 * education, or research, or to non-profit agencies. No cost evaluation
 * licenses are available for commercial users. By obtaining copies of this
 * and other files that comprise GloMoSim, you, the Licensee, agree to abide
 * by the following conditions and understandings with respect to the
 * copyrighted software:
 *
 * 1.Permission to use, copy, and modify this software and its documentation
 *   for education, research, and non-profit purposes is hereby granted to
 *   Licensee, provided that the copyright notice, the original author's names
 *   and unit identification, and this permission notice appear on all such
 *   copies, and that no charge be made for such copies. Any entity desiring
 *   permission to incorporate this software into commercial products or to use
 *   it for commercial purposes should contact: 
 *
 *   Professor Rajive Bagrodia 
 *   University of California, Los Angeles 
 *   Department of Computer Science 
 *   Box 951596 
 *   3532 Boelter Hall 
 *   Los Angeles, CA 90095-1596 
 *   [e-mail]
 *
 * 2.NO REPRESENTATIONS ARE MADE ABOUT THE SUITABILITY OF THE SOFTWARE FOR ANY
 *   PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
 *
 * 3.Neither the software developers, the Parallel Computing Lab, UCLA, or any
 *   affiliate of the UC system shall be liable for any damages suffered by
 *   Licensee from the use of this software.
 */

GloMoSim Visualization Tool User's Guide
For questions and concerns about GloMoSim,
please email [e-mail]

-----------------------------------------------------------------------
GloMoSim Java Visualization Tool, documentation version 1.1
Author: Addison Lee
Upgraded by Kaixin Xu
-----------------------------------------------------------------------

Outline:
 [1] Overview
 [2] Getting Started
 [3] Features of the Visualization Tool
 [4] Modifying GloMoSim to interact with the Visualization Tool

note: Throughout this document, I will use "VT" as an abbreviation
      for "Visualization Tool"

-----------------------------------------------------------------------
[1] Overview
-----------------------------------------------------------------------

The primary purpose of the Java VT is to help network designers debug
their protocols. It is written in Java to provide portability across
multiple platforms.

The GloMoSim simulation can be run with or without the VT. If run without
the VT, it can just be executed from the command line. However, if run with
the VT, it must be executed through the GUI provided by the VT rather
than from the command line.

-----------------------------------------------------------------------
[2] Getting Started 
-----------------------------------------------------------------------

[A] Preliminaries:
    - Make sure that the Java Development Kit (JDK) version 1.2 or higher
      is installed on your machine. Our VT now base on swing package of JDK
      If you prefer to use JDK 1.1, you must install the swing package for
      JDK 1.1. The swing package is included in JDK1.2.
    - Make sure that you have already compiled the GloMoSim source files.
      (see $glomo/doc/user.txt for more information on compiling GloMoSim)
    - Compile the Java VT files:
      - cd to the $glomo/java_gui/ directory
      - type: "javac *.java"

[B] Starting the VT:
    - From the $glomo/java_gui/ directory, type: "java GlomoMain &"

[C] An Example Use of the VT:
    - Start up the VT as explained in part b above.
    - Select "Real Time" from the "Simulate" menu.
    - A dialog will pop up asking for the name of the executable to run.
      The default is: "../bin/Sim ../bin/CONFIG.IN"(UNIX) 
      or "..\bin\glomo ..\bin\CONFIG.IN"(Windows NT);
      Click the "OK" button to continue.
    Once you click the "OK" button, the VT will run GloMoSim, capture the
    standard output (stdout) from GloMoSim, and graphically display the
    results on the screen.

-----------------------------------------------------------------------
[3] Features of the Visualization Tool
-----------------------------------------------------------------------

[A] Simulate Menu:

There are basically two ways to run GloMoSim with the VT: real time
and play back.

  [1] If you choose "Real Time" from the Simulate menu, then the VT will
      display the results of GloMoSim while GloMoSim is running.

  [2] If you wish to run GloMoSim first and then play the results of the
      simulation back later, then you need to do the following:

      (a) Choose "Write Trace" from the Simulate menu. A dialog will pop up
      asking for the name of the executable and the name of the trace file
      to write the output from GloMoSim to.

      (b) Once the trace file has been written to, you can play it back by
      choosing "Play Back" from the Simulate menu. A dialog will pop up asking
      for the name of the trace file to play back.

  The benefit of real time simulation is that you can see the results of
  the GloMoSim simulation right away rather than having to wait for it
  to be written to a trace file and then playing back the trace file.

  The benefit of play back is that you can save a particular scenario
  to file and play it back as many times as you want. Also, play back
  runs faster than real time since only the VT is running as opposed
  to both the VT and GloMoSim running at the same time.

  Here is how the radio layer is currently displayed in the VT:
  When a node transmits a packet, a yellow link is drawn from this node
  to all nodes within it's power range (see main/channel.pc).
  As each node receives the packet, the link is erased and a green line
  is drawn for successful reception and a red line is drawn for
  unsuccessful reception (see radio/radio_no.pc or radio/radio_has.pc).
  No distinction is made between different packet types (ie: control
  packets vs. regular pacekts, etc.)
  To modify this basic functionality, just change the code in the
  channel.pc and radio_*.pc files according to the specifications
  that I discussed earlier in this document.

  [3] There is also an abort option which can be used to abort the simulation.

[B] Options Menu:

The options menu allows the user to specify how things are to be displayed
on the VT.

    [1] Zoom Submenu:
        Allows the user to specify how big images will appear in the VT.

    [2] Background Colors Submenu:
        Allows the user to set the background color by choosing favourite 
        colors.

    [3] Gui Options Submenu:
        There is a tradeoff between specifying colors in the VT GUI
        and specifying colors in the GloMoSim code. Specifying colors
        in the VT GUI is much simpler for the user. However, it is not
        very scalable since every time you want to add a new feature
        which requires a color (such as a new type of packet), then
        you need to modify the Java VT source code. On the other hand,
        specifying all the colors in the GloMoSim code allows much more
        flexiblity for the developer. Since this VT is primarily meant
        for network designers to test out their protocols, I have chosen
        to let all the colors be specified by GloMoSim rather than having
        colors changeable through the VT GUI. In the near future, I will
        add an option to VT which allows the user to select colors to be
        chosen either from a small set of colors in the VT or to be
        completely specified from the GloMoSim code; that way, the network
        designers have the flexibility required to test their protocols,
        but at the same time, the basic colors can be changed quickly
        and easily as might be necessary if you are just doing a demo to show
        other people the results of your work.