Merge branch 'master' of github.com:ros-navigation/docs.nav2.org

Author: SteveMacenski

configuration/packages/configuring-bt-navigator.rst

@@ -180,50 +180,6 @@ Parameters
   Description
     Topic on which odometry is published
 
-:goal_blackboard_id:
-
-  ====== =======
-  Type   Default
-  ------ -------
-  string "goal"
-  ====== =======
-
-  Description
-    Blackboard variable to use to supply the goal to the behavior tree for ``NavigateToPose``. Should match ports of BT XML file.
-
-:path_blackboard_id:
-
-  ====== =======
-  Type   Default
-  ------ -------
-  string "path"
-  ====== =======
-
-  Description
-    Blackboard variable to get the path from the behavior tree for ``NavigateThroughPoses`` feedback. Should match port names of BT XML file.
-
-:goals_blackboard_id:
-
-  ====== =======
-  Type   Default
-  ------ -------
-  string "goals"
-  ====== =======
-
-  Description
-    Blackboard variable to use to supply the goals to the behavior tree for ``NavigateThroughPoses``. Should match ports of BT XML file.
-
-:waypoint_statuses_blackboard_id:
-
-  ====== ===================
-  Type   Default
-  ------ -------------------
-  string "waypoint_statuses"
-  ====== ===================
-
-  Description
-    Blackboard variable to get the statuses of waypoints from the behavior tree for ``NavigateThroughPoses`` feedback/result. Should match ports of BT XML file.
-
 :error_code_name_prefixes:
 
   ============== ===========================
@@ -284,6 +240,28 @@ Parameters
 NavigateToPose Parameters
 *************************
 
+:``<navigate_to_pose_name>``.goal_blackboard_id:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string "goal"
+  ====== =======
+
+  Description
+    Blackboard variable to use to supply the goal to the behavior tree for ``NavigateToPose``. Should match ports of BT XML file.
+
+:``<navigate_to_pose_name>``.path_blackboard_id:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string "path"
+  ====== =======
+
+  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>``.enable_groot_monitoring:
 
   ============== =======
@@ -309,6 +287,39 @@ NavigateToPose Parameters
 NavigateThroughPoses Parameters
 *******************************
 
+:``<navigate_through_poses>``.goals_blackboard_id:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string "goals"
+  ====== =======
+
+  Description
+    Blackboard variable to use to supply the goals to the behavior tree for ``NavigateThroughPoses``. Should match ports of BT XML file.
+
+:``<navigate_through_poses>``.path_blackboard_id:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string "path"
+  ====== =======
+
+  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>``.waypoint_statuses_blackboard_id:
+
+  ====== ===================
+  Type   Default
+  ------ -------------------
+  string "waypoint_statuses"
+  ====== ===================
+
+  Description
+    Blackboard variable to get the statuses of waypoints from the behavior tree for ``NavigateThroughPoses`` feedback/result. Should match ports of BT XML file.
+
 :``<navigate_through_poses>``.enable_groot_monitoring:
 
   ============== =======

configuration/packages/configuring-regulated-pp.rst

@@ -361,7 +361,7 @@ Regulated Pure Pursuit Parameters
   ============== =============================
   Type           Default
   -------------- -----------------------------
-  double         2.0
+  double         -1.0
   ============== =============================
 
   Description
@@ -417,5 +417,5 @@ Example
         rotate_to_heading_min_angle: 0.785
         max_angular_accel: 3.2
         max_robot_pose_search_dist: 10.0
-        min_distance_to_obstacle: 2.0
+        min_distance_to_obstacle: 0.0
         stateful: true

configuration/packages/configuring-savitzky-golay-smoother.rst

@@ -19,6 +19,28 @@ This algorithm is deterministic and low-parameter. In the below image, some odd
 Savitzky-Golay Smoother Parameters
 **********************************
 
+:window_size:
+
+  ============== ===========================
+  Type           Default
+  -------------- ---------------------------
+  int            7
+  ============== ===========================
+
+  Description
+    Size of the smoothing window. Must be an odd integer, with a minimum value of 3
+
+:poly_order:
+
+  ============== ===========================
+  Type           Default
+  -------------- ---------------------------
+  int            3
+  ============== ===========================
+
+  Description
+    Order of the polynomial used to fit the samples in each smoothing window
+
 :do_refinement:
 
   ============== ===========================
@@ -65,6 +87,8 @@ Example
         smoother_plugins: ["savitzky_golay_smoother"]
         savitzky_golay_smoother:
           plugin: "nav2_smoother::SavitzkyGolaySmoother"
+          window_size: 7
+          poly_order: 3
           do_refinement: True
           refinement_num: 2
           enforce_path_inversion: True

maintainer_docs/distribution_syncs.rst

