Merge remote-tracking branch 'origin/master' into PoseStampedArray

Signed-off-by: Tony Najjar <[email protected]>

.gitignore

@@ -1 +1,4 @@
 _build
+lib/
+bin/
+pyvenv.cfg

about/roscon.rst

@@ -0,0 +1,29 @@
+.. _roscon:
+
+ROSCon Talks
+############
+
+Below is a list of ROSCon talks that have been given by the Nav2 team and the community which describe important features, tuning and configuration advice, and how to work with them in your applications.
+
+Nav2 Developer Talks
+--------------------
+
+- `ROSCon 2024: On Use of Nav2 Docking <https://vimeo.com/1024971348>`_
+- `ROSCon FR 2023: Nav2 Whys over What's: Navigating the Philosophies Behind the Features <https://www.youtube.com/watch?v=2W3zWO-msEo>`_
+- `ROSCon 2023: On Use of Nav2 MPPI Controller <https://vimeo.com/879001391>`_
+- `ROSCon 2023: Bidirectional navigation with Nav2 <https://vimeo.com/879000809>`_
+- `ROSCon 2022: On Use of Nav2 Smac Planners <https://vimeo.com/showcase/9954564/video/767157646>`_
+- `ROSCon JP 2021: The Past, Present, and Future of Navigation <https://vimeo.com/638041661/a5306a02ab>`_
+- `ROSCon 2021: Chronicles of Caching and Containerising CI for Nav2 <https://vimeo.com/649647161>`_
+- `ROSCon 2020: Navigation2: The Next Generation Navigation System <https://vimeo.com/showcase/7812155/video/480604621>`_
+- `ROSCon 2019: On Use of SLAM Toolbox <https://vimeo.com/378682207>`_
+- `ROSCon 2019: Navigation 2 Overview <https://vimeo.com/378682188>`_
+- `ROSCon 2018: On Use of the Spatio-Temporal Voxel Layer <https://vimeo.com/292699571>`_
+
+Community's Talks
+-----------------
+
+- `ROSCon ES 2024: Navegación robusta en ROS2 <https://vimeo.com/showcase/11453818/video/1029492785>`_
+- `ROSCon 2022: BehaviorTree.CPP 4.0. What is new and roadmap <https://vimeo.com/showcase/9954564/video/767160437>`_
+- `ROSCon 2024: Mobile Robotics Scale-up Leveraging ROS <https://vimeo.com/1024971160>`_
+- `ROSCon 2024: Radar Tracks for Path Planning in the presence of Dynamic Obstacles <https://vimeo.com/1024971565>`_

configuration/packages/configuring-costmaps.rst

@@ -349,6 +349,7 @@ Plugin Parameters
   costmap-plugins/voxel.rst
   costmap-plugins/range.rst
   costmap-plugins/denoise.rst
+  costmap-plugins/plugin_container.rst
 
 Costmap Filters Parameters
 **************************

configuration/packages/configuring-graceful-motion-controller.rst

@@ -25,16 +25,27 @@ Graceful Controller Parameters
   Description
     The TF transform tolerance (s).
 
-:motion_target_dist:
+:max_lookahead:
 
   ============== =============================
   Type           Default                      
   -------------- -----------------------------
-  double         0.6
+  double         1.0
   ============== =============================
 
   Description
-    The lookahead distance (m) to use to find the motion_target point.
+    The maximum lookahead distance (m) to use when selecting a target pose for the underlying control law. Using poses that are further away will generally result in smoother operations, but simulating poses that are very far away can result in reduced performance, especially in tight or cluttered environments. If the controller cannot forward simulate to a pose this far away without colliding, it will iteratively select a target pose that is closer to the robot.
+
+:min_lookahead:
+
+  ============== =============================
+  Type           Default                      
+  -------------- -----------------------------
+  double         0.25
+  ============== =============================
+
+  Description
+    The minimum lookahead distance (m) to use when selecting a target pose for the underlying control law. This parameter avoids instability when an unexpected obstacle appears in the path of the robot by returning failure, which typically triggers replanning.
 
 :max_robot_pose_search_dist:
 
@@ -52,29 +63,29 @@ Graceful Controller Parameters
   ============== =============================
   Type           Default                      
   -------------- -----------------------------
-  double         3.0 
+  double         2.0
   ============== =============================
 
   Description
