diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index 7945da18bb..3707ad03f9 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 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 ----------- diff --git a/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst b/configuration/packages/nav2_controller-plugins/simple_goal_checker.rst index 531f69cc76..a2e6e8b935 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 and does not care which direction it ends in. See :ref:`tuning` for detailed information. 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! diff --git a/migration/Humble.rst b/migration/Humble.rst index bd73a4b621..c46a30ae3e 100644 --- a/migration/Humble.rst +++ b/migration/Humble.rst @@ -225,3 +225,8 @@ 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. diff --git a/tuning/index.rst b/tuning/index.rst index 854a5b3b55..1dc187419b 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. These work when it does not matter which orientation it ends in. + +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 ==============================