NetAnim2: Difference between revisions

Revision as of 13:06, 26 August 2011

NetAnim is an animator based on the multi-platform QT4 GUI 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

The NetAnim GUI

Prerequisites

mercurial
QT4 development packages
xerces-c++ development packages

Debian/Ubuntu Linux distribution:

apt-get install mercurial
apt-get install qt4-dev-tools
apt-get install libxerces-c-dev

Red Hat/Fedora based distribution:

yum install mercurial
yum install qt4
yum install qt4-devel
yum install xerces-c
yum install xerces-c-devel

Mac/OSX

Qt4 : Install the binaries (including Qt Creator) from http://qt.nokia.com/downloads/
Xerces-c++: http://xerces.apache.org/xerces-c/download.cgi

Downloading NetAnim

NetAnim 2.0:

(Preferred way): hg clone http://code.nsnam.org/jabraham3/netanim

or

via http click here

NetAnim 1.0:

click here. Untar it using:tar -xzvf NetAnim.tar.gz

Building NetAnim (Basic-Mode)

NetAnim uses a QT4 build tool called qmake.

In General

cd netanim
qmake NetAnim.pro
make

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

On Mac OS X

The preferred Qt 4 version is Qt 4.7. Using "Qt Creator" to build NetAnim is usually fool-proof

cd netanim
/usr/local/Trolltech/Qt-4.x.y/bin/qmake NetAnim.pro
make

Note that above, the x.y is the specific version of Qt4 you are running.

If the above steps do not work , please see the suggestion below from a user

1. Download Qt libraries for Mac from the page
   [http://qt.nokia.com/downloads/qt-for-open-source-cpp-development-on-mac-os-x]
    for example: [http://get.qt.nokia.com/qt/source/qt-mac-opensource-4.7.2-debug-libs.dmg]
2. Download NetAnim from [http://www.nsnam.org/~jpelkey3/NetAnim.tar.gz]
3. $tar -xzvf NetAnim.tar.gz
4. $cd NetAnim
5. $/usr/bin/qmake-4.7 NetAnim.pro
    This will create xcode project NetAnim.xcodeproj
6. Open NetAnim.xcodeproj with xcode and build.You will get NetAnim executable.

Special note to Mac OS X Lion users as of July 30, 2011: In the latest build of Qt libraries, namely, http://get.qt.nokia.com/qt/source/qt-mac-opensource-4.7.3.dmg, qmake generates Xcode .pbproj file instead of Makefile by default. The Xcode file, however, is incompatible to the Xcode tools (version 4.1) for Lion. To get the Makefile output from qmake, one can try the following after installed qt-mac-opensource-4.7.3.dmg:

 $ cd /usr/local/Qt4.7/mkspecs/
 $ sudo rm default
 $ sudo ln -s macx-g++ default

Then, qmake will use the GCC template instead of Xcode template for building Qt projects. You can then build NetAnim as usual, namely,

 $ cd netanim
 $ qmake
 $ make

On Ubuntu/Debian

cd netanim
qmake-qt4 NetAnim.pro
make

Feature-set in NetAnim 2.0

Basic
1. Read offline XML trace file generated by ns-3's AnimationInterface
2. Ability to track Wired & Wireless transmission (LTE not yet supported)
3. Any node having a mobility model can be seen on the Animation.
4. Track mobility of nodes
5. Record button to take periodic snapshots of the Animation
6. Display Node Id on the Animation canvas, with zoom-in, zoom-out etc
Advanced (Requires integration with ns-3 libraries.Not yet completely implemented)
1. Plotting the animation while the simulation is running
2. Logging statistics to select Logging Components individually and display them while the simulation is running
3. Routing statistics to print Routing Tables and other Ipv4 statistics such as Tx,Rx,Drop counters,Interface addresses while the simulation is running
Feature removed
1. 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

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.

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 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)

 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 also 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 no polling occurs).
 5. Start recording traces

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
1. Nodes
2. 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 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

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
Track button:

  Overrides the update interval slider logic to avoid skipping over animating packets that fall within the Update interval.
This is helpful when you want to animate  wireless transmissions (which have extremely low propagation delay) which often get skipped during animation 
because the update interval is usually higher than the propagation delay in wireless.It is recommended to disable the Track button when animating over wired links

Pause button: Used to pause the animation

The History slider: Used to go back in simulation time

Update rate slider:

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.

Due to the skipping of packets, it is possible that Wireless transmissions may get skipped. Please enable the "Track" button when such a situation occurs.

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)

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

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

Using the non-XML trace file in NetAnim 1.0

use the command-line

./NetAnim dumbbell-tr

Building NetAnim (Advanced-mode)

To enable NetAnim's advanced-mode features, the ns-3 libraries need to be integrated with NetAnim. See this youtube-video for a glance at the new features

Summary of steps

build ns-3 with the --enable-static option. This should generate static archive libraries under "build/debug"
Run "create_lib_ns3" in the tools folder of NetAnim to create a monolithic ns-3 library
Edit NetAnim.pro to enable ns-3 features
Add your test to ns3test.cpp
Rebuild NetAnim

Detailed steps follow

