From 2301cdfc097678ad2a45ffcf3ab02b7bdd7ce926 Mon Sep 17 00:00:00 2001
From: Tom Henderson <tomh@tomh.org>
Date: Tue, 14 Sep 2021 21:27:13 -0700
Subject: [PATCH] buildings: Update documentation for group mobility changes

---
 CHANGES.html                                |  2 +-
 RELEASE_NOTES                               |  1 +
 src/buildings/doc/source/buildings-user.rst | 20 ++++++++++++++++++++
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/CHANGES.html b/CHANGES.html
index 24995518c..c1c2fdc78 100644
--- a/CHANGES.html
+++ b/CHANGES.html
@@ -61,7 +61,7 @@ us a note on ns-developers mailing list.</p>
 <li>In class <b>ConfigStore</b>, a new Attribue <b>SaveDeprecated</b> allows to not save DEPRECATED Attributes. The default value is <b>false</b> (save DEPRECATED Attributes).</li>
 <li>In class <b>TracedCallback</b>, a new function <b>IsEmpty</b> allows to know if the TracedCallback will call any callback.</li>
 <li>A new specialization of std::hash for Ptr allows to use seamlessly Ptrs as keys in unordered_map and unordered_set.</li>
-<li>A new <b>GroupMobilityHelper</b> 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.</li>
+<li>A new <b>GroupMobilityHelper</b> 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).  New example programs and animation scripts are also added to both the buildings and mobility modules.</li>
 </ul>
 <h2>Changes to existing API:</h2>
 <ul>
diff --git a/RELEASE_NOTES b/RELEASE_NOTES
index 41bf94bf8..6caa5cbbd 100644
--- a/RELEASE_NOTES
+++ b/RELEASE_NOTES
@@ -39,6 +39,7 @@ New user-visible features
 - (core) Add std::hash<ns3::Ptr<T>> 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.
+- (buildings) Add example program demonstrating group mobility with the buildings-aware random walk mobility model, and a script to animate the group motion.
 
 Bugs fixed
 ----------
diff --git a/src/buildings/doc/source/buildings-user.rst b/src/buildings/doc/source/buildings-user.rst
index df654f1a9..40623717d 100644
--- a/src/buildings/doc/source/buildings-user.rst
+++ b/src/buildings/doc/source/buildings-user.rst
@@ -86,6 +86,26 @@ using a simple random mobility over the whole simulation area in
 presence of buildings might easily results in node moving in and out
 of buildings, regardless of the presence of walls.
 
+One dedicated buildings-aware mobility model is the
+``RandomWalk2dOutdoorMobilityModel``.  This class is similar to the
+``RandomWalk2dMobilityModel`` but avoids placing the trajectory
+on a path that would intersect a building wall.  If a boundary
+is encountered (either the bounding box or a building wall), the
+model rebounds with a random direction and speed that ensures that
+the trajectory stays outside the buildings.  An example program
+that demonstrates the use of this model is the
+``src/buildings/examples/outdoor-random-walk-example.cc`` which
+has an associated shell script to plot the traces generated.
+Another example program demonstrates how this outdoor mobility
+model can be used as the basis of a group mobility model, with
+the outdoor buildings-aware model serving as the parent or
+reference mobility model, and with additional nodes defining a
+child mobility model providing the offset from the reference
+mobility model.  This example,
+``src/buildings/example/outdoor-group-mobility-example.cc``,
+also has an associated shell script
+(``outdoor-group-mobility-animate.sh``) that can be used to generate
+an animated GIF of the group's movement.
 
 Place some nodes
 ****************