|
|
| (26 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| {{TOC}} | | {{TOC}} |
|
| |
|
| NetAnim is an offline animator based on the Qt 4 toolkit. | | NetAnim is an offline animator based on the Qt toolkit. |
| It currently animates the simulation using an XML trace file collected during simulation. The first version was developed by George F Riley. NetAnim 2 and 3 are written and maintained by John Abraham. | | It animates a previously executed simulation using an XML trace file generated during a simulation. The first version was developed by George F Riley. The current version was largely developed by John Abraham. NetAnim has not been actively maintained/improved since 2017. |
| | |
|
| |
|
| [[Image:NetAnim3.png|thumb|The NetAnim GUI]] | | [[Image:NetAnim3.png|thumb|The NetAnim GUI]] |
| The current release version is 3.103 bundled with ns-3.16
| |
|
| |
| == Summary of features ==
| |
| * Animate packets over wired-links and wireless-links (Limited support for LTE traces)
| |
| * Packet timeline with regex filter on packet meta-data.
| |
| * Node position statistics with node trajectory plotting(path of a mobile node).
| |
| * Print brief packet-meta data on packets (available only from ns-3.14 onwards)
| |
|
| |
| [[File:PacketStats.png|thumb|left|Packet Statistics]][[File:trajectory.png|thumb|right|Node Trajectory]]
| |
| [[File:Dumbbell.png|thumb|center|Dumbbell]]
| |
| [[File:Wifi2.png|thumb|left|Wifi Beacon]][[File:TCP.png|thumb|right|TCP flags]][[File:Wifi1.png|thumb|center|Wifi Assoc]]
| |
|
| |
| == New Features in NetAnim 3.103 ==
| |
| [[File:IP.png|thumb|left|IPv4 Address]][[File:MAC.png|thumb|left|MAC Address]][[File:LinkDescription.png|thumb|left|Color,Link Description]][[File:NodeColorVisibility.png|thumb|left|Hidden node]]
| |
|
| |
| [http://code.nsnam.org/netanim/file/4990cf2177a1/RELEASE_NOTES 3.103 Release Notes (click here)]
| |
| * Support for setting the following attributes before simulation and modifying them during simulation
| |
| # P2p Link Description
| |
| # Color of the nodes
| |
| # Visibility of the nodes
| |
| # Description of the nodes (Default is Node ID)
| |
|
| |
| * Built-in support for printing the IP and MAC at the interfaces.
| |
| Currently if there is a text overlap, the IP/MAC text will be positioned outside the scene and connected by light blue line, to prevent clutter.
| |
| * XML Tags for packet and wpacket now support "p" and "wp" respectively (instead of "packet" and "wpacket"), to save disk-space.
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
| .
| |
|
| |
| == Prerequisites ==
| |
| # mercurial
| |
| # QT4 development packages (recommended version 4.7)
| |
|
| |
| === Debian/Ubuntu Linux distribution:===
| |
| # apt-get install mercurial
| |
| # apt-get install qt4-dev-tools
| |
|
| |
| === Red Hat/Fedora based distribution:===
| |
| # yum install mercurial
| |
| # yum install qt4
| |
| # yum install qt4-devel
| |
|
| |
| === Mac/OSX ===
| |
| # mercurial
| |
| # Qt4 : Install Qt4 (including Qt Creator if possible) from http://qt.nokia.com/downloads/
| |
|
| |
| == Downloading NetAnim ==
| |
| * NetAnim 3.0:
| |
|
| |
| hg clone http://code.nsnam.org/netanim
| |
|
| |
| * NetAnim 2.0:
| |
| Go to this link [[NetAnim2]]
| |
|
| |
| * NetAnim 1.0:
| |
| Go to this link [[NetAnim 1.0]]
| |
|
| |
| == Building NetAnim==
| |
| 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 (For MAC Users: qmake -spec macx-g++ NetAnim.pro)
| |
| make
| |
|
| |
| '''Note: qmake could be "qmake-qt4" in some systems
| |
| '''
| |
|
| |
| This should create an executable named "NetAnim" in the same directory. To start the application just type "./NetAnim"
| |
|
| |
| == Using NetAnim ==
| |
| Using NetAnim is a two-step process.
| |
|
| |
| Step 1: Generate the animation XML trace file during simulation using "ns3::AnimationInterface" in the ns-3 code base
| |
|
| |
| Step 2: Load the XML trace file generated in Step 1 with the offline animator (NetAnim).
| |
|
| |
| === 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
| |
|
| |
| ==== Mandatory and optional set of steps ====
| |
| Here is the recommended set of steps for generating XML Animation traces.They must be applied just 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) '''
| |
|
| |
| ===== Mandatory =====
| |
| 0. Ensure that your wscript includes the "netanim" module. Example as in: src/netanim/examples/wscript.
| |
| 1. Also include the header [#include "ns3/netanim-module.h"] in your test program
| |
| 2. Add the statement "AnimationInterface anim ("animation.xml");" before Simulator::Run()
| |
|
| |
| ===== Optional =====
| |
| 3. anim.SetMobilityPollInterval (Seconds (1));[OPTIONAL]
| |
| 4. anim.SetConstantPosition (Ptr< Node > n, double x, double y); [OPTIONAL]
| |
| 5. anim.EnablePacketMetadata (true); [OPTIONAL] available only on ns-3-dev and from ns-3.14. Used to show packet meta data on the packet statistics and packet animation
| |
|
| |
| Try to keep the above as close as possible to the "Simulator::Run()" statement
| |
|
| |
| ==== Running an Example File to generate XML trace 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. AnimationInterface anim ("anim.xml");
| |
| 2. anim.SetConstantPosition (n, 100, 200);
| |
|
| |
| where
| |
|
| |
| 1. Get a Ptr to Node from the node container
| |
| 2. Instantiate an object of type AnimationInterface
| |
| 3. Set a node pointed to by "n" to the x-coordinate of 100 and y-coordinate of 200
| |
|
| |
| ===== 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
| |
|
| |
| 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.
| |
|
| |
| === Using the XML trace with NetAnim ===
| |
| Run NetAnim and click the file-open button on the top-left hand corner and select the XML trace file that was discussed in the previous sections
| |
|
| |
| * Here is a youtube video demonstrating how to load the XML file [http://www.youtube.com/watch?v=tz_hUuNwFDs click here]
| |
| * Here is a youtube video demonstrating Animation for Wired transmission [http://www.youtube.com/watch?v=ZQ2yMKZRAfM click here]
| |
| * Here is a youtube video demonstrating Animation for Wireless transmission [http://www.youtube.com/watch?v=-dZcMhdULmw click here]
| |
| * Here is a youtube video demonstrating Animation for Node trajectory [http://www.youtube.com/watch?v=jYRxDzeWxkA click here]
| |
|
| |
| ==== The update rate slider ====
| |
|
| |
| * Update rate slider: [[File:Updaterate.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>
| |
|
| |
| NetAnim uses the first/last bit transmit and receive time to show animations accurately. So if you can pick up your physical cable (assume it is transparent) and can see packets flowing then you can see it with NetAnim as well. But often, the low application data-rate or high bandwidth/low propagation delay links may make it impossible to see packets flowing because they travel really fast.
| |
| In such situations (especially wireless and CSMA) use the "update rate interval" slider to slow down the animation. Also toggle the precision button, to downgrade the precision for CSMA links
| |
|
| |
| == Understanding the XML trace file format ==
| |
| === 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:
| | == NetAnim Versions == |
| toLp = To logical processor Id
| | * NetAnim 3.109 is compatible with ns-3.38 through the current version. |
| toId = Node Id receiving the packet
| | ** 3.109 is a minor release that removes Qt4 support and fixes some compiler warnings |
| fbRx = First bit Reception Time of the packet
| |
| lbRx = Last bit Reception Time of the packet
| |
|
| |
|
| ==== <wpacket> element ====
| | * [[ NetAnim 3.108 ]] was first bundled with ns-3.27 and is compatible through ns-3.37 (and even ns-3.38) |
| 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:
| | * [[ NetAnim 3.107 ]] |
| 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:
| | * [[ NetAnim 3.106 ]] |
| <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
| |
|
| |
|
| == F.A.Q ==
| | * [[ NetAnim 3.105 ]] was released with ns-3.20 |
| * I can see the nodes and topology but cannot see packets animated | |
| >> NetAnim uses the first/last bit transmit and receive time to show animations accurately. So if you can pick up your physical cable (assume it is transparent) and can see packets flowing then you can see it with NetAnim as well. But often, the low application data-rate or high bandwidth/low propagation delay links may make it impossible to see packets flowing because they travel really fast.
| |
| In such situations (especially wireless and CSMA) use the "update rate interval" slider to slow down the animation. Also toggle the precision button, to downgrade the precision for CSMA links
| |
| * I get /
| |
| home/wimax/ns-allinone-3.12.1/ns-3.12.1/build/../examples/routing/manet-routing-compare.cc:366: undefined reference to `ns3::AnimationInterface::AnimationInterface(std::basic_string<char, std::char_traits<char>, std::allocator<char> >, bool)'
| |
| /home/wimax/ns-allinone-3.12.1/ns-3.12.1/build/../examples/routing/manet-routing-compare.cc:366: undefined reference to `ns3::AnimationInterface::~AnimationInterface()'
| |
| /home/wimax/ns-allinone-3.12.1/ns-3.12.1/build/../examples/routing/manet-routing-compare.cc:371: undefined reference to `ns3::AnimationInterface::~AnimationInterface()'
| |
| /home/wimax/ns-allinone-3.12.1/ns-3.12.1/build/../examples/routing/manet-routing-compare.cc:371: undefined reference to `ns3::AnimationInterface::~AnimationInterface()'
| |
| collect2: ld returned 1 exit status
| |
| Waf: Leaving directory `/home/wimax/ns-allinone-3.12.1/ns-3.12.1/build'
| |
| Build failed: -> task failed (err #1):
| |
| {task: cxx_link manet-routing-compare_9.o -> manet-routing-compare}
| |
|
| |
|
| >> Add 'netanim' to your wscript
| | * [[ NetAnim 3.104 ]] was released with ns-3.19 |
