Added documentation for PathCompleteGoalChecker, and GoalChecker plug…

…in interface changes. Made PathCompleteGoalChecker the default in examples. Signed-off-by: Joseph Duchesne <[email protected]>
ros-navigation · Dec 11, 2024 · c76340c · c76340c
1 parent fe19009
commit c76340c
Show file tree

Hide file tree

Showing 9 changed files with 62 additions and 23 deletions.
diff --git a/configuration/packages/bt-plugins/actions/FollowPath.rst b/configuration/packages/bt-plugins/actions/FollowPath.rst
@@ -40,7 +40,7 @@ Input Ports
   ====== =======
 
   Description
-    	Mapped name of the goal checker plugin type to use, e.g. SimpleGoalChecker.
+    	Mapped name of the goal checker plugin type to use, e.g. PathCompleteGoalChecker.
 
 :server_name:
 

diff --git a/configuration/packages/configuring-controller-server.rst b/configuration/packages/configuring-controller-server.rst
@@ -133,7 +133,7 @@ Parameters
           ros__parameters:
             goal_checker_plugins: ["goal_checker"]
             goal_checker:
-              plugin: "nav2_controller::SimpleGoalChecker"
+              plugin: "nav2_controller::PathCompleteGoalChecker"
 
 :min_x_velocity_threshold:
 
@@ -240,6 +240,7 @@ Provided Plugins
   nav2_controller-plugins/pose_progress_checker.rst
   nav2_controller-plugins/simple_goal_checker.rst
   nav2_controller-plugins/stopped_goal_checker.rst
+  nav2_controller-plugins/path_complete_goal_checker.rst
 
 Default Plugins
 ***************
@@ -251,7 +252,7 @@ When the :code:`progress_checker_plugins`, :code:`goal_checker_plugin` or :code:
   ------------------ -----------------------------------------------------
   "progress_checker" "nav2_controller::SimpleProgressChecker"
   ------------------ -----------------------------------------------------
-  "goal_checker"     "nav2_controller::SimpleGoalChecker"
+  "goal_checker"     "nav2_controller::PathCompleteGoalChecker"
   ------------------ -----------------------------------------------------
   "FollowPath"       "dwb_core::DWBLocalPlanner"
   ================== =====================================================
@@ -277,7 +278,7 @@ Example
           required_movement_radius: 0.5
           movement_time_allowance: 10.0
         goal_checker:
-          plugin: "nav2_controller::SimpleGoalChecker"
+          plugin: "nav2_controller::PathCompleteGoalChecker"
           xy_goal_tolerance: 0.25
           yaw_goal_tolerance: 0.25
           stateful: True

diff --git a/configuration/packages/configuring-dwb-controller.rst b/configuration/packages/configuring-dwb-controller.rst
@@ -72,7 +72,7 @@ Example
           required_movement_radius: 0.5
           movement_time_allowance: 10.0
         goal_checker:
-          plugin: "nav2_controller::SimpleGoalChecker"
+          plugin: "nav2_controller::PathCompleteGoalChecker"
           xy_goal_tolerance: 0.25
           yaw_goal_tolerance: 0.25
           stateful: True

diff --git a/configuration/packages/configuring-graceful-motion-controller.rst b/configuration/packages/configuring-graceful-motion-controller.rst
@@ -210,7 +210,7 @@ Example
         required_movement_radius: 0.5
         movement_time_allowance: 10.0
       goal_checker:
-        plugin: "nav2_controller::SimpleGoalChecker"
+        plugin: "nav2_controller::PathCompleteGoalChecker"
         xy_goal_tolerance: 0.25
         yaw_goal_tolerance: 0.25
         stateful: True

diff --git a/configuration/packages/configuring-regulated-pp.rst b/configuration/packages/configuring-regulated-pp.rst
@@ -332,7 +332,7 @@ Example
         required_movement_radius: 0.5
         movement_time_allowance: 10.0
       goal_checker:
-        plugin: "nav2_controller::SimpleGoalChecker"
+        plugin: "nav2_controller::PathCompleteGoalChecker"
         xy_goal_tolerance: 0.25
         yaw_goal_tolerance: 0.25
         stateful: True

diff --git a/configuration/packages/configuring-rotation-shim-controller.rst b/configuration/packages/configuring-rotation-shim-controller.rst
@@ -138,7 +138,7 @@ Example
         required_movement_radius: 0.5
         movement_time_allowance: 10.0
       goal_checker:
-        plugin: "nav2_controller::SimpleGoalChecker"
+        plugin: "nav2_controller::PathCompleteGoalChecker"
         xy_goal_tolerance: 0.25
         yaw_goal_tolerance: 0.25
         stateful: True