-    Ratio of the rate of change in phi to the rate of change in r. Controls the convergence of the slow subsystem. If this value is equal to zero, the controller will behave as a pure waypoint follower. A high value offers extreme scenario of pose-following where theta is reduced much faster than r.
+    Ratio of the rate of change in phi to the rate of change in r. Controls the convergence of the slow subsystem. If this value is equal to zero, the controller will behave as a pure waypoint follower. A high value offers extreme scenario of pose-following where theta is reduced much faster than r. The referenced paper calls this `k1`.
 
 :k_delta:
 
   ============== =============================
   Type           Default                      
   -------------- -----------------------------
-  double         2.0 
+  double         1.0
   ============== =============================
 
   Description
-    Constant factor applied to the heading error feedback. Controls the convergence of the fast subsystem. The bigger the value, the robot converge faster to the reference heading.
+    Constant factor applied to the heading error feedback. Controls the convergence of the fast subsystem. The bigger the value, the robot converge faster to the reference heading. The referenced paper calls this `k2`.
 
 :beta:
 
   ============== =============================
   Type           Default                      
   -------------- -----------------------------
-  double         0.2 
+  double         0.4
   ============== =============================
 
   Description
@@ -124,6 +135,17 @@ Graceful Controller Parameters
   Description
     Maximum angular velocity (rad/s) produced by the control law.
 
+:v_angular_min_in_place:
+
+  ============== =============================
+  Type           Default                      
+  -------------- -----------------------------
+  double         0.25
+  ============== =============================
+
+  Description
+    Minimum angular velocity (rad/s) produced by the control law when rotating in place. This value should be based on the minimum rotation speed controllable by the robot.
+
 :slowdown_radius:
 
   ============== =============================
@@ -146,18 +168,18 @@ Graceful Controller Parameters
   Description
     Enable a rotation in place to the goal before starting the path. The control law may generate large sweeping arcs to the goal pose, depending on the initial robot orientation and ``k_phi``, ``k_delta``.
 
-:initial_rotation_min_angle:
+:initial_rotation_tolerance:
 
   ============== =============================
   Type           Default                      
   -------------- -----------------------------
-  double         0.75 
+  double         0.75
   ============== =============================
 
   Description
-    The difference in the path orientation and the starting robot orientation to trigger a rotate in place, if ``initial_rotation`` is enabled.
+    The difference in the path orientation and the starting robot orientation to trigger a rotate in place, if ``initial_rotation`` is enabled. This value is generally acceptable if continuous replanning is enabled. If not using continuous replanning, a lower value may perform better.
 
-:final_rotation:
+:prefer_final_rotation:
 
   ============== =============================
   Type           Default                      
@@ -166,7 +188,7 @@ Graceful Controller Parameters
   ============== =============================
 
   Description
-    Similar to ``initial_rotation``, the control law can generate large arcs when the goal orientation is not aligned with the path. If this is enabled, the final pose will be ignored and the robot will follow the orientation of he path and will make a final rotation in place to the goal orientation.
+    The control law can generate large arcs when the goal orientation is not aligned with the path. If this is enabled, the orientation of the final pose will be ignored and the robot will follow the orientation of the path and will make a final rotation in place to the goal orientation.
 
 :rotation_scaling_factor:
 
@@ -190,6 +212,17 @@ Graceful Controller Parameters
   Description
     Whether to allow the robot to move backward.
 
+:in_place_collision_tolerance:
+
+  ============== =============================
+  Type           Default                      
+  -------------- -----------------------------
+  double         0.1
+  ============== =============================
+
+  Description
+    When performing an in-place rotation after the XY goal tolerance has been met, this is the angle (in radians) between poses to check for collision.
+
 Example
 *******
 .. code-block:: yaml
@@ -217,10 +250,11 @@ Example
       FollowPath:
         plugin: nav2_graceful_controller::GracefulController
         transform_tolerance: 0.1
-        motion_target_dist: 0.6
+        min_lookahead: 0.25
+        max_lookahead: 1.0
         initial_rotation: true
-        initial_rotation_min_angle: 0.75
-        final_rotation: true
+        initial_rotation_threshold: 0.75
+        prefer_final_rotation: true
         allow_backward: false
         k_phi: 3.0
         k_delta: 2.0
@@ -229,4 +263,5 @@ Example
         v_linear_min: 0.1
         v_linear_max: 1.0
         v_angular_max: 5.0
+        v_angular_min_in_place: 0.25
         slowdown_radius: 1.5

