Difference between revisions of "NetAnim2"

From Nsnam
Jump to: navigation, search
m (Using a new repository)
m (Remove manual links and replace them with wiki links)
 
(302 intermediate revisions by 3 users not shown)
Line 1: Line 1:
A simple animator is presented here, called NetAnim. Written by George Riley, and based on the multi-platform [http://www.qtsoftware.com/products/ QT4 GUI toolkit], it is capable of animating simulations with PointToPoint links in ns-3. It depicts frames on the links as they travel from node to node.  It uses a custom trace output format for animation, so there is some additional code which has to be included in ns-3 to enable these traces.
+
[[NetAnim|NetAnim 3 page]] contains more recent information.
 +
 
 +
NetAnim is an animator based on the multi-platform Qt 4 toolkit. NetAnim can animate a simulation using offline trace files (basic-mode) or it can animate while simulation is running (advanced-mode). NetAnim's advanced-mode also supports some basic statistics collection. Please note that advanced-mode is experimental.
  
 
[[Image:Net-anim.png|thumb|The NetAnim GUI]]  
 
[[Image:Net-anim.png|thumb|The NetAnim GUI]]  
 +
 +
 +
== Feature-set in NetAnim 2.0 ==
 +
* Basic
 +
** Read offline XML trace file generated by ns-3's [http://www.nsnam.org/doxygen/classns3_1_1_animation_interface.html AnimationInterface]
 +
** Ability to track Wired & Wireless transmission (LTE not yet supported)
 +
** Any node having a mobility model can be seen on the Animation.
 +
** Track mobility of nodes
 +
** Record button to take periodic snapshots of the Animation
 +
** Display Node Id on the Animation canvas, with zoom-in, zoom-out etc
 +
 +
* Advanced (Requires integration with ns-3 libraries) Experimental: [[ NetAnim Advanced mode ]]
 +
 +
* Feature removed
 +
** Socket based communication between the Animator and ns-3
 +
 +
== Feature-set in NetAnim 1.0 ==
 +
# Animate only Wired topology
 +
# Read non-XML trace file generated by ns-3
 +
 +
* For more on NetAnim 1.0 go to [[NetAnim 1.0]]
  
  
 
== Prerequisites ==
 
== Prerequisites ==
The animator requires the QT4 development packages. If you are using a Debian or Ubuntu Linux distribution, you can get the following package:
+
# mercurial
qt4-dev-tools
+
# QT4 development packages (recommended version 4.7)
 +
# xerces-c++ development packages (minimum version 3.1.1)
  
This should install everything you need to compile and build NetAnim.  If you are using an Red Hat based distribution, look for similar qt4 packages (or libqt4*) and install these using yum.  Mac users should install the binaries:
+
=== Debian/Ubuntu Linux distribution:===
http://www.qtsoftware.com/downloads/mac-os-cpp
+
# apt-get install mercurial
 +
# apt-get install qt4-dev-tools
 +
# apt-get install libxerces-c-dev
  
Make sure to download the binary package; look for a link to something without the word "src" or "debug" in the download filename.  These will be the library binaries you need.
+
=== Red Hat/Fedora based distribution:===
 +
# yum install mercurial
 +
# yum install qt4
 +
# yum install qt4-devel
 +
# yum install xerces-c
 +
# yum install xerces-c-devel
  
Also, you will require mercurial.  See your distribution's packages or the mercurial website for more info.
+
=== Mac/OSX ===
 +
# mercurial
 +
# Qt4 : Install Qt4 (including Qt Creator if possible) from http://qt.nokia.com/downloads/
 +
# Xerces-c++: http://xerces.apache.org/xerces-c/download.cgi (minimum version 3.1.1)
  
 
== Downloading NetAnim ==
 
== Downloading NetAnim ==
The tarball of the source code is available [http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz here].  Download it, then untar it:
+
* NetAnim 2.0:  
  
tar -xzvf NetAnim.tar.gz
+
hg clone http://code.nsnam.org/jabraham3/netanim2
  
== Building NetAnim ==
+
* NetAnim 1.0:
NetAnim uses a QT4 build tool called qmake; this is similar to the configure script from autotools in that it generates the Makefile, which make then uses to build the project. qmake is different on different versions of Qt, so we'll provide some additional information that is system dependent.  You can check your default version of qmake:
+
Go to this link [[NetAnim 1.0]]
 
+
qmake --version
+
Qmake version: 1.07a (Qt 3.3.8b)
+
Qmake is free software from Trolltech ASA.
+
  
If you see something like the above, where it says Qt 3.x.x, find the qt4 version of qmake on your system and explicitly call it instead.
+
== Building NetAnim 2.0 (Basic-Mode) ==
 +
NetAnim uses a QT4 build tool called qmake. Only qmake version 4.7 is supported
 +
Please read the [[#Prerequisites]] before proceeding
  
 
=== In General ===
 
=== In General ===
  
  cd NetAnim
+
  cd netanim
  qmake
+
make clean
 +
  qmake NetAnim.pro   
 
  make
 
  make
 +
 +
Note: qmake could be "qmake-qt4" in some systems
 +
 +
This should create an executable named "NetAnim" in the same directory
  
 
=== On Mac OS X ===
 
=== On Mac OS X ===
 +
The supported Qt 4 version is Qt 4.7. "qmake" is usually available along with the installation of Qt Creator
  
  cd NetAnim
+
  cd netanim
  /usr/local/Trolltech/Qt-4.x.y/bin/qmake
+
  <path-to-qmake 4.7>/qmake NetAnim.pro
 
  make
 
  make
  
Note that above, the x.y is the specific version of Qt4 you are running.  As of April 1st 2009, the latest version is 4.5.0, although you might have an older version already installed.
+
=== On Fedora ===
  
=== On Ubuntu/Debian with Qt3 AND Qt4 ===
+
  cd netanim
 
+
  qmake-qt4 NetAnim.pro
  cd NetAnim
+
  qmake-qt4
+
 
  make
 
  make
  
== Adding the Animation Interface for ns-3 ==
+
== Using ns3::AnimationInterface to generate Animation trace files==
 +
 
 +
The NetAnim application requires a custom trace file for animation. 
 +
This trace file is created by [http://www.nsnam.org/doxygen/classns3_1_1_animation_interface.html AnimationInterface] in ns-3.
 +
# Model is at: src/netanim/model
 +
# Examples are at src/netanim/examples
 +
 
 +
NetAnim 2.0 supports only reading XML trace files.
 +
 
 +
NetAnim 1.0 can read only Non-XML traces.
 +
 
 +
AnimationInterface as of ns-3.12 generates only non-XML trace files by default.
 +
To generate XML trace files, use [http://www.nsnam.org/doxygen/classns3_1_1_animation_interface.html#ae8612e0b82dd1166add6e959d6c5e5a8 void ns3::AnimationInterface::SetXMLOutput()] prior to StartAnimation. See the examples under "src/netanim/examples"
 +
 
 +
=== Recommended set of steps ===
 +
Here is the recommended set of steps for generating XML Animation traces.They must be applied before the "Simulation::Run" statement.
 +
 
 +
'''NOTE: A node must have an associated mobility model in-order to be displayed on the animation.
 +
This applies for both stationary and mobile nodes (See notes below) '''
 +
  0. Ensure that your wscript includes the "netanim" module. Example as in: src/netanim/examples/wscript. Also include the header [#include "ns3/netanim-module.h"] in your test program
 +
 
 +
For ns-3 version upto ns-3.12
 +
  1. AnimationInterface anim;
 +
  2. anim.SetOutputFile ("animation.xml");
 +
  3. anim.SetXMLOutput ();
 +
  4. anim.SetMobilityPollInterval (Seconds (1));
 +
  5. anim.StartAnimation ();
 +
 
 +
where
 +
  1. Create an AnimationInterface object
 +
  2. Set the trace output file name
 +
  3. Enable XML output (Only when using NetAnim 2.0). If this statement is not used, the AnimationInterface generates traces which are non-XML and can only be
 +
      read by NetAnim 1.0
 +
  4. This statement is optional. It records the position of the nodes every 1 second. NOTE: Setting a low value may result in large XML files.
 +
    If your topology is expected to be stationary, it will be good to set it to a very large value (so that polling occurs rarely).
 +
  5. Start recording traces. StartAnimation and other AnimationInterface methods should be called before "Simulator::Run()"
 +
 
 +
For ns-3 version after ns-3.12
 +
  1. AnimationInterface anim ("animation.xml")
 +
  2. anim.SetMobilityPollInterval (Seconds (1));[OPTIONAL]
 +
 
 +
=== Running an Example File ===
 +
 
 +
The netanim example files are located under "src/netanim/examples"
 +
 
 +
  ./waf --run "dumbbell-animation --nLeftLeaf=5 --nRightLeaf=5 --animFile=dumbbell.xml"
 +
  ./waf --run "grid-animation --xSize=5 --ySize=5 --animFile=grid.xml"
 +
 
 +
 
 +
=== Setting the location of nodes ===
 +
NetAnim requires a location to be assigned to each Node, in-order to be shown on the animation.
 +
 
 +
==== For stationary nodes: ====
 +
* You should assign the ConstantPositionMobilityModel. Constant Position is a kind of mobility.
 +
Here is an example:
 +
 
 +
  1. Ptr<Node> n = nodecontainer.Get (1);
 +
  2. Ptr<ConstantPositionMobilityModel> Loc =  n->GetObject<ConstantPositionMobilityModel> ();
 +
  3. if (Loc == 0)
 +
        {
 +
  4.    Loc = CreateObject<ConstantPositionMobilityModel> ();
 +
  5.    n->AggregateObject (Loc);
 +
        }
 +
  6. Vector vec (10, 20, 0);
 +
  7. Loc->SetPosition (vec);
 +
 
 +
where
 +
 
 +
  1. Get a Ptr to Node from the node container
 +
  2. Get the aggregated ConstantPositionMobilityModel object from the node
 +
  3. If Loc ==0 , it indicates that this node is not aggregated with a mobility model.So we have to aggregate one.
 +
  4. Create a ConstantPositionMobilityModel object and assign it to Loc
 +
  5. Aggregate the mobility model "Loc" to the node
 +
  6. Create a position vector with 3-d co-ordinates  x= 10, y= 20, z=0
 +
  7. Set the position vector to the mobility model
 +
 
 +
==== For mobile nodes ====
 +
* You should assign any suitable Mobility model.
 +
The examples for these are found in places such as src/mobility/examples or examples/routing/manet-routing-compare.cc etc
 +
 
 +
== Understanding the XML trace file format ==
 +
 
 +
The ns3::AnimationInterface class is responsible for the creation of the xml trace files. Currently, in basic-mode, AnimationInterface records the position of the nodes at every periodic interval. This interval is 200 ms by default. This will become more efficient in future releases. This has the potential to cause
 +
a. Slowness in simulation
 +
b. Large XML trace files
 +
 
 +
Some ways to get around this is to identify if your topology has
 +
# only stationary nodes and hence no mobility
 +
# or slow-moving nodes
 +
 
 +
If the above is the case you should use AnimationInterface::SetMobilityPollInterval to set the poll interval to a high value.
 +
 
 +
=== Parts of the XML ===
 +
The XML trace files has the following main sections
 +
# Topology
 +
## Nodes
 +
## Links
 +
# packets (packets over wired-links)
 +
# wpackets (packets over wireless-links.LTE not supported)
 +
 
 +
=== XML tags ===
 +
Nodes are identified by their unique Node id.
 +
The XML begins with the "information" element describing the rest of the elements
 +
 
 +
==== <anim> element ====
 +
This is the XML root element. All other elements fall within this element
 +
  Attributes are:
 +
    lp = Logical Processor Id (Used for distributed simulations only)
 +
 
 +
====  <topology> element ====
 +
This elements contains the Node and Link elements.It describes, the
 +
co-ordinates of the canvas used for animation.
 +
 +
  Attributes are:
 +
    minX = minimum X coordinate of the animation canvas
 +
    minY = minimum Y coordinate of the animation canvas
 +
    maxX = maximum X coordinate of the animation canvas
 +
    maxY = maximum Y coordinate of the animation canvas
 +
 +
  Example:
 +
  <topology minX = "-6.42025" minY = "-6.48444" maxX = "186.187" maxY = "188.049">
 +
 
 +
==== <node> element ====
 +
This element describes each Node's Id and X,Y co-ordinate (position)
 +
 
 +
  Attributes are:
 +
    lp = Logical Processor Id (Used for distributed simulations only)
 +
    id = Node Id
 +
    locX = X coordinate
 +
    locY = Y coordinate
 +
 
 +
  Example:
 +
  <node lp = "0" id = "8" locX = "107.599" locY = "96.9366" />
 +
 
 +
==== <link> element ====
 +
This element describes wired links between two nodes.
 +
 
 +
  Attributes are:
 +
    fromLp = From logical processor Id  (Used for distributed simulations only)
 +
    fromId = From Node Id (first node id)
 +
    toLp  = To logical processor Id
 +
    toId  = To Node Id (second node id)
 +
 
 +
  Example:
 +
  <link fromLp="0" fromId="0" toLp="0" toId="1"/>
 +
 
 +
====  <packet> element ====
 +
This element describes a packet over wired links being transmitted at some node and received at another
 +
The reception details is described in it associated rx element
 +
 
 +
  Attributes are:
 +
    fromLp = From logical processor Id  (Used for distributed simulations only)
 +
    fromId = Node Id transmitting the packet
 +
    fbTx = First bit transmit time of the packet
 +
    lbTx = Last bit transmit time of the packet
 +
 
 +
  Example:
 +
  <packet fromLp="0" fromId="1" fbTx="1" lbTx="1.000067199"><rx toLp="0" toId="0" fbRx="1.002" lbRx="1.002067199"/>
 +
  Packet over wired-links from Node 1 was received at Node 0. The first bit of the packet was transmitted at  the 1th second, the last bit was transmitted at the
 +
  1.000067199th second of the simulation
 +
  Node 0 received the first bit of the packet at the 1.002th second and the last bit of the packet at the 1.002067199th second of the simulation
 +
 
 +
NOTE: A packet with fromId == toId is a dummy packet used internally by the AnimationInterface.Please ignore this packet
 +
 
 +
===== <rx> element =====
 +
This element describes the reception of a packet at a node
 +
 
 +
  Attributes are:
 +
    toLp = To logical processor Id
 +
    toId = Node Id receiving the packet
 +
    fbRx = First bit Reception Time of the packet
 +
    lbRx = Last bit Reception Time of the packet
 +
 
 +
==== <wpacket> element ====
 +
This element describes a packet over wireless links being transmitted at some node and received at another
 +
The reception details is described in it associated rx element
 +
 
 +
  Attributes are:
 +
    fromLp = From logical processor Id (Used in distributed simulations only)
 +
    fromId = Node Id transmitting the packet
 +
    fbTx = First bit transmit time of the packet
 +
    lbTx = Last bit transmit time of the packet
 +
    range = Range of the transmission
 +
 
 +
  Example:
 +
  <wpacket fromLp = "0" fromId = "20" fbTx = "0.003" lbTx = "0.003254" range = "59.68176982">
 +
  <rx toLp="0" toId="32" fbRx="0.003000198" lbRx="0.003254198"/>
 +
  Packet over wireless-links from Node 20 was received at Node 32. The first bit of the packet was transmitted at  the 0.003th second,
 +
  the last bit was transmitted at the
 +
  0.003254 second of the simulation
 +
  Node 0 received the first bit of the packet at the 0.003000198 second and the last bit of the packet at the 0.003254198 second of the simulation
 +
 
 +
== Using the XML trace with NetAnim ==
 +
 
 +
* Here is a youtube video demonstrating Animation for Wireless transmission [http://www.youtube.com/watch?v=-ObcW85Go8M click here]
 +
* Here is a youtube video demonstrating Animation for Wired transmission [https://www.youtube.com/watch?v=DW6upNpJQns click here]
  
This is a layer which allows ns-3 instances to talk to NetAnim.  This is presently implemented by an "AnimationInterface" class in ns-3.  The ns-3 animation interface can be installed in two ways.  First, a new repository can be downloaded, extracted, and built.  This is easier if you are unfamiliar with mercurial or applying patches.  Second, a patch can be used against an existing mercurial repository.
 
  
=== Using a new repository ===
+
=== Parts of the basic-mode Animator ===
 +
The basic-mode Animator will have the following buttons shown here [[File:GeneralVCR.png]]
  
The netanim repository can be downloaded [http://www.nsnam.org/~jpelkey3/ns-3-netanim.tar.gz here]. To use this repository, download and extract it:
+
* Quit: Quits the NetAnim application
 +
* Concentric circles: Shows Wireless transmission as concentric circles
 +
* Reverse play button: Plays the animation in the reverse direction. Don't use this if "Track" button is enabled
 +
* Forward play button: Plays the animation in the forward direction
 +
* Pause button: Used to pause the animation
 +
* The History slider: Used to go back in simulation time [[File:History.png]]
  
  tar -xzvf ns-3-netanim.tar.gz
+
* Update rate slider: [[File:Updateperiod.png]]
 +
This slider controls the interval between updating animation. If it is low, more packets will be animated, but the simulation progress will be slow
 +
<font color=red>'''If it is high, some packets may get skipped, although the simulation may progress faster.
 +
'''</font color>
  
Then enter the ns-3-netanim directory, and build:
 
  
  ./waf -d debug configure
+
[[File:miscbuttons.png]]
 +
* Record button: WIll take snapshots of the animation at periodic intervals and store them as a collection of images under the "recordings" folder
 +
* Zoom-in button: Zoom into the animation
 +
* Zoom-out button: Zoom out
 +
* Reset Zoom
 +
* Pkt ON: If suppressed will display packet transmission. Disable this button, when you are only interested in seeing the location of the nodes (or mobility)
  
 +
[[File:shownode.png]]
 +
* Show Node Id: If enabled shows the Node Id of each node on the canvas
 +
* Node Id Font size: Controls the font size of the Node Id mentioned above
  
Then build:
+
=== Using the XML trace file in NetAnim 2.0 ===
 +
# Open the XML file via "Options" menu --> "Load XML"
  
  ./waf
+
=== Using the non-XML trace file in NetAnim 1.0 ===
 +
# use the command-line
 +
./NetAnim dumbbell-tr
  
=== Using a patch ===
 
  
This patch was created against the ns-3-dev repository, specifically changeset 4e068296f09f [Aug. 17, 2009].  Care should be taken to ensure that a relavent version of ns-3 is used for updating.  If you are unsure, using a new repository [above] is recommended.  You can download the patch [http://www.nsnam.org/~jpelkey3/ns-3-netanim.patch here].  Copy this patch into the ns-3 root directory which you will update, and execute:
 
  
  hg patch ns-3-netanim.patch
+
== F.A.Q ==
 +
* I get
 +
/usr/bin/ld: cannot find -lsqlite3
 +
/usr/bin/ld: cannot find -lpng14
 +
/usr/bin/ld: cannot find -lintl
 +
>>> Try removing the corresponding "-l" phrases from the LIBS variable in NetAnim.pro
  
Then build:
+
* I get GLib-GIO:ERROR:gdbusconnection.c:2279:initable_init: assertion failed: (connection->initialization_error == NULL)Aborted (core dumped)
 +
>>> Don't install or run NetAnim as a root-user
  
  ./waf
+
* I get
 +
QImage: XPM pixels missing on image line 9 (possibly a C++ trigraph).
 +
QImage: XPM pixels missing on image line 10 (possibly a C++ trigraph).
 +
QImage: XPM pixels missing on image line 11 (possibly a C++ trigraph).
 +
QImage: XPM pixels missing on image line 12 (possibly a C++ trigraph).
 +
QImage: XPM pixels missing on image line 13 (possibly a C++ trigraph).
 +
QImage: XPM pixels missing on image line 14 (possibly a C++ trigraph)
  
== Running an Example File ==
+
>>> These can be ignored
An example of how to use the animation functionality can be found [http://www.nsnam.org/~raj/testdb.cc here].  You can drop this file into your scratch directory of ns-3-netanim to compile it and try it out:
+
  
./waf --run "scratch/testdb --nLeftLeaf=10 --nRightLeaf=3 --animFile=out.tr"
+
* I am unable to see any packets animated
  
Then take the output file we generated, and feed it into NetAnim.  Copy the out.tr file from ns-3-netanim directory to the NetAnim directory. From the NetAnim directory:
+
>>> If you are using Wireless links , try using the "Track" button
 +
  >>> If you are using Wired links, try disabling the "Track" button
  
  ./NetAnim out.tr
+
* The program hangs or crashes
 +
  >>> Double-check if the "Special-rules" section has been followed
  
This should produce an animation of the packets in the simulation. The sliders control the behavior of the speed of animation.
+
* I get *.so not found. Try using -rpath
 +
>>> ensure that you have set LD_LIBRARY_PATH correctly

Latest revision as of 16:35, 10 February 2013

NetAnim 3 page contains more recent information.

NetAnim is an animator based on the multi-platform Qt 4 toolkit. NetAnim can animate a simulation using offline trace files (basic-mode) or it can animate while simulation is running (advanced-mode). NetAnim's advanced-mode also supports some basic statistics collection. Please note that advanced-mode is experimental.

The NetAnim GUI


Feature-set in NetAnim 2.0

  • Basic
    • Read offline XML trace file generated by ns-3's AnimationInterface
    • Ability to track Wired & Wireless transmission (LTE not yet supported)
    • Any node having a mobility model can be seen on the Animation.
    • Track mobility of nodes
    • Record button to take periodic snapshots of the Animation
    • Display Node Id on the Animation canvas, with zoom-in, zoom-out etc
  • Feature removed
    • Socket based communication between the Animator and ns-3

Feature-set in NetAnim 1.0

  1. Animate only Wired topology
  2. Read non-XML trace file generated by ns-3


Prerequisites

  1. mercurial
  2. QT4 development packages (recommended version 4.7)
  3. xerces-c++ development packages (minimum version 3.1.1)

Debian/Ubuntu Linux distribution:

  1. apt-get install mercurial
  2. apt-get install qt4-dev-tools
  3. apt-get install libxerces-c-dev

Red Hat/Fedora based distribution:

  1. yum install mercurial
  2. yum install qt4
  3. yum install qt4-devel
  4. yum install xerces-c
  5. yum install xerces-c-devel

Mac/OSX

  1. mercurial
  2. Qt4 : Install Qt4 (including Qt Creator if possible) from http://qt.nokia.com/downloads/
  3. Xerces-c++: http://xerces.apache.org/xerces-c/download.cgi (minimum version 3.1.1)

Downloading NetAnim

  • NetAnim 2.0:

hg clone http://code.nsnam.org/jabraham3/netanim2

  • NetAnim 1.0:

Go to this link NetAnim 1.0

Building NetAnim 2.0 (Basic-Mode)

NetAnim uses a QT4 build tool called qmake. Only qmake version 4.7 is supported Please read the #Prerequisites before proceeding

In General

cd netanim
make clean
qmake NetAnim.pro    
make

Note: qmake could be "qmake-qt4" in some systems

This should create an executable named "NetAnim" in the same directory

On Mac OS X

The supported Qt 4 version is Qt 4.7. "qmake" is usually available along with the installation of Qt Creator

cd netanim
<path-to-qmake 4.7>/qmake NetAnim.pro
make

On Fedora

cd netanim
qmake-qt4 NetAnim.pro
make

Using ns3::AnimationInterface to generate Animation trace files

The NetAnim application requires a custom trace file for animation. This trace file is created by AnimationInterface in ns-3.

  1. Model is at: src/netanim/model
  2. Examples are at src/netanim/examples

NetAnim 2.0 supports only reading XML trace files.

NetAnim 1.0 can read only Non-XML traces.

AnimationInterface as of ns-3.12 generates only non-XML trace files by default. To generate XML trace files, use void ns3::AnimationInterface::SetXMLOutput() prior to StartAnimation. See the examples under "src/netanim/examples"

Recommended set of steps

Here is the recommended set of steps for generating XML Animation traces.They must be applied before the "Simulation::Run" statement.

NOTE: A node must have an associated mobility model in-order to be displayed on the animation. This applies for both stationary and mobile nodes (See notes below)

 0. Ensure that your wscript includes the "netanim" module. Example as in: src/netanim/examples/wscript. Also include the header [#include "ns3/netanim-module.h"] in your test program

For ns-3 version upto ns-3.12

 1. AnimationInterface anim;
 2. anim.SetOutputFile ("animation.xml");
 3. anim.SetXMLOutput ();
 4. anim.SetMobilityPollInterval (Seconds (1));	
 5. anim.StartAnimation ();

where

 1. Create an AnimationInterface object
 2. Set the trace output file name
 3. Enable XML output (Only when using NetAnim 2.0). If this statement is not used, the AnimationInterface generates traces which are non-XML and can only be
     read by NetAnim 1.0
 4. This statement is optional. It records the position of the nodes every 1 second. NOTE: Setting a low value may result in large XML files.
    If your topology is expected to be stationary, it will be good to set it to a very large value (so that polling occurs rarely).
 5. Start recording traces. StartAnimation and other AnimationInterface methods should be called before "Simulator::Run()"

For ns-3 version after ns-3.12

 1. AnimationInterface anim ("animation.xml") 
 2. anim.SetMobilityPollInterval (Seconds (1));[OPTIONAL]

Running an Example File

The netanim example files are located under "src/netanim/examples"

 ./waf --run "dumbbell-animation --nLeftLeaf=5 --nRightLeaf=5 --animFile=dumbbell.xml"
 ./waf --run "grid-animation --xSize=5 --ySize=5 --animFile=grid.xml"


Setting the location of nodes

NetAnim requires a location to be assigned to each Node, in-order to be shown on the animation.

For stationary nodes:

  • You should assign the ConstantPositionMobilityModel. Constant Position is a kind of mobility.

Here is an example:

 1. Ptr<Node> n = nodecontainer.Get (1);
 2. Ptr<ConstantPositionMobilityModel> Loc =  n->GetObject<ConstantPositionMobilityModel> ();
 3. if (Loc == 0)
       {
 4.     Loc = CreateObject<ConstantPositionMobilityModel> ();
 5.     n->AggregateObject (Loc);
       }
 6. Vector vec (10, 20, 0);
 7. Loc->SetPosition (vec);

where

 1. Get a Ptr to Node from the node container
 2. Get the aggregated ConstantPositionMobilityModel object from the node
 3. If Loc ==0 , it indicates that this node is not aggregated with a mobility model.So we have to aggregate one.
 4. Create a ConstantPositionMobilityModel object and assign it to Loc
 5. Aggregate the mobility model "Loc" to the node
 6. Create a position vector with 3-d co-ordinates  x= 10, y= 20, z=0
 7. Set the position vector to the mobility model

For mobile nodes

  • You should assign any suitable Mobility model.

The examples for these are found in places such as src/mobility/examples or examples/routing/manet-routing-compare.cc etc

Understanding the XML trace file format

The ns3::AnimationInterface class is responsible for the creation of the xml trace files. Currently, in basic-mode, AnimationInterface records the position of the nodes at every periodic interval. This interval is 200 ms by default. This will become more efficient in future releases. This has the potential to cause a. Slowness in simulation b. Large XML trace files

Some ways to get around this is to identify if your topology has

  1. only stationary nodes and hence no mobility
  2. or slow-moving nodes

If the above is the case you should use AnimationInterface::SetMobilityPollInterval to set the poll interval to a high value.

Parts of the XML

The XML trace files has the following main sections

  1. Topology
    1. Nodes
    2. Links
  2. packets (packets over wired-links)
  3. wpackets (packets over wireless-links.LTE not supported)

XML tags

Nodes are identified by their unique Node id. The XML begins with the "information" element describing the rest of the elements

<anim> element

This is the XML root element. All other elements fall within this element

 Attributes are:
   lp = Logical Processor Id (Used for distributed simulations only)

<topology> element

This elements contains the Node and Link elements.It describes, the co-ordinates of the canvas used for animation.

 Attributes are:
   minX = minimum X coordinate of the animation canvas
   minY = minimum Y coordinate of the animation canvas
   maxX = maximum X coordinate of the animation canvas
   maxY = maximum Y coordinate of the animation canvas

 Example:
 <topology minX = "-6.42025" minY = "-6.48444" maxX = "186.187" maxY = "188.049">

<node> element

This element describes each Node's Id and X,Y co-ordinate (position)

 Attributes are:
   lp = Logical Processor Id (Used for distributed simulations only)
   id = Node Id
   locX = X coordinate
   locY = Y coordinate
 Example: 
  <node lp = "0" id = "8" locX = "107.599" locY = "96.9366" />

<link> element

This element describes wired links between two nodes.

 Attributes are:
   fromLp = From logical processor Id  (Used for distributed simulations only)
   fromId = From Node Id (first node id)
   toLp   = To logical processor Id
   toId   = To Node Id (second node id)
 
 Example:
  <link fromLp="0" fromId="0" toLp="0" toId="1"/>

<packet> element

This element describes a packet over wired links being transmitted at some node and received at another The reception details is described in it associated rx element

 Attributes are:
   fromLp = From logical processor Id  (Used for distributed simulations only)
   fromId = Node Id transmitting the packet
   fbTx = First bit transmit time of the packet
   lbTx = Last bit transmit time of the packet
 Example: 
  <packet fromLp="0" fromId="1" fbTx="1" lbTx="1.000067199"><rx toLp="0" toId="0" fbRx="1.002" lbRx="1.002067199"/>
  Packet over wired-links from Node 1 was received at Node 0. The first bit of the packet was transmitted at  the 1th second, the last bit was transmitted at the 
  1.000067199th second of the simulation
  Node 0 received the first bit of the packet at the 1.002th second and the last bit of the packet at the 1.002067199th second of the simulation

NOTE: A packet with fromId == toId is a dummy packet used internally by the AnimationInterface.Please ignore this packet

<rx> element

This element describes the reception of a packet at a node

 Attributes are:
   toLp = To logical processor Id
   toId = Node Id receiving the packet
   fbRx = First bit Reception Time of the packet
   lbRx = Last bit Reception Time of the packet

<wpacket> element

This element describes a packet over wireless links being transmitted at some node and received at another The reception details is described in it associated rx element

 Attributes are:
   fromLp = From logical processor Id (Used in distributed simulations only)
   fromId = Node Id transmitting the packet
   fbTx = First bit transmit time of the packet
   lbTx = Last bit transmit time of the packet
   range = Range of the transmission
 Example:
  <wpacket fromLp = "0" fromId = "20" fbTx = "0.003" lbTx = "0.003254" range = "59.68176982">
  <rx toLp="0" toId="32" fbRx="0.003000198" lbRx="0.003254198"/>
  Packet over wireless-links from Node 20 was received at Node 32. The first bit of the packet was transmitted at  the 0.003th second, 
  the last bit was transmitted at the 
  0.003254 second of the simulation
  Node 0 received the first bit of the packet at the 0.003000198 second and the last bit of the packet at the 0.003254198 second of the simulation

Using the XML trace with NetAnim

  • Here is a youtube video demonstrating Animation for Wireless transmission click here
  • Here is a youtube video demonstrating Animation for Wired transmission click here


Parts of the basic-mode Animator

The basic-mode Animator will have the following buttons shown here GeneralVCR.png

  • Quit: Quits the NetAnim application
  • Concentric circles: Shows Wireless transmission as concentric circles
  • Reverse play button: Plays the animation in the reverse direction. Don't use this if "Track" button is enabled
  • Forward play button: Plays the animation in the forward direction
  • Pause button: Used to pause the animation
  • The History slider: Used to go back in simulation time History.png
  • Update rate slider: Updateperiod.png

This slider controls the interval between updating animation. If it is low, more packets will be animated, but the simulation progress will be slow

If it is high, some packets may get skipped, although the simulation may progress faster. 


Miscbuttons.png

  • Record button: WIll take snapshots of the animation at periodic intervals and store them as a collection of images under the "recordings" folder
  • Zoom-in button: Zoom into the animation
  • Zoom-out button: Zoom out
  • Reset Zoom
  • Pkt ON: If suppressed will display packet transmission. Disable this button, when you are only interested in seeing the location of the nodes (or mobility)

Shownode.png

  • Show Node Id: If enabled shows the Node Id of each node on the canvas
  • Node Id Font size: Controls the font size of the Node Id mentioned above

Using the XML trace file in NetAnim 2.0

  1. Open the XML file via "Options" menu --> "Load XML"

Using the non-XML trace file in NetAnim 1.0

  1. use the command-line
./NetAnim dumbbell-tr


F.A.Q

  • I get
/usr/bin/ld: cannot find -lsqlite3
/usr/bin/ld: cannot find -lpng14
/usr/bin/ld: cannot find -lintl
>>> Try removing the corresponding "-l" phrases from the LIBS variable in NetAnim.pro
  • I get GLib-GIO:ERROR:gdbusconnection.c:2279:initable_init: assertion failed: (connection->initialization_error == NULL)Aborted (core dumped)
>>> Don't install or run NetAnim as a root-user
  • I get
QImage: XPM pixels missing on image line 9 (possibly a C++ trigraph).
QImage: XPM pixels missing on image line 10 (possibly a C++ trigraph). 
QImage: XPM pixels missing on image line 11 (possibly a C++ trigraph).
QImage: XPM pixels missing on image line 12 (possibly a C++ trigraph).
QImage: XPM pixels missing on image line 13 (possibly a C++ trigraph).
QImage: XPM pixels missing on image line 14 (possibly a C++ trigraph)
>>> These can be ignored
  • I am unable to see any packets animated
>>> If you are using Wireless links , try using the "Track" button
>>> If you are using Wired links, try disabling the "Track" button
  • The program hangs or crashes
>>> Double-check if the "Special-rules" section has been followed
  • I get *.so not found. Try using -rpath
>>> ensure that you have set LD_LIBRARY_PATH correctly