May 25, 2002

This README file describes the ad hoc network multicast extensions

added to
ns-2.1b8.

This distribution includes an entire ns source tree. The ns-2b8

source tree
was extended to include an implementation of the Adaptive Demand-
Driven
Multicast Routing protocol (ADMR) as well as an implementation of the
On-Demand Multicast Routing Protocol (ODMRP).

This README file assumes some familiarity with ns-2 Monarch wireless
extensions.

You would need to install tcl, otcl, tk and tclcl as with any ns-2
installation.
The versions of these software packages that I am using are:

tcl8.3.2, tk8.3.2, otcl-1.0a7, tclcl-1.0b11

This file is organized as follows:

0. Updates
1. ADMR Implementation
2. ODMRP Implementation
3. Trace Post-Processing
4. Scenario File Generation
5. General Information
6. Final Remarks

Updates
--------------------------------------------------------

Update on March 27 2004: updated mcast_cbrgen.tcl to generate short-

lived sessions.

Update on April 14 2003: fix in pbuff_admr.cc related to buffer

compaction.

Update on March 28 2003: fix in mcast_totals.pl related to receiver

leave events.

Update on March 23 2003: ** IMPORTANT **

Fixed a bug in ODMRP which was causing it to
generate
excessive overhead in certain scenarios.
Also upgraded the trace
support and the mcast_totals.pl file to count
Route Reply Acks
separately from the Route Replies.

Update on Mar. 13 2003: 1 line fix in admr/pbuff_admr.cc

Update on Mar. 1 2003: fixed a Reconnect packet forwarding bug in

ADMR (commented out one line of code).

Update on Feb. 21 2003: fixed a latency bug in ODMRP.

ADMR Implementation
--------------------------------------------------------

The ADMR code is in the admr/ directory which is in the ns-2 source
directory.
There are some minor modifications in other files in the ns-2 source
tree
such as cmu-trace.{h,cc}, packet.h and tcl/lib/ns-mobilenode.tcl.
These were
mostly needed in order to integrate the ADMR header into the
simulator.

The following command line can be used to run an ADMR simulation from
the ns source directory:

./ns scripts/run.tcl -x 1200 -y 800 -nn 100 -stop 900 -tr

TRACES/out.tr -mg
mcast_communication_scenarios/cbr_100_4x64_3x3x20_mcast_ns_rs -sc
movement_scenarios/scen-1200x800-100-0-20-1 -rp admr > &
TRACES/sim_stdoutput

All protocol parameters are specified in the file admr/admr_defs.h.

This implementation of ADMR includes updates to the protocol

specification
(mostly minor optimizations) which are not included in the current 00
Internet-Draft but will be included in the 01 internet draft.

Note: This is not the ADMR implementation used for the experiments
reported
in the Mobihoc 2001 ADMR paper.

ODMRP Implementation:
--------------------------------------------------------

The ODMRP code is in the odmrp/ directory which is in the ns-2 source
directory. There are some minor modifications in other files in the
ns-2
source tree such as cmu-trace.{h,cc}, packet.h and tcl/lib/ns-
mobilenode.tcl.
These were mostly needed in order to integrate the ODMRP header into
the
simulator.

The following command line can be used to run an ODMRP simulation

from
the ns source directory:

./ns scripts/run.tcl -x 1200 -y 800 -stop 900 -tr TRACES/out.tr -mg

mcast_communication_scenarios/cbr_100_4x64_3x3x20_mcast_ns_rs -sc
movement_scenarios/scen-1200x800-100-0-20-1 -nn 100 -rp odmrp >&
TRACES/sim_stdoutput

All protocol parameters are specified in the file odmrp/defs.h.

This is a ported version of the ODMRP implementation used in the

Mobihoc 2001
ADMR paper.

Trace Post Processing

--------------------------------------------------------

The script mcast_totals.pl converts the trace output by the simulator

into
a summary of packet statistics.

The following command line can be used to process an ADMR trace:

scripts/mcast_totals.pl ADM 100 900

mcast_communication_scenarios/cbr_100_4x64_3x3x20_mcast_ns_rs
TRACES/out.tr > RESULTS/admr_totals_output

The final 39 lines of the output are in matlab-ready format. You can
do
"tail -39 RESULTS/admr_totals_output" to extract these lines and then
store them in a
file to directly feed into matlab.

The following command line can be used to process an ODMRP trace:

scripts/mcast_totals.pl ODM 100 900

mcast_communication_scenarios/cbr_100_4x64_3x3x20_mcast_ns_rs
TRACES/out.tr > RESULTS/odmrp_totals_output

The final 21 lines of the output are in matlab ready format. You can
do
"tail -21 RESULTS/odmrp_totals_output" to extract these lines and
then store them in a
file to directly feed into matlab.

Sample matlab output for ADMR:

tx stands for transmissions, rx for receives, fx for forwards.

df = data flood; uka = unicast keepalive; rj = receiver join; ms =

multicast solicitation
ka = keepalive; rn = repair notification; rc = reconnect; rr =
reconnect reply;
ack = explicit acks (only receivers send those; there are only
forwards and receives
because each ack is a forward of a data packet with a set ack flag);

t.mrtr_tx = [ 2195 88346 ] % total control packet

