Merge remote-tracking branch 'nav2/master'

Author: tonynajjar

.codespell_words

@@ -4,3 +4,4 @@ implementors
 retuned
 segway
 lightening
+statics

README.md

@@ -33,6 +33,17 @@ pip3 install -r requirements.txt
 ### Build the Docs
 Build the docs locally with `make html` and you'll find the built docs entry point in `_build/html/index.html`.
 
+To automate the build process, you can use a [sphinx-autobuild](https://github.com/sphinx-doc/sphinx-autobuild) package. \
+Run this command from the virtual environment to build the documentation and start a server:
+
+```bash
+sphinx-autobuild . ./_build/html
+```
+For more options for the command, see the documentation linked above.
+
+Now you can access the page using the local address: http://127.0.0.1:8000. \
+After saving any changes, the documentation will be automatically rebuilt and displayed.
+
 Any images, diagrams, or videos are subject to their own copyrights, trademarks, and licenses.
 
 Want a local PDF version? Follow the [instructions here](https://gist.github.com/alfredodeza/7fb5c667addb1c6963b9).

commander_api/index.rst

@@ -14,7 +14,7 @@ You may use this simple commander preempt commands of the same type (e.g. you ca
 
 .. code-block:: python3
 
-  from nav2_simple_commander.robot_navigator import BasicNavigator
+  from nav2_simple_commander.robot_navigator import BasicNavigator, TaskResult
   import rclpy
 
   rclpy.init()

concepts/index.rst

@@ -52,7 +52,7 @@ After, it is possible to activate the node by transitioning through the activati
 
 This state will allow the node to process information and be fully setup to run.
 The configuration stage, triggering the ``on_configure()`` method, will setup all parameters, ROS networking interfaces, and for safety systems, all dynamically allocated memory.
-The activation stage, triggering the ``on_activate()`` method, will active the ROS networking interfaces and set any states in the program to start processing information.
+The activation stage, triggering the ``on_activate()`` method, will activate the ROS networking interfaces and set any states in the program to start processing information.
 
 To shutdown, we transition into deactivating, cleaning up, shutting down and end in the finalized state.
 The networking interfaces are deactivated and stop processing, deallocate memory, exit cleanly, in those stages, respectively.

configuration/packages/bt-plugins/actions/FollowPath.rst

@@ -113,10 +113,22 @@ Output Ports
   Description
         Follow path error message. See ``FollowPath`` action for the enumerated set of error code definitions.
 
+:tracking_feedback:
+
+  ================================ =======
+  Type                             Default
+  -------------------------------- -------
+  nav2_msgs::msg::TrackingFeedback N/A
+  ================================ =======
+
+  Description
+        Tracking feedback message from the controller server, including cross track error, current path index, remaining path length, etc.
+
+
 
 Example
 -------
 
 .. code-block:: xml
 
-    <FollowPath path="{path}" controller_id="FollowPath" goal_checker_id="precise_goal_checker" path_handler_id="PathHandler" server_name="FollowPath" server_timeout="10" error_code_id="{follow_path_error_code}" error_msg="{follow_path_error_msg}"/>
+    <FollowPath path="{path}" controller_id="FollowPath" goal_checker_id="precise_goal_checker" path_handler_id="PathHandler" server_name="FollowPath" server_timeout="10" error_code_id="{follow_path_error_code}" error_msg="{follow_path_error_msg}" tracking_feedback="{tracking_feedback}"/>

configuration/packages/bt-plugins/conditions/IsGoalNearby.rst

@@ -0,0 +1,87 @@
+.. _bt_is_goal_nearby_condition:
+
+IsGoalNearby
+============
+
+Checks if the robot is near the goal by computing the remaining path length from the robot's current position to the goal. Returns SUCCESS when the remaining path length is less than the proximity threshold, otherwise returns FAILURE.
+
+Parameter
+---------
+
+:transform_tolerance:
+
+  Defined and declared in :ref:`configuring_bt_navigator`.
+
+Example
+^^^^^^^
+.. code-block:: yaml
+
+    bt_navigator:
+      ros__parameters:
+        # other bt_navigator parameters
+        transform_tolerance: 0.1
+
+Input Ports
+-----------
+
+:path:
+
+  ==================================== =======
+  Type                                 Default
+  ------------------------------------ -------
+  nav_msgs::msg::Path                  N/A
+  ==================================== =======
+
+  Description
+    The planned path to evaluate.
+
+:proximity_threshold:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  double 1.0
+  ====== =======
+
+  Description
+    The remaining path length (in meters) considered as "nearby". When the remaining distance along the path is less than this threshold, the condition returns SUCCESS.
+
+:max_robot_pose_search_dist:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  double -1.0
+  ====== =======
+
+  Description
+    Maximum forward integrated distance along the path (starting from the last detected pose) to bound the search for the closest pose to the robot. When set to a negative value (default), the entire path is searched every time. Setting this to a positive value (e.g., 1.0-2.0 meters) can improve performance when this BT node is ticked frequently to address looping or crossed paths (when present).
+
+:global_frame:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string "map"
+  ====== =======
+
+  Description
+    The global reference frame.
+
+:robot_base_frame:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string "base_link"
+  ====== =======
+
+  Description
+    Robot base frame.
+
+Example
+^^^^^^^
+
+.. code-block:: xml
+
+  <IsGoalNearby path="{path}" proximity_threshold="1.0" />

configuration/packages/bt-plugins/conditions/IsPathValid.rst

@@ -3,9 +3,10 @@
 IsPathValid
 ===========
 
-Checks to see if the global path is valid. If there is a
+Checks to see if the global path is valid. If there is an
 obstacle along the path, the condition returns FAILURE, otherwise
-it returns SUCCESS.
+it returns SUCCESS. Optionally checks specific costmap layers and
+can use a custom footprint for validation.
 
 Input Ports
 -----------
@@ -54,10 +55,90 @@ Input Ports
   Description
     Whether to consider unknown cost (255) as obstacle.
 
+:layer_name:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string ""
+  ====== =======
+
+  Description
+    Name of the specific costmap layer to check against.
+    If empty, checks against the full costmap.
+
+:footprint:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string ""
+  ====== =======
+
+  Description
+    Custom footprint specification as a bracketed array of arrays,
+    e.g., "[[x1,y1],[x2,y2],...]". If empty, uses the robot's
+    configured footprint.
+
+:check_full_path:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  bool   false
+  ====== =======
+
+  Description
+    Whether to check all poses in the path (true) or stop at the
+    first invalid pose (false). When true, all collision poses
+    are reported.
+
+Output Ports
+------------
+
+:collision_poses:
+
+  ============================================ =======
+  Type                                         Default
+  -------------------------------------------- -------
+  std::vector<geometry_msgs::msg::PoseStamped> N/A
+  ============================================ =======
+
+  Description
+    Vector of poses in the path that are in collision or invalid.
+    Empty if the path is valid.
+
 
 Example
 -------
 
 .. code-block:: xml
 
-    <IsPathValid server_timeout="10" path="{path}" max_cost="100" consider_unknown_as_obstacle="false" />
+    <IsPathValid
+      server_timeout="10"
+      path="{path}"
+      max_cost="100"
+      consider_unknown_as_obstacle="false"
+      layer_name=""
+      footprint=""
+      check_full_path="false"
+      collision_poses="{collision_poses}" />
+
+With custom footprint:
+
+.. code-block:: xml
+
+    <IsPathValid
+      path="{path}"
+      footprint="[[0.5,0.5],[0.5,-0.5],[-0.5,-0.5],[-0.5,0.5]]"
+      collision_poses="{collision_poses}" />
+
+Checking a specific costmap layer:
+
+.. code-block:: xml
+
+    <IsPathValid
+      path="{path}"
+      layer_name="obstacle_layer"
+      check_full_path="true"
+      collision_poses="{collision_poses}" />

configuration/packages/configuring-amcl.rst

@@ -276,6 +276,20 @@ Parameters
   Description
     Particle filter population density. 2.33 is the 99% percentile.
 
+:random_seed:
+
+  ============== =============================
+  Type           Default
+  -------------- -----------------------------
+  int            -1
+  ============== =============================
+
+  Description
+    Seed for the particle filter RNG.
+
+    - ``random_seed >= 0``: seed the RNG with the provided value (repeatable runs).
+    - ``random_seed < 0`` (default): seed the RNG from time (preserves historical behavior).
+
 :recovery_alpha_fast:
 
   ============== =============================
@@ -540,6 +554,7 @@ Example
         odom_frame_id: "odom"
         pf_err: 0.05
         pf_z: 0.99
+        random_seed: -1
         recovery_alpha_fast: 0.0
         recovery_alpha_slow: 0.0
         resample_interval: 1

configuration/packages/configuring-bt-navigator.rst

@@ -113,6 +113,18 @@ Parameters
     Default timeout value (in milliseconds) while a BT action node is waiting for acknowledgement from an action server.
     This value will be overwritten for a BT node if the input port "server_timeout" is provided.
 
+:default_cancel_timeout:
+
+  ==== =======
+  Type Default
+  ---- -------
+  int  50
+  ==== =======
+
+  Description
+    Default timeout (in seconds) for BT action node cancellation requests during node halt.
+    This value will be overwritten for a BT node if the input port "cancel_timeout" is provided.
+
 :wait_for_service_timeout:
 
   ==== =======
@@ -272,6 +284,17 @@ NavigateToPose Parameters
   Description
     Blackboard variable to get the path from the behavior tree for ``NavigateToPose`` feedback. Should match port names of BT XML file.
 
+:``<navigate_to_pose_name>``.tracking_feedback_blackboard_id:
+
+  ====== ===================
+  Type   Default
+  ------ -------------------
+  string "tracking_feedback"
+  ====== ===================
+
+  Description
+    Blackboard variable to get the tracking feedback from the behavior tree for ``NavigateToPose`` feedback. Should match port names of BT XML file.
+
 :``<navigate_to_pose_name>``.enable_groot_monitoring:
 
   ============== =======
@@ -294,6 +317,17 @@ NavigateToPose Parameters
   Description
     The port number for the Groot2 server. Note: In Groot2, you only need to specify the server port value, not the publisher port, as it is always the server port +1. Therefore, in this case, to use another navigator, the next available port would be 1669.
 
+:``<navigate_to_pose_name>``.search_window:
+
+  ============== =============================
+  Type           Default
+  -------------- -----------------------------
+  double           2.0
+  ============== =============================
+
+  Description
+    How far (in meters) along the path the searching algorithm will look for the closest point.
+
 NavigateThroughPoses Parameters
 *******************************
 
@@ -319,6 +353,17 @@ NavigateThroughPoses Parameters
   Description
     Blackboard variable to get the path from the behavior tree for ``NavigateThroughPoses`` feedback. Should match port names of BT XML file.
 
+:``<navigate_through_poses>``.tracking_feedback_blackboard_id:
+
+  ====== ===================
+  Type   Default
+  ------ -------------------
+  string "tracking_feedback"
+  ====== ===================
+
+  Description
+    Blackboard variable to get the tracking feedback from the behavior tree for ``NavigateThroughPoses`` feedback. Should match port names of BT XML file.
+
 :``<navigate_through_poses>``.waypoint_statuses_blackboard_id:
 
   ====== ===================
@@ -352,6 +397,17 @@ NavigateThroughPoses Parameters
   Description
     The port number for the Groot2 server. Note: In Groot2, you only need to specify the server port value, not the publisher port, as it is always the server port +1. Therefore, in this case, to use another navigator, the next available port would be 1671.
 
+:``<navigate_through_poses>``.search_window:
+
+  ============== =============================
+  Type           Default
+  -------------- -----------------------------
+  double           2.0
+  ============== =============================
+
+  Description
+    How far (in meters) along the path the searching algorithm will look for the closest point.
+
 Example
 *******
 .. code-block:: yaml
@@ -362,6 +418,8 @@ Example
         robot_base_frame: base_link
         transform_tolerance: 0.1
         filter_duration: 0.3
+        default_server_timeout: 20
+        default_cancel_timeout: 50
         introspection_mode: "disabled"
         default_nav_to_pose_bt_xml: replace/with/path/to/bt.xml # or $(find-pkg-share my_package)/behavior_tree/my_nav_to_pose_bt.xml
         default_nav_through_poses_bt_xml: replace/with/path/to/bt.xml # or $(find-pkg-share my_package)/behavior_tree/my_nav_through_poses_bt.xml
@@ -377,10 +435,12 @@ Example
           plugin: "nav2_bt_navigator::NavigateToPoseNavigator" # In Iron and older versions, "/" was used instead of "::"
           enable_groot_monitoring: false
           groot_server_port: 1667
+          search_window: 2.0
         navigate_through_poses:
           plugin: "nav2_bt_navigator::NavigateThroughPosesNavigator" # In Iron and older versions, "/" was used instead of "::"
           enable_groot_monitoring: false
           groot_server_port: 1669
+          search_window: 2.0
         plugin_lib_names:
           - nav2_compute_path_to_pose_action_bt_node
           - nav2_follow_path_action_bt_node