@@ -0,0 +1,99 @@
+.. _distribution_sync_docs:
+
+ROS Distribution Sync Process
+#############################
+
+This is the instructions for updating a Nav2 version in a ROS distribution sync.
+We do this by bulk cherry picking commits from the ``main`` branch after they've had time to soak and apply them to the branch we looking to sync with the newest features.
+
+0. Initial Setup
+----------------
+
+First we need to create a temporary workspace to perform the sync.
+Typically, this is done in the ``/tmp`` directory so that it is cleaned up after a reboot.
+
+.. code-block:: bash
+
+  mkdir -p /tmp/sync_ws/src
+  cd /tmp/sync_ws/src
+  git clone https://github.com/ros-navigation/navigation2.git -b <distro>
+  cd navigation2
+  git checkout -b sync_<distro>
+
+Then, we want to get a list of all of the commits we may be interested in backporting.
+This can be found either in the git logs of the ``main`` branch or using the GitHub UX at https://github.com/ros-navigation/navigation2/commits/ and select the branch you are interested in.
+If using GitHub, open two tabs - one for ``main`` and one for ``<distro>``.
+
+Finally, we need to identify the date of the last sync.
+This can be found looking in the commit messages for ``<distro>``'s branch or by looking at the release page for Nav2 and finding the date of the last release for that distribution.
+Scroll back in the ``main`` and ``<distro>`` git logs to find the last sync commit to begin.
+
+Once you have a local clone, the git logs, and the date of the last sync, we can begin the process.
+
+1. Backporting Process
+----------------------
+
+Starting with the first commit in ``main`` after the last sync date, we will look at each commit individually.
+Each commit should be evaluated for the following criteria:
+
+- Cannot change default out-of-the-box behavior or existing configured robot behavior
+- Cannot change major end-user ABI/API
+- Cannot change message, action, or service definitions
+- Cannot include risky changes that need more time to soak, such as for complete package rewrites or experimental features
+
+If it does not do any of the above, it is a candidate for backporting.
+It can be backported via the following command in your local branch:
+
+.. code-block:: bash
+
+  git cherry-pick <commit_hash>
+
+
+If this merges without issue, you may proceed.
+If not, we either must resolve the conflicts or roll back the commit.
+We may need to roll it back if the merge conflict is too complex or it relies on a cascading chain of other commits that could not be included due to their dependency on commits that were unable to be backported.
+
+.. note::
+
+   Some commits may already have been backported by Mergify.
+   Use the git logs for the ``<distro>`` branch to check if the commit has already been backported.
+   If it has been, it can be skipped.
+
+Once all commits to the present are evaluated, we can proceed to the next step.
+
+2. Testing
+----------
+
+Before we can merge our changes, we need to ensure that everything is working correctly.
+This involves compiling the code, running any unit tests, and performing functional testing.
+Navigate back to the root of the workspace and build the code:
+
+.. code-block:: bash
+
+  cd ../../
+  colcon build
+  source install/setup.bash
+
+After building, we can run the tests:
+
+.. code-block:: bash
+
+  colcon test
+
+
+If all tests pass, we can launch the Nav2 bringup demos and navigate the TB3 and TB4 robots in both Gazebo and the loopback simulator for 10-15 minutes to validate functional stability of the backport.
+
+3. Open a PR
+------------
+
+Once we have validated the changes, we can open a pull request (PR) against the ``<distro>`` branch.
+Increment the package.xml versions for all packages using search and replace to increment one minor version (i.e. 1.1.X).
+Open a PR with the title ``<Branch> Sync: <Date>`` and include a description of the changes made.
+Let CI run and merge once passes for a second independent validation of compilation and testing.
+
+4. Bloom Release
+----------------
+
+Once the PR is merged, we can release the changes to the distribution.
+Create a release of the same version as the ``package.xml`` files targeting the ``<distro>`` branch.
+Then, follow `Steve's Bloom Release Guide <https://gist.github.com/SteveMacenski/1c321d1c9edca096ae4d763d8327c2ee>`_ to perform the bloom release.

maintainer_docs/index.rst

@@ -10,3 +10,4 @@ These are published publicly for visibility and as a resource for the maintainer
    :maxdepth: 1
 
    distribution_release.rst
+   distribution_syncs.rst

migration/Kilted.rst

@@ -197,13 +197,13 @@ Now, it supports future extensions for lifecycle subscriptions or additional wra
 Additionally, it supports QoS override using the parameter ``allow_parameter_qos_overrides``.
 
 Removed Parameter action_server_result_timeout
-**********************************************
+----------------------------------------------
 
 Removed the parameter ``action_server_result_timeout`` from all action servers after resolution within ``rcl`` and ``rclcpp`` to address early goal removal.
 This is not longer required to be set.
 
 Added Corner Smoothing functionality to route_server
-****************************************************
+----------------------------------------------------
 
 In `PR #5226 <https://github.com/ros-navigation/navigation2/pull/5226>`_ the ability to stitch two successive edges in ``route_server`` with a smooth circular arc has been added. Below is an example of two successive edges forming a corner being smoothed with a radius of one. The red lines are the edges of the route graph and the green line is the resultant path that can be used by a local planner.
 
