diff --git a/behavior_trees/images/walkthrough/contextual_recoveries.png b/behavior_trees/images/walkthrough/contextual_recoveries.png index e0b2424c3b..8fe71b9f25 100644 Binary files a/behavior_trees/images/walkthrough/contextual_recoveries.png and b/behavior_trees/images/walkthrough/contextual_recoveries.png differ diff --git a/behavior_trees/images/walkthrough/kilted/navigation_subtree.png b/behavior_trees/images/walkthrough/kilted/navigation_subtree.png new file mode 100644 index 0000000000..4194004d37 Binary files /dev/null and b/behavior_trees/images/walkthrough/kilted/navigation_subtree.png differ diff --git a/behavior_trees/images/walkthrough/kilted/overall_bt.png b/behavior_trees/images/walkthrough/kilted/overall_bt.png new file mode 100644 index 0000000000..38595612f1 Binary files /dev/null and b/behavior_trees/images/walkthrough/kilted/overall_bt.png differ diff --git a/behavior_trees/images/walkthrough/kilted/overall_bt_w_breakdown.png b/behavior_trees/images/walkthrough/kilted/overall_bt_w_breakdown.png new file mode 100644 index 0000000000..4b39c4c15e Binary files /dev/null and b/behavior_trees/images/walkthrough/kilted/overall_bt_w_breakdown.png differ diff --git a/behavior_trees/images/walkthrough/kilted/patience_and_recovery.png b/behavior_trees/images/walkthrough/kilted/patience_and_recovery.png new file mode 100644 index 0000000000..2c9b393c4b Binary files /dev/null and b/behavior_trees/images/walkthrough/kilted/patience_and_recovery.png differ diff --git a/behavior_trees/images/walkthrough/lyrical/navigation_subtree.png b/behavior_trees/images/walkthrough/lyrical/navigation_subtree.png new file mode 100644 index 0000000000..724e54c439 Binary files /dev/null and b/behavior_trees/images/walkthrough/lyrical/navigation_subtree.png differ diff --git a/behavior_trees/images/walkthrough/lyrical/overall_bt.png b/behavior_trees/images/walkthrough/lyrical/overall_bt.png new file mode 100644 index 0000000000..58f03d20ce Binary files /dev/null and b/behavior_trees/images/walkthrough/lyrical/overall_bt.png differ diff --git a/behavior_trees/images/walkthrough/lyrical/overall_bt_w_breakdown.png b/behavior_trees/images/walkthrough/lyrical/overall_bt_w_breakdown.png new file mode 100644 index 0000000000..a9109708ce Binary files /dev/null and b/behavior_trees/images/walkthrough/lyrical/overall_bt_w_breakdown.png differ diff --git a/behavior_trees/images/walkthrough/lyrical/patience_and_recovery.png b/behavior_trees/images/walkthrough/lyrical/patience_and_recovery.png new file mode 100644 index 0000000000..913b8cec77 Binary files /dev/null and b/behavior_trees/images/walkthrough/lyrical/patience_and_recovery.png differ diff --git a/behavior_trees/images/walkthrough/navigation_subtree.png b/behavior_trees/images/walkthrough/navigation_subtree.png deleted file mode 100644 index b5a28f6159..0000000000 Binary files a/behavior_trees/images/walkthrough/navigation_subtree.png and /dev/null differ diff --git a/behavior_trees/images/walkthrough/navigation_subtree_bare.png b/behavior_trees/images/walkthrough/navigation_subtree_bare.png index 83ed997d78..1afb509432 100644 Binary files a/behavior_trees/images/walkthrough/navigation_subtree_bare.png and b/behavior_trees/images/walkthrough/navigation_subtree_bare.png differ diff --git a/behavior_trees/images/walkthrough/overall_bt.png b/behavior_trees/images/walkthrough/overall_bt.png deleted file mode 100644 index 68c7e7de81..0000000000 Binary files a/behavior_trees/images/walkthrough/overall_bt.png and /dev/null differ diff --git a/behavior_trees/images/walkthrough/overall_bt_w_breakdown.png b/behavior_trees/images/walkthrough/overall_bt_w_breakdown.png deleted file mode 100644 index 8f9a39601d..0000000000 Binary files a/behavior_trees/images/walkthrough/overall_bt_w_breakdown.png and /dev/null differ diff --git a/behavior_trees/images/walkthrough/patience_and_recovery.png b/behavior_trees/images/walkthrough/patience_and_recovery.png deleted file mode 100644 index 4a789c09aa..0000000000 Binary files a/behavior_trees/images/walkthrough/patience_and_recovery.png and /dev/null differ diff --git a/behavior_trees/images/walkthrough/recovery_subtree.png b/behavior_trees/images/walkthrough/recovery_subtree.png index 3711e021c1..66b880a6e7 100644 Binary files a/behavior_trees/images/walkthrough/recovery_subtree.png and b/behavior_trees/images/walkthrough/recovery_subtree.png differ diff --git a/behavior_trees/overview/detailed_behavior_tree_walkthrough.rst b/behavior_trees/overview/detailed_behavior_tree_walkthrough.rst index 3dabd4a628..f24da4823c 100644 --- a/behavior_trees/overview/detailed_behavior_tree_walkthrough.rst +++ b/behavior_trees/overview/detailed_behavior_tree_walkthrough.rst @@ -36,73 +36,138 @@ Navigate To Pose With Replanning and Recovery The following section will describe in detail the concept of the main and default BT currently used in Nav2, ``navigate_to_pose_w_replanning_and_recovery.xml``. This behavior tree replans the global path periodically at 1 Hz and it also has recovery actions. -| +.. tabs:: - .. image:: ../images/walkthrough/overall_bt.png - :align: center + .. group-tab:: Rolling -| + .. image:: ../images/walkthrough/lyrical/overall_bt.png + :align: center + + .. group-tab:: Kilted and older + + .. image:: ../images/walkthrough/kilted/overall_bt.png + :align: center BTs are primarily defined in XML. The tree shown above is represented in XML as follows. -.. code-block:: xml +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older - + .. code-block:: xml + + - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - + + - + + + + + + + + + + + + + + + + + + + + + - - + This is likely still a bit overwhelming, but this tree can be broken into two smaller subtrees that we can focus on one at a time. These smaller subtrees are the children of the top-most ``RecoveryNode``. From this point forward the ``NavigateWithReplanning`` subtree will be referred to as the ``Navigation`` subtree, and the ``RecoveryFallback`` subtree will be known as the ``Recovery`` subtree. This can be represented in the following way: -| +.. tabs:: - .. image:: ../images/walkthrough/overall_bt_w_breakdown.png - :align: center + .. group-tab:: Rolling -| + .. image:: ../images/walkthrough/lyrical/overall_bt_w_breakdown.png + :align: center + + .. group-tab:: Kilted and older + + .. image:: ../images/walkthrough/kilted/overall_bt_w_breakdown.png + :align: center The ``Navigation`` subtree mainly involves actual navigation behavior: @@ -129,39 +194,76 @@ This happens until the ``number_of_retries`` for the parent ``RecoveryNode`` is Navigation Subtree ====================== -Now that we have gone over the control flow between the ``Navigation`` subtree and the ``Recovery`` subtree, let's focus on the Navigation subtree. +Now that we have gone over the control flow between the ``Navigation`` subtree and the ``Recovery`` subtree, let's focus on the ``Navigation`` subtree. -| +.. tabs:: - .. image:: ../images/walkthrough/navigation_subtree.png - :align: center + .. group-tab:: Rolling -| + .. image:: ../images/walkthrough/lyrical/navigation_subtree.png + :align: center + + .. group-tab:: Kilted and older + + .. image:: ../images/walkthrough/kilted/navigation_subtree.png + :align: center The XML of this subtree is as follows: -.. code-block:: xml +.. tabs:: - - - + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + - - - - - - - + + + + + + + - + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + - - + + + + + + + + + + - + This subtree has two primary actions ``ComputePathToPose`` and ``FollowPath``. If either of these two actions fail, they will attempt to clear the failure contextually. @@ -231,24 +333,24 @@ And the XML snippet: .. code-block:: xml - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + At the top level, a ``Sequence`` ensures the following steps are executed in order: diff --git a/behavior_trees/trees/follow_point.rst b/behavior_trees/trees/follow_point.rst index beacf0c213..eccf4ad140 100644 --- a/behavior_trees/trees/follow_point.rst +++ b/behavior_trees/trees/follow_point.rst @@ -18,24 +18,52 @@ After the new path to the dynamic point is computed and truncated, it is again p However, note that it is under a ``KeepRunningUntilFailure`` decorator node ensuring the controller continues to execute until a failure mode. This behavior tree will execute infinitely in time until the navigation request is preempted or cancelled. -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + diff --git a/behavior_trees/trees/nav_through_poses_recovery.rst b/behavior_trees/trees/nav_through_poses_recovery.rst index e5c1e4ec3c..69e2966d41 100644 --- a/behavior_trees/trees/nav_through_poses_recovery.rst +++ b/behavior_trees/trees/nav_through_poses_recovery.rst @@ -34,57 +34,119 @@ Next, the recovery subtree will tick the costmap clearing operations, spinning, After each of the recoveries in the subtree, the main navigation subtree will be reattempted. If it continues to fail, the next recovery in the recovery subtree is ticked. -While this behavior tree does not make use of it, the ``PlannerSelector``, ``ControllerSelector``, ``GoalCheckerSelector``, ``ProgressCheckerSelector``, and ``PathHandlerSelector`` behavior tree nodes can also be helpful. Rather than hardcoding the algorithm to use (``GridBased`` and ``FollowPath``), these behavior tree nodes will allow a user to dynamically change the algorithm used in the navigation system via a ROS topic. It may be instead advisable to create different subtree contexts using condition nodes with specified algorithms in their most useful and unique situations. However, the selector nodes can be a useful way to change algorithms from an external application rather than via internal behavior tree control flow logic. It is better to implement changes through behavior tree methods, but we understand that many professional users have external applications to dynamically change settings of their navigators. - -.. code-block:: xml - - - - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + While this behavior tree does not make use of it, the ``PlannerSelector``, ``ControllerSelector``, ``GoalCheckerSelector``, ``ProgressCheckerSelector``, and ``PathHandlerSelector`` behavior tree nodes can also be helpful. Rather than hardcoding the algorithm to use (``grid_based`` and ``follow_path``), these behavior tree nodes will allow a user to dynamically change the algorithm used in the navigation system via a ROS topic. + It may be instead advisable to create different subtree contexts using condition nodes with specified algorithms in their most useful and unique situations. However, the selector nodes can be a useful way to change algorithms from an external application rather than via internal behavior tree control flow logic. It is better to implement changes through behavior tree methods, but we understand that many professional users have external applications to dynamically change settings of their navigators. + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + While this behavior tree does not make use of it, the ``PlannerSelector``, ``ControllerSelector``, ``GoalCheckerSelector``, and ``ProgressCheckerSelector`` behavior tree nodes can also be helpful. Rather than hardcoding the algorithm to use (``GridBased`` and ``FollowPath``), these behavior tree nodes will allow a user to dynamically change the algorithm used in the navigation system via a ROS topic. + It may be instead advisable to create different subtree contexts using condition nodes with specified algorithms in their most useful and unique situations. However, the selector nodes can be a useful way to change algorithms from an external application rather than via internal behavior tree control flow logic. It is better to implement changes through behavior tree methods, but we understand that many professional users have external applications to dynamically change settings of their navigators. + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - + + diff --git a/behavior_trees/trees/nav_to_pose_and_pause_near_goal_obstacle.rst b/behavior_trees/trees/nav_to_pose_and_pause_near_goal_obstacle.rst index ef4c244d52..6c1a443959 100644 --- a/behavior_trees/trees/nav_to_pose_and_pause_near_goal_obstacle.rst +++ b/behavior_trees/trees/nav_to_pose_and_pause_near_goal_obstacle.rst @@ -13,7 +13,15 @@ From the image, it can be noted that there is an additional branch in the Naviga In this particular BT, the monitoring branch is exclusively utilized by ``PathLongerOnApproach`` BT node for checking if the global planner has decided to plan a significantly longer path for the robot on approaching the user-specified goal proximity. If there is no significantly longer path, the monitor node goes into the ``FollowPath`` recovery node, which then generates the necessary control commands. -.. image:: ../images/walkthrough/patience_and_recovery.png +.. tabs:: + + .. group-tab:: Rolling + + .. image:: ../images/walkthrough/lyrical/patience_and_recovery.png + + .. group-tab:: Kilted and older + + .. image:: ../images/walkthrough/kilted/patience_and_recovery.png Once there is a significantly longer path, the child node for the ``PathLongerOnApproach`` node ticks. The child node is a ``RetryUntilSuccessful`` decorator node, which inturns have a ``SequenceWithMemory`` node as its child. @@ -36,50 +44,101 @@ Apart from the above scenarios, we also need to note that, the robot will take t In conclusion, this particular BT would serve, both as an example and ready-to-use BT for an organizational specific application, that wishes to optimize its process cycle time. -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A complete demo of this BT can be seen in the video below: diff --git a/behavior_trees/trees/nav_to_pose_recovery.rst b/behavior_trees/trees/nav_to_pose_recovery.rst index f2a39cefde..759f7c2f72 100644 --- a/behavior_trees/trees/nav_to_pose_recovery.rst +++ b/behavior_trees/trees/nav_to_pose_recovery.rst @@ -30,54 +30,111 @@ Next, the recovery subtree will the recoveries: costmap clearing operations, spi After each of the recoveries in the subtree, the main navigation subtree will be reattempted. If it continues to fail, the next recovery in the recovery subtree is ticked. -While this behavior tree does not make use of it, the ``PlannerSelector``, ``ControllerSelector``, ``GoalCheckerSelector``, ``ProgressCheckerSelector``, and ``PathHandlerSelector`` behavior tree nodes can also be helpful. Rather than hardcoding the algorithm to use (``GridBased`` and ``FollowPath``), these behavior tree nodes will allow a user to dynamically change the algorithm used in the navigation system via a ROS topic. It may be instead advisable to create different subtree contexts using condition nodes with specified algorithms in their most useful and unique situations. However, the selector nodes can be a useful way to change algorithms from an external application rather than via internal behavior tree control flow logic. It is better to implement changes through behavior tree methods, but we understand that many professional users have external applications to dynamically change settings of their navigators. - -.. code-block:: xml - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + While this behavior tree does not make use of it, the ``PlannerSelector``, ``ControllerSelector``, ``GoalCheckerSelector``, ``ProgressCheckerSelector``, and ``PathHandlerSelector`` behavior tree nodes can also be helpful. Rather than hardcoding the algorithm to use (``grid_based`` and ``follow_path``), these behavior tree nodes will allow a user to dynamically change the algorithm used in the navigation system via a ROS topic. + It may be instead advisable to create different subtree contexts using condition nodes with specified algorithms in their most useful and unique situations. However, the selector nodes can be a useful way to change algorithms from an external application rather than via internal behavior tree control flow logic. It is better to implement changes through behavior tree methods, but we understand that many professional users have external applications to dynamically change settings of their navigators. + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + While this behavior tree does not make use of it, the ``PlannerSelector`` and ``ControllerSelector`` behavior tree nodes can also be helpful. Rather than hardcoding the algorithm to use (``GridBased`` and ``FollowPath``), these behavior tree nodes will allow a user to dynamically change the algorithm used in the navigation system via a ROS topic. + It may be instead advisable to create different subtree contexts using condition nodes with specified algorithms in their most useful and unique situations. However, the selector nodes can be a useful way to change algorithms from an external application rather than via internal behavior tree control flow logic. It is better to implement changes through behavior tree methods, but we understand that many professional users have external applications to dynamically change settings of their navigators. + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - + + diff --git a/behavior_trees/trees/nav_to_pose_with_consistent_replanning_and_if_path_becomes_invalid.rst b/behavior_trees/trees/nav_to_pose_with_consistent_replanning_and_if_path_becomes_invalid.rst index 71f649fe47..9deef8058a 100644 --- a/behavior_trees/trees/nav_to_pose_with_consistent_replanning_and_if_path_becomes_invalid.rst +++ b/behavior_trees/trees/nav_to_pose_with_consistent_replanning_and_if_path_becomes_invalid.rst @@ -26,47 +26,103 @@ Next, the recovery subtree will attempt the following recoveries: costmap cleari After each of the recoveries in the subtree, the main navigation subtree will be reattempted. If it continues to fail, the next recovery in the recovery subtree is ticked. -While this behavior tree does not make use of it, the ``PlannerSelector``, ``ControllerSelector``, and ``GoalCheckerSelector`` behavior tree nodes can also be helpful. Rather than hardcoding the algorithm to use (``GridBased`` and ``FollowPath``), these behavior tree nodes will allow a user to dynamically change the algorithm used in the navigation system via a ROS topic. It may be instead advisable to create different subtree contexts using condition nodes with specified algorithms in their most useful and unique situations. However, the selector nodes can be a useful way to change algorithms from an external application rather than via internal behavior tree control flow logic. It is better to implement changes through behavior tree methods, but we understand that many professional users have external applications to dynamically change settings of their navigators. +While this behavior tree does not make use of it, the ``PlannerSelector`` and ``ControllerSelector`` behavior tree nodes can also be helpful. Rather than hardcoding the algorithm to use ``grid_based`` and ``follow_path`` (``GridBased`` and ``FollowPath``, respectively, in Kilted and older), these behavior tree nodes will allow a user to dynamically change the algorithm used in the navigation system via a ROS topic. +It may be instead advisable to create different subtree contexts using condition nodes with specified algorithms in their most useful and unique situations. However, the selector nodes can be a useful way to change algorithms from an external application rather than via internal behavior tree control flow logic. It is better to implement changes through behavior tree methods, but we understand that many professional users have external applications to dynamically change settings of their navigators. -.. code-block:: xml +.. tabs:: - - - - - - - - - - - - - - - - - - - - - - - + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - + + diff --git a/behavior_trees/trees/navigate_on_route_graph_w_recovery.rst b/behavior_trees/trees/navigate_on_route_graph_w_recovery.rst index 28e9256538..ed8895bfb7 100644 --- a/behavior_trees/trees/navigate_on_route_graph_w_recovery.rst +++ b/behavior_trees/trees/navigate_on_route_graph_w_recovery.rst @@ -19,87 +19,178 @@ The compute path, including the first and last mile paths are then smoothed in t For a detailed description of the role of the selector nodes, recovery behaviors, or fallbacks, see the other behavior tree explanations in this section. -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - + + + + + + + + + + + - - + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - + + diff --git a/behavior_trees/trees/odometry_calibration.rst b/behavior_trees/trees/odometry_calibration.rst index ff5f51bbae..fe1a8b40cb 100644 --- a/behavior_trees/trees/odometry_calibration.rst +++ b/behavior_trees/trees/odometry_calibration.rst @@ -12,22 +12,46 @@ This is a primitive experiment to measure odometric accuracy and can be used and :alt: Alternative text :align: center +.. tabs:: -.. code-block:: xml - - - - - - - - - - - - - - - - - + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + + + diff --git a/concepts/index.rst b/concepts/index.rst index 35fd44fe15..86c7d51beb 100644 --- a/concepts/index.rst +++ b/concepts/index.rst @@ -117,12 +117,12 @@ They also host the environmental representation used by the algorithm plugins to The planner, smoother and controller servers will be configured at runtime with the names (aliases) and types of algorithms to use. These types are the pluginlib names that have been registered and the names are the aliases for the task. -An example would be the DWB controller used with name ``FollowPath``, as it follows a reference path. -In this case, then all parameters for DWB would be placed in that namespace, e.g. ``FollowPath.``. +An example would be the DWB controller used with name ``follow_path`` (``FollowPath`` in Kilted and older versions from here on), as it follows a reference path. +In this case, then all parameters for DWB would be placed in that namespace, e.g. ``follow_path.``. These three servers then expose an action interface corresponding to their task. When the behavior tree ticks the corresponding BT node, it will call the action server to process its task. -The action server callback inside the server will call the chosen algorithm by its name (e.g. ``FollowPath``) that maps to a specific algorithm. +The action server callback inside the server will call the chosen algorithm by its name, e.g. ``follow_path`` (``FollowPath`` in Kilted and older), that maps to a specific algorithm. This allows a user to abstract the algorithm used in the behavior tree to classes of algorithms. For instance, you can have ``N`` plugin controllers to follow paths, dock with charger, avoid dynamic obstacles, or interface with a tool. Having all of these plugins in the same server allows the user to make use of a single environmental representation object, which is costly to duplicate. diff --git a/conf.py b/conf.py index 64803255fa..7be6d42eab 100644 --- a/conf.py +++ b/conf.py @@ -36,6 +36,7 @@ 'breathe', 'myst_parser', 'sphinx_copybutton', + 'sphinx_tabs.tabs', 'sphinx.ext.extlinks', 'sphinx.ext.graphviz', 'sphinxcontrib.plantuml', diff --git a/configuration/packages/bt-plugins/actions/CancelBackUp.rst b/configuration/packages/bt-plugins/actions/CancelBackUp.rst index d00a38e08d..f395e3874a 100644 --- a/configuration/packages/bt-plugins/actions/CancelBackUp.rst +++ b/configuration/packages/bt-plugins/actions/CancelBackUp.rst @@ -36,4 +36,4 @@ Example .. code-block:: xml - + diff --git a/configuration/packages/bt-plugins/actions/CancelControl.rst b/configuration/packages/bt-plugins/actions/CancelControl.rst index 504f188dae..af1b0f73e4 100644 --- a/configuration/packages/bt-plugins/actions/CancelControl.rst +++ b/configuration/packages/bt-plugins/actions/CancelControl.rst @@ -36,4 +36,4 @@ Example .. code-block:: xml - + diff --git a/configuration/packages/bt-plugins/actions/CancelSpin.rst b/configuration/packages/bt-plugins/actions/CancelSpin.rst index 7e7d24e90d..efe859dd71 100644 --- a/configuration/packages/bt-plugins/actions/CancelSpin.rst +++ b/configuration/packages/bt-plugins/actions/CancelSpin.rst @@ -36,4 +36,4 @@ Example .. code-block:: xml - + diff --git a/configuration/packages/bt-plugins/actions/CancelWait.rst b/configuration/packages/bt-plugins/actions/CancelWait.rst index 36e8285d63..399daf4a28 100644 --- a/configuration/packages/bt-plugins/actions/CancelWait.rst +++ b/configuration/packages/bt-plugins/actions/CancelWait.rst @@ -36,4 +36,4 @@ Example .. code-block:: xml - + diff --git a/configuration/packages/bt-plugins/actions/ComputeAndTrackRoute.rst b/configuration/packages/bt-plugins/actions/ComputeAndTrackRoute.rst index 1f876e0d56..d4229410f7 100644 --- a/configuration/packages/bt-plugins/actions/ComputeAndTrackRoute.rst +++ b/configuration/packages/bt-plugins/actions/ComputeAndTrackRoute.rst @@ -140,5 +140,5 @@ Example .. code-block:: xml - diff --git a/configuration/packages/bt-plugins/actions/ComputeCoveragePath.rst b/configuration/packages/bt-plugins/actions/ComputeCoveragePath.rst index 51eb0daf26..08c6ea1684 100644 --- a/configuration/packages/bt-plugins/actions/ComputeCoveragePath.rst +++ b/configuration/packages/bt-plugins/actions/ComputeCoveragePath.rst @@ -141,6 +141,6 @@ Example .. code-block:: xml - + Note: the blackboard IDs for the path, error code, and more may be adjusted, but need to match the corresponding parameters in the ``CoverageNavigator`` plugin to set on the blackboard for use from the action server. diff --git a/configuration/packages/bt-plugins/actions/ComputePathThroughPoses.rst b/configuration/packages/bt-plugins/actions/ComputePathThroughPoses.rst index 0b98ccaa7a..50800a1397 100644 --- a/configuration/packages/bt-plugins/actions/ComputePathThroughPoses.rst +++ b/configuration/packages/bt-plugins/actions/ComputePathThroughPoses.rst @@ -10,112 +10,227 @@ The server address can be remapped using the ``server_name`` input port. Input Ports ----------- -:start: - ===================================== ======= - Type Default - ------------------------------------- ------- - geometry_msgs::msg::PoseStamped N/A - ===================================== ======= +.. tabs:: - Description - Start pose. Optional. Only used if not left empty. Takes in a blackboard variable, e.g. "{start}". + .. group-tab:: Rolling -:goals: + :start: - ==================== ======= - Type Default - -------------------- ------- - nav_msgs::msg::Goals N/A - ==================== ======= + ===================================== ======= + Type Default + ------------------------------------- ------- + geometry_msgs::msg::PoseStamped N/A + ===================================== ======= - Description - Goal poses. Takes in a blackboard variable, e.g. "{goals}". + Description + Start pose. Optional. Only used if not left empty. Takes in a blackboard variable, e.g. "{start}". -:planner_id: + :goals: - ============== ======= - Type Default - -------------- ------- - string N/A - ============== ======= + ==================== ======= + Type Default + -------------------- ------- + nav_msgs::msg::Goals N/A + ==================== ======= - Description - Mapped name to the planner plugin type to use, e.g. GridBased. + Description + Goal poses. Takes in a blackboard variable, e.g. "{goals}". -:server_name: + :planner_id: - ============== ======= - Type Default - -------------- ------- - string N/A - ============== ======= + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= - Description - Action server name. + Description + Mapped name to the planner plugin type to use, e.g. grid_based. + :server_name: -:server_timeout: + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= - ============== ======= - Type Default - -------------- ------- - double 10 - ============== ======= + Description + Action server name. - Description - Action server timeout (ms). + + :server_timeout: + + ============== ======= + Type Default + -------------- ------- + double 10 + ============== ======= + + Description + Action server timeout (ms). + + .. group-tab:: Kilted and older + + :start: + + ===================================== ======= + Type Default + ------------------------------------- ------- + geometry_msgs::msg::PoseStamped N/A + ===================================== ======= + + Description + Start pose. Optional. Only used if not left empty. Takes in a blackboard variable, e.g. "{start}". + + :goals: + + ==================== ======= + Type Default + -------------------- ------- + nav_msgs::msg::Goals N/A + ==================== ======= + + Description + Goal poses. Takes in a blackboard variable, e.g. "{goals}". + + Note + In Jazzy and older versions, the ``geometry_msgs::msg::PoseStamped[]`` type is used. + + :planner_id: + + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= + + Description + Mapped name to the planner plugin type to use, e.g. GridBased. + + :server_name: + + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= + + Description + Action server name. + + + :server_timeout: + + ============== ======= + Type Default + -------------- ------- + double 10 + ============== ======= + + Description + Action server timeout (ms). Output Ports ------------ -:path: +.. tabs:: + + .. group-tab:: Rolling + + :path: + + ========================== ======= + Type Default + -------------------------- ------- + nav_msgs::msg::Path N/A + ========================== ======= + + Description + Path created by action server. Takes in a blackboard variable, e.g. "{path}". + + :last_reached_index: + + ========================== ======= + Type Default + -------------------------- ------- + int16 -1 + ========================== ======= + + Description + In the case of a partial plan, index of the last reached pose from the goals list. Otherwise -1 which also corresponds to ComputePathThroughPosesResult::ALL_GOALS if a full plan through all the goals was possible. + + :error_code_id: - ========================== ======= - Type Default - -------------------------- ------- - nav_msgs::msg::Path N/A - ========================== ======= + ============== ======= + Type Default + -------------- ------- + uint16 N/A + ============== ======= - Description - Path created by action server. Takes in a blackboard variable, e.g. "{path}". + Description + Compute path through poses error code. See ``ComputePathThroughPoses`` action message for the enumerated set of error codes. -:last_reached_index: + :error_msg: - ========================== ======= - Type Default - -------------------------- ------- - int16 -1 - ========================== ======= + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= - Description - In the case of a partial plan, index of the last reached pose from the goals list. Otherwise -1 which also corresponds to ComputePathThroughPosesResult::ALL_GOALS if a full plan through all the goals was possible. + Description + Compute path through poses error message. See ``ComputePathThroughPoses`` action message for the enumerated set of error codes. -:error_code_id: + .. group-tab:: Kilted and older - ============== ======= - Type Default - -------------- ------- - uint16 N/A - ============== ======= + :path: - Description - Compute path through poses error code. See ``ComputePathThroughPoses`` action message for the enumerated set of error codes. + ========================== ======= + Type Default + -------------------------- ------- + nav_msgs::msg::Path N/A + ========================== ======= -:error_msg: + Description + Path created by action server. Takes in a blackboard variable, e.g. "{path}". - ============== ======= - Type Default - -------------- ------- - string N/A - ============== ======= + :error_code_id: - Description - Compute path through poses error message. See ``ComputePathThroughPoses`` action message for the enumerated set of error codes. + ============== ======= + Type Default + -------------- ------- + uint16 N/A + ============== ======= + + Description + Compute path through poses error code. See ``ComputePathThroughPoses`` action message for the enumerated set of error codes. + + :error_msg: + + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= + + Description + Compute path through poses error message. See ``ComputePathThroughPoses`` action message for the enumerated set of error codes. Example ------- -.. code-block:: xml +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + .. group-tab:: Kilted and older + + .. code-block:: xml - + diff --git a/configuration/packages/bt-plugins/actions/ComputePathToPose.rst b/configuration/packages/bt-plugins/actions/ComputePathToPose.rst index 49aaf783a8..677cc9b13d 100644 --- a/configuration/packages/bt-plugins/actions/ComputePathToPose.rst +++ b/configuration/packages/bt-plugins/actions/ComputePathToPose.rst @@ -10,72 +10,146 @@ The server address can be remapped using the ``server_name`` input port. Input Ports ----------- -:start: - ===================================== ======= - Type Default - ------------------------------------- ------- - geometry_msgs::msg::PoseStamped N/A - ===================================== ======= +.. tabs:: - Description - Start pose. Optional. Used as the planner start pose instead of the current robot pose, if ``use_start`` is not false (i.e. not provided or set to true). Takes in a blackboard variable, e.g. "{start}". + .. group-tab:: Rolling -:use_start: + :start: - ===================================== ======= - Type Default - ------------------------------------- ------- - geometry_msgs::msg::PoseStamped N/A - ===================================== ======= + ===================================== ======= + Type Default + ------------------------------------- ------- + geometry_msgs::msg::PoseStamped N/A + ===================================== ======= - Description - Optional. For using or not using (i.e. ignoring) the provided start pose ``start``. Takes in a blackboard variable, e.g. "{use_start}". + Description + Start pose. Optional. Used as the planner start pose instead of the current robot pose, if ``use_start`` is not false (i.e. not provided or set to true). Takes in a blackboard variable, e.g. "{start}". -:goal: + :use_start: - ===================================== ======= - Type Default - ------------------------------------- ------- - geometry_msgs::msg::PoseStamped N/A - ===================================== ======= + ===================================== ======= + Type Default + ------------------------------------- ------- + geometry_msgs::msg::PoseStamped N/A + ===================================== ======= - Description - Goal pose. Takes in a blackboard variable, e.g. "{goal}". + Description + Optional. For using or not using (i.e. ignoring) the provided start pose ``start``. Takes in a blackboard variable, e.g. "{use_start}". -:planner_id: + :goal: - ============== ======= - Type Default - -------------- ------- - string N/A - ============== ======= + ===================================== ======= + Type Default + ------------------------------------- ------- + geometry_msgs::msg::PoseStamped N/A + ===================================== ======= - Description - Mapped name to the planner plugin type to use, e.g. GridBased. + Description + Goal pose. Takes in a blackboard variable, e.g. "{goal}". -:server_name: + :planner_id: - ============== ======= - Type Default - -------------- ------- - string N/A - ============== ======= + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= - Description - Action server name. + Description + Mapped name to the planner plugin type to use, e.g. grid_based. + :server_name: -:server_timeout: + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= - ============== ======= - Type Default - -------------- ------- - double 10 - ============== ======= + Description + Action server name. - Description - Action server timeout (ms). + + :server_timeout: + + ============== ======= + Type Default + -------------- ------- + double 10 + ============== ======= + + Description + Action server timeout (ms). + + .. group-tab:: Kilted and newer + + :start: + + ===================================== ======= + Type Default + ------------------------------------- ------- + geometry_msgs::msg::PoseStamped N/A + ===================================== ======= + + Description + Start pose. Optional. Used as the planner start pose instead of the current robot pose, if ``use_start`` is not false (i.e. not provided or set to true). Takes in a blackboard variable, e.g. "{start}". + + :use_start: + + ===================================== ======= + Type Default + ------------------------------------- ------- + geometry_msgs::msg::PoseStamped N/A + ===================================== ======= + + Description + Optional. For using or not using (i.e. ignoring) the provided start pose ``start``. Takes in a blackboard variable, e.g. "{use_start}". + + :goal: + + ===================================== ======= + Type Default + ------------------------------------- ------- + geometry_msgs::msg::PoseStamped N/A + ===================================== ======= + + Description + Goal pose. Takes in a blackboard variable, e.g. "{goal}". + + :planner_id: + + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= + + Description + Mapped name to the planner plugin type to use, e.g. GridBased. + + :server_name: + + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= + + Description + Action server name. + + + :server_timeout: + + ============== ======= + Type Default + -------------- ------- + double 10 + ============== ======= + + Description + Action server timeout (ms). Output Ports ------------ @@ -116,7 +190,18 @@ Output Ports Example ------- -.. code-block:: xml +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + .. group-tab:: Kilted and older + + .. code-block:: xml - + diff --git a/configuration/packages/bt-plugins/actions/ComputeRoute.rst b/configuration/packages/bt-plugins/actions/ComputeRoute.rst index 3ea8854995..28409d6fdb 100644 --- a/configuration/packages/bt-plugins/actions/ComputeRoute.rst +++ b/configuration/packages/bt-plugins/actions/ComputeRoute.rst @@ -162,5 +162,5 @@ Example .. code-block:: xml - diff --git a/configuration/packages/bt-plugins/actions/ControllerSelector.rst b/configuration/packages/bt-plugins/actions/ControllerSelector.rst index c69d75d492..f6ceff0330 100644 --- a/configuration/packages/bt-plugins/actions/ControllerSelector.rst +++ b/configuration/packages/bt-plugins/actions/ControllerSelector.rst @@ -52,7 +52,16 @@ Output Ports Example ------- +.. tabs:: -.. code-block:: xml + .. group-tab:: Rolling - + .. code-block:: xml + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + diff --git a/configuration/packages/bt-plugins/actions/FollowPath.rst b/configuration/packages/bt-plugins/actions/FollowPath.rst index aa4a6507e4..6e858c5052 100644 --- a/configuration/packages/bt-plugins/actions/FollowPath.rst +++ b/configuration/packages/bt-plugins/actions/FollowPath.rst @@ -9,126 +9,235 @@ The server address can be remapped using the ``server_name`` input port. Input Ports ----------- -:path: +.. tabs:: - ====== ======= - Type Default - ------ ------- - string N/A - ====== ======= + .. group-tab:: Rolling - Description - Takes in a blackboard variable containing the path to follow, eg. "{path}". + :path: -:controller_id: + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= - ====== ======= - Type Default - ------ ------- - string N/A - ====== ======= + Description + Takes in a blackboard variable containing the path to follow, eg. "{path}". - Description - Mapped name of the controller plugin type to use, e.g. FollowPath. + :controller_id: -:goal_checker_id: + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= - ====== ======= - Type Default - ------ ------- - string N/A - ====== ======= + Description + Mapped name of the controller plugin type to use, e.g. follow_path. - Description - Mapped name of the goal checker plugin type to use, e.g. SimpleGoalChecker. + :goal_checker_id: -:progress_checker_id: + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= - ====== ======= - Type Default - ------ ------- - string N/A - ====== ======= + Description + Mapped name of the goal checker plugin type to use, e.g. simple_goal_checker. - Description - Mapped name of the progress checker plugin type to use, e.g. SimpleProgressChecker. + :progress_checker_id: -:path_handler_id: + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= - ====== ======= - Type Default - ------ ------- - string N/A - ====== ======= + Description + Mapped name of the progress checker plugin type to use, e.g. simple_progress_checker. - Description - Mapped name of the path handler plugin type to use, e.g. FeasiblePathHandler. + :path_handler_id: -:server_name: + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= - ====== ======= - Type Default - ------ ------- - string N/A - ====== ======= + Description + Mapped name of the path handler plugin type to use, e.g. feasible_path_handler. - Description - Action server name. + :server_name: + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= -:server_timeout: + Description + Action server name. - ============== ======= - Type Default - -------------- ------- - double 10 - ============== ======= - Description - Action server timeout (ms). + :server_timeout: + ============== ======= + Type Default + -------------- ------- + double 10 + ============== ======= + + Description + Action server timeout (ms). + + .. group-tab:: Kilted and older + + :path: + + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= + + Description + Takes in a blackboard variable containing the path to follow, eg. "{path}". + + :controller_id: + + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= + + Description + Mapped name of the controller plugin type to use, e.g. FollowPath. + + :goal_checker_id: + + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= + + Description + Mapped name of the goal checker plugin type to use, e.g. SimpleGoalChecker. + + :progress_checker_id: + + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= + + Description + Mapped name of the progress checker plugin type to use, e.g. SimpleProgressChecker. + + :server_name: + + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= + + Description + Action server name. + + + :server_timeout: + + ============== ======= + Type Default + -------------- ------- + double 10 + ============== ======= + + Description + Action server timeout (ms). Output Ports ------------ -:error_code_id: +.. tabs:: + + .. group-tab:: Rolling + + :error_code_id: + + ============== ======= + Type Default + -------------- ------- + uint16 N/A + ============== ======= + + Description + Follow path error code. See ``FollowPath`` action for the enumerated set of error code definitions. + + :error_msg: - ============== ======= - Type Default - -------------- ------- - uint16 N/A - ============== ======= + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= - Description - Follow path error code. See ``FollowPath`` action for the enumerated set of error code definitions. + Description + Follow path error message. See ``FollowPath`` action for the enumerated set of error code definitions. -:error_msg: + :tracking_feedback: - ============== ======= - Type Default - -------------- ------- - string N/A - ============== ======= + ================================ ======= + Type Default + -------------------------------- ------- + nav2_msgs::msg::TrackingFeedback N/A + ================================ ======= - Description - Follow path error message. See ``FollowPath`` action for the enumerated set of error code definitions. + Description + Tracking feedback message from the controller server, including cross track error, current path index, remaining path length, etc. -:tracking_feedback: + .. group-tab:: Kilted and older - ================================ ======= - Type Default - -------------------------------- ------- - nav2_msgs::msg::TrackingFeedback N/A - ================================ ======= + :error_code_id: - Description - Tracking feedback message from the controller server, including cross track error, current path index, remaining path length, etc. + ============== ======= + Type Default + -------------- ------- + uint16 N/A + ============== ======= + Description + Follow path error code. See ``FollowPath`` action for the enumerated set of error code definitions. + + :error_msg: + + ============== ======= + Type Default + -------------- ------- + string N/A + ============== ======= + + Description + Follow path error message. See ``FollowPath`` action for the enumerated set of error code definitions. Example ------- -.. code-block:: xml +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + .. group-tab:: Kilted and older + + .. code-block:: xml - + diff --git a/configuration/packages/bt-plugins/actions/NavigateThroughPoses.rst b/configuration/packages/bt-plugins/actions/NavigateThroughPoses.rst index cd5ddc3636..d5c93ba794 100644 --- a/configuration/packages/bt-plugins/actions/NavigateThroughPoses.rst +++ b/configuration/packages/bt-plugins/actions/NavigateThroughPoses.rst @@ -84,6 +84,6 @@ Example .. code-block:: xml - diff --git a/configuration/packages/bt-plugins/actions/NavigateToPose.rst b/configuration/packages/bt-plugins/actions/NavigateToPose.rst index b9f5d7f6bb..fdc9932dd1 100644 --- a/configuration/packages/bt-plugins/actions/NavigateToPose.rst +++ b/configuration/packages/bt-plugins/actions/NavigateToPose.rst @@ -84,6 +84,6 @@ Example .. code-block:: xml - diff --git a/configuration/packages/bt-plugins/actions/PathHandlerSelector.rst b/configuration/packages/bt-plugins/actions/PathHandlerSelector.rst index c7dc0c6f0a..e6beae1e4b 100644 --- a/configuration/packages/bt-plugins/actions/PathHandlerSelector.rst +++ b/configuration/packages/bt-plugins/actions/PathHandlerSelector.rst @@ -12,47 +12,59 @@ Any publisher to this topic needs to be configured with some QoS defined as ``re Input Ports ----------- -:topic_name: +.. tabs:: - ====== ===================== - Type Default - ------ --------------------- - string path_handler_selector - ====== ===================== + .. group-tab:: Rolling - Description - The name of the topic used to received select command messages. This is used to support multiple PathHandlerSelector nodes. + :topic_name: -:default_path_handler: + ====== ===================== + Type Default + ------ --------------------- + string path_handler_selector + ====== ===================== - ====== ======= - Type Default - ------ ------- - string N/A - ====== ======= + Description + The name of the topic used to received select command messages. This is used to support multiple PathHandlerSelector nodes. - Description - The default value for the selected PathHandler if no message is received from the input topic. + :default_path_handler: + + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= + + Description + The default value for the selected PathHandler if no message is received from the input topic. Output Ports ------------ -:selected_path_handler: +.. tabs:: + + .. group-tab:: Rolling - ====== ======= - Type Default - ------ ------- - string N/A - ====== ======= + :selected_path_handler: - Description - The output selected PathHandler id. This selected_path_handler string is usually passed to the FollowPath behavior via the path_handler_id input port. + ====== ======= + Type Default + ------ ------- + string N/A + ====== ======= + + Description + The output selected PathHandler id. This selected_path_handler string is usually passed to the FollowPath behavior via the path_handler_id input port. Example ------- -.. code-block:: xml +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml - + diff --git a/configuration/packages/bt-plugins/actions/PlannerSelector.rst b/configuration/packages/bt-plugins/actions/PlannerSelector.rst index b819d5727c..7e12df96da 100644 --- a/configuration/packages/bt-plugins/actions/PlannerSelector.rst +++ b/configuration/packages/bt-plugins/actions/PlannerSelector.rst @@ -53,6 +53,16 @@ Output Ports Example ------- -.. code-block:: xml +.. tabs:: - + .. group-tab:: Rolling + + .. code-block:: xml + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + diff --git a/configuration/packages/bt-plugins/actions/SmootherSelector.rst b/configuration/packages/bt-plugins/actions/SmootherSelector.rst index 256392eee8..cd7bdec6d0 100644 --- a/configuration/packages/bt-plugins/actions/SmootherSelector.rst +++ b/configuration/packages/bt-plugins/actions/SmootherSelector.rst @@ -1,7 +1,7 @@ .. _bt_smoother_selector_node: SmootherSelector -================== +================ It is used to select the Smoother that will be used by the Smoother server. It subscribes to the ``smoother_selector`` topic to receive command messages with the name of the Smoother to be used. It is commonly used before of the FollowPathAction. If none is provided on the topic, the ``default_smoother`` is used. @@ -53,6 +53,16 @@ Output Ports Example ------- -.. code-block:: xml +.. tabs:: - + .. group-tab:: Rolling + + .. code-block:: xml + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + diff --git a/configuration/packages/collision_monitor/configuring-collision-detector-node.rst b/configuration/packages/collision_monitor/configuring-collision-detector-node.rst index 75c6b559aa..5de7213a42 100644 --- a/configuration/packages/collision_monitor/configuring-collision-detector-node.rst +++ b/configuration/packages/collision_monitor/configuring-collision-detector-node.rst @@ -218,168 +218,313 @@ Polygons parameters Observation sources parameters ============================== -```` is the corresponding data source name ID selected for this type. +.. tabs:: -:````.type: + .. group-tab:: Rolling - ============== ============================= - Type Default - -------------- ----------------------------- - string "scan" - ============== ============================= + ```` is the corresponding data source name ID selected for this type. - Description: - Type of polygon shape. Could be ``scan``, ``pointcloud``, ``range`` or ``polygon``. + :````.type: -:````.transport_type: + ============== ============================= + Type Default + -------------- ----------------------------- + string "scan" + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - string "raw" - ============== ============================= + Description: + Type of polygon shape. Could be ``scan``, ``pointcloud``, ``range`` or ``polygon``. - Description: - For ``pointcloud`` data, specify the transport plugin to use: + :````.transport_type: - * raw: No compression. Default; highest bandwidth usage. - * draco: Lossy compression via Google. - * zlib: Lossless compression via Zlib compression. - * zstd: Lossless compression via Zstd compression. + ============== ============================= + Type Default + -------------- ----------------------------- + string "raw" + ============== ============================= - See the `known transports `_ for more details. + Description: + For ``pointcloud`` data, specify the transport plugin to use: -:````.topic: + * raw: No compression. Default; highest bandwidth usage. + * draco: Lossy compression via Google. + * zlib: Lossless compression via Zlib compression. + * zstd: Lossless compression via Zstd compression. - ============== ============================= - Type Default - -------------- ----------------------------- - string "scan" - ============== ============================= + See the `known transports `_ for more details. - Description: - Topic to listen the source data from. + :````.topic: -:````.min_height: + ============== ============================= + Type Default + -------------- ----------------------------- + string "scan" + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.05 - ============== ============================= + Description: + Topic to listen the source data from. - Description: - Minimum height the PointCloud projection to 2D space started from. Applicable for ``pointcloud`` type. + :````.min_height: -:````.max_height: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.05 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.5 - ============== ============================= + Description: + Minimum height the PointCloud projection to 2D space started from. Applicable for ``pointcloud`` type. - Description: - Maximum height the PointCloud projection to 2D space ended with. Applicable for ``pointcloud`` type. + :````.max_height: -:````.obstacles_angle: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double PI / 180 (1 degree) - ============== ============================= + Description: + Maximum height the PointCloud projection to 2D space ended with. Applicable for ``pointcloud`` type. - Description: - Angle increment (in radians) between nearby obstacle points at the range arc. Two outermost points from the field of view are not taken into account (they will always exist regardless of this value). Applicable for ``range`` type. + :````.obstacles_angle: -:````.sampling_distance: + ============== ============================= + Type Default + -------------- ----------------------------- + double PI / 180 (1 degree) + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.1 - ============== ============================= + Description: + Angle increment (in radians) between nearby obstacle points at the range arc. Two outermost points from the field of view are not taken into account (they will always exist regardless of this value). Applicable for ``range`` type. - Description: - Internally the polygon is sampled for collision detection. sampling_distance is the distance between sampled points of the polygon. Applicable for ``polygon`` source type. + :````.sampling_distance: -:````.enabled: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool True - ============== ============================= + Description: + Internally the polygon is sampled for collision detection. sampling_distance is the distance between sampled points of the polygon. Applicable for ``polygon`` source type. - Description: - Whether to use this source for collision detection. (Can be dynamically set) + :````.enabled: -:````.source_timeout: + ============== ============================= + Type Default + -------------- ----------------------------- + bool True + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double (node parameter ``source_timeout`` value) - ============== ============================= + Description: + Whether to use this source for collision detection. (Can be dynamically set) - Description: - Maximum time interval in which source data is considered as valid. If no new data is received within this interval, an additional warning will be displayed. Setting ``source_timeout: 0.0`` disables it. Overrides node parameter for each source individually, if desired. + :````.source_timeout: -:bond_heartbeat_period: + ============== ============================= + Type Default + -------------- ----------------------------- + double (node parameter ``source_timeout`` value) + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.25 - ============== ============================= + Description: + Maximum time interval in which source data is considered as valid. If no new data is received within this interval, an additional warning will be displayed. Setting ``source_timeout: 0.0`` disables it. Overrides node parameter for each source individually, if desired. - Description - The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. + :bond_heartbeat_period: -:allow_parameter_qos_overrides: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.25 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. - Description - Whether to allow QoS profiles to be overwritten with parameterized values. + :allow_parameter_qos_overrides: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to allow QoS profiles to be overwritten with parameterized values. + + .. group-tab:: Kilted and older + + ```` is the corresponding data source name ID selected for this type. + + :````.type: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "scan" + ============== ============================= + + Description: + Type of polygon shape. Could be ``scan``, ``pointcloud``, ``range`` or ``polygon``. + + :````.topic: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "scan" + ============== ============================= + + Description: + Topic to listen the source data from. + + :````.min_height: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.05 + ============== ============================= + + Description: + Minimum height the PointCloud projection to 2D space started from. Applicable for ``pointcloud`` type. + + :````.max_height: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= + + Description: + Maximum height the PointCloud projection to 2D space ended with. Applicable for ``pointcloud`` type. + + :````.obstacles_angle: + + ============== ============================= + Type Default + -------------- ----------------------------- + double PI / 180 (1 degree) + ============== ============================= + + Description: + Angle increment (in radians) between nearby obstacle points at the range arc. Two outermost points from the field of view are not taken into account (they will always exist regardless of this value). Applicable for ``range`` type. + + :````.sampling_distance: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description: + Internally the polygon is sampled for collision detection. sampling_distance is the distance between sampled points of the polygon. Applicable for ``polygon`` source type. + + :````.enabled: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool True + ============== ============================= + + Description: + Whether to use this source for collision detection. (Can be dynamically set) + + :````.source_timeout: + + ============== ============================= + Type Default + -------------- ----------------------------- + double (node parameter ``source_timeout`` value) + ============== ============================= + + Description: + Maximum time interval in which source data is considered as valid. If no new data is received within this interval, an additional warning will be displayed. Setting ``source_timeout: 0.0`` disables it. Overrides node parameter for each source individually, if desired. + + :bond_heartbeat_period: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description + The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. Example ******* Here is an example of configuration YAML for the Collision Detector. -.. code-block:: yaml - - collision_detector: - ros__parameters: - base_frame_id: "base_footprint" - odom_frame_id: "odom" - transform_tolerance: 0.5 - source_timeout: 5.0 - base_shift_correction: True - polygons: ["PolygonFront"] - PolygonFront: - type: "polygon" - points: "[[0.3, 0.3], [0.3, -0.3], [0.0, -0.3], [0.0, 0.3]]" - action_type: "none" - min_points: 4 - visualize: True - polygon_pub_topic: "polygon_front" - observation_sources: ["scan"] - scan: - source_timeout: 0.2 - type: "scan" - topic: "scan" - enabled: True - pointcloud: - type: "pointcloud" - topic: "/intel_realsense_r200_depth/points" - transport_type: "raw" # raw or/ with compression (zlib, draco, zstd) - min_height: 0.1 - max_height: 0.5 - enabled: True +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + collision_detector: + ros__parameters: + base_frame_id: "base_footprint" + odom_frame_id: "odom" + transform_tolerance: 0.5 + source_timeout: 5.0 + base_shift_correction: True + bond_heartbeat_period: 0.25 + polygons: ["polygon_front"] + polygon_front: + type: "polygon" + points: "[[0.3, 0.3], [0.3, -0.3], [0.0, -0.3], [0.0, 0.3]]" + action_type: "none" + min_points: 4 + visualize: True + polygon_pub_topic: "polygon_front" + observation_sources: ["scan"] + scan: + source_timeout: 0.2 + type: "scan" + topic: "scan" + enabled: True + pointcloud: + type: "pointcloud" + topic: "/intel_realsense_r200_depth/points" + transport_type: "raw" # raw or/ with compression (zlib, draco, zstd) + min_height: 0.1 + max_height: 0.5 + enabled: True + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + collision_detector: + ros__parameters: + base_frame_id: "base_footprint" + odom_frame_id: "odom" + transform_tolerance: 0.5 + source_timeout: 5.0 + base_shift_correction: True + bond_heartbeat_period: 0.1 + polygons: ["PolygonFront"] + PolygonFront: + type: "polygon" + points: "[[0.3, 0.3], [0.3, -0.3], [0.0, -0.3], [0.0, 0.3]]" + action_type: "none" + min_points: 4 + visualize: True + polygon_pub_topic: "polygon_front" + observation_sources: ["scan"] + scan: + source_timeout: 0.2 + type: "scan" + topic: "scan" + enabled: True + pointcloud: + type: "pointcloud" + topic: "/intel_realsense_r200_depth/points" + min_height: 0.1 + max_height: 0.5 + enabled: True diff --git a/configuration/packages/collision_monitor/configuring-collision-monitor-node.rst b/configuration/packages/collision_monitor/configuring-collision-monitor-node.rst index 340f366780..0ad10c4d68 100644 --- a/configuration/packages/collision_monitor/configuring-collision-monitor-node.rst +++ b/configuration/packages/collision_monitor/configuring-collision-monitor-node.rst @@ -517,183 +517,312 @@ All previous Polygon parameters apply, in addition to the following unique param Observation sources parameters ============================== -```` is the corresponding data source name ID selected for this type. +.. tabs:: -:````.type: + .. group-tab:: Rolling - ============== ============================= - Type Default - -------------- ----------------------------- - string "scan" - ============== ============================= + ```` is the corresponding data source name ID selected for this type. - Description: - Type of polygon shape. Could be ``scan``, ``pointcloud``, ``range``, ``polygon`` or ``costmap``. + :````.type: -:````.transport_type: + ============== ============================= + Type Default + -------------- ----------------------------- + string "scan" + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - string "raw" - ============== ============================= + Description: + Type of polygon shape. Could be ``scan``, ``pointcloud``, ``range``, ``polygon`` or ``costmap``. - Description: - For ``pointcloud`` data, specify the transport plugin to use: + :````.transport_type: - * raw: No compression. Default; highest bandwidth usage. - * draco: Lossy compression via Google. - * zlib: Lossless compression via Zlib compression. - * zstd: Lossless compression via Zstd compression. + ============== ============================= + Type Default + -------------- ----------------------------- + string "raw" + ============== ============================= - See the `known transports `_ for more details. + Description: + For ``pointcloud`` data, specify the transport plugin to use: -:````.topic: + * raw: No compression. Default; highest bandwidth usage. + * draco: Lossy compression via Google. + * zlib: Lossless compression via Zlib compression. + * zstd: Lossless compression via Zstd compression. - ============== ============================= - Type Default - -------------- ----------------------------- - string "scan" - ============== ============================= + See the `known transports `_ for more details. - Description: - Topic to listen the source data from. + :````.topic: -:````.min_height: + ============== ============================= + Type Default + -------------- ----------------------------- + string "scan" + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.05 - ============== ============================= + Description: + Topic to listen the source data from. - Description: - Minimum height the PointCloud projection to 2D space started from. Applicable for ``pointcloud`` type. + :````.min_height: -:````.max_height: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.05 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.5 - ============== ============================= + Description: + Minimum height the PointCloud projection to 2D space started from. Applicable for ``pointcloud`` type. - Description: - Maximum height the PointCloud projection to 2D space ended with. Applicable for ``pointcloud`` type. + :````.max_height: -:````.use_global_height: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + Description: + Maximum height the PointCloud projection to 2D space ended with. Applicable for ``pointcloud`` type. - Description: - Set true for pointcloud sources containing a "height" field relative to a real world ground contour. The "height" field will be used for the min and max height checks instead of the "z" field and will not be transformed as it is assumed that height is already global frame referenced. Applicable for ``pointcloud`` type. + :````.use_global_height: -:````.min_range: + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.0 - ============== ============================= + Description: + Set true for pointcloud sources containing a "height" field relative to a real world ground contour. The "height" field will be used for the min and max height checks instead of the "z" field and will not be transformed as it is assumed that height is already global frame referenced. Applicable for ``pointcloud`` type. - Description: - Minimum range threshold for PointCloud points. Points closer than this distance (measured as Euclidean distance from sensor origin) will be filtered out before processing. Useful for eliminating noise and invalid readings very close to the sensor. Applicable for ``pointcloud`` type. + :````.min_range: -:````.obstacles_angle: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double PI / 180 (1 degree) - ============== ============================= + Description: + Minimum range threshold for PointCloud points. Points closer than this distance (measured as Euclidean distance from sensor origin) will be filtered out before processing. Useful for eliminating noise and invalid readings very close to the sensor. Applicable for ``pointcloud`` type. - Description: - Angle increment (in radians) between nearby obstacle points at the range arc. Two outermost points from the field of view are not taken into account (they will always exist regardless of this value). Applicable for ``range`` type. + :````.obstacles_angle: -:````.sampling_distance: + ============== ============================= + Type Default + -------------- ----------------------------- + double PI / 180 (1 degree) + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.1 - ============== ============================= + Description: + Angle increment (in radians) between nearby obstacle points at the range arc. Two outermost points from the field of view are not taken into account (they will always exist regardless of this value). Applicable for ``range`` type. - Description: - Internally the polygon is sampled for collision detection. sampling_distance is the distance between sampled points of the polygon. Applicable for ``polygon`` source type. + :````.sampling_distance: -:````.enabled: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool True - ============== ============================= + Description: + Internally the polygon is sampled for collision detection. sampling_distance is the distance between sampled points of the polygon. Applicable for ``polygon`` source type. - Description: - Whether to use this source for collision monitoring. (Can be dynamically set) + :````.enabled: -:````.source_timeout: + ============== ============================= + Type Default + -------------- ----------------------------- + bool True + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double (node parameter ``source_timeout`` value) - ============== ============================= + Description: + Whether to use this source for collision monitoring. (Can be dynamically set) - Description: - Maximum time interval in which source data is considered as valid. If no new data is received within this interval, the robot will be stopped. Setting ``source_timeout: 0.0`` disables this blocking mechanism. Overrides node parameter for each source individually, if desired. + :````.source_timeout: -:````.cost_threshold: + ============== ============================= + Type Default + -------------- ----------------------------- + double (node parameter ``source_timeout`` value) + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - int 253 - ============== ============================= + Description: + Maximum time interval in which source data is considered as valid. If no new data is received within this interval, the robot will be stopped. Setting ``source_timeout: 0.0`` disables this blocking mechanism. Overrides node parameter for each source individually, if desired. - Description: - For ``costmap`` sources only. Minimum cell cost (0–255) to be treated as an - obstacle. By default this matches inscribed/lethal cells (253–254) and ignores - lower-cost cells. + :````.cost_threshold: -:````.treat_unknown_as_obstacle: + ============== ============================= + Type Default + -------------- ----------------------------- + int 253 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description: + For ``costmap`` sources only. Minimum cell cost (0–255) to be treated as an + obstacle. By default this matches inscribed/lethal cells (253–254) and ignores + lower-cost cells. - Description: - For ``costmap`` sources only. If ``true``, cells with cost ``255`` (``NO_INFORMATION``) - will also be turned into obstacle points. Set to ``false`` if your costmap has - large unknown areas you don’t want to trigger Collision Monitor. + :````.treat_unknown_as_obstacle: -:bond_heartbeat_period: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.25 - ============== ============================= + Description: + For ``costmap`` sources only. If ``true``, cells with cost ``255`` (``NO_INFORMATION``) + will also be turned into obstacle points. Set to ``false`` if your costmap has + large unknown areas you don’t want to trigger Collision Monitor. - Description - The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. + :bond_heartbeat_period: -:allow_parameter_qos_overrides: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.25 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. - Description - Whether to allow QoS profiles to be overwritten with parameterized values. + :allow_parameter_qos_overrides: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to allow QoS profiles to be overwritten with parameterized values. + + .. group-tab:: Kilted and older + + ```` is the corresponding data source name ID selected for this type. + + :````.type: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "scan" + ============== ============================= + + Description: + Type of polygon shape. Could be ``scan``, ``pointcloud``, ``range`` or ``polygon``. + + :````.topic: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "scan" + ============== ============================= + + Description: + Topic to listen the source data from. + + :````.min_height: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.05 + ============== ============================= + + Description: + Minimum height the PointCloud projection to 2D space started from. Applicable for ``pointcloud`` type. + + :````.max_height: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= + + Description: + Maximum height the PointCloud projection to 2D space ended with. Applicable for ``pointcloud`` type. + + :````.use_global_height: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description: + Set true for pointcloud sources containing a "height" field relative to a real world ground contour. The "height" field will be used for the min and max height checks instead of the "z" field and will not be transformed as it is assumed that height is already global frame referenced. Applicable for ``pointcloud`` type. + + :````.min_range: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0 + ============== ============================= + + Description: + Minimum range threshold for PointCloud points. Points closer than this distance (measured as Euclidean distance from sensor origin) will be filtered out before processing. Useful for eliminating noise and invalid readings very close to the sensor. Applicable for ``pointcloud`` type. + + :````.obstacles_angle: + + ============== ============================= + Type Default + -------------- ----------------------------- + double PI / 180 (1 degree) + ============== ============================= + + Description: + Angle increment (in radians) between nearby obstacle points at the range arc. Two outermost points from the field of view are not taken into account (they will always exist regardless of this value). Applicable for ``range`` type. + + :````.sampling_distance: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description: + Internally the polygon is sampled for collision detection. sampling_distance is the distance between sampled points of the polygon. Applicable for ``polygon`` source type. + + :````.enabled: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool True + ============== ============================= + + Description: + Whether to use this source for collision monitoring. (Can be dynamically set) + + :````.source_timeout: + + ============== ============================= + Type Default + -------------- ----------------------------- + double (node parameter ``source_timeout`` value) + ============== ============================= + + Description: + Maximum time interval in which source data is considered as valid. If no new data is received within this interval, the robot will be stopped. Setting ``source_timeout: 0.0`` disables this blocking mechanism. Overrides node parameter for each source individually, if desired. + + :bond_heartbeat_period: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description + The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. Example ******* @@ -705,112 +834,223 @@ Here is an example illustrating the common configurations for holonomic robots t Here is an example of configuration YAML for the Collision Monitor. -.. code-block:: yaml - - collision_monitor: - ros__parameters: - enabled: True - base_frame_id: "base_footprint" - odom_frame_id: "odom" - cmd_vel_in_topic: "cmd_vel_smoothed" - cmd_vel_out_topic: "cmd_vel" - state_topic: "collision_monitor_state" - transform_tolerance: 0.5 - source_timeout: 5.0 - base_shift_correction: True - stop_pub_timeout: 2.0 - enable_stamped_cmd_vel: True # False for Jazzy or older - use_realtime_priority: false - polygons: ["PolygonStop", "PolygonSlow", "FootprintApproach"] - PolygonStop: - type: "circle" - radius: 0.3 - action_type: "stop" - min_points: 4 # max_points: 3 for Humble - visualize: True - polygon_pub_topic: "polygon_stop" - enabled: True - PolygonSlow: - type: "polygon" - points: "[[1.0, 1.0], [1.0, -1.0], [-0.5, -1.0], [-0.5, 1.0]]" - action_type: "slowdown" - min_points: 4 # max_points: 3 for Humble - slowdown_ratio: 0.3 - visualize: True - polygon_pub_topic: "polygon_slowdown" - enabled: True - PolygonLimit: - type: "polygon" - points: "[[0.5, 0.5], [0.5, -0.5], [-0.5, -0.5], [-0.5, 0.5]]" - action_type: "limit" - min_points: 4 # max_points: 3 for Humble - linear_limit: 0.4 - angular_limit: 0.5 - visualize: True - polygon_pub_topic: "polygon_limit" - enabled: True - FootprintApproach: - type: "polygon" - action_type: "approach" - footprint_topic: "/local_costmap/published_footprint" - time_before_collision: 2.0 - simulation_time_step: 0.02 - min_points: 6 # max_points: 5 for Humble - visualize: False - enabled: True - VelocityPolygonStop: - type: "velocity_polygon" - action_type: "stop" - min_points: 6 - visualize: True - enabled: True - polygon_pub_topic: "velocity_polygon_stop" - velocity_polygons: ["rotation", "translation_forward", "translation_backward", "stopped"] - holonomic: false - rotation: - points: "[[0.3, 0.3], [0.3, -0.3], [-0.3, -0.3], [-0.3, 0.3]]" - linear_min: 0.0 - linear_max: 0.05 - theta_min: -1.0 - theta_max: 1.0 - translation_forward: - points: "[[0.35, 0.3], [0.35, -0.3], [-0.2, -0.3], [-0.2, 0.3]]" - linear_min: 0.0 - linear_max: 1.0 - theta_min: -1.0 - theta_max: 1.0 - translation_backward: - points: "[[0.2, 0.3], [0.2, -0.3], [-0.35, -0.3], [-0.35, 0.3]]" - linear_min: -1.0 - linear_max: 0.0 - theta_min: -1.0 - theta_max: 1.0 - # This is the last polygon to be checked, it should cover the entire range of robot's velocities - # It is used as the stopped polygon when the robot is not moving and as a fallback if the velocity - # is not covered by any of the other sub-polygons - stopped: - points: "[[0.25, 0.25], [0.25, -0.25], [-0.25, -0.25], [-0.25, 0.25]]" - linear_min: -1.0 - linear_max: 1.0 - theta_min: -1.0 - theta_max: 1.0 - observation_sources: ["scan", "pointcloud"] - scan: - source_timeout: 0.2 - type: "scan" - topic: "/scan" +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + collision_monitor: + ros__parameters: enabled: True - pointcloud: - type: "pointcloud" - topic: "/intel_realsense_r200_depth/points" - transport_type: "raw" # raw or/ with compression (zlib, draco, zstd) - min_height: 0.1 - max_height: 0.5 - min_range: 0.2 + base_frame_id: "base_footprint" + odom_frame_id: "odom" + cmd_vel_in_topic: "cmd_vel_smoothed" + cmd_vel_out_topic: "cmd_vel" + state_topic: "collision_monitor_state" + transform_tolerance: 0.5 + source_timeout: 5.0 + base_shift_correction: True + stop_pub_timeout: 2.0 + enable_stamped_cmd_vel: True + use_realtime_priority: false + bond_heartbeat_period: 0.25 + polygons: ["polygon_stop", "polygon_slow", "footprint_approach"] + polygon_stop: + type: "circle" + radius: 0.3 + action_type: "stop" + min_points: 4 + visualize: True + polygon_pub_topic: "polygon_stop" + enabled: True + polygon_slow: + type: "polygon" + points: "[[1.0, 1.0], [1.0, -1.0], [-0.5, -1.0], [-0.5, 1.0]]" + action_type: "slowdown" + min_points: 4 + slowdown_ratio: 0.3 + visualize: True + polygon_pub_topic: "polygon_slowdown" + enabled: True + polygon_limit: + type: "polygon" + points: "[[0.5, 0.5], [0.5, -0.5], [-0.5, -0.5], [-0.5, 0.5]]" + action_type: "limit" + min_points: 4 + linear_limit: 0.4 + angular_limit: 0.5 + visualize: True + polygon_pub_topic: "polygon_limit" + enabled: True + footprint_approach: + type: "polygon" + action_type: "approach" + footprint_topic: "/local_costmap/published_footprint" + time_before_collision: 2.0 + simulation_time_step: 0.02 + min_points: 6 + visualize: False + enabled: True + velocity_polygon_stop: + type: "velocity_polygon" + action_type: "stop" + min_points: 6 + visualize: True + enabled: True + polygon_pub_topic: "velocity_polygon_stop" + velocity_polygons: ["rotation", "translation_forward", "translation_backward", "stopped"] + holonomic: false + rotation: + points: "[[0.3, 0.3], [0.3, -0.3], [-0.3, -0.3], [-0.3, 0.3]]" + linear_min: 0.0 + linear_max: 0.05 + theta_min: -1.0 + theta_max: 1.0 + translation_forward: + points: "[[0.35, 0.3], [0.35, -0.3], [-0.2, -0.3], [-0.2, 0.3]]" + linear_min: 0.0 + linear_max: 1.0 + theta_min: -1.0 + theta_max: 1.0 + translation_backward: + points: "[[0.2, 0.3], [0.2, -0.3], [-0.35, -0.3], [-0.35, 0.3]]" + linear_min: -1.0 + linear_max: 0.0 + theta_min: -1.0 + theta_max: 1.0 + # This is the last polygon to be checked, it should cover the entire range of robot's velocities + # It is used as the stopped polygon when the robot is not moving and as a fallback if the velocity + # is not covered by any of the other sub-polygons + stopped: + points: "[[0.25, 0.25], [0.25, -0.25], [-0.25, -0.25], [-0.25, 0.25]]" + linear_min: -1.0 + linear_max: 1.0 + theta_min: -1.0 + theta_max: 1.0 + observation_sources: ["scan", "pointcloud"] + scan: + source_timeout: 0.2 + type: "scan" + topic: "/scan" + enabled: True + pointcloud: + type: "pointcloud" + topic: "/intel_realsense_r200_depth/points" + transport_type: "raw" # raw or/ with compression (zlib, draco, zstd) + min_height: 0.1 + max_height: 0.5 + min_range: 0.2 + enabled: True + # costmap: + # type: "costmap" # relative, respects namespaces + # topic: "local_costmap/costmap" + # cost_threshold: 254 + # enabled: True + # treat_unknown_as_obstacle: True + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + collision_monitor: + ros__parameters: enabled: True - # costmap: - # type: "costmap" # relative, respects namespaces - # topic: "local_costmap/costmap" - # cost_threshold: 254 - # enabled: True - # treat_unknown_as_obstacle: True + base_frame_id: "base_footprint" + odom_frame_id: "odom" + cmd_vel_in_topic: "cmd_vel_smoothed" + cmd_vel_out_topic: "cmd_vel" + state_topic: "collision_monitor_state" + transform_tolerance: 0.5 + source_timeout: 5.0 + base_shift_correction: True + stop_pub_timeout: 2.0 + enable_stamped_cmd_vel: True # False for Jazzy or older + use_realtime_priority: false + bond_heartbeat_period: 0.1 + polygons: ["PolygonStop", "PolygonSlow", "FootprintApproach"] + PolygonStop: + type: "circle" + radius: 0.3 + action_type: "stop" + min_points: 4 # max_points: 3 for Humble + visualize: True + polygon_pub_topic: "polygon_stop" + enabled: True + PolygonSlow: + type: "polygon" + points: "[[1.0, 1.0], [1.0, -1.0], [-0.5, -1.0], [-0.5, 1.0]]" + action_type: "slowdown" + min_points: 4 # max_points: 3 for Humble + slowdown_ratio: 0.3 + visualize: True + polygon_pub_topic: "polygon_slowdown" + enabled: True + PolygonLimit: + type: "polygon" + points: "[[0.5, 0.5], [0.5, -0.5], [-0.5, -0.5], [-0.5, 0.5]]" + action_type: "limit" + min_points: 4 # max_points: 3 for Humble + linear_limit: 0.4 + angular_limit: 0.5 + visualize: True + polygon_pub_topic: "polygon_limit" + enabled: True + FootprintApproach: + type: "polygon" + action_type: "approach" + footprint_topic: "/local_costmap/published_footprint" + time_before_collision: 2.0 + simulation_time_step: 0.02 + min_points: 6 # max_points: 5 for Humble + visualize: False + enabled: True + VelocityPolygonStop: + type: "velocity_polygon" + action_type: "stop" + min_points: 6 + visualize: True + enabled: True + polygon_pub_topic: "velocity_polygon_stop" + velocity_polygons: ["rotation", "translation_forward", "translation_backward", "stopped"] + holonomic: false + rotation: + points: "[[0.3, 0.3], [0.3, -0.3], [-0.3, -0.3], [-0.3, 0.3]]" + linear_min: 0.0 + linear_max: 0.05 + theta_min: -1.0 + theta_max: 1.0 + translation_forward: + points: "[[0.35, 0.3], [0.35, -0.3], [-0.2, -0.3], [-0.2, 0.3]]" + linear_min: 0.0 + linear_max: 1.0 + theta_min: -1.0 + theta_max: 1.0 + translation_backward: + points: "[[0.2, 0.3], [0.2, -0.3], [-0.35, -0.3], [-0.35, 0.3]]" + linear_min: -1.0 + linear_max: 0.0 + theta_min: -1.0 + theta_max: 1.0 + # This is the last polygon to be checked, it should cover the entire range of robot's velocities + # It is used as the stopped polygon when the robot is not moving and as a fallback if the velocity + # is not covered by any of the other sub-polygons + stopped: + points: "[[0.25, 0.25], [0.25, -0.25], [-0.25, -0.25], [-0.25, 0.25]]" + linear_min: -1.0 + linear_max: 1.0 + theta_min: -1.0 + theta_max: 1.0 + observation_sources: ["scan", "pointcloud"] + scan: + source_timeout: 0.2 + type: "scan" + topic: "/scan" + enabled: True + pointcloud: + type: "pointcloud" + topic: "/intel_realsense_r200_depth/points" + min_height: 0.1 + max_height: 0.5 + min_range: 0.2 + enabled: True diff --git a/configuration/packages/configuring-bt-xml.rst b/configuration/packages/configuring-bt-xml.rst index 2d1ac9bada..d785d1045a 100644 --- a/configuration/packages/configuring-bt-xml.rst +++ b/configuration/packages/configuring-bt-xml.rst @@ -129,41 +129,86 @@ Example This Behavior Tree replans the global path periodically at 1 Hz and it also has recovery actions. -.. code-block:: xml - - - - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + - - - - - - - - - - - - - - - - + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/configuration/packages/configuring-constrained-smoother.rst b/configuration/packages/configuring-constrained-smoother.rst index 2232065c9b..250d3d82de 100644 --- a/configuration/packages/configuring-constrained-smoother.rst +++ b/configuration/packages/configuring-constrained-smoother.rst @@ -254,36 +254,77 @@ Smoother Server Parameters Example ******* -.. code-block:: yaml - - smoother_server: - ros__parameters: - smoother_plugins: ["SmoothPath"] - - SmoothPath: - plugin: "nav2_constrained_smoother/ConstrainedSmoother" - reversing_enabled: true # whether to detect forward/reverse direction and cusps. Should be set to false for paths without orientations assigned - path_downsampling_factor: 3 # every n-th node of the path is taken. Useful for speed-up - path_upsampling_factor: 1 # 0 - path remains downsampled, 1 - path is upsampled back to original granularity using cubic bezier, 2... - more upsampling - keep_start_orientation: true # whether to prevent the start orientation from being smoothed - keep_goal_orientation: true # whether to prevent the gpal orientation from being smoothed - minimum_turning_radius: 0.40 # minimum turning radius the robot can perform. Can be set to 0.0 (or w_curve can be set to 0.0 with the same effect) for diff-drive/holonomic robots - w_curve: 30.0 # weight to enforce minimum_turning_radius - w_dist: 0.0 # weight to bind path to original as optional replacement for cost weight - w_smooth: 2000000.0 # weight to maximize smoothness of path - w_cost: 0.015 # weight to steer robot away from collision and cost - - # Parameters used to improve obstacle avoidance near cusps (forward/reverse movement changes) - w_cost_cusp_multiplier: 3.0 # option to use higher weight during forward/reverse direction change which is often accompanied with dangerous rotations - cusp_zone_length: 2.5 # length of the section around cusp in which nodes use w_cost_cusp_multiplier (w_cost rises gradually inside the zone towards the cusp point, whose costmap weight eqals w_cost*w_cost_cusp_multiplier) - - # Points in robot frame to grab costmap values from. Format: [x1, y1, weight1, x2, y2, weight2, ...] - # IMPORTANT: Requires much higher number of iterations to actually improve the path. Uncomment only if you really need it (highly elongated/asymmetric robots) - # cost_check_points: [-0.185, 0.0, 1.0] - - optimizer: - max_iterations: 70 # max iterations of smoother - debug_optimizer: false # print debug info - gradient_tol: 5e3 - fn_tol: 1.0e-15 - param_tol: 1.0e-20 + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + smoother_server: + ros__parameters: + smoother_plugins: ["smooth_path"] + + smooth_path: + plugin: "nav2_constrained_smoother/ConstrainedSmoother" + reversing_enabled: true # whether to detect forward/reverse direction and cusps. Should be set to false for paths without orientations assigned + path_downsampling_factor: 3 # every n-th node of the path is taken. Useful for speed-up + path_upsampling_factor: 1 # 0 - path remains downsampled, 1 - path is upsampled back to original granularity using cubic bezier, 2... - more upsampling + keep_start_orientation: true # whether to prevent the start orientation from being smoothed + keep_goal_orientation: true # whether to prevent the gpal orientation from being smoothed + minimum_turning_radius: 0.40 # minimum turning radius the robot can perform. Can be set to 0.0 (or w_curve can be set to 0.0 with the same effect) for diff-drive/holonomic robots + w_curve: 30.0 # weight to enforce minimum_turning_radius + w_dist: 0.0 # weight to bind path to original as optional replacement for cost weight + w_smooth: 2000000.0 # weight to maximize smoothness of path + w_cost: 0.015 # weight to steer robot away from collision and cost + + # Parameters used to improve obstacle avoidance near cusps (forward/reverse movement changes) + w_cost_cusp_multiplier: 3.0 # option to use higher weight during forward/reverse direction change which is often accompanied with dangerous rotations + cusp_zone_length: 2.5 # length of the section around cusp in which nodes use w_cost_cusp_multiplier (w_cost rises gradually inside the zone towards the cusp point, whose costmap weight eqals w_cost*w_cost_cusp_multiplier) + + # Points in robot frame to grab costmap values from. Format: [x1, y1, weight1, x2, y2, weight2, ...] + # IMPORTANT: Requires much higher number of iterations to actually improve the path. Uncomment only if you really need it (highly elongated/asymmetric robots) + # cost_check_points: [-0.185, 0.0, 1.0] + + optimizer: + max_iterations: 70 # max iterations of smoother + debug_optimizer: false # print debug info + gradient_tol: 5e3 + fn_tol: 1.0e-15 + param_tol: 1.0e-20 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + smoother_server: + ros__parameters: + smoother_plugins: ["SmoothPath"] + + SmoothPath: + plugin: "nav2_constrained_smoother/ConstrainedSmoother" + reversing_enabled: true # whether to detect forward/reverse direction and cusps. Should be set to false for paths without orientations assigned + path_downsampling_factor: 3 # every n-th node of the path is taken. Useful for speed-up + path_upsampling_factor: 1 # 0 - path remains downsampled, 1 - path is upsampled back to original granularity using cubic bezier, 2... - more upsampling + keep_start_orientation: true # whether to prevent the start orientation from being smoothed + keep_goal_orientation: true # whether to prevent the gpal orientation from being smoothed + minimum_turning_radius: 0.40 # minimum turning radius the robot can perform. Can be set to 0.0 (or w_curve can be set to 0.0 with the same effect) for diff-drive/holonomic robots + w_curve: 30.0 # weight to enforce minimum_turning_radius + w_dist: 0.0 # weight to bind path to original as optional replacement for cost weight + w_smooth: 2000000.0 # weight to maximize smoothness of path + w_cost: 0.015 # weight to steer robot away from collision and cost + + # Parameters used to improve obstacle avoidance near cusps (forward/reverse movement changes) + w_cost_cusp_multiplier: 3.0 # option to use higher weight during forward/reverse direction change which is often accompanied with dangerous rotations + cusp_zone_length: 2.5 # length of the section around cusp in which nodes use w_cost_cusp_multiplier (w_cost rises gradually inside the zone towards the cusp point, whose costmap weight eqals w_cost*w_cost_cusp_multiplier) + + # Points in robot frame to grab costmap values from. Format: [x1, y1, weight1, x2, y2, weight2, ...] + # IMPORTANT: Requires much higher number of iterations to actually improve the path. Uncomment only if you really need it (highly elongated/asymmetric robots) + # cost_check_points: [-0.185, 0.0, 1.0] + + optimizer: + max_iterations: 70 # max iterations of smoother + debug_optimizer: false # print debug info + gradient_tol: 5e3 + fn_tol: 1.0e-15 + param_tol: 1.0e-20 diff --git a/configuration/packages/configuring-controller-server.rst b/configuration/packages/configuring-controller-server.rst index 5fd1f1923f..64f7d71540 100644 --- a/configuration/packages/configuring-controller-server.rst +++ b/configuration/packages/configuring-controller-server.rst @@ -14,286 +14,542 @@ It also hosts the local costmap. Parameters ********** -:controller_frequency: +.. tabs:: - ============== ======= - Type Default - -------------- ------- - double 20.0 - ============== ======= + .. group-tab:: Rolling - Description - Frequency to run controller (Hz). + :controller_frequency: -:costmap_update_timeout: + ============== ======= + Type Default + -------------- ------- + double 20.0 + ============== ======= - ============== ======== - Type Default - -------------- -------- - double 0.3 - ============== ======== + Description + Frequency to run controller (Hz). - Description - The timeout value (seconds) for the costmap to be fully updated before a control effort can be computed. + :costmap_update_timeout: -:use_realtime_priority: + ============== ======== + Type Default + -------------- -------- + double 0.3 + ============== ======== - ============== ======= - Type Default - -------------- ------- - bool false - ============== ======= + Description + The timeout value (seconds) for the costmap to be fully updated before a control effort can be computed. - Description - Adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` + :use_realtime_priority: -:publish_zero_velocity: + ============== ======= + Type Default + -------------- ------- + bool false + ============== ======= - ============== ======= - Type Default - -------------- ------- - bool true - ============== ======= + Description + Adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` - Description - Whether to publish a zero velocity command on goal exit. This is useful for stopping the robot when a goal terminates. + :publish_zero_velocity: -:controller_plugins: + ============== ======= + Type Default + -------------- ------- + bool true + ============== ======= - ============== ============== - Type Default - -------------- -------------- - vector ['FollowPath'] - ============== ============== + Description + Whether to publish a zero velocity command on goal exit. This is useful for stopping the robot when a goal terminates. - Description - List of mapped names for controller plugins for processing requests and parameters. + :controller_plugins: - Note - Each plugin namespace defined in this list needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. + ============== ============== + Type Default + -------------- -------------- + vector ['follow_path'] + ============== ============== - Example: + Description + List of mapped names for controller plugins for processing requests and parameters. - .. code-block:: yaml + Note + Each plugin namespace defined in this list needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. - controller_server: - ros__parameters: - controller_plugins: ["FollowPath"] - FollowPath: - plugin: "dwb_core::DWBLocalPlanner" - .. + Example: -:progress_checker_plugins: + .. code-block:: yaml - ============== ============== - Type Default - -------------- -------------- - vector ["progress_checker"] - ============== ============== + controller_server: + ros__parameters: + controller_plugins: ["follow_path"] + follow_path: + plugin: "dwb_core::DWBLocalPlanner" + .. - Description - Mapped name for progress checker plugin for checking progress made by robot. Formerly ``progress_checker_plugin`` for Humble and older with a single string plugin. + :progress_checker_plugins: - Note - The plugin namespace defined needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. + ============== ============== + Type Default + -------------- -------------- + vector ["progress_checker"] + ============== ============== - Example: + Description + Mapped name for progress checker plugin for checking progress made by robot. - .. code-block:: yaml + Note + The plugin namespace defined needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. - controller_server: - ros__parameters: - progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older - progress_checker: - plugin: "nav2_controller::SimpleProgressChecker" - .. + Example: -:goal_checker_plugins: + .. code-block:: yaml - ============== ================ - Type Default - -------------- ---------------- - vector ["goal_checker"] - ============== ================ + controller_server: + ros__parameters: + progress_checker_plugins: ["progress_checker"] + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + .. - Description - Mapped name for goal checker plugin for checking goal is reached. When the number of the plugins is more than 2, each :code:`FollowPath` action needs to specify the goal checker plugin name with its :code:`goal_checker_id` field. + :goal_checker_plugins: - Note - The plugin namespace defined needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. + ============== ================ + Type Default + -------------- ---------------- + vector ["goal_checker"] + ============== ================ - Example: + Description + Mapped name for goal checker plugin for checking goal is reached. When the number of the plugins is more than 2, each :code:`follow_path` action needs to specify the goal checker plugin name with its :code:`goal_checker_id` field. - .. code-block:: yaml + Note + The plugin namespace defined needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. - controller_server: - ros__parameters: - goal_checker_plugins: ["goal_checker"] - goal_checker: - plugin: "nav2_controller::SimpleGoalChecker" + Example: -:path_handler_plugins: + .. code-block:: yaml - ============== ================ - Type Default - -------------- ---------------- - vector ["PathHandler"] - ============== ================ + controller_server: + ros__parameters: + goal_checker_plugins: ["goal_checker"] + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" - Description - Mapped name for path handler plugin for processing path from the planner. When the number of the plugins is more than 2, each :code:`FollowPath` action needs to specify the path handler plugin name with its :code:`path_handler_id` field. + :path_handler_plugins: - Note - The plugin namespace defined needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. + ============== ================ + Type Default + -------------- ---------------- + vector ["path_handler"] + ============== ================ - Example: + Description + Mapped name for path handler plugin for processing path from the planner. When the number of the plugins is more than 2, each :code:`follow_path` action needs to specify the path handler plugin name with its :code:`path_handler_id` field. - .. code-block:: yaml + Note + The plugin namespace defined needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. + + Example: + + .. code-block:: yaml + + controller_server: + ros__parameters: + path_handler_plugins: ["path_handler"] + path_handler: + plugin: "nav2_controller::FeasiblePathHandler" + + + :min_x_velocity_threshold: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0001 + ============== ============================= + + Description + The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. + Odometry values below this threshold (in m/s) will be set to 0.0. + + :min_y_velocity_threshold: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0001 + ============== ============================= + + Description + The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. + Odometry values below this threshold (in m/s) will be set to 0.0. For non-holonomic robots + + :min_theta_velocity_threshold: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0001 + ============== ============================= + + Description + The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. + Odometry values below this threshold (in rad/s) will be set to 0.0. + + :failure_tolerance: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0 + ============== ============================= + + Description + The maximum duration in seconds the called controller plugin can fail (i.e. the :code:`computeVelocityCommands` function of the plugin throwing an exception) before the :code:`nav2_msgs::action::FollowPath` action fails. + Setting it to the special value of -1.0 makes it infinite, 0 to disable, and any positive value for the appropriate timeout. + + :speed_limit_topic: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "speed_limit" + ============== ============================= + + Description + Speed limiting topic name to subscribe. This could be published by Speed Filter (please refer to :ref:`speed_filter` configuration page). You can also use this without the Speed Filter as well if you provide an external server to publish `these messages `_. + + :odom_topic: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "odom" + ============== ============================= + + Description + Topic to get instantaneous measurement of speed from. + + :odom_duration: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.3 + ============== =========================== + + Description + Time (s) to buffer odometry commands to estimate the robot speed. + + :enable_stamped_cmd_vel: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to use geometry_msgs::msg::Twist or geometry_msgs::msg::TwistStamped velocity data. + True uses TwistStamped, false uses Twist. + + :bond_heartbeat_period: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.25 + ============== ============================= + + Description + The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. + + :introspection_mode: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "disabled" + ============== ============================= + + Description + The introspection mode for services and actions. Options are "disabled", "metadata", "contents". + + :allow_parameter_qos_overrides: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to allow QoS profiles to be overwritten with parameterized values. + + :search_window: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 2.0 + ============== ============================= + + Description + How far (in meters) along the path the searching algorithm will look for the closest point. - controller_server: - ros__parameters: - path_handler_plugins: ["PathHandler"] - path_handler: - plugin: "nav2_controller::FeasiblePathHandler" + .. group-tab:: Kilted and older + :controller_frequency: -:min_x_velocity_threshold: + ============== ======= + Type Default + -------------- ------- + double 20.0 + ============== ======= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.0001 - ============== ============================= + Description + Frequency to run controller (Hz). - Description - The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. - Odometry values below this threshold (in m/s) will be set to 0.0. + :costmap_update_timeout: -:min_y_velocity_threshold: + ============== ======== + Type Default + -------------- -------- + double 0.3 + ============== ======== - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.0001 - ============== ============================= + Description + The timeout value (seconds) for the costmap to be fully updated before a control effort can be computed. - Description - The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. - Odometry values below this threshold (in m/s) will be set to 0.0. For non-holonomic robots + :use_realtime_priority: -:min_theta_velocity_threshold: + ============== ======= + Type Default + -------------- ------- + bool false + ============== ======= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.0001 - ============== ============================= + Description + Adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. This will set the controller's execution thread to a higher priority than the rest of the system (``90``) to meet scheduling deadlines to have less missed loop rates. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions: `` soft rtprio 99 hard rtprio 99`` - Description - The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. - Odometry values below this threshold (in rad/s) will be set to 0.0. + :publish_zero_velocity: -:failure_tolerance: + ============== ======= + Type Default + -------------- ------- + bool true + ============== ======= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.0 - ============== ============================= + Description + Whether to publish a zero velocity command on goal exit. This is useful for stopping the robot when a goal terminates. - Description - The maximum duration in seconds the called controller plugin can fail (i.e. the :code:`computeVelocityCommands` function of the plugin throwing an exception) before the :code:`nav2_msgs::action::FollowPath` action fails. - Setting it to the special value of -1.0 makes it infinite, 0 to disable, and any positive value for the appropriate timeout. + :action_server_result_timeout: -:speed_limit_topic: + ====== ======= ======= + Type Default Unit + ------ ------- ------- + double 10.0 seconds + ====== ======= ======= - ============== ============================= - Type Default - -------------- ----------------------------- - string "speed_limit" - ============== ============================= + Description + The timeout value (in seconds) for action servers to discard a goal handle if a result has not been produced. This used to default to + 15 minutes in rcl but was changed to 10 seconds in this `PR #1012 `_, which may be less than + some actions in Nav2 take to run. For most applications, this should not need to be adjusted as long as the actions within the server do not exceed this deadline. + This issue has been raised with OSRF to find another solution to avoid active goal timeouts for bookkeeping, so this is a semi-temporary workaround - Description - Speed limiting topic name to subscribe. This could be published by Speed Filter (please refer to :ref:`speed_filter` configuration page). You can also use this without the Speed Filter as well if you provide an external server to publish `these messages `_. + Note + Used in Jazzy. -:odom_topic: + :controller_plugins: - ============== ============================= - Type Default - -------------- ----------------------------- - string "odom" - ============== ============================= + ============== ============== + Type Default + -------------- -------------- + vector ['FollowPath'] + ============== ============== - Description - Topic to get instantaneous measurement of speed from. + Description + List of mapped names for controller plugins for processing requests and parameters. -:odom_duration: + Note + Each plugin namespace defined in this list needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. - ============== =========================== - Type Default - -------------- --------------------------- - double 0.3 - ============== =========================== + Example: - Description - Time (s) to buffer odometry commands to estimate the robot speed. + .. code-block:: yaml -:enable_stamped_cmd_vel: + controller_server: + ros__parameters: + controller_plugins: ["FollowPath"] + FollowPath: + plugin: "dwb_core::DWBLocalPlanner" + .. - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + :progress_checker_plugins: - Description - Whether to use geometry_msgs::msg::Twist or geometry_msgs::msg::TwistStamped velocity data. - True uses TwistStamped, false uses Twist. - Note: This parameter is default ``false`` in Jazzy or older! Kilted or newer uses ``TwistStamped`` by default. + ============== ============== + Type Default + -------------- -------------- + vector ["progress_checker"] + ============== ============== -:bond_heartbeat_period: + Description + Mapped name for progress checker plugin for checking progress made by robot. Formerly ``progress_checker_plugin`` for Humble and older with a single string plugin. - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.25 - ============== ============================= + Note + The plugin namespace defined needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. - Description - The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. + Example: -:introspection_mode: + .. code-block:: yaml - ============== ============================= - Type Default - -------------- ----------------------------- - string "disabled" - ============== ============================= + controller_server: + ros__parameters: + progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + .. - Description - The introspection mode for services and actions. Options are "disabled", "metadata", "contents". + :goal_checker_plugins: -:allow_parameter_qos_overrides: + ============== ================ + Type Default + -------------- ---------------- + vector ["goal_checker"] + ============== ================ - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + Mapped name for goal checker plugin for checking goal is reached. When the number of the plugins is more than 2, each :code:`FollowPath` action needs to specify the goal checker plugin name with its :code:`goal_checker_id` field. - Description - Whether to allow QoS profiles to be overwritten with parameterized values. + Note + The plugin namespace defined needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. -:search_window: + Example: - ============== ============================= - Type Default - -------------- ----------------------------- - double 2.0 - ============== ============================= + .. code-block:: yaml - Description - How far (in meters) along the path the searching algorithm will look for the closest point. + controller_server: + ros__parameters: + goal_checker_plugins: ["goal_checker"] + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + + :min_x_velocity_threshold: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0001 + ============== ============================= + + Description + The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. + Odometry values below this threshold (in m/s) will be set to 0.0. + + :min_y_velocity_threshold: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0001 + ============== ============================= + + Description + The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. + Odometry values below this threshold (in m/s) will be set to 0.0. For non-holonomic robots + + :min_theta_velocity_threshold: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0001 + ============== ============================= + + Description + The controller server filters the velocity portion of the odometry messages received before sending them to the controller plugin. + Odometry values below this threshold (in rad/s) will be set to 0.0. + + :failure_tolerance: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.0 + ============== ============================= + + Description + The maximum duration in seconds the called controller plugin can fail (i.e. the :code:`computeVelocityCommands` function of the plugin throwing an exception) before the :code:`nav2_msgs::action::FollowPath` action fails. + Setting it to the special value of -1.0 makes it infinite, 0 to disable, and any positive value for the appropriate timeout. + + :speed_limit_topic: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "speed_limit" + ============== ============================= + + Description + Speed limiting topic name to subscribe. This could be published by Speed Filter (please refer to :ref:`speed_filter` configuration page). You can also use this without the Speed Filter as well if you provide an external server to publish `these messages `_. + + :odom_topic: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "odom" + ============== ============================= + + Description + Topic to get instantaneous measurement of speed from. + + :odom_duration: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.3 + ============== =========================== + + Description + Time (s) to buffer odometry commands to estimate the robot speed. + + :enable_stamped_cmd_vel: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to use geometry_msgs::msg::Twist or geometry_msgs::msg::TwistStamped velocity data. + True uses TwistStamped, false uses Twist. + Note: This parameter is default ``false`` in Jazzy or older! Kilted or newer uses ``TwistStamped`` by default. + + :bond_heartbeat_period: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description + The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. + + :introspection_mode: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "disabled" + ============== ============================= + + Description + The introspection mode for services and actions. Options are "disabled", "metadata", "contents". Provided Plugins **************** @@ -313,56 +569,112 @@ Provided Plugins Default Plugins *************** -When the :code:`progress_checker_plugins`, :code:`goal_checker_plugin`, :code:`path_handler_plugin` or :code:`controller_plugins` parameters are not overridden, the following default plugins are loaded: +.. tabs:: + + .. group-tab:: Rolling + + When the :code:`progress_checker_plugins`, :code:`goal_checker_plugin`, :code:`path_handler_plugin` or :code:`controller_plugins` parameters are not overridden, the following default plugins are loaded: + + ================== ===================================================== + Namespace Plugin + ------------------ ----------------------------------------------------- + "progress_checker" "nav2_controller::SimpleProgressChecker" + ------------------ ----------------------------------------------------- + "goal_checker" "nav2_controller::SimpleGoalChecker" + ------------------ ----------------------------------------------------- + "path_handler" "nav2_controller::FeasiblePathHandler" + ------------------ ----------------------------------------------------- + "follow_path" "dwb_core::DWBLocalPlanner" + ================== ===================================================== - ================== ===================================================== - Namespace Plugin - ------------------ ----------------------------------------------------- - "progress_checker" "nav2_controller::SimpleProgressChecker" - ------------------ ----------------------------------------------------- - "goal_checker" "nav2_controller::SimpleGoalChecker" - ------------------ ----------------------------------------------------- - "path_handler" "nav2_controller::FeasiblePathHandler" - ------------------ ----------------------------------------------------- - "FollowPath" "dwb_core::DWBLocalPlanner" - ================== ===================================================== + .. group-tab:: Kilted and older + + When the :code:`progress_checker_plugins`, :code:`goal_checker_plugin` or :code:`controller_plugins` parameters are not overridden, the following default plugins are loaded: + + ================== ===================================================== + Namespace Plugin + ------------------ ----------------------------------------------------- + "progress_checker" "nav2_controller::SimpleProgressChecker" + ------------------ ----------------------------------------------------- + "goal_checker" "nav2_controller::SimpleGoalChecker" + ------------------ ----------------------------------------------------- + "FollowPath" "dwb_core::DWBLocalPlanner" + ================== ===================================================== Example ******* -.. code-block:: yaml - - controller_server: - ros__parameters: - controller_frequency: 20.0 - costmap_update_timeout: 0.3 - min_x_velocity_threshold: 0.001 - min_y_velocity_threshold: 0.5 - min_theta_velocity_threshold: 0.001 - failure_tolerance: 0.3 - odom_topic: "odom" - odom_duration: 0.3 - progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older - goal_checker_plugins: ["goal_checker"] # goal_checker_plugin: "goal_checker" For Galactic and older - path_handler_plguins: ["PathHandler"] - controller_plugins: ["FollowPath"] - progress_checker: - plugin: "nav2_controller::SimpleProgressChecker" - required_movement_radius: 0.5 - movement_time_allowance: 10.0 - goal_checker: - plugin: "nav2_controller::SimpleGoalChecker" - xy_goal_tolerance: 0.25 - yaw_goal_tolerance: 0.25 - path_length_tolerance: 1.0 - stateful: True - PathHandler: - plugin: "nav2_controller::FeasiblePathHandler" - prune_distance: 2.0 - enforce_path_inversion: True - enforce_path_rotation: False - inversion_xy_tolerance: 0.2 - inversion_yaw_tolerance: 0.4 - minimum_rotation_angle: 0.785 - reject_unit_path: False - FollowPath: - plugin: "dwb_core::DWBLocalPlanner" + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + costmap_update_timeout: 0.3 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + failure_tolerance: 0.3 + search_window: 2.0 + odom_topic: "odom" + odom_duration: 0.3 + bond_heartbeat_period: 0.25 + progress_checker_plugins: ["progress_checker"] + goal_checker_plugins: ["goal_checker"] + path_handler_plugins: ["path_handler"] + controller_plugins: ["follow_path"] + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + path_length_tolerance: 1.0 + stateful: True + path_handler: + plugin: "nav2_controller::FeasiblePathHandler" + prune_distance: 2.0 + enforce_path_inversion: True + enforce_path_rotation: False + inversion_xy_tolerance: 0.2 + inversion_yaw_tolerance: 0.4 + minimum_rotation_angle: 0.785 + reject_unit_path: False + follow_path: + plugin: "dwb_core::DWBLocalPlanner" + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + costmap_update_timeout: 0.3 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + failure_tolerance: 0.3 + odom_topic: "odom" + odom_duration: 0.3 + bond_heartbeat_period: 0.1 + action_server_result_timeout: 10.0 # Used in Jazzy only + progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + goal_checker_plugins: ["goal_checker"] # goal_checker_plugin: "goal_checker" For Galactic and older + controller_plugins: ["FollowPath"] + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + FollowPath: + plugin: "dwb_core::DWBLocalPlanner" diff --git a/configuration/packages/configuring-dwb-controller.rst b/configuration/packages/configuring-dwb-controller.rst index 066f565b8a..19c23eeba9 100644 --- a/configuration/packages/configuring-dwb-controller.rst +++ b/configuration/packages/configuring-dwb-controller.rst @@ -54,65 +54,145 @@ The trajectory critics listed below are inside the ``dwb_critics`` namespace. Example ******* -.. code-block:: yaml - - controller_server: - ros__parameters: - # controller server parameters (see Controller Server for more info) - controller_frequency: 20.0 - min_x_velocity_threshold: 0.001 - min_y_velocity_threshold: 0.5 - min_theta_velocity_threshold: 0.001 - progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older - goal_checker_plugins: ["goal_checker"] - controller_plugins: ["FollowPath"] - progress_checker: - plugin: "nav2_controller::SimpleProgressChecker" - required_movement_radius: 0.5 - movement_time_allowance: 10.0 - goal_checker: - plugin: "nav2_controller::SimpleGoalChecker" - xy_goal_tolerance: 0.25 - yaw_goal_tolerance: 0.25 - stateful: True - # DWB controller parameters - FollowPath: - plugin: "dwb_core::DWBLocalPlanner" - debug_trajectory_details: True - min_vel_x: 0.0 - min_vel_y: 0.0 - max_vel_x: 0.26 - max_vel_y: 0.0 - max_vel_theta: 1.0 - min_speed_xy: 0.0 - max_speed_xy: 0.26 - min_speed_theta: 0.0 - acc_lim_x: 2.5 - acc_lim_y: 0.0 - acc_lim_theta: 3.2 - decel_lim_x: -2.5 - decel_lim_y: 0.0 - decel_lim_theta: -3.2 - vx_samples: 20 - vy_samples: 5 - vtheta_samples: 20 - sim_time: 1.7 - linear_granularity: 0.05 - angular_granularity: 0.025 - xy_goal_tolerance: 0.25 - path_length_tolerance: 1.0 - trans_stopped_velocity: 0.25 - short_circuit_trajectory_evaluation: True - limit_vel_cmd_in_traj: False - stateful: True - critics: ["RotateToGoal", "Oscillation", "BaseObstacle", "GoalAlign", "PathAlign", "PathDist", "GoalDist"] - BaseObstacle.scale: 0.02 - PathAlign.scale: 32.0 - GoalAlign.scale: 24.0 - PathAlign.forward_point_distance: 0.1 - GoalAlign.forward_point_distance: 0.1 - PathDist.scale: 32.0 - GoalDist.scale: 24.0 - RotateToGoal.scale: 32.0 - RotateToGoal.slowing_factor: 5.0 - RotateToGoal.lookahead_time: -1.0 + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: + # controller server parameters (see Controller Server for more info) + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] + goal_checker_plugins: ["goal_checker"] + path_handler_plugins: ["path_handler"] + controller_plugins: ["follow_path"] + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + path_handler: + plugin: "nav2_controller::FeasiblePathHandler" + prune_distance: 2.0 + enforce_path_inversion: True + enforce_path_rotation: False + inversion_xy_tolerance: 0.2 + inversion_yaw_tolerance: 0.4 + minimum_rotation_angle: 0.785 + reject_unit_path: False + # DWB controller parameters + follow_path: + plugin: "dwb_core::DWBLocalPlanner" + debug_trajectory_details: True + min_vel_x: 0.0 + min_vel_y: 0.0 + max_vel_x: 0.26 + max_vel_y: 0.0 + max_vel_theta: 1.0 + min_speed_xy: 0.0 + max_speed_xy: 0.26 + min_speed_theta: 0.0 + acc_lim_x: 2.5 + acc_lim_y: 0.0 + acc_lim_theta: 3.2 + decel_lim_x: -2.5 + decel_lim_y: 0.0 + decel_lim_theta: -3.2 + vx_samples: 20 + vy_samples: 5 + vtheta_samples: 20 + sim_time: 1.7 + linear_granularity: 0.05 + angular_granularity: 0.025 + xy_goal_tolerance: 0.25 + path_length_tolerance: 1.0 + trans_stopped_velocity: 0.25 + short_circuit_trajectory_evaluation: True + limit_vel_cmd_in_traj: False + stateful: True + critics: ["RotateToGoal", "Oscillation", "BaseObstacle", "GoalAlign", "PathAlign", "PathDist", "GoalDist"] + BaseObstacle.scale: 0.02 + PathAlign.scale: 32.0 + GoalAlign.scale: 24.0 + PathAlign.forward_point_distance: 0.1 + GoalAlign.forward_point_distance: 0.1 + PathDist.scale: 32.0 + GoalDist.scale: 24.0 + RotateToGoal.scale: 32.0 + RotateToGoal.slowing_factor: 5.0 + RotateToGoal.lookahead_time: -1.0 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + controller_server: + ros__parameters: + # controller server parameters (see Controller Server for more info) + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + goal_checker_plugins: ["goal_checker"] + controller_plugins: ["FollowPath"] + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + # DWB controller parameters + FollowPath: + plugin: "dwb_core::DWBLocalPlanner" + debug_trajectory_details: True + min_vel_x: 0.0 + min_vel_y: 0.0 + max_vel_x: 0.26 + max_vel_y: 0.0 + max_vel_theta: 1.0 + min_speed_xy: 0.0 + max_speed_xy: 0.26 + min_speed_theta: 0.0 + acc_lim_x: 2.5 + acc_lim_y: 0.0 + acc_lim_theta: 3.2 + decel_lim_x: -2.5 + decel_lim_y: 0.0 + decel_lim_theta: -3.2 + vx_samples: 20 + vy_samples: 5 + vtheta_samples: 20 + sim_time: 1.7 + linear_granularity: 0.05 + angular_granularity: 0.025 + transform_tolerance: 0.2 + xy_goal_tolerance: 0.25 + trans_stopped_velocity: 0.25 + short_circuit_trajectory_evaluation: True + limit_vel_cmd_in_traj: False + stateful: True + critics: ["RotateToGoal", "Oscillation", "BaseObstacle", "GoalAlign", "PathAlign", "PathDist", "GoalDist"] + BaseObstacle.scale: 0.02 + PathAlign.scale: 32.0 + GoalAlign.scale: 24.0 + PathAlign.forward_point_distance: 0.1 + GoalAlign.forward_point_distance: 0.1 + PathDist.scale: 32.0 + GoalDist.scale: 24.0 + RotateToGoal.scale: 32.0 + RotateToGoal.slowing_factor: 5.0 + RotateToGoal.lookahead_time: -1.0 diff --git a/configuration/packages/configuring-graceful-motion-controller.rst b/configuration/packages/configuring-graceful-motion-controller.rst index adcf501942..598b202ec6 100644 --- a/configuration/packages/configuring-graceful-motion-controller.rst +++ b/configuration/packages/configuring-graceful-motion-controller.rst @@ -14,252 +14,525 @@ See the package's ``README`` for more complete information. Graceful Controller Parameters ****************************** -:max_lookahead: +.. tabs:: - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.0 - ============== ============================= + .. group-tab:: Rolling - Description - 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. + :max_lookahead: -:min_lookahead: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.25 - ============== ============================= + Description + 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. - 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. + :min_lookahead: -:k_phi: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.25 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 2.0 - ============== ============================= + 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. - 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. The referenced paper calls this `k1`. + :k_phi: -:k_delta: + ============== ============================= + Type Default + -------------- ----------------------------- + double 2.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.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. The referenced paper calls this `k1`. - 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. The referenced paper calls this `k2`. + :k_delta: -:beta: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.4 - ============== ============================= + 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. The referenced paper calls this `k2`. - Description - Constant factor applied to the path curvature. This value must be positive. Determines how fast the velocity drops when the curvature increases. + :beta: -:lambda: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.4 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 2.0 - ============== ============================= + Description + Constant factor applied to the path curvature. This value must be positive. Determines how fast the velocity drops when the curvature increases. - Description - Constant factor applied to the path curvature. This value must be greater or equal to 1. Determines the sharpness of the curve: higher lambda implies sharper curves. + :lambda: -:v_linear_min: + ============== ============================= + Type Default + -------------- ----------------------------- + double 2.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.1 - ============== ============================= + Description + Constant factor applied to the path curvature. This value must be greater or equal to 1. Determines the sharpness of the curve: higher lambda implies sharper curves. - Description - Minimum linear velocity (m/s). + :v_linear_min: -:v_linear_max: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.5 - ============== ============================= + Description + Minimum linear velocity (m/s). - Description - Maximum linear velocity (m/s). + :v_linear_max: -:v_angular_max: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.0 - ============== ============================= + Description + Maximum linear velocity (m/s). - Description - Maximum angular velocity (rad/s) produced by the control law. + :v_angular_max: -:v_angular_min_in_place: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.25 - ============== ============================= + Description + Maximum angular velocity (rad/s) produced by the control law. - 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. + :v_angular_min_in_place: -:slowdown_radius: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.25 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.5 - ============== ============================= + 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. - Description - Radius (m) around the goal pose in which the robot will start to slow down. + :slowdown_radius: -:initial_rotation: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.5 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + Radius (m) around the goal pose in which the robot will start to slow down. - 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: -:initial_rotation_tolerance: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.75 - ============== ============================= + 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``. - Description - 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. + :initial_rotation_tolerance: -:prefer_final_rotation: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.75 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + 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. - Description - 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. + :prefer_final_rotation: -:rotation_scaling_factor: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.5 - ============== ============================= + Description + 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. - Description - The scaling factor applied to the rotation in place velocity. + :rotation_scaling_factor: -:allow_backward: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + Description + The scaling factor applied to the rotation in place velocity. - Description - Whether to allow the robot to move backward. + :allow_backward: -:in_place_collision_tolerance: + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.1 - ============== ============================= + Description + Whether to allow the robot to move backward. - 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. + :in_place_collision_tolerance: -:use_collision_detection: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + 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. - Description - Whether to use collision detection to avoid obstacles. + :use_collision_detection: -:allow_parameter_qos_overrides: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + Whether to use collision detection to avoid obstacles. - Description - Whether to allow QoS profiles to be overwritten with parameterized values. + :allow_parameter_qos_overrides: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to allow QoS profiles to be overwritten with parameterized values. + + .. group-tab:: Kilted and older + + :max_lookahead: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= + + Description + 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. + + :transform_tolerance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.1 + ============== =========================== + + Description + The TF transform tolerance (s). + + :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: + + ============== ================================================= + Type Default + -------------- ------------------------------------------------- + double Local costmap max extent (max(width, height) / 2) + ============== ================================================= + + Description + Upper bound on integrated distance along the global plan to search for the closest pose to the robot pose. This should be left as the default unless there are paths with loops and intersections that do not leave the local costmap, in which case making this value smaller is necessary to prevent shortcutting. If set to ``-1``, it will use the maximum distance possible to search every point on the path for the nearest path point. + + :k_phi: + + ============== ============================= + Type Default + -------------- ----------------------------- + 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. The referenced paper calls this `k1`. + + :k_delta: + + ============== ============================= + Type Default + -------------- ----------------------------- + 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. The referenced paper calls this `k2`. + + :beta: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.4 + ============== ============================= + + Description + Constant factor applied to the path curvature. This value must be positive. Determines how fast the velocity drops when the curvature increases. + + :lambda: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 2.0 + ============== ============================= + + Description + Constant factor applied to the path curvature. This value must be greater or equal to 1. Determines the sharpness of the curve: higher lambda implies sharper curves. + + :v_linear_min: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description + Minimum linear velocity (m/s). + + :v_linear_max: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= + + Description + Maximum linear velocity (m/s). + + :v_angular_max: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= + + 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: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.5 + ============== ============================= + + Description + Radius (m) around the goal pose in which the robot will start to slow down. + + :initial_rotation: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + 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_tolerance: + + ============== ============================= + Type Default + -------------- ----------------------------- + 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. This value is generally acceptable if continuous replanning is enabled. If not using continuous replanning, a lower value may perform better. + + :prefer_final_rotation: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + 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: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= + + Description + The scaling factor applied to the rotation in place velocity. + + :allow_backward: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + 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. + + :use_collision_detection: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to use collision detection to avoid obstacles. Example ******* -.. code-block:: yaml - - controller_server: - ros__parameters: - controller_frequency: 20.0 - min_x_velocity_threshold: 0.001 - min_y_velocity_threshold: 0.5 - min_theta_velocity_threshold: 0.001 - progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older - goal_checker_plugins: ["goal_checker"] - controller_plugins: ["FollowPath"] - - progress_checker: - plugin: "nav2_controller::SimpleProgressChecker" - required_movement_radius: 0.5 - movement_time_allowance: 10.0 - goal_checker: - plugin: "nav2_controller::SimpleGoalChecker" - xy_goal_tolerance: 0.25 - yaw_goal_tolerance: 0.25 - stateful: True - FollowPath: - plugin: nav2_graceful_controller::GracefulController - min_lookahead: 0.25 - max_lookahead: 1.0 - initial_rotation: true - initial_rotation_threshold: 0.75 - prefer_final_rotation: true - allow_backward: false - k_phi: 2.0 - k_delta: 1.0 - beta: 0.4 - lambda: 2.0 - v_linear_min: 0.1 - v_linear_max: 0.5 - v_angular_max: 5.0 - v_angular_min_in_place: 0.25 - slowdown_radius: 1.5 + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] + goal_checker_plugins: ["goal_checker"] + controller_plugins: ["follow_path"] + + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + follow_path: + plugin: nav2_graceful_controller::GracefulController + min_lookahead: 0.25 + max_lookahead: 1.0 + initial_rotation: true + initial_rotation_threshold: 0.75 + prefer_final_rotation: true + allow_backward: false + k_phi: 2.0 + k_delta: 1.0 + beta: 0.4 + lambda: 2.0 + v_linear_min: 0.1 + v_linear_max: 0.5 + v_angular_max: 5.0 + v_angular_min_in_place: 0.25 + slowdown_radius: 1.5 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + goal_checker_plugins: ["goal_checker"] + controller_plugins: ["FollowPath"] + + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + FollowPath: + plugin: nav2_graceful_controller::GracefulController + transform_tolerance: 0.1 + min_lookahead: 0.25 + max_lookahead: 1.0 + initial_rotation: true + initial_rotation_threshold: 0.75 + prefer_final_rotation: true + allow_backward: false + k_phi: 2.0 + k_delta: 1.0 + beta: 0.4 + lambda: 2.0 + v_linear_min: 0.1 + v_linear_max: 0.5 + v_angular_max: 5.0 + v_angular_min_in_place: 0.25 + slowdown_radius: 1.5 diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index bcd4771cd2..f12e6fe245 100644 --- a/configuration/packages/configuring-mppic.rst +++ b/configuration/packages/configuring-mppic.rst @@ -30,313 +30,605 @@ See the package's ``README`` for more complete information. MPPI Parameters *************** -:motion_model: +.. tabs:: - ============== =========================== - Type Default - -------------- --------------------------- - string "DiffDrive" - ============== =========================== + .. group-tab:: Rolling - Description - The desired motion model to use for trajectory planning. Options are ``DiffDrive``, ``Omni``, or ``Ackermann``. Differential drive robots may use forward/reverse and angular velocities; Omni add in lateral motion; and Ackermann adds minimum curvature constraints. + :motion_model: -:critics: + ============== =========================== + Type Default + -------------- --------------------------- + string "DiffDrive" + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - string vector N/A - ============== =========================== + Description + The desired motion model to use for trajectory planning. Options are ``DiffDrive``, ``Omni``, or ``Ackermann``. Differential drive robots may use forward/reverse and angular velocities; Omni add in lateral motion; and Ackermann adds minimum curvature constraints. - Description - A vector of critic plugin functions to use, without ``mppi::critic::`` namespace which will be automatically added on loading. + :critics: -:iteration_count: + ============== =========================== + Type Default + -------------- --------------------------- + string vector N/A + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - int 1 - ============== =========================== + Description + A vector of critic plugin functions to use, without ``mppi::critic::`` namespace which will be automatically added on loading. - Description - Iteration count in the MPPI algorithm. Recommended to remain as 1 and instead prefer larger batch sizes. + :iteration_count: -:batch_size: + ============== =========================== + Type Default + -------------- --------------------------- + int 1 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - int 1000 - ============== =========================== + Description + Iteration count in the MPPI algorithm. Recommended to remain as 1 and instead prefer larger batch sizes. - Description - Count of randomly sampled candidate trajectories from current optimal control sequence in a given iteration. 1000 @ 50 Hz or 2000 @ 30 Hz seems to produce good results. + :batch_size: -:time_steps: + ============== =========================== + Type Default + -------------- --------------------------- + int 1000 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - int 56 - ============== =========================== + Description + Count of randomly sampled candidate trajectories from current optimal control sequence in a given iteration. 1000 @ 50 Hz or 2000 @ 30 Hz seems to produce good results. - Description - Number of time steps (points) in candidate trajectories + :time_steps: -:model_dt: + ============== =========================== + Type Default + -------------- --------------------------- + int 56 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.05 - ============== =========================== + Description + Number of time steps (points) in candidate trajectories - Description - Length of each time step's ``dt`` timestep, in seconds. ``time_steps * model_dt`` is the prediction horizon. + :model_dt: -:vx_std: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.05 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.2 - ============== =========================== + Description + Length of each time step's ``dt`` timestep, in seconds. ``time_steps * model_dt`` is the prediction horizon. - Description - Sampling standard deviation for Vx + :vx_std: -:vy_std: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.2 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.2 - ============== =========================== + Description + Sampling standard deviation for Vx - Description - Sampling standard deviation for Vy + :vy_std: -:wz_std: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.2 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.2 - ============== =========================== + Description + Sampling standard deviation for Vy - Description - Sampling standard deviation for Wz (angular velocity) + :wz_std: -:vx_max: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.2 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.5 - ============== =========================== + Description + Sampling standard deviation for Wz (angular velocity) - Description - Target maximum forward velocity (m/s). + :vx_max: -:vy_max: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.5 - ============== =========================== + Description + Target maximum forward velocity (m/s). - Description - Target maximum lateral velocity, if using ``Omni`` motion model (m/s). + :vy_max: -:vx_min: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double -0.35 - ============== =========================== + Description + Target maximum lateral velocity, if using ``Omni`` motion model (m/s). - Description - Maximum reverse velocity (m/s). + :vx_min: -:wz_max: + ============== =========================== + Type Default + -------------- --------------------------- + double -0.35 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 1.9 - ============== =========================== + Description + Maximum reverse velocity (m/s). - Description - Maximum rotational velocity (rad/s). + :wz_max: -:ax_max: + ============== =========================== + Type Default + -------------- --------------------------- + double 1.9 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 3.0 - ============== =========================== + Description + Maximum rotational velocity (rad/s). - Description - Maximum forward acceleration (m/s^2). + :ax_max: -:ay_min: + ============== =========================== + Type Default + -------------- --------------------------- + double 3.0 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double -3.0 - ============== =========================== + Description + Maximum forward acceleration (m/s^2). - Description - Minimum lateral acceleration in either direction, if using ``Omni`` motion model (m/s^2). + :ay_min: -:ay_max: + ============== =========================== + Type Default + -------------- --------------------------- + double -3.0 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 3.0 - ============== =========================== + Description + Minimum lateral acceleration in either direction, if using ``Omni`` motion model (m/s^2). - Description - Maximum lateral acceleration in either direction, if using ``Omni`` motion model (m/s^2). + :ay_max: -:ax_min: + ============== =========================== + Type Default + -------------- --------------------------- + double 3.0 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double -3.0 - ============== =========================== + Description + Maximum lateral acceleration in either direction, if using ``Omni`` motion model (m/s^2). - Description - Maximum deceleration along the X-axis (m/s^2). + :ax_min: -:az_max: + ============== =========================== + Type Default + -------------- --------------------------- + double -3.0 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 3.5 - ============== =========================== + Description + Maximum deceleration along the X-axis (m/s^2). - Description - Maximum angular acceleration (rad/s^2). + :az_max: -:temperature: + ============== =========================== + Type Default + -------------- --------------------------- + double 3.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.3 - ============== =========================== + Description + Maximum angular acceleration (rad/s^2). - Description - Selectiveness of trajectories by their costs (The closer this value to 0, the "more" we take in consideration controls with less cost), 0 mean use control with best cost, huge value will lead to just taking mean of all trajectories without cost consideration. + :temperature: -:gamma: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.3 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.015 - ============== =========================== + Description + Selectiveness of trajectories by their costs (The closer this value to 0, the "more" we take in consideration controls with less cost), 0 mean use control with best cost, huge value will lead to just taking mean of all trajectories without cost consideration. - Description - A trade-off between smoothness (high) and low energy (low). This is a complex parameter that likely won't need to be changed from the default. See Section 3D-2 in "Information Theoretic Model Predictive Control: Theory and Applications to Autonomous Driving" for detailed information. + :gamma: -:visualize: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.015 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + Description + A trade-off between smoothness (high) and low energy (low). This is a complex parameter that likely won't need to be changed from the default. See Section 3D-2 in "Information Theoretic Model Predictive Control: Theory and Applications to Autonomous Driving" for detailed information. - Description - Whether to publish debugging trajectories for visualization. This can slow down the controller substantially (e.g. 1000 batches of 56 size every 30hz is a lot of data). + :visualize: -:publish_optimal_trajectory: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + Description + Whether to publish debugging trajectories for visualization. This can slow down the controller substantially (e.g. 1000 batches of 56 size every 30hz is a lot of data). - Description - Whether to publish the optimal trajectory (pose, velocity, timestamps of via points) computed by MPC for visualization, debugging, or injection by lower-level control systems and/or collision avoidance systems that need awarenes of future velocity commands and/or poses. + :publish_optimal_trajectory: -:retry_attempt_limit: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - int 1 - ============== =========================== + Description + Whether to publish the optimal trajectory (pose, velocity, timestamps of via points) computed by MPC for visualization, debugging, or injection by lower-level control systems and/or collision avoidance systems that need awarenes of future velocity commands and/or poses. - Description - Number of attempts to find feasible trajectory on failure for soft-resets before reporting total failure. + :retry_attempt_limit: -:reset_period: + ============== =========================== + Type Default + -------------- --------------------------- + int 1 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 1.0 - ============== =========================== + Description + Number of attempts to find feasible trajectory on failure for soft-resets before reporting total failure. - Description - Required time of inactivity to reset optimizer (only in Humble due to backport ABI policies). + :regenerate_noises: -:regenerate_noises: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + Description + Whether to regenerate noises each iteration or use single noise distribution computed on initialization and reset. Practically, this is found to work fine since the trajectories are being sampled stochastically from a normal distribution and reduces compute jittering at run-time due to thread wake-ups to resample normal distribution. - Description - Whether to regenerate noises each iteration or use single noise distribution computed on initialization and reset. Practically, this is found to work fine since the trajectories are being sampled stochastically from a normal distribution and reduces compute jittering at run-time due to thread wake-ups to resample normal distribution. + :publish_critics_stats: -:publish_critics_stats: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + Description + Whether to publish statistics about each critic's performance. When enabled, publishes a ``nav2_msgs::msg::CriticsStats`` message containing critic names, whether they changed costs, and the sum of costs added by each critic for all trajectory samples. Useful for debugging and tuning critic behavior but should not be enabled for generic runtime use. - Description - Whether to publish statistics about each critic's performance. When enabled, publishes a ``nav2_msgs::msg::CriticsStats`` message containing critic names, whether they changed costs, and the sum of costs added by each critic for all trajectory samples. Useful for debugging and tuning critic behavior but should not be enabled for generic runtime use. + :open_loop: -:open_loop: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + Description + Whether to use last command velocity or use odometry for MPPI initial state estimation. When enable, use last command velocity for MPPI initial state estimation. - Description - Whether to use last command velocity or use odometry for MPPI initial state estimation. When enable, use last command velocity for MPPI initial state estimation. + :TrajectoryValidator.plugin: -:TrajectoryValidator.plugin: + ============== ========================================= + Type Default + -------------- ----------------------------------------- + string "mppi::DefaultOptimalTrajectoryValidator" + ============== ========================================= - ============== ========================================= - Type Default - -------------- ----------------------------------------- - string "mppi::DefaultOptimalTrajectoryValidator" - ============== ========================================= + Description + The plugin to use for validating final optimal trajectories. - Description - The plugin to use for validating final optimal trajectories. + .. group-tab:: Kilted and older + + :motion_model: + + ============== =========================== + Type Default + -------------- --------------------------- + string "DiffDrive" + ============== =========================== + + Description + The desired motion model to use for trajectory planning. Options are ``DiffDrive``, ``Omni``, or ``Ackermann``. Differential drive robots may use forward/reverse and angular velocities; Omni add in lateral motion; and Ackermann adds minimum curvature constraints. + + :critics: + + ============== =========================== + Type Default + -------------- --------------------------- + string vector N/A + ============== =========================== + + Description + A vector of critic plugin functions to use, without ``mppi::critic::`` namespace which will be automatically added on loading. + + :iteration_count: + + ============== =========================== + Type Default + -------------- --------------------------- + int 1 + ============== =========================== + + Description + Iteration count in the MPPI algorithm. Recommended to remain as 1 and instead prefer larger batch sizes. + + :batch_size: + + ============== =========================== + Type Default + -------------- --------------------------- + int 1000 + ============== =========================== + + Description + Count of randomly sampled candidate trajectories from current optimal control sequence in a given iteration. 1000 @ 50 Hz or 2000 @ 30 Hz seems to produce good results. + + :time_steps: + + ============== =========================== + Type Default + -------------- --------------------------- + int 56 + ============== =========================== + + Description + Number of time steps (points) in candidate trajectories + + :model_dt: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.05 + ============== =========================== + + Description + Length of each time step's ``dt`` timestep, in seconds. ``time_steps * model_dt`` is the prediction horizon. + + :vx_std: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.2 + ============== =========================== + + Description + Sampling standard deviation for Vx + + :vy_std: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.2 + ============== =========================== + + Description + Sampling standard deviation for Vy + + :wz_std: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.2 + ============== =========================== + + Description + Sampling standard deviation for Wz (angular velocity) + + :vx_max: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.5 + ============== =========================== + + Description + Target maximum forward velocity (m/s). + + :vy_max: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.5 + ============== =========================== + + Description + Target maximum lateral velocity, if using ``Omni`` motion model (m/s). + + :vx_min: + + ============== =========================== + Type Default + -------------- --------------------------- + double -0.35 + ============== =========================== + + Description + Maximum reverse velocity (m/s). + + :wz_max: + + ============== =========================== + Type Default + -------------- --------------------------- + double 1.9 + ============== =========================== + + Description + Maximum rotational velocity (rad/s). + + :ax_max: + + ============== =========================== + Type Default + -------------- --------------------------- + double 3.0 + ============== =========================== + + Description + Maximum forward acceleration (m/s^2). + + :ay_min: + + ============== =========================== + Type Default + -------------- --------------------------- + double -3.0 + ============== =========================== + + Description + Minimum lateral acceleration in either direction, if using ``Omni`` motion model (m/s^2). + + :ay_max: + + ============== =========================== + Type Default + -------------- --------------------------- + double 3.0 + ============== =========================== + + Description + Maximum lateral acceleration in either direction, if using ``Omni`` motion model (m/s^2). + + :ax_min: + + ============== =========================== + Type Default + -------------- --------------------------- + double -3.0 + ============== =========================== + + Description + Maximum deceleration along the X-axis (m/s^2). + + :az_max: + + ============== =========================== + Type Default + -------------- --------------------------- + double 3.5 + ============== =========================== + + Description + Maximum angular acceleration (rad/s^2). + + :temperature: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.3 + ============== =========================== + + Description + Selectiveness of trajectories by their costs (The closer this value to 0, the "more" we take in consideration controls with less cost), 0 mean use control with best cost, huge value will lead to just taking mean of all trajectories without cost consideration. + + :gamma: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.015 + ============== =========================== + + Description + A trade-off between smoothness (high) and low energy (low). This is a complex parameter that likely won't need to be changed from the default. See Section 3D-2 in "Information Theoretic Model Predictive Control: Theory and Applications to Autonomous Driving" for detailed information. + + :visualize: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + Whether to publish debugging trajectories for visualization. This can slow down the controller substantially (e.g. 1000 batches of 56 size every 30hz is a lot of data). + + :publish_optimal_trajectory: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + Whether to publish the optimal trajectory (pose, velocity, timestamps of via points) computed by MPC for visualization, debugging, or injection by lower-level control systems and/or collision avoidance systems that need awarenes of future velocity commands and/or poses. + + :retry_attempt_limit: + + ============== =========================== + Type Default + -------------- --------------------------- + int 1 + ============== =========================== + + Description + Number of attempts to find feasible trajectory on failure for soft-resets before reporting total failure. + + :reset_period: + + ============== =========================== + Type Default + -------------- --------------------------- + double 1.0 + ============== =========================== + + Description + Required time of inactivity to reset optimizer (only in Humble due to backport ABI policies). + + :regenerate_noises: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + Whether to regenerate noises each iteration or use single noise distribution computed on initialization and reset. Practically, this is found to work fine since the trajectories are being sampled stochastically from a normal distribution and reduces compute jittering at run-time due to thread wake-ups to resample normal distribution. + + :publish_critics_stats: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + Whether to publish statistics about each critic's performance. When enabled, publishes a ``nav2_msgs::msg::CriticsStats`` message containing critic names, whether they changed costs, and the sum of costs added by each critic for all trajectory samples. Useful for debugging and tuning critic behavior but should not be enabled for generic runtime use. + + :TrajectoryValidator.plugin: + + ============== ========================================= + Type Default + -------------- ----------------------------------------- + string "mppi::DefaultOptimalTrajectoryValidator" + ============== ========================================= + + Description + The plugin to use for validating final optimal trajectories. Trajectory Visualization ------------------------ @@ -363,6 +655,79 @@ Trajectory Visualization Description The step between points on trajectories to visualize to downsample trajectory density. +.. tabs:: + + .. group-tab:: Kilted and older + + None + Previously, these parameters belonged to the internal Path Handler. + + :transform_tolerance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.1 + ============== =========================== + + Description + Time tolerance for data transformations with TF (s). + + :prune_distance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 1.5 + ============== =========================== + + Description + Distance ahead of nearest point on path to robot to prune path to (m). This distance should be at least as great as the furthest distance of interest by a critic (i.e. for maximum velocity projection forward, threshold to consider). + + :max_robot_pose_search_dist: + + ============== =========================== + Type Default + -------------- --------------------------- + double Costmap size / 2 + ============== =========================== + + Description + Max integrated distance ahead of robot pose to search for nearest path point in case of path looping. + + :enforce_path_inversion: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + If true, it will prune paths containing cusping points for segments changing directions (e.g. path inversions) such that the controller will be forced to change directions at or very near the planner's requested inversion point. In addition, these cusping points will also be treated by the critics as local goals that the robot will attempt to reach. This is targeting Smac Planner users with feasible paths who need their robots to switch directions where specifically requested. + + :inversion_xy_tolerance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.2 + ============== =========================== + + Description + Cartesian proximity (m) to path inversion point to be considered "achieved" to pass on the rest of the path after path inversion. + + :inversion_yaw_tolerance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.4 + ============== =========================== + + Description + Angular proximity (radians) to path inversion point to be considered "achieved" to pass on the rest of the path after path inversion. 0.4 rad = 23 deg. + :allow_parameter_qos_overrides: ============== ============================= @@ -534,117 +899,213 @@ This critic incentivizes navigating spatially towards the goal when in reasonabl Obstacles Critic ---------------- -This critic incentivizes navigating away from obstacles and critical collisions using either a circular robot point-check or full SE2 footprint check using distances from obstacles. +.. tabs:: -:critical_weight: + .. group-tab:: Rolling - ============== =========================== - Type Default - -------------- --------------------------- - double 20.0 - ============== =========================== + This critic incentivizes navigating away from obstacles and critical collisions using either a circular robot point-check or full SE2 footprint check using distances from obstacles. - Description - Weight to apply to critic for near collisions closer than ``collision_margin_distance`` to prevent near collisions **only** as a method of virtually inflating the footprint. This should not be used to generally influence obstacle avoidance away from critical collisions. + :critical_weight: -:repulsion_weight: + ============== =========================== + Type Default + -------------- --------------------------- + double 20.0 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 1.5 - ============== =========================== + Description + Weight to apply to critic for near collisions closer than ``collision_margin_distance`` to prevent near collisions **only** as a method of virtually inflating the footprint. This should not be used to generally influence obstacle avoidance away from critical collisions. - Description - Weight to apply to critic for generally preferring routes in lower cost space. This is separated from the critical term to allow for fine tuning of obstacle behaviors with path alignment for dynamic scenes without impacting actions which may directly lead to near-collisions. This is applied within the ``inflation_radius`` distance from obstacles. + :repulsion_weight: -:cost_power: + ============== =========================== + Type Default + -------------- --------------------------- + double 1.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - int 1 - ============== =========================== + Description + Weight to apply to critic for generally preferring routes in lower cost space. This is separated from the critical term to allow for fine tuning of obstacle behaviors with path alignment for dynamic scenes without impacting actions which may directly lead to near-collisions. This is applied within the ``inflation_radius`` distance from obstacles (Inflation Layer parameter). - Description - Power order to apply to term. + :cost_power: -:consider_footprint: + ============== =========================== + Type Default + -------------- --------------------------- + int 1 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + Description + Power order to apply to term. - Description - Whether to use point cost (if robot is circular or low compute power) or compute SE2 footprint cost. + :consider_footprint: -:collision_cost: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 100000.0 - ============== =========================== + Description + Whether to use point cost (if robot is circular or low compute power) or compute SE2 footprint cost. - Description - Cost to apply to a true collision in a trajectory. + :collision_cost: -:collision_margin_distance: + ============== =========================== + Type Default + -------------- --------------------------- + double 100000.0 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.10 - ============== =========================== + Description + Cost to apply to a true collision in a trajectory. - Description - Margin distance (m) from collision to apply severe penalty, similar to footprint inflation. Between 0.05-0.2 is reasonable. Note that it will highly influence the controller not to enter spaces more confined than this, so ensure this parameter is set lower than the narrowest you expect the robot to need to traverse through. + :collision_margin_distance: -:near_goal_distance: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.10 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.50 - ============== =========================== + Description + Margin distance (m) from collision to apply severe penalty, similar to footprint inflation. Between 0.05-0.2 is reasonable. Note that it will highly influence the controller not to enter spaces more confined than this, so ensure this parameter is set lower than the narrowest you expect the robot to need to traverse through. - Description - Distance (m) near goal to stop applying preferential obstacle term to allow robot to smoothly converge to goal pose in close proximity to obstacles. + :near_goal_distance: -:cost_scaling_factor: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.50 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 10.0 - ============== =========================== + Description + Distance (m) near goal to stop applying preferential obstacle term to allow robot to smoothly converge to goal pose in close proximity to obstacles. - Description - Exponential decay factor across inflation radius. This should be the same as for your inflation layer (Humble only) + :inflation_layer_name: -:inflation_radius: + ============== =========================== + Type Default + -------------- --------------------------- + string "" + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.55 - ============== =========================== + Description + Name of the inflation layer. If empty, it uses the last inflation layer in the costmap. If you have multiple inflation layers, you may want to specify the name of the layer to use. - Description - Radius to inflate costmap around lethal obstacles. This should be the same as for your inflation layer (Humble only) + .. group-tab:: Kilted and older -:inflation_layer_name: + This critic incentivizes navigating away from obstacles and critical collisions using either a circular robot point-check or full SE2 footprint check using distances from obstacles. - ============== =========================== - Type Default - -------------- --------------------------- - string "" - ============== =========================== + :critical_weight: - Description - Name of the inflation layer. If empty, it uses the last inflation layer in the costmap. If you have multiple inflation layers, you may want to specify the name of the layer to use. + ============== =========================== + Type Default + -------------- --------------------------- + double 20.0 + ============== =========================== + + Description + Weight to apply to critic for near collisions closer than ``collision_margin_distance`` to prevent near collisions **only** as a method of virtually inflating the footprint. This should not be used to generally influence obstacle avoidance away from critical collisions. + + :repulsion_weight: + + ============== =========================== + Type Default + -------------- --------------------------- + double 1.5 + ============== =========================== + + Description + Weight to apply to critic for generally preferring routes in lower cost space. This is separated from the critical term to allow for fine tuning of obstacle behaviors with path alignment for dynamic scenes without impacting actions which may directly lead to near-collisions. This is applied within the ``inflation_radius`` distance from obstacles. + + :cost_power: + + ============== =========================== + Type Default + -------------- --------------------------- + int 1 + ============== =========================== + + Description + Power order to apply to term. + + :consider_footprint: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + Whether to use point cost (if robot is circular or low compute power) or compute SE2 footprint cost. + + :collision_cost: + + ============== =========================== + Type Default + -------------- --------------------------- + double 100000.0 + ============== =========================== + + Description + Cost to apply to a true collision in a trajectory. + + :collision_margin_distance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.10 + ============== =========================== + + Description + Margin distance (m) from collision to apply severe penalty, similar to footprint inflation. Between 0.05-0.2 is reasonable. Note that it will highly influence the controller not to enter spaces more confined than this, so ensure this parameter is set lower than the narrowest you expect the robot to need to traverse through. + + :near_goal_distance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.50 + ============== =========================== + + Description + Distance (m) near goal to stop applying preferential obstacle term to allow robot to smoothly converge to goal pose in close proximity to obstacles. + + :cost_scaling_factor: + + ============== =========================== + Type Default + -------------- --------------------------- + double 10.0 + ============== =========================== + + Description + Exponential decay factor across inflation radius. This should be the same as for your inflation layer (Humble only) + + :inflation_radius: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.55 + ============== =========================== + + Description + Radius to inflate costmap around lethal obstacles. This should be the same as for your inflation layer (Humble only) + + :inflation_layer_name: + + ============== =========================== + Type Default + -------------- --------------------------- + string "" + ============== =========================== + + Description + Name of the inflation layer. If empty, it uses the last inflation layer in the costmap. If you have multiple inflation layers, you may want to specify the name of the layer to use. Cost Critic @@ -1060,117 +1521,236 @@ This critic penalizes velocities that fall below the deadband threshold, helping Example ******* -.. code-block:: yaml - - controller_server: - ros__parameters: - controller_frequency: 30.0 - FollowPath: - plugin: "nav2_mppi_controller::MPPIController" - time_steps: 56 - model_dt: 0.05 - batch_size: 2000 - vx_std: 0.2 - vy_std: 0.2 - wz_std: 0.4 - vx_max: 0.5 - vx_min: -0.35 - vy_max: 0.5 - wz_max: 1.9 - ax_max: 3.0 - ax_min: -3.0 - ay_min: -3.0 - ay_max: 3.0 - az_max: 3.5 - iteration_count: 1 - temperature: 0.3 - gamma: 0.015 - motion_model: "DiffDrive" - visualize: false - reset_period: 1.0 # (only in Humble) - regenerate_noises: false - TrajectoryVisualizer: - trajectory_step: 5 - time_step: 3 - TrajectoryValidator: - plugin: "mppi::DefaultOptimalTrajectoryValidator" - collision_lookahead_time: 2.0 - consider_footprint: false - AckermannConstraints: - min_turning_r: 0.2 - critics: ["ConstraintCritic", "CostCritic", "GoalCritic", "GoalAngleCritic", "PathAlignCritic", "PathFollowCritic", "PathAngleCritic", "PreferForwardCritic"] - ConstraintCritic: - enabled: true - cost_power: 1 - cost_weight: 4.0 - GoalCritic: - enabled: true - cost_power: 1 - cost_weight: 5.0 - threshold_to_consider: 1.4 - GoalAngleCritic: - enabled: true - cost_power: 1 - cost_weight: 3.0 - threshold_to_consider: 0.5 - PreferForwardCritic: - enabled: true - cost_power: 1 - cost_weight: 5.0 - threshold_to_consider: 0.5 - # ObstaclesCritic: - # enabled: true - # cost_power: 1 - # repulsion_weight: 1.5 - # critical_weight: 20.0 - # consider_footprint: false - # collision_cost: 10000.0 - # collision_margin_distance: 0.1 - # near_goal_distance: 0.5 - # inflation_radius: 0.55 # (only in Humble) - # cost_scaling_factor: 10.0 # (only in Humble) - CostCritic: - enabled: true - cost_power: 1 - cost_weight: 3.81 - critical_cost: 300.0 - consider_footprint: true - collision_cost: 1000000.0 - near_goal_distance: 1.0 - trajectory_point_step: 2 - PathAlignCritic: - enabled: true - cost_power: 1 - cost_weight: 14.0 - max_path_occupancy_ratio: 0.05 - trajectory_point_step: 4 - threshold_to_consider: 0.5 - offset_from_furthest: 20 - use_path_orientations: false - PathFollowCritic: - enabled: true - cost_power: 1 - cost_weight: 5.0 - offset_from_furthest: 5 - threshold_to_consider: 1.4 - PathAngleCritic: - enabled: true - cost_power: 1 - cost_weight: 2.0 - offset_from_furthest: 4 - threshold_to_consider: 0.5 - max_angle_to_furthest: 1.0 - mode: 0 - # VelocityDeadbandCritic: - # enabled: true - # cost_power: 1 - # cost_weight: 35.0 - # deadband_velocities: [0.05, 0.05, 0.05] - # TwirlingCritic: - # enabled: true - # twirling_cost_power: 1 - # twirling_cost_weight: 10.0 +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 30.0 + controller_plugins: ["follow_path"] + follow_path: + plugin: "nav2_mppi_controller::MPPIController" + time_steps: 56 + model_dt: 0.05 + batch_size: 2000 + vx_std: 0.2 + vy_std: 0.2 + wz_std: 0.4 + vx_max: 0.5 + vx_min: -0.35 + vy_max: 0.5 + wz_max: 1.9 + ax_max: 3.0 + ax_min: -3.0 + ay_min: -3.0 + ay_max: 3.0 + az_max: 3.5 + iteration_count: 1 + temperature: 0.3 + gamma: 0.015 + motion_model: "DiffDrive" + visualize: false + regenerate_noises: false + open_loop: false + TrajectoryVisualizer: + trajectory_step: 5 + time_step: 3 + TrajectoryValidator: + plugin: "mppi::DefaultOptimalTrajectoryValidator" + collision_lookahead_time: 2.0 + consider_footprint: false + AckermannConstraints: + min_turning_r: 0.2 + critics: ["ConstraintCritic", "CostCritic", "GoalCritic", "GoalAngleCritic", "PathAlignCritic", "PathFollowCritic", "PathAngleCritic", "PreferForwardCritic"] + ConstraintCritic: + enabled: true + cost_power: 1 + cost_weight: 4.0 + GoalCritic: + enabled: true + cost_power: 1 + cost_weight: 5.0 + threshold_to_consider: 1.4 + GoalAngleCritic: + enabled: true + cost_power: 1 + cost_weight: 3.0 + threshold_to_consider: 0.5 + PreferForwardCritic: + enabled: true + cost_power: 1 + cost_weight: 5.0 + threshold_to_consider: 0.5 + # ObstaclesCritic: + # enabled: true + # cost_power: 1 + # repulsion_weight: 1.5 + # critical_weight: 20.0 + # consider_footprint: false + # collision_cost: 10000.0 + # collision_margin_distance: 0.1 + # near_goal_distance: 0.5 + CostCritic: + enabled: true + cost_power: 1 + cost_weight: 3.81 + critical_cost: 300.0 + consider_footprint: true + collision_cost: 1000000.0 + near_goal_distance: 1.0 + trajectory_point_step: 2 + PathAlignCritic: + enabled: true + cost_power: 1 + cost_weight: 14.0 + max_path_occupancy_ratio: 0.05 + trajectory_point_step: 4 + threshold_to_consider: 0.5 + offset_from_furthest: 20 + use_path_orientations: false + PathFollowCritic: + enabled: true + cost_power: 1 + cost_weight: 5.0 + offset_from_furthest: 5 + threshold_to_consider: 1.4 + PathAngleCritic: + enabled: true + cost_power: 1 + cost_weight: 2.0 + offset_from_furthest: 4 + threshold_to_consider: 0.5 + max_angle_to_furthest: 1.0 + mode: 0 + # VelocityDeadbandCritic: + # enabled: true + # cost_power: 1 + # cost_weight: 35.0 + # deadband_velocities: [0.05, 0.05, 0.05] + # TwirlingCritic: + # enabled: true + # twirling_cost_power: 1 + # twirling_cost_weight: 10.0 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 30.0 + controller_plugins: ["FollowPath"] + FollowPath: + plugin: "nav2_mppi_controller::MPPIController" + time_steps: 56 + model_dt: 0.05 + batch_size: 2000 + vx_std: 0.2 + vy_std: 0.2 + wz_std: 0.4 + vx_max: 0.5 + vx_min: -0.35 + vy_max: 0.5 + wz_max: 1.9 + ax_max: 3.0 + ax_min: -3.0 + ay_min: -3.0 + ay_max: 3.0 + az_max: 3.5 + iteration_count: 1 + prune_distance: 1.7 + transform_tolerance: 0.1 + temperature: 0.3 + gamma: 0.015 + motion_model: "DiffDrive" + visualize: false + reset_period: 1.0 # (only in Humble) + regenerate_noises: false + TrajectoryVisualizer: + trajectory_step: 5 + time_step: 3 + TrajectoryValidator: + plugin: "mppi::DefaultOptimalTrajectoryValidator" + collision_lookahead_time: 2.0 + consider_footprint: false + AckermannConstraints: + min_turning_r: 0.2 + critics: ["ConstraintCritic", "CostCritic", "GoalCritic", "GoalAngleCritic", "PathAlignCritic", "PathFollowCritic", "PathAngleCritic", "PreferForwardCritic"] + ConstraintCritic: + enabled: true + cost_power: 1 + cost_weight: 4.0 + GoalCritic: + enabled: true + cost_power: 1 + cost_weight: 5.0 + threshold_to_consider: 1.4 + GoalAngleCritic: + enabled: true + cost_power: 1 + cost_weight: 3.0 + threshold_to_consider: 0.5 + PreferForwardCritic: + enabled: true + cost_power: 1 + cost_weight: 5.0 + threshold_to_consider: 0.5 + # ObstaclesCritic: + # enabled: true + # cost_power: 1 + # repulsion_weight: 1.5 + # critical_weight: 20.0 + # consider_footprint: false + # collision_cost: 10000.0 + # collision_margin_distance: 0.1 + # near_goal_distance: 0.5 + # inflation_radius: 0.55 # (only in Humble) + # cost_scaling_factor: 10.0 # (only in Humble) + CostCritic: + enabled: true + cost_power: 1 + cost_weight: 3.81 + critical_cost: 300.0 + consider_footprint: true + collision_cost: 1000000.0 + near_goal_distance: 1.0 + trajectory_point_step: 2 + PathAlignCritic: + enabled: true + cost_power: 1 + cost_weight: 14.0 + max_path_occupancy_ratio: 0.05 + trajectory_point_step: 4 + threshold_to_consider: 0.5 + offset_from_furthest: 20 + use_path_orientations: false + PathFollowCritic: + enabled: true + cost_power: 1 + cost_weight: 5.0 + offset_from_furthest: 5 + threshold_to_consider: 1.4 + PathAngleCritic: + enabled: true + cost_power: 1 + cost_weight: 2.0 + offset_from_furthest: 4 + threshold_to_consider: 0.5 + max_angle_to_furthest: 1.0 + mode: 0 + # VelocityDeadbandCritic: + # enabled: true + # cost_power: 1 + # cost_weight: 35.0 + # deadband_velocities: [0.05, 0.05, 0.05] + # TwirlingCritic: + # enabled: true + # twirling_cost_power: 1 + # twirling_cost_weight: 10.0 Notes to Users ************** @@ -1182,7 +1762,7 @@ The ``model_dt`` parameter generally should be set to the duration of your contr Visualization of the trajectories using ``visualize`` uses compute resources to back out trajectories for visualization and therefore slows compute time. It is not suggested that this parameter is set to ``true`` during a deployed use, but is a useful debug instrument while tuning the system, but use sparingly. Visualizing 2000 batches @ 56 points at 30 hz is *a lot*. -The most common parameters you might want to start off changing are the velocity profiles (``vx_max``, ``vx_min``, ``wz_max``, and ``vy_max`` if holonomic) and the ``motion_model`` to correspond to your vehicle. Its wise to consider the ``prune_distance`` of the path plan in proportion to your maximum velocity and prediction horizon. The only deeper parameter that will likely need to be adjusted for your particular settings is the Obstacle critics' ``repulsion_weight`` since the tuning of this is proprtional to your inflation layer's radius. Higher radii should correspond to reduced ``repulsion_weight`` due to the penalty formation (e.g. ``inflation_radius - min_dist_to_obstacle``). If this penalty is too high, the robot will slow significantly when entering cost-space from non-cost space or jitter in narrow corridors. It is noteworthy, but likely not necessary to be changed, that the Obstacle critic may use the full footprint information if ``consider_footprint = true``, though comes at an increased compute cost. +The most common parameters you might want to start off changing are the velocity profiles (``vx_max``, ``vx_min``, ``wz_max``, and ``vy_max`` if holonomic) and the ``motion_model`` to correspond to your vehicle. Its wise to consider the ``prune_distance`` (used in Kilted and older) of the path plan in proportion to your maximum velocity and prediction horizon. The only deeper parameter that will likely need to be adjusted for your particular settings is the Obstacle critics' ``repulsion_weight`` since the tuning of this is proprtional to your inflation layer's radius. Higher radii should correspond to reduced ``repulsion_weight`` due to the penalty formation (e.g. ``inflation_radius - min_dist_to_obstacle``). If this penalty is too high, the robot will slow significantly when entering cost-space from non-cost space or jitter in narrow corridors. It is noteworthy, but likely not necessary to be changed, that the Obstacle critic may use the full footprint information if ``consider_footprint = true``, though comes at an increased compute cost. Otherwise, the parameters have been closely pre-tuned by your friendly neighborhood navigator to give you a decent starting point that hopefully you only need to retune for your specific desired behavior lightly (if at all). Varying costmap parameters or maximum speeds are the actions which require the most attention, as described below: @@ -1202,6 +1782,6 @@ There also exists a relationship between the costmap configurations and the Obst Thus, care should be taken to select weights of the obstacle critic in conjunction with the costmap inflation radius and scale so that a robot does not have such issues. How I (Steve, your friendly neighborhood navigator) tuned this was to first create the appropriate obstacle critic behavior desirable in conjunction with the inflation layer parameters. Its worth noting that the Obstacle critic converts the cost into a distance from obstacles, so the nature of the distribution of costs in the inflation isn't overly significant. However, the inflation radius and the scale will define the cost at the end of the distribution where free-space meets the lowest cost value within the radius. So testing for quality behavior when going over that threshold should be considered. -As you increase or decrease your weights on the Obstacle, you may notice the aforementioned behaviors (e.g. won't overcome free to non-free threshold). To overcome them, increase the FollowPath critic cost to increase the desire for the trajectory planner to continue moving towards the goal. Make sure to not overshoot this though, keep them balanced. A desirable outcome is smooth motion roughly in the center of spaces without significant close interactions with obstacles. It shouldn't be perfectly following a path yet nor should the output velocity be wobbling jaggedly. +As you increase or decrease your weights on the Obstacle, you may notice the aforementioned behaviors (e.g. won't overcome free to non-free threshold). To overcome them, increase the ``follow_path`` critic cost (``FollowPath`` in Kilted and older) to increase the desire for the trajectory planner to continue moving towards the goal. Make sure to not overshoot this though, keep them balanced. A desirable outcome is smooth motion roughly in the center of spaces without significant close interactions with obstacles. It shouldn't be perfectly following a path yet nor should the output velocity be wobbling jaggedly. Once you have your obstacle avoidance behavior tuned and matched with an appropriate path following penalty, tune the Path Align critic to align with the path. If you design exact-path-alignment behavior, its possible to skip the obstacle critic step as highly tuning the system to follow the path will give it less ability to deviate to avoid obstacles (though it'll slow and stop). Tuning the critic weight for the Obstacle critic high will do the job to avoid near-collisions but the repulsion weight is largely unnecessary to you. For others wanting more dynamic behavior, it *can* be beneficial to slowly lower the weight on the obstacle critic to give the path alignment critic some more room to work. If your path was generated with a cost-aware planner (like all provided by Nav2) and providing paths sufficiently far from obstacles for your satisfaction, the impact of a slightly reduced Obstacle critic with a Path Alignment critic will do you well. Not over-weighting the path align critic will allow the robot to deviate from the path to get around dynamic obstacles in the scene or other obstacles not previous considered during path planning. It is subjective as to the best behavior for your application, but it has been shown that MPPI can be an exact path tracker and/or avoid dynamic obstacles very fluidly and everywhere in between. The defaults provided are in the generally right regime for a balanced initial trade-off. diff --git a/configuration/packages/configuring-navfn.rst b/configuration/packages/configuring-navfn.rst index dde71dd71c..48298c3485 100644 --- a/configuration/packages/configuring-navfn.rst +++ b/configuration/packages/configuring-navfn.rst @@ -71,13 +71,31 @@ Parameters Example ******* -.. code-block:: yaml - - planner_server: - ros__parameters: - planner_plugins: ['GridBased'] - GridBased: - plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::" - use_astar: True - allow_unknown: True - tolerance: 1.0 + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ['grid_based'] + grid_based: + plugin: 'nav2_navfn_planner::NavfnPlanner' + use_astar: True + allow_unknown: True + tolerance: 1.0 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ['GridBased'] + GridBased: + plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::" + use_astar: True + allow_unknown: True + tolerance: 1.0 diff --git a/configuration/packages/configuring-planner-server.rst b/configuration/packages/configuring-planner-server.rst index d88e9d868c..489e91ab0e 100644 --- a/configuration/packages/configuring-planner-server.rst +++ b/configuration/packages/configuring-planner-server.rst @@ -14,118 +14,243 @@ It also hosts the global costmap. Parameters ********** -:planner_plugins: +.. tabs:: - ============== ============== - Type Default - -------------- -------------- - vector ['GridBased'] - ============== ============== + .. group-tab:: Rolling - Description - List of Mapped plugin names for parameters and processing requests. + :planner_plugins: - Note - Each plugin namespace defined in this list needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. + ============== ============== + Type Default + -------------- -------------- + vector ['grid_based'] + ============== ============== - Example: + Description + List of Mapped plugin names for parameters and processing requests. - .. code-block:: yaml + Note + Each plugin namespace defined in this list needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. + + Example: + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ["grid_based"] + grid_based: + plugin: "nav2_navfn_planner::NavfnPlanner" + .. + + :allow_partial_planning: + + ============== ======== + Type Default + -------------- -------- + bool false + ============== ======== + + Description + Allows planner server to output partial paths in the presence of obstacles when planning through poses. Otherwise planner fails and aborts the plan request in such a case by default. + + :expected_planner_frequency: + + ============== ======== + Type Default + -------------- -------- + double 20.0 + ============== ======== + + Description + Expected planner frequency. If the current frequency is less than the expected frequency, display the warning message. + + :bond_heartbeat_period: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.25 + ============== ============================= + + Description + The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. + + :costmap_update_timeout: + + ============== ======== + Type Default + -------------- -------- + double 1.0 + ============== ======== + + Description + The timeout value (seconds) for the costmap to be fully updated before a planning request. + + :introspection_mode: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "disabled" + ============== ============================= + + Description + The introspection mode for services and actions. Options are "disabled", "metadata", "contents". + + :allow_parameter_qos_overrides: - planner_server: - ros__parameters: - planner_plugins: ["GridBased"] - GridBased: - plugin: "nav2_navfn_planner::NavfnPlanner" # In Iron and older versions, "/" was used instead of "::" - .. + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= -:allow_partial_planning: + Description + Whether to allow QoS profiles to be overwritten with parameterized values. - ============== ======== - Type Default - -------------- -------- - bool false - ============== ======== + .. group-tab:: Kilted and older - Description - Allows planner server to output partial paths in the presence of obstacles when planning through poses. Otherwise planner fails and aborts the plan request in such a case by default. + :planner_plugins: -:expected_planner_frequency: + ============== ============== + Type Default + -------------- -------------- + vector ['GridBased'] + ============== ============== - ============== ======== - Type Default - -------------- -------- - double 20.0 - ============== ======== + Description + List of Mapped plugin names for parameters and processing requests. - Description - Expected planner frequency. If the current frequency is less than the expected frequency, display the warning message. + Note + Each plugin namespace defined in this list needs to have a :code:`plugin` parameter defining the type of plugin to be loaded in the namespace. -:bond_heartbeat_period: + Example: - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.25 - ============== ============================= + .. code-block:: yaml - Description - The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. + planner_server: + ros__parameters: + planner_plugins: ["GridBased"] + GridBased: + plugin: "nav2_navfn_planner::NavfnPlanner" # In Iron and older versions, "/" was used instead of "::" + .. -:costmap_update_timeout: + :expected_planner_frequency: - ============== ======== - Type Default - -------------- -------- - double 1.0 - ============== ======== + ============== ======== + Type Default + -------------- -------- + double 20.0 + ============== ======== - Description - The timeout value (seconds) for the costmap to be fully updated before a planning request. + Description + Expected planner frequency. If the current frequency is less than the expected frequency, display the warning message. -:introspection_mode: + :action_server_result_timeout: - ============== ============================= - Type Default - -------------- ----------------------------- - string "disabled" - ============== ============================= + ====== ======= ======= + Type Default Unit + ------ ------- ------- + double 10.0 seconds + ====== ======= ======= - Description - The introspection mode for services and actions. Options are "disabled", "metadata", "contents". + Description + The timeout value (in seconds) for action servers to discard a goal handle if a result has not been produced. This used to default to + 15 minutes in rcl but was changed to 10 seconds in this `PR #1012 `_, which may be less than + some actions in Nav2 take to run. For most applications, this should not need to be adjusted as long as the actions within the server do not exceed this deadline. + This issue has been raised with OSRF to find another solution to avoid active goal timeouts for bookkeeping, so this is a semi-temporary workaround -:allow_parameter_qos_overrides: + Note + Used in Jazzy. - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + :bond_heartbeat_period: - Description - Whether to allow QoS profiles to be overwritten with parameterized values. + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description + The lifecycle node bond mechanism publishing period (on the /bond topic). Disabled if inferior or equal to 0.0. + + :costmap_update_timeout: + + ============== ======== + Type Default + -------------- -------- + double 1.0 + ============== ======== + + Description + The timeout value (seconds) for the costmap to be fully updated before a planning request. + + :introspection_mode: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "disabled" + ============== ============================= + + Description + The introspection mode for services and actions. Options are "disabled", "metadata", "contents". Default Plugins *************** When the :code:`planner_plugins` parameter is not overridden, the following default plugins are loaded: - ================= ===================================================== - Namespace Plugin - ----------------- ----------------------------------------------------- - "GridBased" "nav2_navfn_planner::NavfnPlanner" - ================= ===================================================== +.. tabs:: + + .. group-tab:: Rolling + + ================= ===================================================== + Namespace Plugin + ----------------- ----------------------------------------------------- + "grid_based" "nav2_navfn_planner::NavfnPlanner" + ================= ===================================================== + + .. group-tab:: Kilted and older + + ================= ===================================================== + Namespace Plugin + ----------------- ----------------------------------------------------- + "GridBased" "nav2_navfn_planner::NavfnPlanner" + ================= ===================================================== Example ******* -.. code-block:: yaml - - planner_server: - ros__parameters: - allow_partial_planning: false - expected_planner_frequency: 20.0 - costmap_update_timeout: 1.0 - introspection_mode: "disabled" - planner_plugins: ['GridBased'] - GridBased: - plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::" + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + planner_server: + ros__parameters: + allow_partial_planning: false + expected_planner_frequency: 20.0 + costmap_update_timeout: 1.0 + introspection_mode: "disabled" + bond_heartbeat_period: 0.25 + planner_plugins: ['grid_based'] + grid_based: + plugin: 'nav2_navfn_planner::NavfnPlanner' + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + planner_server: + ros__parameters: + expected_planner_frequency: 20.0 + costmap_update_timeout: 1.0 + introspection_mode: "disabled" + bond_heartbeat_period: 0.1 + action_server_result_timeout: 10.0 # Used in Jazzy + planner_plugins: ['GridBased'] + GridBased: + plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::" diff --git a/configuration/packages/configuring-regulated-pp.rst b/configuration/packages/configuring-regulated-pp.rst index 1dc62bab61..761fa0a56a 100644 --- a/configuration/packages/configuring-regulated-pp.rst +++ b/configuration/packages/configuring-regulated-pp.rst @@ -43,462 +43,859 @@ If you use the Dynamic Window Pure Pursuit Controller algorithm or software from Regulated Pure Pursuit Parameters ********************************* -:max_linear_vel: +.. tabs:: - ============== =========================== - Type Default - -------------- --------------------------- - double 0.5 - ============== =========================== + .. group-tab:: Rolling - Description - The maximum linear velocity (m/s) to use. Previously `desired_linear_vel` + :max_linear_vel: -:min_linear_vel: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double -0.5 - ============== =========================== + Description + The maximum linear velocity (m/s) to use. - Description - The minimum linear velocity (m/s) used when `use_dynamic_window` is `true`. + :min_linear_vel: -:max_angular_vel: + ============== =========================== + Type Default + -------------- --------------------------- + double -0.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 2.5 - ============== =========================== + Description + The minimum linear velocity (m/s) used when `use_dynamic_window` is `true`. - Description - The maximum angular velocity (rad/s) used when `use_dynamic_window` is `true`. + :max_angular_vel: -:min_angular_vel: + ============== =========================== + Type Default + -------------- --------------------------- + double 2.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double -2.5 - ============== =========================== + Description + The maximum angular velocity (rad/s) used when `use_dynamic_window` is `true`. - Description - The minimum angular velocity (rad/s) used when `use_dynamic_window` is `true`. + :min_angular_vel: -:max_linear_accel: + ============== =========================== + Type Default + -------------- --------------------------- + double -2.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 2.5 - ============== =========================== + Description + The minimum angular velocity (rad/s) used when `use_dynamic_window` is `true`. - Description - The maximum linear acceleration (m/s^2) used when `use_dynamic_window` is `true`. + :max_linear_accel: -:max_linear_decel: + ============== =========================== + Type Default + -------------- --------------------------- + double 2.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double -2.5 - ============== =========================== + Description + The maximum linear acceleration (m/s^2) used when `use_dynamic_window` is `true`. - Description - The maximum linear deceleration (m/s^2) used when `use_dynamic_window` is `true`. + :max_linear_decel: -:max_angular_accel: + ============== =========================== + Type Default + -------------- --------------------------- + double -2.5 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 3.2 - ============== =========================== + Description + The maximum linear deceleration (m/s^2) used when `use_dynamic_window` is `true`. - Description - The maximum angular acceleration (rad/s^2) to use. + :max_angular_accel: -:max_angular_decel: + ============== =========================== + Type Default + -------------- --------------------------- + double 3.2 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double -3.2 - ============== =========================== + Description + The maximum angular acceleration (rad/s^2) to use. - Description - The maximum angular deceleration (rad/s^2) used when `use_dynamic_window` is `true`. + :max_angular_decel: -:lookahead_dist: + ============== =========================== + Type Default + -------------- --------------------------- + double -3.2 + ============== =========================== - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.6 - ============== ============================= + Description + The maximum angular deceleration (rad/s^2) used when `use_dynamic_window` is `true`. - Description - The lookahead distance (m) to use to find the lookahead point when ``use_velocity_scaled_lookahead_dist`` is ``false``. + :lookahead_dist: -:min_lookahead_dist: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.3 - ============== ============================= + Description + The lookahead distance (m) to use to find the lookahead point when ``use_velocity_scaled_lookahead_dist`` is ``false``. - Description - The minimum lookahead distance (m) threshold when ``use_velocity_scaled_lookahead_dist`` is ``true``. + :min_lookahead_dist: -:max_lookahead_dist: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.3 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.9 - ============== ============================= + Description + The minimum lookahead distance (m) threshold when ``use_velocity_scaled_lookahead_dist`` is ``true``. - Description - The maximum lookahead distance (m) threshold when ``use_velocity_scaled_lookahead_dist`` is ``true``. + :max_lookahead_dist: -:lookahead_time: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.9 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.5 - ============== ============================= + Description + The maximum lookahead distance (m) threshold when ``use_velocity_scaled_lookahead_dist`` is ``true``. - Description - The time (s) to project the velocity by when ``use_velocity_scaled_lookahead_dist`` is ``true``. Also known as the lookahead gain. + :lookahead_time: -:rotate_to_heading_angular_vel: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.5 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.8 - ============== ============================= + Description + The time (s) to project the velocity by when ``use_velocity_scaled_lookahead_dist`` is ``true``. Also known as the lookahead gain. - Description - If ``use_rotate_to_heading`` is ``true``, this is the angular velocity to use. + :rotate_to_heading_angular_vel: -:use_velocity_scaled_lookahead_dist: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.8 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + Description + If ``use_rotate_to_heading`` is ``true``, this is the angular velocity to use. - Description - Whether to use the velocity scaled lookahead distances or constant ``lookahead_distance``. + :use_velocity_scaled_lookahead_dist: -:min_approach_linear_velocity: + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.05 - ============== ============================= + Description + Whether to use the velocity scaled lookahead distances or constant ``lookahead_distance``. - Description - The minimum velocity (m/s) threshold to apply when approaching the goal to ensure progress. Must be ``> 0.01``. + :min_approach_linear_velocity: -:approach_velocity_scaling_dist: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.05 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.6 - ============== ============================= + Description + The minimum velocity (m/s) threshold to apply when approaching the goal to ensure progress. Must be ``> 0.01``. - Description - The distance (m) left on the path at which to start slowing down. Should be less than the half the costmap width. + :approach_velocity_scaling_dist: -:use_collision_detection: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + The distance (m) left on the path at which to start slowing down. Should be less than the half the costmap width. - Description - Whether to enable collision detection. + :use_collision_detection: -:max_allowed_time_to_collision_up_to_carrot: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.0 - ============== ============================= + Description + Whether to enable collision detection. - Description - The time (s) to project a velocity command forward to check for collisions when ``use_collision_detection`` is ``true``. Pre-``Humble``, this was ``max_allowed_time_to_collision``. + :max_allowed_time_to_collision_up_to_carrot: -:use_regulated_linear_velocity_scaling: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + The time (s) to project a velocity command forward to check for collisions when ``use_collision_detection`` is ``true``. - Description - Whether to use the regulated features for path curvature (e.g. slow on high curvature paths). + :use_regulated_linear_velocity_scaling: -:use_cost_regulated_linear_velocity_scaling: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + Whether to use the regulated features for path curvature (e.g. slow on high curvature paths). - Description - Whether to use the regulated features for proximity to obstacles (e.g. slow in close proximity to obstacles). + :use_cost_regulated_linear_velocity_scaling: -:cost_scaling_dist: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.6 - ============== ============================= + Description + Whether to use the regulated features for proximity to obstacles (e.g. slow in close proximity to obstacles). - Description - The minimum distance from an obstacle to trigger the scaling of linear velocity, if ``use_cost_regulated_linear_velocity_scaling`` is enabled. The value set should be smaller or equal to the ``inflation_radius`` set in the inflation layer of costmap, since inflation is used to compute the distance from obstacles. + :cost_scaling_dist: -:cost_scaling_gain: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.0 - ============== ============================= + Description + The minimum distance from an obstacle to trigger the scaling of linear velocity, if ``use_cost_regulated_linear_velocity_scaling`` is enabled. The value set should be smaller or equal to the ``inflation_radius`` set in the inflation layer of costmap, since inflation is used to compute the distance from obstacles. - Description - A multiplier gain, which should be <= 1.0, used to further scale the speed when an obstacle is within ``cost_scaling_dist``. Lower value reduces speed more quickly. + :cost_scaling_gain: -:regulated_linear_scaling_min_radius: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.90 - ============== ============================= + Description + A multiplier gain, which should be <= 1.0, used to further scale the speed when an obstacle is within ``cost_scaling_dist``. Lower value reduces speed more quickly. - Description - The turning radius (m) for which the regulation features are triggered when ``use_regulated_linear_velocity_scaling`` is ``true``. Remember, sharper turns have smaller radii. + :regulated_linear_scaling_min_radius: -:regulated_linear_scaling_min_speed: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.90 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.25 - ============== ============================= + Description + The turning radius (m) for which the regulation features are triggered when ``use_regulated_linear_velocity_scaling`` is ``true``. Remember, sharper turns have smaller radii. - Description - The minimum speed (m/s) for which any of the regulated heuristics can send, to ensure process is still achievable even in high cost spaces with high curvature. Must be ``> 0.1``. + :regulated_linear_scaling_min_speed: -:use_fixed_curvature_lookahead: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.25 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + Description + The minimum speed (m/s) for which any of the regulated heuristics can send, to ensure process is still achievable even in high cost spaces with high curvature. Must be ``> 0.1``. - Description - Whether to use a fixed lookahead distance to compute curvature from. Since a lookahead distance may be set to vary on velocity, it can introduce a reference cycle that can be problematic for large lookahead distances. + :use_fixed_curvature_lookahead: -:curvature_lookahead_dist: + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.6 - ============== ============================= + Description + Whether to use a fixed lookahead distance to compute curvature from. Since a lookahead distance may be set to vary on velocity, it can introduce a reference cycle that can be problematic for large lookahead distances. - Description - Distance to look ahead on the path to detect curvature. + :curvature_lookahead_dist: -:use_rotate_to_heading: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + Distance to look ahead on the path to detect curvature. - Description - Whether to enable rotating to rough heading and goal orientation when using holonomic planners. Recommended on for all robot types that can rotate in place. + :use_rotate_to_heading: - Note: both ``use_rotate_to_heading`` and ``allow_reversing`` cannot be set to ``true`` at the same time as it would result in ambiguous situations. + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= -:allow_reversing: + Description + Whether to enable rotating to rough heading and goal orientation when using holonomic planners. Recommended on for all robot types that can rotate in place. - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + Note: both ``use_rotate_to_heading`` and ``allow_reversing`` cannot be set to ``true`` at the same time as it would result in ambiguous situations. - Description - Enables the robot to drive in the reverse direction, when the path planned involves reversing (which is represented by orientation cusps). Variants of the smac_planner comes with the support of reversing. Checkout the :ref:`configuring_smac_planner` to know more. + :allow_reversing: -:rotate_to_heading_min_angle: + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.785 - ============== ============================= + Description + Enables the robot to drive in the reverse direction, when the path planned involves reversing (which is represented by orientation cusps). Variants of the smac_planner comes with the support of reversing. Checkout the :ref:`configuring_smac_planner` to know more. - Description - The difference in the path orientation and the starting robot orientation (radians) to trigger a rotate in place, if ``use_rotate_to_heading`` is ``true``. + :rotate_to_heading_min_angle: -:use_cancel_deceleration: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.785 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + Description + The difference in the path orientation and the starting robot orientation (radians) to trigger a rotate in place, if ``use_rotate_to_heading`` is ``true``. - Description - Whether to use deceleration when the goal is canceled. + :use_cancel_deceleration: -:cancel_deceleration: + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 3.2 - ============== ============================= + Description + Whether to use deceleration when the goal is canceled. - Description - Linear deceleration (m/s/s) to apply when the goal is canceled. + :cancel_deceleration: -:interpolate_curvature_after_goal: + ============== ============================= + Type Default + -------------- ----------------------------- + double 3.2 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + Description + Linear deceleration (m/s/s) to apply when the goal is canceled. - Description - Interpolate a carrot after the goal dedicated to the curvate calculation (to avoid oscilaltions at the end of the path). For visualization, it will be published on the ``/curvature_lookahead_point`` topic similarly to ``/lookahead_point`` + :interpolate_curvature_after_goal: - Note: Needs ``use_fixed_curvature_lookahead`` to be ``true`` + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= -:stateful: + Description + Interpolate a carrot after the goal dedicated to the curvate calculation (to avoid oscilaltions at the end of the path). For visualization, it will be published on the ``/curvature_lookahead_point`` topic similarly to ``/lookahead_point`` - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Note: Needs ``use_fixed_curvature_lookahead`` to be ``true`` - Description - Enables stateful goal handling behavior. When set to true, the controller will persist the goal state once the robot reaches the XY tolerance. It will then focus on aligning to the goal heading without reverting to XY position corrections. + :stateful: -:allow_parameter_qos_overrides: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + Enables stateful goal handling behavior. When set to true, the controller will persist the goal state once the robot reaches the XY tolerance. It will then focus on aligning to the goal heading without reverting to XY position corrections. - Description - Whether to allow QoS profiles to be overwritten with parameterized values. + :allow_parameter_qos_overrides: -:min_distance_to_obstacle: + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double -1.0 - ============== ============================= + Description + Whether to allow QoS profiles to be overwritten with parameterized values. - Description - The shortest distance at which the robot is allowed to be from an obstacle along its trajectory. Set <= 0.0 to disable. It is limited to maximum distance of lookahead distance selected. + :min_distance_to_obstacle: -:use_dynamic_window: + ============== ============================= + Type Default + -------------- ----------------------------- + double -1.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + Description + The shortest distance at which the robot is allowed to be from an obstacle along its trajectory. Set <= 0.0 to disable. It is limited to maximum distance of lookahead distance selected. - Description - Whether to use the Dynamic Window Pure Pursuit (DWPP) Algorithm. This algorithm computes command velocities that track the path as accurately as possible while respecting velocity and acceleration constraints. It automatically slows down in sharp turns without manual tuning, reducing path tracking errors. - Fumiya Ohnishi and Masaki Takahashi, "Dynamic Window Pure Pursuit for Robot Path Tracking Considering Velocity and Acceleration Constraints", the 19th International Conference on Intelligent Autonomous Systems (IAS-19), 2025. + :use_dynamic_window: + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + Whether to use the Dynamic Window Pure Pursuit (DWPP) Algorithm. This algorithm computes command velocities that track the path as accurately as possible while respecting velocity and acceleration constraints. It automatically slows down in sharp turns without manual tuning, reducing path tracking errors. + Fumiya Ohnishi and Masaki Takahashi, "Dynamic Window Pure Pursuit for Robot Path Tracking Considering Velocity and Acceleration Constraints", the 19th International Conference on Intelligent Autonomous Systems (IAS-19), 2025. + + + .. group-tab:: Kilted and older + + :desired_linear_vel: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.5 + ============== =========================== + + Description + The desired maximum linear velocity (m/s) to use. + + :lookahead_dist: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= + + Description + The lookahead distance (m) to use to find the lookahead point when ``use_velocity_scaled_lookahead_dist`` is ``false``. + + :min_lookahead_dist: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.3 + ============== ============================= + + Description + The minimum lookahead distance (m) threshold when ``use_velocity_scaled_lookahead_dist`` is ``true``. + + :max_lookahead_dist: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.9 + ============== ============================= + + Description + The maximum lookahead distance (m) threshold when ``use_velocity_scaled_lookahead_dist`` is ``true``. + + :lookahead_time: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.5 + ============== ============================= + + Description + The time (s) to project the velocity by when ``use_velocity_scaled_lookahead_dist`` is ``true``. Also known as the lookahead gain. + + :rotate_to_heading_angular_vel: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.8 + ============== ============================= + + Description + If ``use_rotate_to_heading`` is ``true``, this is the angular velocity to use. + + :transform_tolerance: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= + + Description + The TF transform tolerance (s). + + :use_velocity_scaled_lookahead_dist: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + Whether to use the velocity scaled lookahead distances or constant ``lookahead_distance``. + + :min_approach_linear_velocity: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.05 + ============== ============================= + + Description + The minimum velocity (m/s) threshold to apply when approaching the goal to ensure progress. Must be ``> 0.01``. + + :approach_velocity_scaling_dist: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= + + Description + The distance (m) left on the path at which to start slowing down. Should be less than the half the costmap width. + + :use_collision_detection: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to enable collision detection. + + :max_allowed_time_to_collision_up_to_carrot: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= + + Description + The time (s) to project a velocity command forward to check for collisions when ``use_collision_detection`` is ``true``. Pre-``Humble``, this was ``max_allowed_time_to_collision``. + + :use_regulated_linear_velocity_scaling: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to use the regulated features for path curvature (e.g. slow on high curvature paths). + + :use_cost_regulated_linear_velocity_scaling: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to use the regulated features for proximity to obstacles (e.g. slow in close proximity to obstacles). + + :cost_scaling_dist: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= + + Description + The minimum distance from an obstacle to trigger the scaling of linear velocity, if ``use_cost_regulated_linear_velocity_scaling`` is enabled. The value set should be smaller or equal to the ``inflation_radius`` set in the inflation layer of costmap, since inflation is used to compute the distance from obstacles. + + :cost_scaling_gain: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= + + Description + A multiplier gain, which should be <= 1.0, used to further scale the speed when an obstacle is within ``cost_scaling_dist``. Lower value reduces speed more quickly. + + :regulated_linear_scaling_min_radius: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.90 + ============== ============================= + + Description + The turning radius (m) for which the regulation features are triggered when ``use_regulated_linear_velocity_scaling`` is ``true``. Remember, sharper turns have smaller radii. + + :regulated_linear_scaling_min_speed: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.25 + ============== ============================= + + Description + The minimum speed (m/s) for which any of the regulated heuristics can send, to ensure process is still achievable even in high cost spaces with high curvature. Must be ``> 0.1``. + + :use_fixed_curvature_lookahead: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + Whether to use a fixed lookahead distance to compute curvature from. Since a lookahead distance may be set to vary on velocity, it can introduce a reference cycle that can be problematic for large lookahead distances. + + :curvature_lookahead_dist: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.6 + ============== ============================= + + Description + Distance to look ahead on the path to detect curvature. + + :use_rotate_to_heading: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to enable rotating to rough heading and goal orientation when using holonomic planners. Recommended on for all robot types that can rotate in place. + + Note: both ``use_rotate_to_heading`` and ``allow_reversing`` cannot be set to ``true`` at the same time as it would result in ambiguous situations. + + :allow_reversing: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + Enables the robot to drive in the reverse direction, when the path planned involves reversing (which is represented by orientation cusps). Variants of the smac_planner comes with the support of reversing. Checkout the :ref:`configuring_smac_planner` to know more. + + :rotate_to_heading_min_angle: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.785 + ============== ============================= + + Description + The difference in the path orientation and the starting robot orientation (radians) to trigger a rotate in place, if ``use_rotate_to_heading`` is ``true``. + + :max_angular_accel: + + ============== =========================== + Type Default + -------------- --------------------------- + double 3.2 + ============== =========================== + + Description + The maximum angular acceleration (rad/s^2) to use. + + :use_cancel_deceleration: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + Whether to use deceleration when the goal is canceled. + + :cancel_deceleration: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 3.2 + ============== ============================= + + Description + Linear deceleration (m/s/s) to apply when the goal is canceled. + + :max_robot_pose_search_dist: + + ============== ================================================= + Type Default + -------------- ------------------------------------------------- + double Local costmap max extent (max(width, height) / 2) + ============== ================================================= + + Description + Upper bound on integrated distance along the global plan to search for the closest pose to the robot pose. This should be left as the default unless there are paths with loops and intersections that do not leave the local costmap, in which case making this value smaller is necessary to prevent shortcutting. If set to ``-1``, it will use the maximum distance possible to search every point on the path for the nearest path point. + + :interpolate_curvature_after_goal: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + Interpolate a carrot after the goal dedicated to the curvate calculation (to avoid oscilaltions at the end of the path). For visualization, it will be published on the ``/curvature_lookahead_point`` topic similarly to ``/lookahead_point`` + + Note: Needs ``use_fixed_curvature_lookahead`` to be ``true`` + + :stateful: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Enables stateful goal handling behavior. When set to true, the controller will persist the goal state once the robot reaches the XY tolerance. It will then focus on aligning to the goal heading without reverting to XY position corrections. + + :min_distance_to_obstacle: + + ============== ============================= + Type Default + -------------- ----------------------------- + double -1.0 + ============== ============================= + + Description + The shortest distance at which the robot is allowed to be from an obstacle along its trajectory. Set <= 0.0 to disable. It is limited to maximum distance of lookahead distance selected. Example ******* -.. code-block:: yaml - - controller_server: - ros__parameters: - controller_frequency: 20.0 - min_x_velocity_threshold: 0.001 - min_y_velocity_threshold: 0.5 - min_theta_velocity_threshold: 0.001 - progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older - goal_checker_plugins: ["goal_checker"] - controller_plugins: ["FollowPath"] - - progress_checker: - plugin: "nav2_controller::SimpleProgressChecker" - required_movement_radius: 0.5 - movement_time_allowance: 10.0 - goal_checker: - plugin: "nav2_controller::SimpleGoalChecker" - xy_goal_tolerance: 0.25 - yaw_goal_tolerance: 0.25 - stateful: True - FollowPath: - plugin: "nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController" - max_linear_vel: 0.5 - min_linear_vel: -0.5 - max_angular_vel: 2.5 - min_angular_vel: -2.5 - max_linear_accel: 2.5 - max_linear_decel: -2.5 - max_angular_accel: 3.2 - max_angular_decel: -3.2 - lookahead_dist: 0.6 - min_lookahead_dist: 0.3 - max_lookahead_dist: 0.9 - lookahead_time: 1.5 - rotate_to_heading_angular_vel: 1.8 - use_velocity_scaled_lookahead_dist: false - min_approach_linear_velocity: 0.05 - approach_velocity_scaling_dist: 0.6 - use_collision_detection: true - max_allowed_time_to_collision_up_to_carrot: 1.0 - use_regulated_linear_velocity_scaling: true - use_fixed_curvature_lookahead: false - curvature_lookahead_dist: 0.25 - use_cost_regulated_linear_velocity_scaling: false - cost_scaling_dist: 0.3 - cost_scaling_gain: 1.0 - regulated_linear_scaling_min_radius: 0.9 - regulated_linear_scaling_min_speed: 0.25 - use_rotate_to_heading: true - allow_reversing: false - rotate_to_heading_min_angle: 0.785 - min_distance_to_obstacle: 0.0 - stateful: true - use_dynamic_window: false + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] + goal_checker_plugins: ["goal_checker"] + controller_plugins: ["follow_path"] + + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + follow_path: + plugin: "nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController" + max_linear_vel: 0.5 + min_linear_vel: -0.5 + max_angular_vel: 2.5 + min_angular_vel: -2.5 + max_linear_accel: 2.5 + max_linear_decel: -2.5 + max_angular_accel: 3.2 + max_angular_decel: -3.2 + lookahead_dist: 0.6 + min_lookahead_dist: 0.3 + max_lookahead_dist: 0.9 + lookahead_time: 1.5 + rotate_to_heading_angular_vel: 1.8 + use_velocity_scaled_lookahead_dist: false + min_approach_linear_velocity: 0.05 + approach_velocity_scaling_dist: 0.6 + use_collision_detection: true + max_allowed_time_to_collision_up_to_carrot: 1.0 + use_regulated_linear_velocity_scaling: true + use_fixed_curvature_lookahead: false + curvature_lookahead_dist: 0.25 + use_cost_regulated_linear_velocity_scaling: false + cost_scaling_dist: 0.3 + cost_scaling_gain: 1.0 + regulated_linear_scaling_min_radius: 0.9 + regulated_linear_scaling_min_speed: 0.25 + use_rotate_to_heading: true + allow_reversing: false + rotate_to_heading_min_angle: 0.785 + min_distance_to_obstacle: 0.0 + stateful: true + use_dynamic_window: false + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + goal_checker_plugins: ["goal_checker"] + controller_plugins: ["FollowPath"] + + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + FollowPath: + plugin: "nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController" + desired_linear_vel: 0.5 + lookahead_dist: 0.6 + min_lookahead_dist: 0.3 + max_lookahead_dist: 0.9 + lookahead_time: 1.5 + rotate_to_heading_angular_vel: 1.8 + transform_tolerance: 0.1 + use_velocity_scaled_lookahead_dist: false + min_approach_linear_velocity: 0.05 + approach_velocity_scaling_dist: 0.6 + use_collision_detection: true + max_allowed_time_to_collision_up_to_carrot: 1.0 + use_regulated_linear_velocity_scaling: true + use_fixed_curvature_lookahead: false + curvature_lookahead_dist: 0.25 + use_cost_regulated_linear_velocity_scaling: false + cost_scaling_dist: 0.3 + cost_scaling_gain: 1.0 + regulated_linear_scaling_min_radius: 0.9 + regulated_linear_scaling_min_speed: 0.25 + use_rotate_to_heading: true + allow_reversing: false + rotate_to_heading_min_angle: 0.785 + max_angular_accel: 3.2 + max_robot_pose_search_dist: 10.0 + stateful: true diff --git a/configuration/packages/configuring-rotation-shim-controller.rst b/configuration/packages/configuring-rotation-shim-controller.rst index 21ec3ff8e4..f6c05b1d87 100644 --- a/configuration/packages/configuring-rotation-shim-controller.rst +++ b/configuration/packages/configuring-rotation-shim-controller.rst @@ -30,161 +30,333 @@ See the package's ``README`` for more complete information. Rotation Shim Controller Parameters *********************************** -:angular_dist_threshold: +.. tabs:: - ============== =========================== - Type Default - -------------- --------------------------- - double 0.785 - ============== =========================== + .. group-tab:: Rolling - Description - Maximum angular distance, in radians, away from the path heading to trigger rotation + :angular_dist_threshold: -:angular_disengage_threshold: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.785 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.3925 - ============== =========================== + Description + Maximum angular distance, in radians, away from the path heading to trigger rotation - Description - New to Jazzy, the threshold to the path's heading before disengagement (radians). Prior to Jazzy, disengagement occurs at the ``angular_dist_threshold`` instead. This allows for better alignment before passing to the child controller when engaged. + :angular_disengage_threshold: -:forward_sampling_distance: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.3925 + ============== =========================== - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.5 - ============== ============================= + Description + New to Jazzy, the threshold to the path's heading before disengagement (radians). Prior to Jazzy, disengagement occurs at the ``angular_dist_threshold`` instead. This allows for better alignment before passing to the child controller when engaged. - Description - Forward distance, in meters, along path to select a sampling point to use to approximate path heading. This distance should not be larger than the path handler's prune distance. + :forward_sampling_distance: -:rotate_to_heading_angular_vel: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.8 - ============== ============================= + Description + Forward distance, in meters, along path to select a sampling point to use to approximate path heading. This distance should not be larger than the path handler's prune distance. - Description - Angular rotational velocity, in rad/s, to rotate to the path heading + :rotate_to_heading_angular_vel: -:primary_controller: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.8 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - string N/A - ============== ============================= + Description + Angular rotational velocity, in rad/s, to rotate to the path heading. - Description - Internal controller plugin to use for actual control behavior after rotating to heading + :primary_controller: -:max_angular_accel: + ============== ============================= + Type Default + -------------- ----------------------------- + N/A N/A + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 3.2 - ============== ============================= + Description + Namespace for internal controller plugin to use for actual control behavior after rotating to heading. - Description - Maximum angular acceleration for rotation to heading (rad/s/s) + Note + Use ``plugin:`` to specify the internal controller type and other controller parameters within this namespace. An example is given below. -:simulate_ahead_time: + :max_angular_accel: - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.0 - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + double 3.2 + ============== ============================= - Description - Time in seconds to forward simulate a rotation command to check for collisions. If a collision is found, forwards control back to the primary controller plugin. + Description + Maximum angular acceleration for rotation to heading (rad/s/s) -:rotate_to_goal_heading: + :simulate_ahead_time: - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= - Description - If true, the rotationShimController will take back control of the robot when in XY tolerance of the goal and start rotating towards the goal heading. + Description + Time in seconds to forward simulate a rotation command to check for collisions. If a collision is found, forwards control back to the primary controller plugin. -:rotate_to_heading_once: + :rotate_to_goal_heading: - ============== ============================= - Type Default - -------------- ----------------------------- - bool false - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= - Description - If true, the rotationShimController will only rotate to heading once on a new goal, not each time a path is set. + Description + If true, the rotationShimController will take back control of the robot when in XY tolerance of the goal and start rotating towards the goal heading. -:closed_loop: + :rotate_to_heading_once: - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= - Description - If false, the rotationShimController will use the last commanded velocity as the next iteration's current velocity. When acceleration limits are set appropriately and the robot's controllers are responsive, this can be a good assumption. If true, it will use odometry to estimate the robot's current speed. In this case it is important that the source is high-rate and low-latency to account for control delay. + Description + If true, the rotationShimController will only rotate to heading once on a new goal, not each time a path is set. -:use_path_orientations: + :closed_loop: - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - Description - If true, the controller will use the orientations of the path points to compute the heading of the path instead of computing the heading from the path point's relative locations. If true, the controller will use the orientations of the path points to compute the heading of the path instead of computing the heading from the path points. Use for for feasible planners like the Smac Planner which generate feasible paths with orientations for forward and reverse motion. + Description + If false, the rotationShimController will use the last commanded velocity as the next iteration's current velocity. When acceleration limits are set appropriately and the robot's controllers are responsive, this can be a good assumption. If true, it will use odometry to estimate the robot's current speed. In this case it is important that the source is high-rate and low-latency to account for control delay. + + :use_path_orientations: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + If true, the controller will use the orientations of the path points to compute the heading of the path instead of computing the heading from the path point's relative locations. If true, the controller will use the orientations of the path points to compute the heading of the path instead of computing the heading from the path points. Use for for feasible planners like the Smac Planner which generate feasible paths with orientations for forward and reverse motion. + + .. group-tab:: Kilted and older + + :angular_dist_threshold: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.785 + ============== =========================== + + Description + Maximum angular distance, in radians, away from the path heading to trigger rotation + + :angular_disengage_threshold: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.3925 + ============== =========================== + + Description + New to Jazzy, the threshold to the path's heading before disengagement (radians). Prior to Jazzy, disengagement occurs at the ``angular_dist_threshold`` instead. This allows for better alignment before passing to the child controller when engaged. + + :forward_sampling_distance: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.5 + ============== ============================= + + Description + Forward distance, in meters, along path to select a sampling point to use to approximate path heading. This distance should not be larger than the path handler's prune distance. + + :rotate_to_heading_angular_vel: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.8 + ============== ============================= + + Description + Angular rotational velocity, in rad/s, to rotate to the path heading + + :primary_controller: + + ============== ============================= + Type Default + -------------- ----------------------------- + string N/A + ============== ============================= + + Description + Internal controller plugin to use for actual control behavior after rotating to heading + + :max_angular_accel: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 3.2 + ============== ============================= + + Description + Maximum angular acceleration for rotation to heading (rad/s/s) + + :simulate_ahead_time: + + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= + + Description + Time in seconds to forward simulate a rotation command to check for collisions. If a collision is found, forwards control back to the primary controller plugin. + + :rotate_to_goal_heading: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + If true, the rotationShimController will take back control of the robot when in XY tolerance of the goal and start rotating towards the goal heading. + + :rotate_to_heading_once: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool false + ============== ============================= + + Description + If true, the rotationShimController will only rotate to heading once on a new goal, not each time a path is set. + + :closed_loop: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + If false, the rotationShimController will use the last commanded velocity as the next iteration's current velocity. When acceleration limits are set appropriately and the robot's controllers are responsive, this can be a good assumption. If true, it will use odometry to estimate the robot's current speed. In this case it is important that the source is high-rate and low-latency to account for control delay. + + :use_path_orientations: + + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== + + Description + If true, the controller will use the orientations of the path points to compute the heading of the path instead of computing the heading from the path point's relative locations. If true, the controller will use the orientations of the path points to compute the heading of the path instead of computing the heading from the path points. Use for for feasible planners like the Smac Planner which generate feasible paths with orientations for forward and reverse motion. Example ******* -.. code-block:: yaml - - controller_server: - ros__parameters: - controller_frequency: 20.0 - min_x_velocity_threshold: 0.001 - min_y_velocity_threshold: 0.5 - min_theta_velocity_threshold: 0.001 - progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older - goal_checker_plugins: ["goal_checker"] - controller_plugins: ["FollowPath"] - - progress_checker: - plugin: "nav2_controller::SimpleProgressChecker" - required_movement_radius: 0.5 - movement_time_allowance: 10.0 - goal_checker: - plugin: "nav2_controller::SimpleGoalChecker" - xy_goal_tolerance: 0.25 - yaw_goal_tolerance: 0.25 - stateful: True - FollowPath: - plugin: "nav2_rotation_shim_controller::RotationShimController" - angular_dist_threshold: 0.785 - forward_sampling_distance: 0.5 - angular_disengage_threshold: 0.3925 - rotate_to_heading_angular_vel: 1.8 - max_angular_accel: 3.2 - simulate_ahead_time: 1.0 - rotate_to_goal_heading: false - - # Primary controller params can be placed here below - primary_controller: - plugin: "nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController" - # ... + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] + goal_checker_plugins: ["goal_checker"] + controller_plugins: ["follow_path"] + + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + follow_path: + plugin: "nav2_rotation_shim_controller::RotationShimController" + angular_dist_threshold: 0.785 + forward_sampling_distance: 0.5 + angular_disengage_threshold: 0.3925 + rotate_to_heading_angular_vel: 1.8 + max_angular_accel: 3.2 + simulate_ahead_time: 1.0 + rotate_to_goal_heading: false + + # Primary controller params can be placed here below + primary_controller: + plugin: "nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController" + # ... + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + goal_checker_plugins: ["goal_checker"] + controller_plugins: ["FollowPath"] + + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True + FollowPath: + plugin: "nav2_rotation_shim_controller::RotationShimController" + primary_controller: "nav2_regulated_pure_pursuit_controller::RegulatedPurePursuitController" + angular_dist_threshold: 0.785 + forward_sampling_distance: 0.5 + angular_disengage_threshold: 0.3925 + rotate_to_heading_angular_vel: 1.8 + max_angular_accel: 3.2 + simulate_ahead_time: 1.0 + rotate_to_goal_heading: false + + # Primary controller params can be placed here below + # ... diff --git a/configuration/packages/configuring-route-server.rst b/configuration/packages/configuring-route-server.rst index e27c4b0975..c63a1a2293 100644 --- a/configuration/packages/configuring-route-server.rst +++ b/configuration/packages/configuring-route-server.rst @@ -35,303 +35,607 @@ See the package's README file for additional information such as performance met Server Parameters ***************** -:base_frame: +.. tabs:: - ============== ============== - Type Default - -------------- -------------- - string "base_link" - ============== ============== + .. group-tab:: Rolling - Description - The base frame of the robot to use to obtain the robot's pose from when not using the ``use_start`` request parameter. + :base_frame: -:route_frame: + ============== ============== + Type Default + -------------- -------------- + string "base_link" + ============== ============== - ============== ============== - Type Default - -------------- -------------- - string "map" - ============== ============== + Description + The base frame of the robot to use to obtain the robot's pose from when not using the ``use_start`` request parameter. - Description - The frame of the route graph to plan within. If values in the graph file are not w.r.t. this frame, they will be automatically transformed. + :route_frame: + ============== ============== + Type Default + -------------- -------------- + string "map" + ============== ============== -:path_density: + Description + The frame of the route graph to plan within. If values in the graph file are not w.r.t. this frame, they will be automatically transformed. - ============== ======== - Type Default - -------------- -------- - double 0.05 - ============== ======== - Description - The density of path-points in the output route, if using the ``nav_msgs/Path`` route rather than the collection of nodes and edges. This is used to upsample the route into a path that may be followed. + :path_density: -:max_iterations: + ============== ======== + Type Default + -------------- -------- + double 0.05 + ============== ======== - ============== ======== - Type Default - -------------- -------- - int 0 - ============== ======== + Description + The density of path-points in the output route, if using the ``nav_msgs/Path`` route rather than the collection of nodes and edges. This is used to upsample the route into a path that may be followed. - Description - The maximum number of planning iterations to perform. If 0, the maximum number of iterations is used. + :max_iterations: -:max_planning_time: + ============== ======== + Type Default + -------------- -------- + int 0 + ============== ======== - ============== ======== - Type Default - -------------- -------- - double 2.0 - ============== ======== + Description + The maximum number of planning iterations to perform. If 0, the maximum number of iterations is used. - Description - The maximum planning time to use. + :max_planning_time: -:smooth_corners: + ============== ======== + Type Default + -------------- -------- + double 2.0 + ============== ======== - ============== ======== - Type Default - -------------- -------- - bool false - ============== ======== + Description + The maximum planning time to use. - Description - Whether to smooth corners formed between subsequent edges after a route has been found + :smooth_corners: -:smoothing_radius: + ============== ======== + Type Default + -------------- -------- + bool false + ============== ======== - ============== ======== - Type Default - -------------- -------- - double 1.0 - ============== ======== + Description + Whether to smooth corners formed between subsequent edges after a route has been found - Description - Radius to fit to corners formed by edges if corner smoothing is enabled + :smoothing_radius: -:costmap_topic: + ============== ======== + Type Default + -------------- -------- + double 1.0 + ============== ======== - ============== ============================ - Type Default - -------------- ---------------------------- - string 'global_costmap/costmap_raw' - ============== ============================ + Description + Radius to fit to corners formed by edges if corner smoothing is enabled - Description - The costmap to use for the server-level costmap subscriber. This is created to aid the goal intent extractor (if BFS-based terminal route node finding is enabled) and also shared with the Collision Monitor Operation and Costmap Edge Scorer if set to the same topic. Otherwise, those plugins will create their own subscribers to their respective costmap topics. + :costmap_topic: -:tracker_update_rate: + ============== ============================ + Type Default + -------------- ---------------------------- + string 'global_costmap/costmap_raw' + ============== ============================ - ============== ======== - Type Default - -------------- -------- - double 50.0 - ============== ======== + Description + The costmap to use for the server-level costmap subscriber. This is created to aid the goal intent extractor (if BFS-based terminal route node finding is enabled) and also shared with the Collision Monitor Operation and Costmap Edge Scorer if set to the same topic. Otherwise, those plugins will create their own subscribers to their respective costmap topics. - Description - The update rate of the tracker (when using ``ComputeAndTrackRoute`` action) to check the status of path tracking and execute route operations. + :tracker_update_rate: -:aggregate_blocked_ids: + ============== ======== + Type Default + -------------- -------- + double 50.0 + ============== ======== - ============== ======== - Type Default - -------------- -------- - bool false - ============== ======== + Description + The update rate of the tracker (when using ``ComputeAndTrackRoute`` action) to check the status of path tracking and execute route operations. - Description - Whether to aggregate the blocked IDs reported by route operations over the lifespan of the navigation request or only use the currently marked blocked IDs. + :aggregate_blocked_ids: -:boundary_radius_to_achieve_node: + ============== ======== + Type Default + -------------- -------- + bool false + ============== ======== - ============== ======== - Type Default - -------------- -------- - double 1.0 - ============== ======== + Description + Whether to aggregate the blocked IDs reported by route operations over the lifespan of the navigation request or only use the currently marked blocked IDs. - Description - The radius at a boundary condition (start, goal) to mark the node achieved by the tracker when using ``ComputeAndTrackRoute``. Note that this is not the same as the goal tolerance, as the route or path follower (controller) will continue to run until its goal tolerance is met. + :boundary_radius_to_achieve_node: -:radius_to_achieve_node: + ============== ======== + Type Default + -------------- -------- + double 1.0 + ============== ======== - ============== ========== - Type Default - -------------- ---------- - double 1.0 - ============== ========== + Description + The radius at a boundary condition (start, goal) to mark the node achieved by the tracker when using ``ComputeAndTrackRoute``. Note that this is not the same as the goal tolerance, as the route or path follower (controller) will continue to run until its goal tolerance is met. - Description - The radius for non-boundary conditions to mark the node as achieved once within tolerance of, when using ``ComputeAndTrackRoute``. Note that this is a radius to consider achievable, however a refinement process takes place to most accurately identify when a node is reached. The radius is the trigger to start this process. Set this generously based on path tracking tolerances. + :radius_to_achieve_node: -:max_prune_dist_from_edge: + ============== ========== + Type Default + -------------- ---------- + double 1.0 + ============== ========== - ============== ========== - Type Default - -------------- ---------- - double 8.0 - ============== ========== + Description + The radius for non-boundary conditions to mark the node as achieved once within tolerance of, when using ``ComputeAndTrackRoute``. Note that this is a radius to consider achievable, however a refinement process takes place to most accurately identify when a node is reached. The radius is the trigger to start this process. Set this generously based on path tracking tolerances. - Description - Maximum distance from an edge to consider pruning it as in-progress (i.e. if we're to far away from an edge, it is nonsensical to prune it). + :max_prune_dist_from_edge: -:min_prune_dist_from_goal: + ============== ========== + Type Default + -------------- ---------- + double 8.0 + ============== ========== - ============== =============== - Type Default - -------------- --------------- - double 0.15 - ============== =============== + Description + Maximum distance from an edge to consider pruning it as in-progress (i.e. if we're to far away from an edge, it is nonsensical to prune it). - Description - Minimum distance from the goal node away from the request's goal pose (if using ``use_poses``) to consider pruning as being passed, in case the goal pose is very close to the goal node, but is not exact. + :min_prune_dist_from_goal: -:min_prune_dist_from_start: + ============== =============== + Type Default + -------------- --------------- + double 0.15 + ============== =============== - ============== =============== - Type Default - -------------- --------------- - double 0.1 - ============== =============== + Description + Minimum distance from the goal node away from the request's goal pose (if using ``use_poses``) to consider pruning as being passed, in case the goal pose is very close to the goal node, but is not exact. - Description - Minimum distance from the start node away from the start pose (if using ``use_poses``) to consider pruning as being passed, in case the start pose is very close to the start node, but is not exact. Setting this to be ~3-5x the goal tolerance may be a good choice when doing largely on-graph navigation to connect from the start node near the robot to the route fully without pruning. + :min_prune_dist_from_start: -:prune_goal: + ============== =============== + Type Default + -------------- --------------- + double 0.1 + ============== =============== - ============== =============== - Type Default - -------------- --------------- - bool true - ============== =============== + Description + Minimum distance from the start node away from the start pose (if using ``use_poses``) to consider pruning as being passed, in case the start pose is very close to the start node, but is not exact. Setting this to be ~3-5x the goal tolerance may be a good choice when doing largely on-graph navigation to connect from the start node near the robot to the route fully without pruning. - Description - Whether pruning the goal node from the route due to it being spatially past the goal pose requested (pose requests only ``use_poses``). + :prune_goal: -:enable_nn_search: + ============== =============== + Type Default + -------------- --------------- + bool true + ============== =============== - ============== =============== - Type Default - -------------- --------------- - bool true - ============== =============== + Description + Whether pruning the goal node from the route due to it being spatially past the goal pose requested (pose requests only ``use_poses``). - Description - Whether to use Breadth-first search to find the nearest traversable node (true) or simply the nearest node (false) for the start and goal when using pose requests. + :enable_nn_search: -:max_nn_search_iterations: + ============== =============== + Type Default + -------------- --------------- + bool true + ============== =============== - ============== =============== - Type Default - -------------- --------------- - int 10000 - ============== =============== + Description + Whether to use Breadth-first search to find the nearest traversable node (true) or simply the nearest node (false) for the start and goal when using pose requests. - Description - The maximum number of iterations to perform Breadth-first search to find the start and goal closest traversable nodes. + :max_nn_search_iterations: -:num_nearest_nodes: + ============== =============== + Type Default + -------------- --------------- + int 10000 + ============== =============== - ============== =============== - Type Default - -------------- --------------- - int 5 - ============== =============== + Description + The maximum number of iterations to perform Breadth-first search to find the start and goal closest traversable nodes. - Description - The number of nearest-neighbors to extract from a Kd-tree in order to check against in the Breadth-first search. + :num_nearest_nodes: -:graph_filepath: + ============== =============== + Type Default + -------------- --------------- + int 5 + ============== =============== - ============== =============== - Type Default - -------------- --------------- - string "" - ============== =============== + Description + The number of nearest-neighbors to extract from a Kd-tree in order to check against in the Breadth-first search. - Description - The filepath to the graph file for loading. It may be empty on initialization, but then the graph must be set from the server's set graph service later. + :graph_filepath: -:graph_file_loader: + ============== =============== + Type Default + -------------- --------------- + string "" + ============== =============== - ============== ======================== - Type Default - -------------- ------------------------ - string "GeoJsonGraphFileLoader" - ============== ======================== + Description + The filepath to the graph file for loading. It may be empty on initialization, but then the graph must be set from the server's set graph service later. - Description - The name of the graph file loader plugin to use. + :graph_file_loader: -:graph_file_loader.plugin: + ============== ======================== + Type Default + -------------- ------------------------ + string "geo_json_graph_file_loader" + ============== ======================== - ============== ==================================== - Type Default - -------------- ------------------------------------ - string "nav2_route::GeoJsonGraphFileLoader" - ============== ==================================== + Description + The name of the graph file loader plugin to use. - Description - The graph loading plugin to use. By default, we use ``geojson``. + :graph_file_loader.plugin: -:edge_cost_functions: + ============== ==================================== + Type Default + -------------- ------------------------------------ + string "nav2_route::GeoJsonGraphFileLoader" + ============== ==================================== - ============== ======================================== - Type Default - -------------- ---------------------------------------- - vector ["DistanceScorer", "DynamicEdgesScorer"] - ============== ======================================== + Description + The graph loading plugin to use. By default, we use ``geojson``. - Description - Which edge cost functions should be used for planning purposes to score the edges. By default, we optimize for minimum distance while providing a service cost function to set arbitrary costs or mark edge as closed from a service. + :edge_cost_functions: -:operations: + ============== ======================================== + Type Default + -------------- ---------------------------------------- + vector ["distance_scorer", "dynamic_edges_scorer"] + ============== ======================================== - ============== ======================================== - Type Default - -------------- ---------------------------------------- - vector ["AdjustSpeedLimit", "ReroutingService"] - ============== ======================================== + Description + Which edge cost functions should be used for planning purposes to score the edges. By default, we optimize for minimum distance while providing a service cost function to set arbitrary costs or mark edge as closed from a service. - Description - The route operation plugins to use for ``ComputeAndTrackRoute``. By default, we have a speed limit adjuster and a ROS service request rerouting operation. + :operations: -:.plugin: + ============== ======================================== + Type Default + -------------- ---------------------------------------- + vector ["adjust_speed_limit", "rerouting_service"] + ============== ======================================== - ============== ============ - Type Default - -------------- ------------ - string "" - ============== ============ + Description + The route operation plugins to use for ``ComputeAndTrackRoute``. By default, we have a speed limit adjuster and a ROS service request rerouting operation. - Description - The plugin to load under that name. The ``edge_cost_functions.`` namespaces is also where plugin-specific parameters are defined. + :.plugin: -:introspection_mode: + ============== ============ + Type Default + -------------- ------------ + string "" + ============== ============ - ============== ============================= - Type Default - -------------- ----------------------------- - string "disabled" - ============== ============================= + Description + The plugin to load under that name. The ``edge_cost_functions.`` namespaces is also where plugin-specific parameters are defined. - Description - The introspection mode for services and actions. Options are "disabled", "metadata", "contents". + :introspection_mode: -:allow_parameter_qos_overrides: + ============== ============================= + Type Default + -------------- ----------------------------- + string "disabled" + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description + The introspection mode for services and actions. Options are "disabled", "metadata", "contents". - Description - Whether to allow QoS profiles to be overwritten with parameterized values. + :allow_parameter_qos_overrides: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to allow QoS profiles to be overwritten with parameterized values. + + .. group-tab:: Kilted and older + + :base_frame: + + ============== ============== + Type Default + -------------- -------------- + string "base_link" + ============== ============== + + Description + The base frame of the robot to use to obtain the robot's pose from when not using the ``use_start`` request parameter. + + :route_frame: + + ============== ============== + Type Default + -------------- -------------- + string "map" + ============== ============== + + Description + The frame of the route graph to plan within. If values in the graph file are not w.r.t. this frame, they will be automatically transformed. + + + :path_density: + + ============== ======== + Type Default + -------------- -------- + double 0.05 + ============== ======== + + Description + The density of path-points in the output route, if using the ``nav_msgs/Path`` route rather than the collection of nodes and edges. This is used to upsample the route into a path that may be followed. + + :max_iterations: + + ============== ======== + Type Default + -------------- -------- + int 0 + ============== ======== + + Description + The maximum number of planning iterations to perform. If 0, the maximum number of iterations is used. + + :max_planning_time: + + ============== ======== + Type Default + -------------- -------- + double 2.0 + ============== ======== + + Description + The maximum planning time to use. + + :smooth_corners: + + ============== ======== + Type Default + -------------- -------- + bool false + ============== ======== + + Description + Whether to smooth corners formed between subsequent edges after a route has been found + + :smoothing_radius: + + ============== ======== + Type Default + -------------- -------- + double 1.0 + ============== ======== + + Description + Radius to fit to corners formed by edges if corner smoothing is enabled + + :costmap_topic: + + ============== ============================ + Type Default + -------------- ---------------------------- + string 'global_costmap/costmap_raw' + ============== ============================ + + Description + The costmap to use for the server-level costmap subscriber. This is created to aid the goal intent extractor (if BFS-based terminal route node finding is enabled) and also shared with the Collision Monitor Operation and Costmap Edge Scorer if set to the same topic. Otherwise, those plugins will create their own subscribers to their respective costmap topics. + + :tracker_update_rate: + + ============== ======== + Type Default + -------------- -------- + double 50.0 + ============== ======== + + Description + The update rate of the tracker (when using ``ComputeAndTrackRoute`` action) to check the status of path tracking and execute route operations. + + :aggregate_blocked_ids: + + ============== ======== + Type Default + -------------- -------- + bool false + ============== ======== + + Description + Whether to aggregate the blocked IDs reported by route operations over the lifespan of the navigation request or only use the currently marked blocked IDs. + + :boundary_radius_to_achieve_node: + + ============== ======== + Type Default + -------------- -------- + double 1.0 + ============== ======== + + Description + The radius at a boundary condition (start, goal) to mark the node achieved by the tracker when using ``ComputeAndTrackRoute``. Note that this is not the same as the goal tolerance, as the route or path follower (controller) will continue to run until its goal tolerance is met. + + :radius_to_achieve_node: + + ============== ========== + Type Default + -------------- ---------- + double 1.0 + ============== ========== + + Description + The radius for non-boundary conditions to mark the node as achieved once within tolerance of, when using ``ComputeAndTrackRoute``. Note that this is a radius to consider achievable, however a refinement process takes place to most accurately identify when a node is reached. The radius is the trigger to start this process. Set this generously based on path tracking tolerances. + + :max_prune_dist_from_edge: + + ============== ========== + Type Default + -------------- ---------- + double 8.0 + ============== ========== + + Description + Maximum distance from an edge to consider pruning it as in-progress (i.e. if we're to far away from an edge, it is nonsensical to prune it). + + :min_prune_dist_from_goal: + + ============== =============== + Type Default + -------------- --------------- + double 0.15 + ============== =============== + + Description + Minimum distance from the goal node away from the request's goal pose (if using ``use_poses``) to consider pruning as being passed, in case the goal pose is very close to the goal node, but is not exact. + + :min_prune_dist_from_start: + + ============== =============== + Type Default + -------------- --------------- + double 0.1 + ============== =============== + + Description + Minimum distance from the start node away from the start pose (if using ``use_poses``) to consider pruning as being passed, in case the start pose is very close to the start node, but is not exact. Setting this to be ~3-5x the goal tolerance may be a good choice when doing largely on-graph navigation to connect from the start node near the robot to the route fully without pruning. + + :prune_goal: + + ============== =============== + Type Default + -------------- --------------- + bool true + ============== =============== + + Description + Whether pruning the goal node from the route due to it being spatially past the goal pose requested (pose requests only ``use_poses``). + + :enable_nn_search: + + ============== =============== + Type Default + -------------- --------------- + bool true + ============== =============== + + Description + Whether to use Breadth-first search to find the nearest traversable node (true) or simply the nearest node (false) for the start and goal when using pose requests. + + :max_nn_search_iterations: + + ============== =============== + Type Default + -------------- --------------- + int 10000 + ============== =============== + + Description + The maximum number of iterations to perform Breadth-first search to find the start and goal closest traversable nodes. + + :num_nearest_nodes: + + ============== =============== + Type Default + -------------- --------------- + int 5 + ============== =============== + + Description + The number of nearest-neighbors to extract from a Kd-tree in order to check against in the Breadth-first search. + + :graph_filepath: + + ============== =============== + Type Default + -------------- --------------- + string "" + ============== =============== + + Description + The filepath to the graph file for loading. It may be empty on initialization, but then the graph must be set from the server's set graph service later. + + :graph_file_loader: + + ============== ======================== + Type Default + -------------- ------------------------ + string "GeoJsonGraphFileLoader" + ============== ======================== + + Description + The name of the graph file loader plugin to use. + + :graph_file_loader.plugin: + + ============== ==================================== + Type Default + -------------- ------------------------------------ + string "nav2_route::GeoJsonGraphFileLoader" + ============== ==================================== + + Description + The graph loading plugin to use. By default, we use ``geojson``. + + :edge_cost_functions: + + ============== ======================================== + Type Default + -------------- ---------------------------------------- + vector ["DistanceScorer", "DynamicEdgesScorer"] + ============== ======================================== + + Description + Which edge cost functions should be used for planning purposes to score the edges. By default, we optimize for minimum distance while providing a service cost function to set arbitrary costs or mark edge as closed from a service. + + :operations: + + ============== ======================================== + Type Default + -------------- ---------------------------------------- + vector ["AdjustSpeedLimit", "ReroutingService"] + ============== ======================================== + + Description + The route operation plugins to use for ``ComputeAndTrackRoute``. By default, we have a speed limit adjuster and a ROS service request rerouting operation. + + :.plugin: + + ============== ============ + Type Default + -------------- ------------ + string "" + ============== ============ + + Description + The plugin to load under that name. The ``edge_cost_functions.`` namespaces is also where plugin-specific parameters are defined. + + :introspection_mode: + + ============== ============================= + Type Default + -------------- ----------------------------- + string "disabled" + ============== ============================= + + Description + The introspection mode for services and actions. Options are "disabled", "metadata", "contents". + + :allow_parameter_qos_overrides: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description + Whether to allow QoS profiles to be overwritten with parameterized values. Edge Scorer Parameters ********************** @@ -802,45 +1106,90 @@ It uses a `std_srvs/Trigger` interface and is a demonstration of the `RouteOpera Example ******* -.. code-block:: yaml - - route_server: - ros__parameters: - - base_frame: "base_link" # Robot's base frame - route_frame: "map" # Global reference frame - path_density: 0.05 # Density of points for generating the dense nav_msgs/Path from route (m) - max_iterations: 0 # Maximum number of search iterations, if 0, uses maximum possible - max_planning_time: 2.0 # Maximum planning time (seconds) - smoothing_corners: true # Whether to smooth corners formed by adjacent edges or not - smoothing_radius: 1.0 # Radius of corner to fit into the corner - - graph_file_loader: "GeoJsonGraphFileLoader" # Name of default file loader - plugin: nav2_route::GeoJsonGraphFileLoader # file loader plugin to use - graph_filepath: "" # file path to graph to use - - edge_cost_functions: ["DistanceScorer", "DynamicEdgesScorer"] # Edge scoring cost functions to use - DistanceScorer: - plugin: "nav2_route::DistanceScorer" - DynamicEdgesScorer: - plugin: "nav2_route::DynamicEdgesScorer" - - operations: ["AdjustSpeedLimit", "ReroutingService"] # Route operations plugins to use - AdjustSpeedLimit: - plugin: "nav2_route::AdjustSpeedLimit" - ReroutingService: - plugin: "nav2_route::ReroutingService" - - tracker_update_rate: 50.0 # Rate at which to check the status of path tracking - aggregate_blocked_ids: false # Whether to aggregate the blocked IDs reported by route operations over the lifespan of the navigation request or only use the currently blocked IDs. - boundary_radius_to_achieve_node: 1.0 # Radius (m) near boundary nodes (e.g. start/end) to enable evaluation of achievement metric - radius_to_achieve_node: 2.0 # Radius (m) near route nodes as preliminary condition for evaluation of achievement metric - - max_prune_dist_from_edge: 8.0 # Max distance from an edge to consider pruning it as in-progress (e.g. if we're too far away from the edge, its nonsensical to prune it) - min_prune_dist_from_goal: 0.15 # Min distance from goal node away from goal pose to consider goal node pruning as considering it as being passed (in case goal pose is very close to a goal node, but not exact) - min_prune_dist_from_start: 0.10 # Min distance from start node away from start pose to consider start node pruning as considering it as being passed (in case start pose is very close to a start node, but not exact) - prune_goal: true # Whether pruning the goal nodes from the route due to being past the goal pose requested is possible (pose requests only) +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + route_server: + ros__parameters: + + base_frame: "base_link" # Robot's base frame + route_frame: "map" # Global reference frame + path_density: 0.05 # Density of points for generating the dense nav_msgs/Path from route (m) + max_iterations: 0 # Maximum number of search iterations, if 0, uses maximum possible + max_planning_time: 2.0 # Maximum planning time (seconds) + smoothing_corners: true # Whether to smooth corners formed by adjacent edges or not + smoothing_radius: 1.0 # Radius of corner to fit into the corner + + graph_file_loader: "geo_json_graph_file_loader" # Name of default file loader + plugin: nav2_route::GeoJsonGraphFileLoader # file loader plugin to use + graph_filepath: "" # file path to graph to use + + edge_cost_functions: ["distance_scorer", "dynamic_edges_scorer"] # Edge scoring cost functions to use + distance_scorer: + plugin: "nav2_route::DistanceScorer" + dynamic_edges_scorer: + plugin: "nav2_route::DynamicEdgesScorer" + + operations: ["adjust_speed_limit", "rerouting_service"] # Route operations plugins to use + adjust_speed_limit: + plugin: "nav2_route::AdjustSpeedLimit" + rerouting_service: + plugin: "nav2_route::ReroutingService" + + tracker_update_rate: 50.0 # Rate at which to check the status of path tracking + aggregate_blocked_ids: false # Whether to aggregate the blocked IDs reported by route operations over the lifespan of the navigation request or only use the currently blocked IDs. + boundary_radius_to_achieve_node: 1.0 # Radius (m) near boundary nodes (e.g. start/end) to enable evaluation of achievement metric + radius_to_achieve_node: 2.0 # Radius (m) near route nodes as preliminary condition for evaluation of achievement metric + + max_prune_dist_from_edge: 8.0 # Max distance from an edge to consider pruning it as in-progress (e.g. if we're too far away from the edge, its nonsensical to prune it) + min_prune_dist_from_goal: 0.15 # Min distance from goal node away from goal pose to consider goal node pruning as considering it as being passed (in case goal pose is very close to a goal node, but not exact) + min_prune_dist_from_start: 0.10 # Min distance from start node away from start pose to consider start node pruning as considering it as being passed (in case start pose is very close to a start node, but not exact) + prune_goal: true # Whether pruning the goal nodes from the route due to being past the goal pose requested is possible (pose requests only) + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + route_server: + ros__parameters: + + base_frame: "base_link" # Robot's base frame + route_frame: "map" # Global reference frame + path_density: 0.05 # Density of points for generating the dense nav_msgs/Path from route (m) + max_iterations: 0 # Maximum number of search iterations, if 0, uses maximum possible + max_planning_time: 2.0 # Maximum planning time (seconds) + smoothing_corners: true # Whether to smooth corners formed by adjacent edges or not + smoothing_radius: 1.0 # Radius of corner to fit into the corner + + graph_file_loader: "GeoJsonGraphFileLoader" # Name of default file loader + plugin: nav2_route::GeoJsonGraphFileLoader # file loader plugin to use + graph_filepath: "" # file path to graph to use + + edge_cost_functions: ["DistanceScorer", "DynamicEdgesScorer"] # Edge scoring cost functions to use + DistanceScorer: + plugin: "nav2_route::DistanceScorer" + DynamicEdgesScorer: + plugin: "nav2_route::DynamicEdgesScorer" + + operations: ["AdjustSpeedLimit", "ReroutingService"] # Route operations plugins to use + AdjustSpeedLimit: + plugin: "nav2_route::AdjustSpeedLimit" + ReroutingService: + plugin: "nav2_route::ReroutingService" + + tracker_update_rate: 50.0 # Rate at which to check the status of path tracking + aggregate_blocked_ids: false # Whether to aggregate the blocked IDs reported by route operations over the lifespan of the navigation request or only use the currently blocked IDs. + boundary_radius_to_achieve_node: 1.0 # Radius (m) near boundary nodes (e.g. start/end) to enable evaluation of achievement metric + radius_to_achieve_node: 2.0 # Radius (m) near route nodes as preliminary condition for evaluation of achievement metric + + max_prune_dist_from_edge: 8.0 # Max distance from an edge to consider pruning it as in-progress (e.g. if we're too far away from the edge, its nonsensical to prune it) + min_prune_dist_from_goal: 0.15 # Min distance from goal node away from goal pose to consider goal node pruning as considering it as being passed (in case goal pose is very close to a goal node, but not exact) + min_prune_dist_from_start: 0.10 # Min distance from start node away from start pose to consider start node pruning as considering it as being passed (in case start pose is very close to a start node, but not exact) + prune_goal: true # Whether pruning the goal nodes from the route due to being past the goal pose requested is possible (pose requests only) Configuring the Nav2 Route Server Demo ************************************** diff --git a/configuration/packages/configuring-thetastar.rst b/configuration/packages/configuring-thetastar.rst index 355e72f6b7..12316bdd77 100644 --- a/configuration/packages/configuring-thetastar.rst +++ b/configuration/packages/configuring-thetastar.rst @@ -110,14 +110,32 @@ The parameters of the planner are: Example ******* -.. code-block:: yaml - - planner_server: - ros__parameters: - expected_planner_frequency: 20.0 - planner_plugins: ["GridBased"] - GridBased: - plugin: "nav2_theta_star_planner::ThetaStarPlanner" # In Iron and older versions, "/" was used instead of "::" - how_many_corners: 8 - w_euc_cost: 1.0 - w_traversal_cost: 2.0 +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + planner_server: + ros__parameters: + expected_planner_frequency: 20.0 + planner_plugins: ["grid_based"] + grid_based: + plugin: "nav2_theta_star_planner::ThetaStarPlanner" + how_many_corners: 8 + w_euc_cost: 1.0 + w_traversal_cost: 2.0 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + planner_server: + ros__parameters: + expected_planner_frequency: 20.0 + planner_plugins: ["GridBased"] + GridBased: + plugin: "nav2_theta_star_planner::ThetaStarPlanner" # In Iron and older versions, "/" was used instead of "::" + how_many_corners: 8 + w_euc_cost: 1.0 + w_traversal_cost: 2.0 diff --git a/configuration/packages/map_server/configuring-vector-object-server.rst b/configuration/packages/map_server/configuring-vector-object-server.rst index 449aae5997..ae29aa7252 100644 --- a/configuration/packages/map_server/configuring-vector-object-server.rst +++ b/configuration/packages/map_server/configuring-vector-object-server.rst @@ -74,247 +74,267 @@ Using Vector Object server publishing an output map as input mask to :ref:`Costm Parameters ========== -:map_topic: +.. tabs:: - ============== ============================= - Type Default - -------------- ----------------------------- - string "vo_map" - ============== ============================= + .. group-tab:: Rolling - Description: - Output topic, publishing an OccupancyGrid map with vector objects put on it. + :map_topic: -:global_frame_id: + ============== ============================= + Type Default + -------------- ----------------------------- + string "vo_map" + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - string "map" - ============== ============================= + Description: + Output topic, publishing an OccupancyGrid map with vector objects put on it. - Description: - The name of the coordinate frame where the map is being published at. + :global_frame_id: -:resolution: + ============== ============================= + Type Default + -------------- ----------------------------- + string "map" + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.05 - ============== ============================= + Description: + The name of the coordinate frame where the map is being published at. - Description: - Output map resolution in meters. + :resolution: -:default_value: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.05 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - int -1 (unknown) - ============== ============================= + Description: + Output map resolution in meters. - Description: - Default OccupancyGrid value to fill the background of output map with. + :default_value: -:overlay_type: + ============== ============================= + Type Default + -------------- ----------------------------- + int -1 (unknown) + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - int 0 - ============== ============================= + Description: + Default OccupancyGrid value to fill the background of output map with. - Description: - How one vector object to be overlaid with other and the map. - The following values are supported: + :overlay_type: - - 0 (``OVERLAY_SEQ``): Vector objects are superimposed in the order in which they have arrived. - - 1 (``OVERLAY_MAX``): Maximum value from vector objects and map is being chosen. - - 2 (``OVERLAY_MIN``): Minimum value from vector objects and map is being chosen. Unknown OccupancyGrid value is always being overrode, when it is possible. + ============== ============================= + Type Default + -------------- ----------------------------- + int 0 + ============== ============================= -:update_frequency: + Description: + How one vector object to be overlaid with other and the map. + The following values are supported: - ============== ============================= - Type Default - -------------- ----------------------------- - double 1.0 - ============== ============================= + - 0 (``OVERLAY_SEQ``): Vector objects are superimposed in the order in which they have arrived. + - 1 (``OVERLAY_MAX``): Maximum value from vector objects and map is being chosen. + - 2 (``OVERLAY_MIN``): Minimum value from vector objects and map is being chosen. Unknown OccupancyGrid value is always being overrode, when it is possible. - Description: - Output map update frequency (when dynamic update model is switched-on). + :update_frequency: -:transform_tolerance: + ============== ============================= + Type Default + -------------- ----------------------------- + double 1.0 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - double 0.1 - ============== ============================= + Description: + Output map update frequency (when dynamic update model is switched-on). - Description: - Transform tolerance for the case when any of the shapes are placed in different than map's frame. + :transform_tolerance: -:shapes: + ============== ============================= + Type Default + -------------- ----------------------------- + double 0.1 + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - vector {} - ============== ============================= + Description: + Transform tolerance for the case when any of the shapes are placed in different than map's frame. - Description: - List of vector objects (polygons and circles). Empty by-default. + :shapes: + + ============== ============================= + Type Default + -------------- ----------------------------- + vector {} + ============== ============================= + + Description: + List of vector objects (polygons and circles). Empty by-default. Shapes parameters ----------------- -```` - is the corresponding shape name string selected for this vector object. +.. tabs:: + + .. group-tab:: Rolling + + ```` - is the corresponding shape name string selected for this vector object. -:````.type: + :````.type: - ============== ============================= - Type Default - -------------- ----------------------------- - string N/A - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + string N/A + ============== ============================= - Description: - Type of vector object shape. Available values are ``polygon`` and ``circle``. Causes an error, if not specialized. + Description: + Type of vector object shape. Available values are ``polygon`` and ``circle``. Causes an error, if not specialized. -:````.uuid: + :````.uuid: - ============== ============================= - Type Default - -------------- ----------------------------- - string N/A - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + string N/A + ============== ============================= - Description: - UUID of the shape specified in ``12345678-9abc-def0-1234-56789abcdef0`` format. Parameter is optional and could be skipped: if not specialized, Vector Object server will automatically generate a new one for the shape. + Description: + UUID of the shape specified in ``12345678-9abc-def0-1234-56789abcdef0`` format. Parameter is optional and could be skipped: if not specialized, Vector Object server will automatically generate a new one for the shape. -:````.frame_id: + :````.frame_id: - ============== ============================= - Type Default - -------------- ----------------------------- - string "" - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + string "" + ============== ============================= - Description: - Frame ID of the given shape. Empty value is being treated as map's global frame. + Description: + Frame ID of the given shape. Empty value is being treated as map's global frame. -:````.value: + :````.value: - ============== ============================= - Type Default - -------------- ----------------------------- - int 100 (occupied) - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + int 100 (occupied) + ============== ============================= - Description: - Shape's value to be put on map with. + Description: + Shape's value to be put on map with. Parameters applicable for polygons only ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:````.points: +.. tabs:: - ============== ============================= - Type Default - -------------- ----------------------------- - vector N/A - ============== ============================= + .. group-tab:: Rolling - Description: - Polygon vertices, listed in ``[p1.x, p1.y, p2.x, p2.y, p3.x, p3.y, ...]`` format (e.g. ``[0.5, 0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5]`` for the square). Minimum 3 points for a triangle polygon. Causes an error, if not specialized incorrectly (less than 6 or odd number of items in the vector) or not specialized. + :````.points: -:````.closed: + ============== ============================= + Type Default + -------------- ----------------------------- + vector N/A + ============== ============================= - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + Description: + Polygon vertices, listed in ``[p1.x, p1.y, p2.x, p2.y, p3.x, p3.y, ...]`` format (e.g. ``[0.5, 0.5, 0.5, -0.5, -0.5, -0.5, -0.5, 0.5]`` for the square). Minimum 3 points for a triangle polygon. Causes an error, if not specialized incorrectly (less than 6 or odd number of items in the vector) or not specialized. - Description: - Whether the polygon is closed (and filled), or drawn as polygonal chain otherwise. + :````.closed: + + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= + + Description: + Whether the polygon is closed (and filled), or drawn as polygonal chain otherwise. Parameters applicable for circles only ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:````.center: +.. tabs:: + + .. group-tab:: Rolling + + :````.center: - ============== ============================= - Type Default - -------------- ----------------------------- - vector N/A - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + vector N/A + ============== ============================= - Description: - Center of the circle, listed in ``{center.x, center.y}`` format (e.g. ``{0.2, 0.3}``). Should contain exactly 2 items: X and Y coordinate of the circle's center in a given frame. Otherwise, causes an error. + Description: + Center of the circle, listed in ``{center.x, center.y}`` format (e.g. ``{0.2, 0.3}``). Should contain exactly 2 items: X and Y coordinate of the circle's center in a given frame. Otherwise, causes an error. -:````.radius: + :````.radius: - ============== ============================= - Type Default - -------------- ----------------------------- - double N/A - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + double N/A + ============== ============================= - Description: - Circle radius. Causes an error, if less than zero or not specialized. + Description: + Circle radius. Causes an error, if less than zero or not specialized. -:````.fill: + :````.fill: - ============== ============================= - Type Default - -------------- ----------------------------- - bool true - ============== ============================= + ============== ============================= + Type Default + -------------- ----------------------------- + bool true + ============== ============================= - Description: - Whether the circle to be filled with a given value, or drawn only circle's border otherwise. + Description: + Whether the circle to be filled with a given value, or drawn only circle's border otherwise. Example ======= Here is an example of configuration YAML for the Vector Object server: -.. code-block:: yaml - - vector_object_server: - ros__parameters: - map_topic: "vo_map" - global_frame_id: "map" - resolution: 0.05 - default_value: -1 - overlay_type: 0 - update_frequency: 1.0 - transform_tolerance: 0.1 - shapes: ["Poly", "CircleA", "CircleB"] - Poly: - type: "polygon" - frame_id: "map" - closed: True - value: 100 - points: [0.3, 0.3, 0.3, -0.3, 0.0, -0.3, 0.0, 0.3] - CircleA: - type: "circle" - frame_id: "map" - fill: True - value: 10 - center: [3.0, 3.0] - radius: 0.5 - uuid: "7b3f3d7d-135c-4b6c-aca1-7a84d1050505" - CircleB: - type: "circle" - frame_id: "map" - fill: False - value: 90 - center: [3.5, 3.5] - radius: 1.5 +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + vector_object_server: + ros__parameters: + map_topic: "vo_map" + global_frame_id: "map" + resolution: 0.05 + default_value: -1 + overlay_type: 0 + update_frequency: 1.0 + transform_tolerance: 0.1 + shapes: ["poly", "circle_a", "circle_b"] + poly: + type: "polygon" + frame_id: "map" + closed: True + value: 100 + points: [0.3, 0.3, 0.3, -0.3, 0.0, -0.3, 0.0, 0.3] + circle_a: + type: "circle" + frame_id: "map" + fill: True + value: 10 + center: [3.0, 3.0] + radius: 0.5 + uuid: "7b3f3d7d-135c-4b6c-aca1-7a84d1050505" + circle_b: + type: "circle" + frame_id: "map" + fill: False + value: 90 + center: [3.5, 3.5] + radius: 1.5 For this, Vector Object server will produce the following map: diff --git a/configuration/packages/nav2_controller-plugins/feasible_path_handler.rst b/configuration/packages/nav2_controller-plugins/feasible_path_handler.rst index 30d2b8ee1e..db6d5a926a 100644 --- a/configuration/packages/nav2_controller-plugins/feasible_path_handler.rst +++ b/configuration/packages/nav2_controller-plugins/feasible_path_handler.rst @@ -9,107 +9,116 @@ within the costmap bounds, and handles in-place rotation and cusp pruning. Parameters ********** -````: nav2_controller plugin name defined in the **path_handler_plugin_id** parameter in :ref:`configuring_controller_server`. +.. tabs:: -:````.reject_unit_path: + .. group-tab:: Rolling - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + ````: nav2_controller plugin name defined in the **path_handler_plugin_id** parameter in :ref:`configuring_controller_server`. - Description - If enabled, the path handler will reject a path that contains only a single pose. + :````.reject_unit_path: -:````.prune_distance: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 2.0 - ============== =========================== + Description + If enabled, the path handler will reject a path that contains only a single pose. - Description - Distance ahead of nearest point on path to robot to prune path to (m). This distance should be at least as great as the furthest distance of interest by a critic (i.e. for maximum velocity projection forward, threshold to consider). + :````.prune_distance: -:````.max_robot_pose_search_dist: + ============== =========================== + Type Default + -------------- --------------------------- + double 2.0 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double Costmap size / 2 - ============== =========================== + Description + Distance ahead of nearest point on path to robot to prune path to (m). This distance should be at least as great as the furthest distance of interest by a critic (i.e. for maximum velocity projection forward, threshold to consider). - Description - Max integrated distance ahead of robot pose to search for nearest path point in case of path looping. + :````.max_robot_pose_search_dist: -:````.enforce_path_inversion: + ============== =========================== + Type Default + -------------- --------------------------- + double Costmap size / 2 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + Description + Max integrated distance ahead of robot pose to search for nearest path point in case of path looping. - Description - If true, it will prune paths containing cusping points for segments changing directions (e.g. path inversions) such that the controller will be forced to change directions at or very near the planner's requested inversion point. In addition, these cusping points will also be treated by the critics as local goals that the robot will attempt to reach. This is targeting Smac Planner users with feasible paths who need their robots to switch directions where specifically requested. + :````.enforce_path_inversion: -:````.enforce_path_rotation: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - bool false - ============== =========================== + Description + If true, it will prune paths containing cusping points for segments changing directions (e.g. path inversions) such that the controller will be forced to change directions at or very near the planner's requested inversion point. In addition, these cusping points will also be treated by the critics as local goals that the robot will attempt to reach. This is targeting Smac Planner users with feasible paths who need their robots to switch directions where specifically requested. - Description - If true, the controller will detect in-place rotation segments (where translation is near zero) and prune the remaining poses after the rotation point. This forces the robot to explicitly perform the rotation before proceeding along the rest of the path. - This is particularly useful for feasible planners (e.g., Smac Planner) where direction changes are intentionally introduced and must be respected during execution. + :````.enforce_path_rotation: -:````.minimum_rotation_angle: + ============== =========================== + Type Default + -------------- --------------------------- + bool false + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.785 - ============== =========================== + Description + If true, the controller will detect in-place rotation segments (where translation is near zero) and prune the remaining poses after the rotation point. This forces the robot to explicitly perform the rotation before proceeding along the rest of the path. + This is particularly useful for feasible planners (e.g., Smac Planner) where direction changes are intentionally introduced and must be respected during execution. - Description - The minimum accumulated rotation (in radians) required to classify a segment as an in-place rotation. 0.785 rad = 45 deg. + :````.minimum_rotation_angle: -:````.inversion_xy_tolerance: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.785 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.2 - ============== =========================== + Description + The minimum accumulated rotation (in radians) required to classify a segment as an in-place rotation. 0.785 rad = 45 deg. - Description - Cartesian proximity (m) to path inversion point to be considered "achieved" to pass on the rest of the path after path inversion. + :````.inversion_xy_tolerance: -:````.inversion_yaw_tolerance: + ============== =========================== + Type Default + -------------- --------------------------- + double 0.2 + ============== =========================== - ============== =========================== - Type Default - -------------- --------------------------- - double 0.4 - ============== =========================== + Description + Cartesian proximity (m) to path inversion point to be considered "achieved" to pass on the rest of the path after path inversion. - Description - Angular proximity (radians) to path inversion point to be considered "achieved" to pass on the rest of the path after path inversion. 0.4 rad = 23 deg. + :````.inversion_yaw_tolerance: + + ============== =========================== + Type Default + -------------- --------------------------- + double 0.4 + ============== =========================== + + Description + Angular proximity (radians) to path inversion point to be considered "achieved" to pass on the rest of the path after path inversion. 0.4 rad = 23 deg. Example ******* -.. code-block:: yaml - - PathHandler: - plugin: "nav2_controller::FeasiblePathHandler" - prune_distance: 2.0 - enforce_path_inversion: True - enforce_path_rotation: False - inversion_xy_tolerance: 0.2 - inversion_yaw_tolerance: 0.4 - minimum_rotation_angle: 0.785 - reject_unit_path: False + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + path_handler: + plugin: "nav2_controller::FeasiblePathHandler" + prune_distance: 2.0 + enforce_path_inversion: True + enforce_path_rotation: False + inversion_xy_tolerance: 0.2 + inversion_yaw_tolerance: 0.4 + minimum_rotation_angle: 0.785 + reject_unit_path: False diff --git a/configuration/packages/smac/configuring-smac-2d.rst b/configuration/packages/smac/configuring-smac-2d.rst index dea02ec9df..811268b3b6 100644 --- a/configuration/packages/smac/configuring-smac-2d.rst +++ b/configuration/packages/smac/configuring-smac-2d.rst @@ -204,25 +204,55 @@ Parameters Example ******* -.. code-block:: yaml - - planner_server: - ros__parameters: - planner_plugins: ["GridBased"] - - GridBased: - plugin: "nav2_smac_planner::SmacPlanner2D" # In Iron and older versions, "/" was used instead of "::" - tolerance: 0.125 # tolerance for planning if unable to reach exact pose, in meters - downsample_costmap: false # whether or not to downsample the map - downsampling_factor: 1 # multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm) - allow_unknown: true # allow traveling in unknown space - max_iterations: 1000000 # maximum total iterations to search for before failing (in case unreachable), set to -1 to disable - max_on_approach_iterations: 1000 # maximum number of iterations to attempt to reach goal once in tolerance - max_planning_time: 2.0 # max time in s for planner to plan, smooth - cost_travel_multiplier: 2.0 # Cost multiplier to apply to search to steer away from high cost areas. Larger values will place in the center of aisles more exactly (if non-`FREE` cost potential field exists) but take slightly longer to compute. To optimize for speed, a value of 1.0 is reasonable. A reasonable tradeoff value is 2.0. A value of 0.0 effective disables steering away from obstacles and acts like a naive binary search A*. - use_final_approach_orientation: false # Whether to set the final path pose at the goal's orientation to the requested orientation (false) or in line with the approach angle so the robot doesn't rotate to heading (true) - smoother: - max_iterations: 1000 - w_smooth: 0.3 - w_data: 0.2 - tolerance: 1.0e-10 + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ["grid_based"] + + grid_based: + plugin: "nav2_smac_planner::SmacPlanner2D" + tolerance: 0.125 # tolerance for planning if unable to reach exact pose, in meters + downsample_costmap: false # whether or not to downsample the map + downsampling_factor: 1 # multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm) + allow_unknown: true # allow traveling in unknown space + max_iterations: 1000000 # maximum total iterations to search for before failing (in case unreachable), set to -1 to disable + max_on_approach_iterations: 1000 # maximum number of iterations to attempt to reach goal once in tolerance + max_planning_time: 2.0 # max time in s for planner to plan, smooth + cost_travel_multiplier: 2.0 # Cost multiplier to apply to search to steer away from high cost areas. Larger values will place in the center of aisles more exactly (if non-`FREE` cost potential field exists) but take slightly longer to compute. To optimize for speed, a value of 1.0 is reasonable. A reasonable tradeoff value is 2.0. A value of 0.0 effective disables steering away from obstacles and acts like a naive binary search A*. + use_final_approach_orientation: false # Whether to set the final path pose at the goal's orientation to the requested orientation (false) or in line with the approach angle so the robot doesn't rotate to heading (true) + smoother: + max_iterations: 1000 + w_smooth: 0.3 + w_data: 0.2 + tolerance: 1.0e-10 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ["GridBased"] + + GridBased: + plugin: "nav2_smac_planner::SmacPlanner2D" # In Iron and older versions, "/" was used instead of "::" + tolerance: 0.125 # tolerance for planning if unable to reach exact pose, in meters + downsample_costmap: false # whether or not to downsample the map + downsampling_factor: 1 # multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm) + allow_unknown: true # allow traveling in unknown space + max_iterations: 1000000 # maximum total iterations to search for before failing (in case unreachable), set to -1 to disable + max_on_approach_iterations: 1000 # maximum number of iterations to attempt to reach goal once in tolerance + max_planning_time: 2.0 # max time in s for planner to plan, smooth + cost_travel_multiplier: 2.0 # Cost multiplier to apply to search to steer away from high cost areas. Larger values will place in the center of aisles more exactly (if non-`FREE` cost potential field exists) but take slightly longer to compute. To optimize for speed, a value of 1.0 is reasonable. A reasonable tradeoff value is 2.0. A value of 0.0 effective disables steering away from obstacles and acts like a naive binary search A*. + use_final_approach_orientation: false # Whether to set the final path pose at the goal's orientation to the requested orientation (false) or in line with the approach angle so the robot doesn't rotate to heading (true) + smoother: + max_iterations: 1000 + w_smooth: 0.3 + w_data: 0.2 + tolerance: 1.0e-10 diff --git a/configuration/packages/smac/configuring-smac-hybrid.rst b/configuration/packages/smac/configuring-smac-hybrid.rst index 295d148108..61a65b9ba8 100644 --- a/configuration/packages/smac/configuring-smac-hybrid.rst +++ b/configuration/packages/smac/configuring-smac-hybrid.rst @@ -413,47 +413,99 @@ Parameters Example ******* -.. code-block:: yaml - - planner_server: - ros__parameters: - planner_plugins: ["GridBased"] - - GridBased: - plugin: "nav2_smac_planner::SmacPlannerHybrid" # In Iron and older versions, "/" was used instead of "::" - downsample_costmap: false # whether or not to downsample the map - downsampling_factor: 1 # multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm) - tolerance: 0.25 # dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found. - allow_unknown: true # allow traveling in unknown space - max_iterations: 1000000 # maximum total iterations to search for before failing (in case unreachable), set to -1 to disable - max_on_approach_iterations: 1000 # Maximum number of iterations after within tolerances to continue to try to find exact solution - max_planning_time: 5.0 # max time in s for planner to plan, smooth - motion_model_for_search: "DUBIN" # Hybrid-A* Dubin, Redds-Shepp - angle_quantization_bins: 72 # Number of angle bins for search - analytic_expansion_ratio: 3.5 # The ratio to attempt analytic expansions during search for final approach. - analytic_expansion_max_length: 3.0 # For Hybrid/Lattice nodes: The maximum length of the analytic expansion to be considered valid to prevent unsafe shortcutting - analytic_expansion_max_cost: 200.0 # The maximum single cost for any part of an analytic expansion to contain and be valid, except when necessary on approach to goal - analytic_expansion_max_cost_override: false # Whether or not to override the maximum cost setting if within critical distance to goal (ie probably required) - minimum_turning_radius: 0.40 # minimum turning radius in m of path / vehicle - reverse_penalty: 2.0 # Penalty to apply if motion is reversing, must be => 1 - change_penalty: 0.0 # Penalty to apply if motion is changing directions (L to R), must be >= 0 - non_straight_penalty: 1.2 # Penalty to apply if motion is non-straight, must be => 1 - cost_penalty: 2.0 # Penalty to apply to higher cost areas when adding into the obstacle map dynamic programming distance expansion heuristic. This drives the robot more towards the center of passages. A value between 1.3 - 3.5 is reasonable. - retrospective_penalty: 0.015 - lookup_table_size: 20.0 # Size of the dubin/reeds-sheep distance window to cache, in meters. - cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. - debug_visualizations: false # For Hybrid nodes: Whether to publish expansions on the /expansions topic as an array of poses (the orientation has no meaning) and the path's footprints on the /planned_footprints topic. WARNING: heavy to compute and to display, for debug only as it degrades the performance. - use_quadratic_cost_penalty: False - downsample_obstacle_heuristic: True - allow_primitive_interpolation: False - coarse_search_resolution: 4 # Number of bins to skip when doing a coarse search for the path. Only used for all_direction goal heading mode. - goal_heading_mode: "DEFAULT" # DEFAULT, BIDIRECTIONAL, ALL_DIRECTION - smooth_path: True # If true, does a simple and quick smoothing post-processing to the path - - smoother: - max_iterations: 1000 - w_smooth: 0.3 - w_data: 0.2 - tolerance: 1.0e-10 - do_refinement: true - refinement_num: 2 + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ["grid_based"] + + grid_based: + plugin: "nav2_smac_planner::SmacPlannerHybrid" + downsample_costmap: false # whether or not to downsample the map + downsampling_factor: 1 # multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm) + tolerance: 0.25 # dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found. + allow_unknown: true # allow traveling in unknown space + max_iterations: 1000000 # maximum total iterations to search for before failing (in case unreachable), set to -1 to disable + max_on_approach_iterations: 1000 # Maximum number of iterations after within tolerances to continue to try to find exact solution + max_planning_time: 5.0 # max time in s for planner to plan, smooth + motion_model_for_search: "DUBIN" # Hybrid-A* Dubin, Redds-Shepp + angle_quantization_bins: 72 # Number of angle bins for search + analytic_expansion_ratio: 3.5 # The ratio to attempt analytic expansions during search for final approach. + analytic_expansion_max_length: 3.0 # For Hybrid/Lattice nodes: The maximum length of the analytic expansion to be considered valid to prevent unsafe shortcutting + analytic_expansion_max_cost: 200.0 # The maximum single cost for any part of an analytic expansion to contain and be valid, except when necessary on approach to goal + analytic_expansion_max_cost_override: false # Whether or not to override the maximum cost setting if within critical distance to goal (ie probably required) + minimum_turning_radius: 0.40 # minimum turning radius in m of path / vehicle + reverse_penalty: 2.0 # Penalty to apply if motion is reversing, must be => 1 + change_penalty: 0.0 # Penalty to apply if motion is changing directions (L to R), must be >= 0 + non_straight_penalty: 1.2 # Penalty to apply if motion is non-straight, must be => 1 + cost_penalty: 2.0 # Penalty to apply to higher cost areas when adding into the obstacle map dynamic programming distance expansion heuristic. This drives the robot more towards the center of passages. A value between 1.3 - 3.5 is reasonable. + retrospective_penalty: 0.015 + lookup_table_size: 20.0 # Size of the dubin/reeds-sheep distance window to cache, in meters. + cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. + debug_visualizations: false # For Hybrid nodes: Whether to publish expansions on the /expansions topic as an array of poses (the orientation has no meaning) and the path's footprints on the /planned_footprints topic. WARNING: heavy to compute and to display, for debug only as it degrades the performance. + use_quadratic_cost_penalty: False + downsample_obstacle_heuristic: True + allow_primitive_interpolation: False + coarse_search_resolution: 4 # Number of bins to skip when doing a coarse search for the path. Only used for all_direction goal heading mode. + goal_heading_mode: "DEFAULT" # DEFAULT, BIDIRECTIONAL, ALL_DIRECTION + smooth_path: True # If true, does a simple and quick smoothing post-processing to the path + + smoother: + max_iterations: 1000 + w_smooth: 0.3 + w_data: 0.2 + tolerance: 1.0e-10 + do_refinement: true + refinement_num: 2 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ["GridBased"] + + GridBased: + plugin: "nav2_smac_planner::SmacPlannerHybrid" # In Iron and older versions, "/" was used instead of "::" + downsample_costmap: false # whether or not to downsample the map + downsampling_factor: 1 # multiplier for the resolution of the costmap layer (e.g. 2 on a 5cm costmap would be 10cm) + tolerance: 0.25 # dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found. + allow_unknown: true # allow traveling in unknown space + max_iterations: 1000000 # maximum total iterations to search for before failing (in case unreachable), set to -1 to disable + max_on_approach_iterations: 1000 # Maximum number of iterations after within tolerances to continue to try to find exact solution + max_planning_time: 5.0 # max time in s for planner to plan, smooth + motion_model_for_search: "DUBIN" # Hybrid-A* Dubin, Redds-Shepp + angle_quantization_bins: 72 # Number of angle bins for search + analytic_expansion_ratio: 3.5 # The ratio to attempt analytic expansions during search for final approach. + analytic_expansion_max_length: 3.0 # For Hybrid/Lattice nodes: The maximum length of the analytic expansion to be considered valid to prevent unsafe shortcutting + analytic_expansion_max_cost: 200.0 # The maximum single cost for any part of an analytic expansion to contain and be valid, except when necessary on approach to goal + analytic_expansion_max_cost_override: false # Whether or not to override the maximum cost setting if within critical distance to goal (ie probably required) + minimum_turning_radius: 0.40 # minimum turning radius in m of path / vehicle + reverse_penalty: 2.0 # Penalty to apply if motion is reversing, must be => 1 + change_penalty: 0.0 # Penalty to apply if motion is changing directions (L to R), must be >= 0 + non_straight_penalty: 1.2 # Penalty to apply if motion is non-straight, must be => 1 + cost_penalty: 2.0 # Penalty to apply to higher cost areas when adding into the obstacle map dynamic programming distance expansion heuristic. This drives the robot more towards the center of passages. A value between 1.3 - 3.5 is reasonable. + retrospective_penalty: 0.015 + lookup_table_size: 20.0 # Size of the dubin/reeds-sheep distance window to cache, in meters. + cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. + debug_visualizations: false # For Hybrid nodes: Whether to publish expansions on the /expansions topic as an array of poses (the orientation has no meaning) and the path's footprints on the /planned_footprints topic. WARNING: heavy to compute and to display, for debug only as it degrades the performance. + use_quadratic_cost_penalty: False + downsample_obstacle_heuristic: True + allow_primitive_interpolation: False + coarse_search_resolution: 4 # Number of bins to skip when doing a coarse search for the path. Only used for all_direction goal heading mode. + goal_heading_mode: "DEFAULT" # DEFAULT, BIDIRECTIONAL, ALL_DIRECTION + smooth_path: True # If true, does a simple and quick smoothing post-processing to the path + + smoother: + max_iterations: 1000 + w_smooth: 0.3 + w_data: 0.2 + tolerance: 1.0e-10 + do_refinement: true + refinement_num: 2 diff --git a/configuration/packages/smac/configuring-smac-lattice.rst b/configuration/packages/smac/configuring-smac-lattice.rst index 49ff2842ef..4685349537 100644 --- a/configuration/packages/smac/configuring-smac-lattice.rst +++ b/configuration/packages/smac/configuring-smac-lattice.rst @@ -385,42 +385,89 @@ Parameters Example ******* -.. code-block:: yaml - - planner_server: - ros__parameters: - planner_plugins: ["GridBased"] - - GridBased: - plugin: "nav2_smac_planner::SmacPlannerLattice" # In Iron and older versions, "/" was used instead of "::" - allow_unknown: true # Allow traveling in unknown space - tolerance: 0.25 # dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found. - max_iterations: 1000000 # Maximum total iterations to search for before failing (in case unreachable), set to -1 to disable - max_on_approach_iterations: 1000 # Maximum number of iterations after within tolerances to continue to try to find exact solution - max_planning_time: 5.0 # Max time in s for planner to plan, smooth - analytic_expansion_ratio: 3.5 # The ratio to attempt analytic expansions during search for final approach. - analytic_expansion_max_length: 3.0 # For Hybrid/Lattice nodes The maximum length of the analytic expansion to be considered valid to prevent unsafe shortcutting - analytic_expansion_max_cost: 200.0 # The maximum single cost for any part of an analytic expansion to contain and be valid, except when necessary on approach to goal - analytic_expansion_max_cost_override: false # Whether or not to override the maximum cost setting if within critical distance to goal (ie probably required) - downsample_obstacle_heuristic: true # Downsample the obstacle map dynamic programming distance expansion heuristic to speed up search at the cost of some path quality - use_quadratic_cost_penalty: false # Use quadratic cost penalty for traversal and heuristic cost computations rather than linear - reverse_penalty: 2.0 # Penalty to apply if motion is reversing, must be => 1 - change_penalty: 0.05 # Penalty to apply if motion is changing directions (L to R), must be >= 0 - non_straight_penalty: 1.05 # Penalty to apply if motion is non-straight, must be => 1 - cost_penalty: 2.0 # Penalty to apply to higher cost areas when adding into the obstacle map dynamic programming distance expansion heuristic. This drives the robot more towards the center of passages. A value between 1.3 - 3.5 is reasonable. - rotation_penalty: 5.0 # Penalty to apply to in-place rotations, if minimum control set contains them - retrospective_penalty: 0.015 - lattice_filepath: "" # The filepath to the state lattice graph - lookup_table_size: 20.0 # Size of the dubin/reeds-sheep distance window to cache, in meters. - cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. - allow_reverse_expansion: false # If true, allows the robot to use the primitives to expand in the mirrored opposite direction of the current robot's orientation (to reverse). - coarse_search_resolution: 1 # Number of bins to skip when doing a coarse search for the path. Only used for all_direction goal heading mode. - goal_heading_mode: "DEFAULT" # DEFAULT, BIDIRECTIONAL, ALL_DIRECTION - smooth_path: True # If true, does a simple and quick smoothing post-processing to the path - smoother: - max_iterations: 1000 - w_smooth: 0.3 - w_data: 0.2 - tolerance: 1.0e-10 - do_refinement: true - refinement_num: 2 + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ["grid_based"] + + grid_based: + plugin: "nav2_smac_planner::SmacPlannerLattice" + allow_unknown: true # Allow traveling in unknown space + tolerance: 0.25 # dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found. + max_iterations: 1000000 # Maximum total iterations to search for before failing (in case unreachable), set to -1 to disable + max_on_approach_iterations: 1000 # Maximum number of iterations after within tolerances to continue to try to find exact solution + max_planning_time: 5.0 # Max time in s for planner to plan, smooth + analytic_expansion_ratio: 3.5 # The ratio to attempt analytic expansions during search for final approach. + analytic_expansion_max_length: 3.0 # For Hybrid/Lattice nodes The maximum length of the analytic expansion to be considered valid to prevent unsafe shortcutting + analytic_expansion_max_cost: 200.0 # The maximum single cost for any part of an analytic expansion to contain and be valid, except when necessary on approach to goal + analytic_expansion_max_cost_override: false # Whether or not to override the maximum cost setting if within critical distance to goal (ie probably required) + downsample_obstacle_heuristic: true # Downsample the obstacle map dynamic programming distance expansion heuristic to speed up search at the cost of some path quality + use_quadratic_cost_penalty: false # Use quadratic cost penalty for traversal and heuristic cost computations rather than linear + reverse_penalty: 2.0 # Penalty to apply if motion is reversing, must be => 1 + change_penalty: 0.05 # Penalty to apply if motion is changing directions (L to R), must be >= 0 + non_straight_penalty: 1.05 # Penalty to apply if motion is non-straight, must be => 1 + cost_penalty: 2.0 # Penalty to apply to higher cost areas when adding into the obstacle map dynamic programming distance expansion heuristic. This drives the robot more towards the center of passages. A value between 1.3 - 3.5 is reasonable. + rotation_penalty: 5.0 # Penalty to apply to in-place rotations, if minimum control set contains them + retrospective_penalty: 0.015 + lattice_filepath: "" # The filepath to the state lattice graph + lookup_table_size: 20.0 # Size of the dubin/reeds-sheep distance window to cache, in meters. + cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. + allow_reverse_expansion: false # If true, allows the robot to use the primitives to expand in the mirrored opposite direction of the current robot's orientation (to reverse). + coarse_search_resolution: 1 # Number of bins to skip when doing a coarse search for the path. Only used for all_direction goal heading mode. + goal_heading_mode: "DEFAULT" # DEFAULT, BIDIRECTIONAL, ALL_DIRECTION + smooth_path: True # If true, does a simple and quick smoothing post-processing to the path + smoother: + max_iterations: 1000 + w_smooth: 0.3 + w_data: 0.2 + tolerance: 1.0e-10 + do_refinement: true + refinement_num: 2 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ["GridBased"] + + GridBased: + plugin: "nav2_smac_planner::SmacPlannerLattice" # In Iron and older versions, "/" was used instead of "::" + allow_unknown: true # Allow traveling in unknown space + tolerance: 0.25 # dist-to-goal heuristic cost (distance) for valid tolerance endpoints if exact goal cannot be found. + max_iterations: 1000000 # Maximum total iterations to search for before failing (in case unreachable), set to -1 to disable + max_on_approach_iterations: 1000 # Maximum number of iterations after within tolerances to continue to try to find exact solution + max_planning_time: 5.0 # Max time in s for planner to plan, smooth + analytic_expansion_ratio: 3.5 # The ratio to attempt analytic expansions during search for final approach. + analytic_expansion_max_length: 3.0 # For Hybrid/Lattice nodes The maximum length of the analytic expansion to be considered valid to prevent unsafe shortcutting + analytic_expansion_max_cost: 200.0 # The maximum single cost for any part of an analytic expansion to contain and be valid, except when necessary on approach to goal + analytic_expansion_max_cost_override: false # Whether or not to override the maximum cost setting if within critical distance to goal (ie probably required) + downsample_obstacle_heuristic: true # Downsample the obstacle map dynamic programming distance expansion heuristic to speed up search at the cost of some path quality + use_quadratic_cost_penalty: false # Use quadratic cost penalty for traversal and heuristic cost computations rather than linear + reverse_penalty: 2.0 # Penalty to apply if motion is reversing, must be => 1 + change_penalty: 0.05 # Penalty to apply if motion is changing directions (L to R), must be >= 0 + non_straight_penalty: 1.05 # Penalty to apply if motion is non-straight, must be => 1 + cost_penalty: 2.0 # Penalty to apply to higher cost areas when adding into the obstacle map dynamic programming distance expansion heuristic. This drives the robot more towards the center of passages. A value between 1.3 - 3.5 is reasonable. + rotation_penalty: 5.0 # Penalty to apply to in-place rotations, if minimum control set contains them + retrospective_penalty: 0.015 + lattice_filepath: "" # The filepath to the state lattice graph + lookup_table_size: 20.0 # Size of the dubin/reeds-sheep distance window to cache, in meters. + cache_obstacle_heuristic: false # Cache the obstacle map dynamic programming distance expansion heuristic between subsequent replannings of the same goal location. Dramatically speeds up replanning performance (40x) if costmap is largely static. + allow_reverse_expansion: false # If true, allows the robot to use the primitives to expand in the mirrored opposite direction of the current robot's orientation (to reverse). + coarse_search_resolution: 1 # Number of bins to skip when doing a coarse search for the path. Only used for all_direction goal heading mode. + goal_heading_mode: "DEFAULT" # DEFAULT, BIDIRECTIONAL, ALL_DIRECTION + smooth_path: True # If true, does a simple and quick smoothing post-processing to the path + smoother: + max_iterations: 1000 + w_smooth: 0.3 + w_data: 0.2 + tolerance: 1.0e-10 + do_refinement: true + refinement_num: 2 diff --git a/migration/Kilted.rst b/migration/Kilted.rst index 74b7109919..8ab0f89885 100644 --- a/migration/Kilted.rst +++ b/migration/Kilted.rst @@ -5,6 +5,195 @@ Kilted to L-turtle Moving from ROS 2 Kilted to L-Turtle, a number of stability improvements were added that we will not specifically address here. +Changed parameter naming style +------------------------------ + +`PR #5793 `_ +updates the naming style for a group of parameters from ``PascalCase`` to ``snake_case``. +The changes concern the names of parameters (IDs) that are associated with plugins and other components, +which are described in the tables below. + +Parameter files +^^^^^^^^^^^^^^^ + +To make it easier to find names that need to be changed, the table below shows the server names, +along with the corresponding parameters associated with updated names, including at least one example of such an updated name. + ++----------------------+---------------------------+----------------------------------------------------------+ +| Server name | Parameter where IDs | Example | +| | are defined | | ++======================+===========================+==========================================================+ +|**Plugin related** | ++----------------------+---------------------------+----------------------------------------------------------+ +| controller_server | controller_plugins | `FollowPath` -> `follow_path` | ++----------------------+---------------------------+----------------------------------------------------------+ +| controller_server | path_handler_plugins | `PathHandler` -> `path_handler` | ++----------------------+---------------------------+----------------------------------------------------------+ +| planner_server | planner_plugins | `GridBased` -> `grid_based` | ++----------------------+---------------------------+----------------------------------------------------------+ +| smoother_server | smoother_plugins | `SimpleSmoother` -> `simple_smoother` | ++----------------------+---------------------------+----------------------------------------------------------+ +| route_server | operations | `AdjustSpeedLimit` -> `adjust_speed_limit` | ++----------------------+---------------------------+----------------------------------------------------------+ +| route_server | edge_cost_functions | `DistanceScorer` -> `distance_scorer` | ++----------------------+---------------------------+----------------------------------------------------------+ +| route_server | graph_file_loader | `GeoJsonGraphFileLoader` -> `geo_json_graph_file_loader` | ++----------------------+---------------------------+----------------------------------------------------------+ +|**Non-plugin related** | ++----------------------+---------------------------+----------------------------------------------------------+ +| collision_monitor | polygons | `FootprintApproach` -> `footprint_approach` | ++----------------------+---------------------------+----------------------------------------------------------+ +| collision_detector | polygons | `PolygonFront` -> `polygon_front` | ++----------------------+---------------------------+----------------------------------------------------------+ +| vector_object_server | shapes | `Circle` -> `circle` | ++----------------------+---------------------------+----------------------------------------------------------+ + +Examples from updated YAML configuration files: + +.. tabs:: + + .. group-tab:: Lyrical + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_plugins: ["follow_path"] + follow_path: + plugin: "nav2_mppi_controller::MPPIController" + + .. code-block:: yaml + + collision_monitor: + ros__parameters: + polygons: ["footprint_approach"] + footprint_approach: + type: "polygon" + + .. group-tab:: Kilted + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_plugins: ["FollowPath"] + FollowPath: + plugin: "nav2_mppi_controller::MPPIController" + + .. code-block:: yaml + + collision_monitor: + ros__parameters: + polygons: ["FootprintApproach"] + FootprintApproach: + type: "polygon" + +An example of a complete configuration can be found in +`nav2_params.yaml `_ file. + +BT configuration +^^^^^^^^^^^^^^^^ + +The behavior tree XML configuration files may require updating the following names related to input ports used in BT Action Nodes: + ++-------------------------+--------------------------+-----------------------------------------+ +| BT Action Node ID | Input port | Example | ++=========================+==========================+=========================================+ +| FollowPath | controller_id | `FollowPath` -> `follow_path` | ++-------------------------+--------------------------+-----------------------------------------+ +| FollowPath | path_handler_id | `PathHandler` -> `path_handler` | ++-------------------------+--------------------------+-----------------------------------------+ +| FollowPath | goal_checker_id | `GoalChecker` -> `goal_checker` | ++-------------------------+--------------------------+-----------------------------------------+ +| FollowPath | progress_checker_id | `ProgressChecker` -> `progress_checker` | ++-------------------------+--------------------------+-----------------------------------------+ +| ComputePathToPose | planner_id | `GridBased` -> `grid_based` | ++-------------------------+--------------------------+-----------------------------------------+ +| ComputePathThroughPoses | planner_id | `GridBased` -> `grid_based` | ++-------------------------+--------------------------+-----------------------------------------+ +| SmoothPath | smoother_id | `RouteSmoother` -> `route_smoother` | ++-------------------------+--------------------------+-----------------------------------------+ +| ControllerSelector | default_controller | `FollowPath` -> `follow_path` | ++-------------------------+--------------------------+-----------------------------------------+ +| GoalCheckerSelector | default_goal_checker | `GoalChecker` -> `goal_checker` | ++-------------------------+--------------------------+-----------------------------------------+ +| ProgressCheckerSelector | default_progress_checker | `ProgressChecker` -> `progress_checker` | ++-------------------------+--------------------------+-----------------------------------------+ +| PlannerSelector | planner_id | `GridBased` -> `grid_based` | ++-------------------------+--------------------------+-----------------------------------------+ +| PathHandlerSelector | default_path_handler | `PathHandler` -> `path_handler` | ++-------------------------+--------------------------+-----------------------------------------+ +| SmootherSelector | default_smoother | `SimpleSmoother` -> `simple_smoother` | ++-------------------------+--------------------------+-----------------------------------------+ + +An example for updated XML configuration file: + +.. tabs:: + + .. group-tab:: Lyrical + + .. code-block:: xml + + ... + + + ... + + .. group-tab:: Kilted + + .. code-block:: xml + + ... + + + ... + +The full configuration can be found in +`navigate_to_pose_w_replanning_and_recovery.xml +`_ +(default behavior tree). + +Additionally, some BT Action Nodes have new default values in the `nav2_tree_nodes.xml +`_ file used for Groot: + ++------------+--------------------+ +| Action ID | Default input port | ++============+====================+ +| SmoothPath | smooth_path | ++------------+--------------------+ +| FollowPath | follow_path | ++------------+--------------------+ + +.. tabs:: + + .. group-tab:: Lyrical + + .. code-block:: xml + + + + ... + + + + + ... + + + .. group-tab:: Kilted + + .. code-block:: xml + + + + ... + + + + + ... + + New Nav2 ROS Common & Nav2 Lifecycle Node ----------------------------------------- @@ -631,7 +820,7 @@ With this change, users can now configure a path handler in the controller serve .. code-block:: yaml - PathHandler: + path_handler: plugin: "nav2_controller::FeasiblePathHandler" prune_distance: 2.0 enforce_path_inversion: True diff --git a/plugin_tutorials/docs/writing_new_bt_plugin.rst b/plugin_tutorials/docs/writing_new_bt_plugin.rst index 08669e80e5..d88f58fb39 100644 --- a/plugin_tutorials/docs/writing_new_bt_plugin.rst +++ b/plugin_tutorials/docs/writing_new_bt_plugin.rst @@ -207,35 +207,71 @@ For example, the ``navigate_w_replanning_and_recovery.xml`` file is shown below. Select this BT XML file in your specific navigation request in ``NavigateToPose`` or as the default behavior tree in the BT Navigator's configuration yaml file. -.. code-block:: xml - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - + + Using custom types for Input/Output ports ========================================= diff --git a/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst b/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst index 2be1503da6..40d667987e 100644 --- a/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst +++ b/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst @@ -133,8 +133,8 @@ In controllers, ``configure()`` method must set member variables from ROS parame Here, ``plugin_name_ + ".desired_linear_vel"`` is fetching the ROS parameter ``desired_linear_vel`` which is specific to our controller. Nav2 allows loading of multiple plugins, and to keep things organized, each plugin is mapped to some ID/name. Now, if we want to retrieve the parameters for that specific plugin, we use ``.`` as done in the above snippet. -For example, our example controller is mapped to the name ``FollowPath`` and to retrieve the ``desired_linear_vel`` parameter, which is specific to "FollowPath”, -we used ``FollowPath.desired_linear_vel``. In other words, ``FollowPath`` is used as a namespace for plugin-specific parameters. +For example, our example controller is mapped to the name ``follow_path`` (``FollowPath`` in Kilted and older versions from here on) and to retrieve the ``desired_linear_vel`` parameter, which is specific to "follow_path", +we used ``follow_path.desired_linear_vel``. In other words, ``follow_path`` is used as a namespace for plugin-specific parameters. We will see more on this when we discuss the parameters file (or params file). The passed-in arguments are stored in member variables so that they can be used at a later stage if needed. @@ -277,21 +277,41 @@ Next, we'll use this plugin. To enable the plugin, we need to modify the ``nav2_params.yaml`` file as below -.. code-block:: text +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_plugins: ["follow_path"] + + follow_path: + plugin: "nav2_pure_pursuit_controller::PurePursuitController" + debug_trajectory_details: True + desired_linear_vel: 0.2 + lookahead_dist: 0.4 + max_angular_vel: 1.0 + transform_tolerance: 1.0 + + .. group-tab:: Kilted and older + + .. code-block:: yaml - controller_server: - ros__parameters: - controller_plugins: ["FollowPath"] + controller_server: + ros__parameters: + controller_plugins: ["FollowPath"] - FollowPath: - plugin: "nav2_pure_pursuit_controller::PurePursuitController" # In Iron and older versions, "/" was used instead of "::" - debug_trajectory_details: True - desired_linear_vel: 0.2 - lookahead_dist: 0.4 - max_angular_vel: 1.0 - transform_tolerance: 1.0 + FollowPath: + plugin: "nav2_pure_pursuit_controller::PurePursuitController" # In Iron and older versions, "/" was used instead of "::" + debug_trajectory_details: True + desired_linear_vel: 0.2 + lookahead_dist: 0.4 + max_angular_vel: 1.0 + transform_tolerance: 1.0 -In the above snippet, you can observe the mapping of our ``nav2_pure_pursuit_controller::PurePursuitController`` controller to its id ``FollowPath``. +In the above snippet, you can observe the mapping of our ``nav2_pure_pursuit_controller::PurePursuitController`` controller to its id ``follow_path`` (``FollowPath`` in Kilted and older). To pass plugin-specific parameters we have used ``.``. 4- Run Pure Pursuit Controller plugin diff --git a/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst b/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst index 8fa6eb00c7..b5e15a56bd 100644 --- a/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst +++ b/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst @@ -80,7 +80,7 @@ In planners, ``configure()`` method must set member variables from ROS parameter nav2_util::declare_parameter_if_not_declared(node_, name_ + ".interpolation_resolution", rclcpp::ParameterValue(0.1)); node_->get_parameter(name_ + ".interpolation_resolution", interpolation_resolution_); -Here, ``name_ + ".interpolation_resolution"`` is fetching the ROS parameters ``interpolation_resolution`` which is specific to our planner. Nav2 allows the loading of multiple plugins, and to keep things organized, each plugin is mapped to some ID/name. Now if we want to retrieve the parameters for that specific plugin, we use ``.`` as done in the above snippet. For example, our example planner is mapped to the name "GridBased" and to retrieve the ``interpolation_resolution`` parameter which is specific to "GridBased", we used ``Gridbased.interpolation_resolution``. In other words, ``GridBased`` is used as a namespace for plugin-specific parameters. We will see more on this when we discuss the parameters file (or params file). +Here, ``name_ + ".interpolation_resolution"`` is fetching the ROS parameters ``interpolation_resolution`` which is specific to our planner. Nav2 allows the loading of multiple plugins, and to keep things organized, each plugin is mapped to some ID/name. Now if we want to retrieve the parameters for that specific plugin, we use ``.`` as done in the above snippet. For example, our example planner is mapped to the name ``grid_based`` (``GridBased`` in Kilted and older versions from here on) and to retrieve the ``interpolation_resolution`` parameter which is specific to "grid_based", we used ``grid_based.interpolation_resolution``. In other words, ``grid_based`` is used as a namespace for plugin-specific parameters. We will see more on this when we discuss the parameters file (or params file). In ``createPlan()`` method, we need to create a path from the given start to goal poses. The ``StraightLine::createPlan()`` is called using start pose and goal pose to solve the global path planning problem. Upon succeeding, it converts the path to the ``nav_msgs::msg::Path`` and returns to the planner server. Below annotation shows the implementation of this method. @@ -207,29 +207,57 @@ To enable the plugin, we need to modify the ``nav2_params.yaml`` file as below t For Galactic or later, ``plugin_names`` and ``plugin_types`` have been replaced with a single ``plugins`` string vector for plugin names. The types are now defined in the ``plugin_name`` namespace in the ``plugin:`` field (e.g. ``plugin: MyPlugin::Plugin``). Inline comments in the code blocks will help guide you through this. -.. code-block:: text +.. tabs:: - planner_server: - ros__parameters: - plugins: ["GridBased"] - GridBased: - plugin: "nav2_navfn_planner::NavfnPlanner" # For Foxy and later. In Iron and older versions, "/" was used instead of "::" - tolerance: 2.0 - use_astar: false - allow_unknown: true + .. group-tab:: Rolling -with + .. code-block:: yaml -.. code-block:: text + planner_server: + ros__parameters: + plugins: ["grid_based"] + grid_based: + plugin: "nav2_navfn_planner::NavfnPlanner" + tolerance: 2.0 + use_astar: false + allow_unknown: true + + with + + .. code-block:: yaml + + planner_server: + ros__parameters: + plugins: ["grid_based"] + grid_based: + plugin: "nav2_straightline_planner::StraightLine" + interpolation_resolution: 0.1 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + planner_server: + ros__parameters: + plugins: ["GridBased"] + GridBased: + plugin: "nav2_navfn_planner::NavfnPlanner" # For Foxy and later. In Iron and older versions, "/" was used instead of "::" + tolerance: 2.0 + use_astar: false + allow_unknown: true + + with + + .. code-block:: yaml - planner_server: - ros__parameters: - plugins: ["GridBased"] - GridBased: - plugin: "nav2_straightline_planner::StraightLine" - interpolation_resolution: 0.1 + planner_server: + ros__parameters: + plugins: ["GridBased"] + GridBased: + plugin: "nav2_straightline_planner::StraightLine" + interpolation_resolution: 0.1 -In the above snippet, you can observe the mapping of our ``nav2_straightline_planner::StraightLine`` planner to its id ``GridBased``. To pass plugin-specific parameters, we have used ``.``. +In the above snippet, you can observe the mapping of our ``nav2_straightline_planner::StraightLine`` planner to its id ``grid_based`` (``GridBased`` in Kilted and older). To pass plugin-specific parameters, we have used ``.``. 4- Run StraightLine plugin --------------------------- diff --git a/requirements.txt b/requirements.txt index 1cf4fae29e..cf2cef52d5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,5 +5,6 @@ myst-parser==1.0.0 sphinx_copybutton==0.5.2 sphinx_rtd_theme==2.0.0 sphinx-autobuild +sphinx-tabs sphinx==5.3.0 sphinxcontrib-plantuml diff --git a/setup_guides/algorithm/select_algorithm.rst b/setup_guides/algorithm/select_algorithm.rst index 2874d10267..f502cc047d 100644 --- a/setup_guides/algorithm/select_algorithm.rst +++ b/setup_guides/algorithm/select_algorithm.rst @@ -60,15 +60,29 @@ Summary Example Configuration --------------------- -.. code-block:: yaml +.. tabs:: - planner_server: - ros__parameters: - planner_plugins: ['GridBased'] - GridBased: - plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::" + .. group-tab:: Rolling -An example configuration of the planner server is shown above. The ``planner_plugins`` parameter accepts a list of mapped planner plugin names. For each plugin namespace defined in ``planner_plugins`` (``GridBased`` in our example), we specify the type of plugin to be loaded in the ``plugin`` parameter. Additional configurations must then be specified in this namespace based on the algorithm to be used. Please see the `Configuration Guide `_ for more details. + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ['grid_based'] + grid_based: + plugin: 'nav2_navfn_planner::NavfnPlanner' + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + planner_server: + ros__parameters: + planner_plugins: ['GridBased'] + GridBased: + plugin: 'nav2_navfn_planner::NavfnPlanner' # In Iron and older versions, "/" was used instead of "::" + +An example configuration of the planner server is shown above. The ``planner_plugins`` parameter accepts a list of mapped planner plugin names. For each plugin namespace defined in ``planner_plugins``, ``grid_based`` as in the example (``GridBased`` in Kilted and older), we specify the type of plugin to be loaded in the ``plugin`` parameter. Additional configurations must then be specified in this namespace based on the algorithm to be used. Please see the `Configuration Guide `_ for more details. Controller Server ================= @@ -105,15 +119,30 @@ All of these algorithms work for both circular and non-circular robots. Example Configuration --------------------- -.. code-block:: yaml +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_plugins: ["follow_path"] + follow_path: + plugin: "dwb_core::DWBLocalPlanner" + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_plugins: ["FollowPath"] + FollowPath: + plugin: "dwb_core::DWBLocalPlanner" - controller_server: - ros__parameters: - controller_plugins: ["FollowPath"] - FollowPath: - plugin: "dwb_core::DWBLocalPlanner" -Shown above is a sample basic configuration of the controller server. The list of mapped names for controller plugins are defined in the ``controller_plugins`` parameter. Similar to the planner server, each namespace defined in the ``controller_plugins`` (``FollowPath`` in our example) must define the type of plugin it will use in the ``plugin`` parameter. Additional configurations must also be made for the selected algorithm in the namespace. Please see the `Configuration Guide `_ for more details. +Shown above is a sample basic configuration of the controller server. The list of mapped names for controller plugins are defined in the ``controller_plugins`` parameter. Similar to the planner server, each namespace defined in the ``controller_plugins``, ``follow_path`` as in the example (``FollowPath`` in Kilted and older), must define the type of plugin it will use in the ``plugin`` parameter. Additional configurations must also be made for the selected algorithm in the namespace. Please see the `Configuration Guide `_ for more details. .. note:: The planner and controller servers, along with the other servers of Nav2, are launched in ROS 2 through lifecycle nodes. Lifecycle nodes allow for easier bringup and teardown of the servers. Lifecycle node management will be discussed in the next tutorial. diff --git a/tutorials/docs/adding_smoother.rst b/tutorials/docs/adding_smoother.rst index 37baceecee..2d1609bbb2 100644 --- a/tutorials/docs/adding_smoother.rst +++ b/tutorials/docs/adding_smoother.rst @@ -70,18 +70,41 @@ Note: If you use only a single type of smoothing algorithm, there is no need to A given behavior tree will have a line: -.. code-block:: xml +.. tabs:: - + .. group-tab:: Rolling -This line calls the planner server and return a path to the ``path`` blackboard variable in the behavior tree. We are going to replace that line with the following to compute the path, smooth the path, and finally replace the ``path`` blackboard variable with the new smoothed path that the system will now interact with: + .. code-block:: xml -.. code-block:: xml + + + .. group-tab:: Kilted and older + + .. code-block:: xml - - - + +This line calls the planner server and return a path to the ``path`` blackboard variable in the behavior tree. We are going to replace that line with the following to compute the path, smooth the path, and finally replace the ``path`` blackboard variable with the new smoothed path that the system will now interact with: + +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + .. hint:: When using this sequence inside a ``PipelineSequence`` node, it is recommended to remap the smoothed path to a different blackboard variable (e.g. ``smoothed_path="{smoothed_path}"``). diff --git a/tutorials/docs/navigation2_dynamic_point_following.rst b/tutorials/docs/navigation2_dynamic_point_following.rst index f6530d32ce..9ffb970998 100644 --- a/tutorials/docs/navigation2_dynamic_point_following.rst +++ b/tutorials/docs/navigation2_dynamic_point_following.rst @@ -149,76 +149,165 @@ ComputePathToPose Tutorial Steps Let's start from this simple behavior tree. This behavior tree replans a new path at 1 hz and passes that path to the controller to follow: -.. code-block:: xml - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + First, let's make this behavior run until there's a failure. For this purpose, we will use the ``KeepRunningUntilFailure`` control node. -.. code-block:: xml - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + We will then use the decorator ``GoalUpdater`` to accept updates of the dynamic object pose we're trying to follow. This node takes as input the current goal and subscribes to the topic ``/goal_update``. It sets the new goal as ``updated_goal`` if a new goal on that topic is received. -.. code-block:: xml - - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + To stay at a certain distance from the target, we will use the action node ``TruncatePath``. This node modifies a path making it shorter so we don't try to navigate into the object of interest. We can set up the desired distance to the goal using the input port ``distance``. -.. code-block:: xml - - - - - - - - - - - - - - - - - - +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + .. group-tab:: Kilted and older + + .. code-block:: xml + + + + + + + + + + + + + + + + + + Now, you may save this behavior tree and use it in our navigation task. diff --git a/tutorials/docs/navigation2_with_vector_objects.rst b/tutorials/docs/navigation2_with_vector_objects.rst index 11d2ca1716..68ce63fae2 100644 --- a/tutorials/docs/navigation2_with_vector_objects.rst +++ b/tutorials/docs/navigation2_with_vector_objects.rst @@ -43,22 +43,26 @@ Vector Object server has its own ``vector_object_server.launch.py`` launch-file In this tutorial, we are focusing on the application how to utilize the simple setup allowing to add virtual obstacles on costmaps. For demonstration purposes, let's specify two obstacle shapes: triangle polygon and circle filled with "occupied" value, in order to prevent the robot to go through them. The YAML-part for polygon and circle will look as follows: -.. code-block:: yaml - - shapes: ["Poly", "Circle"] - Poly: - type: "polygon" - frame_id: "map" - closed: True - value: 100 - points: [0.3, 0.5, -0.4, 1.2, -0.4, -0.2] - Circle: - type: "circle" - frame_id: "map" - fill: True - value: 100 - center: [1.5, 0.5] - radius: 0.7 +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + shapes: ["poly", "circle"] + poly: + type: "polygon" + frame_id: "map" + closed: True + value: 100 + points: [0.3, 0.5, -0.4, 1.2, -0.4, -0.2] + circle: + type: "circle" + frame_id: "map" + fill: True + value: 100 + center: [1.5, 0.5] + radius: 0.7 Where the triangle polygon is specified by ``{0.3, 0.5}, {-0.4, 1.2}, {-0.4, -0.2}`` 3-point shape and the circle has ``{1.5, 0.5}`` coordinate of its center with ``0.7`` meter radius in the ``map`` frame. ``closed`` true-value for the polygon and ``fill`` for the circle mean that both shapes to be filled the with specified ``value``. @@ -77,38 +81,42 @@ Costmap Filter Info message is being published by Costmap Filter Info server, wh The complete ``vector_object_server_params.yaml`` YAML-file for the demonstration looks as follows: -.. code-block:: yaml - - vector_object_server: - ros__parameters: - map_topic: "vo_map" - global_frame_id: "map" - resolution: 0.05 - default_value: -1 - overlay_type: 0 - update_frequency: 1.0 - transform_tolerance: 0.1 - shapes: ["Poly", "Circle"] - Poly: - type: "polygon" - frame_id: "map" - closed: True - value: 100 - points: [0.3, 0.5, -0.4, 1.2, -0.4, -0.2] - Circle: - type: "circle" - frame_id: "map" - fill: True - value: 100 - center: [1.5, 0.5] - radius: 0.7 - costmap_filter_info_server: - ros__parameters: - type: 0 - filter_info_topic: "vo_costmap_filter_info" - mask_topic: "vo_map" - base: 0.0 - multiplier: 1.0 +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + vector_object_server: + ros__parameters: + map_topic: "vo_map" + global_frame_id: "map" + resolution: 0.05 + default_value: -1 + overlay_type: 0 + update_frequency: 1.0 + transform_tolerance: 0.1 + shapes: ["poly", "circle"] + poly: + type: "polygon" + frame_id: "map" + closed: True + value: 100 + points: [0.3, 0.5, -0.4, 1.2, -0.4, -0.2] + circle: + type: "circle" + frame_id: "map" + fill: True + value: 100 + center: [1.5, 0.5] + radius: 0.7 + costmap_filter_info_server: + ros__parameters: + type: 0 + filter_info_topic: "vo_costmap_filter_info" + mask_topic: "vo_map" + base: 0.0 + multiplier: 1.0 More detailed information about each Vector Object server parameter and its operating principle could be found on :ref:`configuring_vector_object_server` configuration guide page. Costmap Filter Info server parameters description could be found at :ref:`configuring_costmap_filter_info_server` page. @@ -126,17 +134,21 @@ Vector Object server puts shapes to OccupacyGrid map and publishes it in a topic Enabling of Keeput Filter in Nav2 stack principles are similar as written in :ref:`navigation2_with_keepout_filter` tutorial. Since vector objects are being enabled in global costmaps, Keepout Filter called as "vector_object_layer", should be added to the global costmap section of the ``nav2_params.yaml`` standard Nav2 configuration as follows: -.. code-block:: yaml +.. tabs:: - global_costmap: - ros__parameters: - plugins: ["static_layer", "obstacle_layer", "inflation_layer"] - filters: ["keepout_filter", "speed_filter", "vector_object_layer"] - ... - vector_object_layer: - plugin: "nav2_costmap_2d::KeepoutFilter" - enabled: True - filter_info_topic: "vo_costmap_filter_info" + .. group-tab:: Rolling + + .. code-block:: yaml + + global_costmap: + ros__parameters: + plugins: ["static_layer", "obstacle_layer", "inflation_layer"] + filters: ["keepout_filter", "speed_filter", "vector_object_layer"] + ... + vector_object_layer: + plugin: "nav2_costmap_2d::KeepoutFilter" + enabled: True + filter_info_topic: "vo_costmap_filter_info" Demo Execution ============== diff --git a/tutorials/docs/using_collision_monitor.rst b/tutorials/docs/using_collision_monitor.rst index ea57f69b79..724f891c32 100644 --- a/tutorials/docs/using_collision_monitor.rst +++ b/tutorials/docs/using_collision_monitor.rst @@ -7,7 +7,7 @@ Using Collision Monitor - `Requirements`_ - `Preparing Nav2 stack`_ - `Configuring Collision Monitor`_ -- `Configuring Collision Monitor with VelocityPolygon`_ +- `Configuring Collision Monitor with velocity_polygon`_ - `Demo Execution`_ .. image:: images/Collision_Monitor/collision_monitor.gif @@ -35,26 +35,51 @@ For the demonstration, two shapes will be created - an inner stop and a larger s If more than 3 points will appear inside a slowdown box, the robot will decrease its speed to ``30%`` from its value. For the cases when obstacles are dangerously close to the robot, inner stop zone will work. -For this setup, the following lines should be added into ``collision_monitor_params.yaml`` parameters file. Stop box is named as ``PolygonStop`` and slowdown bounding box - as ``PolygonSlow``: +For this setup, the following lines should be added into ``collision_monitor_params.yaml`` parameters file. Stop box is named as ``polygon_stop`` and slowdown bounding box - as ``polygon_slow`` (``PolygonStop`` and ``PolygonSlow``, respectively, in Kilted and older): -.. code-block:: yaml +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + polygons: ["polygon_stop", "polygon_slow"] + polygon_stop: + type: "polygon" + points: "[[0.4, 0.3], [0.4, -0.3], [0.0, -0.3], [0.0, 0.3]]" + action_type: "stop" + min_points: 4 + visualize: True + polygon_pub_topic: "polygon_stop" + polygon_slow: + type: "polygon" + points: "[[0.6, 0.4], [0.6, -0.4], [0.0, -0.4], [0.0, 0.4]]" + action_type: "slowdown" + min_points: 4 + slowdown_ratio: 0.3 + visualize: True + polygon_pub_topic: "polygon_slowdown" - polygons: ["PolygonStop", "PolygonSlow"] - PolygonStop: - type: "polygon" - points: "[[0.4, 0.3], [0.4, -0.3], [0.0, -0.3], [0.0, 0.3]]" - action_type: "stop" - min_points: 4 # max_points: 3 for Humble - visualize: True - polygon_pub_topic: "polygon_stop" - PolygonSlow: - type: "polygon" - points: "[[0.6, 0.4], [0.6, -0.4], [0.0, -0.4], [0.0, 0.4]]" - action_type: "slowdown" - min_points: 4 # max_points: 3 for Humble - slowdown_ratio: 0.3 - visualize: True - polygon_pub_topic: "polygon_slowdown" + .. group-tab:: Kilted and older + + .. code-block:: yaml + + polygons: ["PolygonStop", "PolygonSlow"] + PolygonStop: + type: "polygon" + points: "[[0.4, 0.3], [0.4, -0.3], [0.0, -0.3], [0.0, 0.3]]" + action_type: "stop" + min_points: 4 # max_points: 3 for Humble + visualize: True + polygon_pub_topic: "polygon_stop" + PolygonSlow: + type: "polygon" + points: "[[0.6, 0.4], [0.6, -0.4], [0.0, -0.4], [0.0, 0.4]]" + action_type: "slowdown" + min_points: 4 # max_points: 3 for Humble + slowdown_ratio: 0.3 + visualize: True + polygon_pub_topic: "polygon_slowdown" .. note:: The circle shape could be used instead of polygon, e.g. for the case of omni-directional robots where the collision can occur from any direction. However, for the tutorial needs, let's focus our view on polygons. For the same reason, we leave out of scope the Approach model. Both of these cases could be easily enabled by referencing to the :ref:`configuring_collision_monitor` configuration guide. @@ -75,52 +100,92 @@ In current demonstration, it is used laser scanner (though ``PointCloud2`` and R Set topic names, frame ID-s and timeouts to work correctly with a default Nav2 setup. The whole ``nav2_collision_monitor/params/collision_monitor_params.yaml`` file in this case will look as follows: -.. code-block:: yaml - - collision_monitor: - ros__parameters: - enabled: True - base_frame_id: "base_footprint" - odom_frame_id: "odom" - cmd_vel_in_topic: "cmd_vel_smoothed" - cmd_vel_out_topic: "cmd_vel" - transform_tolerance: 0.5 - source_timeout: 5.0 - stop_pub_timeout: 2.0 - enable_stamped_cmd_vel: True # False for Jazzy or older by default - polygons: ["PolygonStop", "PolygonSlow"] - PolygonStop: - type: "polygon" - points: "[[0.4, 0.3], [0.4, -0.3], [0.0, -0.3], [0.0, 0.3]]" - action_type: "stop" - min_points: 4 # max_points: 3 for Humble - visualize: True - polygon_pub_topic: "polygon_stop" - PolygonSlow: - type: "polygon" - points: "[[0.6, 0.4], [0.6, -0.4], [0.0, -0.4], [0.0, 0.4]]" - action_type: "slowdown" - min_points: 4 # max_points: 3 for Humble - slowdown_ratio: 0.3 - visualize: True - polygon_pub_topic: "polygon_slowdown" - observation_sources: ["scan"] - scan: - type: "scan" - topic: "scan" - -Configuring Collision Monitor with VelocityPolygon -================================================== +.. tabs:: + + .. group-tab:: Rolling + + .. code-block:: yaml + + collision_monitor: + ros__parameters: + enabled: True + base_frame_id: "base_footprint" + odom_frame_id: "odom" + cmd_vel_in_topic: "cmd_vel_smoothed" + cmd_vel_out_topic: "cmd_vel" + transform_tolerance: 0.5 + source_timeout: 5.0 + stop_pub_timeout: 2.0 + enable_stamped_cmd_vel: True + polygons: ["polygon_stop", "polygon_slow"] + polygon_stop: + type: "polygon" + points: "[[0.4, 0.3], [0.4, -0.3], [0.0, -0.3], [0.0, 0.3]]" + action_type: "stop" + min_points: 4 + visualize: True + polygon_pub_topic: "polygon_stop" + polygon_slow: + type: "polygon" + points: "[[0.6, 0.4], [0.6, -0.4], [0.0, -0.4], [0.0, 0.4]]" + action_type: "slowdown" + min_points: 4 + slowdown_ratio: 0.3 + visualize: True + polygon_pub_topic: "polygon_slowdown" + observation_sources: ["scan"] + scan: + type: "scan" + topic: "scan" + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + collision_monitor: + ros__parameters: + enabled: True + base_frame_id: "base_footprint" + odom_frame_id: "odom" + cmd_vel_in_topic: "cmd_vel_smoothed" + cmd_vel_out_topic: "cmd_vel" + transform_tolerance: 0.5 + source_timeout: 5.0 + stop_pub_timeout: 2.0 + enable_stamped_cmd_vel: True # False for Jazzy or older by default + polygons: ["PolygonStop", "PolygonSlow"] + PolygonStop: + type: "polygon" + points: "[[0.4, 0.3], [0.4, -0.3], [0.0, -0.3], [0.0, 0.3]]" + action_type: "stop" + min_points: 4 # max_points: 3 for Humble + visualize: True + polygon_pub_topic: "polygon_stop" + PolygonSlow: + type: "polygon" + points: "[[0.6, 0.4], [0.6, -0.4], [0.0, -0.4], [0.0, 0.4]]" + action_type: "slowdown" + min_points: 4 # max_points: 3 for Humble + slowdown_ratio: 0.3 + visualize: True + polygon_pub_topic: "polygon_slowdown" + observation_sources: ["scan"] + scan: + type: "scan" + topic: "scan" + +Configuring Collision Monitor with velocity_polygon +=================================================== .. image:: images/Collision_Monitor/dexory_velocity_polygon.gif :width: 800px -For this part of tutorial, we will set up the Collision Monitor with ``VelocityPolygon`` type for a ``stop`` action. ``VelocityPolygon`` allows the user to setup multiple polygons to cover the range of the robot's velocity limits. For example, the user can configure different polygons for rotation, moving forward, or moving backward. The Collision Monitor will check the robot's velocity against each sub polygon to determine the appropriate polygon to be used for collision checking. +For this part of tutorial, we will set up the Collision Monitor with ``velocity_polygon`` (``VelocityPolygon`` in Kilted and older versions from here on) type for a ``stop`` action. ``velocity_polygon`` allows the user to setup multiple polygons to cover the range of the robot's velocity limits. For example, the user can configure different polygons for rotation, moving forward, or moving backward. The Collision Monitor will check the robot's velocity against each sub polygon to determine the appropriate polygon to be used for collision checking. -In general, here are the steps to configure the Collision Monitor with ``VelocityPolygon`` type: +In general, here are the steps to configure the Collision Monitor with ``velocity_polygon`` type: -#. Add a ``VelocityPolygon`` to the ``polygons`` param list -#. Configure the ``VelocityPolygon`` +#. Add a ``velocity_polygon`` to the ``polygons`` param list +#. Configure the ``velocity_polygon`` #. Specify the ``holonomic`` property of the polygon (default is ``false``) #. Start by adding a ``stopped`` sub polygon to cover the full range of the robot's velocity limits in ``velocity_polygons`` list #. Add additional sub polygons to the front of the ``velocity_polygons`` list to cover the range of the robot's velocity limits for each type of motion (e.g. rotation, moving forward, moving backward) @@ -129,45 +194,91 @@ In this example, we will consider a **non-holonomic** robot with linear velocity Below is the example configuration using 4 sub-polygons to cover the full range of the robot's velocity limits: -.. code-block:: yaml +.. tabs:: + + .. group-tab:: Rolling - polygons: ["VelocityPolygonStop"] - VelocityPolygonStop: - type: "velocity_polygon" - action_type: "stop" - min_points: 6 - visualize: True - enabled: True - polygon_pub_topic: "velocity_polygon_stop" - velocity_polygons: ["rotation", "translation_forward", "translation_backward", "stopped"] - holonomic: false - rotation: - points: "[[0.3, 0.3], [0.3, -0.3], [-0.3, -0.3], [-0.3, 0.3]]" - linear_min: 0.0 - linear_max: 0.05 - theta_min: -1.0 - theta_max: 1.0 - translation_forward: - points: "[[0.35, 0.3], [0.35, -0.3], [-0.2, -0.3], [-0.2, 0.3]]" - linear_min: 0.0 - linear_max: 1.0 - theta_min: -1.0 - theta_max: 1.0 - translation_backward: - points: "[[0.2, 0.3], [0.2, -0.3], [-0.35, -0.3], [-0.35, 0.3]]" - linear_min: -1.0 - linear_max: 0.0 - theta_min: -1.0 - theta_max: 1.0 - # This is the last polygon to be checked, it should cover the entire range of robot's velocities - # It is used as the stopped polygon when the robot is not moving and as a fallback if the velocity - # is not covered by any of the other sub-polygons - stopped: - points: "[[0.25, 0.25], [0.25, -0.25], [-0.25, -0.25], [-0.25, 0.25]]" - linear_min: -1.0 - linear_max: 1.0 - theta_min: -1.0 - theta_max: 1.0 + .. code-block:: yaml + + polygons: ["velocity_polygon_stop"] + velocity_polygon_stop: + type: "velocity_polygon" + action_type: "stop" + min_points: 6 + visualize: True + enabled: True + polygon_pub_topic: "velocity_polygon_stop" + velocity_polygons: ["rotation", "translation_forward", "translation_backward", "stopped"] + holonomic: false + rotation: + points: "[[0.3, 0.3], [0.3, -0.3], [-0.3, -0.3], [-0.3, 0.3]]" + linear_min: 0.0 + linear_max: 0.05 + theta_min: -1.0 + theta_max: 1.0 + translation_forward: + points: "[[0.35, 0.3], [0.35, -0.3], [-0.2, -0.3], [-0.2, 0.3]]" + linear_min: 0.0 + linear_max: 1.0 + theta_min: -1.0 + theta_max: 1.0 + translation_backward: + points: "[[0.2, 0.3], [0.2, -0.3], [-0.35, -0.3], [-0.35, 0.3]]" + linear_min: -1.0 + linear_max: 0.0 + theta_min: -1.0 + theta_max: 1.0 + # This is the last polygon to be checked, it should cover the entire range of robot's velocities + # It is used as the stopped polygon when the robot is not moving and as a fallback if the velocity + # is not covered by any of the other sub-polygons + stopped: + points: "[[0.25, 0.25], [0.25, -0.25], [-0.25, -0.25], [-0.25, 0.25]]" + linear_min: -1.0 + linear_max: 1.0 + theta_min: -1.0 + theta_max: 1.0 + + .. group-tab:: Kilted and older + + .. code-block:: yaml + + polygons: ["VelocityPolygonStop"] + VelocityPolygonStop: + type: "velocity_polygon" + action_type: "stop" + min_points: 6 + visualize: True + enabled: True + polygon_pub_topic: "velocity_polygon_stop" + velocity_polygons: ["rotation", "translation_forward", "translation_backward", "stopped"] + holonomic: false + rotation: + points: "[[0.3, 0.3], [0.3, -0.3], [-0.3, -0.3], [-0.3, 0.3]]" + linear_min: 0.0 + linear_max: 0.05 + theta_min: -1.0 + theta_max: 1.0 + translation_forward: + points: "[[0.35, 0.3], [0.35, -0.3], [-0.2, -0.3], [-0.2, 0.3]]" + linear_min: 0.0 + linear_max: 1.0 + theta_min: -1.0 + theta_max: 1.0 + translation_backward: + points: "[[0.2, 0.3], [0.2, -0.3], [-0.35, -0.3], [-0.35, 0.3]]" + linear_min: -1.0 + linear_max: 0.0 + theta_min: -1.0 + theta_max: 1.0 + # This is the last polygon to be checked, it should cover the entire range of robot's velocities + # It is used as the stopped polygon when the robot is not moving and as a fallback if the velocity + # is not covered by any of the other sub-polygons + stopped: + points: "[[0.25, 0.25], [0.25, -0.25], [-0.25, -0.25], [-0.25, 0.25]]" + linear_min: -1.0 + linear_max: 1.0 + theta_min: -1.0 + theta_max: 1.0 .. note:: It is recommended to include a ``stopped`` sub polygon as the last entry in the ``velocity_polygons`` list to cover the entire range of the robot's velocity limits. In cases where the velocity is not within the scope of any sub polygons, the Collision Monitor will log a warning message and continue with the previously matched polygon. @@ -241,7 +352,7 @@ In parallel console, launch Collision Monitor node by using its launch-file: ros2 launch nav2_collision_monitor collision_monitor_node.launch.py -Since both ``PolygonStop`` and ``PolygonSlow`` polygons will have their own publishers, they could be added to visualization as shown at the picture below: +Since both ``polygon_stop`` and ``polygon_slow`` (``PolygonStop`` and ``PolygonSlow``, respectively, in Kilted and older) polygons will have their own publishers, they could be added to visualization as shown at the picture below: .. image:: images/Collision_Monitor/polygons_visualization.png :width: 800px diff --git a/tutorials/docs/using_shim_controller.rst b/tutorials/docs/using_shim_controller.rst index 10d580e3b9..51ed768de8 100644 --- a/tutorials/docs/using_shim_controller.rst +++ b/tutorials/docs/using_shim_controller.rst @@ -42,17 +42,21 @@ This controller is a *shim* because it is placed between the primary controller As such, its configuration looks very similar to that of any other plugin. In the code block below, you can see that we've added the ``RotationShimController`` as the plugin for path tracking in the controller server. You can see that we've also configured it below with its internal parameters, ``angular_dist_threshold`` through ``max_angular_accel``. -.. code-block:: yaml +.. tabs:: - controller_server: - ros__parameters: + .. group-tab:: Rolling + + .. code-block:: yaml + + controller_server: + ros__parameters: controller_frequency: 20.0 min_x_velocity_threshold: 0.001 min_y_velocity_threshold: 0.5 min_theta_velocity_threshold: 0.001 - progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + progress_checker_plugins: ["progress_checker"] goal_checker_plugins: ["goal_checker"] - controller_plugins: ["FollowPath"] + controller_plugins: ["follow_path"] progress_checker: plugin: "nav2_controller::SimpleProgressChecker" required_movement_radius: 0.5 @@ -62,7 +66,7 @@ As such, its configuration looks very similar to that of any other plugin. In th xy_goal_tolerance: 0.25 yaw_goal_tolerance: 0.25 stateful: True - FollowPath: + follow_path: plugin: "nav2_rotation_shim_controller::RotationShimController" angular_dist_threshold: 0.785 forward_sampling_distance: 0.5 @@ -70,43 +74,103 @@ As such, its configuration looks very similar to that of any other plugin. In th max_angular_accel: 3.2 simulate_ahead_time: 1.0 -The Rotation Shim Controller is very simple and only has a couple of parameters to dictate the conditions it should be enacted. + .. group-tab:: Kilted and older -- ``angular_dist_threshold``: The angular distance (in radians) apart from the robot's current heading and the approximated path heading to trigger the rotation behavior. Once the robot is within this threshold, control is handed over to the primary controller plugin. -- ``forward_sampling_distance``: The distance (in meters) away from the robot to select a point on the path to approximate the path's starting heading at. This is analogous to a "lookahead" point. -- ``rotate_to_heading_angular_vel``: The angular velocity (in rad/s) to have the robot rotate to heading by, when the behavior is enacted. -- ``max_angular_accel``: The angular acceleration (in rad/s/s) to have the robot rotate to heading by, when the behavior is enacted. -- ``simulate_ahead_time``: The Time (s) to forward project the rotation command to check for collision - -Configuring Primary Controller -============================== - -There is one more remaining parameter of the ``RotationShimController`` not mentioned above, the ``primary_controller``. This is the type of controller that your application would like to use as the primary modus operandi. It will share the same name and yaml namespace as the shim plugin. You can observe this below with the primary controller set the ``DWB`` (with the progress and goal checkers removed for brevity). + .. code-block:: yaml -.. code-block:: yaml - - controller_server: - ros__parameters: + controller_server: + ros__parameters: controller_frequency: 20.0 min_x_velocity_threshold: 0.001 min_y_velocity_threshold: 0.5 min_theta_velocity_threshold: 0.001 + progress_checker_plugins: ["progress_checker"] # progress_checker_plugin: "progress_checker" For Humble and older + goal_checker_plugins: ["goal_checker"] controller_plugins: ["FollowPath"] + progress_checker: + plugin: "nav2_controller::SimpleProgressChecker" + required_movement_radius: 0.5 + movement_time_allowance: 10.0 + goal_checker: + plugin: "nav2_controller::SimpleGoalChecker" + xy_goal_tolerance: 0.25 + yaw_goal_tolerance: 0.25 + stateful: True FollowPath: plugin: "nav2_rotation_shim_controller::RotationShimController" - primary_controller: "dwb_core::DWBLocalPlanner" angular_dist_threshold: 0.785 forward_sampling_distance: 0.5 rotate_to_heading_angular_vel: 1.8 max_angular_accel: 3.2 simulate_ahead_time: 1.0 - # DWB parameters - ... - ... - ... +The Rotation Shim Controller is very simple and only has a couple of parameters to dictate the conditions it should be enacted. + +- ``angular_dist_threshold``: The angular distance (in radians) apart from the robot's current heading and the approximated path heading to trigger the rotation behavior. Once the robot is within this threshold, control is handed over to the primary controller plugin. +- ``forward_sampling_distance``: The distance (in meters) away from the robot to select a point on the path to approximate the path's starting heading at. This is analogous to a "lookahead" point. +- ``rotate_to_heading_angular_vel``: The angular velocity (in rad/s) to have the robot rotate to heading by, when the behavior is enacted. +- ``max_angular_accel``: The angular acceleration (in rad/s/s) to have the robot rotate to heading by, when the behavior is enacted. +- ``simulate_ahead_time``: The Time (s) to forward project the rotation command to check for collision + +Configuring Primary Controller +============================== -An important note is that **within the same yaml namespace**, you may also include any ``primary_controller`` specific parameters required for a robot. Thusly, after ``max_angular_accel``, you can include any of ``DWB``'s parameters for your platform. +.. tabs:: + + .. group-tab:: Rolling + + There is one more remaining parameter of the ``RotationShimController`` not mentioned above, the ``primary_controller``. This is the type of controller that your application would like to use as the primary modus operandi. This requires an additional namespace within the parent namespace for the shim plugin. You can observe this below, where the ``primary_controller`` is placed in the ``follow_path`` namespace and uses the ``DWB`` as an example (with the progress and goal checkers removed for brevity). + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + controller_plugins: ["follow_path"] + follow_path: + plugin: "nav2_rotation_shim_controller::RotationShimController" + angular_dist_threshold: 0.785 + forward_sampling_distance: 0.5 + rotate_to_heading_angular_vel: 1.8 + max_angular_accel: 3.2 + simulate_ahead_time: 1.0 + + # DWB parameters + primary_controller: + plugin: "dwb_core::DWBLocalPlanner" + ... + + .. group-tab:: Kilted and older + + There is one more remaining parameter of the ``RotationShimController`` not mentioned above, the ``primary_controller``. This is the type of controller that your application would like to use as the primary modus operandi. It will share the same name and yaml namespace as the shim plugin. You can observe this below with the primary controller set the ``DWB`` (with the progress and goal checkers removed for brevity). + + .. code-block:: yaml + + controller_server: + ros__parameters: + controller_frequency: 20.0 + min_x_velocity_threshold: 0.001 + min_y_velocity_threshold: 0.5 + min_theta_velocity_threshold: 0.001 + controller_plugins: ["FollowPath"] + FollowPath: + plugin: "nav2_rotation_shim_controller::RotationShimController" + primary_controller: "dwb_core::DWBLocalPlanner" + angular_dist_threshold: 0.785 + forward_sampling_distance: 0.5 + rotate_to_heading_angular_vel: 1.8 + max_angular_accel: 3.2 + simulate_ahead_time: 1.0 + + # DWB parameters + ... + ... + ... + + An important note is that **within the same yaml namespace**, you may also include any ``primary_controller`` specific parameters required for a robot. Thusly, after ``simulate_ahead_time``, you can include any of ``DWB``'s parameters for your platform. Demo Execution