Update model to first journal submission

* Implement VrBurstGenerator from journal paper
* Add average throughput to csv traces
* Update: examples, documentation, references, CSV traffic traces
* Improve: wifi example max throughput, trace file burst generator (add GetTraceDuration)
* Fix: comment in example, missing initialization (the compiler was complaining in optimized mode), vr-app-n-stas.cc trace start time

README.md

@@ -11,12 +11,11 @@ This module comprises the following features:
 
 * Adds `BurstyApplication` and `BurstSink` as ns-3 applications: they allow to model complex applications by sending large data packets over UDP sockets, fragmenting them into bursts of smaller packets, and reassembling the packets at the receiver, if possible
 * A tracing system allows to obtain burst-level and fragment-level information at both the transmitter and receiver side
-* Models a Virtual Reality traffic source
-* 10 of the acquired VR traffic traces can be found in [model/BurstGeneratorTraces/](model/BurstGeneratorTraces/) and can be used directly in a simulation, using the `TraceFileBurstGenerator`
+* Models Virtual Reality traffic sources with realistic head movements in popular VR applications
+* 40 of the acquired VR traffic traces can be found in [model/BurstGeneratorTraces/](model/BurstGeneratorTraces/) and can be used directly in a simulation, using the `TraceFileBurstGenerator`. More information can be found in the folder and in the documentation.
 * Additional traffic models can be implemented by simply extending the `BurstGenerator` interface
 
 Future releases will aim to:
-* Improve, add, and diversify the VR traffic traces, including realistic head movements in popular VR applications
 * Model second-order statistics for VR traffic
 * Include a head-rotation model, coupled with the VR traffic generator
 * Optionally include sound traffic in the VR traffic generator, other than video traffic
@@ -78,6 +77,7 @@ Compiling standalone documentation:
 1. Open with your browser the file `contrib/vr-app/doc/models/build/html/bursty-framework.html` to visualize the documentation of the model
 
 
-## Reference paper
+## Reference papers
 
