animation-interface.h

Go to the documentation of this file.

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation;
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Author: George F. Riley<riley@ece.gatech.edu>
 * Author: John Abraham <john.abraham@gatech.edu>
 * Contributions: Eugene Kalishenko <ydginster@gmail.com> (Open Source and Linux Laboratory http://dev.osll.ru/)
 */

// Interface between ns3 and the network animator

#ifndef ANIMATION_INTERFACE__H
#define ANIMATION_INTERFACE__H

#include <string>
#include <cstdio>
#include <map>

#include "ns3/ptr.h"
#include "ns3/net-device.h"
#include "ns3/node-container.h"
#include "ns3/nstime.h"
#include "ns3/log.h"
#include "ns3/node-list.h"
#include "ns3/random-variable-stream.h"
#include "ns3/simulator.h"
#include "ns3/config.h"
#include "ns3/mac48-address.h"
#include "ns3/lte-ue-net-device.h"
#include "ns3/lte-enb-net-device.h"
#include "ns3/uan-phy-gen.h"
#include "ns3/wifi-phy.h"
#include "ns3/rectangle.h"
#include "ns3/ipv4.h"
#include "ns3/ipv4-l3-protocol.h"
#include "ns3/wifi-phy.h"

namespace ns3 {

#define MAX_PKTS_PER_TRACE_FILE 100000
#define PURGE_INTERVAL 5
#define NETANIM_VERSION "netanim-3.108"
#define CHECK_STARTED_INTIMEWINDOW {if (!m_started || !IsInTimeWindow ()) {return; }}
#define CHECK_STARTED_INTIMEWINDOW_TRACKPACKETS {if (!m_started || !IsInTimeWindow () || !m_trackPackets) {return; }}


struct NodeSize;
class WifiPsdu;

class AnimationInterface
{
public:
  AnimationInterface (const std::string filename);

  typedef enum
  {
    UINT32_COUNTER,
    DOUBLE_COUNTER
  } CounterType;

  typedef void (*AnimWriteCallback)(const char * str);

  ~AnimationInterface ();

  void EnableIpv4L3ProtocolCounters (Time startTime, Time stopTime, Time pollInterval = Seconds (1));

  void EnableQueueCounters (Time startTime, Time stopTime, Time pollInterval = Seconds (1));

  void EnableWifiMacCounters (Time startTime, Time stopTime, Time pollInterval = Seconds (1));

  void EnableWifiPhyCounters (Time startTime, Time stopTime, Time pollInterval = Seconds (1));

  AnimationInterface & EnableIpv4RouteTracking (std::string fileName, Time startTime, Time stopTime, Time pollInterval = Seconds (5));

  AnimationInterface & EnableIpv4RouteTracking (std::string fileName, Time startTime, Time stopTime, NodeContainer nc, Time pollInterval = Seconds (5));

  static bool IsInitialized (void);

  void SetStartTime (Time t);

  void SetStopTime (Time t);

  void SetMaxPktsPerTraceFile (uint64_t maxPktsPerFile);

  void SetMobilityPollInterval (Time t);

  void SetAnimWriteCallback (AnimWriteCallback cb);

  void ResetAnimWriteCallback ();

  static void SetConstantPosition (Ptr <Node> n, double x, double y, double z = 0);

  void UpdateNodeDescription (Ptr <Node> n, std::string descr);

  void UpdateNodeDescription (uint32_t nodeId, std::string descr);

  void UpdateNodeImage (uint32_t nodeId, uint32_t resourceId);

  void UpdateNodeSize (uint32_t nodeId, double width, double height);

  void UpdateNodeColor (Ptr <Node> n, uint8_t r, uint8_t g, uint8_t b);

  void UpdateNodeColor (uint32_t nodeId, uint8_t r, uint8_t g, uint8_t b);

  void UpdateNodeCounter (uint32_t nodeCounterId, uint32_t nodeId, double counter);

  void SetBackgroundImage (std::string fileName, double x, double y, double scaleX, double scaleY, double opacity);

  void UpdateLinkDescription (uint32_t fromNode, uint32_t toNode,
                              std::string linkDescription);

  void UpdateLinkDescription (Ptr <Node> fromNode, Ptr <Node> toNode,
                              std::string linkDescription);

  AnimationInterface & AddSourceDestination (uint32_t fromNodeId, std::string destinationIpv4Address);

  bool IsStarted (void);

  void SkipPacketTracing ();

  void EnablePacketMetadata (bool enable = true);

  uint64_t GetTracePktCount ();

  uint32_t AddNodeCounter (std::string counterName, CounterType counterType);

  uint32_t AddResource (std::string resourcePath);

  double GetNodeEnergyFraction (Ptr <const Node> node) const;

private:
  class AnimPacketInfo

  {
public:
    AnimPacketInfo ();
    AnimPacketInfo (const AnimPacketInfo & pInfo);
    AnimPacketInfo (Ptr <const NetDevice> tx_nd, const Time fbTx, uint32_t txNodeId = 0);
    Ptr <const NetDevice> m_txnd; 
    uint32_t m_txNodeId; 
    double m_fbTx; 
    double m_lbTx; 
    double m_fbRx; 
    double m_lbRx; 
    Ptr <const NetDevice> m_rxnd; 

    void ProcessRxBegin (Ptr <const NetDevice> nd, const double fbRx);
  };

  typedef struct
  {
    uint8_t r;   
    uint8_t g;   
    uint8_t b;   
  } Rgb;   

  typedef struct
  {
    uint32_t fromNode; 
    uint32_t toNode; 
  } P2pLinkNodeIdPair; 

  typedef struct
  {
    std::string fromNodeDescription; 
    std::string toNodeDescription; 
    std::string linkDescription; 
  } LinkProperties; 

  struct LinkPairCompare
  {
    bool operator () (P2pLinkNodeIdPair first, P2pLinkNodeIdPair second) const
    {
      //Check if they are the same node pairs but flipped
      if (  ((first.fromNode == second.fromNode) && (first.toNode == second.toNode))
            || ((first.fromNode == second.toNode) && (first.toNode == second.fromNode)) )
        {
          return false;
        }
      std::ostringstream oss1;
      oss1 << first.fromNode << first.toNode;
      std::ostringstream oss2;
      oss2 << second.fromNode << second.toNode;
      return oss1.str () < oss2.str ();
    }

  };

  typedef struct
  {
    std::string destination;   
    uint32_t fromNodeId;   
  } Ipv4RouteTrackElement;   

  typedef struct
  {
    uint32_t nodeId;   
    std::string nextHop;   
  } Ipv4RoutePathElement;   

  typedef enum
  {
    UAN,
    LTE,
    WIFI,
    WIMAX,
    CSMA,
    LRWPAN,
    WAVE
  } ProtocolType;

  typedef struct
  {
    double width;   
    double height;   
  } NodeSize;   
  typedef std::map <P2pLinkNodeIdPair, LinkProperties, LinkPairCompare> LinkPropertiesMap; 
  typedef std::map <uint32_t, std::string> NodeDescriptionsMap; 
  typedef std::map <uint32_t, Rgb> NodeColorsMap; 
  typedef std::map<uint64_t, AnimPacketInfo> AnimUidPacketInfoMap; 
  typedef std::map <uint32_t, double> EnergyFractionMap; 
  typedef std::vector <Ipv4RoutePathElement> Ipv4RoutePathElements; 
  typedef std::multimap <uint32_t, std::string> NodeIdIpv4Map; 
  typedef std::multimap <uint32_t, std::string> NodeIdIpv6Map; 
  typedef std::pair <uint32_t, std::string> NodeIdIpv4Pair; 
  typedef std::pair <uint32_t, std::string> NodeIdIpv6Pair; 


  // Node Counters
  typedef std::map <uint32_t, uint64_t> NodeCounterMap64; 


  class AnimXmlElement
  {
public:
    AnimXmlElement (std::string tagName, bool emptyElement = true);
    template <typename T>
    void AddAttribute (std::string attribute, T value, bool xmlEscape = false);
    void SetText (std::string text);
    void AppendChild (AnimXmlElement e);
    std::string ToString (bool autoClose = true);

private:
    std::string m_tagName; 
    std::string m_text; 
    std::vector<std::string> m_attributes; 
    std::vector<std::string> m_children; 

  };



  // ##### State #####

  FILE * m_f; 
  FILE * m_routingF; 
  Time m_mobilityPollInterval; 
  std::string m_outputFileName; 
  uint64_t gAnimUid;     
  AnimWriteCallback m_writeCallback; 
  bool m_started; 
  bool m_enablePacketMetadata; 
  Time m_startTime; 
  Time m_stopTime; 
  uint64_t m_maxPktsPerFile; 
  std::string m_originalFileName; 
  Time m_routingStopTime; 
  std::string m_routingFileName; 
  Time m_routingPollInterval; 
  NodeContainer m_routingNc; 
  Time m_ipv4L3ProtocolCountersStopTime; 
  Time m_ipv4L3ProtocolCountersPollInterval; 
  Time m_queueCountersStopTime; 
  Time m_queueCountersPollInterval; 
  Time m_wifiMacCountersStopTime; 
  Time m_wifiMacCountersPollInterval; 
  Time m_wifiPhyCountersStopTime; 
  Time m_wifiPhyCountersPollInterval; 
  static Rectangle * userBoundary; 
  bool m_trackPackets; 

  // Counter ID
  uint32_t m_remainingEnergyCounterId; 

  uint32_t m_ipv4L3ProtocolTxCounterId; 
  uint32_t m_ipv4L3ProtocolRxCounterId; 
  uint32_t m_ipv4L3ProtocolDropCounterId; 

  uint32_t m_queueEnqueueCounterId; 
  uint32_t m_queueDequeueCounterId; 
  uint32_t m_queueDropCounterId; 

  uint32_t m_wifiMacTxCounterId; 
  uint32_t m_wifiMacTxDropCounterId; 
  uint32_t m_wifiMacRxCounterId; 
  uint32_t m_wifiMacRxDropCounterId; 

  uint32_t m_wifiPhyTxDropCounterId; 
  uint32_t m_wifiPhyRxDropCounterId; 

  AnimUidPacketInfoMap m_pendingWifiPackets; 
  AnimUidPacketInfoMap m_pendingWimaxPackets; 
  AnimUidPacketInfoMap m_pendingLrWpanPackets; 
  AnimUidPacketInfoMap m_pendingLtePackets; 
  AnimUidPacketInfoMap m_pendingCsmaPackets; 
  AnimUidPacketInfoMap m_pendingUanPackets; 
  AnimUidPacketInfoMap m_pendingWavePackets; 

  std::map <uint32_t, Vector> m_nodeLocation; 
  std::map <std::string, uint32_t> m_macToNodeIdMap; 
  std::map <std::string, uint32_t> m_ipv4ToNodeIdMap; 
  std::map <std::string, uint32_t> m_ipv6ToNodeIdMap; 
  NodeIdIpv4Map m_nodeIdIpv4Map; 
  NodeIdIpv6Map m_nodeIdIpv6Map; 

  NodeColorsMap m_nodeColors; 
  NodeDescriptionsMap m_nodeDescriptions; 
  LinkPropertiesMap m_linkProperties; 
  EnergyFractionMap m_nodeEnergyFraction; 
  uint64_t m_currentPktCount; 
  std::vector <Ipv4RouteTrackElement> m_ipv4RouteTrackElements; 
  std::map <uint32_t, NodeSize> m_nodeSizes; 
  std::vector <std::string> m_resources; 
  std::vector <std::string> m_nodeCounters; 

  /* Value-added custom counters */
  NodeCounterMap64 m_nodeIpv4Drop; 
  NodeCounterMap64 m_nodeIpv4Tx; 
  NodeCounterMap64 m_nodeIpv4Rx; 
  NodeCounterMap64 m_nodeQueueEnqueue; 
  NodeCounterMap64 m_nodeQueueDequeue; 
  NodeCounterMap64 m_nodeQueueDrop; 
  NodeCounterMap64 m_nodeWifiMacTx; 
  NodeCounterMap64 m_nodeWifiMacTxDrop; 
  NodeCounterMap64 m_nodeWifiMacRx; 
  NodeCounterMap64 m_nodeWifiMacRxDrop; 
  NodeCounterMap64 m_nodeWifiPhyTxDrop; 
  NodeCounterMap64 m_nodeWifiPhyRxDrop; 
  NodeCounterMap64 m_nodeLrWpanMacTx; 
  NodeCounterMap64 m_nodeLrWpanMacTxDrop; 
  NodeCounterMap64 m_nodeLrWpanMacRx; 
  NodeCounterMap64 m_nodeLrWpanMacRxDrop; 

  const std::vector<std::string> GetElementsFromContext (const std::string& context) const;
  Ptr <Node> GetNodeFromContext (const std::string& context) const;
  Ptr <NetDevice> GetNetDeviceFromContext (std::string context);

  // ##### General #####
  void StartAnimation (bool restart = false);
  void SetOutputFile (const std::string& fn, bool routing = false);
  void StopAnimation (bool onlyAnimation = false);
  std::string CounterTypeToString (CounterType counterType);
  std::string GetPacketMetadata (Ptr<const Packet> p);
  void AddByteTag (uint64_t animUid, Ptr<const Packet> p);
  int WriteN (const char* data, uint32_t count, FILE * f);
  int WriteN (const std::string& st, FILE * f);
  std::string GetMacAddress (Ptr <NetDevice> nd);
  std::string GetIpv4Address (Ptr <NetDevice> nd);
  std::string GetIpv6Address (Ptr <NetDevice> nd);
  std::vector<std::string> GetIpv4Addresses (Ptr <NetDevice> nd);
  std::vector<std::string> GetIpv6Addresses (Ptr <NetDevice> nd);

  std::string GetNetAnimVersion ();
  void MobilityAutoCheck ();
  bool IsPacketPending (uint64_t animUid, ProtocolType protocolType);
  void PurgePendingPackets (ProtocolType protocolType);
  AnimUidPacketInfoMap * ProtocolTypeToPendingPackets (ProtocolType protocolType);
  std::string ProtocolTypeToString (ProtocolType protocolType);
  void AddPendingPacket (ProtocolType protocolType, uint64_t animUid, AnimPacketInfo pktInfo);
  uint64_t GetAnimUidFromPacket (Ptr <const Packet>);
  void AddToIpv4AddressNodeIdTable (std::string ipv4Address, uint32_t nodeId);
  void AddToIpv4AddressNodeIdTable (std::vector<std::string> ipv4Addresses, uint32_t nodeId);
  void AddToIpv6AddressNodeIdTable (std::string ipv6Address, uint32_t nodeId);
  void AddToIpv6AddressNodeIdTable (std::vector<std::string> ipv6Addresses, uint32_t nodeId);
  bool IsInTimeWindow ();
  void CheckMaxPktsPerTraceFile ();

  void TrackWifiPhyCounters ();
  void TrackWifiMacCounters ();
  void TrackIpv4L3ProtocolCounters ();
  void TrackQueueCounters ();
  // ##### Routing #####
  void TrackIpv4Route ();
  void TrackIpv4RoutePaths ();
  std::string GetIpv4RoutingTable (Ptr <Node> n);
  void RecursiveIpv4RoutePathSearch (std::string from, std::string to, Ipv4RoutePathElements &rpElements);
  void WriteRoutePath (uint32_t nodeId, std::string destination, Ipv4RoutePathElements rpElements);


  // ##### Trace #####
  void EnqueueTrace (std::string context, Ptr<const Packet>);
  void DequeueTrace (std::string context, Ptr<const Packet>);
  void QueueDropTrace (std::string context, Ptr<const Packet>);
  void Ipv4TxTrace (std::string context,
                    Ptr<const Packet> p, Ptr<Ipv4> ipv4,
                    uint32_t interfaceIndex);
  void Ipv4RxTrace (std::string context,
                    Ptr<const Packet> p, Ptr<Ipv4> ipv4,
                    uint32_t interfaceIndex);
  void Ipv4DropTrace (std::string context,
                      const Ipv4Header & ipv4Header,
                      Ptr<const Packet> p,
                      Ipv4L3Protocol::DropReason dropReason, Ptr<Ipv4> ipv4,
                      uint32_t interfaceIndex);

  void WifiMacTxTrace (std::string context, Ptr<const Packet> p);
  void WifiMacTxDropTrace (std::string context, Ptr<const Packet> p);
  void WifiMacRxTrace (std::string context, Ptr<const Packet> p);
  void WifiMacRxDropTrace (std::string context, Ptr<const Packet> p);
  void WifiPhyTxDropTrace (std::string context, Ptr<const Packet> p);
  void WifiPhyRxDropTrace (std::string context, Ptr<const Packet> p, WifiPhyRxfailureReason reason);
  void LrWpanMacTxTrace (std::string context,
                         Ptr<const Packet> p);
  void LrWpanMacTxDropTrace (std::string context,
                             Ptr<const Packet> p);
  void LrWpanMacRxTrace (std::string context,
                         Ptr<const Packet> p);
  void LrWpanMacRxDropTrace (std::string context,
                             Ptr<const Packet> p);
  void DevTxTrace (std::string context,
                   Ptr<const Packet> p,
                   Ptr<NetDevice> tx,
                   Ptr<NetDevice> rx,
                   Time txTime,
                   Time rxTime);
  void WifiPhyTxBeginTrace (std::string context, WifiConstPsduMap psduMap, WifiTxVector txVector, double txPowerW);
  void WifiPhyRxBeginTrace (std::string context, Ptr<const Packet> p, RxPowerWattPerChannelBand rxPowersW);
  void WavePhyTxBeginTrace (std::string context,
                            Ptr<const Packet> p);
  void WavePhyRxBeginTrace (std::string context,
                            Ptr<const Packet> p);
  void LrWpanPhyTxBeginTrace (std::string context,
                              Ptr<const Packet> p);
  void LrWpanPhyRxBeginTrace (std::string context,
                              Ptr<const Packet> p);
  void WimaxTxTrace (std::string context,
                     Ptr<const Packet> p,
                     const Mac48Address & m);
  void WimaxRxTrace (std::string context,
                     Ptr<const Packet> p,
                     const Mac48Address & m);
  void CsmaPhyTxBeginTrace (std::string context, Ptr<const Packet> p);
  void CsmaPhyTxEndTrace (std::string context, Ptr<const Packet> p);
  void CsmaPhyRxEndTrace (std::string context, Ptr<const Packet> p);
  void CsmaMacRxTrace (std::string context, Ptr<const Packet> p);
  void LteTxTrace (std::string context,
                   Ptr<const Packet> p,
                   const Mac48Address & m);
  void LteRxTrace (std::string context,
                   Ptr<const Packet> p,
                   const Mac48Address & m);
  void LteSpectrumPhyTxStart (std::string context, Ptr<const PacketBurst> pb);
  void LteSpectrumPhyRxStart (std::string context, Ptr<const PacketBurst> pb);
  void UanPhyGenTxTrace (std::string context, Ptr<const Packet>);
  void UanPhyGenRxTrace (std::string context, Ptr<const Packet>);
  void RemainingEnergyTrace (std::string context, double previousEnergy, double currentEnergy);
  void GenericWirelessTxTrace (std::string context, Ptr<const Packet> p, ProtocolType protocolType);
  void GenericWirelessRxTrace (std::string context, Ptr<const Packet> p, ProtocolType protocolType);


  void ConnectCallbacks ();
  void ConnectLte ();
  void ConnectLteUe (Ptr <Node> n, Ptr <LteUeNetDevice> nd, uint32_t devIndex);
  void ConnectLteEnb (Ptr <Node> n, Ptr <LteEnbNetDevice> nd, uint32_t devIndex);


  // ##### Mobility #####
  Vector GetPosition (Ptr <Node> n);
  Vector UpdatePosition (Ptr <Node> n);
  Vector UpdatePosition (Ptr <Node> n, Vector v);
  Vector UpdatePosition (Ptr <NetDevice> ndev);
  bool NodeHasMoved (Ptr <Node> n, Vector newLocation);
  std::vector < Ptr <Node> > GetMovedNodes ();
  void MobilityCourseChangeTrace (Ptr <const MobilityModel> mob);


  // ##### XML Helpers #####

  void WriteNonP2pLinkProperties (uint32_t id, std::string ipv4Address, std::string channelType);
  void WriteNodeUpdate (uint32_t nodeId);
  void OutputWirelessPacketTxInfo (Ptr<const Packet> p, AnimPacketInfo& pktInfo, uint64_t animUid);
  void OutputWirelessPacketRxInfo (Ptr<const Packet> p, AnimPacketInfo& pktInfo, uint64_t animUid);
  void OutputCsmaPacket (Ptr<const Packet> p, AnimPacketInfo& pktInfo);
  void WriteLinkProperties ();
  void WriteIpv4Addresses ();
  void WriteIpv6Addresses ();
  void WriteNodes ();
  void WriteNodeColors ();
  void WriteNodeSizes ();
  void WriteNodeEnergies ();
  void WriteXmlAnim (bool routing = false);
  void WriteXmlUpdateNodePosition (uint32_t nodeId, double x, double y);
  void WriteXmlUpdateNodeColor (uint32_t nodeId, uint8_t r, uint8_t g, uint8_t b);
  void WriteXmlUpdateNodeDescription (uint32_t nodeId);
  void WriteXmlUpdateNodeSize (uint32_t nodeId, double width, double height);
  void WriteXmlAddResource (uint32_t resourceId, std::string resourcePath);
  void WriteXmlAddNodeCounter (uint32_t counterId, std::string counterName, CounterType counterType);
  void WriteXmlUpdateNodeImage (uint32_t nodeId, uint32_t resourceId);
  void WriteXmlUpdateNodeCounter (uint32_t counterId, uint32_t nodeId, double value);
  void WriteXmlNode (uint32_t id, uint32_t sysId, double locX, double locY);
  void WriteXmlLink (uint32_t fromId, uint32_t toLp, uint32_t toId);
  void WriteXmlUpdateLink (uint32_t fromId, uint32_t toId, std::string linkDescription);
  void WriteXmlP (std::string pktType,
                  uint32_t fId,
                  double fbTx,
                  double lbTx,
                  uint32_t tId,
                  double fbRx,
                  double lbRx,
                  std::string metaInfo = "");
  void WriteXmlP (uint64_t animUid, std::string pktType, uint32_t fId, double fbTx, double lbTx);
  void WriteXmlPRef (uint64_t animUid, uint32_t fId, double fbTx, std::string metaInfo = "");
  void WriteXmlClose (std::string name, bool routing = false);
  void WriteXmlNonP2pLinkProperties (uint32_t id, std::string ipAddress, std::string channelType);
  void WriteXmlRouting (uint32_t id, std::string routingInfo);
  void WriteXmlRp (uint32_t nodeId, std::string destination, Ipv4RoutePathElements rpElements);
  void WriteXmlUpdateBackground (std::string fileName, double x, double y, double scaleX, double scaleY, double opacity);
  void WriteXmlIpv4Addresses (uint32_t nodeId, std::vector<std::string> ipv4Addresses);
  void WriteXmlIpv6Addresses (uint32_t nodeId, std::vector<std::string> ipv6Addresses);

};




class AnimByteTag : public Tag
{
public:
  static TypeId GetTypeId (void);

  virtual TypeId GetInstanceTypeId (void) const;

  virtual uint32_t GetSerializedSize (void) const;

  virtual void Serialize (TagBuffer i) const;

  virtual void Deserialize (TagBuffer i);

  virtual void Print (std::ostream &os) const;

  void Set (uint64_t AnimUid);

  uint64_t Get (void) const;

private:
  uint64_t m_AnimUid; 
};



}
#endif