INSTALLATION
GUIDE
0.
DOWNLOAD
Download
the files of the new module. Download
new RTP/RTCP NS-2 module
Montagud, M. and Boronat, F. 2010. A new network simulator
2 (NS-2) module based on RTP/RTCP protocols to achieve multimedia group
synchronization. In Proceedings of the 3rd international ICST Conference
on Simulation Tools and Techniques (Torremolinos, Malaga, Spain, March
15 - 19, 2010). International Conference on Simulation Tools and Techniques
for Commuications, Networks and Systems & Workshops. ICST (Institute
for Computer Sciences Social-Informatics and Telecommunications Engineering),
ICST, Brussels, Belgium, 1-8. DOI= http://dx.doi.org/10.4108/ICST.SIMUTOOLS2010.8686
1.
INTRODUCTION
In this document
the authors describe the necessary steps to include the new developed RTP/RTCP
module with the other built-in NS-2 modules,
without needing to replace the native implementation for these protocols.
We assume the reader has successfully installed a current NS-2.XX[1] version. This
code has been developed and tested with NS-2.33 and NS-2.34.
In the legacy code,
RTP
and RTCP protocols are implemented as the RTP Agent and
the RTCP Agent classes, respectively. These two classes
are implemented in the rtp.cc
(located in ~ns-2.XX/apps/rtp.cc) and rtcp.cc (located in ~ns-2.XX/tcp/rtcp.cc) files, as can
be appreciated in Figure 1. The RTP Agent holds
all the functionalities for sending and receiving data packets, whereas
the RTCP Agent is responsible for the
control reports transmission and reception. The RTP Session
class (implemented in ~ns-2.XX/common/session-rtp.cc) mainly deals
with feedback report building and participant’s information tables maintenance, through the received packets passed
by its agents. This class also defines the procedures for session initialization,
report interval calculation, associating new RTP sessions with nodes, managing
join and leave processes to multicast groups, stopping RTP flow transmissions,
liberating the session resources, etc. It is called by its binding Session/RTP OTcl class (implemented
in ~ns-2.XX/tcl/rtp/session-rtp.tcl). All the above
files use rtp.h
(located in ~ns-2.XX/apps/rtp.h) as header file, and they are shown in pink boxes in Figure 1.
Figure 1. NS-2 Directory Structure
The native implementation
is quite generic. Many attributes specified in RFC 3550 are not included
or they are not implemented accurately: i) it
does not define all the RTCP packets, only RTCP Sender Reports (SR) packets
are included, but its format is not complete (it does not include payload
type, number of packets/octets sent fields, etc.); ii) since RTCP Receiver
Reports (RR) messages are not defined, neither QoS
metrics (jitter, network delay, Round Trip Time -RTT-, loss rate) monitoring
nor reporting are provided; iii) the same packet header data structure is
used for both RTP and RTCP packets construction; iv) the packet header fields
are specified using incorrect variables’ types and sizes; v) there is a
bug for multicast transmissions configuration; vi) the code does not support
multiple multicast streams on the same node; vii) the RTP Agent is only capable
of generating CBR (Constant Bit Rate) traffic, etc.
As simulations
rely on the accuracy of the proposed models,
and as the NS-2 native implementation
for RTP/RTCP standard protocols is incomplete and imprecise, authors decided
to develop a new module with a more complete and accurate implementation
for these protocols than the one in the NS-2 native code, following strictly
all the attributes specified in RFC 3550. The code includes
the following enhancements: i) definition of
all the types of RTCP packets with their exact format (Sender Report
or SR, Receiver Reports or RR, Source Description or SDES, Application-defined
or APP and BYE packets); ii) network-level metrics
(such as end-to-end delay, jitter, RTT, throughput and packet loss) monitoring,
processing and registering in simulation time; iii) capability of processing
any kind of application traffic pattern supported by NS-2; iv) support
for multiple multicast streams on the same node; and v) compatibility with
the legacy code.
2. INSTALLATION STEPS
In order to install
the new developed NS-2 module, users must follow the next instructions:
- Decompress (untar) the ‘rtp_gs_module.tar.gz’ file. After decompression,
a new folder ‘rtp_gs_module’ will
be created. It includes:
- ‘rtp_gs’ folder, containing the C++
source code:
rtp_gs.h rtp_gs.cc
rtcp_gs.h rtcp_gs.cc session-rtp_gs.h session-rtp_gs.cc
- session-rtp.tcl file, including the TCL code.
In this file we have slightly modified the native TCL code in order
to correct a small bug that does not allow configuring
multicast scenarios. We have also included,
in the same file, the TCL code for the new developed module in order
to avoid adding another file (and/or directory).
- rtp_scenario.tcl
file, with an example
of a TCL script. It includes the necessary steps in order to configure
a new multicast simulation scenario with one RTP Source and three
RTP Receivers distributed over the network topology, using our new RTP/RTCP
module.
- Move the ‘rtp_gs’ folder into ns-allinone-2.XX/ns-2.XX directory.
- Replace the
session-rtp.tcl file,
located in ns-allinone-2.XX/ns-2.XX/tcl/rtp/, with
the one provided in the ‘rtp_gs_module’
folder.
- Define the
new specific packet types for the new developed protocols. The list of supported
packets by NS-2 is located inside ~ns-2.XX/common/packet.h
file. Thus, users must
modify this file including the new RTP/RTCP packets (using numeric
constants, which can vary depending on the NS-2 version) in packet_t enumeration
(located in this header file):
typedef unsigned int
packet_t;
static const packet_t
PT_TCP = 0;
static const packet_t
PT_UDP = 1;
...
static const packet_t
PT_RTCP = 14;
static const packet_t
PT_RTP = 15;
...
// insert new packet
types here
static
const packet_t PT_RTCP_GS = 61;
static
const packet_t PT_RTP_GS = 62;
// The numbers can
vary depending on the NS-2 version!!!
// This MUST be the
LAST one (61+2)
static packet_t PT_NTYPE
= 63;
In the same file,
users must provide a textual name for the new RTP/RTCP novel
packets identifying in order to distinguish them from the native packets
in the output trace files generated by the simulator. This is done by adding
the following lines inside p_info
C++ class constructor:
class
p_info {
public:
p_info()
{
initname()
}
...
static
void initName()
{
...
name_[PT_TCP]= "tcp";
name_[PT_UDP]= "udp";
...
name_[PT_RTCP]= "rtcp";
name_[PT_RTP]= "rtp";
...
name_[PT_RTCP_GS]= "rtcp_gs";
name_[PT_RTP_GS]= "rtp_gs";
...
}
}
Doing so, the new
RTP/RTCP packets will be able to be sent, received and processed by the
NS-2 simulation objects.
- Save changes.
- Add the following
lines to ‘ns-2.XX/tcl/lib/ns-default.tcl’ file just below the line ‘Agent/RTCP
set seqno_
Agent/RTCP set seqno_ 0
# New RTP/RTCP module:
default variables setting
Agent/RTP_gs
set seqno_ 0
Agent/RTP_gs set packetSize_ 1000
Agent/RTCP_gs set interval_ 500ms.
Agent/RTCP_gs set random_ 0
Session/RTP_gs set debug_ 0
Session/RTP_gs set cname_ 0
Session/RTP_gs set jitter_ 0
Session/RTP_gs set RTT_ 0
Session/RTP_gs set rx_recv_ 0
…
- Save changes.
- After that,
it is necessary to open the ‘Makefile.in’
file (located in ~ns-2.XX/ directory)
and modify it in order to add the source files of the new RTP/RTCP
module.
- Add to the
INCLUDES section this text: '-I./rtp_gs \'. It should look like:
INCLUDES = \
-
-
@V_INCLUDES@ \
-I./tcp -I./sctp -I./common -I./link -I./queue
-I./adc -I./apps -I./mac -I./mobile -I./trace \
-
-I./diffusion3/lib/main
-I./diffusion3/lib \
-I./diffusion3/lib/nr
-I./diffusion3/ns \
-I./diffusion3/filter_core
-I./asim/ -I./qs \
-I./diffserv -I./satellite
-I./rtp_gs \
-I./wpan
- Go to the “OBJ.CC” section and
add the following line (before the line @V_STLOBJ@):
rtp_gs/rtp_gs.o
rtp_gs/rtcp_gs.o rtp_gs/session-rtp_gs.o
\
We can add it just
below the line:
common/session-rtp.o
apps/rtp.o tcp/rtcp.o
\
Users need to do
that because the source directories for the new RTP/RTCP code have been
collocated in a new directory (‘rtp_gs’).
- Save changes.
- Here, all
the necessary modifications have been finished. Open a terminal window, move
to ns-allinone-2.XX/ns-2.XX and run:
./configure
, in order to create a new ‘Makefile’ file.
- The last step
is to compile the code. Execute the following commands (users must
still be in ns-allinone-2.XX/ns-2.XX directory):
make
clean;make depend;make;
Once it is finished,
a new binary file named ‘ns’ in ns-allinone-2.XX/ns-2.XX/
directory will be available with the new RTP/RTCP functionality.
Authors recommend
the use of an IDE to work with NS-2. We personally use KDevelop.
For bugs reporting
email to: mamontor@posgrado.upv.es or fboronat@dcom.upv.es.