Commits

Joshua Bonsink committed dd4ab2b

Finished documentation

Comments (0)

Files changed (1)

core/ns3/util/netanim.py

+"""
+
+This file contains a utility class to convert the generated pcap files 
+during a simulation into a usable XML file for NetAnim.
+
+"""
+
 from operator import itemgetter
+import os
+import random 
+from subprocess import check_call
+import time
 
 import ns3
 import ns
 
-import random 
 import settings
-from subprocess import check_call
-import os
-
-import time
 
 def export_to_txt(f_name, txt_f_name):
-    cmd = """tshark -o column.format:'"No.", "%%m", "Time", "%%t", "Source", "%%s", "Destination", "%%d", "srcport", "%%uS", "dstport", "%%uD", "len", "%%L", "Protocol", "%%p"' -r %s > %s""" % (f_name, txt_f_name)    
+    """Convert a pcap file to a readable txt file."""    
+    
+    cmd = """tshark -o column.format:'"No.", "%%m", "Time", "%%t",
+"Source", "%%s", "Destination", "%%d", "srcport", "%%uS", "dstport", "%%uD",
+"len", "%%L", "Protocol", "%%p"' -r %s > %s""" % (f_name, txt_f_name) 
     print('--> ', cmd)
     check_call(cmd, shell=True)
 
 def fix_pcap(f_name):
+    """Fix corrupted pcap files before converting them to txt files."""
     cmd = "pcapfix " + f_name
     print('--> ', cmd)
     check_call(cmd, shell=True)
     
 def parse_txt(f_name):    
+    """
+    
+    Read and parse a txt file containg the captured packets. The packets
+    are returned in an array.
+    
+    """
     FORMAT = dict(
         seq=(0, int),
         start_time=(1, float),
 
 class AnimationInterface():
     
+    """
+    
+    This class is created to enable the generation of an compatible
+    xml file for NetAnim.
+    
+    """
+    
     def __init__(self, fileName):
         self.fileName = fileName        
         self.topoMinX = 0
         
         self.started = False
         
-        self.startAnimation()
+        self.initializeXML()
         
-    def startAnimation(self):
+    def initializeXML(self):
+        """Inizialize the xml file."""
         self.determineTopologyDimensions()      
         self.openAnimElement()
         self.writeInformation()
         self.started = True
         
     def determineTopologyDimensions(self):
+        """
+        
+        Determine the positions of the nodes in the topology. This can be
+        improved by reading the real positions from the topology file.
+        
+        """
         nodes = ns3.NodeList.GetNNodes()
         
         for i in range(nodes):
             self.updatePosition(node)                
          
     def updatePosition(self, node):       
+        """Randomly generate node positions."""        
         x = random.uniform(self.topoMinX, self.topoMaxX)
         y = random.uniform(self.topoMinY, self.topoMaxY)
         
         self.nodeLocation.append((x, y))
         
     def openAnimElement(self, lp = 0):
+        """Write the opening anim tag into the file."""
         self.writeLine("<anim lp = \"" + str(lp) + "\" >\n")
     
     def openCloseTopology(self, minX, minY, maxX, maxY):
+        """Write the specification of the topology into the file"""
         self.writeLine("<topology minX = \"" + str(minX) + "\" minY = \"" + str(minY) + "\" maxX = \"" + str(maxX) + "\" maxY = \"" + str(maxY) + "\">\n")  
     
     def openCloseNode(self):
+        """For every node write the definition of it's position into the file."""
         nodes = ns3.NodeList.GetNNodes()
         
         for i in range(nodes):
             self.writeLine("<node id = \"" + str(ID) + "\"" + " descr=\"\"" + " locX = \"" + str(locX) + "\" locY = \"" + str(locY) + "\" />\n")
     
     def openCloseLinks(self):
+        """
+        
+        For every node find the links connected to it and write those into the file.
+        There maybe something wrong with this implementation. Since during
+        a NetAnim animation packets can travel through non-existing links.
+        
+        """
         nodes = ns3.NodeList.GetNNodes()
         
         for i in range(nodes):
 </information>\n")
         
     def pcapToXML(self):
+        """
+        
+        Convert pcap files containing the captured traffic into a xml file
+        compatible with NetAnim.
+        
+        Most pcap files generated during the simulation are corrupted. These
+        have to be fixed before converting the pcap files into txt files.
+        
+        The txt files are read and the packets are extraced and saved into
+        an array. Since there are multiple pcap files containing traffic
+        captured at different nodes, the array has to be sorted on the time. 
+        
+        A record in a pcap file only contains one time value. But the xml
+        needs four. Two times for the first bit and last bit transmission 
+        for incoming and outgoing traffic. These times are approximated
+        by increasing the one time in the pcap record by some random numbers.
+        The random numbers are based on the min/max difference of the respective
+        times in an example.
+        
+        """
         path = settings.ROOT + "/res"     
            
         for dirEntry in os.listdir(path):
         self.writeLine("</anim>")
     
     def getNodeID(self, address): 
+        """Get the ID of the node with the given ip-address"""
+        
         if '255' in address:
             return None
         
                     if str(local_addr) == address:
                         return node.GetId()
         
-        print "cannot find node with address " + address
-        
-        """    
-        value = self.nodeAddress.get(address, None)
-        
-        if value == None:
-            self.nodeAddress[address] = self.nodeCounter
-            value = self.nodeCounter
-        self.nodeCounter += 1
-        """            
+        print "cannot find node with address " + address      
+   
         return None
     
-    def writeLine(self, line):         
+    def writeLine(self, line):        
+        """Write line at the end of the xml file."""
         with open(self.fileName, 'r+U') as f:
             try:
                 f.seek(-1, 2)