diff --git a/2021summerOfCode/projects/assisted_teleop.rst b/2021summerOfCode/projects/assisted_teleop.rst index 00040d284..39ff5f2bf 100644 --- a/2021summerOfCode/projects/assisted_teleop.rst +++ b/2021summerOfCode/projects/assisted_teleop.rst @@ -35,7 +35,7 @@ This will be an excellent chance to make a substantial new feature in the Nav2 s - `ROS `_ - `Gazebo Simulator `_ -- `Github ticket `_ +- `Github ticket `_ - `Navigation2 `_ **Licensing** diff --git a/2021summerOfCode/projects/create_configuration_assistant.rst b/2021summerOfCode/projects/create_configuration_assistant.rst index fbafe4b55..a0a04f84f 100644 --- a/2021summerOfCode/projects/create_configuration_assistant.rst +++ b/2021summerOfCode/projects/create_configuration_assistant.rst @@ -47,7 +47,7 @@ After the items are configured, there should be a preview to see how the paramet - `QT `_ - `Gazebo Simulator `_ -- `Original github issue page `_ +- `Original github issue page `_ **Licensing** - All contributions will be under the Apache 2.0 license. diff --git a/2021summerOfCode/projects/create_plugins.rst b/2021summerOfCode/projects/create_plugins.rst index 562b66a46..665452634 100644 --- a/2021summerOfCode/projects/create_plugins.rst +++ b/2021summerOfCode/projects/create_plugins.rst @@ -40,7 +40,7 @@ Your task will be to create a high-quality implementation of one of the followin - `ROS `_ - `Gazebo Simulator `_ -- `Github issue page `_ +- `Github issue page `_ - `Nav2 `_ **Licensing** diff --git a/2021summerOfCode/projects/dynamic.rst b/2021summerOfCode/projects/dynamic.rst index 4ead28ed6..710dcb1cc 100644 --- a/2021summerOfCode/projects/dynamic.rst +++ b/2021summerOfCode/projects/dynamic.rst @@ -35,10 +35,10 @@ If time permits, you may also work to also integrate this dynamic information in **List of relevant open source software repositories and refs** -- `Starting project `_ +- `Starting project `_ - `ROS `_ - `Gazebo Simulator `_ -- `Github ticket `_ +- `Github ticket `_ - `Navigation2 `_ - `Some related works `_ diff --git a/2021summerOfCode/projects/grid_maps.rst b/2021summerOfCode/projects/grid_maps.rst index 330875479..d74baf075 100644 --- a/2021summerOfCode/projects/grid_maps.rst +++ b/2021summerOfCode/projects/grid_maps.rst @@ -37,8 +37,8 @@ This will involve porting code from ROS 1 to ROS 2, analyzing uses of the enviro - `ROS `_ - `Gazebo Simulator `_ -- `Original github issue 1 `_ -- `Original github issue 2 `_ +- `Original github issue 1 `_ +- `Original github issue 2 `_ - `Navigation2 `_ **Licensing** diff --git a/2021summerOfCode/projects/localization.rst b/2021summerOfCode/projects/localization.rst index 8cc1f3efc..cf5e9b117 100644 --- a/2021summerOfCode/projects/localization.rst +++ b/2021summerOfCode/projects/localization.rst @@ -42,7 +42,7 @@ An optional but recommended feature of this work would be to also accept the inp - `ROS `_ - `Gazebo Simulator `_ -- `Original Github Issue `_ +- `Original Github Issue `_ - `Navigation2 `_ **Licensing** diff --git a/2021summerOfCode/projects/multithreading.rst b/2021summerOfCode/projects/multithreading.rst index 89f8d878a..dd078ae41 100644 --- a/2021summerOfCode/projects/multithreading.rst +++ b/2021summerOfCode/projects/multithreading.rst @@ -43,7 +43,7 @@ This will be an excellent chance to apply (or obtain) C++ parallel computing ski - `ROS `_ - `Gazebo Simulator `_ -- `Github ticket `_ +- `Github ticket `_ - `Navigation2 `_ **Licensing** diff --git a/2021summerOfCode/projects/navigation_rebranding.rst b/2021summerOfCode/projects/navigation_rebranding.rst index 6ae0dcc08..69da387de 100644 --- a/2021summerOfCode/projects/navigation_rebranding.rst +++ b/2021summerOfCode/projects/navigation_rebranding.rst @@ -32,7 +32,7 @@ As such, we would like to initiate a re-branding effort to help differentiate it **List of relevant open source software repositories and refs** -- `Github issue `_ +- `Github issue `_ - `Navigation2 `_ **Licensing** diff --git a/2021summerOfCode/projects/safety_node.rst b/2021summerOfCode/projects/safety_node.rst index 9a744862c..4dbd49ad2 100644 --- a/2021summerOfCode/projects/safety_node.rst +++ b/2021summerOfCode/projects/safety_node.rst @@ -40,7 +40,7 @@ This will be an excellent chance to make mobile robots and Nav2 users significan - `ROS `_ - `Gazebo Simulator `_ -- `Github ticket `_ +- `Github ticket `_ - `Navigation2 `_ **Licensing** diff --git a/2021summerOfCode/projects/semantics.rst b/2021summerOfCode/projects/semantics.rst index 7de827f95..b4201ddf2 100644 --- a/2021summerOfCode/projects/semantics.rst +++ b/2021summerOfCode/projects/semantics.rst @@ -33,8 +33,8 @@ After creating the generic representation, your project will be to create demons - `ROS `_ - `Gazebo Simulator `_ -- `Github ticket `_ -- `Github ticket2 `_ +- `Github ticket `_ +- `Github ticket2 `_ - `Navigation2 `_ **Licensing** diff --git a/2021summerOfCode/projects/spinners.rst b/2021summerOfCode/projects/spinners.rst index 5ebb2e134..e4d7ff803 100644 --- a/2021summerOfCode/projects/spinners.rst +++ b/2021summerOfCode/projects/spinners.rst @@ -36,8 +36,8 @@ More details about this project can be supplied if interested, but the tickets l - `ROS `_ - `Gazebo Simulator `_ -- `Github ticket `_ -- `Github ticket2 `_ +- `Github ticket `_ +- `Github ticket2 `_ - `Navigation2 `_ - `Some related works `_ diff --git a/2021summerOfCode/projects/testing.rst b/2021summerOfCode/projects/testing.rst index 294aece00..0d351f8fd 100644 --- a/2021summerOfCode/projects/testing.rst +++ b/2021summerOfCode/projects/testing.rst @@ -32,7 +32,7 @@ The ROS 2 Navigation Stack has had a focus on testing and reliability as a chara - `ROS `_ - `Gazebo Simulator `_ - `Navigation2 `_ -- `Navigation2 Repo System Tests `_ +- `Navigation2 Repo System Tests `_ **Licensing** - All contributions will be under the Apache 2.0 license. diff --git a/2021summerOfCode/projects/twist_n_config.rst b/2021summerOfCode/projects/twist_n_config.rst index 67f273036..7623153b6 100644 --- a/2021summerOfCode/projects/twist_n_config.rst +++ b/2021summerOfCode/projects/twist_n_config.rst @@ -41,8 +41,8 @@ In the meantime while you're waiting for PRs to be merged or blocked by reviews - `ROS `_ - `Gazebo Simulator `_ -- `Github ticket `_ -- `Github ticket2 `_ +- `Github ticket `_ +- `Github ticket2 `_ - `Navigation2 `_ - `Some related works `_ diff --git a/about/related_projects.rst b/about/related_projects.rst index 50fd6c617..32b09d847 100644 --- a/about/related_projects.rst +++ b/about/related_projects.rst @@ -27,9 +27,9 @@ This is a community maintained list of related repositories and projects to Navi | `slam_toolbox`_ | Steve Macenski | Default 2D SLAM library | +--------------------------------+------------------------+----------------------------------+ -.. _Navigation2: https://github.com/ros-planning/navigation2 -.. _docs.nav2.org: https://github.com/ros-planning/docs.nav2.org -.. _navigation2_tutorials: https://github.com/ros-planning/navigation2_tutorials -.. _navigation2_dynamic: https://github.com/ros-planning/navigation2_dynamic +.. _Navigation2: https://github.com/ros-navigation/navigation2 +.. _docs.nav2.org: https://github.com/ros-navigation/docs.nav2.org +.. _navigation2_tutorials: https://github.com/ros-navigation/navigation2_tutorials +.. _navigation2_dynamic: https://github.com/ros-navigation/navigation2_dynamic .. _robot_localization: https://github.com/cra-ros-pkg/robot_localization .. _slam_toolbox: https://github.com/SteveMacenski/slam_toolbox diff --git a/behavior_trees/overview/nav2_specific_nodes.rst b/behavior_trees/overview/nav2_specific_nodes.rst index 91a26f283..85276795b 100644 --- a/behavior_trees/overview/nav2_specific_nodes.rst +++ b/behavior_trees/overview/nav2_specific_nodes.rst @@ -9,7 +9,7 @@ Introduction To Nav2 Specific Nodes - An ``ActionNode`` in the context of BTs is not necessarily connected to an Action Server in the ROS 2 context (but often it is) There are quite a few custom Nav2 BT nodes that are provided to be used in the Nav2 specific fashion. Some commonly used Nav2 nodes will be described below. -The full list of custom BT nodes can be found in the `nav2_behavior_tree plugins folder `_. +The full list of custom BT nodes can be found in the `nav2_behavior_tree plugins folder `_. The `configuration guide <../../configuration/packages/configuring-bt-xml.html>`_ can also be quite useful. Action Nodes diff --git a/commander_api/index.rst b/commander_api/index.rst index f87c3197f..f895985e7 100644 --- a/commander_api/index.rst +++ b/commander_api/index.rst @@ -6,7 +6,7 @@ Simple Commander API Overview ******** -The goal of the Nav2 Simple (Python3) Commander is to provide a "navigation as a library" capability to Python3 users. We provide an API that handles all the ROS 2 and Action Server tasks for you such that you can focus on building an application leveraging the capabilities of Nav2 (after you've configured it to your liking with your plugins of choice). `We also provide you with demos and examples of API usage `_ to build common basic capabilities in autonomous mobile robotics in the ``nav2_simple_commander`` package. +The goal of the Nav2 Simple (Python3) Commander is to provide a "navigation as a library" capability to Python3 users. We provide an API that handles all the ROS 2 and Action Server tasks for you such that you can focus on building an application leveraging the capabilities of Nav2 (after you've configured it to your liking with your plugins of choice). `We also provide you with demos and examples of API usage `_ to build common basic capabilities in autonomous mobile robotics in the ``nav2_simple_commander`` package. A simple demonstration is shown below. Note: ``goToPose()``, ``goThroughPoses()``, ``followWaypoints()`` and similar are **non-blocking** such that you can receive and process feedback in a single-threaded application. As such while waiting for a task to be completed, the ``while not nav.isTaskComplete()`` design is necessary to poll for changes in the navigation completion, and if not complete some tasks of interest to your application (like processing feedback, doing something with the data the robot is collecting, or checking for faults). @@ -214,7 +214,7 @@ and calculate the cost of a Footprint in a given map. Examples and Demos ****************** -All of these can be found in the `package `_. +All of these can be found in the `package `_. .. image:: readme.gif :width: 800 diff --git a/conf.py b/conf.py index 8ca20157c..ada1fc0f5 100644 --- a/conf.py +++ b/conf.py @@ -199,4 +199,4 @@ breathe_default_members = ('members', 'undoc-members', 'content-only') extlinks = {'projectfile': - ('https://github.com/ros-planning/navigation2/blob/main/%s', 'filepath ')} + ('https://github.com/ros-navigation/navigation2/blob/main/%s', 'filepath ')} diff --git a/configuration/packages/bt-plugins/actions/AssistedTeleop.rst b/configuration/packages/bt-plugins/actions/AssistedTeleop.rst index 8f9effa22..8e24e4ccf 100644 --- a/configuration/packages/bt-plugins/actions/AssistedTeleop.rst +++ b/configuration/packages/bt-plugins/actions/AssistedTeleop.rst @@ -7,7 +7,7 @@ Invokes the AssistedTeleop ROS 2 action server, which filters teleop twist comma collisions. This is used in nav2 Behavior Trees as a recovery behavior or a regular behavior. The nav2_behaviors_ module implements the AssistedTeleop action server. -.. _nav2_behaviors: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors +.. _nav2_behaviors: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors Input Ports diff --git a/configuration/packages/bt-plugins/actions/BackUp.rst b/configuration/packages/bt-plugins/actions/BackUp.rst index c3b66c4da..67ea2125d 100644 --- a/configuration/packages/bt-plugins/actions/BackUp.rst +++ b/configuration/packages/bt-plugins/actions/BackUp.rst @@ -7,7 +7,7 @@ Invokes the BackUp ROS 2 action server, which causes the robot to back up by a s It performs an linear translation by a given distance. This is used in nav2 Behavior Trees as a recovery behavior. The nav2_behaviors module implements the BackUp action server. -.. nav2_behaviors_: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors +.. nav2_behaviors_: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors Input Ports *********** diff --git a/configuration/packages/bt-plugins/actions/ComputePathThroughPoses.rst b/configuration/packages/bt-plugins/actions/ComputePathThroughPoses.rst index beb384c1e..4e7527e61 100644 --- a/configuration/packages/bt-plugins/actions/ComputePathThroughPoses.rst +++ b/configuration/packages/bt-plugins/actions/ComputePathThroughPoses.rst @@ -6,7 +6,7 @@ ComputePathThroughPoses Invokes the ComputePathThroughPoses ROS 2 action server, which is implemented by the nav2_planner_ module. The server address can be remapped using the ``server_name`` input port. -.. _nav2_planner: https://github.com/ros-planning/navigation2/tree/main/nav2_planner +.. _nav2_planner: https://github.com/ros-navigation/navigation2/tree/main/nav2_planner Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/ComputePathToPose.rst b/configuration/packages/bt-plugins/actions/ComputePathToPose.rst index 7117273d1..9f5dad0a2 100644 --- a/configuration/packages/bt-plugins/actions/ComputePathToPose.rst +++ b/configuration/packages/bt-plugins/actions/ComputePathToPose.rst @@ -6,7 +6,7 @@ ComputePathToPose Invokes the ComputePathToPose ROS 2 action server, which is implemented by the nav2_planner_ module. The server address can be remapped using the ``server_name`` input port. -.. _nav2_planner: https://github.com/ros-planning/navigation2/tree/main/nav2_planner +.. _nav2_planner: https://github.com/ros-navigation/navigation2/tree/main/nav2_planner Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/ControllerSelector.rst b/configuration/packages/bt-plugins/actions/ControllerSelector.rst index a14b21b44..150633637 100644 --- a/configuration/packages/bt-plugins/actions/ControllerSelector.rst +++ b/configuration/packages/bt-plugins/actions/ControllerSelector.rst @@ -7,7 +7,7 @@ It is used to select the Controller that will be used by the Controller server. Any publisher to this topic needs to be configured with some QoS defined as ``reliable`` and ``transient local``. -.. _bt_navigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator +.. _bt_navigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/DriveOnHeading.rst b/configuration/packages/bt-plugins/actions/DriveOnHeading.rst index 0f66028f0..79c6fcc4e 100644 --- a/configuration/packages/bt-plugins/actions/DriveOnHeading.rst +++ b/configuration/packages/bt-plugins/actions/DriveOnHeading.rst @@ -6,7 +6,7 @@ DriveOnHeading Invokes the DriveOnHeading ROS 2 action server, which causes the robot to drive on the current heading by a specific displacement. It performs a linear translation by a given distance. The nav2_behaviors module implements the DriveOnHeading action server. -.. nav2_behaviors_: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors +.. nav2_behaviors_: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors Input Ports *********** diff --git a/configuration/packages/bt-plugins/actions/GoalCheckerSelector.rst b/configuration/packages/bt-plugins/actions/GoalCheckerSelector.rst index 4c0436fc4..8ac7c0a45 100644 --- a/configuration/packages/bt-plugins/actions/GoalCheckerSelector.rst +++ b/configuration/packages/bt-plugins/actions/GoalCheckerSelector.rst @@ -7,7 +7,7 @@ It is used to select the GoalChecker that will be used by the goal_checker serve Any publisher to this topic needs to be configured with some QoS defined as ``reliable`` and ``transient local``. -.. _bt_navigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator +.. _bt_navigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/NavigateThroughPoses.rst b/configuration/packages/bt-plugins/actions/NavigateThroughPoses.rst index 6adcb00ec..a45d100d3 100644 --- a/configuration/packages/bt-plugins/actions/NavigateThroughPoses.rst +++ b/configuration/packages/bt-plugins/actions/NavigateThroughPoses.rst @@ -5,7 +5,7 @@ NavigateThroughPoses Invokes the NavigateThroughPoses ROS 2 action server, which is implemented by the bt_navigator_ module. -.. _bt_navigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator +.. _bt_navigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/NavigateToPose.rst b/configuration/packages/bt-plugins/actions/NavigateToPose.rst index 1d51a7a27..b9a57f392 100644 --- a/configuration/packages/bt-plugins/actions/NavigateToPose.rst +++ b/configuration/packages/bt-plugins/actions/NavigateToPose.rst @@ -5,7 +5,7 @@ NavigateToPose Invokes the NavigateToPose ROS 2 action server, which is implemented by the bt_navigator_ module. -.. _bt_navigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator +.. _bt_navigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/PlannerSelector.rst b/configuration/packages/bt-plugins/actions/PlannerSelector.rst index 0c4501d89..0e2019609 100644 --- a/configuration/packages/bt-plugins/actions/PlannerSelector.rst +++ b/configuration/packages/bt-plugins/actions/PlannerSelector.rst @@ -7,7 +7,7 @@ It is used to select the planner that will be used by the planner server. It sub Any publisher to this topic needs to be configured with some QoS defined as ``reliable`` and ``transient local``. -.. _bt_navigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator +.. _bt_navigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/ProgressCheckerSelector.rst b/configuration/packages/bt-plugins/actions/ProgressCheckerSelector.rst index a0ba4039d..b91c4696a 100644 --- a/configuration/packages/bt-plugins/actions/ProgressCheckerSelector.rst +++ b/configuration/packages/bt-plugins/actions/ProgressCheckerSelector.rst @@ -7,7 +7,7 @@ It is used to select the ProgressChecker that will be used by the progress_check Any publisher to this topic needs to be configured with some QoS defined as ``reliable`` and ``transient local``. -.. _bt_navigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator +.. _bt_navigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/SmootherSelector.rst b/configuration/packages/bt-plugins/actions/SmootherSelector.rst index c465f0d23..9736d9816 100644 --- a/configuration/packages/bt-plugins/actions/SmootherSelector.rst +++ b/configuration/packages/bt-plugins/actions/SmootherSelector.rst @@ -7,7 +7,7 @@ It is used to select the Smoother that will be used by the Smoother server. It s Any publisher to this topic needs to be configured with some QoS defined as ``reliable`` and ``transient local``. -.. _bt_navigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator +.. _bt_navigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/Spin.rst b/configuration/packages/bt-plugins/actions/Spin.rst index ed382943a..df89009d0 100644 --- a/configuration/packages/bt-plugins/actions/Spin.rst +++ b/configuration/packages/bt-plugins/actions/Spin.rst @@ -7,7 +7,7 @@ Invokes the Spin ROS 2 action server, which is implemented by the nav2_behaviors It performs an in-place rotation by a given angle. This action is used in nav2 Behavior Trees as a recovery behavior. -.. _nav2_behaviors: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors +.. _nav2_behaviors: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors Input Ports ----------- diff --git a/configuration/packages/bt-plugins/actions/Wait.rst b/configuration/packages/bt-plugins/actions/Wait.rst index dbcbda864..824cc37d8 100644 --- a/configuration/packages/bt-plugins/actions/Wait.rst +++ b/configuration/packages/bt-plugins/actions/Wait.rst @@ -6,7 +6,7 @@ Wait Invokes the Wait ROS 2 action server, which is implemented by the nav2_behaviors_ module. This action is used in nav2 Behavior Trees as a recovery behavior. -.. _nav2_behaviors: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors +.. _nav2_behaviors: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors Input Ports ----------- diff --git a/configuration/packages/configuring-amcl.rst b/configuration/packages/configuring-amcl.rst index c4a1fa782..e43e47f17 100644 --- a/configuration/packages/configuring-amcl.rst +++ b/configuration/packages/configuring-amcl.rst @@ -5,7 +5,7 @@ AMCL Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_amcl +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_amcl AMCL implements the server for taking a static map and localizing the robot within it using an Adaptive Monte-Carlo Localizer. diff --git a/configuration/packages/configuring-behavior-server.rst b/configuration/packages/configuring-behavior-server.rst index 7a6852da2..80cac712a 100644 --- a/configuration/packages/configuring-behavior-server.rst +++ b/configuration/packages/configuring-behavior-server.rst @@ -5,7 +5,7 @@ Behavior Server Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors The Behavior Server implements the server for handling various behavior, such as recoveries and docking, requests and hosting a vector of plugins implementing various C++ behaviors. It is also possible to implement independent behavior servers for each custom behavior, but this server will allow multiple behaviors to share resources such as costmaps and TF buffers to lower incremental costs for new behaviors. diff --git a/configuration/packages/configuring-bt-navigator.rst b/configuration/packages/configuring-bt-navigator.rst index 7f50fbcea..f60b5fe79 100644 --- a/configuration/packages/configuring-bt-navigator.rst +++ b/configuration/packages/configuring-bt-navigator.rst @@ -5,7 +5,7 @@ Behavior-Tree Navigator Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator The BT Navigator (Behavior Tree Navigator) module implements the NavigateToPose, NavigateThroughPoses, and other task interfaces. It is a Behavior Tree-based implementation of navigation that is intended to allow for flexibility diff --git a/configuration/packages/configuring-bt-xml.rst b/configuration/packages/configuring-bt-xml.rst index fd6213695..4f4982d5b 100644 --- a/configuration/packages/configuring-bt-xml.rst +++ b/configuration/packages/configuring-bt-xml.rst @@ -5,7 +5,7 @@ Behavior Tree XML Nodes The nav2_behavior_tree_ package provides several navigation-specific nodes that are pre-registered and can be included in Behavior Trees. -.. _nav2_behavior_tree: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree +.. _nav2_behavior_tree: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree Check this introduction_ to learn how behavior trees work and the difference between actions, conditions, controls and decorators. diff --git a/configuration/packages/configuring-collision-monitor.rst b/configuration/packages/configuring-collision-monitor.rst index 3caed6033..f943297f9 100644 --- a/configuration/packages/configuring-collision-monitor.rst +++ b/configuration/packages/configuring-collision-monitor.rst @@ -5,7 +5,7 @@ Collision Monitor Source code and ``README`` with design, explanations, and metrics can be found on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_collision_monitor +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_collision_monitor The ``nav2_collision_monitor`` package contains nodes providing an additional level of robot safety, namely the Collision Monitor and the Collision Detector. The Collision Monitor is a node providing an additional level of robot safety. It performs several collision avoidance related tasks using incoming data from the sensors, bypassing the costmap and trajectory planners, to monitor for and prevent potential collisions at the emergency-stop level. diff --git a/configuration/packages/configuring-constrained-smoother.rst b/configuration/packages/configuring-constrained-smoother.rst index 941b67dfb..48f732f7a 100644 --- a/configuration/packages/configuring-constrained-smoother.rst +++ b/configuration/packages/configuring-constrained-smoother.rst @@ -5,7 +5,7 @@ Constrained smoother Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_constrained_smoother +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_constrained_smoother .. _`RoboTech Vision`: https://robotechvision.com/ diff --git a/configuration/packages/configuring-controller-server.rst b/configuration/packages/configuring-controller-server.rst index f4fa0d4fc..f3f0b780e 100644 --- a/configuration/packages/configuring-controller-server.rst +++ b/configuration/packages/configuring-controller-server.rst @@ -5,7 +5,7 @@ Controller Server Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_controller +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_controller The Controller Server implements the server for handling the controller requests for the stack and host a map of plugin implementations. It will take in path and plugin names for controller, progress checker and goal checker to use and call the appropriate plugins. @@ -192,7 +192,7 @@ Parameters ============== ============================= 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 `_. + 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: diff --git a/configuration/packages/configuring-costmaps.rst b/configuration/packages/configuring-costmaps.rst index cd87d5fbc..1576ce620 100644 --- a/configuration/packages/configuring-costmaps.rst +++ b/configuration/packages/configuring-costmaps.rst @@ -5,7 +5,7 @@ Costmap 2D Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d The Costmap 2D package implements a 2D grid-based costmap for environmental representations and a number of sensor processing plugins (AI outputs, depth sensor obstacle buffering, semantic information, etc). It is used in the planner and controller servers for creating the space to check for collisions or higher cost areas to negotiate around. diff --git a/configuration/packages/configuring-dwb-controller.rst b/configuration/packages/configuring-dwb-controller.rst index 2e0c9dc81..b3fb7a896 100644 --- a/configuration/packages/configuring-dwb-controller.rst +++ b/configuration/packages/configuring-dwb-controller.rst @@ -5,7 +5,7 @@ DWB Controller Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_dwb_controller +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_dwb_controller The DWB controller is the default controller. It is a fork of `David Lu's controller `_ diff --git a/configuration/packages/configuring-graceful-motion-controller.rst b/configuration/packages/configuring-graceful-motion-controller.rst index 0e7d74552..e6b1f56d3 100644 --- a/configuration/packages/configuring-graceful-motion-controller.rst +++ b/configuration/packages/configuring-graceful-motion-controller.rst @@ -5,7 +5,7 @@ Graceful Controller Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_graceful_controller +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_graceful_controller The graceful controller implements a controller based on the works of Jong Jin Park and Benjamin Kuipers in "A Smooth Control Law for Graceful Motion of Differential Wheeled Mobile Robots in 2D Environment" (ICRA 2011). In this implementation, a `motion_target` is set at a distance away from the robot that is exponentially stable to generate a smooth trajectory for the robot to follow. diff --git a/configuration/packages/configuring-lifecycle.rst b/configuration/packages/configuring-lifecycle.rst index 42049e977..23afd5b6f 100644 --- a/configuration/packages/configuring-lifecycle.rst +++ b/configuration/packages/configuring-lifecycle.rst @@ -5,7 +5,7 @@ Lifecycle Manager Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_lifecycle_manager +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_lifecycle_manager The Lifecycle Manager module implements the method for handling the lifecycle transition states for the stack in a deterministic way. It will take in a set of ordered nodes to transition one-by-one into the configuration and activate states to run the stack. diff --git a/configuration/packages/configuring-map-server.rst b/configuration/packages/configuring-map-server.rst index 3ee507da2..fec595bc5 100644 --- a/configuration/packages/configuring-map-server.rst +++ b/configuration/packages/configuring-map-server.rst @@ -5,7 +5,7 @@ Map Server / Saver Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_map_server +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_map_server The Map Server implements the server for handling the map load requests for the stack and host a map topic. It also implements a map saver server which will run in the background and save maps based on service requests. There exists a map saver CLI similar to ROS 1 as well for a single map save. diff --git a/configuration/packages/configuring-mppic.rst b/configuration/packages/configuring-mppic.rst index 48fad3980..2e405ce18 100644 --- a/configuration/packages/configuring-mppic.rst +++ b/configuration/packages/configuring-mppic.rst @@ -5,7 +5,7 @@ Model Predictive Path Integral Controller Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_mppi_controller +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_mppi_controller .. image:: images/mppi_demo.gif diff --git a/configuration/packages/configuring-navfn.rst b/configuration/packages/configuring-navfn.rst index 517fad4e4..3835f9b7d 100644 --- a/configuration/packages/configuring-navfn.rst +++ b/configuration/packages/configuring-navfn.rst @@ -5,7 +5,7 @@ NavFn Planner Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_navfn_planner +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_navfn_planner The Navfn Planner plugin implements a wavefront Dijkstra or A* expanded holonomic planner. diff --git a/configuration/packages/configuring-planner-server.rst b/configuration/packages/configuring-planner-server.rst index 5059dfece..81042ed30 100644 --- a/configuration/packages/configuring-planner-server.rst +++ b/configuration/packages/configuring-planner-server.rst @@ -5,7 +5,7 @@ Planner Server Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_planner +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_planner The Planner Server implements the server for handling the planner requests for the stack and host a map of plugin implementations. It will take in a goal and a planner plugin name to use and call the appropriate plugin to compute a path to the goal. diff --git a/configuration/packages/configuring-regulated-pp.rst b/configuration/packages/configuring-regulated-pp.rst index ceb45cdda..38a726997 100644 --- a/configuration/packages/configuring-regulated-pp.rst +++ b/configuration/packages/configuring-regulated-pp.rst @@ -5,7 +5,7 @@ Regulated Pure Pursuit Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_regulated_pure_pursuit_controller +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_regulated_pure_pursuit_controller The Regulated Pure Pursuit controller implements a variation on the Pure Pursuit controller that specifically targeting service / industrial robot needs. It regulates the linear velocities by curvature of the path to help reduce overshoot at high speeds around blind corners allowing operations to be much more safe. diff --git a/configuration/packages/configuring-rotation-shim-controller.rst b/configuration/packages/configuring-rotation-shim-controller.rst index 3b70e7854..3186199aa 100644 --- a/configuration/packages/configuring-rotation-shim-controller.rst +++ b/configuration/packages/configuring-rotation-shim-controller.rst @@ -5,7 +5,7 @@ Rotation Shim Controller Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_rotation_shim_controller +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_rotation_shim_controller The ``nav2_rotation_shim_controller`` will check the rough heading difference with respect to the robot and a newly received path. If within a threshold, it will pass the request onto the ``primary_controller`` to execute the task. If it is outside of the threshold, this controller will rotate the robot in place towards that path heading. Once it is within the tolerance, it will then pass off control-execution from this rotation shim controller onto the primary controller plugin. At this point, the robot's main plugin will take control for a smooth hand off into the task. diff --git a/configuration/packages/configuring-savitzky-golay-smoother.rst b/configuration/packages/configuring-savitzky-golay-smoother.rst index a09d6f081..a45880081 100644 --- a/configuration/packages/configuring-savitzky-golay-smoother.rst +++ b/configuration/packages/configuring-savitzky-golay-smoother.rst @@ -5,7 +5,7 @@ Savitzky-Golay Smoother Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_smoother +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_smoother The Savitzky-Golay Smoother is a Smoother Server plugin that will take in an input path and smooth it using a simple and fast smoothing technique based on `Savitzky Golay Filters `_. It uses a digital signal processing technique designed to reduce noise distorting a reference signal, in this case, a path. diff --git a/configuration/packages/configuring-simple-smoother.rst b/configuration/packages/configuring-simple-smoother.rst index 0acf6584f..41f926ab9 100644 --- a/configuration/packages/configuring-simple-smoother.rst +++ b/configuration/packages/configuring-simple-smoother.rst @@ -5,7 +5,7 @@ Simple Smoother Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_smoother +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_smoother The Simple Smoother is a Smoother Server plugin that will take in an input path and smooth it using a simple and fast smoothing technique. It weights the initial path points and the smoothed path points to create a balanced result where the path retains its high level characteristics but reduces oscillations or jagged features. diff --git a/configuration/packages/configuring-smac-planner.rst b/configuration/packages/configuring-smac-planner.rst index 853ebcf77..136d7cb3b 100644 --- a/configuration/packages/configuring-smac-planner.rst +++ b/configuration/packages/configuring-smac-planner.rst @@ -5,7 +5,7 @@ Smac Planner Source code and ``README`` with design, explanations, and metrics can be found on Github_. A brief explanation can be found below, but the ``README`` contains the most detailed overview of the framework and planner implementations. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_smac_planner +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_smac_planner The Smac Planner plugin implements three A* based planning algorithms: 2D A*, Hybrid-A*, and State Lattice path planners. It is important to know that in June 2021 and December 2021, the package received a several **major** updates both improving path quality and run-times by 2-3x. diff --git a/configuration/packages/configuring-smoother-server.rst b/configuration/packages/configuring-smoother-server.rst index ac7477de1..532dc41a6 100644 --- a/configuration/packages/configuring-smoother-server.rst +++ b/configuration/packages/configuring-smoother-server.rst @@ -5,7 +5,7 @@ Smoother Server Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_smoother +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_smoother The Smoother Server implements the server for handling smooth path requests and hosting a vector of plugins implementing various C++ smoothers. The server exposes an action interface for smoothing with multiple smoothers that share resources such as costmaps and TF buffers. diff --git a/configuration/packages/configuring-thetastar.rst b/configuration/packages/configuring-thetastar.rst index 1e8405fbe..5bf01797d 100644 --- a/configuration/packages/configuring-thetastar.rst +++ b/configuration/packages/configuring-thetastar.rst @@ -5,7 +5,7 @@ Theta Star Planner .. The source code and README with design, explanations, metrics and usage tips can be found on Github_. -.. .. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_theta_star_planner +.. .. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_theta_star_planner Theta Star Planner implements the Theta* path planner meant to plan any-angled line-segment focused paths using A*. diff --git a/configuration/packages/configuring-velocity-smoother.rst b/configuration/packages/configuring-velocity-smoother.rst index 536613bc2..36a9ab3aa 100644 --- a/configuration/packages/configuring-velocity-smoother.rst +++ b/configuration/packages/configuring-velocity-smoother.rst @@ -5,7 +5,7 @@ Velocity Smoother Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_velocity_smoother +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_velocity_smoother The ``nav2_velocity_smoother`` is a package containing a lifecycle-component node for smoothing velocities sent by Nav2 to robot controllers. The aim of this package is to implement velocity, acceleration, and deadband smoothing from Nav2 to reduce wear-and-tear on robot motors and hardware controllers by smoothing out the accelerations/jerky movements that might be present with some local trajectory planners' control efforts. diff --git a/configuration/packages/configuring-waypoint-follower.rst b/configuration/packages/configuring-waypoint-follower.rst index d9a856782..ac113d764 100644 --- a/configuration/packages/configuring-waypoint-follower.rst +++ b/configuration/packages/configuring-waypoint-follower.rst @@ -5,7 +5,7 @@ Waypoint Follower Source code on Github_. -.. _Github: https://github.com/ros-planning/navigation2/tree/main/nav2_waypoint_follower +.. _Github: https://github.com/ros-navigation/navigation2/tree/main/nav2_waypoint_follower The Waypoint Follower module implements a way of doing waypoint following using the NavigateToPose action server. It will take in a set of ordered waypoints to follow and then try to navigate to them in order. diff --git a/configuration/packages/costmap-plugins/binary_filter.rst b/configuration/packages/costmap-plugins/binary_filter.rst index 5deecf3c5..38b36a731 100644 --- a/configuration/packages/costmap-plugins/binary_filter.rst +++ b/configuration/packages/costmap-plugins/binary_filter.rst @@ -32,7 +32,7 @@ Filter space value is being calculated as: ``Fv = base + multiplier * mask_value ====== ======= Description - Name of the incoming `CostmapFilterInfo `_ topic having filter-related information. Published by Costmap Filter Info Server along with filter mask topic. For more details about Map and Costmap Filter Info servers configuration please refer to the :ref:`configuring_map_server` configuration page. + Name of the incoming `CostmapFilterInfo `_ topic having filter-related information. Published by Costmap Filter Info Server along with filter mask topic. For more details about Map and Costmap Filter Info servers configuration please refer to the :ref:`configuring_map_server` configuration page. :````.transform_tolerance: diff --git a/configuration/packages/costmap-plugins/keepout_filter.rst b/configuration/packages/costmap-plugins/keepout_filter.rst index 4b95ac0eb..eb6746ec3 100644 --- a/configuration/packages/costmap-plugins/keepout_filter.rst +++ b/configuration/packages/costmap-plugins/keepout_filter.rst @@ -29,7 +29,7 @@ Note: As Costmap Filters does not have the inflation layer applied to them (sinc ====== ======= Description - Name of the incoming `CostmapFilterInfo `_ topic having filter-related information. Published by Costmap Filter Info Server along with filter mask topic. For more details about Map and Costmap Filter Info servers configuration please refer to the :ref:`configuring_map_server` configuration page. + Name of the incoming `CostmapFilterInfo `_ topic having filter-related information. Published by Costmap Filter Info Server along with filter mask topic. For more details about Map and Costmap Filter Info servers configuration please refer to the :ref:`configuring_map_server` configuration page. :````.transform_tolerance: diff --git a/configuration/packages/costmap-plugins/speed_filter.rst b/configuration/packages/costmap-plugins/speed_filter.rst index f23978de7..a3b6383ef 100644 --- a/configuration/packages/costmap-plugins/speed_filter.rst +++ b/configuration/packages/costmap-plugins/speed_filter.rst @@ -35,7 +35,7 @@ Speed Filter - is a Costmap Filter that restricting maximum velocity of robot. T ====== ======= Description - Name of the incoming `CostmapFilterInfo `_ topic having filter-related information. Published by Costmap Filter Info Server along with filter mask topic. For more details about Map and Costmap Filter Info servers configuration please refer to the :ref:`configuring_map_server` configuration page. + Name of the incoming `CostmapFilterInfo `_ topic having filter-related information. Published by Costmap Filter Info Server along with filter mask topic. For more details about Map and Costmap Filter Info servers configuration please refer to the :ref:`configuring_map_server` configuration page. :````.speed_limit_topic: @@ -46,7 +46,7 @@ Speed Filter - is a Costmap Filter that restricting maximum velocity of robot. T ====== ============= Description - Topic to publish speed limit to. The `messages `_ have the following fields' meaning: + Topic to publish speed limit to. The `messages `_ have the following fields' meaning: - ``percentage``: speed limit is expressed in percentage if ``true`` or in absolute values in ``false`` case. This parameter is set depending on ``type`` field of ``CostmapFilterInfo`` message. diff --git a/development_guides/build_docs/build_troubleshooting_guide.rst b/development_guides/build_docs/build_troubleshooting_guide.rst index 0e143d3bb..c4f72c914 100644 --- a/development_guides/build_docs/build_troubleshooting_guide.rst +++ b/development_guides/build_docs/build_troubleshooting_guide.rst @@ -21,13 +21,13 @@ Common Nav2 Dependencies Build Failures * Make sure you've activated the lifecycle nodes if you're not seeing transforms or servers running. -* Search `GitHub Issues `_ +* Search `GitHub Issues `_ * Make sure you're using the correct branch for your distribution. There is no cross support from branch for ``DistroA`` in ``DistroB``. The main development branch uses the rolling distribution. -Still can't solve it? Let us know about your issue. `Open a ticket `_. +Still can't solve it? Let us know about your issue. `Open a ticket `_. Reporting Issue =============== -- If you run into any issues when building Navigation2, you can use the search tool in the issues tab on `GitHub `_ and always feel free to `open a ticket `_. +- If you run into any issues when building Navigation2, you can use the search tool in the issues tab on `GitHub `_ and always feel free to `open a ticket `_. diff --git a/development_guides/build_docs/index.rst b/development_guides/build_docs/index.rst index 39719f4db..2f3859b49 100644 --- a/development_guides/build_docs/index.rst +++ b/development_guides/build_docs/index.rst @@ -59,7 +59,7 @@ Once your environment is setup, clone the repo, install all dependencies, and bu source /opt/ros//setup.bash mkdir -p ~/nav2_ws/src && cd ~/nav2_ws - git clone https://github.com/ros-planning/navigation2.git --branch $ROS_DISTRO ./src/navigation2 + git clone https://github.com/ros-navigation/navigation2.git --branch $ROS_DISTRO ./src/navigation2 rosdep install -y \ --from-paths ./src \ --ignore-src @@ -69,7 +69,7 @@ Once your environment is setup, clone the repo, install all dependencies, and bu You can then ``source ~/nav2_ws/install/setup.bash`` to get ready for demonstrations! .. hint:: - For more examples on building Nav2 from released distribution binaries, checkout `distro.Dockerfile `_. + For more examples on building Nav2 from released distribution binaries, checkout `distro.Dockerfile `_. .. rst-class:: content-collapse @@ -90,7 +90,7 @@ Once your environment is setup, clone the repo and build the workspace: source /install/setup.bash mkdir -p ~/nav2_ws/src && cd ~/nav2_ws - git clone https://github.com/ros-planning/navigation2.git --branch main ./src/navigation2 + git clone https://github.com/ros-navigation/navigation2.git --branch main ./src/navigation2 rosdep install -r -y \ --from-paths ./src \ --ignore-src @@ -101,7 +101,7 @@ You can then ``source ~/nav2_ws/install/setup.bash`` to get ready for demonstrat to ignore the rosdep error of from the missing ``slam_toolbox`` key. .. hint:: - For more examples on building Nav2 from rolling development source, checkout `source.Dockerfile `_. + For more examples on building Nav2 from rolling development source, checkout `source.Dockerfile `_. .. rst-class:: content-collapse @@ -121,14 +121,14 @@ Once your system is setup, you can build the Nav2 Dockerfile from the root of th .. code:: bash export ROS_DISTRO=rolling - git clone https://github.com/ros-planning/navigation2.git --branch main + git clone https://github.com/ros-navigation/navigation2.git --branch main docker build --tag navigation2:$ROS_DISTRO \ --build-arg FROM_IMAGE=ros:$ROS_DISTRO \ --build-arg OVERLAY_MIXINS="release ccache lld" \ - --cache-from ghcr.io/ros-planning/navigation2:main \ + --cache-from ghcr.io/ros-navigation/navigation2:main \ ./navigation2 -The `docker build `_ command above creates a tagged image using the `Dockerfile` from the context specified using the path to the repo, where build-time variables are set using additional arguments, e.g. passing a set of `colcon mixins `_ to configure the workspace build. Check the ``ARG`` directives in the `Dockerfile` to discover all build-time variables available. The command also specifies an `external cache source `_ to pull the latest cached image from Nav2's `Container Registry `_ to speed up the build process. +The `docker build `_ command above creates a tagged image using the `Dockerfile` from the context specified using the path to the repo, where build-time variables are set using additional arguments, e.g. passing a set of `colcon mixins `_ to configure the workspace build. Check the ``ARG`` directives in the `Dockerfile` to discover all build-time variables available. The command also specifies an `external cache source `_ to pull the latest cached image from Nav2's `Container Registry `_ to speed up the build process. .. tip:: The images cached from above are used for Nav2 CI, but can also be used with Nav2 :ref:`devcontainers`! diff --git a/migration/Eloquent.rst b/migration/Eloquent.rst index f22b8085e..f07bf336b 100644 --- a/migration/Eloquent.rst +++ b/migration/Eloquent.rst @@ -18,7 +18,7 @@ It also reduces the redundant code in ``nav2_bringup``. The lifecycle manager also now contains ``Bond`` connections to each lifecycle server. This means that if a server crashes or exits, the lifecycle manager will be constantly checking and transition down its lifecycle nodes for safety. -This acts as a watchdog during run-time to complement the lifecycle manager's transitioning up and down from active states. See `this PR for details `_. +This acts as a watchdog during run-time to complement the lifecycle manager's transitioning up and down from active states. See `this PR for details `_. A fix to the BT navigator was added to remove a rare issue where it may crash due to asynchronous issues. As a result, a behavior tree is created for each navigation request rather than resetting an existing tree. @@ -69,7 +69,7 @@ An example: ``controller_server`` defines the parameter ``controller_plugins`` w Each plugin will load the parameters in their namespace, e.g. ``FollowPath.max_vel_x``, rather than globally in the server namespace. This will allow multiple plugins of the same type with different parameters and reduce conflicting parameter names. -DWB Contains new parameters as an update relative to the ROS 1 updates, `see here for more information `_. +DWB Contains new parameters as an update relative to the ROS 1 updates, `see here for more information `_. Additionally, the controller and planner interfaces were updated to include a ``std::string name`` parameter on initialization. This was added to the interfaces to allow the plugins to know the namespace it should load its parameters in. E.g. for a controller to find the parameter ``FollowPath.max_vel_x``, it must be given its name, ``FollowPath`` to get this parameter. @@ -86,16 +86,16 @@ These plugins are set as default in the ``nav2_bt_navigator`` but may be overrid Original GitHub tickets: -- `DistanceController `_ -- `SpeedController `_ -- `GoalUpdatedCondition `_ -- `DistanceTraveledCondition `_ -- `TimeExpiredCondition `_ -- `UpdateGoal `_ -- `TruncatePath `_ -- `IsBatteryLowCondition `_ -- `ProgressChecker `_ -- `GoalChecker `_ +- `DistanceController `_ +- `SpeedController `_ +- `GoalUpdatedCondition `_ +- `DistanceTraveledCondition `_ +- `TimeExpiredCondition `_ +- `UpdateGoal `_ +- `TruncatePath `_ +- `IsBatteryLowCondition `_ +- `ProgressChecker `_ +- `GoalChecker `_ Map Server Re-Work ****************** @@ -110,7 +110,7 @@ Map Server now has new ``map_io`` dynamic library. All functions saving/loading ``map_loader`` was completely removed from ``nav2_util``. All its functionality already present in ``map_io``. Please use it in your code instead. -Please refer to the `original GitHub ticket `_ and `Map Server README `_ for more information. +Please refer to the `original GitHub ticket `_ and `Map Server README `_ for more information. New Particle Filter Messages @@ -122,7 +122,7 @@ New particle filter messages for particle clouds were added to include the parti ``AMCL`` now publishes its particle cloud as a ``nav2_msgs/ParticleCloud`` instead of a ``geometry_msgs/PoseArray``. -`See here for more information. `_ +`See here for more information. `_ Selection of Behavior Tree in each navigation action @@ -130,7 +130,7 @@ Selection of Behavior Tree in each navigation action The ``NavigateToPose`` action allows now to select in the action request the behavior tree to be used by ``bt_navigator`` for carrying out the navigation action through the ``string behavior_tree`` field. This field indicates the absolute path of the xml file that will be used to use to carry out the action. If no file is specified, leaving this field empty, the default behavior tree specified in the ``default_bt_xml_filename parameter`` will be used. -This functionality has been discussed in `the ticket #1780 `_, and carried out in `the pull request #1784 `_. +This functionality has been discussed in `the ticket #1780 `_, and carried out in `the pull request #1784 `_. FollowPoint Capability @@ -138,7 +138,7 @@ FollowPoint Capability A new behavior tree ``followpoint.xml`` has added. This behavior tree makes a robot follow a dynamically generated point, keeping a certain distance from the target. This can be used for moving target following maneuvers. -This functionality has been discussed in `the ticket #1660 `_, and carried out in `the pull request #1859 `_. +This functionality has been discussed in `the ticket #1660 `_, and carried out in `the pull request #1859 `_. New Costmap Layer ***************** diff --git a/migration/Foxy.rst b/migration/Foxy.rst index 1fb9302b0..169b822c8 100644 --- a/migration/Foxy.rst +++ b/migration/Foxy.rst @@ -61,7 +61,7 @@ In both cases negative values are silently inverted. Nav2 Controllers and Goal Checker Plugin Interface Changes ********************************************************** -As of `this PR 2247 `_, the ``controller`` plugins will now be given a pointer to the current goal checker in use of the navigation task in ``computeAndPublishVelocity()``. This is geared to enabling controllers to have access to predictive checks for goal completion as well as access to the state information of the goal checker plugin. +As of `this PR 2247 `_, the ``controller`` plugins will now be given a pointer to the current goal checker in use of the navigation task in ``computeAndPublishVelocity()``. This is geared to enabling controllers to have access to predictive checks for goal completion as well as access to the state information of the goal checker plugin. The ``goal_checker`` plugins also have the change of including a ``getTolerances()`` method. This method allows a goal checker holder to access the tolerance information of the goal checker to consider at the goal. Each field of the ``pose`` and ``velocity`` represents the maximum allowable error in each dimension for a goal to be considered completed. In the case of a translational tolerance (combined X and Y components), each the X and Y will be populated with the tolerance value because it is the **maximum** tolerance in the dimension (assuming the other has no error). If the goal checker does not contain any tolerances for a dimension, the ``numeric_limits lowest()`` value is utilized in its place. @@ -132,10 +132,10 @@ Loading a plugin of this type is done through ``nav2_bringup/params/nav2_param.y Original GitHub tickets: -- `WaypointTaskExecutor `_ -- `WaitAtWaypoint `_ -- `PhotoAtWaypoint `_ -- `InputAtWaypoint `_ +- `WaypointTaskExecutor `_ +- `WaitAtWaypoint `_ +- `PhotoAtWaypoint `_ +- `InputAtWaypoint `_ Costmap Filters *************** @@ -146,12 +146,12 @@ Architecturally, costmap filters consists from ``CostmapFilter`` class which is - ``KeepoutFilter``: keep-out/safety zones filter plugin. - ``SpeedFilter``: slow/speed-restricted areas filter. -- Preferred lanes in industries. This plugin is covered by ``KeepoutFilter`` (see discussion in `corresponding PR `_ for more details). +- Preferred lanes in industries. This plugin is covered by ``KeepoutFilter`` (see discussion in `corresponding PR `_ for more details). -Each costmap filter subscribes to filter info topic (publishing by `Costmap Filter Info Publisher Server `_) having all necessary information for loaded costmap filter and filter mask topic. -``SpeedFilter`` additionally publishes maximum speed restricting `messages `_ targeted for a Controller to enforce robot won't exceed given limit. +Each costmap filter subscribes to filter info topic (publishing by `Costmap Filter Info Publisher Server `_) having all necessary information for loaded costmap filter and filter mask topic. +``SpeedFilter`` additionally publishes maximum speed restricting `messages `_ targeted for a Controller to enforce robot won't exceed given limit. -High-level design of this concept could be found `here `_. The functionality of costmap filters is being discussed in `the ticket #1263 `_ and carried out by `PR #1882 `_. The following tutorials: :ref:`navigation2_with_keepout_filter` and :ref:`navigation2_with_speed_filter` will help to easily get involved with ``KeepoutFilter`` and ``SpeedFilter`` functionalities. +High-level design of this concept could be found `here `_. The functionality of costmap filters is being discussed in `the ticket #1263 `_ and carried out by `PR #1882 `_. The following tutorials: :ref:`navigation2_with_keepout_filter` and :ref:`navigation2_with_speed_filter` will help to easily get involved with ``KeepoutFilter`` and ``SpeedFilter`` functionalities. SmacPlanner *********** @@ -207,7 +207,7 @@ To follow the SI units outlined in REP-103 to the "T" nodes below were modified Ray Tracing Parameters ********************** -Raytracing functionality was modified to include a minimum range parameter from which ray tracing starts to clear obstacles to avoid incorrectly clearing obstacles too close to the robot. This issue was mentioned in `ROS Answers `_. An existing parameter ``raytrace_range`` was renamed to ``raytrace_max_range`` to reflect the functionality it affects. The renamed parameters and the plugins that they belong to are mentioned below. The changes were introduced in this `pull request `_. +Raytracing functionality was modified to include a minimum range parameter from which ray tracing starts to clear obstacles to avoid incorrectly clearing obstacles too close to the robot. This issue was mentioned in `ROS Answers `_. An existing parameter ``raytrace_range`` was renamed to ``raytrace_max_range`` to reflect the functionality it affects. The renamed parameters and the plugins that they belong to are mentioned below. The changes were introduced in this `pull request `_. - obstacle_layer plugin @@ -239,19 +239,19 @@ Obstacle marking was modified to include a minimum range parameter from which ob Recovery Action Changes *********************** -The recovery actions, ``Spin`` and ``BackUp`` were modified to correctly return ``FAILURE`` if the recovery action is aborted due to a potential collision. Previously, these actions incorrectly always returned ``SUCCESS``. Changes to this resulted in downstream action clients, such as the default behavior tree. The changes were introduced in this `pull request 1855 `_. +The recovery actions, ``Spin`` and ``BackUp`` were modified to correctly return ``FAILURE`` if the recovery action is aborted due to a potential collision. Previously, these actions incorrectly always returned ``SUCCESS``. Changes to this resulted in downstream action clients, such as the default behavior tree. The changes were introduced in this `pull request 1855 `_. Default Behavior Tree Changes ***************************** -The default behavior tree (BT) ``navigate_w_replanning_and_recovery.xml`` has been updated to allow for replanning in between recoveries. The changes were introduced in this `PR 1855 `_. Additionally, an alternative BT ``navigate_w_replanning_and_round_robin_recovery.xml`` was removed due to similarity with the updated default BT. +The default behavior tree (BT) ``navigate_w_replanning_and_recovery.xml`` has been updated to allow for replanning in between recoveries. The changes were introduced in this `PR 1855 `_. Additionally, an alternative BT ``navigate_w_replanning_and_round_robin_recovery.xml`` was removed due to similarity with the updated default BT. NavFn Planner Parameters ************************ -The NavFn Planner has now its 3 parameters reconfigurable at runtime (``tolerance``, ``use_astar`` and ``allow_unknown``). The changes were introduced in this `pull request 2181 `_. +The NavFn Planner has now its 3 parameters reconfigurable at runtime (``tolerance``, ``use_astar`` and ``allow_unknown``). The changes were introduced in this `pull request 2181 `_. New ClearCostmapExceptRegion and ClearCostmapAroundRobot BT-nodes ***************************************************************** -The ClearEntireCostmap action node was already implemented but the ClearCostmapExceptRegion and ClearCostmapAroundRobot BT nodes calling the sister services ``(local_or_global)_costmap/clear_except_(local_or_global)_costmap`` and ``clear_around_(local_or_global)_costmap`` of Costmap 2D were missing, they are now implemented in a similar way. They both expose a ``reset_distance`` input port. See :ref:`bt_clear_costmap_except_region_action` and :ref:`bt_clear_entire_costmap_around_robot_action` for more. The changes were introduced in this `pull request 2204 `_. +The ClearEntireCostmap action node was already implemented but the ClearCostmapExceptRegion and ClearCostmapAroundRobot BT nodes calling the sister services ``(local_or_global)_costmap/clear_except_(local_or_global)_costmap`` and ``clear_around_(local_or_global)_costmap`` of Costmap 2D were missing, they are now implemented in a similar way. They both expose a ``reset_distance`` input port. See :ref:`bt_clear_costmap_except_region_action` and :ref:`bt_clear_entire_costmap_around_robot_action` for more. The changes were introduced in this `pull request 2204 `_. New Behavior Tree Nodes *********************** @@ -261,13 +261,13 @@ These plugins are set as default in the ``nav2_bt_navigator`` but may be overrid Original GitHub tickets: -- `SingleTrigger `_ -- `PlannerSelector `_ -- `ControllerSelector `_ -- `GoalCheckerSelector `_ -- `NavigateThroughPoses `_ -- `RemovePassedGoals `_ -- `ComputePathThroughPoses `_ +- `SingleTrigger `_ +- `PlannerSelector `_ +- `ControllerSelector `_ +- `GoalCheckerSelector `_ +- `NavigateThroughPoses `_ +- `RemovePassedGoals `_ +- `ComputePathThroughPoses `_ Additionally, behavior tree nodes were modified to contain their own local executors to spin for actions, topics, services, etc to ensure that each behavior tree node is independent of each other (e.g. spinning in one BT node doesn't trigger a callback in another). @@ -279,25 +279,25 @@ Due to deprecation of `sensor_msgs/PointCloud `_. +These changes were introduced in `pull request 2263 `_. ControllerServer New Parameter failure_tolerance ************************************************ A new parameter :code:`failure_tolerance` was added to the Controller Server for tolerating controller plugin exceptions without failing immediately. It is analogous to ``controller_patience`` in ROS(1) Nav. See :ref:`configuring_controller_server` for description. -This change was introduced in this `pull request 2264 `_. +This change was introduced in this `pull request 2264 `_. Removed BT XML Launch Configurations ************************************ The launch python configurations for CLI setting of the behavior tree XML file has been removed. Instead, you should use the yaml files to set this value. If you, however, have a ``path`` to the yaml file that is inconsistent in a larger deployment, you can use the ``RewrittenYaml`` tool in your parent launch file to remap the default XML paths utilizing the ``get_shared_package_path()`` directory finder (or as you were before in python3). The use of map subscription QoS launch configuration was also removed, use parameter file. -This change was introduced in this `pull request 2295 `_. +This change was introduced in this `pull request 2295 `_. Nav2 RViz Panel Action Feedback Information ******************************************* The Nav2 RViz Panel now displays the action feedback published by ``nav2_msgs/NavigateToPose`` and ``nav2_msgs/NavigateThroughPoses`` actions. Users can find information like the estimated time of arrival, distance remaining to goal, time elapsed since navigation started, and number of recoveries performed during a navigation action directly through the RViz panel. -This feature was introduced in this `pull request 2338 `_. +This feature was introduced in this `pull request 2338 `_. .. image:: /images/rviz/panel-feedback.gif :width: 600px diff --git a/migration/Galactic.rst b/migration/Galactic.rst index a25b623ed..71e1021d2 100644 --- a/migration/Galactic.rst +++ b/migration/Galactic.rst @@ -48,7 +48,7 @@ Further, the traversal cost and heuristic cost computations were updated **requi Simple (Python) Commander ************************* -`This PR 2411 `_ introduces a new package to Nav2, called the ``nav2_simple_commander``. It is a set of functions in an object, ``BasicNavigator``, which can be used to build Nav2-powered autonomy tasks in Python3 without concerning yourself with the Nav2, ROS 2, or Action server details. It contains a simple API taking common types (primarily ``PoseStamped``) and handles all of the implementation details behind the hood. For example, this is a simple navigation task using this API: +`This PR 2411 `_ introduces a new package to Nav2, called the ``nav2_simple_commander``. It is a set of functions in an object, ``BasicNavigator``, which can be used to build Nav2-powered autonomy tasks in Python3 without concerning yourself with the Nav2, ROS 2, or Action server details. It contains a simple API taking common types (primarily ``PoseStamped``) and handles all of the implementation details behind the hood. For example, this is a simple navigation task using this API: .. code-block:: python3 @@ -85,7 +85,7 @@ Simple (Python) Commander elif result == TaskResult.FAILED: print('Goal failed!') -`The full API can be found in the README of the package `_. A number of well commented examples and demos can also be found in the package's source code at the link prior. +`The full API can be found in the README of the package `_. A number of well commented examples and demos can also be found in the package's source code at the link prior. Reduce Nodes and Executors @@ -93,33 +93,33 @@ Reduce Nodes and Executors In order for nav2 to make the best use of ROS 2, we need minimize the number of nodes and executors in nav2, which can improve performance. -This functionality has been discussed in `the ticket #816 `_, and carried out in +This functionality has been discussed in `the ticket #816 `_, and carried out in - - Remove ``client_node_`` in ``class WaypointFollower`` : `PR2441 `_ - - Remove ``rclcpp_node_`` in ``class MapSaver`` : `PR2454 `_ - - Remove ``bond_client_node_`` in ``class LifecycleManager`` : `PR2456 `_ - - Remove ``node_`` in ``class LifecycleManagerClient`` : `PR2469 `_ - - Remove ``rclcpp_node_`` in ``class ControllerServer`` : `PR2459 `_, `PR2479 `_ - - Remove ``rclcpp_node_`` in ``class PlannerServer`` : `PR2459 `_, `PR2480 `_ - - Remove ``rclcpp_node_`` in ``class AmclNode`` : `PR2483 `_ - - Remove ``rclcpp_node_`` and ``clinet_node_`` in ``class Costmap2DROS`` : `PR2489 `_ - - Remove ``rclcpp_node_`` in ``class LifecycleNode`` : `PR2993 `_ + - Remove ``client_node_`` in ``class WaypointFollower`` : `PR2441 `_ + - Remove ``rclcpp_node_`` in ``class MapSaver`` : `PR2454 `_ + - Remove ``bond_client_node_`` in ``class LifecycleManager`` : `PR2456 `_ + - Remove ``node_`` in ``class LifecycleManagerClient`` : `PR2469 `_ + - Remove ``rclcpp_node_`` in ``class ControllerServer`` : `PR2459 `_, `PR2479 `_ + - Remove ``rclcpp_node_`` in ``class PlannerServer`` : `PR2459 `_, `PR2480 `_ + - Remove ``rclcpp_node_`` in ``class AmclNode`` : `PR2483 `_ + - Remove ``rclcpp_node_`` and ``clinet_node_`` in ``class Costmap2DROS`` : `PR2489 `_ + - Remove ``rclcpp_node_`` in ``class LifecycleNode`` : `PR2993 `_ some APIs are changed in these PRs: - - `PR2489 `_ removes arguments ``client_node``, ``rclcpp_node`` and adds argument ``callback_group`` in the initialize function of class ``nav2_costmap_2d::Layer``. ``callback_group`` is used to replace ``rclcpp_node``. - - `PR2993 `_ removes argument ``use_rclcpp_node `` in the constructor of class ``nav2_util::LifecycleNode``. + - `PR2489 `_ removes arguments ``client_node``, ``rclcpp_node`` and adds argument ``callback_group`` in the initialize function of class ``nav2_costmap_2d::Layer``. ``callback_group`` is used to replace ``rclcpp_node``. + - `PR2993 `_ removes argument ``use_rclcpp_node `` in the constructor of class ``nav2_util::LifecycleNode``. API Change for nav2_core ************************ -`PR 2976 `_ changes the API for ``nav2_core::Controller`` and ``nav2_core::Smoother`` by replacing the use of shared pointer references ``(const shared_ptr<> &)`` to shared pointers ``(shared_ptr<>)``. +`PR 2976 `_ changes the API for ``nav2_core::Controller`` and ``nav2_core::Smoother`` by replacing the use of shared pointer references ``(const shared_ptr<> &)`` to shared pointers ``(shared_ptr<>)``. Use of shared pointer references meant that the shared pointer counter was never incremented. Extending the BtServiceNode to process Service-Results ****************************************************** -`This PR 2481 `_ and `PR 2992 `_ address `the ticket `_ and `this ticket `_ and adds a virtual ``on_completion()`` function to the ``BtServiceNode`` class (`can be found here `_). +`This PR 2481 `_ and `PR 2992 `_ address `the ticket `_ and `this ticket `_ and adds a virtual ``on_completion()`` function to the ``BtServiceNode`` class (`can be found here `_). Similar to the already existing virtual ``on_wait_for_result()`` function, it can be overwritten in the child class to react to a respective event with some user-defined operation. The added ``on_completion()`` function will be called after the service interaction of the ``BtServiceNode`` has been successfully completed. @@ -142,7 +142,7 @@ The normal behavior of the ``BtServiceNode`` is not affected by introducing the Including new Rotation Shim Controller Plugin ********************************************* -`This PR 2718 `_ introduces the new ``nav2_rotation_shim_controller``. This controller will check the rough heading difference with respect to the robot and a newly received path. If within a threshold, it will pass the request onto the primary controller to execute. If it is outside of the threshold, this controller will rotate the robot towards that path heading. Once it is within the tolerance, it will then pass off control-execution from this rotation shim controller onto the primary controller plugin. At this point, the robot is still going to be rotating, allowing the current plugin to take control for a smooth hand off into path tracking. +`This PR 2718 `_ introduces the new ``nav2_rotation_shim_controller``. This controller will check the rough heading difference with respect to the robot and a newly received path. If within a threshold, it will pass the request onto the primary controller to execute. If it is outside of the threshold, this controller will rotate the robot towards that path heading. Once it is within the tolerance, it will then pass off control-execution from this rotation shim controller onto the primary controller plugin. At this point, the robot is still going to be rotating, allowing the current plugin to take control for a smooth hand off into path tracking. The Rotation Shim Controller is suitable for: @@ -154,7 +154,7 @@ The Rotation Shim Controller is suitable for: Spawning the robot in Gazebo **************************** -`This PR 2473 `_ deletes the pkg ``nav2_gazebo_spawner`` inside nav2_bringup directory. Instead of ``nav2_gazebo_spawner`` the Node `spawn_entity.py `_ of ``gazebo_ros`` is recommended to spawn the robot in gazebo. +`This PR 2473 `_ deletes the pkg ``nav2_gazebo_spawner`` inside nav2_bringup directory. Instead of ``nav2_gazebo_spawner`` the Node `spawn_entity.py `_ of ``gazebo_ros`` is recommended to spawn the robot in gazebo. Note that * gazebo should be started with both ``libgazebo_ros_init.so`` and ``libgazebo_ros_factory.so`` to work correctly. @@ -169,7 +169,7 @@ Recoveries in Nav2, spin and backup, now have ``time_allowance`` ports in their New parameter ``use_final_approach_orientation`` for the 3 2D planners ********************************************************************** -`Pull request 2488 `_ adds a new parameter ``use_final_approach_orientation`` to the 3 2D planners (Theta*, SmacPlanner2D and NavFn), ``false`` by default. If ``true``, the last pose of the path generated by the planner will have its orientation set to the approach orientation, i.e. the orientation of the vector connecting the last two points of the path. It allows sending the robot to a position (x,y) instead of a pose (x,y,theta) by effectively ignoring the goal orientation. +`Pull request 2488 `_ adds a new parameter ``use_final_approach_orientation`` to the 3 2D planners (Theta*, SmacPlanner2D and NavFn), ``false`` by default. If ``true``, the last pose of the path generated by the planner will have its orientation set to the approach orientation, i.e. the orientation of the vector connecting the last two points of the path. It allows sending the robot to a position (x,y) instead of a pose (x,y,theta) by effectively ignoring the goal orientation. For example, below, for the same goal with an orientaton pointed left of the screen, ``use_final_approach_orientation=false`` (left) and ``use_final_approach_orientation=true`` (right) .. image:: images/use_final_approach_orientation_false.gif @@ -181,27 +181,27 @@ For example, below, for the same goal with an orientaton pointed left of the scr SmacPlanner2D and Theta*: fix goal orientation being ignored ************************************************************ -`This pull request 2488 `_ fixes `the issue `_ of the goal pose orientation being ignored (the end path pose orientation was always set to 0). +`This pull request 2488 `_ fixes `the issue `_ of the goal pose orientation being ignored (the end path pose orientation was always set to 0). SmacPlanner2D, NavFn and Theta*: fix small path corner cases ************************************************************ -`This PR 2488 `_ ensures the planners are not failing when the distance between the start and the goal is small (i.e. when they are on the same costmap cell), and in that case the output path is constructed with a single pose. +`This PR 2488 `_ ensures the planners are not failing when the distance between the start and the goal is small (i.e. when they are on the same costmap cell), and in that case the output path is constructed with a single pose. Change and fix behavior of dynamic parameter change detection ************************************************************* -`This `_ and `this PR `_ modify the method used to catch the changes of dynamic parameters. The motivation was to fix the issue that ``void on_parameter_event_callback(const rcl_interfaces::msg::ParameterEvent::SharedPtr event)`` was called for every parameter change of every node leading to unwanted parameter changes if 2 different nodes had the same parameter name. +`This `_ and `this PR `_ modify the method used to catch the changes of dynamic parameters. The motivation was to fix the issue that ``void on_parameter_event_callback(const rcl_interfaces::msg::ParameterEvent::SharedPtr event)`` was called for every parameter change of every node leading to unwanted parameter changes if 2 different nodes had the same parameter name. Dynamic Parameters ****************** Newly added dynamic parameters to: -- `This PR 2592 `_ makes most of the Costmap2DROS parameters dynamic -- `This PR 2607 `_ makes most of the Regulated Pure Pursuit parameters dynamic -- `This PR 2665 `_ makes most of the Theta * Planner parameters dynamic -- `This PR 2704 `_ makes Waypoint Follower, Planner Server, and Controller Server's params reconfigurable +- `This PR 2592 `_ makes most of the Costmap2DROS parameters dynamic +- `This PR 2607 `_ makes most of the Regulated Pure Pursuit parameters dynamic +- `This PR 2665 `_ makes most of the Theta * Planner parameters dynamic +- `This PR 2704 `_ makes Waypoint Follower, Planner Server, and Controller Server's params reconfigurable BT Action Nodes Exception Changes @@ -212,7 +212,7 @@ When BT action nodes throw exceptions due to networking or action server failure BT Navigator Groot Multiple Navigators ************************************** -`This PR 2627 `_ creates separate parameters for groot monitoring for the NavToPose and NavThroughPoses navigator types so you can individually track the state of each behavior tree through the ZMQ publisher. This resolves a long-standing problem after we added multiple navigator types to BT Navigator that you could only view the nav to poses BT execution live. BT.CPP and Groot only support one static ZMQ stream at a time, so there is a bit of a quirk where you must locally reset Groot after switching trees in order to view the live stream of the Nav Through Poses BT, if in use. This is a state of the BT.CPP and Groot libraries and not something we can resolve within Nav2. +`This PR 2627 `_ creates separate parameters for groot monitoring for the NavToPose and NavThroughPoses navigator types so you can individually track the state of each behavior tree through the ZMQ publisher. This resolves a long-standing problem after we added multiple navigator types to BT Navigator that you could only view the nav to poses BT execution live. BT.CPP and Groot only support one static ZMQ stream at a time, so there is a bit of a quirk where you must locally reset Groot after switching trees in order to view the live stream of the Nav Through Poses BT, if in use. This is a state of the BT.CPP and Groot libraries and not something we can resolve within Nav2. There is some thought into the future regarding complete deprecation of live BT monitoring using Groot due to this quirk and the almost-certain infux of tickets on the topic. Groot will however always be supported for visualizing behavior tree XML files and modifications, simply not visualizing the BT execution live during robot navigation. @@ -224,23 +224,23 @@ The parameters ``max_linear_accel`` and ``max_linear_decel`` were removed along Added Smoother Task Server ************************** -A new task server was added which loads smoother plugins and executes them to improve quality of an existing planned path. Smoothing action can be called from a behavior tree using SmoothPath action node. `PR 2569 `_ implements and `PR 2875 `_ adds in the first of the plugins using it with a simple smoother. Other smoothers are in development and will be added in the future. +A new task server was added which loads smoother plugins and executes them to improve quality of an existing planned path. Smoothing action can be called from a behavior tree using SmoothPath action node. `PR 2569 `_ implements and `PR 2875 `_ adds in the first of the plugins using it with a simple smoother. Other smoothers are in development and will be added in the future. Removed Use Approach Velocity Scaling Param in RPP ************************************************** -The parameter ``use_approach_linear_velocity_scaling`` is removed in favor of always on to help in smooth transitions to the goal. `This PR 2701 `_ implements. +The parameter ``use_approach_linear_velocity_scaling`` is removed in favor of always on to help in smooth transitions to the goal. `This PR 2701 `_ implements. Refactored AMCL motion models as plugins **************************************** -`This PR 2642 `_ creates plugins for the different motion models currently used in AMCL. This functionality enables users to use any custom motion model by creating it as a plugin and changing the robot_model_type parameter to the name of the plugin in nav2_params.yaml file. This helps to use custom motion models without the need to modify the AMCL source code. +`This PR 2642 `_ creates plugins for the different motion models currently used in AMCL. This functionality enables users to use any custom motion model by creating it as a plugin and changing the robot_model_type parameter to the name of the plugin in nav2_params.yaml file. This helps to use custom motion models without the need to modify the AMCL source code. Dropping Support for Live Groot Monitoring of Nav2 ************************************************** -- https://github.com/ros-planning/navigation2/pull/2696 +- https://github.com/ros-navigation/navigation2/pull/2696 It was a great feature idea but never quite panned out, especially after we introduced multiple navigator types in the BT Navigator server. The issue we run into primarily is that Zero-MQ prevents users from producing multiple logger types in the same process. Since BT nav has multiple servers, the swapping between them for viewing has never had a clean hand off causing folks to file tickets or have nasty logs appear or ZMQ crashes in the background. The BT.CPP client for this doesn't allow us to have a clean shutdown process so we're left with hoping that ZMQ properly handles the situation, which it rarely does. Further, Groot only supports visualizing one type of tree at a time so for applications often switching between navigator types, its not possible to use a single groot client, causing great frustration. @@ -249,16 +249,16 @@ So, what I propose here is to remove live monitoring of the BT from Nav2. **We c Replanning Only if Path is Invalid ********************************** -`This PR 2591 `_ creates two new condition BT node to facilitate replanning only if path becomes invalid rather than constantly replanning. These new nodes were integrated into the default BT. +`This PR 2591 `_ creates two new condition BT node to facilitate replanning only if path becomes invalid rather than constantly replanning. These new nodes were integrated into the default BT. Fix CostmapLayer clearArea invert param logic ********************************************* -`This PR 2772 `_ fixes the invert paramlogic of the CostmapLayer clearArea function. Hence correcting the behavior of the clearAroundRobot and clearExceptRegion services and their corresponding BT actions. +`This PR 2772 `_ fixes the invert paramlogic of the CostmapLayer clearArea function. Hence correcting the behavior of the clearAroundRobot and clearExceptRegion services and their corresponding BT actions. Dynamic Composition ******************* -`This PR 2750 `_ provides a optional bringup based on ROS2 dynamic composition for users. It can be used to compose all Nav2 nodes in a single process instead of launching these nodes separately, which is useful for embedded systems users that need to make optimizations due to harsh resource constraints. it's used by default, but can be disabled by using the launch argument ``use_composition:=False``. +`This PR 2750 `_ provides a optional bringup based on ROS2 dynamic composition for users. It can be used to compose all Nav2 nodes in a single process instead of launching these nodes separately, which is useful for embedded systems users that need to make optimizations due to harsh resource constraints. it's used by default, but can be disabled by using the launch argument ``use_composition:=False``. Some experiments to show performance improvement of dynamic composition, and the cpu and memory are captured by ``psutil`` : @@ -273,12 +273,12 @@ The way of dynamic composition consumes lower memory(saves ~70%), and lower cpu BT Cancel Node ************** -`This PR 2787 `_ caters the users with an abstract node to develop cancel behaviors for different servers present in the Nav2 stack such as the controller_server, recovery_server and so on. As a start, this PR also provides the ``CancelControl`` behavior to cancel the goal given to the controller_server. As an addition to the ``CancelControl`` `This PR 2856 `_ provides the users with the option to cancel the recoveries such as the ``backup``, ``spin`` and ``wait``. +`This PR 2787 `_ caters the users with an abstract node to develop cancel behaviors for different servers present in the Nav2 stack such as the controller_server, recovery_server and so on. As a start, this PR also provides the ``CancelControl`` behavior to cancel the goal given to the controller_server. As an addition to the ``CancelControl`` `This PR 2856 `_ provides the users with the option to cancel the recoveries such as the ``backup``, ``spin`` and ``wait``. BT PathLongerOnApproach Node **************************** -In the `PR `_, a new Decorator BT node known as ``PathLongerOnApproach`` has been added to provide with the functionality to check and potentially handle longer path generated due to an obstacle in the given goal proximity. To demonstrate this functionality, a new BT ``navigate_to_pose_w_replanning_goal_patience_and_recovery.xml`` would serve both as an example and ready-to-use BT for a specific application that wishes to optimize their process cycle time. Demo of the developed BT can be seen below, where the robot pauses when close to a goal to see if the dynamic obstacle moves out of the way. Else, it executes the replan: +In the `PR `_, a new Decorator BT node known as ``PathLongerOnApproach`` has been added to provide with the functionality to check and potentially handle longer path generated due to an obstacle in the given goal proximity. To demonstrate this functionality, a new BT ``navigate_to_pose_w_replanning_goal_patience_and_recovery.xml`` would serve both as an example and ready-to-use BT for a specific application that wishes to optimize their process cycle time. Demo of the developed BT can be seen below, where the robot pauses when close to a goal to see if the dynamic obstacle moves out of the way. Else, it executes the replan: Obstacle does not clear at all, with `obstacle_clearance_time` to be 3 seconds: @@ -291,28 +291,28 @@ Obstacle clears and you can see the robot pass through the (could have been idea BT TruncatePathLocal Node ************************* -In the `PR 2753 `_, a new Action BT node named ``TruncatePathLocal`` has been added to extract a bounded-length path section near robot to be used e.g. for collision checking or computationally expensive smoothers +In the `PR 2753 `_, a new Action BT node named ``TruncatePathLocal`` has been added to extract a bounded-length path section near robot to be used e.g. for collision checking or computationally expensive smoothers Constrained Smoother ******************** -In `the PR 2753 `_, a new Smoother named ``nav2_constrained_smoother::ConstrainedSmoother`` has been added to optimize various path criteria such as smoothness or distance from obstacles, maintaining minimum turning radius +In `the PR 2753 `_, a new Smoother named ``nav2_constrained_smoother::ConstrainedSmoother`` has been added to optimize various path criteria such as smoothness or distance from obstacles, maintaining minimum turning radius Replanning at a Constant Rate and if the Path is Invalid ******************************************************** -`This PR 2804 `_ introduces a new behavior tree that navigates to pose with consistent replanning and if the path becomes invalid. +`This PR 2804 `_ introduces a new behavior tree that navigates to pose with consistent replanning and if the path becomes invalid. To facilitate the new behavior tree a new condition node PathExpiringTimer was introduced to trigger replanning at a consistent rate. Euclidean Distance 2D ********************* -`This PR 2865 `_ changes Euclidean distance calculation throughout nav2 to project on to the XY plane (i.e. discard any information related to components in Z). +`This PR 2865 `_ changes Euclidean distance calculation throughout nav2 to project on to the XY plane (i.e. discard any information related to components in Z). This may potentially subtly change the way certain BT nodes, BT Navigators, controller servers, planner servers, and RPP behave if using custom plugins outside the Nav2 ecosystem. Recovery To Behavior ******************** -`This PR 2867 `_ renames the nav2_recoveries to nav2_behaviors. +`This PR 2867 `_ renames the nav2_recoveries to nav2_behaviors. In navigation_launch.py recoveries_server -> behavior_server and nav2_recoveries -> nav2_behaviors. In nav2_params.yaml recovery_plugins -> behavior_plugins and nav2_recoveries -> nav2_behaviors. @@ -320,20 +320,20 @@ In nav2_params.yaml recovery_plugins -> behavior_plugins and nav2_recoveries -> Respawn Support in Launch and Lifecycle Manager *********************************************** -`PR 2752 `_ enables respawn support in Nav2. In the launch files, you may set ``use_respawn`` to ``true`` to enable respawning of servers that crash. This is only available in non-composed systems, since in composed systems, all of the nodes are under a single process and a crash anywhere will bring everything down (including the lifecycle manager itself). Even if the container was set to respawn, it would only respawn the empty container, not with all of the components loaded into it. +`PR 2752 `_ enables respawn support in Nav2. In the launch files, you may set ``use_respawn`` to ``true`` to enable respawning of servers that crash. This is only available in non-composed systems, since in composed systems, all of the nodes are under a single process and a crash anywhere will bring everything down (including the lifecycle manager itself). Even if the container was set to respawn, it would only respawn the empty container, not with all of the components loaded into it. That PR also enables the lifecycle manager to check if a system goes down due to a crash. If so, it allows the manager to check if the server comes back online within a given timeout period. If it does, it will automatically retransition the system back up to active to continue on its task automatically. New Nav2 Velocity Smoother ************************** -`PR 2964 `_ introduces the ``nav2_velocity_smoother`` for smoothing velocity commands from Nav2 to a robot controller by velocity, acceleration, and deadband constraints. See :ref:`configuring_velocity_smoother` for more details. It is not included in the default bringup batteries included from ``nav2_bringup``. +`PR 2964 `_ introduces the ``nav2_velocity_smoother`` for smoothing velocity commands from Nav2 to a robot controller by velocity, acceleration, and deadband constraints. See :ref:`configuring_velocity_smoother` for more details. It is not included in the default bringup batteries included from ``nav2_bringup``. Goal Checker API Changed ************************ -`PR 2965 `_ adds an extra argument in the initialize function of the `nav2_core::GoalChecker` class. +`PR 2965 `_ adds an extra argument in the initialize function of the `nav2_core::GoalChecker` class. The extra argument is a costmap_ros pointer. This is used to check if the goal is in collision, so that we can avoid moving towards the goal and replanning can be initiates using some BT plugin. Added Assisted Teleop ********************* -`PR 2904 `_ adds a new behavior for assisted teleop along with two new BT nodes AssistedTeleop and CancelAssistedTeleop. +`PR 2904 `_ adds a new behavior for assisted teleop along with two new BT nodes AssistedTeleop and CancelAssistedTeleop. diff --git a/migration/Humble.rst b/migration/Humble.rst index 550bf9966..a71561db9 100644 --- a/migration/Humble.rst +++ b/migration/Humble.rst @@ -8,21 +8,21 @@ Moving from ROS 2 Humble to Iron, a number of stability improvements were added New Behavior-Tree Navigator Plugins *********************************** -New in `PR 3345 `_, the navigator types are exposed to users as plugins that can be replaced or new navigator types added. The default behaviors of navigate to pose and navigate through poses continue to be default behavior but are now customizable with new action interface definitions. These plugins implement the ``nav2_core::BehaviorTreeNavigator`` base class, which must process the action request, feedback, and completion messages. The behavior tree is handled by this base class with as much general logic as possible abstracted away from users to minimize repetition. +New in `PR 3345 `_, the navigator types are exposed to users as plugins that can be replaced or new navigator types added. The default behaviors of navigate to pose and navigate through poses continue to be default behavior but are now customizable with new action interface definitions. These plugins implement the ``nav2_core::BehaviorTreeNavigator`` base class, which must process the action request, feedback, and completion messages. The behavior tree is handled by this base class with as much general logic as possible abstracted away from users to minimize repetition. See :ref:`writing_new_nav2navigator_plugin` for a tutorial about writing new navigator plugins. Added Collision Monitor *********************** -`PR 2982 `_ adds new safety layer operating independently of Nav2 stack which ensures the robot to control the collisions with near obstacles, obtained from different sensors (LaserScan, PointCloud, IR, Sonars, etc...). See :ref:`configuring_collision_monitor` for more details. It is not included in the default bringup batteries included from ``nav2_bringup``. +`PR 2982 `_ adds new safety layer operating independently of Nav2 stack which ensures the robot to control the collisions with near obstacles, obtained from different sensors (LaserScan, PointCloud, IR, Sonars, etc...). See :ref:`configuring_collision_monitor` for more details. It is not included in the default bringup batteries included from ``nav2_bringup``. Removed use_sim_time from yaml ****************************** -`PR #3131 `_ makes it possible to set the use_sim_time parameter from the launch file for multiple nodes instead of individually via the yaml files. If using the Nav2 launch files, you can optionally remove the use_sim_time parameter from your yaml files and set it via a launch argument. +`PR #3131 `_ makes it possible to set the use_sim_time parameter from the launch file for multiple nodes instead of individually via the yaml files. If using the Nav2 launch files, you can optionally remove the use_sim_time parameter from your yaml files and set it via a launch argument. Run-time Speed up of Smac Planner ********************************* -The core data structure of the graph implementation in the Smac Planner framework was swapped out in `PR 3201 `_ to using a specialized unordered map implementation. This speeds up the planner by 10% on trivial requests and reports up to 30% on complex plans that involve numerous rehashings. +The core data structure of the graph implementation in the Smac Planner framework was swapped out in `PR 3201 `_ to using a specialized unordered map implementation. This speeds up the planner by 10% on trivial requests and reports up to 30% on complex plans that involve numerous rehashings. Recursive Refinement of Smac and Simple Smoothers ************************************************* @@ -31,49 +31,49 @@ The number of recursive refinements for the Simple and Smac Planner Smoothers ha Simple Commander Python API *************************** -`PR 3159 `_ and follow-up PRs add in Costmap API in Python3 simple commander to receive ``OccupancyGrid`` messages from Nav2 and be able to work with them natively in Python3, analog to the C++ Costmap API. It also includes a line iterator and collision checking object to perform footprint or other collision checking in Python3. See the Simple Commander API for more details. +`PR 3159 `_ and follow-up PRs add in Costmap API in Python3 simple commander to receive ``OccupancyGrid`` messages from Nav2 and be able to work with them natively in Python3, analog to the C++ Costmap API. It also includes a line iterator and collision checking object to perform footprint or other collision checking in Python3. See the Simple Commander API for more details. Smac Planner Start Pose Included in Path **************************************** -`PR 3168 `_ adds the starting pose to the Smac Planners that was previously excluded during backtracing. +`PR 3168 `_ adds the starting pose to the Smac Planners that was previously excluded during backtracing. Parameterizable Collision Checking in RPP ***************************************** -`PR 3204 `_ adds makes collision checking for RPP optional (default on). +`PR 3204 `_ adds makes collision checking for RPP optional (default on). Expanded Planner Benchmark Tests ******************************** -`PR 3218 `_ adds launch files and updated scripts for performing objective random planning tests across the planners in Nav2 for benchmarking and metric computation. +`PR 3218 `_ adds launch files and updated scripts for performing objective random planning tests across the planners in Nav2 for benchmarking and metric computation. Smac Planner Path Tolerances **************************** -`PR 3219 `_ adds path tolerances to Hybrid-A* and State Lattice planners to return approximate paths if exact paths cannot be found, within a configurable tolerance aroun the goal pose. +`PR 3219 `_ adds path tolerances to Hybrid-A* and State Lattice planners to return approximate paths if exact paths cannot be found, within a configurable tolerance aroun the goal pose. costmap_2d_node default constructor *********************************** -`PR #3222 `_ changes the constructor used by the standalone costmap node. The new constructor does not set a name and namespace internally so it can be set via the launch file. +`PR #3222 `_ changes the constructor used by the standalone costmap node. The new constructor does not set a name and namespace internally so it can be set via the launch file. Feedback for Navigation Failures ******************************** -`PR #3146 `_ updates the global planners to throw exceptions on planning failures. These exceptions get reported back to the planner server which in turn places a error code on the Behavior Tree Navigator's blackboard for use in contextual error handling in the autonomy application. +`PR #3146 `_ updates the global planners to throw exceptions on planning failures. These exceptions get reported back to the planner server which in turn places a error code on the Behavior Tree Navigator's blackboard for use in contextual error handling in the autonomy application. The following errors codes are supported (with more to come as necessary): Unknown, TF Error, Start or Goal Outside of Map, Start or Goal Occupied, Timeout, or No Valid Path Found. -`PR #3248 `_ updates the compute path through poses action to report planning failures. These exceptions get reported back to the planner server which in turn places a error code on the Behavior Tree Navigator's blackboard for use in contextual error handling in the autonomy application. +`PR #3248 `_ updates the compute path through poses action to report planning failures. These exceptions get reported back to the planner server which in turn places a error code on the Behavior Tree Navigator's blackboard for use in contextual error handling in the autonomy application. The following errors codes are supported (with more to come as necessary): Unknown, TF Error, Start or Goal Outside of Map, Start or Goal Occupied, Timeout, No Valid Path Found and No Waypoints given. -`PR #3227 `_ updates the controllers to throw exceptions on failures. These exceptions get reported back to the controller server which in turn places a error code on the Behavior Tree Navigatior's blackboard for use in contextual error handling in the autonomy application. +`PR #3227 `_ updates the controllers to throw exceptions on failures. These exceptions get reported back to the controller server which in turn places a error code on the Behavior Tree Navigatior's blackboard for use in contextual error handling in the autonomy application. The following error codes are supported (with more to come as necessary): Unknown, TF Error, Invalid Path, Patience Exceeded, Failed To Make Progress, or No Valid Control. -`PR #3251 `_ pipes the highest priority error code through the bt_navigator and defines the error code structure. +`PR #3251 `_ pipes the highest priority error code through the bt_navigator and defines the error code structure. A new parameter for the the BT Navigator called "error_code_id_names" was added to the nav2_params.yaml to define the error codes to compare. The lowest error in the "error_code_id_names" is then returned in the action request (navigate to pose, navigate through poses waypoint follower), whereas the code enums increase the higher up in the software stack - giving higher priority to lower-level failures. @@ -97,9 +97,9 @@ See :ref:`adding_a_nav2_task_server` and the PR for additional information. Costmap Filters *************** -Costmap Filters now are have an ability to be enabled/disabled in run-time by calling ``toggle_filter`` service for appropriate filter (`PR #3229 `_). +Costmap Filters now are have an ability to be enabled/disabled in run-time by calling ``toggle_filter`` service for appropriate filter (`PR #3229 `_). -Added new binary flip filter, allowing e.g. to turn off camera in sensitive areas, turn on headlights/leds/other safety things or switch operating mode when robot is inside marked on mask areas (`PR #3228 `_). +Added new binary flip filter, allowing e.g. to turn off camera in sensitive areas, turn on headlights/leds/other safety things or switch operating mode when robot is inside marked on mask areas (`PR #3228 `_). Savitzky-Golay Smoother *********************** @@ -108,20 +108,20 @@ Adding a new smoother algorithm, the Savitzky-Golay smoother to the smoother ser Changes to Map yaml file path for map_server node in Launch *********************************************************** -`PR #3174 `_ adds a way to set the path to map yaml file for the map_server node either from the yaml file or using the launch configuration parameter ``map`` giving priority to the launch configuration parameter. ``yaml_filename`` is no longer strictly required to be present in ``nav2_params.yaml``. +`PR #3174 `_ adds a way to set the path to map yaml file for the map_server node either from the yaml file or using the launch configuration parameter ``map`` giving priority to the launch configuration parameter. ``yaml_filename`` is no longer strictly required to be present in ``nav2_params.yaml``. SmootherSelector BT Node ************************ -`PR #3283 `_ adds a BT node to set the smoother based on a topic or a default. See the configuration guide :ref:`configuring_simple_smoother` for more details. +`PR #3283 `_ adds a BT node to set the smoother based on a topic or a default. See the configuration guide :ref:`configuring_simple_smoother` for more details. Publish Costmap Layers ********************** -`PR #3320 `_ adds the ability for the nav2_costmap_2d package to publish out costmap data associated with each layer. +`PR #3320 `_ adds the ability for the nav2_costmap_2d package to publish out costmap data associated with each layer. Give Behavior Server Access to Both Costmaps ******************************************** -`PR #3255 `_ adds the ability for a behavior to access the local and global costmap. +`PR #3255 `_ adds the ability for a behavior to access the local and global costmap. To update behaviors, any reference to the global_frame must be updated to the local_frame parameter along with the ``configuration`` method which now takes in the local and global collision checkers. @@ -137,7 +137,7 @@ See the README.md and :ref:`configuring_mppic` page for more detail. Behavior Tree Uses Error Codes ****************************** -`PR #3324 `_ adds three new condition nodes to check for error codes on the blackboard set by action BT nodes which contain them. +`PR #3324 `_ adds three new condition nodes to check for error codes on the blackboard set by action BT nodes which contain them. The ``AreErrorCodesPresent`` condition node allows the user to specify the error code from the server along with the error codes to match against. The ``WouldAControllerRecoveryHelp`` checks if the active error code is UNKNOWN, PATIENCE_EXCEEDED, FAILED_TO_MAKE_PROGRESS or NO_VALID_CONTROL. @@ -155,7 +155,7 @@ These error code are potentially able to be cleared by a smoother recovery. Load, Save and Loop Waypoints from the Nav2 Panel in RViz ********************************************************* -`PR #3165 `_ provides three new functionalities for the nav2 panel in RViz, they are: +`PR #3165 `_ provides three new functionalities for the nav2 panel in RViz, they are: - load and save waypoints in a yaml file for waypoint following (initial pose can also be stored if required) - loop functionality to revisit the waypoints @@ -166,48 +166,48 @@ Looping functionality is not specific to the nav2 panel in RViz. Users utilizing DWB Forward vs Reverse Pruning ****************************** -`PR #3374 `_ adds a new ``forward_prune_distance`` parameter in the DWB controller. It replaces the ``prune_distance`` for forward path shortening, enabled through the ``shorten_transformed_plan`` boolean parameter. This change allows to use different values for forward and backward path shortening. +`PR #3374 `_ adds a new ``forward_prune_distance`` parameter in the DWB controller. It replaces the ``prune_distance`` for forward path shortening, enabled through the ``shorten_transformed_plan`` boolean parameter. This change allows to use different values for forward and backward path shortening. More stable regulation on curves for long lookahead distances ************************************************************* -`PR #3414 `_ adds a new ``use_fixed_curvature_lookahead`` parameter to the RPP controller. This makes slowing down on curve not dependent on the instantaneous lookahead point, but instead on a fixed distance set by the parameter ``curvature_lookahead_dist``. +`PR #3414 `_ adds a new ``use_fixed_curvature_lookahead`` parameter to the RPP controller. This makes slowing down on curve not dependent on the instantaneous lookahead point, but instead on a fixed distance set by the parameter ``curvature_lookahead_dist``. Publish Collision Monitor State ******************************* -`PR #3504 `_ adds a new ``state_topic`` parameter to the CollisionMonitor. If specified, this optional parameter enables the state topic publisher. The topic reports the currently activated polygon action type and name. +`PR #3504 `_ adds a new ``state_topic`` parameter to the CollisionMonitor. If specified, this optional parameter enables the state topic publisher. The topic reports the currently activated polygon action type and name. Renamed ROS-parameter in Collision Monitor ****************************************** -`PR #3513 `_ renames ``max_points`` parameter to ``min_points`` and changes its meaning. Formerly ``max_points`` meant the maximum number of points inside the area still not triggering the action, while ``min_points`` - is a minimal number of points starting from the action to be initiated. In other words ``min_points`` now should be adjusted as ``max_points + 1``. +`PR #3513 `_ renames ``max_points`` parameter to ``min_points`` and changes its meaning. Formerly ``max_points`` meant the maximum number of points inside the area still not triggering the action, while ``min_points`` - is a minimal number of points starting from the action to be initiated. In other words ``min_points`` now should be adjusted as ``max_points + 1``. New safety behavior model "limit" in Collision Monitor ****************************************************** -`PR #3519 `_ adds a new collision monitor behavior model ``limit`` that restricts maximum linear and angular speed to specific values (``linear_limit`` and ``angular_limit``) if enough points are in the given shape. +`PR #3519 `_ adds a new collision monitor behavior model ``limit`` that restricts maximum linear and angular speed to specific values (``linear_limit`` and ``angular_limit``) if enough points are in the given shape. Velocity smoother applies deceleration when timeout *************************************************** -`PR #3512 `_ makes the VelocitySmoother apply the deceleration when the input command timeout. +`PR #3512 `_ makes the VelocitySmoother apply the deceleration when the input command timeout. PoseProgressChecker plugin ************************** -`PR #3530 `_ adds a new ``nav2_controller::PoseProgressChecker`` plugin. It builds on the behavior of the ``SimpleProgressChecker`` by adding a new parameter ``required_movement_angle``, allowing the plugin to considers that there is still progress when there is no translation movement, from the moment there is a rotation movement superior to ``required_movement_angle`` within the ``movement_time_allowance``. +`PR #3530 `_ adds a new ``nav2_controller::PoseProgressChecker`` plugin. It builds on the behavior of the ``SimpleProgressChecker`` by adding a new parameter ``required_movement_angle``, allowing the plugin to considers that there is still progress when there is no translation movement, from the moment there is a rotation movement superior to ``required_movement_angle`` within the ``movement_time_allowance``. Allow multiple goal checkers and change parameter progress_checker_plugin(s) name and type ****************************************************************************************** -`PR #3555 `_ initializes the progress checker plugin(s) in the same way as for the goal checker and controller plugins: it is now a list of string and was renamed from ``progress_checker_plugin`` to ``progress_checker_plugins``, and the type changed from ``string`` to ``vector``. This allows the initialization of multiple progress checkers that can be chosen from the added ``progress_checker_id field`` of the ``FollowPath`` action. +`PR #3555 `_ initializes the progress checker plugin(s) in the same way as for the goal checker and controller plugins: it is now a list of string and was renamed from ``progress_checker_plugin`` to ``progress_checker_plugins``, and the type changed from ``string`` to ``vector``. This allows the initialization of multiple progress checkers that can be chosen from the added ``progress_checker_id field`` of the ``FollowPath`` action. Beware that it is a breaking change and that configuration files will need to be updated. IsBatteryChargingCondition BT Node ********************************** -`PR #3553 `_ adds a BT node to check if the battery is charging. See the configuration guide :ref:`bt_is_battery_charging_condition` for more details. +`PR #3553 `_ adds a BT node to check if the battery is charging. See the configuration guide :ref:`bt_is_battery_charging_condition` for more details. Behavior Server Error Codes *************************** -`PR #3569 `_ updates the behavior server plugins to provide error codes on failure. +`PR #3569 `_ updates the behavior server plugins to provide error codes on failure. - Spin: NONE: 0, UNKNOWN: 701, server error codes: 701-709 - BackUp: NONE: 0, UNKNOWN: 801, server error codes: 710-719 @@ -216,7 +216,7 @@ Behavior Server Error Codes New Denoise Costmap Layer Plugin ******************************** -`PR #2567 `_ adds the new plugin for filtering noise on the costmap. +`PR #2567 `_ adds the new plugin for filtering noise on the costmap. Due to errors in ``Voxel Layer`` or ``Obstacle Layer`` measurements, salt and pepper noise may appear on the :ref:`costmap `. This noise creates false obstacles that prevent the robot from finding the best path on the map. The new ``Denoise Layer`` plugin is designed to filter out noise-induced standalone obstacles or small obstacles groups. This plugin allows you to add layer that will filter local or global costmap. @@ -224,4 +224,4 @@ More information about ``Denoise Layer`` plugin and how it works could be found SmacPlannerHybrid viz_expansions parameter ****************************************** -`PR #3577 `_ adds a new parameter for visualising SmacPlannerHybrid expansions for debug purpose. +`PR #3577 `_ adds a new parameter for visualising SmacPlannerHybrid expansions for debug purpose. diff --git a/migration/Iron.rst b/migration/Iron.rst index efec22d43..55c97af34 100644 --- a/migration/Iron.rst +++ b/migration/Iron.rst @@ -25,13 +25,13 @@ A new parameter ``enable_stamped_cmd_vel`` has been added to all of the publishe Add VelocityPolygon in Collision Monitor **************************************** -`PR #3708 `_ adds ``VelocityPolgon`` type in Collision Monitor. This 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. The tutorial is available in the :ref:`Configuring Collision Monitor with VelocityPolygon ` section. +`PR #3708 `_ adds ``VelocityPolgon`` type in Collision Monitor. This 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. The tutorial is available in the :ref:`Configuring Collision Monitor with VelocityPolygon ` section. Change polygon points parameter format in Collision Monitor *********************************************************** -`PR #4020 `_ changes the format of the Polygon points parameter from ``vector`` to ``string``. This makes the polygon description more uniform across the Collision Monitor and Costmap_2D. +`PR #4020 `_ changes the format of the Polygon points parameter from ``vector`` to ``string``. This makes the polygon description more uniform across the Collision Monitor and Costmap_2D. Now we can define a polygon's points in string that has a ``vector>`` structure like this ``"[[p1.x, p1.y], [p2.x, p2.y], [p3.x, p3.y],...]"`` with a minimum of 4 points described. An example of a Square polygon will be written as follows. @@ -49,7 +49,7 @@ Now we can define a polygon's points in string that has a ``vector`_ adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. The Simple Action Server now has a ``realtime`` input field exposed in the Controller Server via the parameter ``use_realtime_priority`` which will set the controller's execution thread to a higher priority than the rest of the system to meet scheduling deadlines. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions. This is currently only enabled in the Controller Server, who's execution thread is sensitive to scheduling priorities, but could be set with other threads in the future if found necessary. +`PR #3914 `_ adds soft real-time prioritization to the controller server to better ensure resources to time sensitive portions of the codebase. The Simple Action Server now has a ``realtime`` input field exposed in the Controller Server via the parameter ``use_realtime_priority`` which will set the controller's execution thread to a higher priority than the rest of the system to meet scheduling deadlines. To use this feature, you use set the following inside of ``/etc/security/limits.conf`` to give userspace access to elevated prioritization permissions. This is currently only enabled in the Controller Server, who's execution thread is sensitive to scheduling priorities, but could be set with other threads in the future if found necessary. .. code-block:: text @@ -77,13 +77,13 @@ See :ref:`docking_tutorial` for a tutorial on using this new capability! Thanks Introduce a new Multi-Robot Bringup Launch ****************************************** -`PR #3572 `_ introduces a new way of bringup tb3 multi-robot that names as ``cloned_tb3_simulation_launch.py`` for simulation. ``cloned_tb3_simulation_launch.py`` enables to bring up multiple robots with same parameter that described in ``nav2_multirobot_param_all.yaml``. And multiple robots are separated by namespaces which are given as a Launch Arguments. +`PR #3572 `_ introduces a new way of bringup tb3 multi-robot that names as ``cloned_tb3_simulation_launch.py`` for simulation. ``cloned_tb3_simulation_launch.py`` enables to bring up multiple robots with same parameter that described in ``nav2_multirobot_param_all.yaml``. And multiple robots are separated by namespaces which are given as a Launch Arguments. Existing ``multi_tb3_simulation_launch.py`` which was utilized in previous is replaced with ``unique_tb3_simulation_launch.py``, allowing for multiple unique robot instances utilizing ``nav2_multirobot_params_.yaml`` configuration files. New option for the Voxel and Obstacle Layers ******************************************** -`PR #3612 `_ adds a new MaxWithoutUnknownOverwrite option to combination_method parameter in Voxel and Obstacle Layers. This can be used to make sure that the static map is the dominant source of information, and +`PR #3612 `_ adds a new MaxWithoutUnknownOverwrite option to combination_method parameter in Voxel and Obstacle Layers. This can be used to make sure that the static map is the dominant source of information, and easily prevent the robot to go through places that are not present in the static map. use_interpolation RPP Parameter Depreciated @@ -127,7 +127,7 @@ New to Jazzy, MPPI is 45% faster due to a weeks long optimization campaign. Enjo Move Error Code Enumerations **************************** -`PR #3693 `_ moves the enumeration codes from the goal to the result section. +`PR #3693 `_ moves the enumeration codes from the goal to the result section. Substitution in parameter file ****************************** @@ -145,7 +145,7 @@ For more information about substitutions syntax, see `here `_ allows behavior servers plugins to access and modify the action result. +`PR #3704 `_ allows behavior servers plugins to access and modify the action result. Smac Planner Debug Param Name Change ************************************ @@ -162,7 +162,7 @@ This PR also introduces additional analytic expansion scoring logic and edge cas Added GPS Waypoint Follower Server ********************************** -`This PR 2814 `_ adds the ``follow_gps_waypoints`` action server in ``nav2_waypoint_follower``. This server accepts a set of GPS goals instead of cartesian goals and provides all the other functionalities available on ``nav2_waypoint_follower``. A new tutorial demonstrating its functionality was also added on `PR 70 on navigation2_tutorials `_ and can be found on the General Tutorials directory on this website. +`This PR 2814 `_ adds the ``follow_gps_waypoints`` action server in ``nav2_waypoint_follower``. This server accepts a set of GPS goals instead of cartesian goals and provides all the other functionalities available on ``nav2_waypoint_follower``. A new tutorial demonstrating its functionality was also added on `PR 70 on navigation2_tutorials `_ and can be found on the General Tutorials directory on this website. Smac Planner Hybrid-A* New Features *********************************** @@ -172,18 +172,18 @@ New features ``allow_primitive_interpolation`` which allows for more primitives New node in nav2_collision_monitor: Collision Detector ****************************************************** -In this `PR #3693 `_ A new node was introduced in the nav2_collision_monitor: Collision Detector. +In this `PR #3693 `_ A new node was introduced in the nav2_collision_monitor: Collision Detector. It works similarly to the Collision Monitor, but does not affect the robot's velocity. It will only inform that data from the configured sources has been detected within the configured polygons via message to the ``collision_detector_state`` topic that might be used by any external module (e.g. switching LED or sound alarm in case of collision). Dynamic enabling/disabling of sources/polygons in Collision Monitor/Detector **************************************************************************** -In this `PR #3825 `_ we added the ability to dynamically enable/disable sources and polygons in the Collision Monitor/Detector. +In this `PR #3825 `_ we added the ability to dynamically enable/disable sources and polygons in the Collision Monitor/Detector. Expose action server's result timeout ************************************* -In this `PR #3787 `_ the timeout for action server's result was exposed in all nodes having action servers. +In this `PR #3787 `_ the timeout for action server's result was exposed in all nodes having action servers. This is because in this `PR #1012 `_ in rcl a change was introduced which makes action servers discard a goal handle if the result is not produced within 10 seconds, when the default was set to 15 minutes before. Since some actions in Nav2 may take more than 10 seconds to complete, the user has now the ability to set this value through the ``action_server_result_timeout`` parameter, which defaults to 15 minutes in the ``bt_navigators`` and ``waypoint_follower`` and to 10 seconds in all other nodes. @@ -192,40 +192,40 @@ RewrittenYaml could add new parameters to YAMLs *********************************************** Now ``RewrittenYaml`` widely used in Nav2 launch-scripts, could do not only substitutions of ROS-parameters existing in original YAML, but rather additions of new parameters, that did not exist in the YAML. Certainly, these parameters should be declared for target ROS-nodes, otherwise they won't be processed in run-time. In such functionality, they should be expressed in absolute values, separated by a dot. For example, the rewrite for a ``prune_distance`` parameter of a ``FollowPath`` node will look like ``'controller_server.ros__parameters.FollowPath.prune_distance': '1.0'`` in a ``param_rewrites`` dictionary of ``RewrittenYaml()`` argument. -The change was intoroduced in the scope of `PR #3785 `_ fix. +The change was intoroduced in the scope of `PR #3785 `_ fix. Simple Commander API Allows Multi-Robot Namespacing *************************************************** -The Simple Navigator API now allows multi-robot namespacing by exposing a ``namespace`` field in the constructor to allow you to specify the Nav2 stacks' namespace for a robot or system. See `this PR for details `_. +The Simple Navigator API now allows multi-robot namespacing by exposing a ``namespace`` field in the constructor to allow you to specify the Nav2 stacks' namespace for a robot or system. See `this PR for details `_. Change duration type in wait_action node **************************************** -In this `PR #3871 `_ the type of duration variable in wait_action node is changed from int to double, which allows you to use floating values for wait_action. +In this `PR #3871 `_ the type of duration variable in wait_action node is changed from int to double, which allows you to use floating values for wait_action. The costmap activation fails when required transforms are not available *********************************************************************** -In this `PR #3866 `_ the parameter ``initial_transform_timeout`` is added to the costmap. The activation of the costmap now fails, +In this `PR #3866 `_ the parameter ``initial_transform_timeout`` is added to the costmap. The activation of the costmap now fails, if the transformation from the robot base frame to the global frame does not become available during this timeout. Subtrees Obtain Shared Resources ******************************** -`PR #3911 `_ gives all sub-trees in BT.CPP the same shared resources as the main tree (node, shared timeouts, etc). +`PR #3911 `_ gives all sub-trees in BT.CPP the same shared resources as the main tree (node, shared timeouts, etc). Collision Monitor: added watchdog mechanism based on ``source_timeout`` parameter with default blocking behavior **************************************************************************************************************** -`PR #3880 `_ adds a watchdog mechanism that stops the robot if a source data is not published yet, or if no new data is received within the `source_timeout`` parameter, or if impossible to transform data to base frame. ``source_timeout`` parameter can now be set per source: if ``source_timeout`` is not set for a source, the value of the node ``source_timeout`` parameter is used. +`PR #3880 `_ adds a watchdog mechanism that stops the robot if a source data is not published yet, or if no new data is received within the `source_timeout`` parameter, or if impossible to transform data to base frame. ``source_timeout`` parameter can now be set per source: if ``source_timeout`` is not set for a source, the value of the node ``source_timeout`` parameter is used. Additionally, this watchdog mechanism can be disabled by setting ``source_timeout: 0.0``. BtActionServer: use native library haltTree() ********************************************* -`PR #3950 `_ changes the method used by `BehaviorTreeEngine::haltAllActions` to halt the BT nodes to the bt.cpp native method `haltTree()`. +`PR #3950 `_ changes the method used by `BehaviorTreeEngine::haltAllActions` to halt the BT nodes to the bt.cpp native method `haltTree()`. Before this change, only the active BT node was halted when finishing the action. After this change, all BT nodes halt() methods are called. This is very convenient to handle cleaning operation (switch off your lights when leaving) in halt(). @@ -239,7 +239,7 @@ The Global Frame was removed from ``RemovePassedGoals`` and ``GoalReached`` BT n Introduction of ``CostmapUpdate.msg`` ************************************* -`PR #3965 `_ introduces a new type of message - ``CostmapUpdate.msg``. It is the update message related to the ``Costmap.msg``. Now instead of sending the whole costmap in every message, such as with ``Costmap.msg``, the ``CostmapUpdate.msg`` includes only the area of the costmap that has changed since the previous update message. The ``Costmap.msg`` is sent only once at the beginning, followed by the messages of the ``CostmapUpdate.msg`` type. The idea is to mimic the ``OccupancyGrid.msg`` and ``OccupancyGridUpdate.msg`` behavior. +`PR #3965 `_ introduces a new type of message - ``CostmapUpdate.msg``. It is the update message related to the ``Costmap.msg``. Now instead of sending the whole costmap in every message, such as with ``Costmap.msg``, the ``CostmapUpdate.msg`` includes only the area of the costmap that has changed since the previous update message. The ``Costmap.msg`` is sent only once at the beginning, followed by the messages of the ``CostmapUpdate.msg`` type. The idea is to mimic the ``OccupancyGrid.msg`` and ``OccupancyGridUpdate.msg`` behavior. To activate this feature, the Costmap2D ROS parameter ``always_send_full_costmap`` has to be set to ``false``. @@ -253,7 +253,7 @@ The stack no longer contains wall timers or wall rates. It will now use the node New Graceful Motion Controller ****************************** -`PR #4021 `_ introduces a new type of controller for differential robots based on a pose-following kinematic control law that generates a smooth and comfortable trajectory. +`PR #4021 `_ introduces a new type of controller for differential robots based on a pose-following kinematic control law that generates a smooth and comfortable trajectory. See :ref:`configuring_graceful_motion_controller` for more information. @@ -265,7 +265,7 @@ New to Jazzy, the ``plugin_lib_names`` parameter implicitly includes all Nav2 BT New RViz Plugin for selecting Planners, Controllers, Goal Checkers, Progress Checkers and Smoothers *************************************************************************************************** -`In PR #4091 `_ a new RViz plugin was added to select the planner, controller, goal checker, progress checker, and smoother on the fly. +`In PR #4091 `_ a new RViz plugin was added to select the planner, controller, goal checker, progress checker, and smoother on the fly. The primary goal of this plugin is to facilitate the developers and easy integration testing of their configuration before deploying the robot in the intended application. @@ -284,7 +284,7 @@ In this case, the `FollowPath` is the default controller_id. The difference betw RPP new optional ``interpolate_curvature_after_goal`` behavior and fix conflict between ``use_rotate_to_heading`` and ``allow_reversing`` ***************************************************************************************************************************************** -`In PR #4140 `_ a new optional ``interpolate_curvature_after_goal`` parameter (default ``false``) was added that activates the interpolation of a carrot after the goal in order to maintain a constant curvature lookahead distance. This is to avoid instabilities at the end of the path on the generation of the angular speed. The carrot used for the linear speed computation stays the same. +`In PR #4140 `_ a new optional ``interpolate_curvature_after_goal`` parameter (default ``false``) was added that activates the interpolation of a carrot after the goal in order to maintain a constant curvature lookahead distance. This is to avoid instabilities at the end of the path on the generation of the angular speed. The carrot used for the linear speed computation stays the same. Interpolation is based on the orientation of the vector formed by the last 2 poses of the path. Hence paths of length 1 are rejected when ``interpolate_curvature_after_goal`` is ``true``. It can be used only when ``use_fixed_curvature_lookahead: true``. @@ -295,7 +295,7 @@ Additionally, the conflict between ``use_rotate_to_heading`` and ``allow_reversi Cancel Checker Interface For GlobalPlanner ******************************************* -`PR #4148 `_ introduces a new interface for the ``GlobalPlanner`` to allow for the cancellation of the current planning task. +`PR #4148 `_ introduces a new interface for the ``GlobalPlanner`` to allow for the cancellation of the current planning task. Before the planners would continue to plan even if the goal was cancelled, now they can check it and stop planning if the goal is cancelled. New interface for ``GlobalPlanner::createPlan``: @@ -313,19 +313,19 @@ Smac and Theta* planners have a new parameter ``terminal_checking_interval`` whi New BtActionServer/BtNavigator parameter **************************************** -`PR #4209 `_ introduces a new boolean parameter ``always_reload_bt_xml``, which enables the possibility to always reload a requested behavior tree XML description, regardless of the currently active XML. This allows keeping the action server running while changing/developing the XML description. +`PR #4209 `_ introduces a new boolean parameter ``always_reload_bt_xml``, which enables the possibility to always reload a requested behavior tree XML description, regardless of the currently active XML. This allows keeping the action server running while changing/developing the XML description. New collision monitor parameter ******************************* -`PR #4207 `_ introduces a new boolean parameter ``polygon_subscribe_transient_local`` (value is false by default), which set the QoS durability for polygon topic or footprint topic subscription. +`PR #4207 `_ introduces a new boolean parameter ``polygon_subscribe_transient_local`` (value is false by default), which set the QoS durability for polygon topic or footprint topic subscription. New graceful cancellation API for Controllers ********************************************* -`PR #4136 `_ introduces a new graceful cancellation API for controllers. Previously when a goal was canceled, the controller would stop the robot immediately. This API allows the controller to stop the robot in a more graceful way. The new API is implemented in the ``RegulatedPurePursuitController`` by adding a new parameter ``cancel_deceleration``. So when the goal is canceled, a constant deceleration will be used while continuing to track the path to stop the robot instead of stopping immediately. This API can be should be added to all controllers that have acceleration limits. +`PR #4136 `_ introduces a new graceful cancellation API for controllers. Previously when a goal was canceled, the controller would stop the robot immediately. This API allows the controller to stop the robot in a more graceful way. The new API is implemented in the ``RegulatedPurePursuitController`` by adding a new parameter ``cancel_deceleration``. So when the goal is canceled, a constant deceleration will be used while continuing to track the path to stop the robot instead of stopping immediately. This API can be should be added to all controllers that have acceleration limits. Standardization of Plugin Naming with Double Colons (::) @@ -341,21 +341,21 @@ Standardization of Plugin Naming with Double Colons (::) Collision monitor: dynamic radius for circle type polygons ********************************************************** -`PR #4226 `_ introduces usage of parameter ``.polygon_sub_topic`` for circle type polygons. If parameter ``.radius`` is not set, collision monitor node subscribes to topic ``.polygon_sub_topic`` (subscription type is ``std_msgs/msg/Float32``), and the current circle polygon radius will be updating accordingly to received messages on topic. +`PR #4226 `_ introduces usage of parameter ``.polygon_sub_topic`` for circle type polygons. If parameter ``.radius`` is not set, collision monitor node subscribes to topic ``.polygon_sub_topic`` (subscription type is ``std_msgs/msg/Float32``), and the current circle polygon radius will be updating accordingly to received messages on topic. Static Layer: new parameter ``footprint_clearing_enabled`` ********************************************************** -`PR #4282 `_ introduces usage of parameter ``footprint_clearing_enabled`` for the static layer. It works similarly to the ``footprint_clearing_enabled`` parameter in the obstacle and voxel layer. If set to ``true``, the static layer will clear the costmap cells that are within the robot's footprint. It is ``false`` by default to keep the previous behavior. +`PR #4282 `_ introduces usage of parameter ``footprint_clearing_enabled`` for the static layer. It works similarly to the ``footprint_clearing_enabled`` parameter in the obstacle and voxel layer. If set to ``true``, the static layer will clear the costmap cells that are within the robot's footprint. It is ``false`` by default to keep the previous behavior. Lifecycle Node: added bond_heartbeat_period parameter (and allow disabling the bond mechanism) ********************************************************************************************** -`PR #4342 `_ adds the parameter ``bond_heartbeat_period`` to the lifecycle nodes to customize the bond mechanism publishing period (on the ``/bond`` topic). Default value unchanged to 0.1s. Disabled if inferior or equal to 0.0. +`PR #4342 `_ adds the parameter ``bond_heartbeat_period`` to the lifecycle nodes to customize the bond mechanism publishing period (on the ``/bond`` topic). Default value unchanged to 0.1s. Disabled if inferior or equal to 0.0. Rotation Shim Controller: new parameter ``rotate_to_goal_heading`` ****************************************************************** -`PR #4332 `_ introduces usage of parameter ``rotate_to_goal_heading`` for the rotation shim controller. It allows the rotation shim controller to take back control when reaching the XY goal tolerance to perform a clean rotation towards the goal heading. Some controllers will do this internally, but it is a useful option for others. +`PR #4332 `_ introduces usage of parameter ``rotate_to_goal_heading`` for the rotation shim controller. It allows the rotation shim controller to take back control when reaching the XY goal tolerance to perform a clean rotation towards the goal heading. Some controllers will do this internally, but it is a useful option for others. MPPI Controller: Addition of acceleration constraints ****************************************************** diff --git a/plugin_tutorials/docs/writing_new_behavior_plugin.rst b/plugin_tutorials/docs/writing_new_behavior_plugin.rst index e4a9c374b..045e381e4 100644 --- a/plugin_tutorials/docs/writing_new_behavior_plugin.rst +++ b/plugin_tutorials/docs/writing_new_behavior_plugin.rst @@ -33,7 +33,7 @@ Tutorial Steps We will create a simple send sms behavior. It will use Twilio to send a message via SMS to a remote operations center. -The code in this tutorial can be found in `navigation_tutorials `_ repository as ``nav2_sms_behavior``. +The code in this tutorial can be found in `navigation_tutorials `_ repository as ``nav2_sms_behavior``. This package can be a considered as a reference for writing Behavior Plugin. Our example plugin implements the plugin class of ``nav2_core::Behavior``. diff --git a/plugin_tutorials/docs/writing_new_bt_plugin.rst b/plugin_tutorials/docs/writing_new_bt_plugin.rst index 978d9877b..7388d8bd2 100644 --- a/plugin_tutorials/docs/writing_new_bt_plugin.rst +++ b/plugin_tutorials/docs/writing_new_bt_plugin.rst @@ -32,7 +32,7 @@ For this example, we're going to analyze the simplest behavior tree action node Beyond this example of an action BT node, you can also create custom decorator, condition, and control nodes. Each node type has a unique role in the behavior tree to perform actions like planning, control the flow of the BT, check the status of a condition, or modify the output of other BT nodes. -The code in this tutorial can be found in `nav2_behavior_tree `_ package as the ``wait_action`` node. +The code in this tutorial can be found in `nav2_behavior_tree `_ package as the ``wait_action`` node. This action node can be considered as a reference for writing other action node plugins. Our example plugin inherits from the base class ``nav2_behavior_tree::BtActionNode``. diff --git a/plugin_tutorials/docs/writing_new_costmap2d_plugin.rst b/plugin_tutorials/docs/writing_new_costmap2d_plugin.rst index d74926636..609e11d01 100644 --- a/plugin_tutorials/docs/writing_new_costmap2d_plugin.rst +++ b/plugin_tutorials/docs/writing_new_costmap2d_plugin.rst @@ -31,7 +31,7 @@ Tutorial Steps ------------------------------- For a demonstration, this example will create a costmap plugin that puts repeating cost gradients in the costmap. -The annotated code for this tutorial can be found in `navigation2_tutorials `_ repository as the ``nav2_gradient_costmap_plugin`` ROS 2-package. +The annotated code for this tutorial can be found in `navigation2_tutorials `_ repository as the ``nav2_gradient_costmap_plugin`` ROS 2-package. Please refer to it when making your own layer plugin for Costmap2D. The plugin class ``nav2_gradient_costmap_plugin::GradientLayer`` is inherited from basic class ``nav2_costmap_2d::Layer``: diff --git a/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst b/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst index 8750f9280..52c7e27b0 100644 --- a/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst +++ b/plugin_tutorials/docs/writing_new_nav2controller_plugin.rst @@ -22,7 +22,7 @@ In this tutorial, we will be implementing the pure pursuit path tracking algorit It is recommended you go through it. Note: This tutorial is based on a previously existing simplified version of the Regulated Pure Pursuit controller now in the Nav2 stack. -You can find the source code matching this tutorial `here `_. +You can find the source code matching this tutorial `here `_. Requirements ============ @@ -38,7 +38,7 @@ Tutorial Steps 1- Create a new Controller Plugin --------------------------------- -We will be implementing the pure pursuit controller. The annotated code in this tutorial can be found in `navigation_tutorials `_ repository +We will be implementing the pure pursuit controller. The annotated code in this tutorial can be found in `navigation_tutorials `_ repository as the ``nav2_pure_pursuit_controller``. This package can be considered as a reference for writing your own controller plugin. Our example plugin class ``nav2_pure_pursuit_controller::PurePursuitController`` inherits from the base class ``nav2_core::Controller``. The base class provides a diff --git a/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst b/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst index ae4d1ada7..9dd5a1762 100644 --- a/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst +++ b/plugin_tutorials/docs/writing_new_nav2planner_plugin.rst @@ -32,7 +32,7 @@ Tutorial Steps -------------------------------- We will create a simple straight-line planner. -The annotated code in this tutorial can be found in `navigation_tutorials `_ repository as the ``nav2_straightline_planner``. +The annotated code in this tutorial can be found in `navigation_tutorials `_ repository as the ``nav2_straightline_planner``. This package can be considered as a reference for writing planner plugin. Our example plugin inherits from the base class ``nav2_core::GlobalPlanner``. The base class provides 5 pure virtual methods to implement a planner plugin. The plugin will be used by the planner server to compute trajectories. diff --git a/plugin_tutorials/docs/writing_new_navigator_plugin.rst b/plugin_tutorials/docs/writing_new_navigator_plugin.rst index 3eaeda37a..29c3a36cf 100644 --- a/plugin_tutorials/docs/writing_new_navigator_plugin.rst +++ b/plugin_tutorials/docs/writing_new_navigator_plugin.rst @@ -30,7 +30,7 @@ Tutorial Steps 1- Create a new Navigator Plugin -------------------------------- -We will be implementing pure point-to-point navigation behavior. The code in this tutorial can be found in `Nav2's BT Navigator package `_ as the ``NavigateToPoseNavigator``. This package can be considered as a reference for writing your own plugin. +We will be implementing pure point-to-point navigation behavior. The code in this tutorial can be found in `Nav2's BT Navigator package `_ as the ``NavigateToPoseNavigator``. This package can be considered as a reference for writing your own plugin. Our example plugin class ``nav2_bt_navigator::NavigateToPoseNavigator`` inherits from the base class ``nav2_core::BehaviorTreeNavigator``. The base class provides a set of virtual methods to implement a navigator plugin. These methods are called at runtime by the BT Navigator server or as a response to ROS 2 actions to process a navigation request. diff --git a/plugins/index.rst b/plugins/index.rst index a4cc31669..6940557f6 100644 --- a/plugins/index.rst +++ b/plugins/index.rst @@ -27,8 +27,8 @@ Behavior-Tree Navigators | | | (Cartesian or GPS) via a BTs | +----------------------------------+--------------------+-----------------------------------+ -.. _NavigateToPoseNavigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator/src/navigators -.. _NavigateThroughPosesNavigator: https://github.com/ros-planning/navigation2/tree/main/nav2_bt_navigator/src/navigators +.. _NavigateToPoseNavigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator/src/navigators +.. _NavigateThroughPosesNavigator: https://github.com/ros-navigation/navigation2/tree/main/nav2_bt_navigator/src/navigators .. _CoverageNavigator: https://github.com/open-navigation/opennav_coverage/tree/main/opennav_coverage_navigator @@ -71,11 +71,11 @@ Costmap Layers | | | obstacles groups | +--------------------------------+------------------------+----------------------------------+ -.. _Voxel Layer: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d/plugins/voxel_layer.cpp -.. _Static Layer: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d/plugins/static_layer.cpp -.. _Range Layer: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d/plugins/range_sensor_layer.cpp -.. _Inflation Layer: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d/plugins/inflation_layer.cpp -.. _Obstacle Layer: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d/plugins/obstacle_layer.cpp +.. _Voxel Layer: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d/plugins/voxel_layer.cpp +.. _Static Layer: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d/plugins/static_layer.cpp +.. _Range Layer: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d/plugins/range_sensor_layer.cpp +.. _Inflation Layer: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d/plugins/inflation_layer.cpp +.. _Obstacle Layer: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d/plugins/obstacle_layer.cpp .. _Spatio-Temporal Voxel Layer: https://github.com/SteveMacenski/spatio_temporal_voxel_layer/ .. _Non-Persistent Voxel Layer: https://github.com/SteveMacenski/nonpersistent_voxel_layer .. _Denoise Layer: https://github.com/ryzhikovas/navigation2/tree/feature-costmap2d-denoise/nav2_costmap_2d/plugins/denoise_layer.cpp @@ -96,52 +96,47 @@ Costmap Filters | | | behavior to trigger actions. | +--------------------+--------------------+-----------------------------------+ -.. _Keepout Filter: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d/plugins/costmap_filters/keepout_filter.cpp -.. _Speed Filter: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d/plugins/costmap_filters/speed_filter.cpp -.. _Binary Filter: https://github.com/ros-planning/navigation2/tree/main/nav2_costmap_2d/plugins/costmap_filters/binary_filter.cpp +.. _Keepout Filter: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d/plugins/costmap_filters/keepout_filter.cpp +.. _Speed Filter: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d/plugins/costmap_filters/speed_filter.cpp +.. _Binary Filter: https://github.com/ros-navigation/navigation2/tree/main/nav2_costmap_2d/plugins/costmap_filters/binary_filter.cpp Controllers =========== -+--------------------------------+-----------------------+------------------------------------+-----------------------+ -| Plugin Name | Creator | Description | Drivetrain support | -+================================+=======================+====================================+=======================+ -| `DWB Controller`_ | David Lu!! | A highly configurable DWA | Differential, | -| | | implementation with plugin | Omnidirectional, | -| | | interfaces | Legged | -+--------------------------------+-----------------------+------------------------------------+-----------------------+ -| `TEB Controller`_ | Christoph Rösmann | A MPC-like controller suitable | **Ackermann**, Legged,| -| | | for ackermann, differential, and | Omnidirectional, | -| | | holonomic robots. | Differential | -+--------------------------------+-----------------------+------------------------------------+-----------------------+ -| `Regulated Pure Pursuit`_ | Steve Macenski | A service / industrial robot | **Ackermann**, Legged,| -| | | variation on the pure pursuit | Differential | -| | | algorithm with adaptive features. | | -+--------------------------------+-----------------------+------------------------------------+-----------------------+ -| `MPPI Controller`_ | Steve Macenski | A predictive MPC controller with | Differential, Omni, | -| | Aleksei Budyakov | modular & custom cost functions | **Ackermann** | -| | | that can accomplish many tasks. | | -+--------------------------------+-----------------------+------------------------------------+-----------------------+ -| `Rotation Shim Controller`_ | Steve Macenski | A "shim" controller to rotate | Differential, Omni, | -| | | to path heading before passing | model rotate in place | -| | | to main controller for tracking. | | -+--------------------------------+-----------------------+------------------------------------+-----------------------+ -| `Graceful Controller`_ | Alberto Tudela | A controller based on a | Differential | -| | | pose-following control law to | | -| | | generate smooth trajectories. | | -+--------------------------------+-----------------------+------------------------------------+-----------------------+ -| `Vector Pursuit Controller`_ | Black Coffee Robotics | A controller based on the vector | Differential, | -| | | pursuit algorithm useful for | Ackermann, Legged, | -| | | high speed accurate path tracking. | | -+--------------------------------+-----------------------+------------------------------------+-----------------------+ - -.. _Vector Pursuit Controller: https://github.com/blackcoffeerobotics/vector_pursuit_controller -.. _DWB Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_dwb_controller ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| Plugin Name | Creator | Description | Drivetrain support | ++================================+====================+==================================+=======================+ +| `DWB Controller`_ | David Lu!! | A highly configurable DWA | Differential, | +| | | implementation with plugin | Omnidirectional, | +| | | interfaces | Legged | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `TEB Controller`_ | Christoph Rösmann | A MPC-like controller suitable | **Ackermann**, Legged,| +| | | for ackermann, differential, and | Omnidirectional, | +| | | holonomic robots. | Differential | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `Regulated Pure Pursuit`_ | Steve Macenski | A service / industrial robot | **Ackermann**, Legged,| +| | | variation on the pure pursuit | Differential | +| | | algorithm with adaptive features.| | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `MPPI Controller`_ | Steve Macenski | A predictive MPC controller with | Differential, Omni, | +| | Aleksei Budyakov | modular & custom cost functions | **Ackermann** | +| | | that can accomplish many tasks. | | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `Rotation Shim Controller`_ | Steve Macenski | A "shim" controller to rotate | Differential, Omni, | +| | | to path heading before passing | model rotate in place | +| | | to main controller for tracking.| | ++--------------------------------+--------------------+----------------------------------+-----------------------+ +| `Graceful Controller`_ | Alberto Tudela | A controller based on a | Differential | +| | | pose-following control law to | | +| | | generate smooth trajectories. | | ++--------------------------------+--------------------+----------------------------------+-----------------------+ + +.. _DWB Controller: https://github.com/ros-navigation/navigation2/tree/main/nav2_dwb_controller .. _TEB Controller: https://github.com/rst-tu-dortmund/teb_local_planner -.. _Regulated Pure Pursuit: https://github.com/ros-planning/navigation2/tree/main/nav2_regulated_pure_pursuit_controller -.. _Rotation Shim Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_rotation_shim_controller -.. _MPPI Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_mppi_controller -.. _Graceful Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_graceful_controller +.. _Regulated Pure Pursuit: https://github.com/ros-navigation/navigation2/tree/main/nav2_regulated_pure_pursuit_controller +.. _Rotation Shim Controller: https://github.com/ros-navigation/navigation2/tree/main/nav2_rotation_shim_controller +.. _MPPI Controller: https://github.com/ros-navigation/navigation2/tree/main/nav2_mppi_controller +.. _Graceful Controller: https://github.com/ros-navigation/navigation2/tree/main/nav2_graceful_controller Planners ======== @@ -186,11 +181,11 @@ Planners | | | 2D holonomic particle | | +---------------------------+---------------------------------------+------------------------------+---------------------+ -.. _NavFn Planner: https://github.com/ros-planning/navigation2/tree/main/nav2_navfn_planner -.. _SmacPlannerHybrid: https://github.com/ros-planning/navigation2/tree/main/nav2_smac_planner -.. _SmacPlanner2D: https://github.com/ros-planning/navigation2/tree/main/nav2_smac_planner -.. _ThetaStarPlanner: https://github.com/ros-planning/navigation2/tree/main/nav2_theta_star_planner -.. _SmacPlannerLattice: https://github.com/ros-planning/navigation2/tree/main/nav2_smac_planner +.. _NavFn Planner: https://github.com/ros-navigation/navigation2/tree/main/nav2_navfn_planner +.. _SmacPlannerHybrid: https://github.com/ros-navigation/navigation2/tree/main/nav2_smac_planner +.. _SmacPlanner2D: https://github.com/ros-navigation/navigation2/tree/main/nav2_smac_planner +.. _ThetaStarPlanner: https://github.com/ros-navigation/navigation2/tree/main/nav2_theta_star_planner +.. _SmacPlannerLattice: https://github.com/ros-navigation/navigation2/tree/main/nav2_smac_planner Smoothers @@ -219,9 +214,9 @@ Smoothers | | | path. | +---------------------------+---------------------------------------+------------------------------+ -.. _Simple Smoother: https://github.com/ros-planning/navigation2/tree/main/nav2_smoother -.. _Constrained Smoother: https://github.com/ros-planning/navigation2/tree/main/nav2_constrained_smoother -.. _Savitzky-Golay Smoother: https://github.com/ros-planning/navigation2/tree/main/nav2_smoother +.. _Simple Smoother: https://github.com/ros-navigation/navigation2/tree/main/nav2_smoother +.. _Constrained Smoother: https://github.com/ros-navigation/navigation2/tree/main/nav2_constrained_smoother +.. _Savitzky-Golay Smoother: https://github.com/ros-navigation/navigation2/tree/main/nav2_smoother Behaviors ========= @@ -256,12 +251,12 @@ Behaviors | | | prevent collisions. | +----------------------+------------------------+----------------------------------+ -.. _Back Up: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors/plugins -.. _Spin: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors/plugins -.. _Wait: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors/plugins -.. _Drive On Heading: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors/plugins -.. _Clear Costmap: https://github.com/ros-planning/navigation2/blob/main/nav2_costmap_2d/src/clear_costmap_service.cpp -.. _Assisted Teleop: https://github.com/ros-planning/navigation2/tree/main/nav2_behaviors/plugins +.. _Back Up: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors/plugins +.. _Spin: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors/plugins +.. _Wait: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors/plugins +.. _Drive On Heading: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors/plugins +.. _Clear Costmap: https://github.com/ros-navigation/navigation2/blob/main/nav2_costmap_2d/src/clear_costmap_service.cpp +.. _Assisted Teleop: https://github.com/ros-navigation/navigation2/tree/main/nav2_behaviors/plugins Waypoint Task Executors ======================= @@ -284,9 +279,9 @@ Waypoint Task Executors | | | waypoint. | +---------------------------------+------------------------+----------------------------------+ -.. _WaitAtWaypoint: https://github.com/ros-planning/navigation2/tree/main/nav2_waypoint_follower/plugins/wait_at_waypoint.cpp -.. _PhotoAtWaypoint: https://github.com/ros-planning/navigation2/tree/main/nav2_waypoint_follower/plugins/photo_at_waypoint.cpp -.. _InputAtWaypoint: https://github.com/ros-planning/navigation2/tree/main/nav2_waypoint_follower/plugins/input_at_waypoint.cpp +.. _WaitAtWaypoint: https://github.com/ros-navigation/navigation2/tree/main/nav2_waypoint_follower/plugins/wait_at_waypoint.cpp +.. _PhotoAtWaypoint: https://github.com/ros-navigation/navigation2/tree/main/nav2_waypoint_follower/plugins/photo_at_waypoint.cpp +.. _InputAtWaypoint: https://github.com/ros-navigation/navigation2/tree/main/nav2_waypoint_follower/plugins/input_at_waypoint.cpp Goal Checkers ============= @@ -305,8 +300,8 @@ Goal Checkers | | | and velocity threshold. | +---------------------------------+------------------------+----------------------------------+ -.. _SimpleGoalChecker: https://github.com/ros-planning/navigation2/blob/main/nav2_controller/plugins/simple_goal_checker.cpp -.. _StoppedGoalChecker: https://github.com/ros-planning/navigation2/blob/main/nav2_controller/plugins/stopped_goal_checker.cpp +.. _SimpleGoalChecker: https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/plugins/simple_goal_checker.cpp +.. _StoppedGoalChecker: https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/plugins/stopped_goal_checker.cpp Progress Checkers ================= @@ -325,8 +320,8 @@ Progress Checkers | | | to make progress towards a goal | +---------------------------------+------------------------+----------------------------------+ -.. _SimpleProgressChecker: https://github.com/ros-planning/navigation2/blob/main/nav2_controller/plugins/simple_progress_checker.cpp -.. _PoseProgressChecker: https://github.com/ros-planning/navigation2/blob/main/nav2_controller/plugins/pose_progress_checker.cpp +.. _SimpleProgressChecker: https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/plugins/simple_progress_checker.cpp +.. _PoseProgressChecker: https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/plugins/pose_progress_checker.cpp Behavior Tree Nodes @@ -425,36 +420,36 @@ Behavior Tree Nodes | `Undock Robot Action`_ | Steve Macenski | Calls undock robot action | +---------------------------------------------+---------------------+------------------------------------------+ -.. _Back Up Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/back_up_action.cpp -.. _Drive On Heading Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/drive_on_heading_action.cpp -.. _Assisted Teleop Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/assisted_teleop_action.cpp -.. _Clear Entire Costmap Service: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/clear_costmap_service.cpp -.. _Clear Costmap Except Region Service: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/clear_costmap_service.cpp -.. _Clear Costmap Around Robot Service: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/clear_costmap_service.cpp -.. _Compute Path to Pose Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/compute_path_to_pose_action.cpp -.. _Smooth Path Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/smooth_path_action.cpp -.. _Follow Path Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/follow_path_action.cpp -.. _Navigate to Pose Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/navigate_to_pose_action.cpp -.. _Reinitalize Global Localization Service: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/reinitialize_global_localization_service.cpp -.. _Spin Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/spin_action.cpp -.. _Wait Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/wait_action.cpp -.. _Truncate Path: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/truncate_path_action.cpp -.. _Truncate Path Local: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/truncate_path_local_action.cpp -.. _Planner Selector: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/planner_selector_node.cpp -.. _Controller Selector: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/controller_selector_node.cpp -.. _Goal Checker Selector: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/goal_checker_selector_node.cpp -.. _Smoother Selector: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/smoother_selector_node.cpp -.. _Progress Checker Selector: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/progress_checker_selector_node.cpp -.. _Navigate Through Poses: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/navigate_through_poses_action.cpp -.. _Remove Passed Goals: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/remove_passed_goals_action.cpp -.. _Remove In Collision Goals: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/remove_in_collision_goals_action.cpp -.. _Compute Path Through Poses: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/compute_path_through_poses_action.cpp -.. _Cancel Control Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/controller_cancel_node.cpp -.. _Cancel BackUp Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/back_up_cancel_node.cpp -.. _Cancel Spin Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/spin_cancel_node.cpp -.. _Cancel Wait Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/wait_cancel_node.cpp -.. _Cancel Drive on Heading Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/drive_on_heading_cancel_node.cpp -.. _Cancel Assisted Teleop Action: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/action/assisted_teleop_cancel_node.cpp +.. _Back Up Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/back_up_action.cpp +.. _Drive On Heading Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/drive_on_heading_action.cpp +.. _Assisted Teleop Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/assisted_teleop_action.cpp +.. _Clear Entire Costmap Service: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/clear_costmap_service.cpp +.. _Clear Costmap Except Region Service: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/clear_costmap_service.cpp +.. _Clear Costmap Around Robot Service: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/clear_costmap_service.cpp +.. _Compute Path to Pose Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/compute_path_to_pose_action.cpp +.. _Smooth Path Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/smooth_path_action.cpp +.. _Follow Path Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/follow_path_action.cpp +.. _Navigate to Pose Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/navigate_to_pose_action.cpp +.. _Reinitalize Global Localization Service: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/reinitialize_global_localization_service.cpp +.. _Spin Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/spin_action.cpp +.. _Wait Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/wait_action.cpp +.. _Truncate Path: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/truncate_path_action.cpp +.. _Truncate Path Local: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/truncate_path_local_action.cpp +.. _Planner Selector: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/planner_selector_node.cpp +.. _Controller Selector: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/controller_selector_node.cpp +.. _Goal Checker Selector: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/goal_checker_selector_node.cpp +.. _Smoother Selector: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/smoother_selector_node.cpp +.. _Progress Checker Selector: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/progress_checker_selector_node.cpp +.. _Navigate Through Poses: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/navigate_through_poses_action.cpp +.. _Remove Passed Goals: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/remove_passed_goals_action.cpp +.. _Remove In Collision Goals: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/remove_in_collision_goals_action.cpp +.. _Compute Path Through Poses: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/compute_path_through_poses_action.cpp +.. _Cancel Control Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/controller_cancel_node.cpp +.. _Cancel BackUp Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/back_up_cancel_node.cpp +.. _Cancel Spin Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/spin_cancel_node.cpp +.. _Cancel Wait Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/wait_cancel_node.cpp +.. _Cancel Drive on Heading Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/drive_on_heading_cancel_node.cpp +.. _Cancel Assisted Teleop Action: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/action/assisted_teleop_cancel_node.cpp .. _Cancel Complete Coverage Action: https://github.com/open-navigation/opennav_coverage/blob/main/opennav_coverage_bt/src/cancel_complete_coverage_path.cpp .. _Compute Complete Coverage Path Action: https://github.com/open-navigation/opennav_coverage/blob/main/opennav_coverage_bt/src/compute_complete_coverage_path.cpp .. _Get Pose From Path Action: https://github.com/ros-navigation/navigation2/blob/main/nav2_behavior_tree/plugins/action/get_pose_from_path_action.cpp @@ -535,22 +530,22 @@ Behavior Tree Nodes | | | is charging. | +------------------------------------+--------------------+------------------------+ -.. _Goal Reached Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/goal_reached_condition.cpp -.. _Goal Updated Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/goal_updated_condition.cpp +.. _Goal Reached Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/goal_reached_condition.cpp +.. _Goal Updated Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/goal_updated_condition.cpp .. _Globally Updated Goal Condition: https://github.com/navigation2/blob/replanning/nav2_behavior_tree/plugins/condition/globally_updated_goal_condition.cpp -.. _Initial Pose received Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/initial_pose_received_condition.cpp -.. _Is Stuck Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/is_stuck_condition.cpp -.. _Transform Available Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/transform_available_condition.cpp -.. _Distance Traveled Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/distance_traveled_condition.cpp -.. _Time Expired Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/time_expired_condition.cpp -.. _Is Battery Low Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/is_battery_low_condition.cpp +.. _Initial Pose received Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/initial_pose_received_condition.cpp +.. _Is Stuck Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/is_stuck_condition.cpp +.. _Transform Available Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/transform_available_condition.cpp +.. _Distance Traveled Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/distance_traveled_condition.cpp +.. _Time Expired Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/time_expired_condition.cpp +.. _Is Battery Low Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/is_battery_low_condition.cpp .. _Is Path Valid Condition: https://github.com/navigation2/blob/replanning/nav2_behavior_tree/plugins/condition/is_path_valid_condition.cpp -.. _Path Expiring Timer: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/path_expiring_timer_condition.cpp -.. _Are Error Codes Present: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/are_error_codes_present_condition.cpp -.. _Would A Controller Recovery Help: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/would_a_controller_recovery_help.cpp -.. _Would A Planner Recovery Help: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/would_a_planner_recovery_help.cpp -.. _Would A Smoother Recovery Help: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/would_a_smoother_recovery_help.cpp -.. _Is Battery Charging Condition: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/condition/is_battery_charging_condition.cpp +.. _Path Expiring Timer: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/path_expiring_timer_condition.cpp +.. _Are Error Codes Present: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/are_error_codes_present_condition.cpp +.. _Would A Controller Recovery Help: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/would_a_controller_recovery_help.cpp +.. _Would A Planner Recovery Help: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/would_a_planner_recovery_help.cpp +.. _Would A Smoother Recovery Help: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/would_a_smoother_recovery_help.cpp +.. _Is Battery Charging Condition: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/condition/is_battery_charging_condition.cpp +--------------------------+---------------------+----------------------------------+ | Decorator Plugin Name | Creator | Description | @@ -576,12 +571,12 @@ Behavior Tree Nodes | | | on approach to the goal | +--------------------------+---------------------+----------------------------------+ -.. _Rate Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/rate_controller.cpp -.. _Distance Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/distance_controller.cpp -.. _Speed Controller: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/speed_controller.cpp -.. _Goal Updater: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/goal_updater_node.cpp -.. _Single Trigger: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/single_trigger_node.cpp -.. _PathLongerOnApproach: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/path_longer_on_approach.cpp +.. _Rate Controller: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/rate_controller.cpp +.. _Distance Controller: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/distance_controller.cpp +.. _Speed Controller: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/speed_controller.cpp +.. _Goal Updater: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/goal_updater_node.cpp +.. _Single Trigger: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/single_trigger_node.cpp +.. _PathLongerOnApproach: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/decorator/path_longer_on_approach.cpp +-----------------------+------------------------+----------------------------------+ | Control Plugin Name | Creator | Description | @@ -601,6 +596,6 @@ Behavior Tree Nodes | | | a result and move on to ``i+1`` | +-----------------------+------------------------+----------------------------------+ -.. _Pipeline Sequence: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/control/pipeline_sequence.cpp -.. _Recovery: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/control/recovery_node.cpp -.. _Round Robin: https://github.com/ros-planning/navigation2/tree/main/nav2_behavior_tree/plugins/control/round_robin_node.cpp +.. _Pipeline Sequence: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/control/pipeline_sequence.cpp +.. _Recovery: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/control/recovery_node.cpp +.. _Round Robin: https://github.com/ros-navigation/navigation2/tree/main/nav2_behavior_tree/plugins/control/round_robin_node.cpp diff --git a/roadmap/roadmap.rst b/roadmap/roadmap.rst index f4a5aec28..bc0205341 100644 --- a/roadmap/roadmap.rst +++ b/roadmap/roadmap.rst @@ -85,13 +85,13 @@ Iron Roadmap | | | +--------------------------------+------------------------+ -.. _Smac Planner Improvements: https://github.com/ros-planning/navigation2/issues/3172 -.. _Pluginize Navigators: https://github.com/ros-planning/navigation2/issues/3335 -.. _MPPI Controller: https://github.com/ros-planning/navigation2/pull/3350 -.. _Route Graph Planner: https://github.com/ros-planning/navigation2/issues/2229 -.. _Velocity Smoother: https://github.com/ros-planning/navigation2/pull/2964 -.. _Fuse Migration: https://github.com/ros-planning/navigation2/issues/2598 -.. _Ignition Migration: https://github.com/ros-planning/navigation2/issues/2997 +.. _Smac Planner Improvements: https://github.com/ros-navigation/navigation2/issues/3172 +.. _Pluginize Navigators: https://github.com/ros-navigation/navigation2/issues/3335 +.. _MPPI Controller: https://github.com/ros-navigation/navigation2/pull/3350 +.. _Route Graph Planner: https://github.com/ros-navigation/navigation2/issues/2229 +.. _Velocity Smoother: https://github.com/ros-navigation/navigation2/pull/2964 +.. _Fuse Migration: https://github.com/ros-navigation/navigation2/issues/2598 +.. _Ignition Migration: https://github.com/ros-navigation/navigation2/issues/2997 Humble Roadmap ************** @@ -136,11 +136,11 @@ Humble Roadmap | | | +--------------------------------+------------------------+ -.. _Smac Lattice Planner: https://github.com/ros-planning/navigation2/issues/1710 -.. _Nav2 1 Node Per Server: https://github.com/ros-planning/navigation2/issues/816 -.. _Safety Collision Nodes: https://github.com/ros-planning/navigation2/issues/1899 -.. _Fix Min Range Bug: https://github.com/ros-planning/navigation2/pull/2460 -.. _Complete First Time Guide: https://github.com/ros-planning/navigation2/issues/1589 -.. _Rotation Shim Controller: https://github.com/ros-planning/navigation2/pull/2718 -.. _Move Development from Master to Rolling: https://github.com/ros-planning/navigation2/issues/2337 -.. _Dynamic Composition: https://github.com/ros-planning/navigation2/issues/2147 +.. _Smac Lattice Planner: https://github.com/ros-navigation/navigation2/issues/1710 +.. _Nav2 1 Node Per Server: https://github.com/ros-navigation/navigation2/issues/816 +.. _Safety Collision Nodes: https://github.com/ros-navigation/navigation2/issues/1899 +.. _Fix Min Range Bug: https://github.com/ros-navigation/navigation2/pull/2460 +.. _Complete First Time Guide: https://github.com/ros-navigation/navigation2/issues/1589 +.. _Rotation Shim Controller: https://github.com/ros-navigation/navigation2/pull/2718 +.. _Move Development from Master to Rolling: https://github.com/ros-navigation/navigation2/issues/2337 +.. _Dynamic Composition: https://github.com/ros-navigation/navigation2/issues/2147 diff --git a/setup_guides/footprint/setup_footprint.rst b/setup_guides/footprint/setup_footprint.rst index 36dcfa1eb..00d1daa75 100644 --- a/setup_guides/footprint/setup_footprint.rst +++ b/setup_guides/footprint/setup_footprint.rst @@ -25,12 +25,12 @@ Configuring the Robot's Footprint ********************************* In this section, we will configure the footprint of ``sam_bot`` such that ``footprint`` (polygon) is used for the local costmap and ``robot_radius`` (circular) is used for the global costmap. We will utilize the default configuration file of Nav2 with a modified footprint parameter for the global and local costmaps. -.. note:: The complete source code for ``sam_bot`` can be found in `navigation2_tutorials `_ repository. +.. note:: The complete source code for ``sam_bot`` can be found in `navigation2_tutorials `_ repository. -Under the ``config`` directory, create a new file named ``nav2_params.yaml``. Next, copy the contents of `config/nav2_params.yaml `_ and paste them into the newly created file. The contents of `config/nav2_params.yaml `_ are copied from the default configuration file of Nav2 but with changes in the ``footprint`` and ``robot_radius`` parameters to match the shape of ``sam_bot``. +Under the ``config`` directory, create a new file named ``nav2_params.yaml``. Next, copy the contents of `config/nav2_params.yaml `_ and paste them into the newly created file. The contents of `config/nav2_params.yaml `_ are copied from the default configuration file of Nav2 but with changes in the ``footprint`` and ``robot_radius`` parameters to match the shape of ``sam_bot``. .. seealso:: - The default configuration file for Nav2 can be found in the official `Navigation2 repository `_. + The default configuration file for Nav2 can be found in the official `Navigation2 repository `_. Below is the code snippet from ``nav2_params.yaml`` defining the local costmap footprint. In this configuration file, the ``footprint`` parameter of the local costmap has already been set with a rectangular-shaped footprint. This box is centered at the ``base_link`` frame of ``sam_bot``. @@ -54,7 +54,7 @@ Build, Run and Verification *************************** We will now confirm that we have properly set up ``sam_bot``'s footprint. -First, we launch `launch/display.launch.py `_ to launch the robot state publisher, spawn ``sam_bot`` in Gazebo, and visualize ``sam_bot`` and its footprint in Rviz. The robot state publisher publishes the ``base_link`` => ``sensors`` transforms defined in ``sam_bot``'s URDF, while Gazebo's differential drive plugin publishes the ``odom`` => ``base_link`` transform. Open a new terminal and execute the lines below. +First, we launch `launch/display.launch.py `_ to launch the robot state publisher, spawn ``sam_bot`` in Gazebo, and visualize ``sam_bot`` and its footprint in Rviz. The robot state publisher publishes the ``base_link`` => ``sensors`` transforms defined in ``sam_bot``'s URDF, while Gazebo's differential drive plugin publishes the ``odom`` => ``base_link`` transform. Open a new terminal and execute the lines below. .. code-block:: shell diff --git a/setup_guides/odom/setup_odom.rst b/setup_guides/odom/setup_odom.rst index 2b4d7a007..2f49c54df 100644 --- a/setup_guides/odom/setup_odom.rst +++ b/setup_guides/odom/setup_odom.rst @@ -4,7 +4,7 @@ Setting Up Odometry In this guide, we will be looking at how to integrate our robot's odometry system with Nav2. First we will provide a brief introduction on odometry, plus the necessary messages and transforms that need to be published for Nav2 to function correctly. Next, we will show how to setup odometry with two different cases. In the first case, we will show how to setup an odometry system for a robot with already available wheel encoders. In the second case, we will build a demo that simulates a functioning odometry system on ``sam_bot`` (the robot that we built in the previous section) using Gazebo. Afterwards, we will discuss how various sources of odometry can be fused to provide a smoothed odometry using the ``robot_localization`` package. Lastly, we will also show how to publish the ``odom`` => ``base_link`` transform using ``robot_localization``. .. seealso:: - The complete source code in this tutorial can be found in `navigation2_tutorials `_ repository under the ``sam_bot_description`` package. Note that the repository contains the full code after accomplishing all the tutorials in this guide. + The complete source code in this tutorial can be found in `navigation2_tutorials `_ repository under the ``sam_bot_description`` package. Note that the repository contains the full code after accomplishing all the tutorials in this guide. Odometry Introduction ********************* @@ -62,7 +62,7 @@ For other types of sensors such as IMU, VIO, etc, their respective ROS drivers s Simulating an Odometry System using Gazebo ****************************************** -In this section, we will be using Gazebo to simulate the odometry system of ``sam_bot``, the robot that we built in the previous section of this tutorial series. You may go through that guide first or grab the `complete source here `_. +In this section, we will be using Gazebo to simulate the odometry system of ``sam_bot``, the robot that we built in the previous section of this tutorial series. You may go through that guide first or grab the `complete source here `_. .. note:: If you are working on your own physical robot and have already set up your odometry sensors, you may opt to skip this section and head onto the next one where we fuse IMU and odometry messages to provide a smooth ``odom`` => ``base_link`` transformation. @@ -228,7 +228,7 @@ To include this plugin in our URDF, add the following lines after the ```_, to spawn ``sam_bot`` in Gazebo. Since we will be simulating our robot, we can remove the GUI for the joint state publisher by deleting the following lines inside the ``generate_launch_description()``: +We will now edit our launch file, `launch/display.launch.py `_, to spawn ``sam_bot`` in Gazebo. Since we will be simulating our robot, we can remove the GUI for the joint state publisher by deleting the following lines inside the ``generate_launch_description()``: .. code-block:: shell @@ -259,7 +259,7 @@ Remove the condition and parameters. Add arguments to the `joint_state_publisher condition=launch.conditions.UnlessCondition(LaunchConfiguration('gui')) # Remove this line ) -Next, open `package.xml `_ and delete the line: +Next, open `package.xml `_ and delete the line: .. code-block:: shell @@ -271,7 +271,7 @@ To launch Gazebo, add the following before the ``joint_state_publisher_node,`` l launch.actions.ExecuteProcess(cmd=['gazebo', '--verbose', '-s', 'libgazebo_ros_init.so', '-s', 'libgazebo_ros_factory.so'], output='screen'), -We will now add a node that spawns ``sam_bot`` in Gazebo. Open `launch/display.launch.py `_ again and paste the following lines before the ``return launch.LaunchDescription([`` line. +We will now add a node that spawns ``sam_bot`` in Gazebo. Open `launch/display.launch.py `_ again and paste the following lines before the ``return launch.LaunchDescription([`` line. .. code-block:: shell diff --git a/setup_guides/sensors/setup_sensors.rst b/setup_guides/sensors/setup_sensors.rst index 25ad203cd..54dd68c66 100644 --- a/setup_guides/sensors/setup_sensors.rst +++ b/setup_guides/sensors/setup_sensors.rst @@ -65,7 +65,7 @@ To be able to follow the rest of this section, make sure that you have properly Adding Gazebo Plugins to a URDF =============================== -Let us first add a lidar sensor to ``sam_bot``. Open the URDF file, `src/description/sam_bot_description.urdf `_ and paste the following lines before the ```` tag. +Let us first add a lidar sensor to ``sam_bot``. Open the URDF file, `src/description/sam_bot_description.urdf `_ and paste the following lines before the ```` tag. .. code-block:: xml :lineno-start: 251 @@ -221,9 +221,9 @@ Launch and Build Files To verify that the sensors are set up properly and that they can see objects in our environment, let us launch ``sam_bot`` in a Gazebo world with objects. Let us create a Gazebo world with a single cube and a single sphere that are within the range of ``sam_bot``'s sensors so we can verify if it can see the objects correctly. -To create the world, create a directory named ``world`` at the root of your project and create a file named ``my_world.sdf`` inside the ``world`` folder . Then copy the contents of `world/my_world.sdf `_ and paste them inside ``my_world.sdf``. +To create the world, create a directory named ``world`` at the root of your project and create a file named ``my_world.sdf`` inside the ``world`` folder . Then copy the contents of `world/my_world.sdf `_ and paste them inside ``my_world.sdf``. -Now, let us edit our launch file, `launch/display.launch.py `_, to launch Gazebo with the world we just created. First, add the path of ``my_world.sdf`` by adding the following lines inside the ``generate_launch_description()``: +Now, let us edit our launch file, `launch/display.launch.py `_, to launch Gazebo with the world we just created. First, add the path of ``my_world.sdf`` by adding the following lines inside the ``generate_launch_description()``: .. code-block:: shell @@ -235,7 +235,7 @@ Lastly, add the world path in the ``launch.actions.ExecuteProcess(cmd=['gazebo', launch.actions.ExecuteProcess(cmd=['gazebo', '--verbose', '-s', 'libgazebo_ros_init.so', '-s', 'libgazebo_ros_factory.so', world_path], output='screen'), -We also have to add the ``world`` directory to our ``CMakeLists.txt`` file. Open `CmakeLists.txt `_ and append the ``world`` directory inside the install(DIRECTORY...), as shown in the snippet below. +We also have to add the ``world`` directory to our ``CMakeLists.txt`` file. Open `CmakeLists.txt `_ and append the ``world`` directory inside the install(DIRECTORY...), as shown in the snippet below. .. code-block:: shell diff --git a/setup_guides/urdf/setup_urdf.rst b/setup_guides/urdf/setup_urdf.rst index 9eec74054..882d982e9 100644 --- a/setup_guides/urdf/setup_urdf.rst +++ b/setup_guides/urdf/setup_urdf.rst @@ -6,7 +6,7 @@ Setting Up The URDF For this guide, we will be creating the Unified Robot Description Format (URDF) file for a simple differential drive robot to give you hands-on experience on working with URDF. We will also setup the robot state publisher and visualize our model in RVIZ. Lastly, we will be adding some kinematic properties to our robot URDF to prepare it for simulation purposes. These steps are necessary to represent all the sensor, hardware, and robot transforms of your robot for use in navigation. .. seealso:: - The complete source code in this tutorial can be found in `navigation2_tutorials `_ repository under the ``sam_bot_description`` package. Note that the repository contains the full code after accomplishing all the tutorials in this guide. + The complete source code in this tutorial can be found in `navigation2_tutorials `_ repository under the ``sam_bot_description`` package. Note that the repository contains the full code after accomplishing all the tutorials in this guide. URDF and the Robot State Publisher ================================== diff --git a/substitutions.txt b/substitutions.txt index d0c86b873..ce3f93987 100644 --- a/substitutions.txt +++ b/substitutions.txt @@ -5,19 +5,19 @@ .. |LPN| replace:: Nav2 -.. _project repo: https://github.com/ros-planning/navigation2 +.. _project repo: https://github.com/ros-navigation/navigation2 -.. _documentation repo: https://github.com/ros-planning/docs.nav2.org/doc +.. _documentation repo: https://github.com/ros-navigation/docs.nav2.org/doc -.. _nav2_bringup pkg: https://github.com/ros-planning/navigation2/tree/main/nav2_bringup/bringup +.. _nav2_bringup pkg: https://github.com/ros-navigation/navigation2/tree/main/nav2_bringup/bringup -.. _nav2_params file: https://github.com/ros-planning/navigation2/blob/main/nav2_bringup/bringup/params/nav2_params.yaml +.. _nav2_params file: https://github.com/ros-navigation/navigation2/blob/main/nav2_bringup/bringup/params/nav2_params.yaml -.. _documentation site: https://rosplanning.github.io/docs.nav2.org/ +.. _documentation site: https://docs.nav2.org/ -.. _project website: https://rosplanning.github.io/navigation2/ +.. _project website: https://nav2.org -.. |PP| replace:: https://github.com/ros-planning/navigation2/blob/main +.. |PP| replace:: https://github.com/ros-navigation/navigation2/blob/main .. _`ROS 2 binary packages`: https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debians.html diff --git a/tuning/index.rst b/tuning/index.rst index 5e9495e89..2bdd1adce 100644 --- a/tuning/index.rst +++ b/tuning/index.rst @@ -171,4 +171,4 @@ Within ``nav2_bringup``, there is a main entryfile ``tb3_simulation_launch.py``. Other Pages We'd Love To Offer ============================== -If you are willing to chip in, some ideas are in https://github.com/ros-planning/docs.nav2.org/issues/204, but we'd be open to anything you think would be insightful! +If you are willing to chip in, some ideas are in https://github.com/ros-navigation/docs.nav2.org/issues/204, but we'd be open to anything you think would be insightful! diff --git a/tutorials/docs/adding_a_nav2_task_server.rst b/tutorials/docs/adding_a_nav2_task_server.rst index 9f8e78e9a..1161215bc 100644 --- a/tutorials/docs/adding_a_nav2_task_server.rst +++ b/tutorials/docs/adding_a_nav2_task_server.rst @@ -1,200 +1,200 @@ -.. _adding_a_nav2_task_server: - -Adding a New Nav2 Task Server -############################# - -A nav2 task server consists of server side logic to complete different types of requests, usually called by the autonomy system or through the Behavior Tree Navigator. In this guide, we will discuss the core components needed to add a new task server to Nav2 (ex. Controller, Behavior, Smoother, Planner Servers). Namely, how to set up your new Lifecycle-Component Node for launch and state management and the communication of semantically meaningful error codes (if necessary). - -While this tutorial does not cover how to add the complementary Behavior Tree Node to interact with this new Task Server, that is covered at length in :ref:`writing_new_nbt_plugin` so this Task Server can be invoked in the BTs in BT Navigator. - -If you've created a new Task Server that may have general reuse for the community, consider contacting the maintainers to add it to the Nav2 project! Nav2 gets better by contributions by users like you! - - - -Lifecycle Nodes -*************** - -The Lifecycle node is the first key component of a nav2 task server. Lifecycle nodes were introduced in ROS 2 to systematically manage the bringup and shutdown of the different nodes involved in the robot's operation. The use of Lifecycle nodes ensures that all nodes are successfully instantiated before they begin their execution and Nav2 shuts down all nodes if there is any unresponsive node. - - -Lifecycle nodes contain state machine transitions that enable deterministic behavior in ROS 2 servers. The Lifecycle node transitions in Nav2 are handled by the ``Lifecycle Manager``. The Lifecycle Manager transitions the states of the Lifecycle nodes and provides greater control over the state of a system. - - -The primary states of a Lifecycle node are ``Unconfigured``, ``Inactive``, ``Active``, and ``Finalized``. A Lifecycle node starts in an ``Unconfigured`` state after being instantiated. The Lifecycle Manager transitions a node from ``Unconfigured`` to ``Inactive`` by implementing the ``Configurating`` transition. The ``Configurating`` transition sets up all configuration parameters and prepares any required setup such as memory allocation and the set up of the static publication and subscription topics. A node in the ``Inactive`` state is allowed to reconfigure its parameters and but cannot perform any processing. From the ``Inactive`` state, the Lifecycle Manager implements the ``Activating`` transition state to transition the node from ``Inactive`` to ``Active``, which is the main state. A node in the ``Active`` state is allowed to perform any processing operation. In case a node crashes, the Lifecycle Manager shuts down the system to prevent any critical failures. On shutdown, the necessary cleanup operations are performed and the nodes are transitioned to the ``Finalized`` state via ``Deactivating``, ``CleaningUp``, and ``ShuttingDown`` transition states. - -.. seealso:: - For more information on Lifecycle management, see the article on `Managed Nodes `_. - -You may wish to integrate your own nodes into the Nav2 framework or add new lifecycle nodes to your system. As an example, we will add a new notional lifecycle node ``sensor_driver``, and have it be controlled via the Nav2 Lifecycle Manager to ensure sensor feeds are available before activating navigation. You can do so by adding a ``sensor_driver`` node in your launch file and adding it to the list of nodes to be activated by the ``lifecycle_manager`` before navigation, as shown in the example below. - -.. code-block:: python - - lifecycle_nodes = ['sensor_driver', - 'controller_server', - 'smoother_server', - 'planner_server', - 'behavior_server', - 'bt_navigator', - 'waypoint_follower'] - - ... - - Node( - package='nav2_sensor_driver', - executable='sensor_driver', - name='sensor_driver', - output='screen', - parameters=[configured_params], - remappings=remappings), - - Node( - package='nav2_lifecycle_manager', - executable='lifecycle_manager', - name='lifecycle_manager_navigation', - output='screen', - parameters=[{'autostart': autostart}, - {'node_names': lifecycle_nodes}]), - - -In the snippet above, the nodes to be handled by the Lifecycle Manager are set using the ``node_names`` parameter. The ``node_names`` parameter takes in an ordered list of nodes to bringup through the Lifecycle transition. As shown in the snippet, the ``node_names`` parameter takes in ``lifecycle_nodes`` which contains the list of nodes to be added to the Lifecycle Manager. The Lifecycle Manager implements bringup transitions (``Configuring`` and ``Activating``) to the nodes one-by-one and in order, while the nodes are processed in reverse order for shutdown transitions. Hence, the ``sensor_driver`` is listed first before the other navigation servers so that the sensor data is available before the navigation servers are activated. - - - -Two other parameters of the Lifecycle Manager are ``autostart`` and ``bond_timeout``. Set ``autostart`` to ``true`` if you want to set the transition nodes to the ``Active`` state on startup. Otherwise, you will need to manually trigger Lifecycle Manager to transition up the system. The ``bond_timeout`` sets the waiting time to decide when to transition down all of the nodes if a node is not responding. - -.. note:: - More information on Lifecycle Manager parameters can be found in the `Configuration Guide of Lifecycle Manager `_ - - -Composition -*********** - -Composition is the second key component nav2 task servers that was introduced to reduce the memory and CPU resources by putting multiple nodes in a single process. In Nav2, Composition can be used to compose all Nav2 nodes in a single process instead of launching them separately. This is useful for deployment on embedded systems where developers need to optimize resource usage. - -.. seealso:: - More information on Composition can be found `here `_. - -In the following section, we give an example on how to add a new Nav2 server, which we notionally call the ``route_server``, to our system. - - -We make use of the launch files to compose different servers into a single process. The process is established by the ``ComposableNodeContainer`` container that is populated with composition nodes via ``ComposableNode``. This container can then be launched and used the same as any other Nav2 node. - -1. Add a new ``ComposableNode()`` instance in your launch file pointing to the component container of your choice. - - .. code-block:: python - - container = ComposableNodeContainer( - name='my_container', - namespace='', - package='rclcpp_components', - executable='component_container', - composable_node_descriptions=[ - ComposableNode( - package='nav2_route_server', - plugin='nav2_route_server::RouteServer', - name='nav2_route_server'), - ], - output='screen', - ) - - .. seealso:: - See example in composition demo's `composition_demo.launch.py `_. - -2. Add the package containing the server to your ``package.xml`` file. - - .. code-block:: xml - - nav2_route_server - - -Error codes -*********** - -Your nav2 task server may also wish to return a 'error_code' in its action response (though not required). If there are semantically meaningful and actionable types of failures for your system, this is a systemic way to communicate those failures which may be automatically aggregated into the responses of the navigation system to your application. - -It is important to note that error codes from 0-9999 are reserved for internal nav2 servers with each server offset by 100 while external servers start at 10000 and end at 65535. -The table below shows the current servers along with the expected error code structure. - - - -+---------------------------------------------------+-----------------------+----------------------+ -| Server Name | Reserved | RANGE | -+===================================================+=======================+======================+ -| ... | NONE=0, UNKNOWN=1 | 2-99 | -+---------------------------------------------------+-----------------------+----------------------+ -| `Controller Server`_ | NONE=0, UNKNOWN=100 | 101-199 | -+---------------------------------------------------+-----------------------+----------------------+ -| `Planner Server`_ (compute_path_to_pose) | NONE=0, UNKNOWN=200 | 201-299 | -+---------------------------------------------------+-----------------------+----------------------+ -| `Planner Server`_ (compute_path_through_poses) | NONE=0, UNKNOWN=300 | 301-399 | -+---------------------------------------------------+-----------------------+----------------------+ -| ... | ... | | -+---------------------------------------------------+-----------------------+----------------------+ -| `Smoother Server`_ | NONE=0, UNKNOWN=500 | 501-599 | -+---------------------------------------------------+-----------------------+----------------------+ -| `Waypoint Follower Server`_ | NONE=0, UNKNOWN=600 | 601-699 | -+---------------------------------------------------+-----------------------+----------------------+ -| `Behavior Server`_ | NONE=0 | 701-799 | -+---------------------------------------------------+-----------------------+----------------------+ -| Coverage Server | NONE=0, UNKNOWN=800 | 801-899 | -+---------------------------------------------------+-----------------------+----------------------+ -| ... | ... | | -+---------------------------------------------------+-----------------------+----------------------+ -| Last Nav2 Server | NONE=0, UNKNOWN=9900 | 9901-9999 | -+---------------------------------------------------+-----------------------+----------------------+ -| First External Server | NONE=0, UNKNOWN=10000 | 10001-10099 | -+---------------------------------------------------+-----------------------+----------------------+ -| ... | ... | | -+---------------------------------------------------+-----------------------+----------------------+ - -.. _Controller Server: https://github.com/ros-planning/navigation2/blob/main/nav2_controller/src/controller_server.cpp -.. _Planner Server: https://github.com/ros-planning/navigation2/blob/main/nav2_planner/src/planner_server.cpp -.. _Smoother Server: https://github.com/ros-planning/navigation2/blob/main/nav2_smoother/src/nav2_smoother.cpp -.. _Waypoint Follower Server: https://github.com/ros-planning/navigation2/blob/main/nav2_waypoint_follower/src/waypoint_follower.cpp -.. _Behavior Server: https://github.com/ros-planning/navigation2/blob/main/nav2_behaviors/src/behavior_server.cpp - -Error codes are attached to the response of the action message. An example can be seen below for the route server. Note that by convention we set the error code field within the message definition to ``error_code``. - - - -.. code-block:: bash - - # Error codes - # Note: The expected priority order of the errors should match the message order - uint16 NONE=0 # 0 is reserved for NONE - uint16 UNKNOWN=10000 # first error code in the sequence is reserved for UNKNOWN - - # User Error codes below - int16 INVALID_START=10001 - int16 NO_VALID_ROUTE=10002 - - #goal definition - route_msgs/PoseStamped goal - route_msgs/PoseStamped start - string route_id - --- - #result definition - nav_msgs/Route route - builtin_interfaces/Duration route_time - uint16 error_code - --- - -As stated in the message, the priority order of the errors should match the message order, 0 is reserved for NONE and the first error code in the sequence is reserved for UNKNOWN. -Since the the route server is a external server, the errors codes start at 10000 and go up to 10099. - -In order to propagate your server's error code to the rest of the system it must be added to the nav2_params.yaml file. -The `error_code_id_names` inside of the BT Navigator define what error codes to look for on the blackboard by the server. The lowest error code of the sequence is then returned - whereas the code enums increase the higher up in the software stack - giving higher priority to lower-level failures. - - - -.. code-block:: yaml - - error_code_id_names: - - compute_path_error_code_id - - follow_path_error_code_id - - route_error_code_id - -Conclusion -********** - -In this section of the guide, we have discussed Lifecycle Nodes, Composition and Error Codes which are new and important concepts in ROS 2. We also showed how to implement Lifecycle Nodes, Composition and Error Codes to your newly created nodes/servers with Nav2. These three concepts are helpful to efficiently run your system and therefore are encouraged to be used throughout Nav2. +.. _adding_a_nav2_task_server: + +Adding a New Nav2 Task Server +############################# + +A nav2 task server consists of server side logic to complete different types of requests, usually called by the autonomy system or through the Behavior Tree Navigator. In this guide, we will discuss the core components needed to add a new task server to Nav2 (ex. Controller, Behavior, Smoother, Planner Servers). Namely, how to set up your new Lifecycle-Component Node for launch and state management and the communication of semantically meaningful error codes (if necessary). + +While this tutorial does not cover how to add the complementary Behavior Tree Node to interact with this new Task Server, that is covered at length in :ref:`writing_new_nbt_plugin` so this Task Server can be invoked in the BTs in BT Navigator. + +If you've created a new Task Server that may have general reuse for the community, consider contacting the maintainers to add it to the Nav2 project! Nav2 gets better by contributions by users like you! + + + +Lifecycle Nodes +*************** + +The Lifecycle node is the first key component of a nav2 task server. Lifecycle nodes were introduced in ROS 2 to systematically manage the bringup and shutdown of the different nodes involved in the robot's operation. The use of Lifecycle nodes ensures that all nodes are successfully instantiated before they begin their execution and Nav2 shuts down all nodes if there is any unresponsive node. + + +Lifecycle nodes contain state machine transitions that enable deterministic behavior in ROS 2 servers. The Lifecycle node transitions in Nav2 are handled by the ``Lifecycle Manager``. The Lifecycle Manager transitions the states of the Lifecycle nodes and provides greater control over the state of a system. + + +The primary states of a Lifecycle node are ``Unconfigured``, ``Inactive``, ``Active``, and ``Finalized``. A Lifecycle node starts in an ``Unconfigured`` state after being instantiated. The Lifecycle Manager transitions a node from ``Unconfigured`` to ``Inactive`` by implementing the ``Configurating`` transition. The ``Configurating`` transition sets up all configuration parameters and prepares any required setup such as memory allocation and the set up of the static publication and subscription topics. A node in the ``Inactive`` state is allowed to reconfigure its parameters and but cannot perform any processing. From the ``Inactive`` state, the Lifecycle Manager implements the ``Activating`` transition state to transition the node from ``Inactive`` to ``Active``, which is the main state. A node in the ``Active`` state is allowed to perform any processing operation. In case a node crashes, the Lifecycle Manager shuts down the system to prevent any critical failures. On shutdown, the necessary cleanup operations are performed and the nodes are transitioned to the ``Finalized`` state via ``Deactivating``, ``CleaningUp``, and ``ShuttingDown`` transition states. + +.. seealso:: + For more information on Lifecycle management, see the article on `Managed Nodes `_. + +You may wish to integrate your own nodes into the Nav2 framework or add new lifecycle nodes to your system. As an example, we will add a new notional lifecycle node ``sensor_driver``, and have it be controlled via the Nav2 Lifecycle Manager to ensure sensor feeds are available before activating navigation. You can do so by adding a ``sensor_driver`` node in your launch file and adding it to the list of nodes to be activated by the ``lifecycle_manager`` before navigation, as shown in the example below. + +.. code-block:: python + + lifecycle_nodes = ['sensor_driver', + 'controller_server', + 'smoother_server', + 'planner_server', + 'behavior_server', + 'bt_navigator', + 'waypoint_follower'] + + ... + + Node( + package='nav2_sensor_driver', + executable='sensor_driver', + name='sensor_driver', + output='screen', + parameters=[configured_params], + remappings=remappings), + + Node( + package='nav2_lifecycle_manager', + executable='lifecycle_manager', + name='lifecycle_manager_navigation', + output='screen', + parameters=[{'autostart': autostart}, + {'node_names': lifecycle_nodes}]), + + +In the snippet above, the nodes to be handled by the Lifecycle Manager are set using the ``node_names`` parameter. The ``node_names`` parameter takes in an ordered list of nodes to bringup through the Lifecycle transition. As shown in the snippet, the ``node_names`` parameter takes in ``lifecycle_nodes`` which contains the list of nodes to be added to the Lifecycle Manager. The Lifecycle Manager implements bringup transitions (``Configuring`` and ``Activating``) to the nodes one-by-one and in order, while the nodes are processed in reverse order for shutdown transitions. Hence, the ``sensor_driver`` is listed first before the other navigation servers so that the sensor data is available before the navigation servers are activated. + + + +Two other parameters of the Lifecycle Manager are ``autostart`` and ``bond_timeout``. Set ``autostart`` to ``true`` if you want to set the transition nodes to the ``Active`` state on startup. Otherwise, you will need to manually trigger Lifecycle Manager to transition up the system. The ``bond_timeout`` sets the waiting time to decide when to transition down all of the nodes if a node is not responding. + +.. note:: + More information on Lifecycle Manager parameters can be found in the `Configuration Guide of Lifecycle Manager `_ + + +Composition +*********** + +Composition is the second key component nav2 task servers that was introduced to reduce the memory and CPU resources by putting multiple nodes in a single process. In Nav2, Composition can be used to compose all Nav2 nodes in a single process instead of launching them separately. This is useful for deployment on embedded systems where developers need to optimize resource usage. + +.. seealso:: + More information on Composition can be found `here `_. + +In the following section, we give an example on how to add a new Nav2 server, which we notionally call the ``route_server``, to our system. + + +We make use of the launch files to compose different servers into a single process. The process is established by the ``ComposableNodeContainer`` container that is populated with composition nodes via ``ComposableNode``. This container can then be launched and used the same as any other Nav2 node. + +1. Add a new ``ComposableNode()`` instance in your launch file pointing to the component container of your choice. + + .. code-block:: python + + container = ComposableNodeContainer( + name='my_container', + namespace='', + package='rclcpp_components', + executable='component_container', + composable_node_descriptions=[ + ComposableNode( + package='nav2_route_server', + plugin='nav2_route_server::RouteServer', + name='nav2_route_server'), + ], + output='screen', + ) + + .. seealso:: + See example in composition demo's `composition_demo.launch.py `_. + +2. Add the package containing the server to your ``package.xml`` file. + + .. code-block:: xml + + nav2_route_server + + +Error codes +*********** + +Your nav2 task server may also wish to return a 'error_code' in its action response (though not required). If there are semantically meaningful and actionable types of failures for your system, this is a systemic way to communicate those failures which may be automatically aggregated into the responses of the navigation system to your application. + +It is important to note that error codes from 0-9999 are reserved for internal nav2 servers with each server offset by 100 while external servers start at 10000 and end at 65535. +The table below shows the current servers along with the expected error code structure. + + + ++---------------------------------------------------+-----------------------+----------------------+ +| Server Name | Reserved | RANGE | ++===================================================+=======================+======================+ +| ... | NONE=0, UNKNOWN=1 | 2-99 | ++---------------------------------------------------+-----------------------+----------------------+ +| `Controller Server`_ | NONE=0, UNKNOWN=100 | 101-199 | ++---------------------------------------------------+-----------------------+----------------------+ +| `Planner Server`_ (compute_path_to_pose) | NONE=0, UNKNOWN=200 | 201-299 | ++---------------------------------------------------+-----------------------+----------------------+ +| `Planner Server`_ (compute_path_through_poses) | NONE=0, UNKNOWN=300 | 301-399 | ++---------------------------------------------------+-----------------------+----------------------+ +| ... | ... | | ++---------------------------------------------------+-----------------------+----------------------+ +| `Smoother Server`_ | NONE=0, UNKNOWN=500 | 501-599 | ++---------------------------------------------------+-----------------------+----------------------+ +| `Waypoint Follower Server`_ | NONE=0, UNKNOWN=600 | 601-699 | ++---------------------------------------------------+-----------------------+----------------------+ +| `Behavior Server`_ | NONE=0 | 701-799 | ++---------------------------------------------------+-----------------------+----------------------+ +| Coverage Server | NONE=0, UNKNOWN=800 | 801-899 | ++---------------------------------------------------+-----------------------+----------------------+ +| ... | ... | | ++---------------------------------------------------+-----------------------+----------------------+ +| Last Nav2 Server | NONE=0, UNKNOWN=9900 | 9901-9999 | ++---------------------------------------------------+-----------------------+----------------------+ +| First External Server | NONE=0, UNKNOWN=10000 | 10001-10099 | ++---------------------------------------------------+-----------------------+----------------------+ +| ... | ... | | ++---------------------------------------------------+-----------------------+----------------------+ + +.. _Controller Server: https://github.com/ros-navigation/navigation2/blob/main/nav2_controller/src/controller_server.cpp +.. _Planner Server: https://github.com/ros-navigation/navigation2/blob/main/nav2_planner/src/planner_server.cpp +.. _Smoother Server: https://github.com/ros-navigation/navigation2/blob/main/nav2_smoother/src/nav2_smoother.cpp +.. _Waypoint Follower Server: https://github.com/ros-navigation/navigation2/blob/main/nav2_waypoint_follower/src/waypoint_follower.cpp +.. _Behavior Server: https://github.com/ros-navigation/navigation2/blob/main/nav2_behaviors/src/behavior_server.cpp + +Error codes are attached to the response of the action message. An example can be seen below for the route server. Note that by convention we set the error code field within the message definition to ``error_code``. + + + +.. code-block:: bash + + # Error codes + # Note: The expected priority order of the errors should match the message order + uint16 NONE=0 # 0 is reserved for NONE + uint16 UNKNOWN=10000 # first error code in the sequence is reserved for UNKNOWN + + # User Error codes below + int16 INVALID_START=10001 + int16 NO_VALID_ROUTE=10002 + + #goal definition + route_msgs/PoseStamped goal + route_msgs/PoseStamped start + string route_id + --- + #result definition + nav_msgs/Route route + builtin_interfaces/Duration route_time + uint16 error_code + --- + +As stated in the message, the priority order of the errors should match the message order, 0 is reserved for NONE and the first error code in the sequence is reserved for UNKNOWN. +Since the the route server is a external server, the errors codes start at 10000 and go up to 10099. + +In order to propagate your server's error code to the rest of the system it must be added to the nav2_params.yaml file. +The `error_code_id_names` inside of the BT Navigator define what error codes to look for on the blackboard by the server. The lowest error code of the sequence is then returned - whereas the code enums increase the higher up in the software stack - giving higher priority to lower-level failures. + + + +.. code-block:: yaml + + error_code_id_names: + - compute_path_error_code_id + - follow_path_error_code_id + - route_error_code_id + +Conclusion +********** + +In this section of the guide, we have discussed Lifecycle Nodes, Composition and Error Codes which are new and important concepts in ROS 2. We also showed how to implement Lifecycle Nodes, Composition and Error Codes to your newly created nodes/servers with Nav2. These three concepts are helpful to efficiently run your system and therefore are encouraged to be used throughout Nav2. diff --git a/tutorials/docs/docker_dev.rst b/tutorials/docs/docker_dev.rst index 99c82d943..2572dceb9 100644 --- a/tutorials/docs/docker_dev.rst +++ b/tutorials/docs/docker_dev.rst @@ -436,7 +436,7 @@ Instead, it pulls the dependencies so that when you run this container, you obta WORKDIR /root/nav2_ws RUN mkdir -p ~/nav2_ws/src - RUN git clone https://github.com/ros-planning/navigation2.git --branch main ./src/navigation2 + RUN git clone https://github.com/ros-navigation/navigation2.git --branch main ./src/navigation2 RUN rosdep init RUN apt update && apt upgrade -y \ && rosdep update \ @@ -461,7 +461,7 @@ From here, you can go to the :ref:`getting_started` to test it out! # For Rolling or want to build from source a particular branch / fork WORKDIR /root/nav2_ws RUN mkdir -p ~/nav2_ws/src - RUN git clone https://github.com/ros-planning/navigation2.git --branch main ./src/navigation2 + RUN git clone https://github.com/ros-navigation/navigation2.git --branch main ./src/navigation2 RUN rosdep init RUN apt update && apt upgrade -y \ && rosdep update \ diff --git a/tutorials/docs/navigation2_dynamic_point_following.rst b/tutorials/docs/navigation2_dynamic_point_following.rst index f41a05297..1c8d252b8 100644 --- a/tutorials/docs/navigation2_dynamic_point_following.rst +++ b/tutorials/docs/navigation2_dynamic_point_following.rst @@ -126,7 +126,7 @@ To stay at a certain distance from the target, we will use the action node ``Tru Now, you may save this behavior tree and use it in our navigation task. -For reference, this exact behavior tree is `made available `_ to you batteries included in the ``nav2_bt_navigator`` package. +For reference, this exact behavior tree is `made available `_ to you batteries included in the ``nav2_bt_navigator`` package. 1- Setup Rviz clicked point --------------------------- diff --git a/tutorials/docs/navigation2_with_gps.rst b/tutorials/docs/navigation2_with_gps.rst index 771de049a..d36036104 100644 --- a/tutorials/docs/navigation2_with_gps.rst +++ b/tutorials/docs/navigation2_with_gps.rst @@ -36,7 +36,7 @@ It is assumed ROS2 and Nav2 dependent packages are installed or built locally. A sudo apt install ros-$ROS_DISTRO-mapviz-plugins sudo apt install ros-$ROS_DISTRO-tile-map -The code for this tutorial is hosted on `nav2_gps_waypoint_follower_demo `_. Though we will go through the most important steps of the setup, it's highly recommended that you clone and build the package when setting up your dev environment. +The code for this tutorial is hosted on `nav2_gps_waypoint_follower_demo `_. Though we will go through the most important steps of the setup, it's highly recommended that you clone and build the package when setting up your dev environment. You may also need to install gazebo and turtlebot3 simulation if you have not executed previous tutorials or Nav2 demos. See Nav2's Getting Started page for more information. @@ -91,7 +91,7 @@ Tutorial Steps 0- Setup Gazebo World --------------------- -To navigate using GPS we first need to create an outdoors Gazebo world with a robot having a GPS sensor to setup for navigation. For this tutorial we will be using the `Sonoma Raceway `_ because its aligned with the real location. A sample world has been setup `here `_ using gazebo's spherical coordinates plugin, which creates a local tangent plane centered in the set geographic origin and provides latitude, longitude and altitude coordinates for each point in the world: +To navigate using GPS we first need to create an outdoors Gazebo world with a robot having a GPS sensor to setup for navigation. For this tutorial we will be using the `Sonoma Raceway `_ because its aligned with the real location. A sample world has been setup `here `_ using gazebo's spherical coordinates plugin, which creates a local tangent plane centered in the set geographic origin and provides latitude, longitude and altitude coordinates for each point in the world: .. code-block:: xml @@ -107,7 +107,7 @@ To navigate using GPS we first need to create an outdoors Gazebo world with a ro 180 -To get GPS readings from Gazebo we need to create a robot model with a GPS sensor. An updated Turtlebot model with such sensor is provided in the `tutorial repo `_, it outputs ``NavSatFix`` messages on the topic ``/gps/fix``: +To get GPS readings from Gazebo we need to create a robot model with a GPS sensor. An updated Turtlebot model with such sensor is provided in the `tutorial repo `_, it outputs ``NavSatFix`` messages on the topic ``/gps/fix``: .. code-block:: xml @@ -170,7 +170,7 @@ In this tutorial, the GPS sensor on the robot will replace ``amcl`` in providing We will setup one Extended Kalman Filter for local odometry, fusing wheel odometry and IMU data; a second one for global localization, fusing the local cartesian converted GPS coordinates, the wheel odometry and the IMU data; and a navsat_transform node to output cartesian odometry messages from GPS data. This is a common setup on robot_localization when using GPS data and more details around its configuration can be found in `RL's docs `_. -A `configuration file `_ and a `launch file `_ are provided for this purpose. You may take a while before continuing to understand these two files and what they configure. Let's walk through the most relevant setting of each node. +A `configuration file `_ and a `launch file `_ are provided for this purpose. You may take a while before continuing to understand these two files and what they configure. Let's walk through the most relevant setting of each node. Local Odometry ^^^^^^^^^^^^^^ @@ -262,7 +262,7 @@ As a sanity check that everything is working correctly, launch RL's launch file ros2 launch nav2_gps_waypoint_follower_demo dual_ekf_navsat.launch.py -On a different terminal launch mapviz using the pre-built `config file `_ in the repo. `Get a bing maps API key `_ and use it to display satellite pictures. +On a different terminal launch mapviz using the pre-built `config file `_ in the repo. `Get a bing maps API key `_ and use it to display satellite pictures. .. code-block:: bash @@ -342,7 +342,7 @@ There are three main possible setups for the global costmap: origin_x: 25.0 origin_y: 25.0 -We provide a `Nav2 params file `_ with the rolling costmap setup and a `launch file `_ to put it all together. Remember that the GPS setup of robot_localization was just a means for setting up the global localization system, however Nav2 is still a cartesian navigation stack and you may still use all its cartesian tools. To confirm that everything is working, launch the provided file (this launches gazebo and RL as well so close them if you have them running from the previous steps) and use rviz to send a goal to the robot: +We provide a `Nav2 params file `_ with the rolling costmap setup and a `launch file `_ to put it all together. Remember that the GPS setup of robot_localization was just a means for setting up the global localization system, however Nav2 is still a cartesian navigation stack and you may still use all its cartesian tools. To confirm that everything is working, launch the provided file (this launches gazebo and RL as well so close them if you have them running from the previous steps) and use rviz to send a goal to the robot: .. code-block:: bash @@ -359,7 +359,7 @@ The gif below shows what you should see Nav2 navigating the robot autonomously! Now that we have performed our complete system setup, let's leverage Nav2 GPS waypoint follower capabilities to navigate to goals that are expressed directly in GPS coordinates. For this demo we want to build an interactive interface similar to rviz's, that allows us to click over a map to make the robot navigate to the clicked location. For that we will use mapviz's point click publisher on the ``wgs84`` reference frame, which will publish a ``PointStamped`` message with the GPS coordinates of the point clicked over the satellite image. This is a great way to get started in your custom GPS navigation setup! -For this purpose we provide the `interactive_waypoint_follower `_ python node, which subscribes to mapviz's topic and calls the ``/follow_gps_waypoints`` action server with the clicked point as goal using the ``BasicNavigator`` in ``nav2_simple_commander``. To run it source your workspace and with the rest of the system running type: +For this purpose we provide the `interactive_waypoint_follower `_ python node, which subscribes to mapviz's topic and calls the ``/follow_gps_waypoints`` action server with the clicked point as goal using the ``BasicNavigator`` in ``nav2_simple_commander``. To run it source your workspace and with the rest of the system running type: .. code-block:: bash @@ -374,7 +374,7 @@ You can now click on the mapviz map the pose you want the robot to go. The gif b 4- Logged GPS Waypoint Follower & Waypoint Logging --------------------------------------------------- -Finally let's make a robot go through a set of predefined GPS waypoints. We provide a `waypoint logging tool `_ that subscribes to the robot's GPS and IMU and offers a simple GUI to save the robot coordinates and heading on demand to a ``yaml`` file with the format: +Finally let's make a robot go through a set of predefined GPS waypoints. We provide a `waypoint logging tool `_ that subscribes to the robot's GPS and IMU and offers a simple GUI to save the robot coordinates and heading on demand to a ``yaml`` file with the format: .. code-block:: yaml @@ -398,7 +398,7 @@ If you don't provide a path to save your waypoints, they will be saved in your ` :width: 800px :align: center -After that you should get a ``yaml`` file in the location you specified with the format shown above; let's now make the robot follow the logged waypoints. For this purpose we provide the `logged_waypoint_follower `_ node, which takes in the path to the waypoints file as an argument and uses the ``BasicNavigator`` in ``nav2_simple_commander`` to send the logged goals to the ``/follow_gps_waypoints`` action server. If not provided, the node uses the `default waypoints `_ in the ``nav2_gps_waypoint_follower_demo`` package. +After that you should get a ``yaml`` file in the location you specified with the format shown above; let's now make the robot follow the logged waypoints. For this purpose we provide the `logged_waypoint_follower `_ node, which takes in the path to the waypoints file as an argument and uses the ``BasicNavigator`` in ``nav2_simple_commander`` to send the logged goals to the ``/follow_gps_waypoints`` action server. If not provided, the node uses the `default waypoints `_ in the ``nav2_gps_waypoint_follower_demo`` package. To run this node source your workspace and with the rest of the system running type: diff --git a/tutorials/docs/navigation2_with_keepout_filter.rst b/tutorials/docs/navigation2_with_keepout_filter.rst index 8308128d4..a0e4153f1 100644 --- a/tutorials/docs/navigation2_with_keepout_filter.rst +++ b/tutorials/docs/navigation2_with_keepout_filter.rst @@ -33,7 +33,7 @@ Tutorial Steps As was written in :ref:`concepts`, any Costmap Filter (including Keepout Filter) are reading the data marked in a filter mask file. Filter mask - is the usual Nav2 2D-map distributed through PGM, PNG or BMP raster file with its metadata containing in a YAML file. The following steps help to understand how to make a new filter mask: -Create a new image with a PGM/PNG/BMP format: copy `turtlebot3_world.pgm `_ main map which will be used in a world simulation from a ``Nav2`` repository to a new ``keepout_mask.pgm`` file. +Create a new image with a PGM/PNG/BMP format: copy `turtlebot3_world.pgm `_ main map which will be used in a world simulation from a ``Nav2`` repository to a new ``keepout_mask.pgm`` file. Open ``keepout_mask.pgm`` in your favourite raster graphics editor (as an example could be taken GIMP editor). The lightness of each pixel on the mask means an encoded information for the specific costmap filter you are going to use. Color lightness of each pixel belongs to the ``[0..255]`` range (or ``[0..100]`` in percent scale), where ``0`` means black color and ``255`` - white. Another term "darkness" will be understood as the exact opposite of lightness. In other words ``color_darkness = 100% - color_lightness``. @@ -64,7 +64,7 @@ For simplicity, in the example fill the areas with black color (in ``trinary`` m After all keepout areas will be filled save the ``keepout_mask.pgm`` image. -Like all other maps, filter mask should have its own YAML metadata file. Copy `turtlebot3_world.yaml `_ to ``keepout_mask.yaml``. Open ``keepout_mask.yaml`` and correct ``image`` field to a newly made PGM mask: +Like all other maps, filter mask should have its own YAML metadata file. Copy `turtlebot3_world.yaml `_ to ``keepout_mask.yaml``. Open ``keepout_mask.yaml`` and correct ``image`` field to a newly made PGM mask: .. code-block:: text @@ -85,7 +85,7 @@ Since filter mask image was created as a copy of main map, other fields of YAML- 2. Configure Costmap Filter Info Publisher Server ------------------------------------------------- -Each costmap filter reads incoming meta-information (such as filter type or data conversion coefficients) in a messages of ``nav2_msgs/CostmapFilterInfo`` type. These messages are being published by `Costmap Filter Info Publisher Server `_. The server is running as a lifecycle node. According to the `design document `_, ``nav2_msgs/CostmapFilterInfo`` messages are going in a pair with ``OccupancyGrid`` filter mask topic. Therefore, along with Costmap Filter Info Publisher Server there should be enabled a new instance of Map Server configured to publish filter mask. +Each costmap filter reads incoming meta-information (such as filter type or data conversion coefficients) in a messages of ``nav2_msgs/CostmapFilterInfo`` type. These messages are being published by `Costmap Filter Info Publisher Server `_. The server is running as a lifecycle node. According to the `design document `_, ``nav2_msgs/CostmapFilterInfo`` messages are going in a pair with ``OccupancyGrid`` filter mask topic. Therefore, along with Costmap Filter Info Publisher Server there should be enabled a new instance of Map Server configured to publish filter mask. In order to enable Keepout Filter in your configuration, both servers should be enabled as a lifecycle nodes in Python launch-file. It is also possible to add them as Composition Nodes to your Navigation Component Container, which might look as follows: @@ -268,13 +268,13 @@ Note, that: - Filter mask topic name should be the equal for ``mask_topic`` parameter of Costmap Filter Info Publisher Server and ``topic_name`` parameter of Map Server. - According to the Costmap Filters design, ``OccupancyGrid`` values are being linearly transformed into feature map in a filter space. For a Keepout Filter these values are directly passed as a filter space values without a linear conversion. Even though ``base`` and ``multiplier`` coefficients are not used in Keepout Filter, they should be set to ``0.0`` and ``1.0`` accordingly in order to explicitly show that we have one-to-one conversion from ``OccupancyGrid`` values -> to a filter value space. -Ready-to-go standalone Python launch-script, YAML-file with ROS parameters and filter mask example for Keepout Filter could be found in a `nav2_costmap_filters_demo `_ directory of ``navigation2_tutorials`` repository. To simply run Filter Info Publisher Server and Map Server tuned on Turtlebot3 standard simulation written at :ref:`getting_started`, build the demo and launch ``costmap_filter_info.launch.py`` as follows: +Ready-to-go standalone Python launch-script, YAML-file with ROS parameters and filter mask example for Keepout Filter could be found in a `nav2_costmap_filters_demo `_ directory of ``navigation2_tutorials`` repository. To simply run Filter Info Publisher Server and Map Server tuned on Turtlebot3 standard simulation written at :ref:`getting_started`, build the demo and launch ``costmap_filter_info.launch.py`` as follows: .. code-block:: bash $ mkdir -p ~/tutorials_ws/src $ cd ~/tutorials_ws/src - $ git clone https://github.com/ros-planning/navigation2_tutorials.git + $ git clone https://github.com/ros-navigation/navigation2_tutorials.git $ cd ~/tutorials_ws $ colcon build --symlink-install --packages-select nav2_costmap_filters_demo $ source ~/tutorials_ws/install/setup.bash diff --git a/tutorials/docs/navigation2_with_speed_filter.rst b/tutorials/docs/navigation2_with_speed_filter.rst index fc1dc44af..7ca225a05 100644 --- a/tutorials/docs/navigation2_with_speed_filter.rst +++ b/tutorials/docs/navigation2_with_speed_filter.rst @@ -72,7 +72,7 @@ We will use ``scale`` map mode with no thresholds. In this mode darker colors wi After all speed restriction areas will be filled, save the ``speed_mask.pgm`` image. -Like all other maps, the filter mask should have its own YAML metadata file. Copy `turtlebot3_world.yaml `_ to ``speed_mask.yaml``. Open ``speed_mask.yaml`` and update the fields as shown below (as mentioned before for the ``scale`` mode to use whole color lightness range there should be no thresholds: ``free_thresh = 0.0`` and ``occupied_thresh = 1.0``): +Like all other maps, the filter mask should have its own YAML metadata file. Copy `turtlebot3_world.yaml `_ to ``speed_mask.yaml``. Open ``speed_mask.yaml`` and update the fields as shown below (as mentioned before for the ``scale`` mode to use whole color lightness range there should be no thresholds: ``free_thresh = 0.0`` and ``occupied_thresh = 1.0``): .. code-block:: yaml @@ -99,7 +99,7 @@ Since Costmap2D does not support orientation, the last third "yaw" component of 2. Configure Costmap Filter Info Publisher Server ------------------------------------------------- -Each costmap filter reads incoming meta-information (such as filter type or data conversion coefficients) in messages of ``nav2_msgs/CostmapFilterInfo`` type. These messages are being published by `Costmap Filter Info Publisher Server `_. The server is running as a lifecycle node. According to the `design document `_, ``nav2_msgs/CostmapFilterInfo`` messages are going in a pair with ``OccupancyGrid`` filter mask topic. Therefore, along with Costmap Filter Info Publisher Server there should be enabled a new instance of Map Server configured to publish filter masks. +Each costmap filter reads incoming meta-information (such as filter type or data conversion coefficients) in messages of ``nav2_msgs/CostmapFilterInfo`` type. These messages are being published by `Costmap Filter Info Publisher Server `_. The server is running as a lifecycle node. According to the `design document `_, ``nav2_msgs/CostmapFilterInfo`` messages are going in a pair with ``OccupancyGrid`` filter mask topic. Therefore, along with Costmap Filter Info Publisher Server there should be enabled a new instance of Map Server configured to publish filter masks. In order to enable Speed Filter in your configuration, both servers should be enabled as lifecycle nodes in Python launch-file. For example, this might look as follows, though adding them as Composition Nodes to your Navigation Component Container is also possible: @@ -235,13 +235,13 @@ Note, that: - Filter mask topic name should be the equal for ``mask_topic`` parameter of Costmap Filter Info Publisher Server and ``topic_name`` parameter of Map Server. - As was described in a previous chapter, ``base`` and ``multiplier`` should be set to ``100.0`` and ``-1.0`` accordingly for the purposes of this tutorial example. -Ready-to-go standalone Python launch-script, YAML-file with ROS parameters and filter mask example for Speed Filter could be found in a `nav2_costmap_filters_demo `_ directory of ``navigation2_tutorials`` repository. To simply run Filter Info Publisher Server and Map Server tuned on Turtlebot3 standard simulation written at :ref:`getting_started`, build the demo and launch ``costmap_filter_info.launch.py`` as follows: +Ready-to-go standalone Python launch-script, YAML-file with ROS parameters and filter mask example for Speed Filter could be found in a `nav2_costmap_filters_demo `_ directory of ``navigation2_tutorials`` repository. To simply run Filter Info Publisher Server and Map Server tuned on Turtlebot3 standard simulation written at :ref:`getting_started`, build the demo and launch ``costmap_filter_info.launch.py`` as follows: .. code-block:: bash $ mkdir -p ~/tutorials_ws/src $ cd ~/tutorials_ws/src - $ git clone https://github.com/ros-planning/navigation2_tutorials.git + $ git clone https://github.com/ros-navigation/navigation2_tutorials.git $ cd ~/tutorials_ws $ colcon build --symlink-install --packages-select nav2_costmap_filters_demo $ source ~/tutorials_ws/install/setup.bash @@ -277,7 +277,7 @@ In this tutorial, we will enable Speed Filter for the global costmap. For this u filter_info_topic: "/costmap_filter_info" speed_limit_topic: "/speed_limit" -As stated in the `design `_, Speed Filter publishes speed restricting `messages `_ targeted for a Controller Server so that it could restrict maximum speed of the robot when it needed. Controller Server has a ``speed_limit_topic`` ROS parameter for that, which should be set to the same as in ``speed_filter`` plugin value. This topic in the map server could also be used to any number of other speed-restricted applications beyond the speed limiting zones, such as dynamically adjusting maximum speed by payload mass. +As stated in the `design `_, Speed Filter publishes speed restricting `messages `_ targeted for a Controller Server so that it could restrict maximum speed of the robot when it needed. Controller Server has a ``speed_limit_topic`` ROS parameter for that, which should be set to the same as in ``speed_filter`` plugin value. This topic in the map server could also be used to any number of other speed-restricted applications beyond the speed limiting zones, such as dynamically adjusting maximum speed by payload mass. Set ``speed_limit_topic`` parameter of a Controller Server to the same value as it set for ``speed_filter`` plugin: diff --git a/tutorials/docs/using_groot.rst b/tutorials/docs/using_groot.rst index 932ed481b..5868067ee 100644 --- a/tutorials/docs/using_groot.rst +++ b/tutorials/docs/using_groot.rst @@ -113,7 +113,7 @@ After completing, select `OK` in :numref:`groot_interactive_node_creation`, the Before starting to create a new BT based on the new custom nodes, it is recommend to export the newly created nodes to save in case of Groot crashing. This can be performed with the icon highlighted in green from :numref:`groot_export_new_node`. The resulting XML output from the node created in :numref:`groot_interactive_node_creation` can be seen below. -You can see more examples in `Nav2's BT Node Palette XML `_. +You can see more examples in `Nav2's BT Node Palette XML `_. .. code-block:: xml