Document gracefull cancellation API

configuration/packages/configuring-regulated-pp.rst

@@ -266,6 +266,17 @@ Regulated Pure Pursuit Parameters
   Description
     Maximum allowable angular acceleration (rad/s/s) while rotating to heading, if ``use_rotate_to_heading`` is ``true``.
 
+:cancel_deceleration:
+
+  ============== =============================
+  Type           Default
+  -------------- -----------------------------
+  double         3.2
+  ============== =============================
+
+  Description
+    Linear deceleration (m/s/s) to apply when the goal is canceled.
+
 :max_robot_pose_search_dist:
 
   ============== =================================================

migration/Iron.rst

@@ -299,3 +299,8 @@ New collision monitor parameter
 *******************************
 
 `PR #4207 <https://github.com/ros-planning/navigation2/pull/4207>`_ introduces a new boolean parameter ``polygon_subscribe_transient_local`` (value is false by default), which set the QoS durability for polygon topic or footprint topic subscription.
+
+New graceful cancellation API for Controllers
+*********************************************
+
+`PR #4136 <https://github.com/ros-planning/navigation2/pull/4136>`_ introduces a new graceful cancellation API for controllers. Previously when a goal was canceled, the controller would stop the robot immediately. This API allows the controller to stop the robot in a more graceful way. The new API is implemented in the ``RegulatedPurePursuitController`` by adding a new parameter ``cancel_deceleration``. So when the goal is canceled, a constant deceleration will be used while continuing to track the path to stop the robot instead of stopping immediately. This API can be should be added to all controllers that have acceleration limits.

plugin_tutorials/docs/writing_new_nav2controller_plugin.rst

@@ -73,6 +73,11 @@ The list of methods, their descriptions, and necessity are presented in the tabl
 |                           | robot to drive.  This method passes 2 parameters: reference to the current robot      |                        |
 |                           | pose and its current velocity.                                                        |                        |
 +---------------------------+---------------------------------------------------------------------------------------+------------------------+
+| cancel()                  | Method is called when the controller server receives a cancel request. If this method | No                     |
+|                           | is unimplemented, the controller will immediately stop when receiving a cancel        |                        |
+|                           | request. If this method is implemented, the controller can perform a more graceful    |                        |
+|                           | stop and signal the controller server when it is done.                                |                        |
++---------------------------+---------------------------------------------------------------------------------------+------------------------+
 | setSpeedLimit()           | Method is called when it is required to limit the maximum linear speed of the robot.  | Yes                    |
 |                           | Speed limit could be expressed in absolute value (m/s) or in percentage from maximum  |                        |
 |                           | robot speed. Note that typically, maximum rotational speed is being limited           |                        |