From 18d243056121bdf28f2cd145d0049656457d3850 Mon Sep 17 00:00:00 2001 From: Sandeep Dutta Date: Wed, 17 Dec 2025 16:05:54 -0800 Subject: [PATCH 01/12] added documentation for symmetric_yaw_tolerance --- configuration/index.rst | 8 + configuration/packages/configuring-mppic.rst | 11 ++ .../simple_goal_checker.rst | 11 ++ .../packages/symmetric_yaw_tolerance.rst | 155 ++++++++++++++++++ migration/Humble.rst | 4 + 5 files changed, 189 insertions(+) create mode 100644 configuration/packages/symmetric_yaw_tolerance.rst diff --git a/configuration/index.rst b/configuration/index.rst index a16c91aa41..5751336684 100644 --- a/configuration/index.rst +++ b/configuration/index.rst @@ -59,6 +59,14 @@ Smoother Plugins packages/configuring-savitzky-golay-smoother.rst packages/configuring-simple-smoother.rst +Advanced Topics +*************** + +.. toctree:: + :maxdepth: 1 + + packages/symmetric_yaw_tolerance.rst + Others ****** diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index 7945da18bb..98a340ad47 100644 --- a/configuration/packages/configuring-mppic.rst +++ b/configuration/packages/configuring-mppic.rst @@ -551,6 +551,17 @@ This critic incentivizes navigating to achieve the angle of the goal posewhen in Description Minimal distance (m) between robot and goal above which angle goal cost considered. +:symmetric_yaw_tolerance: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + Enable symmetric goal orientation acceptance. When enabled, the critic prefers trajectories that approach the goal at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions. When enabled, the critic uses the minimum distance to either goal orientation, reducing the cost penalty for approaching from the backward direction. See :ref:`symmetric_yaw_tolerance_guide` for detailed information. + Goal Critic ----------- diff --git a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst index 531f69cc76..f016a8e275 100644 --- a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst +++ b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst @@ -42,3 +42,14 @@ Parameters Description Whether to check for XY position tolerance after rotating to goal orientation in case of minor localization changes. + +:````.symmetric_yaw_tolerance: + + ==== ======= + Type Default + ---- ------- + bool false + ==== ======= + + Description + Enable symmetric goal orientation acceptance. When enabled, the robot accepts the goal as reached when oriented at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions. See :ref:`symmetric_yaw_tolerance_guide` for detailed information. diff --git a/configuration/packages/symmetric_yaw_tolerance.rst b/configuration/packages/symmetric_yaw_tolerance.rst new file mode 100644 index 0000000000..68e3f4b671 --- /dev/null +++ b/configuration/packages/symmetric_yaw_tolerance.rst @@ -0,0 +1,155 @@ +.. _symmetric_yaw_tolerance_guide: + +Symmetric Yaw Tolerance for Goal Checking and Navigation +######################################################### + +Overview +******** + +The **symmetric_yaw_tolerance** parameter enables symmetric robots (that can drive equally well in both forward and backward directions) to reach goals without unnecessary 180° rotations. This feature is available in: + +- **GoalAngleCritic** (MPPI Controller) - for trajectory cost evaluation +- **SimpleGoalChecker** (Controller Server) - for goal achievement detection + +When enabled, these plugins accept either the goal orientation or the goal orientation + 180°, preventing the robot from wasting time and energy rotating when it could simply drive backward. + +Use Case +******** + +This feature is ideal for robots with symmetric mechanical designs, such as: + +- Differential drive robots with sensors on both ends +- Robots with bidirectional capabilities + +Without this feature, a standard goal checker or goal angle critic would force the robot to rotate 180° if it approaches the goal from the "wrong" direction, even when the robot could simply drive backward to the goal. + +How It Works +************ + +When ``symmetric_yaw_tolerance: true`` is set: + +**In GoalAngleCritic (MPPI Controller):** + The critic calculates the angular distance to both the goal orientation and the flipped goal orientation (goal + 180°), then uses the minimum of these two distances for trajectory scoring. This allows trajectories approaching from either direction to have lower costs. + +**In SimpleGoalChecker (Controller Server):** + The goal checker returns true if the robot is within tolerance of either orientation - the exact goal orientation OR the goal orientation + 180°. + +This allows the robot to: + +1. Approach the goal from either direction without penalty +2. Avoid unnecessary rotations when already facing away from the goal orientation +3. Select the most efficient trajectory based on current orientation +4. Accept goal achievement when facing backward (goal ± 180°) + +Enabling the Feature +******************** + +To enable symmetric yaw tolerance for your robot: + +**In the Goal Checker:** + +Add ``symmetric_yaw_tolerance: true`` to your SimpleGoalChecker configuration: + +.. code-block:: yaml + + controller_server: + ros__parameters: + goal_checker_plugins: ["goal_checker"] + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.15 + yaw_goal_tolerance: 0.15 + symmetric_yaw_tolerance: true + +**In the MPPI Controller:** + +Add ``symmetric_yaw_tolerance: true`` to your GoalAngleCritic configuration: + +.. code-block:: yaml + + controller_server: + ros__parameters: + FollowPath: + plugin: "nav2_mppi_controller::MPPIController" + + critics: + - "GoalAngleCritic" + + GoalAngleCritic: + cost_weight: 5.0 + cost_power: 1 + threshold_to_consider: 0.4 + symmetric_yaw_tolerance: true + +**Complete Example:** + +.. code-block:: yaml + + controller_server: + ros__parameters: + use_sim_time: false + controller_frequency: 30.0 + + # Goal checker with symmetric support + goal_checker_plugins: ["goal_checker"] + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.15 + yaw_goal_tolerance: 0.15 + stateful: true + symmetric_yaw_tolerance: true + + # Controller with symmetric support + controller_plugins: ["FollowPath"] + FollowPath: + plugin: "nav2_mppi_controller::MPPIController" + time_steps: 56 + model_dt: 0.05 + batch_size: 2000 + motion_model: "DiffDrive" + + critics: + - "ConstraintCritic" + - "GoalCritic" + - "GoalAngleCritic" + - "PathAlignCritic" + + ConstraintCritic: + cost_weight: 4.0 + GoalCritic: + cost_weight: 5.0 + threshold_to_consider: 1.4 + GoalAngleCritic: + cost_weight: 5.0 + threshold_to_consider: 0.4 + symmetric_yaw_tolerance: true + PathAlignCritic: + cost_weight: 10.0 + +Configuration Options +********************* + +Both plugins can be configured independently. You can enable one, the other, or both depending on your needs: + +**Only Goal Checker Enabled:** + The robot accepts goals as reached when facing either direction (goal or goal ± 180°), but trajectory planning doesn't prefer the backward approach. Useful if you want goal flexibility without trajectory planning changes. + +**Only Goal Angle Critic Enabled:** + The trajectory planner prefers minimal rotation and approaches that minimize angle difference, but the goal is only marked as reached in the exact orientation. Useful for partial trajectory optimization. + +**Both Enabled:** + Complete symmetric support - trajectory planning prefers efficient approach AND goal acceptance is orientation-agnostic. **Recommended** for full symmetric robot support. + +**Expected Behavior:** + +- With ``symmetric_yaw_tolerance: true``, the robot should accept goals when approaching from either direction +- GoalAngleCritic should prefer minimal rotation when within threshold_to_consider +- Robot should achieve goal without unnecessary 180° rotations + +Related Documentation +********************* + +- :ref:`configuring_mppic` - MPPI Controller configuration guide +- :ref:`configuring_controller_server` - Controller Server configuration guide +- `Nav2 MPPI Controller Documentation `_ +- `Nav2 Goal Checker Plugins `_ diff --git a/migration/Humble.rst b/migration/Humble.rst index bd73a4b621..de27cd456b 100644 --- a/migration/Humble.rst +++ b/migration/Humble.rst @@ -225,3 +225,7 @@ More information about ``Denoise Layer`` plugin and how it works could be found SmacPlannerHybrid viz_expansions parameter ****************************************** `PR #3577 `_ adds a new parameter for visualising SmacPlannerHybrid expansions for debug purpose. + +Symmetric Yaw Tolerance for Goal Checking and Navigation +******************************************************** +`PR #5795 `_ introduces the symmetric yaw tolerance feature for goal checking and navigation, allowing symmetric robots to reach goals without unnecessary 180° rotations. \ No newline at end of file From 576936ba3adffa7d54c7834ecd483e18f641b40e Mon Sep 17 00:00:00 2001 From: Sandeep Dutta Date: Wed, 17 Dec 2025 16:05:54 -0800 Subject: [PATCH 02/12] added documentation for symmetric_yaw_tolerance addressed comments on PR --- configuration/index.rst | 7 - configuration/packages/configuring-mppic.rst | 2 +- .../simple_goal_checker.rst | 2 +- tuning/index.rst | 147 ++++++++++++++++++ 4 files changed, 149 insertions(+), 9 deletions(-) diff --git a/configuration/index.rst b/configuration/index.rst index 5751336684..01c1254a83 100644 --- a/configuration/index.rst +++ b/configuration/index.rst @@ -59,13 +59,6 @@ Smoother Plugins packages/configuring-savitzky-golay-smoother.rst packages/configuring-simple-smoother.rst -Advanced Topics -*************** - -.. toctree:: - :maxdepth: 1 - - packages/symmetric_yaw_tolerance.rst Others ****** diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index 98a340ad47..ad746d4257 100644 --- a/configuration/packages/configuring-mppic.rst +++ b/configuration/packages/configuring-mppic.rst @@ -560,7 +560,7 @@ This critic incentivizes navigating to achieve the angle of the goal posewhen in ============== =========================== Description - Enable symmetric goal orientation acceptance. When enabled, the critic prefers trajectories that approach the goal at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions. When enabled, the critic uses the minimum distance to either goal orientation, reducing the cost penalty for approaching from the backward direction. See :ref:`symmetric_yaw_tolerance_guide` for detailed information. + Enable symmetric goal orientation acceptance. When enabled, the critic prefers trajectories that approach the goal at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions. When enabled, the critic uses the minimum distance to either goal orientation, reducing the cost penalty for approaching from the backward direction. See :ref:`tuning` for detailed information. Goal Critic ----------- diff --git a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst index f016a8e275..97d1bd1f66 100644 --- a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst +++ b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst @@ -52,4 +52,4 @@ Parameters ==== ======= Description - Enable symmetric goal orientation acceptance. When enabled, the robot accepts the goal as reached when oriented at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions. See :ref:`symmetric_yaw_tolerance_guide` for detailed information. + Enable symmetric goal orientation acceptance. When enabled, the robot accepts the goal as reached when oriented at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions. See :ref:`tuning` for detailed information. diff --git a/tuning/index.rst b/tuning/index.rst index 854a5b3b55..09594a30ab 100644 --- a/tuning/index.rst +++ b/tuning/index.rst @@ -168,6 +168,153 @@ Within ``nav2_bringup``, there is a main entryfile ``tb3_simulation_launch.py``. - ``robot_sdf`` : The filepath to the robot's gazebo configuration file containing the Gazebo plugins and setup to simulate the robot system. - ``x_pose``, ``y_pose``, ``z_pose``, ``roll``, ``pitch``, ``yaw`` : Parameters to set the initial position of the robot in the simulation. + +Symmetric Yaw Tolerance for Goal Checking and Navigation +######################################################### + +Overview +******** + +The **symmetric_yaw_tolerance** parameter enables symmetric robots (that can drive equally well in both forward and backward directions) to reach goals without unnecessary 180° rotations. This feature is available in: + +- **GoalAngleCritic** (MPPI Controller) - for trajectory cost evaluation +- **SimpleGoalChecker** (Controller Server) - for goal achievement detection + +When enabled, these plugins accept either the goal orientation or the goal orientation + 180°, preventing the robot from wasting time and energy rotating when it could simply drive backward. + +Use Case +******** + +This feature is ideal for robots with symmetric mechanical designs, such as: + +- Differential drive robots with sensors on both ends +- Robots with bidirectional capabilities + +Without this feature, a standard goal checker or goal angle critic would force the robot to rotate 180° if it approaches the goal from the "wrong" direction, even when the robot could simply drive backward to the goal. + +How It Works +************ + +When ``symmetric_yaw_tolerance: true`` is set: + +**In GoalAngleCritic (MPPI Controller):** + The critic calculates the angular distance to both the goal orientation and the flipped goal orientation (goal + 180°), then uses the minimum of these two distances for trajectory scoring. This allows trajectories approaching from either direction to have lower costs. + +**In SimpleGoalChecker (Controller Server):** + The goal checker returns true if the robot is within tolerance of either orientation - the exact goal orientation OR the goal orientation + 180°. + +This allows the robot to: + +1. Approach the goal from either direction without penalty +2. Avoid unnecessary rotations when already facing away from the goal orientation +3. Select the most efficient trajectory based on current orientation +4. Accept goal achievement when facing backward (goal ± 180°) + +Enabling the Feature +******************** + +To enable symmetric yaw tolerance for your robot: + +**In the Goal Checker:** + +Add ``symmetric_yaw_tolerance: true`` to your SimpleGoalChecker configuration: + +.. code-block:: yaml + + controller_server: + ros__parameters: + goal_checker_plugins: ["goal_checker"] + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.15 + yaw_goal_tolerance: 0.15 + symmetric_yaw_tolerance: true + +**In the MPPI Controller:** + +Add ``symmetric_yaw_tolerance: true`` to your GoalAngleCritic configuration: + +.. code-block:: yaml + + controller_server: + ros__parameters: + FollowPath: + plugin: "nav2_mppi_controller::MPPIController" + + critics: + - "GoalAngleCritic" + + GoalAngleCritic: + cost_weight: 5.0 + cost_power: 1 + threshold_to_consider: 0.4 + symmetric_yaw_tolerance: true + +**Complete Example:** + +.. code-block:: yaml + + controller_server: + ros__parameters: + use_sim_time: false + controller_frequency: 30.0 + + # Goal checker with symmetric support + goal_checker_plugins: ["goal_checker"] + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.15 + yaw_goal_tolerance: 0.15 + stateful: true + symmetric_yaw_tolerance: true + + # Controller with symmetric support + controller_plugins: ["FollowPath"] + FollowPath: + plugin: "nav2_mppi_controller::MPPIController" + time_steps: 56 + model_dt: 0.05 + batch_size: 2000 + motion_model: "DiffDrive" + + critics: + - "ConstraintCritic" + - "GoalCritic" + - "GoalAngleCritic" + - "PathAlignCritic" + + ConstraintCritic: + cost_weight: 4.0 + GoalCritic: + cost_weight: 5.0 + threshold_to_consider: 1.4 + GoalAngleCritic: + cost_weight: 5.0 + threshold_to_consider: 0.4 + symmetric_yaw_tolerance: true + PathAlignCritic: + cost_weight: 10.0 + +Configuration Options +********************* + +Both plugins can be configured independently. You can enable one, the other, or both depending on your needs: + +**Only Goal Checker Enabled:** + The robot accepts goals as reached when facing either direction (goal or goal ± 180°), but trajectory planning doesn't prefer the backward approach. Useful if you want goal flexibility without trajectory planning changes. + +**Only Goal Angle Critic Enabled:** + The trajectory planner prefers minimal rotation and approaches that minimize angle difference, but the goal is only marked as reached in the exact orientation. Useful for partial trajectory optimization. + +**Both Enabled:** + Complete symmetric support - trajectory planning prefers efficient approach AND goal acceptance is orientation-agnostic. **Recommended** for full symmetric robot support. + +**Expected Behavior:** + +- With ``symmetric_yaw_tolerance: true``, the robot should accept goals when approaching from either direction +- GoalAngleCritic should prefer minimal rotation when within threshold_to_consider +- Robot should achieve goal without unnecessary 180° rotations + Other Pages We'd Love To Offer ============================== From 78d25192e427db87bfe8a6699480eb4de0a2a08e Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Fri, 19 Dec 2025 20:47:53 -0800 Subject: [PATCH 03/12] Update migration/Humble.rst Signed-off-by: Steve Macenski --- migration/Humble.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/migration/Humble.rst b/migration/Humble.rst index de27cd456b..bc6e434d8b 100644 --- a/migration/Humble.rst +++ b/migration/Humble.rst @@ -228,4 +228,5 @@ SmacPlannerHybrid viz_expansions parameter Symmetric Yaw Tolerance for Goal Checking and Navigation ******************************************************** + `PR #5795 `_ introduces the symmetric yaw tolerance feature for goal checking and navigation, allowing symmetric robots to reach goals without unnecessary 180° rotations. \ No newline at end of file From 860c44b3c48ee114fb52ed4a26c7c4ede1797751 Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Fri, 19 Dec 2025 20:48:01 -0800 Subject: [PATCH 04/12] Update configuration/index.rst Signed-off-by: Steve Macenski --- configuration/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/configuration/index.rst b/configuration/index.rst index 01c1254a83..a16c91aa41 100644 --- a/configuration/index.rst +++ b/configuration/index.rst @@ -59,7 +59,6 @@ Smoother Plugins packages/configuring-savitzky-golay-smoother.rst packages/configuring-simple-smoother.rst - Others ****** From cc2560bdcad6833c4ae257de3f6a903a5128d8e9 Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Fri, 19 Dec 2025 20:48:08 -0800 Subject: [PATCH 05/12] Update configuration/packages/configuring-mppic.rst Signed-off-by: Steve Macenski --- configuration/packages/configuring-mppic.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index ad746d4257..3707ad03f9 100644 --- a/configuration/packages/configuring-mppic.rst +++ b/configuration/packages/configuring-mppic.rst @@ -560,7 +560,7 @@ This critic incentivizes navigating to achieve the angle of the goal posewhen in ============== =========================== Description - Enable symmetric goal orientation acceptance. When enabled, the critic prefers trajectories that approach the goal at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions. When enabled, the critic uses the minimum distance to either goal orientation, reducing the cost penalty for approaching from the backward direction. See :ref:`tuning` for detailed information. + Enable symmetric goal orientation acceptance. When enabled, the critic prefers trajectories that approach the goal at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions and does not care which direction it ends in. When enabled, the critic uses the minimum distance to either goal orientation, reducing the cost penalty for approaching from the backward direction. See :ref:`tuning` for detailed information. Goal Critic ----------- From e7365fb7bc114a9548f636724468f77d22846555 Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Fri, 19 Dec 2025 20:48:15 -0800 Subject: [PATCH 06/12] Update configuration/packages/nav2_controller-plugins/simple_goal_checker.rst Signed-off-by: Steve Macenski --- .../packages/nav2_controller-plugins/simple_goal_checker.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst index 97d1bd1f66..52fbbcf228 100644 --- a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst +++ b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst @@ -52,4 +52,4 @@ Parameters ==== ======= Description - Enable symmetric goal orientation acceptance. When enabled, the robot accepts the goal as reached when oriented at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions. See :ref:`tuning` for detailed information. + Enable symmetric goal orientation acceptance. When enabled, the robot accepts the goal as reached when oriented at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions and does not care which it ends in. See :ref:`tuning` for detailed information. From 18ab234c9eaf80cbd14300e52775084263ff06f0 Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Fri, 19 Dec 2025 20:48:21 -0800 Subject: [PATCH 07/12] Update configuration/packages/symmetric_yaw_tolerance.rst Signed-off-by: Steve Macenski --- configuration/packages/symmetric_yaw_tolerance.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/packages/symmetric_yaw_tolerance.rst b/configuration/packages/symmetric_yaw_tolerance.rst index 68e3f4b671..5f55d6e493 100644 --- a/configuration/packages/symmetric_yaw_tolerance.rst +++ b/configuration/packages/symmetric_yaw_tolerance.rst @@ -1,7 +1,7 @@ .. _symmetric_yaw_tolerance_guide: Symmetric Yaw Tolerance for Goal Checking and Navigation -######################################################### +######################################################## Overview ******** From fc833d4e6e23c7daaf2935c31d7a1c8117e14a9a Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Fri, 19 Dec 2025 20:48:28 -0800 Subject: [PATCH 08/12] Update tuning/index.rst Signed-off-by: Steve Macenski --- tuning/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tuning/index.rst b/tuning/index.rst index 09594a30ab..f73bbfba29 100644 --- a/tuning/index.rst +++ b/tuning/index.rst @@ -170,7 +170,7 @@ Within ``nav2_bringup``, there is a main entryfile ``tb3_simulation_launch.py``. Symmetric Yaw Tolerance for Goal Checking and Navigation -######################################################### +######################################################## Overview ******** From 6c60a69435df49d596fc78d4bce4959e53faa4da Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Fri, 19 Dec 2025 20:48:35 -0800 Subject: [PATCH 09/12] Update tuning/index.rst Signed-off-by: Steve Macenski --- tuning/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/tuning/index.rst b/tuning/index.rst index f73bbfba29..2840f500f9 100644 --- a/tuning/index.rst +++ b/tuning/index.rst @@ -181,6 +181,7 @@ The **symmetric_yaw_tolerance** parameter enables symmetric robots (that can dri - **SimpleGoalChecker** (Controller Server) - for goal achievement detection When enabled, these plugins accept either the goal orientation or the goal orientation + 180°, preventing the robot from wasting time and energy rotating when it could simply drive backward. +These work when it does not matter which orientation it ends in. Use Case ******** From a922b4516474d88f643ee36ea12905929ea99401 Mon Sep 17 00:00:00 2001 From: Steve Macenski Date: Fri, 19 Dec 2025 20:19:17 -0800 Subject: [PATCH 10/12] Revise section titles and numbers in distribution_release.rst (#828) Signed-off-by: Steve Macenski --- maintainer_docs/distribution_release.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/maintainer_docs/distribution_release.rst b/maintainer_docs/distribution_release.rst index fe84288938..0852c43ae4 100644 --- a/maintainer_docs/distribution_release.rst +++ b/maintainer_docs/distribution_release.rst @@ -93,7 +93,15 @@ Finally, create the new distribution branch from ``main`` and push to the server Go into the GitHub Actions tab on ``nav2_docker`` and retrigger its build job. The nightly and release jobs should now exist for the new distribution and return successfully (validate this). -3. Setup Branch CI +3. Mark Branch as Protected +--------------------------- + +Go to the Repo Settings -> Branches. Create a branch protection rule for the new branch that matches the last. + +* Request a PR before merging -> Require approvals & override for infra-admins. +* Restrict who can push branches that match this rule. + +4. Setup Branch CI ------------------ The final change to the branch is to setup CI so PRs targeting it can be successfully built. @@ -108,7 +116,7 @@ Then, retrigger the Update CI Image workflow in Nav2's GitHub Actions tab, it sh Open a dummy PR against the new distribution branch and ensure that it builds successfully. -4. Update Auxiliary Projects +5. Update Auxiliary Projects ---------------------------- Nav2 has a number of auxiliary projects that also need to be updated for a new distribution. @@ -124,7 +132,7 @@ For each: * Update CI on the new branch to use this new distribution image * Review and update the readme as needed -5. Run Bloom Release +6. Run Bloom Release -------------------- Once the new branches, versions, and CI are setup and ready, we can run the bloom release process. @@ -136,7 +144,7 @@ Run the following command to create a new release for the distribution for each Be patient, this will take a while to run. -6. Nav2 Docker Build +7. Nav2 Docker Build -------------------- To allow the ``nav2_docker`` build of the released version in Step 5, we need to enable the first build to pass the latest tag check in the workflow. @@ -144,7 +152,7 @@ You should see that the nightly of this distribution works, but the release vers To resolve, comment out the ``exit 1`` in the ``latest_version`` validity check. Once the job turns over, revert this commit to reintroduce the error. -7. Announcements +8. Announcements ---------------- Finally, we can announce the updates! From e5031a2d3e5c449c629b5eaba775de72e6776644 Mon Sep 17 00:00:00 2001 From: Sandeep Dutta Date: Wed, 17 Dec 2025 16:05:54 -0800 Subject: [PATCH 11/12] updated Fixed PR comments Signed-off-by: Sandeep Dutta --- .../simple_goal_checker.rst | 2 +- .../packages/symmetric_yaw_tolerance.rst | 155 ------------------ tuning/index.rst | 3 +- 3 files changed, 2 insertions(+), 158 deletions(-) delete mode 100644 configuration/packages/symmetric_yaw_tolerance.rst diff --git a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst index 52fbbcf228..a2e6e8b935 100644 --- a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst +++ b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst @@ -52,4 +52,4 @@ Parameters ==== ======= Description - Enable symmetric goal orientation acceptance. When enabled, the robot accepts the goal as reached when oriented at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions and does not care which it ends in. See :ref:`tuning` for detailed information. + Enable symmetric goal orientation acceptance. When enabled, the robot accepts the goal as reached when oriented at either the goal orientation or the goal orientation + 180°. This is useful for symmetric robots (e.g., differential drives with sensors on both ends) that can navigate equally well in forward and backward directions and does not care which direction it ends in. See :ref:`tuning` for detailed information. diff --git a/configuration/packages/symmetric_yaw_tolerance.rst b/configuration/packages/symmetric_yaw_tolerance.rst deleted file mode 100644 index 5f55d6e493..0000000000 --- a/configuration/packages/symmetric_yaw_tolerance.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. _symmetric_yaw_tolerance_guide: - -Symmetric Yaw Tolerance for Goal Checking and Navigation -######################################################## - -Overview -******** - -The **symmetric_yaw_tolerance** parameter enables symmetric robots (that can drive equally well in both forward and backward directions) to reach goals without unnecessary 180° rotations. This feature is available in: - -- **GoalAngleCritic** (MPPI Controller) - for trajectory cost evaluation -- **SimpleGoalChecker** (Controller Server) - for goal achievement detection - -When enabled, these plugins accept either the goal orientation or the goal orientation + 180°, preventing the robot from wasting time and energy rotating when it could simply drive backward. - -Use Case -******** - -This feature is ideal for robots with symmetric mechanical designs, such as: - -- Differential drive robots with sensors on both ends -- Robots with bidirectional capabilities - -Without this feature, a standard goal checker or goal angle critic would force the robot to rotate 180° if it approaches the goal from the "wrong" direction, even when the robot could simply drive backward to the goal. - -How It Works -************ - -When ``symmetric_yaw_tolerance: true`` is set: - -**In GoalAngleCritic (MPPI Controller):** - The critic calculates the angular distance to both the goal orientation and the flipped goal orientation (goal + 180°), then uses the minimum of these two distances for trajectory scoring. This allows trajectories approaching from either direction to have lower costs. - -**In SimpleGoalChecker (Controller Server):** - The goal checker returns true if the robot is within tolerance of either orientation - the exact goal orientation OR the goal orientation + 180°. - -This allows the robot to: - -1. Approach the goal from either direction without penalty -2. Avoid unnecessary rotations when already facing away from the goal orientation -3. Select the most efficient trajectory based on current orientation -4. Accept goal achievement when facing backward (goal ± 180°) - -Enabling the Feature -******************** - -To enable symmetric yaw tolerance for your robot: - -**In the Goal Checker:** - -Add ``symmetric_yaw_tolerance: true`` to your SimpleGoalChecker configuration: - -.. code-block:: yaml - - controller_server: - ros__parameters: - goal_checker_plugins: ["goal_checker"] - goal_checker: - plugin: "nav2_controller::SimpleGoalChecker" - xy_goal_tolerance: 0.15 - yaw_goal_tolerance: 0.15 - symmetric_yaw_tolerance: true - -**In the MPPI Controller:** - -Add ``symmetric_yaw_tolerance: true`` to your GoalAngleCritic configuration: - -.. code-block:: yaml - - controller_server: - ros__parameters: - FollowPath: - plugin: "nav2_mppi_controller::MPPIController" - - critics: - - "GoalAngleCritic" - - GoalAngleCritic: - cost_weight: 5.0 - cost_power: 1 - threshold_to_consider: 0.4 - symmetric_yaw_tolerance: true - -**Complete Example:** - -.. code-block:: yaml - - controller_server: - ros__parameters: - use_sim_time: false - controller_frequency: 30.0 - - # Goal checker with symmetric support - goal_checker_plugins: ["goal_checker"] - goal_checker: - plugin: "nav2_controller::SimpleGoalChecker" - xy_goal_tolerance: 0.15 - yaw_goal_tolerance: 0.15 - stateful: true - symmetric_yaw_tolerance: true - - # Controller with symmetric support - controller_plugins: ["FollowPath"] - FollowPath: - plugin: "nav2_mppi_controller::MPPIController" - time_steps: 56 - model_dt: 0.05 - batch_size: 2000 - motion_model: "DiffDrive" - - critics: - - "ConstraintCritic" - - "GoalCritic" - - "GoalAngleCritic" - - "PathAlignCritic" - - ConstraintCritic: - cost_weight: 4.0 - GoalCritic: - cost_weight: 5.0 - threshold_to_consider: 1.4 - GoalAngleCritic: - cost_weight: 5.0 - threshold_to_consider: 0.4 - symmetric_yaw_tolerance: true - PathAlignCritic: - cost_weight: 10.0 - -Configuration Options -********************* - -Both plugins can be configured independently. You can enable one, the other, or both depending on your needs: - -**Only Goal Checker Enabled:** - The robot accepts goals as reached when facing either direction (goal or goal ± 180°), but trajectory planning doesn't prefer the backward approach. Useful if you want goal flexibility without trajectory planning changes. - -**Only Goal Angle Critic Enabled:** - The trajectory planner prefers minimal rotation and approaches that minimize angle difference, but the goal is only marked as reached in the exact orientation. Useful for partial trajectory optimization. - -**Both Enabled:** - Complete symmetric support - trajectory planning prefers efficient approach AND goal acceptance is orientation-agnostic. **Recommended** for full symmetric robot support. - -**Expected Behavior:** - -- With ``symmetric_yaw_tolerance: true``, the robot should accept goals when approaching from either direction -- GoalAngleCritic should prefer minimal rotation when within threshold_to_consider -- Robot should achieve goal without unnecessary 180° rotations - -Related Documentation -********************* - -- :ref:`configuring_mppic` - MPPI Controller configuration guide -- :ref:`configuring_controller_server` - Controller Server configuration guide -- `Nav2 MPPI Controller Documentation `_ -- `Nav2 Goal Checker Plugins `_ diff --git a/tuning/index.rst b/tuning/index.rst index 2840f500f9..1dc187419b 100644 --- a/tuning/index.rst +++ b/tuning/index.rst @@ -180,8 +180,7 @@ The **symmetric_yaw_tolerance** parameter enables symmetric robots (that can dri - **GoalAngleCritic** (MPPI Controller) - for trajectory cost evaluation - **SimpleGoalChecker** (Controller Server) - for goal achievement detection -When enabled, these plugins accept either the goal orientation or the goal orientation + 180°, preventing the robot from wasting time and energy rotating when it could simply drive backward. -These work when it does not matter which orientation it ends in. +When enabled, these plugins accept either the goal orientation or the goal orientation + 180°, preventing the robot from wasting time and energy rotating when it could simply drive backward. These work when it does not matter which orientation it ends in. Use Case ******** From 0f18c46f18048b44ae15e5844517db15ddb8f293 Mon Sep 17 00:00:00 2001 From: Sandeep Dutta Date: Wed, 17 Dec 2025 16:05:54 -0800 Subject: [PATCH 12/12] updated to fix pre-commit failure Signed-off-by: Sandeep Dutta --- migration/Humble.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/migration/Humble.rst b/migration/Humble.rst index bc6e434d8b..c46a30ae3e 100644 --- a/migration/Humble.rst +++ b/migration/Humble.rst @@ -229,4 +229,4 @@ SmacPlannerHybrid viz_expansions parameter Symmetric Yaw Tolerance for Goal Checking and Navigation ******************************************************** -`PR #5795 `_ introduces the symmetric yaw tolerance feature for goal checking and navigation, allowing symmetric robots to reach goals without unnecessary 180° rotations. \ No newline at end of file +`PR #5795 `_ introduces the symmetric yaw tolerance feature for goal checking and navigation, allowing symmetric robots to reach goals without unnecessary 180° rotations.