diff --git a/migration/Jazzy.rst b/migration/Jazzy.rst
@@ -198,4 +198,36 @@ This can be useful, for example, in cases where you want to move the robot even
 
 Default value:
 
-- false
+- false
+
+Extended GoalChecker Interface
+******************************
+
+In `PR #4789 <https://github.com/ros-navigation/navigation2/pull/4789>`_ the GoalChecker interface gained a new parameter `path` in the method `is_goal_reached`.
+
+Before:
+
+.. code-block:: cpp
+  
+  bool isGoalReached(
+      const geometry_msgs::msg::Pose & query_pose, const geometry_msgs::msg::Pose & goal_pose
+      const geometry_msgs::msg::Twist & velocity);
+  
+After:
+
+.. code-block:: cpp
+  
+  bool isGoalReached(
+      const geometry_msgs::msg::Pose & query_pose, const geometry_msgs::msg::Pose & goal_pose,
+      const geometry_msgs::msg::Twist & velocity, const nav_msgs::msg::Path & current_path);
+  
+This allows for GoalChecker plugins to account for the current path in deciding if the goal has been reached or not.
+
+The new argument `current_path` can be ignored by existing out of tree plugins that do not make use of it, once they are updated to use the new method signature.
+
+New (default) Goal Checker Plugin: PathCompleteGoalChecker
+********************************************************
+
+In `PR #4789 <https://github.com/ros-navigation/navigation2/pull/4789>`_ a new goal checker plugin: :ref:`configuring_nav2_controller_path_complete_goal_checker_plugin` was introduced.
+
+This was made the default goal checker, resolving a `premature path completion bug <https://github.com/ros-navigation/navigation2/issues/4304>`_.
diff --git a/plugins/index.rst b/plugins/index.rst
@@ -291,22 +291,28 @@ Waypoint Task Executors
 Goal Checkers
 =============
 
-+---------------------------------+------------------------+----------------------------------+
-|     Plugin Name                 |         Creator        |       Description                |
-+=================================+========================+==================================+
-| `SimpleGoalChecker`_            | David Lu!!             | A plugin check whether robot     |
-|                                 |                        | is within translational distance |
-|                                 |                        | and rotational distance of goal. |
-|                                 |                        |                                  |
-+---------------------------------+------------------------+----------------------------------+
-| `StoppedGoalChecker`_           | David Lu!!             | A plugin check whether robot     |
-|                                 |                        | is within translational distance |
-|                                 |                        | , rotational distance of goal,   |
-|                                 |                        | and velocity threshold.          |
-+---------------------------------+------------------------+----------------------------------+
++---------------------------------+------------------------+-----------------------------------+
+|     Plugin Name                 |         Creator        |       Description                 |
++=================================+========================+===================================+
+| `SimpleGoalChecker`_            | David Lu!!             | A plugin check whether robot      |
+|                                 |                        | is within translational distance  |
+|                                 |                        | and rotational distance of goal.  |
+|                                 |                        |                                   |
++---------------------------------+------------------------+-----------------------------------+
+| `StoppedGoalChecker`_           | David Lu!!             | A plugin check whether robot      |
+|                                 |                        | is within translational distance  |
+|                                 |                        | , rotational distance of goal,    |
+|                                 |                        | and velocity threshold.           |
++---------------------------------+------------------------+-----------------------------------+
+| `PathCompleteGoalChecker`_      | Joseph Duchesne        | A plugin that checks if robot is  |
+|                                 |                        | within translational & rotational |
+|                                 |                        | distance of goal, once path       |
+|                                 |                        | length is below a threshold.      |
++---------------------------------+------------------------+-----------------------------------+
 
 .. _SimpleGoalChecker: https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/plugins/simple_goal_checker.cpp
 .. _StoppedGoalChecker: https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/plugins/stopped_goal_checker.cpp
+.. _PathCompleteGoalChecker: https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/plugins/path_complete_goal_checker.cpp
 
 Progress Checkers
 =================

diff --git a/tutorials/docs/using_shim_controller.rst b/tutorials/docs/using_shim_controller.rst
@@ -59,7 +59,7 @@ As such, its configuration looks very similar to that of any other plugin. In th
           required_movement_radius: 0.5
           movement_time_allowance: 10.0
         goal_checker:
-          plugin: "nav2_controller::SimpleGoalChecker"
+          plugin: "nav2_controller::PathCompleteGoalChecker"
           xy_goal_tolerance: 0.25
           yaw_goal_tolerance: 0.25
           stateful: True