diff --git a/behavior_trees/trees/nav_through_poses_recovery.rst b/behavior_trees/trees/nav_through_poses_recovery.rst index f3bcb62ec9..eaf95ea1ca 100644 --- a/behavior_trees/trees/nav_through_poses_recovery.rst +++ b/behavior_trees/trees/nav_through_poses_recovery.rst @@ -75,7 +75,7 @@ While this behavior tree does not make use of it, the ``PlannerSelector``, ``Con - + diff --git a/configuration/packages/configuring-bt-navigator.rst b/configuration/packages/configuring-bt-navigator.rst index 5cddf96aba..fe0140618a 100644 --- a/configuration/packages/configuring-bt-navigator.rst +++ b/configuration/packages/configuring-bt-navigator.rst @@ -11,7 +11,7 @@ The BT Navigator (Behavior Tree Navigator) module implements the NavigateToPose, It is a Behavior Tree-based implementation of navigation that is intended to allow for flexibility in the navigation task and provide a way to easily specify complex robot behaviors, including recovery. -Consider checking out the :ref:`groot_introduction` tutorial for using Groot to visualize and modify behavior trees. +Consider checking out the :ref:`using_groot` tutorial for using Groot to visualize and modify behavior trees. Make sure to review all parameters for non-default navigator plugins not discussed on this page (e.g. ``CoverageNavigator`` or custom additions). diff --git a/configuration/packages/configuring-bt-xml.rst b/configuration/packages/configuring-bt-xml.rst index 1b5045b8f4..143d57b7dc 100644 --- a/configuration/packages/configuring-bt-xml.rst +++ b/configuration/packages/configuring-bt-xml.rst @@ -11,7 +11,7 @@ Check this introduction_ to learn how behavior trees work and the difference bet .. _introduction: https://www.behaviortree.dev/bt_basics/ -Consider checking out the :ref:`groot_introduction` tutorial for using Groot to visualize and modify behavior trees. +Consider checking out the :ref:`using_groot` tutorial for using Groot to visualize and modify behavior trees. Action Plugins ************** diff --git a/migration/Iron.rst b/migration/Iron.rst index fa8441e253..0ccb9bbb0e 100644 --- a/migration/Iron.rst +++ b/migration/Iron.rst @@ -172,7 +172,7 @@ 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 #3500 `_ 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 @@ -331,7 +331,7 @@ New graceful cancellation API for Controllers Standardization of Plugin Naming with Double Colons (::) ******************************************************** -`PR #4220`_ standardizes plugin naming across the Navigation2 package to use double colons (::), replacing the previous mixed use of slashes (/) and double colons. Affected plugins include: +`PR #4220 `_ standardizes plugin naming across the Navigation2 package to use double colons (::), replacing the previous mixed use of slashes (/) and double colons. Affected plugins include: - Behavior Server: ``nav2_behaviors::Spin``, ``nav2_behaviors::BackUp``, ``nav2_behaviors::DriveOnHeading``, ``nav2_behaviors::Wait``, ``nav2_behaviors::AssistedTeleop`` - Planner Server: ``nav2_navfn_planner::NavfnPlanner``, ``nav2_smac_planner::SmacPlanner2D``, ``nav2_smac_planner::SmacPlannerHybrid``, ``nav2_theta_star_planner::ThetaStarPlanner`` diff --git a/migration/Jazzy.rst b/migration/Jazzy.rst index 0f175cae47..27786b9731 100644 --- a/migration/Jazzy.rst +++ b/migration/Jazzy.rst @@ -52,7 +52,7 @@ The following provides examples of modifications that should be made to behavior .. code-block:: xml - + diff --git a/tutorials/docs/adding_a_nav2_task_server.rst b/tutorials/docs/adding_a_nav2_task_server.rst index 9cfdeb5b40..5ab66dd29c 100644 --- a/tutorials/docs/adding_a_nav2_task_server.rst +++ b/tutorials/docs/adding_a_nav2_task_server.rst @@ -162,6 +162,7 @@ The table below shows the current servers along with the expected error code str .. _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 +.. _Navigator: https://github.com/ros-navigation/navigation2/blob/main/nav2_bt_navigator/ Error codes and messages are attached to the response of the action message. An example can be seen below for the route server. Note it is necessary to set the error code field within the message result definition to ``error_code`` and the error message field to ``error_msg``. diff --git a/tutorials/docs/groot.rst b/tutorials/docs/groot.rst new file mode 100644 index 0000000000..86872b4d94 --- /dev/null +++ b/tutorials/docs/groot.rst @@ -0,0 +1,100 @@ +.. _groot_introduction: + +Groot - Interacting with Behavior Trees +*************************************** + +- `Visualize Behavior Trees`_ +- `Edit Behavior Trees`_ +- `Adding A Custom Node`_ + + +Visualize Behavior Trees +======================== + +To display a Behavior Tree like that in :numref:`groot_nav2_default_bt`, we will first start the Groot executable. +Out of the box, Groot can only display Behavior Trees and nodes that are from the defaults in BT.CPP, since it does not know anything about Nav2 or your other projects. +Therefore, we must point Groot to our palette, or index of Nav2 / custom behavior tree nodes: + +1. Open Groot in editor mode. Now, Groot should look like in :numref:`groot_bt_editor`. +2. Select the `Load palette from file` option either via the context menu or the import icon in the top middle of the menu bar. +3. Open the file `/path/to/navigation2/nav2_behavior_tree/nav2_tree_nodes.xml` to import all the custom behavior tree nodes used for navigation. This is the palette of Nav2 custom behavior tree nodes. Now, Groot should look like in :numref:`groot_bt_editor_with_nodes`. +4. Select `Load tree` option near the top left corner +5. Browse the tree you want to visualize, then select `OK`. The Nav2 BTs exist in `/path/to/navigation2/nav2_bt_navigator/behavior_trees/` + ++-----------------------------------------------------------+-----------------------------------------------------------+ +| .. figure:: images/Groot/groot_bt_editor.png | .. figure:: images/Groot/groot_with_nav2_custom_nodes.png | +| :name: groot_bt_editor | :name: groot_bt_editor_with_nodes | +| | | +| Default Editor View | Editor with Custom Nodes loaded in blue | ++-----------------------------------------------------------+-----------------------------------------------------------+ + +If you select the default tree `navigate_w_replanning_and_recovery.xml`, then a Groot editor should look like :numref:`groot_nav2_default_bt`. + ++-----------------------------------------------------------+ +| .. figure:: images/Groot/bt_w_replanning_and_recovery.png | +| :name: groot_nav2_default_bt | +| | +| Full Nav2 Default BehaviorTree | ++-----------------------------------------------------------+ + +.. note:: + If a tree cannot be visualized because some nodes are missing in the palette, you might need to add it to your palette. While we try to keep Nav2's BT nodes and palettes in sync, if you notice one is missing, please file a ticket or pull request and we should have that updated quickly. + + +Edit Behavior Trees +=================== + +Now that you have a Nav2 BT open in Groot in editor mode, you should be able to trivially modify it using the GUI. +Starting from a screen like that shown in :numref:`groot_nav2_default_bt`, you can pull in new nodes from the side panel to add them to the workspace. +You may then connect the nodes using a "drag and drop" motion between the node's input and output ports to assemble the new nodes into the tree. + +If you select a given node, you can change metadata about it such as its name or values of parameterizable ports. When you're done modifying, simply save the new configuration file and use that on your robot the next time! + +Adding A Custom Node +==================== + +Each node in the behavior tree holds a specialized function. +Sometimes, its useful to create new nodes and add them to your palette during the design process - perhaps before the implementations themselves exist. +This helps designers abstract away the implementation specifics of the nodes from the higher level logic of the tree itself and how they'd like to interact with a given node (e.g. type, ports, etc). +Within Groot, you may create new custom nodes to add to your tree and export these new nodes back to your palette. +Implementing the node itself needs to be done separately from Groot, which is described in :ref:`writing_new_nbt_plugin`. + ++-----------------------------------------------------------+ +| .. figure:: images/Groot/groot_create_custom_node.png | +| :name: groot_create_custom_node | +| | +| Create a new Custom Node | ++-----------------------------------------------------------+ + +Creating a new custom node can be started by clicking the orange marked icon in :numref:`groot_create_custom_node`, while Groot is in Editor mode. +This should load a new window, similar to :numref:`groot_interactive_node_creation`. +In this new window, it asks you to fill in the metadata about this new node, in order to create it. +It will ask you for standard information such as name (green box), type of node (orange box), and any optional ports for parameterization or access to blackboard variables (blue box). + +After completing, select `OK` in :numref:`groot_interactive_node_creation`, the new custom node should appear in blue in the `TreeNode Palette` as in :numref:`groot_export_new_node`. + ++--------------------------------------------------------------+--------------------------------------------------------------+ +| .. figure:: images/Groot/groot_interactive_node_creation.png | .. figure:: images/Groot/groot_export_new_node.png | +| :name: groot_interactive_node_creation | :name: groot_export_new_node | +| | :width: 180% | +| | | +| UI to describing new Nodes | Exporting the new Custom Node | ++--------------------------------------------------------------+--------------------------------------------------------------+ + +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 `_. + + +.. code-block:: xml + + + + + coffee + Sense of life + rolling target + + + diff --git a/tutorials/docs/groot2.rst b/tutorials/docs/groot2.rst new file mode 100644 index 0000000000..15d074a2e0 --- /dev/null +++ b/tutorials/docs/groot2.rst @@ -0,0 +1,92 @@ +.. _groot2_introduction: + +Groot2 - Interacting with Behavior Trees +**************************************** + +- `Visualize Behavior Trees`_ +- `Edit Behavior Trees`_ +- `Adding A Custom Node`_ + + +Visualize Behavior Trees +======================== + +To display the default editor view, we will first start the Groot2 executable. +Out of the box, Groot2 can only display Behavior Trees and nodes that are from the defaults in BT.CPP, since it does not know anything about Nav2 or your other projects. +Therefore, we must point Groot2 to our palette, or index of Nav2 / custom behavior tree nodes: + +1. Open Groot2 in editor mode. The interface should now look like the example shown in the first image below. +2. Click the red icon as shown in the second image, open the file `/path/to/navigation2/nav2_behavior_tree/nav2_tree_nodes.xml` to import all the custom behavior tree nodes used for navigation. Once loaded, you should see the full palette of Nav2's custom nodes. +3. Click the blue icon as shown in the second image, browse the tree you want to visualize, then select `Open`. The Nav2 BTs exist in `/path/to/navigation2/nav2_bt_navigator/behavior_trees/`. + +.. image:: images/Groot2/groot_bt_editor.png + :width: 46% +.. image:: images/Groot2/groot_with_nav2_custom_nodes.png + :width: 45% + +If you select the default tree `navigate_w_replanning_and_recovery.xml`, the Groot2 editor should now display the full behavior tree structure, as shown in the image below. + +.. image:: images/Groot2/bt_w_replanning_and_recovery.png + :width: 80% + +You can also check/uncheck the Nodes visualization part in the preferences to better visualize the tree. + +.. image:: images/Groot2/groot_preferences.png + :width: 80% + +.. note:: + If a tree cannot be visualized because some nodes are missing in the palette, you might need to add it to your palette. While we try to keep Nav2's BT nodes and palettes in sync, if you notice one is missing, please file a ticket or pull request and we should have that updated quickly. + +Edit Behavior Trees +=================== + +Now that you have a Nav2 BT open in Groot2 in editor mode, you should be able to trivially modify it using the GUI. +You can pull in new nodes from the side panel to add them to the workspace. +You may then connect the nodes using a "drag and drop" motion between the node's input and output ports to assemble the new nodes into the tree. + +If you select a given node, you can change metadata about it such as its name or values of parameterizable ports. When you're done modifying, simply save the new configuration file and use that on your robot the next time! + +.. image:: images/Groot2/editing_bt.png + :width: 80% + + +Adding A Custom Node +==================== + +Each node in the behavior tree holds a specialized function. +Sometimes, its useful to create new nodes and add them to your palette during the design process - perhaps before the implementations themselves exist. +This helps designers abstract away the implementation specifics of the nodes from the higher level logic of the tree itself and how they'd like to interact with a given node (e.g. type, ports, etc). +Within Groot2, you may create new custom nodes to add to your tree and export these new nodes back to your palette. +Implementing the node itself needs to be done separately from Groot2, which is described in :ref:`writing_new_nbt_plugin`. + + + +Creating a new custom node can be started by clicking the red marked icon, while Groot2 is in Editor mode. + +.. image:: images/Groot2/groot_create_custom_node.png + :width: 40% + +This should load a new window, as shown in the next image. + +.. image:: images/Groot2/groot_interactive_node_creation.png + :width: 50% + +In this new window, it asks you to fill in the metadata about this new node, in order to create it. +It will ask you for standard information such as port name, type of node, and any optional ports for parameterization or access to blackboard variables. +After completing, select `OK`, the new custom node should now appear in the `TreeNode Palette`. + +.. image:: images/Groot2/groot_new_node.png + :width: 35% + +Exporting Behavior Trees +======================== + +Once you have finished editing or creating your behavior tree in Groot2, you may want to export it for use in your application. +To do this, you can either use the Export Project button shown in the image below, or use the Save Current Project As button next to it. + +.. image:: images/Groot2/groot_export_button.png + :width: 50% +.. image:: images/Groot2/groot_export_page.png + :width: 40% + +Your behavior tree has been successfully exported! You can reload it the next time you open Groot2. diff --git a/tutorials/docs/images/Groot2/bt_w_replanning_and_recovery.png b/tutorials/docs/images/Groot2/bt_w_replanning_and_recovery.png new file mode 100644 index 0000000000..bedadd4e9b Binary files /dev/null and b/tutorials/docs/images/Groot2/bt_w_replanning_and_recovery.png differ diff --git a/tutorials/docs/images/Groot2/editing_bt.png b/tutorials/docs/images/Groot2/editing_bt.png new file mode 100644 index 0000000000..a7428f1df3 Binary files /dev/null and b/tutorials/docs/images/Groot2/editing_bt.png differ diff --git a/tutorials/docs/images/Groot2/groot_bt_editor.png b/tutorials/docs/images/Groot2/groot_bt_editor.png new file mode 100644 index 0000000000..65d488a1d6 Binary files /dev/null and b/tutorials/docs/images/Groot2/groot_bt_editor.png differ diff --git a/tutorials/docs/images/Groot2/groot_create_custom_node.png b/tutorials/docs/images/Groot2/groot_create_custom_node.png new file mode 100644 index 0000000000..98e2c1960d Binary files /dev/null and b/tutorials/docs/images/Groot2/groot_create_custom_node.png differ diff --git a/tutorials/docs/images/Groot2/groot_export_button.png b/tutorials/docs/images/Groot2/groot_export_button.png new file mode 100644 index 0000000000..fd7263ea6c Binary files /dev/null and b/tutorials/docs/images/Groot2/groot_export_button.png differ diff --git a/tutorials/docs/images/Groot2/groot_export_page.png b/tutorials/docs/images/Groot2/groot_export_page.png new file mode 100644 index 0000000000..99782b184c Binary files /dev/null and b/tutorials/docs/images/Groot2/groot_export_page.png differ diff --git a/tutorials/docs/images/Groot2/groot_interactive_node_creation.png b/tutorials/docs/images/Groot2/groot_interactive_node_creation.png new file mode 100644 index 0000000000..bcc69bb6fb Binary files /dev/null and b/tutorials/docs/images/Groot2/groot_interactive_node_creation.png differ diff --git a/tutorials/docs/images/Groot2/groot_new_node.png b/tutorials/docs/images/Groot2/groot_new_node.png new file mode 100644 index 0000000000..1c21cfea6c Binary files /dev/null and b/tutorials/docs/images/Groot2/groot_new_node.png differ diff --git a/tutorials/docs/images/Groot2/groot_preferences.png b/tutorials/docs/images/Groot2/groot_preferences.png new file mode 100644 index 0000000000..adecf50eb6 Binary files /dev/null and b/tutorials/docs/images/Groot2/groot_preferences.png differ diff --git a/tutorials/docs/images/Groot2/groot_with_nav2_custom_nodes.png b/tutorials/docs/images/Groot2/groot_with_nav2_custom_nodes.png new file mode 100644 index 0000000000..0b7b703af0 Binary files /dev/null and b/tutorials/docs/images/Groot2/groot_with_nav2_custom_nodes.png differ diff --git a/tutorials/docs/using_groot.rst b/tutorials/docs/using_groot.rst index 59ac7f27c2..6e1d13712f 100644 --- a/tutorials/docs/using_groot.rst +++ b/tutorials/docs/using_groot.rst @@ -1,17 +1,12 @@ -.. _groot_introduction: +.. _using_groot: -Groot - Interacting with Behavior Trees -*************************************** +Groot Tutorials +############### .. figure:: images/Groot/groot_start_menu.png :name: groot_startup_menu :align: center -- `Overview`_ -- `Visualize Behavior Trees`_ -- `Edit Behavior Trees`_ -- `Adding A Custom Node`_ - Overview ======== @@ -34,96 +29,15 @@ These nodes are of types: `Action`, `Condition`, `Control`, or `Decorator`, and A BT configuration file in BehaviorTree.CPP is an XML file. This is used to dynamically load the BT node plugins at run-time from the appropriate libraries mapped to their names. The XML format is defined `in detail here `_. Therefore, Groot needs to have a list of nodes it has access to and important metadata about them like their type and ports (or parameters). We refer to this as the "palette" of nodes later in the tutorial. -In the video above you can see Groot side-by-side with RVIz and a test platform 100% equipped with ROS-enabled hardware from SIEMENS. -Groot not only displays the current Behavior Tree while the robot is operating. Note: Before ROS 2 Humble, live Groot behavior tree monitoring during execution was supported in Nav2. This was removed due to buggy support in BT.CPP / Groot for changing behavior trees on the fly, see :ref:`galactic_migration` for more details. - -Visualize Behavior Trees -======================== - -To display a Behavior Tree like that in :numref:`groot_nav2_default_bt`, we will first start the Groot executable. -Out of the box, Groot can only display Behavior Trees and nodes that are from the defaults in BT.CPP, since it does not know anything about Nav2 or your other projects. -Therefore, we must point Groot to our palette, or index, of Nav2 / custom behavior tree nodes: - -1. Open Groot in editor mode. Now, Groot should look like in :numref:`groot_bt_editor`. -2. Select the `Load palette from file` option either via the context menu or the import icon in the top middle of the menu bar. -3. Open the file `/path/to/navigation2/nav2_behavior_tree/nav2_tree_nodes.xml` to import all the custom behavior tree nodes used for navigation. This is the palette of Nav2 custom behavior tree nodes. Now, Groot should look like in :numref:`groot_bt_editor_with_nodes`. -4. Select `Load tree` option near the top left corner -5. Browse the tree you want to visualize, then select `OK`. The Nav2 BTs exist in `/path/to/navigation2/nav2_bt_navigator/behavior_trees/` - -+-----------------------------------------------------------+-----------------------------------------------------------+ -| .. figure:: images/Groot/groot_bt_editor.png | .. figure:: images/Groot/groot_with_nav2_custom_nodes.png | -| :name: groot_bt_editor | :name: groot_bt_editor_with_nodes | -| | | -| Default Editor View | Editor with Custom Nodes loaded in blue | -+-----------------------------------------------------------+-----------------------------------------------------------+ - -If you select the default tree `navigate_w_replanning_and_recovery.xml`, then a Groot editor should look like :numref:`groot_nav2_default_bt`. - -+-----------------------------------------------------------+ -| .. figure:: images/Groot/bt_w_replanning_and_recovery.png | -| :name: groot_nav2_default_bt | -| | -| Full Nav2 Default BehaviorTree | -+-----------------------------------------------------------+ - -.. note:: - If a tree cannot be visualized because some nodes are missing in the palette, you might need to add it to your palette. While we try to keep Nav2's BT nodes and palettes in sync, if you notice one is missing, please file a ticket or pull request and we should have that updated quickly. - - -Edit Behavior Trees -=================== - -Now that you have a Nav2 BT open in Groot in editor mode, you should be able to trivially modify it using the GUI. -Starting from a screen like that shown in :numref:`groot_nav2_default_bt`, you can pull in new nodes from the side panel to add them to the workspace. -You may then connect the nodes using a "drag and drop" motion between the node's input and output ports to assemble the new nodes into the tree. - -If you select a given node, you can change metadata about it such as its name or values of parameterizable ports. When you're done modifying, simply save the new configuration file and use that on your robot the next time! - -Adding A Custom Node -==================== - -Each node in the behavior tree holds a specialized function. -Sometimes, its useful to create new nodes and add them to your palette during the design process - perhaps before the implementations themselves exist. -This helps designers abstract away the implementation specifics of the nodes from the higher level logic of the tree itself and how they'd like to interact with a given node (e.g. type, ports, etc). -Within Groot, you may create new custom nodes to add to your tree and export these new nodes back to your palette. -Implementing the node itself needs to be done separately from Groot, which is described in :ref:`writing_new_nbt_plugin`. - -+-----------------------------------------------------------+ -| .. figure:: images/Groot/groot_create_custom_node.png | -| :name: groot_create_custom_node | -| | -| Create a new Custom Node | -+-----------------------------------------------------------+ - -Creating a new custom node can be started by clicking the orange marked icon in :numref:`groot_create_custom_node`, while Groot is in Editor mode. -This should load a new window, similar to :numref:`groot_interactive_node_creation`. -In this new window, it asks you to fill in the metadata about this new node, in order to create it. -It will ask you for standard information such as name (green box), type of node (orange box), and any optional ports for parameterization or access to blackboard variables (blue box). - -After completing, select `OK` in :numref:`groot_interactive_node_creation`, the new custom node should appear in blue in the `TreeNode Palette` as in :numref:`groot_export_new_node`. - -+--------------------------------------------------------------+--------------------------------------------------------------+ -| .. figure:: images/Groot/groot_interactive_node_creation.png | .. figure:: images/Groot/groot_export_new_node.png | -| :name: groot_interactive_node_creation | :name: groot_export_new_node | -| | :width: 180% | -| | | -| UI to describing new Nodes | Exporting the new Custom Node | -+--------------------------------------------------------------+--------------------------------------------------------------+ +In the video above you can see Groot side-by-side with RViz and a test platform 100% equipped with ROS-enabled hardware from SIEMENS. -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 `_. +There are tutorials available for both Groot and Groot2, with Groot2 being the newer version. Groot is used with BehaviorTree.CPP v3.x, while Groot2 is designed for v4.x. +Table of Contents +================= -.. code-block:: xml +.. toctree:: + :maxdepth: 1 - - - - coffee - Sense of life - rolling target - - - + groot.rst + groot2.rst