diff --git a/CHANGES.html b/CHANGES.html
index 782e1c071..24995518c 100644
--- a/CHANGES.html
+++ b/CHANGES.html
@@ -61,6 +61,7 @@ us a note on ns-developers mailing list.
In class ConfigStore, a new Attribue SaveDeprecated allows to not save DEPRECATED Attributes. The default value is false (save DEPRECATED Attributes).
In class TracedCallback, a new function IsEmpty allows to know if the TracedCallback will call any callback.
A new specialization of std::hash for Ptr allows to use seamlessly Ptrs as keys in unordered_map and unordered_set.
+A new GroupMobilityHelper mobility helper has been added to ease the configuration of group mobility (a form of hierarchical mobility in which multiple child mobility models move with reference to an underlying parent mobility model). A new example program and animation script are also added.
Changes to existing API:
diff --git a/RELEASE_NOTES b/RELEASE_NOTES
index 5198dcd97..41bf94bf8 100644
--- a/RELEASE_NOTES
+++ b/RELEASE_NOTES
@@ -38,6 +38,7 @@ New user-visible features
- (core) Add TracedCallback::IsEmpty to know if a TracedCallback has any callback associated.
- (core) Add std::hash> to allow seamless use of Ptr as key in unordered_maps.
- (wifi) Add support for 11ax MU EDCA Parameter Set.
+- (mobility) Add GroupMobilityHelper and demonstrate its use with a new program that configures the Reference Point Group Mobility model for a number of nodes.
Bugs fixed
----------
diff --git a/src/mobility/doc/mobility.rst b/src/mobility/doc/mobility.rst
index 1607cd64a..62ec72f21 100644
--- a/src/mobility/doc/mobility.rst
+++ b/src/mobility/doc/mobility.rst
@@ -28,7 +28,7 @@ Design
The design includes mobility models, position allocators, and helper
functions.
-In |ns3|, special ``MobilityModel`` objects track the evolution of position
+In |ns3|, `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 ()``. The base class ``ns3::MobilityModel``
@@ -42,8 +42,8 @@ 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.
+allocator, and can be used with a node container to install a similar
+mobility capability on a set of nodes.
We first describe the coordinate system and issues
surrounding multiple coordinate systems.
@@ -58,7 +58,7 @@ 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 |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
+the `proj4 `_ library for projections and reverse
projections.
If we support converting between coordinate systems, we must adopt a
@@ -136,13 +136,23 @@ at the helper API level). The MobilityHelper class encapsulates
a MobilityModel factory object and a PositionAllocator used for
initial node layout.
+Group mobility is also configurable via a GroupMobilityHelper object.
+Group mobility reuses the HierarchicalMobilityModel allowing one to
+define a reference (parent) mobility model and child (member) mobility
+models, with the position being the vector sum of the two mobility
+model positions (i.e., the child position is defined as an offset to
+the parent position). In the GroupMobilityHelper, the parent mobility
+model is not associated with any node, and is used as the parent mobility
+model for all (distinct) child mobility models. The reference point group
+mobility model [Camp2002]_ is the basis for this |ns3| model.
+
ns-2 MobilityHelper
###################
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:
+Valid trace files use the following |ns2| statements:
.. sourcecode:: bash
@@ -172,10 +182,10 @@ Some examples of external tools that can export in this format include:
- `BonnMotion `_
- - `Installation instructions `_ and
- - `Documentation `_ for using BonnMotion with |ns3|
+ - `Installation instructions `_ and
+ - `Documentation `_ for using BonnMotion with |ns3|
-- `SUMO `_
+- `SUMO `_
- `TraNS `_
- |ns2| `setdest `_ utility
@@ -193,7 +203,8 @@ Scope and Limitations
References
==========
-TBD
+.. [Camp2002] T. Camp, J. Boleng, V. Davies. "A survey of mobility models for ad hoc network research",
+ in Wireless Communications and Mobile Computing, 2002: vol. 2, pp. 2483-2502.
Usage
*****
@@ -430,6 +441,27 @@ Examples
- ns2-mobility-trace.cc
- ns2-bonnmotion.cc
+reference-point-group-mobility-example.cc
+#########################################
+
+The reference point group mobility model ([Camp2002]_) is demonstrated
+in the example program `reference-point-group-mobility-example.cc`.
+This example runs a short simulation that illustrates a parent
+WaypointMobilityModel traversing a rectangular course within a bounding
+box, and three member nodes independently execute a two-dimensional
+random walk around the parent position, within a small bounding box.
+The example illustrates configuration using the GroupMobilityHelper
+and manual configuration without a helper; the configuration option
+is selectable by command-line argument.
+
+The example outputs two mobility trace files, a course change trace and
+a time-series trace of node position. The latter trace file can be
+parsed by a Bash script (`reference-point-group-mobility-animate.sh`)
+to create PNG images at one-second intervals, which can then be combined
+using an image processing program such as ImageMagick to form a
+basic animated gif of the mobility. The example and animation program
+files have further instructions on how to run them.
+
Validation
**********