@@ -212,22 +212,22 @@ In `PR #5226 <https://github.com/ros-navigation/navigation2/pull/5226>`_ the abi
 New parameters include ``smooth_corners`` which enable or disable corner smoothing and ``smoothing_radius`` which specifies the radius of the corner to fit to a corner. The tangents of the starting and ending points of the circular arc will match the tangent of the edges that form the corner. In the event that two edges are basically straight, no corner arc is added and regular linear interpolation is done. In addition to that, if the corner arc requires a starting point and ending point that's longer than the edge lengths, then it will not add a corner arc.
 
 Added NonblockingSequence Control Node
-**************************************
+--------------------------------------
 
 In `PR #5325 <https://github.com/ros-navigation/navigation2/pull/5325>`_ a new Nav2 specific behavior tree control node has been added. The new behavior tree control node, ``NonblockingSequence``, allows every child node in the sequence to be ticked through even if one of the child node returns ``RUNNING``. This is done to prevent long running child nodes from blocking the sequence.
 
 For additional details regarding the ``NonblockingSequence`` please see the `Nav2 specific node walkthrough <../behavior_trees/overview/nav2_specific_nodes.html>`_ and `NonblockingSequence configuration guide <../configuration/packages/bt-plugins/controls/NonblockingSequence.html>`_.
 
 MPPI Optimal Trajectory Validator Plugin
-****************************************
+----------------------------------------
 
 The MPPI controller now has a plugin, ``OptimalTrajectoryValidator``, which can be used to validate an output trajectory for execution.
 This can be used to check for collisions, margin from obstacles, distance from a path, progress being made, etc.
 By default, it uses the ``DefaultOptimalTrajectoryValidator`` which checks for collisions.
 Note that kinematic and dynamic constraints are not required to be checked as the Optimizer ensures these constraints are met.
 
 Added PersistentSequence and PauseResumeController Control Nodes
-****************************************************************
+----------------------------------------------------------------
 
 In `PR #5247 <https://github.com/ros-navigation/navigation2/pull/5247>`_ two new Nav2 specific behavior tree control nodes have been added.
 
@@ -289,3 +289,72 @@ Below are measured bandwidth values for different transport types with default p
 +------------------+----------------+
 | zlib             | 121.95         |
 +------------------+----------------+
+
+Private BT Navigator's BlackBoard ID parameters
+-----------------------------------------------
+
+The parameters ``xx_blackboard_id`` used in the BT navigator to specify the name of the blackboard variables from the
+behavior trees were moved into the respective navigators. They now have to be specified under the namespace of the particular navigator.
+
+These parameters are:
+
+ - NavigateToPose:
+
+  - ``<navigate_to_pose_name>.goal_blackboard_id``
+  - ``<navigate_to_pose_name>.path_blackboard_id``
+
+ - NavigateThroughPoses:
+
+  - ``<navigate_through_poses_name>.goals_blackboard_id``
+  - ``<navigate_through_poses_name>.path_blackboard_id``
+  - ``<navigate_through_poses_name>.waypoint_statuses_blackboard_id``
+
+ - CoverageNavigator:
+
+  - ``<coverage_navigator_name>.path_blackboard_id``
+  - ``<coverage_navigator_name>.field_file_blackboard_id``
+  - ``<coverage_navigator_name>.field_polygon_blackboard_id``
+  - ``<coverage_navigator_name>.polygon_frame_blackboard_id``
+
+Example:
+
+.. code-block:: yaml
+
+  bt_navigator:
+    ros__parameters:
+      other parameters: ....
+
+      navigate_to_pose:
+        plugin: "nav2_bt_navigator::NavigateToPoseNavigator"
+        enable_groot_monitoring: false
+        groot_server_port: 1667
+        goal_blackboard_id: "goal"
+        path_blackboard_id: "path"
+
+      navigate_through_poses:
+        plugin: "nav2_bt_navigator::NavigateThroughPosesNavigator"
+        enable_groot_monitoring: false
+        groot_server_port: 1669
+        goals_blackboard_id: "goals"
+        path_blackboard_id: "path"
+        waypoint_statuses_blackboard_id: "waypoint_statuses"
+
+      navigate_complete_coverage:
+        plugin: "opennav_coverage_navigator/CoverageNavigator"
+        path_blackboard_id: "path"
+        field_file_blackboard_id: "field_filepath"
+        field_polygon_blackboard_id: "field_polygon"
+        polygon_frame_blackboard_id: "polygon_frame_id"
+
+See also :ref:`configuring_bt_navigator`
+
+Option to have custom window size and poly order in Savitsky-Golay Smoother
+---------------------------------------------------------------------------
+
+In `PR #5489 <https://github.com/ros-navigation/navigation2/pull/5489>`_, option to have custom window size and polynomial order was added.
+Previously, the implementation used a fixed window size of 7 and a polynomial order of 3.
+
+Default value:
+
+- window_size: 7
+- poly_order: 3