configuration/packages/costmap-plugins/plugin_container.rst

@@ -0,0 +1,95 @@
+.. plugin_container:
+
+Plugin Container Layer Parameters
+=================================
+
+This implements a costmap layer which combines costmap layers within a submap, which can then be integrated with other submaps in the same parent costmap. An example would be the use of different inflation layers for different sensors, objects, or static layers  
+
+``<plugin container layer>`` is the corresponding plugin name selected for this type.
+
+:``<plugin container layer>``.enabled:
+
+  ==== =======
+  Type Default                                                   
+  ---- -------
+  bool True            
+  ==== =======
+
+  Description
+    Whether it is enabled.
+
+:``<plugin container layer>``.plugins:
+
+  ============== =======
+  Type           Default
+  -------------- -------
+  vector<string> {}
+  ============== =======
+
+  Description
+    List of mapped costmap layer names for parameter namespaces and names.
+
+  Note
+    Costmap filters are presently unsupported
+
+Example
+*******
+.. code-block:: yaml
+
+  global_costmap:
+    ros__parameters:
+      update_frequency: 1.0
+      publish_frequency: 1.0
+      global_frame: map
+      robot_base_frame: base_link
+      robot_radius: 0.22
+      resolution: 0.05
+      track_unknown_space: true
+
+      plugins: ["plugin_container_static_layer", "plugin_container_obstacle_layer"]
+
+      plugin_container_static_layer:
+        plugin: "nav2_costmap_2d::PluginContainerLayer"
+        enabled: True
+        combination_method: 1
+        plugins: ["static_layer", "inflation_layer"]
+        static_layer:
+          plugin: "nav2_costmap_2d::StaticLayer"
+          map_subscribe_transient_local: True
+        inflation_layer:
+          plugin: "nav2_costmap_2d::InflationLayer"
+          cost_scaling_factor: 2.0
+          inflation_radius: 0.5
+
+      plugin_container_obstacle_layer:
+        plugin: "nav2_costmap_2d::PluginContainerLayer"
+        enabled: True
+        combination_method: 1
+        plugins: ["obstacle_layer", "inflation_layer"]
+        obstacle_layer:
+          plugin: "nav2_costmap_2d::ObstacleLayer"
+          enabled: True
+          observation_sources: scan
+          scan:
+            topic: /scan
+            max_obstacle_height: 2.0
+            clearing: True
+            marking: True
+            data_type: "LaserScan"
+            raytrace_max_range: 3.0
+            raytrace_min_range: 0.0
+            obstacle_max_range: 2.5
+            obstacle_min_range: 0.0
+        inflation_layer:
+          plugin: "nav2_costmap_2d::InflationLayer"
+          cost_scaling_factor: 3.0
+          inflation_radius: 1.0
+
+The above example settings, when applied to the Nav2 turtlebot simulation would give the following costmap on startup
+
+.. figure:: plugin_container_layer.png
+    :align: center
+    :alt: Costmap generated by plugin container layer
+
+    Costmap generated by turtlebot using example plugin container layer settings
+

index.rst

@@ -18,7 +18,7 @@
 Our Sponsors
 ############
 
-.. image:: images/sponsors_feb_2024.png
+.. image:: images/sponsors_jan_2025.png
     :width: 700px
     :align: center
     :alt: Our Sponsors
@@ -193,6 +193,7 @@ IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2021
    concepts/index.rst
    setup_guides/index.rst
    about/robots.rst
+   about/roscon.rst
    tutorials/index.rst
    plugin_tutorials/index.rst
    configuration/index.rst

migration/Jazzy.rst

@@ -13,7 +13,7 @@ it also allows for rejection of stale velocity messages, which can be useful in
 Your robot should now subscribe to a ``TwistStamped`` message instead of a ``Twist`` message & update your simulation appropriately.
 The topic names are the same.
 
-However, this can be disabled by setting ``enable_twist_stamped`` to ``false`` in the ``nav2_params.yaml`` file for all nodes that involve Twist subscriptions or publications.
+However, this can be disabled by setting ``enable_stamped_cmd_vel`` to ``false`` in the ``nav2_params.yaml`` file for all nodes that involve Twist subscriptions or publications.
 See the configuration guide for more information on how to configure this parameter for each node.
 
 An example simulation migration using Gazebo can be seen in the `following pull request for the Turtlebot 3 and 4 <https://github.com/ros-navigation/nav2_minimal_turtlebot_simulation/pull/16>`_.
