50 NetAnim is a stand-alone program which uses the custom trace files generated by

    16 NetAnim is a standalone, Qt4-based software executable that uses a trace file generated during 

    51 the animation interface to graphically display the simulation. NetAnim is based

    17 an |ns-3| simulation to display the topology and animate the packet flow between nodes.

    52 on the multi-platform `Qt4 GUI toolkit <http://qt.nokia.com/>`_.

    53 A screenshot of the NetAnim GUI is shown below.

    61 The NetAnim GUI provides play, pause, and record buttons. Play and pause start

    25 Methodology

    62 and stop the simulation. The record button starts a series of screenshots of the

    26 ===========

    63 animator, which are written to the directory in which the trace file was run.

    27 The class ns3::AnimationInterface is responsible for the creation the trace XML file.

    64 Two slider bars also exist. The top slider provides a "seek" functionality,

    28 AnimationInterface uses the tracing infrastructure to track packet flows between nodes.

    65 which allows a user to skip to any moment in the simulation. The bottom slider

    29 AnimationInterface registers itself as a trace hook for tx and rx events before the simulation

    66 changes the granularity of the time step for the animation. Finally, there is a

    30 begins. When a packet is scheduled for transmission or reception, the corresponding tx and rx 

    67 quit button to stop the simulation and quit the animator.

    31 trace hooks in AnimationInterface are called. When the rx hooks are called, AnimationInterface will be aware of the two endpoints between which a packet has flowed, and adds this information

    68 

    32 to the trace file, in XML format along with the corresponding tx and rx timestamps. The XML format 

    69 For detailed instructions on installing "NetAnim" and loading the XML trace file 

    33 will be discussed in a later section. It is important to note that AnimationInterface records a 

    34 packet only if the rx trace hooks are called. Every tx event must be matched by an rx event.

    35 

    36 Downloading NetAnim

    37 ===================

    38 If NetAnim is not already available in the |ns-3| package you downloaded, you can do the following

    39 

    40 Please ensure that you have installed mercurial.

    41 The latest version of NetAnim can be downloaded using mercurial with the following command

    42 ::

    43   hg clone http://code.nsnam.org/jabraham3/netanim

    44 

    45 

    46 Building NetAnim

    47 ================

    48 Prerequisites

    49 ~~~~~~~~~~~~~

    50 Qt4 (4.7 and over) is required to build NetAnim. This can be obtained using the following ways:

    51 

    52 For Debian/Ubuntu Linux distributions

    53 ::

    54     apt-get install qt4-dev-tools

    55 

    56 For Red Hat/Fedora based distribution

    57 ::

    58     yum install qt4

    59     yum install qt4-devel

    60 

    61 For Mac/OSX

    62 ::

    63     http://qt.nokia.com/downloads/

    64 

    65 Build steps

    66 ~~~~~~~~~~~

    67 

    68 To build NetAnim use the following commands

    69 ::

    70   cd netanim

    71   make clean

    72   qmake NetAnim.pro  (For MAC Users: qmake -spec macx-g++ NetAnim.pro)

    73   make

    74 

    75 

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

    77 

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

    79 ::

    80  john@john-VirtualBox:~/netanim$ ls -l NetAnim

    81  -rwxr-xr-x 1 john john 390395 2012-05-22 08:32 NetAnim

    82 

    83 

    84 Usage

    85 =====

    86 Using NetAnim is a two-step process

    87 

    88 Step 1: Generate the animation XML trace file during simulation using "ns3::AnimationInterface" 

    89         in the |ns-3| code base.

    90 Step 2: Load the XML trace file generated in Step 1 with the offline Qt4-based animator (NetAnim).

    91 

    92 

    93 Step 1: Generate XML animation trace file

    94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    95 The class "AnimationInterface" under "src/netanim" uses underlying |ns3| trace sources 

    96 to construct a timestamped ASCII file in XML format.

    97 

    98 Examples are found under src/netanim/examples

    99 Example

   100 ::

   101   ./waf -d debug configure --enable-examples

   102   ./waf --run "dumbbell-animation"

   103 The above will create an XML file dumbbell-animation.xml

   104 

   105 Mandatory

   106 #########

   107 

   108 1. Ensure that your program's wscript includes the "netanim" module. An example of such a wscript is at src/netanim/examples/wscript. 

   109 2. Include the header [#include "ns3/netanim-module.h"] in your test program

   110 3. Add the statement

   111 ::

   112   AnimationInterface anim ("animation.xml"); 

   113     where "animation.xml" is any arbitrary filename

   114 

   115 

   116 [for versions before ns-3.13 you also have to use the line "anim.SetXMLOutput() to set the XML mode and also use anim.StartAnimation();]

   117 

   118 

   119 Optional

   120 ########

   121 The following are optional but useful steps

   122 ::

   123   1.anim.SetMobilityPollInterval (Seconds (1));

   124 

   125 AnimationInterface records the position of all nodes every 250 ms by default. The statement above sets 

   126 the periodic interval at which AnimationInterface records the position of all nodes. If the nodes are 

   127 expected to move very little, it is useful to set a high mobility interval to avoid large XML files.

   128 ::

   129   2. anim.SetConstantPosition (Ptr< Node > n, double x, double y);

   130 

   131 AnimationInterface requires that the position of all nodes be set. In ns-3 this is done by setting an associated MobilityModel. "SetConstantPosition" is a quick way to set the x-y coordinates of a node which is stationary.

   132 ::

   133   3. anim.SetStartTime (Seconds(150)); and anim.SetStopTime (Seconds(150));

   134 

   135 AnimationInterface can generate large XML files. The above statements restricts the window between which AnimationInterface does tracing. Restricting the window serves to focus only on relevant portions of the simulation and creating manageably small XML files

   136 ::

   137   4. AnimationInterface anim ("animation.xml", 50000);

   138 

   139 Using the above constructor ensures that each animation XML trace file has only 50000 packets. For example, if AnimationInterface captures 150000 packets, using the above constructor splits the capture into 3 files

   140 

   141 animation.xml - containing the packet range 1-50000

   142 

   143 animation.xml-1 - containing the packet range 50001-100000 

   144 

   145 animation.xml-2 - containing the packet range 100001-150000 

   146 ::

   147   5. anim.EnablePacketMetadata (true);

   148 

   149 With the above statement, AnimationInterface records the meta-data of each packet in the xml trace file. Metadata can be used by NetAnim to provide better statistics and filter, along with providing some brief information about the packet such as TCP sequence number or source & destination IP address during packet animation.

   150 CAUTION: Enabling this feature will result in larger XML trace files.

   151 Please do NOT enable this feature when using Wimax links.

   152 

   153 Step 2: Loading the XML in NetAnim

   154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   155 

   156 1. Assuming NetAnim was built, use the command "./NetAnim" to launch NetAnim. Please review the section "Building NetAnim" if NetAnim is not available.

   157 2. When NetAnim is opened, click on the File open button at the top-left corner, select the XML file generated during Step 1.

   158 3. Hit the green play button to begin animation.

   159 

   160 Essential settings of NetAnim

   161 =============================

   162 

   163 Persist combobox

   164 ~~~~~~~~~~~~~~~~

   165 When packets are transmitted and received very quickly, they can be almost invisible. The persist time setting

   166 allows the user to control the duration for which a packet should be visible on the animation canvas. 

   167 

   168 Fast-forward button

   169 ~~~~~~~~~~~~~~~~~~~

   170 This setting is ON by default. With this setting ON, the animation progresses in simulation time rather than

   171 wall-clock time. This means, if there were three intervals of time, A to B , B to C and C to D, and if all packets are transmitted and received only in the intervals A to B and C to D , while B to C is a 

   172 20 second idle period with no packet tranmission or reception or node mobility, NetAnim will skip over B to C, instantly without waiting for 20 seconds. The user can turn OFF Fast-forward when they want the animation to proceed like wall-clock time. 

   173 

   174 Update-interval slider

   175 ~~~~~~~~~~~~~~~~~~~~~~

   176 If Fast-forward (discussed above) is turned OFF, the update-interval slider controls the rate at which 

   177 NetAnim refreshes the canvas screen.

   178 

   179 Precision button

   180 ~~~~~~~~~~~~~~~~

   181 This setting is turned OFF by default. When using purely point-to-point topologies precision can be turned ON, 

   182 to distinguish between small and large packets travelling on a link. For instance a small packet such as a 

   183 TCP ACK segment occupies only a small fraction of the length of the link , which provides a realistic animation

   184 CAUTION: Precision should be turned ON only for completely point-to-point topologies.

   185 

   186 Sim-time spinbox

   187 ~~~~~~~~~~~~~~~~

   188 The Sim-time spinbox can be used to go forward or backward in simulation time.

   189 

   190 

   191 Parts of the XML

   192 ================

   193 The XML trace files has the following main sections

   194 

   195 1. Topology

   196 

   197    - Nodes

   198    - Links

   199 2. packets (packets over wired-links)

   200 3. wpackets (packets over wireless-links)

   201 

   202 XML tags

   203 ~~~~~~~~

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

   205 

   206 1. <anim> element

   207 

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

   209   Attributes are:

   210   lp = Logical Processor Id (Used for distributed simulations only)

   211 

   212 2. <topology> element

   213 

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

   215    Attributes are:

   216    minX = minimum X coordinate of the animation canvas

   217    minY = minimum Y coordinate of the animation canvas

   218    maxX = maximum X coordinate of the animation canvas

   219    maxY = maximum Y coordinate of the animation canvas

   220 

   221 Example

   222 ::

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

   224 

   225 3. <node> element

   226 

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

   228   Attributes are:

   229    id = Node Id

   230    locX = X coordinate

   231    locY = Y coordinate

   232 

   233 Example

   234 ::

   235   <node id = "8" locX = "107.599" locY = "96.9366" />

   236 

   237 4. <link> element

   238 

   239 This element describes wired links between two nodes.

   240  Attributes are:

   241    fromId = From Node Id (first node id)

   242    toId   = To Node Id (second node id)

   243  

   244 Example

   245 ::

   246   <link fromId="0" toId="1"/>

   247 

   248 5. <packet> element

   249 

   250 This element describes a packet over wired links being transmitted at some node and received at another. The reception details are described in its associated rx element

   251  Attributes are:

   252    fromId = Node Id transmitting the packet

   253    fbTx = First bit transmit time of the packet

   254    lbTx = Last bit transmit time of the packet

   255 

   256 Example

   257 ::

   258   <packet fromId="1" fbTx="1" lbTx="1.000067199"><rx toLp="0" toId="0" fbRx="1.002" lbRx="1.002067199"/>

   259 

   260 A 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

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

   262 

   263 6. <rx> element

   264 

   265 This element describes the reception of a packet at a node

   266  Attributes are:

   267    toId = Node Id receiving the packet

   268    fbRx = First bit Reception Time of the packet

   269    lbRx = Last bit Reception Time of the packet

   270 

   271 7. <wpacket> element

   272 

   273 This element describes a packet over wireless links being transmitted at some node and received at another. The reception details are described in its associated rx element

   274  Attributes are:

   275    fromId = Node Id transmitting the packet

   276    fbTx = First bit transmit time of the packet

   277    lbTx = Last bit transmit time of the packet

   278    range = Range of the transmission

   279 

   280 Example

   281 ::

   282   <wpacket fromId = "20" fbTx = "0.003" lbTx = "0.003254" range = "59.68176982">

   283   <rx toLp="0" toId="32" fbRx="0.003000198" lbRx="0.003254198"/>

   284 

   285 A 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

   286 

   287 Wiki

   288 ====

   289 For detailed instructions on installing "NetAnim", F.A.Qs and loading the XML trace file