--- a/src/mobility/doc/mobility.rst Tue Sep 25 06:51:40 2012 -0700
+++ b/src/mobility/doc/mobility.rst Tue Sep 25 06:52:39 2012 -0700
@@ -1,3 +1,5 @@
+.. include:: replace.txt
+
Mobility
--------
@@ -7,7 +9,7 @@
============= Subsection (#.#.#)
############# Paragraph (no number)
-The mobility support in ns-3 includes:
+The mobility support in |ns3| includes:
- a set of mobility models which are used to track and maintain the *current* cartesian position and speed of an object.
- a "course change notifier" trace source which can be used to register listeners to the course changes of a mobility model
@@ -24,7 +26,7 @@
The design includes mobility models, position allocators, and helper
functions.
-In ns-3, special ``MobilityModel`` objects track the evolution of position
+In |ns3|, special ``MobilityModel`` objects track the evolution of position
with respect to a (cartesian) coordinate system. The mobility model
is typically aggregated to an ``ns3::Node`` object and queried using
``GetObject<MobilityModel> ()``. The base class ``ns3::MobilityModel``
@@ -48,11 +50,11 @@
#################
There are many possible coordinate systems and possible translations between
-them. ns-3 uses the Cartesian coordinate system only, at present.
+them. |ns3| uses the Cartesian coordinate system only, at present.
The question has arisen as to how to use the mobility models (supporting
Cartesian coordinates) with different coordinate systems. This is possible
-if the user performs conversion between the ns-3 Cartesian and the
+if the user performs conversion between the |ns3| Cartesian and the
other coordinate system. One possible library to assist is
the proj4 http://trac.osgeo.org/proj/ library for projections and reverse
projections.
@@ -76,7 +78,7 @@
positions are normally described as coordinates and not vectors in
the literature, it is possible to reuse the same data structure to
represent position (x,y,z) and velocity (magnitude and direction
-from the current position). ns-3 uses class Vector for both.
+from the current position). |ns3| uses class Vector for both.
There are also some additional related structures used to support
mobility models.
@@ -135,7 +137,7 @@
ns-2 MobilityHelper
###################
-The ns-2 mobility format is a widely used mobility trace format. The
+The |ns2| mobility format is a widely used mobility trace format. The
documentation is available at: http://www.isi.edu/nsnam/ns/doc/node172.html
Valid trace files use the following ns2 statements: ::
@@ -160,21 +162,21 @@
a new position (via ``set``), or sent on another course change
(via ``setdest``).
-Note that in ns-3, movement along the Z dimension is not supported.
+Note that in |ns3|, movement along the Z dimension is not supported.
Some examples of external tools that can export in this format include:
- BonnMotion http://net.cs.uni-bonn.de/wg/cs/applications/bonnmotion/
- Some installation instructions for BonnMotion can be found here: http://www.nsnam.org/wiki/index.php/HOWTO_use_ns-3_with_BonnMotion_mobility_generator_and_analysis_tool
- - Documentation on using BonnMotion with ns-3 is posted here: http://www.ida.liu.se/~rikno/files/mobility_generation.pdf
+ - Documentation on using BonnMotion with |ns3| is posted here: http://www.ida.liu.se/~rikno/files/mobility_generation.pdf
- SUMO http://sourceforge.net/apps/mediawiki/sumo/index.php?title=Main_Page
- TraNS http://trans.epfl.ch/
-- the ``setdest`` utility in ns-2, documented here: http://www.winlab.rutgers.edu/~zhibinwu/html/ns2_wireless_scene.htm
+- the ``setdest`` utility in |ns2|, documented here: http://www.winlab.rutgers.edu/~zhibinwu/html/ns2_wireless_scene.htm
A special Ns2MobilityHelper object can be used to parse these files
-and convert the statements into ns-3 mobility events. The underlying
+and convert the statements into |ns3| mobility events. The underlying
ConstantVelocityMobilityModel is used to model these movements.
See below for additional usage instructions on this helper.
@@ -192,8 +194,8 @@
Usage
*****
-Most ns-3 program authors typically interact with the mobility system
-only at configuration time. However, various ns-3 objects interact
+Most |ns3| program authors typically interact with the mobility system
+only at configuration time. However, various |ns3| objects interact
with mobility objects repeatedly during runtime, such as a propagation
model trying to determine the path loss between two mobile nodes.
@@ -219,7 +221,7 @@
"LayoutType", StringValue ("RowFirst"));
This code tells the mobility helper to use a two-dimensional grid to initially
-place the nodes. The first argument is an ns-3 TypeId specifying the
+place the nodes. The first argument is an |ns3| TypeId specifying the
type of mobility model; the remaining attribute/value pairs configure
this position allocator.
@@ -237,17 +239,117 @@
mobility.Install (wifiStaNodes);
A MobilityHelper object may be reconfigured and reused for different
-NodeContainers during the configuration of an ns-3 scenario.
+NodeContainers during the configuration of an |ns3| scenario.
Ns2MobilityHelper
=================
Two example programs are provided demonstrating the use of the
-ns-2 mobility helper:
+|ns2| mobility helper:
- ns2-mobility-trace.cc
- bonnmotion-ns2-example.cc
+ns2-mobility-trace
+##################
+
+The ``ns2-mobility-trace.cc`` program is an example of loading an
+|ns2| trace file that specifies the movements of two nodes over 100
+seconds of simulation time. It is paired with the file
+``default.ns_movements``.
+
+The program behaves as follows:
+
+- a Ns2MobilityHelper object is created, with the specified trace file.
+- A log file is created, using the log file name argument.
+- A node container is created with the number of nodes specified in the command line. For this particular trace file, specify the value 2 for this argument.
+- the Install() method of Ns2MobilityHelper to set mobility to nodes. At this moment, the file is read line by line, and the movement is scheduled in the simulator.
+- A callback is configured, so each time a node changes its course a log message is printed.
+
+The example prints out messages generated by each read line from the ns2 movement trace file. For each line, it shows if the line is correct, or of it has errors and in this case it will be ignored.
+
+Example usage:
+
+::
+
+ ./waf --run "ns2-mobility-trace --traceFile=src/mobility/examples/default.ns_movements --nodeNum=2 --duration=100.0 --logFile=ns2-mob.log"
+
+Sample log file output:
+
+::
+
+ +0.0ns POS: x=150, y=93.986, z=0; VEL:0, y=50.4038, z=0
+ +0.0ns POS: x=195.418, y=150, z=0; VEL:50.1186, y=0, z=0
+ +104727357.0ns POS: x=200.667, y=150, z=0; VEL:50.1239, y=0, z=0
+ +204480076.0ns POS: x=205.667, y=150, z=0; VEL:0, y=0, z=0
+
+bonnmotion-ns2-example
+######################
+
+The ``bonnmotion-ns2-example.cc`` program, which models the movement of
+a single mobile node for 1000 seconds of simulation time, has a few
+associated files:
+
+- ``bonnmotion.ns_movements`` is the |ns2|-formatted mobility trace
+- ``bonnmotion.params`` is a BonnMotion-generated file with some metadata about the mobility trace
+- ``bonnmotion.ns_params`` is another BonnMotion-generated file with ns-2-related metadata.
+
+Neither of the latter two files is used by |ns3|, although they are generated
+as part of the BonnMotion process to output ns-2-compatible traces.
+
+The program ``bonnmotion-ns2-example.cc`` will output the following to stdout:
+
+::
+
+ At 0.00 node 0: Position(329.82, 66.06, 0.00); Speed(0.53, -0.22, 0.00)
+ At 100.00 node 0: Position(378.38, 45.59, 0.00); Speed(0.00, 0.00, 0.00)
+ At 200.00 node 0: Position(304.52, 123.66, 0.00); Speed(-0.92, 0.97, 0.00)
+ At 300.00 node 0: Position(274.16, 131.67, 0.00); Speed(-0.53, -0.46, 0.00)
+ At 400.00 node 0: Position(202.11, 123.60, 0.00); Speed(-0.98, 0.35, 0.00)
+ At 500.00 node 0: Position(104.60, 158.95, 0.00); Speed(-0.98, 0.35, 0.00)
+ At 600.00 node 0: Position(31.92, 183.87, 0.00); Speed(0.76, -0.51, 0.00)
+ At 700.00 node 0: Position(107.99, 132.43, 0.00); Speed(0.76, -0.51, 0.00)
+ At 800.00 node 0: Position(184.06, 80.98, 0.00); Speed(0.76, -0.51, 0.00)
+ At 900.00 node 0: Position(250.08, 41.76, 0.00); Speed(0.60, -0.05, 0.00)
+
+The motion of the mobile node is sampled every 100 seconds, and its position
+and speed are printed out. This output may be compared to the output of
+a similar |ns2| program (found in the |ns2| ``tcl/ex/`` directory of |ns2|)
+running from the same mobility trace.
+
+The next file is generated from |ns2| (users will have to download and
+install |ns2| and run this Tcl program to see this output).
+The output of the |ns2| ``bonnmotion-example.tcl`` program is shown below
+for comparison (file ``bonnmotion-example.tr``):
+
+::
+
+ M 0.00000 0 (329.82, 66.06, 0.00), (378.38, 45.59), 0.57
+ M 100.00000 0 (378.38, 45.59, 0.00), (378.38, 45.59), 0.57
+ M 119.37150 0 (378.38, 45.59, 0.00), (286.69, 142.52), 1.33
+ M 200.00000 0 (304.52, 123.66, 0.00), (286.69, 142.52), 1.33
+ M 276.35353 0 (286.69, 142.52, 0.00), (246.32, 107.57), 0.70
+ M 300.00000 0 (274.16, 131.67, 0.00), (246.32, 107.57), 0.70
+ M 354.65589 0 (246.32, 107.57, 0.00), (27.38, 186.94), 1.04
+ M 400.00000 0 (202.11, 123.60, 0.00), (27.38, 186.94), 1.04
+ M 500.00000 0 (104.60, 158.95, 0.00), (27.38, 186.94), 1.04
+ M 594.03719 0 (27.38, 186.94, 0.00), (241.02, 42.45), 0.92
+ M 600.00000 0 (31.92, 183.87, 0.00), (241.02, 42.45), 0.92
+ M 700.00000 0 (107.99, 132.43, 0.00), (241.02, 42.45), 0.92
+ M 800.00000 0 (184.06, 80.98, 0.00), (241.02, 42.45), 0.92
+ M 884.77399 0 (241.02, 42.45, 0.00), (309.59, 37.22), 0.60
+ M 900.00000 0 (250.08, 41.76, 0.00), (309.59, 37.22), 0.60
+
+The output formatting is slightly different, and the course change
+times are additionally plotted, but it can be seen that the position
+vectors are the same between the two traces at intervals of 100 seconds.
+
+The mobility computations performed on the |ns2| trace file are slightly
+different in |ns2| and |ns3|, and floating-point arithmetic is used,
+so there is a chance that the position in |ns2| may be slightly
+different than the respective position when using the trace file
+in |ns3|.
+
Use of Random Variables
=======================