@@ -200,6 +200,21 @@ Default value:
 
 - false
 
+New Plugin Container Layer
+**************************
+
+In `PR #4781 <https://github.com/ros-navigation/navigation2/pull/4781>`_ a costmap layer plugin type was added to support the grouping of different costmap layers under a single costmap layer. This would allow for different isolated combinations of costmap layers to be combined under one parent costmap instead of the current implementation which would indiscriminately combine all costmap layers together.
+
+Iterative Target Selection for the Graceful Controller
+******************************************************
+
+In `PR #4795 <https://github.com/ros-navigation/navigation2/pull/4795>`_ the ``nav2_graceful_controller`` was updated to iteratively select motion targets. This is a large refactor which significantly improves the performance of the controller. The ``motion_target_dist`` parameter has been replaced by ``min_lookahead`` and ``max_lookahead`` parameters. Additional changes include:
+
+* Improved defaults for ``k_phi``, ``k_delta``, ``beta`` parameters of the underlying control law.
+* Automatic creation of orientations for the plan if they are missing.
+* Addition of ``v_angular_min_in_place`` parameter to avoid the robot getting stuck while rotating due to mechanical limitations.
+* ``final_rotation`` has been renamed ``prefer_final_rotation`` and the behavior has changed slightly.
+
 Introduction of PoseStampedArray
 ********************************
 

plugin_tutorials/docs/writing_new_behavior_plugin.rst

@@ -164,7 +164,7 @@ It is good practice to place these lines at the end of the file but technically,
 2. Next step would be to create plugin's description file in the root directory of the package. For example, ``behavior_plugin.xml`` file in our tutorial package. This file contains following information
 
  - ``library path``: Plugin's library name and it's location.
- - ``class name``: Name of the class.
+ - ``class name``: Name of the class (optional). If not set, it will default to the ``class type``.
  - ``class type``: Type of class.
  - ``base class``: Name of the base class.
  - ``description``: Description of the plugin.

plugin_tutorials/docs/writing_new_costmap2d_plugin.rst

@@ -230,6 +230,7 @@ In this case each plugin object will be handled by its own parameters tree in a
     plugin: nav2_gradient_costmap_plugin::GradientLayer # In Iron and older versions, "/" was used instead of "::"
     enabled: False
     ...
+NOTE: the order in which plugins are listed in the configuration is significant, as it determines the sequence in which they are applied to the costmap. For example, if the inflation layer is listed before the range layer, obstacles added to the costmap by the range layer will not be inflated.
 
 4- Run GradientLayer plugin
 ---------------------------

plugin_tutorials/docs/writing_new_nav2controller_plugin.rst

@@ -221,7 +221,7 @@ It is good practice to place these lines at the end of the file, but technically
 2. The next step would be to create the plugin's description file in the root directory of the package. For example, ``pure_pursuit_controller_plugin.xml`` file in our tutorial package. This file contains the following information
 
 - ``library path``: Plugin's library name and its location.
-- ``class name``: Name of the class.
+- ``class name``: Name of the class (optional). If not set, it will default to the ``class type``.
 - ``class type``: Type of class.
 - ``base class``: Name of the base class.
 - ``description``: Description of the plugin.

plugin_tutorials/docs/writing_new_nav2planner_plugin.rst

@@ -154,7 +154,7 @@ It is good practice to place these lines at the end of the file, but technically
 2. Next step would be to create plugin's description file in the root directory of the package. For example, ``global_planner_plugin.xml`` file in our tutorial package. This file contains the following information
 
  - ``library path``: Plugin's library name and its location.
- - ``class name``: Name of the class.
+ - ``class name``: Name of the class (optional). If not set, it will default to the ``class type``.
  - ``class type``: Type of class.
  - ``base class``: Name of the base class.
  - ``description``: Description of the plugin.

plugin_tutorials/docs/writing_new_navigator_plugin.rst

@@ -280,7 +280,7 @@ It is good practice to place these lines at the end of the file, but technically
 2. The next step would be to create the plugin's description file in the root directory of the package. For example, ``navigator_plugin.xml`` file in our tutorial package. This file contains the following information
 
 - ``library path``: Plugin's library name and it's location.
-- ``class name``: Name of the class.
+- ``class name``: Name of the class (optional). If not set, it will default to the ``class type``.
 - ``class type``: Type of class.
 - ``base class``: Name of the base class.
 - ``description``: Description of the plugin.