-Mattia Lecci, Andrea Zanella, Michele Zorzi, "An ns-3 Implementation of a Bursty Traffic Framework for Virtual Reality Sources," accepted to Workshop on ns-3 (WNS3), Jun. 2021, Virtual Event, USA, Pre-print available: [arXiv:2103.04609](https://arxiv.org/abs/2103.04609)
+* M. Lecci, M. Drago, A. Zanella, M. Zorzi, "An Open Framework for Analyzing and Modeling XR Network Traffic," Submitted to IEEE Access, Pre-print available: [arXiv:2108.04577](https://arxiv.org/abs/2108.04577).
+* Mattia Lecci, Andrea Zanella, Michele Zorzi, "An ns-3 Implementation of a Bursty Traffic Framework for Virtual Reality Sources," Workshop on ns-3 (WNS3), Jun. 2021, Virtual Event, USA, Open access DOI: [10.1145/3460797.3460807](https://doi.org/10.1145/3460797.3460807).

doc/source/bursty-framework.rst

@@ -7,7 +7,7 @@ The framework aims at supporting large packets sent across a network, fragmented
 Model Description
 *****************
 
-This model is described in `[WNS3-2021]`_.
+This model is described in `[WNS3-2021]`_ and was later improved in `[Access21]`_.
 It was originally designed to model an Virtual Reality traffic source, although the bursty framework is more general.
 
 
@@ -27,7 +27,14 @@ The framework comes with three generators already implemented:
 
 - ``SimpleBurstGenerator``: the user can specify ``RandomVariableStream`` for the packet size and period.
 - ``TraceFileBurstGenerator``: traffic trace files are imported and executed in ns-3, allowing the user to import real traffic traces into its simulations. Some traces representing a VR traffic source are included.
-- ``VrBurstGenerator``: implements a traffic model able to emulate Virtual Reality traffic, as described in `[WNS3-2021]`_.
+- ``VrBurstGenerator``: implements a traffic model able to simulate VR traffic sources, as described in `[Access21]`_. The model is based on over 4 hours of acquisitions while playing three different applications targeting different types of interactions. Specifically:
+
+  #. *Minecraft*: an extremely popular game, with the mod *Vivecraft* enabling both room-scale or seated VR experiences. The user can explore by walking or swimming, and interact with the virtual world by cutting trees, digging holes, crafting tools, etc.
+  #. *Virus Popper*: during this fast-paced educational game, many cartoony-looking viruses swarm a virtual room, and the user has to attack them with cleaning tools for survival.
+  #. *Google Earth VR - Tour*: the VR version of Google earth, allowing you to explore the world with satellite imagery, 3D terrain of the entire globe, and 3D buildings in hundreds of cities around the world. The SteamVR application allows you to make tours, teleporting the user all around the world every few seconds.
+  #. *Google Earth VR - Cities*: in this case, a more interactive experience is yielded, allowing the user to fully explore cities or landmarks for as long as they want.
+
+Please note that *Google Earth VR* was used in two different ways, thus allowing us to analyze two different versions of a same application.
 
 Bursty Application description
 ##############################
@@ -102,4 +109,8 @@ References
 
 .. _`[WNS3-2021]`:
 
-[WNS3-2021] Mattia Lecci, Andrea Zanella, Michele Zorzi, "An ns-3 Implementation of a Bursty Traffic Framework for Virtual Reality Sources," accepted to Workshop on ns-3 (WNS3), 2021, Preprint available: `arXiv:2103.04609 <https://arxiv.org/abs/2103.04609>`_.
+[WNS3-2021] Mattia Lecci, Andrea Zanella, Michele Zorzi, "An ns-3 Implementation of a Bursty Traffic Framework for Virtual Reality Sources," Workshop on ns-3 (WNS3), Jun. 2021, Virtual Event, USA, Open access DOI: `10.1145/3460797.3460807 <https://doi.org/10.1145/3460797.3460807>`_.
+
+.. _`[Access21]`:
+
+[Access21] Mattia Lecci, Matteo Drago, Andrea Zanella, Michele Zorzi, "An Open Framework for Analyzing and Modeling XR Network Traffic," submitted to IEEE Access, 2021, Preprint available: `arXiv:2108.04577 <https://arxiv.org/abs/2108.04577>`_.

examples/bursty-application-example.cc

@@ -146,7 +146,7 @@ main (int argc, char *argv[])
   BurstSinkHelper burstSinkHelper ("ns3::UdpSocketFactory",
                                    InetSocketAddress (sinkAddress, portNumber));
 
-  // Install HTTP client
+  // Install burst sink
   ApplicationContainer clientApps = burstSinkHelper.Install (nodes.Get (0));
   Ptr<BurstSink> burstSink = clientApps.Get (0)->GetObject<BurstSink> ();
 

examples/trace-file-burst-application-example.cc

@@ -28,6 +28,7 @@
 #include "ns3/seq-ts-size-frag-header.h"
 #include "ns3/bursty-helper.h"
 #include "ns3/burst-sink-helper.h"
+#include "ns3/trace-file-burst-generator.h"
 
 /**
  * Example of BurstyApplication using a TraceFileBurstGenerator.
@@ -61,7 +62,7 @@ int
 main (int argc, char *argv[])
 {
   std::string traceFolder = "contrib/vr-app/model/BurstGeneratorTraces/"; // example traces can be found here
-  std::string traceFile = "steam_init_20mbps_30fps_5min_usb_still.csv";
+  std::string traceFile = "ge_cities_20mbps_30fps.csv";
   double startTime = 0;
   double simTime = 20;
 
@@ -111,6 +112,18 @@ main (int argc, char *argv[])
   ApplicationContainer serverApps = burstyHelper.Install (nodes.Get (1));
   Ptr<BurstyApplication> burstyApp = serverApps.Get (0)->GetObject<BurstyApplication> ();
 
+  // Extract TraceFileBurstGenerator and check if able to fill the entire simulation
+  PointerValue val;
+  burstyApp->GetAttribute ("BurstGenerator", val);
+  Ptr<TraceFileBurstGenerator> tfbg = DynamicCast<TraceFileBurstGenerator> (val.GetObject ());
+  NS_ASSERT_MSG (tfbg, "The bursty application should be a TraceFileBurstGenerator");
+
+  if (startTime + simTime > tfbg->GetTraceDuration ())
+    {
+      NS_LOG_WARN ("The trace file will end before the simulation ends. Please choose a different "
+                   << "start time, a longer trace, or reduce the simulation duration.");
+    }
+
   // Create burst sink helper
   BurstSinkHelper burstSinkHelper ("ns3::UdpSocketFactory",
                                    InetSocketAddress (sinkAddress, portNumber));

examples/vr-app-n-stas.cc

@@ -133,6 +133,7 @@ main (int argc, char *argv[])
   double distance = 1; // the distance from the AP [m]
   std::string appRate = "50Mbps"; // the app target data rate
   double frameRate = 60; // the app frame rate [FPS]
+  std::string vrAppName = "VirusPopper"; // the app name
   std::string burstGeneratorType = "model"; // type of burst generator {"model", "trace", "deterministic"}
   double simulationTime = 10; // simulation time in seconds
 
@@ -141,6 +142,7 @@ main (int argc, char *argv[])
   // cmd.AddValue ("distance", "the distance from the AP [m]", distance);
   cmd.AddValue ("appRate", "the app target data rate", appRate);
   cmd.AddValue ("frameRate", "the app frame rate [FPS]", frameRate);
+  cmd.AddValue ("vrAppName", "the app name", vrAppName);
   cmd.AddValue ("burstGeneratorType",
                 "type of burst generator {\"model\", \"trace\", \"deterministic\"}",
                 burstGeneratorType);
@@ -149,7 +151,7 @@ main (int argc, char *argv[])
 
   uint32_t fragmentSize = 1472; //bytes
   uint32_t channelWidth = 160; // MHz
-  bool sgi = false; // Use short guard interval
+  bool sgi = true; // Use short guard interval
 
   LogComponentEnableAll (LOG_PREFIX_ALL);
   LogComponentEnable ("VrAppNStas", LOG_INFO);
@@ -239,18 +241,43 @@ main (int argc, char *argv[])
 
   if (burstGeneratorType == "model")
     {
-      NS_LOG_DEBUG ("VR generator with framerate=" << frameRate << ", appRate=" << appRate);
+      NS_LOG_DEBUG ("VR generator with framerate=" << frameRate << ", appRate=" << appRate << ", vrAppName=" << vrAppName);
 
       client.SetBurstGenerator ("ns3::VrBurstGenerator",
                                 "FrameRate", DoubleValue (frameRate),
-                                "TargetDataRate", DataRateValue (DataRate (appRate)));
+                                "TargetDataRate", DataRateValue (DataRate (appRate)),
+                                "VrAppName", StringValue (vrAppName));
     }
   else if (burstGeneratorType == "trace")
     {
       uint32_t dataRateMbps = uint32_t (DataRate (appRate).GetBitRate () / 1e6);
+      std::string appAbbrev;
+      if (vrAppName == "VirusPopper")
+        {
+          appAbbrev = "vp";
+        }
+      else if (vrAppName == "Minecraft")
+        {
+          appAbbrev = "mc";
+        }
+      else if (vrAppName == "GoogleEarthVrCities")
+        {
+          appAbbrev = "ge_cities";
+        }
+      else if (vrAppName == "GoogleEarthVrTour")
+        {
+          appAbbrev = "ge_tour";
+        }
+      else
+        {
+          NS_ABORT_MSG ("vrAppName=" << vrAppName << " was not recognized");
+        }
+
       std::ostringstream filenameSs;
-      filenameSs << GetInputPath () << "src/applications/model/BurstGeneratorTraces/"
-                 << dataRateMbps << "mbps_" << uint32_t (frameRate) << "fps.csv";
+      filenameSs << GetInputPath () << "contrib/vr-app/model/BurstGeneratorTraces/"
+                 << appAbbrev << "_"
+                 << dataRateMbps << "mbps_"
+                 << uint32_t (frameRate) << "fps.csv";
 
       NS_LOG_DEBUG ("Trace file generator with filename=" << filenameSs.str ());
 
@@ -283,6 +310,7 @@ main (int argc, char *argv[])
   ApplicationContainer clientApps = client.Install (wifiStaNodes);
   Ptr<UniformRandomVariable> x = CreateObjectWithAttributes<UniformRandomVariable> (
       "Min", DoubleValue (0), "Max", DoubleValue (1));
+  Ptr<UniformRandomVariable> y = CreateObject<UniformRandomVariable> ();
   for (uint32_t i = 0; i < nStas; i++)
     {
       Time startTime = Seconds (x->GetValue ());
@@ -296,7 +324,12 @@ main (int argc, char *argv[])
       Ptr<TraceFileBurstGenerator> tfbg = DynamicCast<TraceFileBurstGenerator> (val.GetObject ());
       if (tfbg)
         {
-          tfbg->SetAttribute ("StartTime", DoubleValue (i * simulationTime));
+          NS_ABORT_MSG_IF (tfbg->GetTraceDuration () < simulationTime,
+                           "Trace too short for this simulation");
+
+          double traceStartTime = y->GetValue (0, tfbg->GetTraceDuration () - simulationTime);
+          NS_LOG_UNCOND ("STA" << i << " will start its trace from " << traceStartTime);
+          tfbg->SetAttribute ("StartTime", DoubleValue (traceStartTime));
         }
     }
   clientApps.Stop (Seconds (simulationTime + 1));

examples/vr-application-example.cc

@@ -28,6 +28,7 @@
 #include "ns3/seq-ts-size-frag-header.h"
 #include "ns3/bursty-helper.h"
 #include "ns3/burst-sink-helper.h"
+#include "ns3/vr-burst-generator.h"
 
 using namespace ns3;
 
@@ -62,10 +63,12 @@ main (int argc, char *argv[])
   double simTime = 20;
   double frameRate = 30;
   std::string targetDataRate = "40Mbps";
+  std::string vrAppName = "VirusPopper";
 
   CommandLine cmd (__FILE__);
   cmd.AddValue ("frameRate", "VR application frame rate [FPS].", frameRate);
   cmd.AddValue ("targetDataRate", "Target data rate of the VR application.", targetDataRate);
+  cmd.AddValue ("vrAppName", "The VR application on which the model is based upon.", vrAppName);
   cmd.AddValue ("simTime", "Length of simulation [s].", simTime);
   cmd.Parse (argc, argv);
 
@@ -102,7 +105,8 @@ main (int argc, char *argv[])
   burstyHelper.SetAttribute ("FragmentSize", UintegerValue (1200));
   burstyHelper.SetBurstGenerator ("ns3::VrBurstGenerator",
                                   "FrameRate", DoubleValue (frameRate),
-                                  "TargetDataRate", DataRateValue (DataRate (targetDataRate)));
+                                  "TargetDataRate", DataRateValue (DataRate (targetDataRate)),
+                                  "VrAppName", StringValue(vrAppName));
 
   // Install bursty application
   ApplicationContainer serverApps = burstyHelper.Install (nodes.Get (1));