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 ] 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.