Refactor the plugin names for bt_navigator to use double colons (ros-navigation#539)

* Refactor the plugin names for bt_navigator to use double colons

* Refactor the plugin names for planner_server to use double colons

Signed-off-by: Alan Xue <[email protected]>

* Refactor the plugin names for behavior_server to use double colons

Signed-off-by: Alan Xue <[email protected]>

* Refactor the section of plugin tutorials to use double colons

Signed-off-by: Alan Xue <[email protected]>

* Update the migration guide from Iron to Jazzy to include the standardization of plugin naming using double colons (::).

Signed-off-by: Alan Xue <[email protected]>

* Add comment on '/' to '::' syntax change in example YAML files

* List of Plugins Affected by Naming Standardization

---------

Signed-off-by: Alan Xue <[email protected]>

Author: alanxuefei

configuration/packages/configuring-behavior-server.rst

@@ -151,30 +151,32 @@ Behavior Server Parameters
           ros__parameters:
             behavior_plugins: ["spin", "backup", "drive_on_heading", "wait"]
             spin:
-              plugin: "nav2_behaviors/Spin"
+              plugin: "nav2_behaviors::Spin" # In Iron and older versions, "/" was used instead of "::"
             backup:
-              plugin: "nav2_behaviors/BackUp"
+              plugin: "nav2_behaviors::BackUp" # In Iron and older versions, "/" was used instead of "::"
             drive_on_heading:
-              plugin: "nav2_behaviors/DriveOnHeading"
+              plugin: "nav2_behaviors::DriveOnHeading" # In Iron and older versions, "/" was used instead of "::"
             wait:
-              plugin: "nav2_behaviors/Wait"
+              plugin: "nav2_behaviors::Wait" # In Iron and older versions, "/" was used instead of "::"
     ..
 
 Default Plugins
 ***************
+.. note::
+    In Iron and older versions, "/" was used instead of "::".
 
 When the :code:`behavior_plugins` parameter is not overridden, the following default plugins are loaded:
 
   ================== =====================================================
   Namespace          Plugin
   ------------------ -----------------------------------------------------
-  "spin"             "nav2_behaviors/Spin"
+  "spin"             "nav2_behaviors::Spin"
   ------------------ -----------------------------------------------------
-  "backup"           "nav2_behaviors/BackUp"
+  "backup"           "nav2_behaviors::BackUp"
   ------------------ -----------------------------------------------------
-  "drive_on_heading" "nav2_behaviors/DriveOnHeading"
+  "drive_on_heading" "nav2_behaviors::DriveOnHeading"
   ------------------ -----------------------------------------------------
-  "wait"             "nav2_behaviors/Wait"
+  "wait"             "nav2_behaviors::Wait"
   ================== =====================================================
 
 Spin Behavior Parameters
@@ -359,15 +361,15 @@ Example
         cycle_frequency: 10.0
         behavior_plugins: ["spin", "backup", "drive_on_heading", "wait", "assisted_teleop"]
         spin:
-          plugin: "nav2_behaviors/Spin"
+          plugin: "nav2_behaviors::Spin" # In Iron and older versions, "/" was used instead of "::"
         backup:
-          plugin: "nav2_behaviors/BackUp"
+          plugin: "nav2_behaviors::BackUp" # In Iron and older versions, "/" was used instead of "::"
         drive_on_heading:
-          plugin: "nav2_behaviors/DriveOnHeading"
+          plugin: "nav2_behaviors::DriveOnHeading" # In Iron and older versions, "/" was used instead of "::"
         wait:
-          plugin: "nav2_behaviors/Wait"
+          plugin: "nav2_behaviors::Wait" # In Iron and older versions, "/" was used instead of "::"
         assisted_teleop:
-          plugin: "nav2_behaviors/AssistedTeleop"
+          plugin: "nav2_behaviors::AssistedTeleop" # In Iron and older versions, "/" was used instead of "::"
         local_frame: odom
         global_frame: map
         robot_base_frame: base_link

configuration/packages/configuring-bt-navigator.rst

@@ -246,9 +246,9 @@ Example
         path_blackboard_id: path
         navigators: ['navigate_to_pose', 'navigate_through_poses']
         navigate_to_pose:
-          plugin: "nav2_bt_navigator/NavigateToPoseNavigator"
+          plugin: "nav2_bt_navigator::NavigateToPoseNavigator" # In Iron and older versions, "/" was used instead of "::"
         navigate_through_poses:
-          plugin: "nav2_bt_navigator/NavigateThroughPosesNavigator"
+          plugin: "nav2_bt_navigator::NavigateThroughPosesNavigator" # In Iron and older versions, "/" was used instead of "::"
         plugin_lib_names: 
           - nav2_compute_path_to_pose_action_bt_node
           - nav2_follow_path_action_bt_node

configuration/packages/configuring-navfn.rst

@@ -66,7 +66,7 @@ Example
       ros__parameters:
         planner_plugins: ['GridBased']
         GridBased:
-          plugin: 'nav2_navfn_planner/NavfnPlanner'
+          plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::"
           use_astar: True
           allow_unknown: True
           tolerance: 1.0

configuration/packages/configuring-planner-server.rst

@@ -36,7 +36,7 @@ Parameters
           ros__parameters:
             planner_plugins: ["GridBased"]
             GridBased:
-              plugin: "nav2_navfn_planner/NavfnPlanner"
+              plugin: "nav2_navfn_planner::NavfnPlanner" # In Iron and older versions, "/" was used instead of "::"
     ..
 
 :expected_planner_frequency:
@@ -72,7 +72,7 @@ When the :code:`planner_plugins` parameter is not overridden, the following defa
   ================= =====================================================
   Namespace         Plugin
   ----------------- -----------------------------------------------------
-  "GridBased"       "nav2_navfn_planner/NavfnPlanner"
+  "GridBased"       "nav2_navfn_planner::NavfnPlanner"
   ================= =====================================================
 
 Example
@@ -84,4 +84,4 @@ Example
         expected_planner_frequency: 20.0
         planner_plugins: ['GridBased']
         GridBased:
-          plugin: 'nav2_navfn_planner/NavfnPlanner'
+          plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::"

configuration/packages/configuring-thetastar.rst

@@ -107,7 +107,7 @@ Example
       use_sim_time: True
       planner_plugins: ["GridBased"]
       GridBased:
-        plugin: "nav2_theta_star_planner/ThetaStarPlanner"
+        plugin: "nav2_theta_star_planner::ThetaStarPlanner" # In Iron and older versions, "/" was used instead of "::"
         how_many_corners: 8
         w_euc_cost: 1.0
         w_traversal_cost: 2.0

configuration/packages/smac/configuring-smac-2d.rst

@@ -179,7 +179,7 @@ Example
       use_sim_time: True
 
       GridBased:
-        plugin: "nav2_smac_planner/SmacPlanner2D"
+        plugin: "nav2_smac_planner::SmacPlanner2D" # In Iron and older versions, "/" was used instead of "::"
         tolerance: 0.125                      # tolerance for planning if unable to reach exact pose, in meters
         downsample_costmap: false             # whether or not to downsample the map
         downsampling_factor: 1                # multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm)

configuration/packages/smac/configuring-smac-hybrid.rst

@@ -388,7 +388,7 @@ Example
       use_sim_time: True
 
       GridBased:
-        plugin: "nav2_smac_planner/SmacPlannerHybrid"
+        plugin: "nav2_smac_planner::SmacPlannerHybrid" # In Iron and older versions, "/" was used instead of "::"
         downsample_costmap: false           # whether or not to downsample the map
         downsampling_factor: 1              # multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm)
         tolerance: 0.25                     # dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found.

configuration/packages/smac/configuring-smac-lattice.rst

@@ -338,7 +338,7 @@ Example
       use_sim_time: True
 
       GridBased:
-        plugin: "nav2_smac_planner/SmacPlannerLattice"
+        plugin: "nav2_smac_planner::SmacPlannerLattice" # In Iron and older versions, "/" was used instead of "::"
         allow_unknown: true                 # Allow traveling in unknown space
         tolerance: 0.25                     # dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found.
         max_iterations: 1000000             # Maximum total iterations to search for before failing (in case unreachable), set to -1 to disable

migration/Iron.rst

@@ -304,3 +304,14 @@ 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.
+
+Standardization of Plugin Naming with Double Colons (::)
+********************************************************
+
+`PR #4220`_ standardizes plugin naming across the Navigation2 package to use double colons (::), replacing the previous mixed use of slashes (/) and double colons. Affected plugins include:
+
+- Behavior Server: ``nav2_behaviors::Spin``, ``nav2_behaviors::BackUp``, ``nav2_behaviors::DriveOnHeading``, ``nav2_behaviors::Wait``, ``nav2_behaviors::AssistedTeleop``
+- Planner Server: ``nav2_navfn_planner::NavfnPlanner``, ``nav2_smac_planner::SmacPlanner2D``, ``nav2_smac_planner::SmacPlannerHybrid``, ``nav2_theta_star_planner::ThetaStarPlanner``
+- Controller Server: ``nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController``, ``nav2_dwb_controller::DWBLocalPlanner``
+- BT Navigator: ``nav2_bt_navigator::NavigateToPoseNavigator``, ``nav2_bt_navigator::NavigateThroughPosesNavigator``
+

plugin_tutorials/docs/writing_new_behavior_plugin.rst

@@ -172,7 +172,7 @@ It is good practice to place these lines at the end of the file but technically,
 .. code-block:: xml
 
   <library path="nav2_sms_behavior_plugin">
-    <class name="nav2_sms_behavior/SendSms" type="nav2_sms_behavior::SendSms" base_class_type="nav2_core::Behavior">
+    <class type="nav2_sms_behavior::SendSms" base_class_type="nav2_core::Behavior">
       <description>This is an example plugin which produces an SMS text message recovery.</description>
     </class>
   </library>
@@ -211,11 +211,11 @@ To enable the plugin, we need to modify the ``nav2_params.yaml`` file as below t
       behavior_plugins: ["spin", "backup", "wait"]  # Humble and later
       recovery_plugins: ["spin", "backup", "wait"]  # Galactic and earlier
       spin:
-        plugin: "nav2_behaviors/Spin"
+        plugin: "nav2_behaviors::Spin" # In Iron and older versions, "/" was used instead of "::"
       backup:
-        plugin: "nav2_behaviors/BackUp"
+        plugin: "nav2_behaviors::BackUp" # In Iron and older versions, "/" was used instead of "::"
       wait:
-        plugin: "nav2_behaviors/Wait"
+        plugin: "nav2_behaviors::Wait" # In Iron and older versions, "/" was used instead of "::"
       global_frame: odom
       robot_base_frame: base_link
       transform_timeout: 0.1
@@ -240,13 +240,13 @@ with
       behavior_plugins: ["spin", "backup", "wait","send_sms"]  # Humble and newer
       recovery_plugins: ["spin", "backup", "wait","send_sms"]  # Galactic and earlier
       spin:
-        plugin: "nav2_behaviors/Spin"
+        plugin: "nav2_behaviors::Spin" # In Iron and older versions, "/" was used instead of "::"
       backup:
-        plugin: "nav2_behaviors/BackUp"
+        plugin: "nav2_behaviors::BackUp" # In Iron and older versions, "/" was used instead of "::"
       wait:
-        plugin: "nav2_behaviors/Wait"
+        plugin: "nav2_behaviors::Wait" # In Iron and older versions, "/" was used instead of "::"
       send_sms:
-        plugin: "nav2_sms_behavior/SendSms"
+        plugin: "nav2_sms_behavior::SendSms" # In Iron and older versions, "/" was used instead of "::"
       account_sid: ... # your sid
       auth_token: ... # your token
       from_number: ... # your number

plugin_tutorials/docs/writing_new_costmap2d_plugin.rst

@@ -152,7 +152,7 @@ This part is usually placed at the end of cpp-file where the plugin class was wr
 .. code-block:: xml
 
   <library path="nav2_gradient_costmap_plugin_core">
-    <class name="nav2_gradient_costmap_plugin/GradientLayer" type="nav2_gradient_costmap_plugin::GradientLayer" base_class_type="nav2_costmap_2d::Layer">
+    <class type="nav2_gradient_costmap_plugin::GradientLayer" base_class_type="nav2_costmap_2d::Layer">
       <description>This is an example plugin which puts repeating costs gradients to costmap</description>
     </class>
   </library>
@@ -223,11 +223,11 @@ In this case each plugin object will be handled by its own parameters tree in a
 .. code-block:: text
 
   gradient_layer_1:
-    plugin: nav2_gradient_costmap_plugin/GradientLayer
+    plugin: nav2_gradient_costmap_plugin::GradientLayer # In Iron and older versions, "/" was used instead of "::"
     enabled: True
     ...
   gradient_layer_2:
-    plugin: nav2_gradient_costmap_plugin/GradientLayer
+    plugin: nav2_gradient_costmap_plugin::GradientLayer # In Iron and older versions, "/" was used instead of "::"
     enabled: False
     ...
 

plugin_tutorials/docs/writing_new_nav2controller_plugin.rst

@@ -265,14 +265,14 @@ To enable the plugin, we need to modify the ``nav2_params.yaml`` file as below
       controller_plugins: ["FollowPath"]
 
       FollowPath:
-        plugin: "nav2_pure_pursuit_controller::PurePursuitController"
+        plugin: "nav2_pure_pursuit_controller::PurePursuitController" # In Iron and older versions, "/" was used instead of "::"
         debug_trajectory_details: True
         desired_linear_vel: 0.2
         lookahead_dist: 0.4
         max_angular_vel: 1.0
         transform_tolerance: 1.0
 
-In the above snippet, you can observe the mapping of our ``nav2_pure_pursuit_controller/PurePursuitController`` controller to its id ``FollowPath``. 
+In the above snippet, you can observe the mapping of our ``nav2_pure_pursuit_controller::PurePursuitController`` controller to its id ``FollowPath``. 
 To pass plugin-specific parameters we have used ``<plugin_id>.<plugin_specific_parameter>``.
 
 4- Run Pure Pursuit Controller plugin

plugin_tutorials/docs/writing_new_nav2planner_plugin.rst

@@ -162,7 +162,7 @@ It is good practice to place these lines at the end of the file, but technically
 .. code-block:: xml
 
   <library path="nav2_straightline_planner_plugin">
-    <class name="nav2_straightline_planner/StraightLine" type="nav2_straightline_planner::StraightLine" base_class_type="nav2_core::GlobalPlanner">
+    <class type="nav2_straightline_planner::StraightLine" base_class_type="nav2_core::GlobalPlanner">
       <description>This is an example plugin which produces straight path.</description>
     </class>
   </library>
@@ -200,7 +200,7 @@ To enable the plugin, we need to modify the ``nav2_params.yaml`` file as below t
       plugins: ["GridBased"]
       use_sim_time: True
       GridBased:
-        plugin: "nav2_navfn_planner/NavfnPlanner" # For Foxy and later
+        plugin: "nav2_navfn_planner::NavfnPlanner" # For Foxy and later. In Iron and older versions, "/" was used instead of "::"
         tolerance: 2.0
         use_astar: false
         allow_unknown: true
@@ -214,10 +214,10 @@ with
       plugins: ["GridBased"]
       use_sim_time: True
       GridBased:
-        plugin: "nav2_straightline_planner/StraightLine"
+        plugin: "nav2_straightline_planner::StraightLine"
         interpolation_resolution: 0.1
 
-In the above snippet, you can observe the mapping of our ``nav2_straightline_planner/StraightLine`` planner to its id ``GridBased``. To pass plugin-specific parameters, we have used ``<plugin_id>.<plugin_specific_parameter>``.
+In the above snippet, you can observe the mapping of our ``nav2_straightline_planner::StraightLine`` planner to its id ``GridBased``. To pass plugin-specific parameters, we have used ``<plugin_id>.<plugin_specific_parameter>``.
 
 4- Run StraightLine plugin
 ---------------------------

plugin_tutorials/docs/writing_new_navigator_plugin.rst

@@ -332,12 +332,12 @@ To enable the plugin, we need to modify the ``nav2_params.yaml`` file as below
         path_blackboard_id: path
         navigators: ['navigate_to_pose', 'navigate_through_poses']
         navigate_to_pose:
-          plugin: "nav2_bt_navigator/NavigateToPoseNavigator"
+          plugin: "nav2_bt_navigator::NavigateToPoseNavigator" # In Iron and older versions, "/" was used instead of "::"
         navigate_through_poses:
-          plugin: "nav2_bt_navigator/NavigateThroughPosesNavigator"
+          plugin: "nav2_bt_navigator::NavigateThroughPosesNavigator" # In Iron and older versions, "/" was used instead of "::"
 
 
-In the above snippet, you can observe the mapping of our ``nav2_bt_navigator/NavigateToPoseNavigator`` plugin to its id ``navigate_to_pose``. 
+In the above snippet, you can observe the mapping of our ``nav2_bt_navigator::NavigateToPoseNavigator`` plugin to its id ``navigate_to_pose``. 
 To pass plugin-specific parameters we have used ``<plugin_id>.<plugin_specific_parameter>``.
 
 4- Run plugin

setup_guides/algorithm/select_algorithm.rst

@@ -66,7 +66,7 @@ Example Configuration
       ros__parameters:
         planner_plugins: ['GridBased']
         GridBased:
-          plugin: 'nav2_navfn_planner/NavfnPlanner'
+          plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::"
 
 An example configuration of the planner server is shown above. The ``planner_plugins`` parameter accepts a list of mapped planner plugin names. For each plugin namespace defined in ``planner_plugins`` (``GridBased`` in our example), we specify the type of plugin to be loaded in the ``plugin`` parameter. Additional configurations must then be specified in this namespace based on the algorithm to be used. Please see the `Configuration Guide <https://navigation.ros.org/configuration/index.html>`_ for more details.