diff --git a/doc/models/Makefile b/doc/models/Makefile index 4b3daffd3..879cf6e4d 100644 --- a/doc/models/Makefile +++ b/doc/models/Makefile @@ -43,6 +43,7 @@ SOURCES = \ $(SRC)/internet/doc/ipv6.rst \ $(SRC)/internet/doc/routing-overview.rst \ $(SRC)/internet/doc/tcp.rst \ + $(SRC)/mobility/doc/mobility.rst \ $(SRC)/olsr/doc/olsr.rst \ $(SRC)/openflow/doc/openflow-switch.rst \ $(SRC)/point-to-point/doc/point-to-point.rst \ diff --git a/doc/models/source/index.rst b/doc/models/source/index.rst index e81ac3837..84b3d38ea 100644 --- a/doc/models/source/index.rst +++ b/doc/models/source/index.rst @@ -32,6 +32,7 @@ This document is written in `reStructuredText ()``. The base class ``ns3::MobilityModel`` +is subclassed for different motion behaviors. + +The initial position of objects is typically set with a PositionAllocator. +These types of objects will lay out the position on a notional canvas. +Once the simulation starts, the position allocator may no longer be +used, or it may be used to pick future mobility "waypoints" for such +mobility models. + +Most users interact with the mobility system using mobility helper +classes. The MobilityHelper combines a mobility model and position +allocator, and can be used with a node container to install mobility +capability on a set of nodes. + +We first describe the coordinate system and issues +surrounding multiple coordinate systems. + +Coordinate system +################# + +There are many possible coordinate systems and possible translations between +them. ns-3 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 +other coordinate system. One possible library to assist is +the proj4 http://trac.osgeo.org/proj/ library for projections and reverse +projections. + +If we support converting between coordinate systems, we must adopt a +reference. It has been suggested to use the geocentric Cartesian coordinate +system as a reference. Contributions are welcome in this regard. + +The question has arisen about adding a new mobility model whose motion +is natively implemented in a different coordinate system (such as an +orbital mobility model implemented using spherical coordinate system). +We advise to create a subclass with the APIs desired +(such as Get/SetSphericalPosition), and new position allocators, and +implement the motion however desired, but must also support the conversion to +cartesian (by supporting the cartesian Get/SetPosition). + +Coordinates +########### + +The base class for a coordinate is called ``ns3::Vector``. While +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. + +There are also some additional related structures used to support +mobility models. + +- Rectangle +- Box +- Waypoint + +MobilityModel +############# + +Describe base class + +- GetPosition () +- Position and Velocity attributes +- GetDistanceFrom () +- CourseChangeNotification + +MobilityModel Subclasses +######################## + +- ConstantPosition +- ConstantVelocity +- ConstantAcceleration +- GaussMarkov +- Hierarchical +- RandomDirection2D +- RandomWalk2D +- RandomWaypoint +- SteadyStateRandomWaypoint +- Waypoint + +PositionAllocator +################# + +Position allocators usually used only at beginning, to lay out the nodes +initial position. However, some mobility models (e.g. RandomWaypoint) will +use a position allocator to pick new waypoints. + +- ListPositionAllocator +- GridPositionAllocator +- RandomRectanglePositionAllocator +- RandomBoxPositionAllocator +- RandomDiscPositionAllocator +- UniformDiscPositionAllocator + +Helper +###### + +A special mobility helper is provided that is mainly aimed at supporting +the installation of mobility to a Node container (when using containers +at the helper API level). The MobilityHelper class encapsulates +a MobilityModel factory object and a PositionAllocator used for +initial node layout. + +ns-2 MobilityHelper +################### + +The ns-2 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: :: + + $node set X_ x1 + $node set Y_ y1 + $node set Z_ z1 + $ns at $time $node setdest x2 y2 speed + $ns at $time $node set X_ x1 + $ns at $time $node set Y_ Y1 + $ns at $time $node set Z_ Z1 + +Some examples of external tools that can export in this format include: + +- BonnMotion http://net.cs.uni-bonn.de/wg/cs/applications/bonnmotion/ +- SUMO http://sourceforge.net/apps/mediawiki/sumo/index.php?title=Main_Page +- TraNS http://trans.epfl.ch/ + +A special Ns2MobilityHelper object can be used to parse these files +and convert the statements into ns-3 mobility events. + +Scope and Limitations +===================== + +- only cartesian coordinates are presently supported + +References +========== + +TBD + +Usage +***** + +Most ns-3 program authors typically interact with the mobility system +only at configuration time. However, various ns-3 objects interact +with mobility objects repeatedly during runtime, such as a propagation +model trying to determine the path loss between two mobile nodes. + +Helper +====== + +A typical usage pattern can be found in the ``third.cc`` program in the +tutorial. + +First, the user instantiates a ``MobilityHelper`` object and sets some +``Attributes`` controlling the "position allocator" functionality. + +:: + + MobilityHelper mobility; + + mobility.SetPositionAllocator ("ns3::GridPositionAllocator", + "MinX", DoubleValue (0.0), + "MinY", DoubleValue (0.0), + "DeltaX", DoubleValue (5.0), + "DeltaY", DoubleValue (10.0), + "GridWidth", UintegerValue (3), + "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 +type of mobility model; the remaining attribute/value pairs configure +this position allocator. + +Next, the user typically sets the MobilityModel subclass; e.g.: + +:: + + mobility.SetMobilityModel ("ns3::RandomWalk2dMobilityModel", + "Bounds", RectangleValue (Rectangle (-50, 50, -50, 50))); + +Once the helper is configured, it is typically passed a container, such as: + +:: + + mobility.Install (wifiStaNodes); + +A MobilityHelper object may be reconfigured and reused for different +NodeContainers during the configuration of an ns-3 scenario. + +Advanced Usage +============== + +A number of external tools can be used to generate traces read by +the Ns2MobilityHelper. + +ns-2 scengen +############ + +TBD + +BonnMotion +########## + +http://net.cs.uni-bonn.de/wg/cs/applications/bonnmotion/ + +SUMO +#### + +http://sourceforge.net/apps/mediawiki/sumo/index.php?title=Main_Page + +TraNS +##### + +http://trans.epfl.ch/ + +Examples +======== + +- main-random-topology.cc +- main-random-walk.cc +- main-grid-topology.cc +- ns2-mobility-trace.cc + +Validation +********** + +TBD