Document gracefull cancellation API (#535)

* Document gracefull cancellation API Signed-off-by: Ramon Wijnands <[email protected]> * Update plugin_tutorials/docs/writing_new_nav2controller_plugin.rst Signed-off-by: Ramon Wijnands <[email protected]> Co-authored-by: Steve Macenski <[email protected]> * Add graceful cancellation API to the migration guides Signed-off-by: Ramon Wijnands <[email protected]> * Update migration/Iron.rst Co-authored-by: Steve Macenski <[email protected]> * Add documentation for the RPP cancel_deceleration parameter --------- Signed-off-by: Ramon Wijnands <[email protected]> Co-authored-by: Steve Macenski <[email protected]>
ros-navigation · Mar 28, 2024 · 4c1c9e6 · 4c1c9e6
1 parent b3a5fef
commit 4c1c9e6
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 0 deletions.
diff --git a/configuration/packages/configuring-regulated-pp.rst b/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:
 
   ============== =================================================

diff --git a/migration/Iron.rst b/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.
diff --git a/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst b/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           |                        |