transmissions
t.mrtr_rx = [ 550952 41229404 ] % total control packet
receptions
t.mrtr_fx = [ 39523 3080551 ] % total control packet
forwards
t.df_tx = [ 259 26936 ] % # of data floods
transmissions
t.df_rx = [ 331986 34526544 ]
t.df_fx = [ 25542 2656368 ]
t.uka_tx = [ 91 3640 ]
t.uka_rx = [ 317 12680 ]
t.uka_fx = [ 227 9080 ]
t.rj_tx = [ 270 7830 ]
t.rj_rx = [ 689 19981 ]
t.rj_fx = [ 420 12180 ]
t.ms_tx = [ 60 1740 ]
t.ms_rx = [ 82736 2399344 ]
t.ms_fx = [ 5940 172260 ]
t.ka_tx = [ 212 6784 ]
t.ka_rx = [ 86529 2768928 ]
t.ka_fx = [ 4958 158656 ]
t.rn_tx = [ 1223 39136 ]
t.rn_rx = [ 29977 959264 ]
t.rn_fx = [ 494 15808 ]
t.rc_tx = [ 40 1160 ]
t.rc_rx = [ 18559 538211
begin_of_the_skype_highlighting 18559
538211 end_of_the_skype_highlighting ]
t.rc_fx = [ 1823 52867 ]
t.rr_tx = [ 40 1120 ]
t.rr_rx = [ 159 4452 ]
t.rr_fx = [ 119 3332 ]
t.ack_tx = [ 0 0 ]
t.ack_rx = [ 2231295 214204320 ]
t.ack_fx = [ 172207 16531872 ]
t.cbr_tx = [ 28965 1853760 ]
t.cbr_rx = [ 552865 35383360 ]
t.cbr_fx = [ 532752 51144192 ]
t.cbr_rx_total = [ 552865 552865 ] % total cbr packet receptions
t.cbr_srx_total = [ 561423 561423 ] % # cbr packets that should have
been received (over
% all receivers
t.cbr_opt = [ 806280 0 0 ] % # of packets transmitted along
a given path length
% in the optimal case (the path
length is 0, 1, 2 etc.
% corresponding to the position
of the number in the
% array
t.cbr_act = [ 127359 98745 0 0 ] % number of packets actually
forwarded along a path
% of a certain length
t.cbr_dif % difference between t.cbr_act and
t.cbr_opt
t.cbr_lat % average latency experienced by
each receiver (time between when the
% packet is transmited and when
it is received (does not measure buffering
% delays)

Scenario File Generation

--------------------------------------------------------

The script scripts/mcast_cbrgen.tcl is used to generate the

multicast communication patterns. It is an extension of the
communication pattern generator included in the ns-2 Monarch
wireless extensions.

The following command line can be used to generate a communication

pattern for a 100 node simulation in which there are 2 groups, 5
sources per
group, 10 receivers per group:

./ns scripts/mcast_cbrgen.tcl -type cbr -nn 100 -seed 492832928 -rate

4 -ng 2 -nspg 5 -nrpg 10 -leave_mg 1 -join_dur_r 1 >
cbr_100_4x64_2x5x10_mcast_ns_rl
leave_mg is a flag which when set indicates that in addition to
joining the
group, the receivers may also leave the group at some point during
the
simulation. join_dur_r specifies whether the join duration of the
receivers
should be random or fixed. The options that can be given to the
generated
can be found in the mcast_cbrgen.tcl script itself.

scenario file naming convention used:

rl at the end of the scenario name indicates that the receivers are
allowed to
leave the group. the communication file ends with rs when the
receivers never
leave the group. 4x64 means that the send rate is 4 packets of 64
bytes each.
ns inicated that the sources are non-stop.

The movement scenarios that I have been using so far are random
waypoint
scenarios and are generated by the generators included in the ns-2
wireless extensions (setdest.cc).

Some pregenerated movement scenarios are in movement_scenarios/.

Several
pregenerated communication scenarios are in
mcast_communication_scenarios/.

Note that only cbr scenario generation has been tested, tcp has not.

General Information
--------------------------------------------------------

In order to be able to run both a multicast and unicast routing

protocol in the same simulation run, instead of attaching the
multicast
agent directly to the node, I have added a simple routing agent
(routing_agent/) which can be used to demultiplex unicast and
multicast
packets. The routing agent attaches directly to the node and a
multicast
agent and a unicast agent can be attached to it. ADMR and ODMRP are
each
implemented as multicast agents. Currently a dummy unicast agent is
used
(unicast_agent/).

The current implementation only supports one multicast source per

multicast
agent.

The file mcast_hookup.eps in mcast_doc/ shows a picture of the new

setup.

The mcast base address is specified via the mcast_base_addr_ variable

in
rtragent.cc and the multicast agents and is set to admr/odmrp.tcl to
0x8000
currently. Multicast addresses are > mcast_base_addr_.
Final Remarks
--------------------------------------------------------

I have had problems when the O2 flag is set (in the Makefile) and so
I normally disable
it. Also note that the NODEBUG flag which disables asserts is a
default Makefile
option in ns-2.

Sometimes the simulator core dumps in the last second of the

simulation. The problem
is somewhere in the tcl code and since it doesn't affect the results
I didn't spend
time debugging it.

---------------------------------------------------------

This is work in progress. Updates to the code and the protocol

specification
will be posted on the Monarch project webpage at
http://www.monarch.cs.rice.edu.

Disclaimer: This code is provided as a service to the wireless

community. It is
not a commercial product and does not include detailed comments or
documentation.
The best way to understand it is to read the source.

For questions or comments, contact Jorjeta G. Jetcheva at

jorjeta@cs.cmu.edu.