Build ns-3 modular libraries

Linux

Use the following steps to build ns-3 static modular libraries for OSX (Mac)

hg clone http://code.nsnam.org/ns-3-dev
cd ns-3-dev
./waf -d debug configure
./waf

Check if the libraries got built

Mac (OSX)

Use the following steps to build ns-3 static modular libraries for OSX (Mac)

hg clone http://code.nsnam.org/ns-3-dev
cd ns-3-dev
./waf -d debug configure --enable-examples --enable-tests --enable-static
./waf

Check if the libraries got built

John-Abraham:ns-3-dev john$ pwd
/Users/john/ns-3/animqt4/ns-3-dev
John-Abrahams:ns-3-dev john$ ls build/debug/*.a
build/debug/libns3-aodv.a			build/debug/libns3-lte.a			build/debug/libns3-spectrum.a 
build/debug/libns3-applications.a		build/debug/libns3-mesh.a			build/debug/libns3-stats.a 
build/debug/libns3-bridge.a			build/debug/libns3-mobility.a			build/debug/libns3-tools.a
build/debug/libns3-config-store.a		build/debug/libns3-mpi.a			build/debug/libns3-topology-read.a
build/debug/libns3-core.a			build/debug/libns3-netanim.a			build/debug/libns3-uan.a
build/debug/libns3-csma-layout.a		build/debug/libns3-network.a			build/debug/libns3-virtual-net-device.a
build/debug/libns3-csma.a			build/debug/libns3-nix-vector-routing.a		build/debug/libns3-visualizer.a
build/debug/libns3-dsdv.a			build/debug/libns3-olsr.a			build/debug/libns3-wifi.a
build/debug/libns3-energy.a			build/debug/libns3-point-to-point-layout.a	build/debug/libns3-wimax.a
build/debug/libns3-flow-monitor.a		build/debug/libns3-point-to-point.a
build/debug/libns3-internet.a			build/debug/libns3-propagation.a

Create ns-3 monolithic library

cd into the tools folder of NetAnim. Execute the "create_lib_ns3" script by providing it the path to the modular ns-3 libraries generated above

John-Abrahams-MacBook-Pro:netanim john$ pwd
/Users/john/netanim25/netanim
John-Abrahams-MacBook-Pro:netanim john$ 
John-Abrahams-MacBook-Pro:netanim john$ cd tools/
John-Abrahams-MacBook-Pro:tools john$ ./create_lib_ns3 /Users/john/ns-3/animqt4/ns-3-dev/build/debug/

You might get something like

Path to libs: /Users/john/ns-3/animqt4/ns-3-dev/build/debug/
Clean external libs directory
rm: ../external_libs/*.a: No such file or directory
/Users/john/ns-3/animqt4/ns-3-dev/build/debug//libns3-aodv.a
Extracting: /Users/john/ns-3/animqt4/ns-3-dev/build/debug//libns3-aodv.a to  ../external_libs
/Users/john/ns-3/animqt4/ns-3-dev/build/debug//libns3-applications.a
Extracting: /Users/john/ns-3/animqt4/ns-3-dev/build/debug//libns3-applications.a to  ../external_libs
.....
Creating monolithic ns-3 library
/usr/bin/ranlib: file: libns3.a(dummy-file-for-static-builds_378.o) has no symbols
Library creation complete

This creates the ns-3 monolithic library at

John-Abrahams-MacBook-Pro:netanim john$ ls external_libs/*.a 
external_libs/libns3.a

Edit NetAnim.pro to enable Advanced-mode

This is trickiest part By default the NetAnim.pro contains the following

######### NS-3 related
#DEFINES += WITH_NS3
#INCLUDEPATH += /Users/john/ns-3/animqt4/ns-3-dev/build/debug
#LIBS += external_libs/libns3.a
#LIBS += -l sqlite3 -l xml2 -L/opt/local/lib -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lpangocairo-1.0 -lXext -lXrender -lXinerama -lXi -lXrandr -lXcursor -lXcomposite -lXdamage - lgdk_pixbuf-2.0 -lpangoft2-1.0 -lgio-2.0 -lXfixes -lcairo -lX11 -lpng14 -lpango-1.0 -lm -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lglib-2.0 -lintl
#DEFINES += _DEBUG
#DEFINES +=  NS3_ASSERT_ENABLE
#DEFINES +=  NS3_LOG_ENABLE

Uncomment the above to look like

######### NS-3 related
DEFINES += WITH_NS3 
INCLUDEPATH += /Users/john/ns-3/animqt4/ns-3-dev/build/debug
LIBS += external_libs/libns3.a
LIBS += -l sqlite3 -l xml2 -L/opt/local/lib -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lpangocairo-1.0 -lXext -lXrender -lXinerama -lXi -lXrandr -lXcursor -lXcomposite -lXdamage - lgdk_pixbuf-2.0 -lpangoft2-1.0 -lgio-2.0 -lXfixes -lcairo -lX11 -lpng14 -lpango-1.0 -lm -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lglib-2.0 -lintl
DEFINES += _DEBUG
DEFINES +=  NS3_ASSERT_ENABLE 
DEFINES +=  NS3_LOG_ENABLE

where

INCLUDEPATH is the path to the debug folder of ns-3 (after generating the static libraries)

where the line

 LIBS += -l sqlite3 -l xml2 -L/opt/local/lib -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lpangocairo-1.0 -lXext -lXrender -lXinerama -lXi -lXrandr -lXcursor -lXcomposite -lXdamage - lgdk_pixbuf-2.0 -lpangoft2-1.0 -lgio-2.0 -lXfixes -lcairo -lX11 -lpng14 -lpango-1.0 -lm -lfreetype -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lgthread-2.0 -lglib-2.0 -lintl

indicates the libraries used to build the ns-3 static libraries. This line can vary from machine to machine, depending on how you built ns-3. If you don't include all the relevant libraries you might get several linker errors stating "Undefined reference to symbol" The correct list of libs for your case can be obtained by your config logs in the ns-3 build directory

John-Abrahams-MacBook-Pro:ns-3-dev john$ pwd
/Users/john/ns-3/animqt4/ns-3-dev
John-Abrahams-MacBook-Pro:ns-3-dev john$ ls build/config.log 
build/config.log

In "config.log" search for phrases that include "-l " for example

-L/opt/local/lib -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lpangocairo-1.0 -lXext -lXrender -lXinerama -lXi -lXrandr -lXcursor

based on your build of ns-3, you may have to add the required " -l " libraries to the LIBS variable of NetAnim.pro

A Test Run

Assuming all of the above steps were done correctly , go to the netanim folder and build NetAnim like so

make clean
qmake NetAnim.pro
make
./NetAnim

If the above went well, the NetAnim advanced-mode should be presented like the below image , with "Logging" and "Routing" tabs etc

Adding your own tests

NetAnim comes with a default example in the "ns3test" folder in the file "ns3test.cpp". To run an ns-3 example within NetAnim the following must be considered

NetAnim uses the namespace "netanim".
Your program must not include "Simulator::Run" and "Simulator::Destroy" (NetAnim will do that for you)
Your program must not include any "ns3::AnimationInterface" objects (NetAnim will take care of setting up the Animation Interface)
Your program must replace the "main" function with "Simulation::ConfigureSimulation" as shown in the example "ns3test.cpp"
Your program must include the Simulator::Stop(Time_t) function to indicate when the Simulation should stop. Without this, the simulation may run indefinitely.

IMPORTANT: NetAnim has its own definition of "Node" and "Packet" so if you use Node and Packet in your program make sure you have the proper name resolution such as

netanim::Node n
ns3::Node n
netanim::Packet
ns3::Packet

Your example code must use the statement

using namespace netanim

as shown in the example in "ns3test.cpp"

Advanced-mode Animation

Press the "Offline" button to move to "Online" mode. Hit play as usual. Don't forget to remove "Track" for Wired animation.

Advanced-mode Logging

Here you can log components separately. More than one component can be added using the "+" and "-" button

Advanced-mode L3/Routing stats

This tab records commonly used stats such as "Routing-table", Tx,Rx,Drop Counters, list of IP addresses of a node. It also has the logtofile button, which can be used to log the stats to the disk under the "logs" folder We have the option of polling the stats per Simulation Time or Real time.

As shown below before simulation begins, NetAnim will provide a scrollable list of buttons for each node Id. Toggling each of these buttons monitors the l3 stats for a node selectively.

F.A.Q

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

@@ Line 393: / Line 393: @@
 ==== Create ns-3 monolithic library ====
-cd into the tools folder of NetAnim. Execute the "create_lib_ns3" script by providing it the path to the modular ns-3 static libraries generated above
+cd into the tools folder of NetAnim. Execute the "create_lib_ns3" script by providing it the path to the modular ns-3 libraries generated above
   John-Abrahams-MacBook-Pro:netanim john$ pwd

NetAnim2: Difference between revisions

Revision as of 13:06, 26 August 2011

Prerequisites

Debian/Ubuntu Linux distribution:

Red Hat/Fedora based distribution:

Mac/OSX

Downloading NetAnim

Building NetAnim (Basic-Mode)

In General

On Mac OS X

On Ubuntu/Debian

Feature-set in NetAnim 2.0

Feature-set in NetAnim 1.0

Using ns3::AnimationInterface to generate Animation trace files

Recommended set of steps

Running an Example File

Setting the location of nodes

For stationary nodes:

For mobile nodes

Understanding the XML trace file format

Parts of the XML

XML tags

<anim> element

<topology> element

<node> element

<link> element

<packet> element

<rx> element

<wpacket> element

Using the XML trace with NetAnim

Parts of the basic-mode Animator

Using the XML trace file in NetAnim 2.0

Using the non-XML trace file in NetAnim 1.0

Building NetAnim (Advanced-mode)

Summary of steps

Build ns-3 modular libraries

Linux

Mac (OSX)

Create ns-3 monolithic library

Edit NetAnim.pro to enable Advanced-mode

A Test Run

Adding your own tests

Advanced-mode Animation

Advanced-mode Logging

Advanced-mode L3/Routing stats

F.A.Q

Navigation menu

Search