Release/0.1.0

README.md

@@ -2,7 +2,8 @@ VR traffic model for ns-3
 =========================
 
 **NOTE:** You can find more information about this work in the following paper:
-```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)
+
+_**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)**_
 
 Examples of usage for the newly introduced features can be found in the ``examples/`` folder.
 

doc/Makefile

@@ -0,0 +1,178 @@
+EPSTOPDF = epstopdf
+DIA = dia
+DOT = dot
+CONVERT = convert -density 250
+
+
+SOURCE = source
+FIGURES = $(SOURCE)/figures
+
+# specify dia figures from which .png and .pdf figures need to be built
+
+IMAGES_DIA = \
+
+# specify eps figures from which .png and .pdf figures need to be built
+
+IMAGES_EPS = \
+
+# rescale pdf figures as necessary
+
+IMAGES_NOBUILD = 
+# IMAGES_NOBUILD = $(FIGURES)/fading_pedestrian.png \
+
+IMAGES_BUILD = \
+	${IMAGES_DIA:.dia=.eps} \
+	${IMAGES_DIA:.dia=.png} \
+	${IMAGES_DIA:.dia=.pdf} \
+	${IMAGES_EPS:.eps=.png} \
+	${IMAGES_EPS:.eps=.pdf} 
+
+
+IMAGES = $(IMAGES_NOBUILD) $(IMAGES_BUILD)
+
+RESCALE = ../../../utils/rescale-pdf.sh
+
+%.eps : %.dia; $(DIA) -t eps $< -e $@
+%.png : %.dia; $(DIA) -t png $< -e $@
+%.png : %.eps; $(CONVERT) $< $@
+%.pdf : %.eps
+	$(EPSTOPDF) $< -o=$@
+	if test x$($@_width) != x; then $(RESCALE) $($@_width) $@ ; fi
+
+
+# You can set these variables from the command line.
+SPHINXOPTS		=
+SPHINXBUILD	= sphinx-build
+PAPER				=
+BUILDDIR			= build
+
+# Internal variables.
+PAPEROPT_a4		= -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS	= -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCE) 
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo " html			 to make standalone HTML files"
+	@echo " dirhtml	 to make HTML files named index.html in directories"
+	@echo " singlehtml to make a single large HTML file"
+	@echo " pickle		 to make pickle files"
+	@echo " json			 to make JSON files"
+	@echo " htmlhelp	 to make HTML files and a HTML help project"
+	@echo " qthelp		 to make HTML files and a qthelp project"
+	@echo " devhelp	 to make HTML files and a Devhelp project"
+	@echo " epub			 to make an epub"
+	@echo " latex		 to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo " latexpdf	 to make LaTeX files and run them through pdflatex"
+	@echo " text			 to make text files"
+	@echo " man			 to make manual pages"
+	@echo " changes	 to make an overview of all changed/added/deprecated items"
+	@echo " linkcheck to check all external links for integrity"
+	@echo " doctest	 to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+	-rm -f $(IMAGES_BUILD)
+
+
+images: $(IMAGES_NOBUILD) $(IMAGES_BUILD)
+
+frag: pickle
+	@if test ! -d $(BUILDDIR)/frag; then mkdir $(BUILDDIR)/frag; fi
+	pushd $(BUILDDIR)/frag && ../../pickle-to-xml.py ../pickle/index.fpickle	> navigation.xml && popd
+	cp -r $(BUILDDIR)/pickle/_images $(BUILDDIR)/frag
+
+html: $(IMAGES) 
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:	$(IMAGES)
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml: $(IMAGES)
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle: $(IMAGES)
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json: $(IMAGES)
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp: $(IMAGES)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+				".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp: $(IMAGES)
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+				".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ns-3.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ns-3.qhc"
+
+devhelp:	$(IMAGES)
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/ns-3"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ns-3"
+	@echo "# devhelp"
+
+epub: $(IMAGES)
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:	$(IMAGES)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+				"(use \`make latexpdf' here to do that automatically)."
+
+latexpdf: $(IMAGES)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text: $(IMAGES)
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:	$(IMAGES)
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:	$(IMAGES)
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:	$(IMAGEs)
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+				"or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:	$(IMAGES)
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+				"results in $(BUILDDIR)/doctest/output.txt."

doc/source/bursty-framework.rst

@@ -0,0 +1,105 @@
+Bursty Framework
+----------------
+
+The framework aims at supporting large packets sent across a network, fragmented into bursts of multiple smaller packets.
+
+
+Model Description
+*****************
+
+This model is described in `[WNS3-2021]`_.
+It was originally designed to model an Virtual Reality traffic source, although the bursty framework is more general.
+
+
+Design
+======
+
+Packets are generated by a class extending the ``BurstGenerator`` interface, fragmented into packet bursts by ``BurstyApplication``, and finally received by a ``BurstSink``.
+The framework is similar to ``OnOffApplication``-``PacketSink``, but generalized to support large packets fragmented into bursts.
+
+Burst Generator description
+###########################
+
+The ``BurstGenerator`` interface defines two methods that child classes have to extend, namely ``GenerateBurst`` and ``HasNextBurst``.
+The former generates a packet size and period, while the latter makes sure whether it is possible to generate an additional burst.
+
+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]`_.
+
+Bursty Application description
+##############################
+
+The ``BurstyApplication`` generates packet bursts based on the information yielded by the attached ``BurstGenerator``.
+A ``SeqTsSizeFragHeader`` is attached to each fragment, with information on its transmission time, the burst sequence number, the fragment sequence number, the total burst size, and the total number of fragments of the burst.
+This information is then used by the ``BurstSink`` to re-aggregate the burst into a single packet, if possible.
+
+Traces are fired for each transmitted fragment and burst.
+
+Burst Sink description
+######################
+
+The ``BurstSink`` tries to re-aggregate fragments into the original packet.
+It assumes that the burst transmission duration is relatively small compared to the burst period, and does not perform any Forward Error Correction (FEC).
+
+To do so, it gathers information from SeqTsSizeFragHeader, which all received packets should have.
+It then proceeds as follows:
+
+- Being based on a UDP socket, packets might arrive out-of-order. Within a burst, BurstSink will reorder the received packets.
+- While receiving burst n, if a fragment from burst k<n is received, the fragment is discarded
+- While receiving burst n, if a fragment from burst k>n is received, burst n is discarded and burst k will start being buffered.
+- If all fragments from a burst are received, the burst is successfully received.
+
+Traces are fired for each received fragment and burst successfully received.
+
+
+Usage
+*****
+
+This section is principally concerned with the usage of your model, using the public API. Focus first on most common usage patterns, then go into more advanced topics.
+
+Building New Module
+===================
+
+First, clone the main ns-3 repository, e.g.,:
+
+``git clone https://gitlab.com/nsnam/ns-3-dev ns-3-dev``
+
+Then, clone the bursty framework module into the ``contrib/`` folder:
+
+``git clone https://github.com/signetlabdei/ns-3-vr-app ns-3-dev/contrib/vr-app``
+
+Configure and build ns-3 from the `ns-3-dev` folder:
+
+| ``./waf configure --enable-tests --enable-examples``
+| ``./waf build``
+
+This module does not provide Python bindings at the moment.
+
+
+Setting up a scenario
+=====================
+
+Please reference the examples to understand how to set up a scenario.
+
+
+Examples
+========
+
+For more information, please check the the source files of the provided examples.
+
+Troubleshooting
+===============
+
+For any problem with the module, please open an issue. The maintainers will do their best to provide technical support!
+
+
+
+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>`_.