You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`Groot <https://github.com/BehaviorTree/Groot>`_ is the companion application of
25
+
`Groot <https://github.com/BehaviorTree/Groot>`_ is the companion application of the C++ library
25
26
`BehaviorTree.CPP <https://github.com/BehaviorTree/BehaviorTree.CPP>`_ to create, edit, and monitor behavior trees.
26
-
With Groot one can visualize, edit and create new behavior trees. Also, complete new custom nodes except control flow nodes can be created using Groot.
27
-
`Recently added <https://github.com/ros-planning/navigation2/pull/1958>`_ to the ROS2 and nav2 implementation of BT.cpp V3 is live monitoring of the current status of the behavior tree.
27
+
Behavior Trees are deeply integrated into Nav2, while not being strictly ROS dependent. Behavior Trees, in short BTs, consist out of multiples leave nodes.
28
+
Such leave nodes must be type of either `Action`, `Condition`, `Control`, `Decorator`, or `SubTree`.
29
+
These types are described in more detail at the chapter `Creating your Custom Node`_.
30
+
31
+
Each node must be written in C++ and can be loaded as plugins into a factory.
32
+
The `BehaviorTree Documentation <../../plugin_tutorials/docs/writing_new_bt_plugin.html>`_ offers well written examples of creating a simple node, that make use of existing Macros for convenient adding them into your Behavior Tree.
33
+
Dynamic at runtime and C++ are perfectly combined through the underlying builder-factory mechanism and class-loader mechanics of plugins provided through shared-objects.
34
+
35
+
While it is crucial to correctly implement the individual nodes, the composition of the individual nodes is as least as important.
36
+
BehaviorTree.Cpp brings a lot of dynamic with it. This dynamic can be controlled with XML-files that hold the construction plan for the integrated factory.
37
+
XML in this case only describes the logic how the different nodes are combined through an own Domain specific langugage.
38
+
Groot basically helps to visually understand and work with those special XML-files. The XML Format is defined `in detail here <https://www.behaviortree.dev/xml_format/>`_.
39
+
40
+
Groot can not only visualize the XML describing the BT, but also edit and even create new behavior trees. Additionally, complete new custom nodes can be described using Groot.
41
+
This helps to describe the functionality of your application at a higher abstraction layer.
42
+
If ROS is your given Middleware in this case, BTs can be described as "Top-Ware" and Groot helps you visualize it similar to a down stripped RVIz.
43
+
`Groot support for Nav2 <https://github.com/ros-planning/navigation2/pull/1958>`_ is integrated into Nav2 with the latest version of BT.cpp V3.
44
+
45
+
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.
46
+
Groot not only displays the current BehaviorTree, but also shows the current active nodes in near real-time, all while the real robot operates.
47
+
Understanding the visual output of Groot will be explained in chapter `Live Monitoring Behavior Trees`_.
3. Open the file `/path/to/navigation2/nav2_behavior_tree/nav2_tree_nodes.xml` to import all the behavior tree nodes used for navigation.
76
+
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. Now Groot should look like in :numref:`groot_bt_editor_with_nodes`.
48
77
4. Select `Load tree` option near the top left corner
49
-
5. Browse the tree you want to visualize the select ok.
78
+
5. Browse the tree you want to visualize, then select ok. The Nav2 BTs exist in `/path/to/navigation2/nav2_bt_navigator/behavior_trees/`
In case you choose the default tree `navigate_w_replanning_and_recovery.xml`, then your Groot editor should display :numref:`groot_nav2_default_bt`.
52
81
53
82
.. note::
54
-
If a tree cannot be visualized because some nodes are missing in the pallet, you might need to visit :ref:`plugins` and search for the plugin that is missing.
83
+
If a tree cannot be visualized because some nodes are missing in the pallet, you might need to visit the BehaviorTree section of :ref:`plugins` and search for the plugin that is missing.
55
84
If you got all the optional blackboard fields from the code of the plugin, you are free to go to add the description to ``/path/to/navigation2/nav2_behavior_tree/nav2_tree_nodes.xml``.
85
+
You can create the missing xml description of that particular node by following the steps of `Creating your Custom Node`_.
56
86
Now you can reload the pallet from this updated file and should be able to work with the tree.
57
87
58
-
Monitoring mode is unaffected from this, as the whole factory with sufficient meta data gets transferred upon connection.
59
-
This is a known issue to reduce the overhead of creating additional xml-node-description files, when the data is also available in the shared object.
60
-
Feel free to support adding this feature to the open source project Groot. The `feature request <https://github.com/BehaviorTree/Groot/issues/10>`_ already exists for this.
Remember, there exists 5 different categories for Nodes, they are called `Action`, `Condition`, `Control`, `Decorator`, and `SubTree`.
99
+
Each of them holds a special functionality. Detailed descriptions can be taken from the `official BehaviorTree Documentation <https://www.behaviortree.dev/bt_basics/#types-of-nodes>`_.
100
+
101
+
The Groot specification of any of those nodes help in an early design process for your BT.
102
+
It also guides the user on setting any Input or Output-Ports conveniently.
103
+
Both, the node-palette and the resulting BehaviorTree (composition of nodes) can profit from using Groot.
104
+
But, only creating a new node in Groot is not all that you need, except for SubTrees that can be fully designed with Groot.
105
+
Try seeing Groot as a tool that complies to all the `BT specific xml-format rules <https://www.behaviortree.dev/xml_format/>`_.
106
+
107
+
Implementing the C++ features of your node needs to be done separately from Groot, which is described in :ref:`writing_new_nbt_plugin`.
108
+
109
+
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.
110
+
This should load a new window, similar to :numref:`groot_interactive_node_creation`.
111
+
In this new window multiple small steps must be fulfilled, in order to create a new custom node. First, a name must be defined in the green field.
112
+
Second, the type of the new node must be defined in the orange drop down menu.
113
+
Optionally, input and output-ports can be defined for data exchange on the blackboard.
114
+
They are managed trough the buttons in the blue box.
115
+
After pressing `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`.
The BehaviorTree above shows the current default BehaviorTree of Nav2.
163
+
In short, the left side is responsible for the default navigation towards a goal and the right side tries to handle errors during the navigation process.
164
+
With the help of live monitoring, it can not only be seen which node(s) are currently active - orange color -, but also which nodes returned a `SUCCESS` and which a `FAILURE` response code.
165
+
For instance here the different stages of the recovery behavior can be observed, while one after one node turns green.
70
166
71
-
In order to live monitor a running behavior tree, a few easy steps are necessary.
167
+
As described, with Groot one can see in addition to tools like RVIz, at which certain condition a given task failed.
168
+
This enables a complete new way of debugging, as the operator or engineer does not need to know the complete robot architecture off his head.
169
+
BehaviorTrees cannot give a deep view inside the code-stack, but they can help pinpointing problems due to the modular architecture enforced by BTs.
72
170
73
-
Behavior trees of the BT.cpp V3 kind do not automatically include monitoring.
74
-
This is and always should be an optional feature as it involves opening an additional communication layer: ``ZMQ``.
171
+
In order to enable live monitoring for your robot, a few easy steps are necessary.
75
172
76
-
Adding the monitoring feature to nav2 therefore involves activating a special parameter listed in :ref:`configuring_bt_navigator`.
77
-
After activating ``enable_groot_monitoring``, the zmq network ports for a ``zmq-server`` and ``zmq-publisher`` can be set optionally.
173
+
Behavior trees of the BT.cpp V3 library do not automatically include monitoring.
174
+
To enable monitoring with Groot, an additional logger has to be attached to the BT.
175
+
For communication between the BT and Groot, the middleware `ZMQ` has been chosen.
78
176
79
-
Given the launch-parameters are set correctly, the navigation2 stack has to be started normally first.
80
-
Regardless of simulation or real hardware, **monitoring only works if the behavior tree is currently running!**
177
+
Monitoring with Groot in Nav2 is enabled by default.
178
+
It can be deactivated by setting ``enable_groot_monitoring`` to `false`, as seen in :ref:`configuring_bt_navigator`.
179
+
If desired, the `ZMQ` network ports for ``zmq-server`` and ``zmq-publisher`` can be set optionally.
180
+
The defaults correspond to the default networking-ports within Groot.
181
+
182
+
To try the live monitoring features, a few prerequisites have to be met.
183
+
Given the launch-parameters are set correctly, the navigation2 stack has to be started first.
184
+
Regardless of simulation or real hardware, it is important to note that **monitoring only works if the behavior tree is currently running!**
81
185
82
186
A step-by-step guide for simulation can look like this:
83
187
84
-
1. complete :ref:`getting_started` and be able to run the tb3 simulation
85
-
2. set ``enable_groot_monitoring`` to ``True`` in the ``params.yaml`` file
86
-
3. (re-)start the tb3 simulation (optionally with ``headless:=True`` for only RVIZ as GUI)
87
-
4. set the initial pose of the robot -> this will activate the whole navigation2 stack (check if they are active)
88
-
5. start Groot and choose the monitor mode
89
-
6. press connect in the upper left corner (``Server IP``, ``Publisher Port``, and ``Server Port`` can all be left to the default for the simulation)
90
-
7. the behavior tree should now be visible in Groot
91
-
8. send a new goal to your robot (can also include a new behaviorTree.xml, which gets loaded automatically)
92
-
9. watch your robot drive in simulation and see how Groot automatically watches the state of your behavior tree
188
+
1. Complete :ref:`getting_started` and be able to run the tb3 simulation
189
+
2. Check if ``enable_groot_monitoring`` is set to ``True`` in the ``params.yaml`` file in ``nav2_bringup/bringup/params``
190
+
3. Start the tb3 simulation
191
+
4. Set the initial pose of the robot -> this will activate the whole navigation2 stack
192
+
5. Start Groot and choose the monitor mode
193
+
6. Press connect in the upper left corner (``Server IP``, ``Publisher Port``, and ``Server Port`` can all be left to the default for the simulation)
194
+
7. The behavior tree should be visible now in Groot
195
+
8. Send a new goal to your robot through RVIz
196
+
9. Watch your robot drive in simulation and see how Groot automatically monitors the state of your behavior tree
197
+
93
198
94
199
Real world robots can easily be adapted to this. Just change the ``Server IP``
95
-
and zmq network ports accordingly to your local environment.
200
+
and optionally different zmq network ports accordingly to your local environment.
201
+
202
+
Reloading of the behavior tree in Groot is done on multiple occasions and works completely automatically.
203
+
Sending a new goal with a different BT.xml will also trigger Groot to reload the new BT to display and monitor.
204
+
More about `Groot reloading the BT <https://github.com/BehaviorTree/Groot/pull/96>`_ can be seen in the merged PR here.
96
205
97
-
Reloading of the behavior tree in Groot is done on multiple occasions,
98
-
but only when a new behavior tree is loaded by nav2 or Groot is restarted. More about `Groot reloading the BT <https://github.com/BehaviorTree/Groot/pull/96>`_ can be seen in the merged PR here.
206
+
207
+
.. note::
208
+
Monitoring mode is unaffected from failing to display BTs with custom nodes that are not already imported into Groot, unlike the Editor Mode.
209
+
This is due the fact that the whole BT-factory with sufficient meta data gets transferred upon the first connection with Groot.
210
+
There is a known issue to reduce the overhead of creating additional xml-node-description files, when the data is also available in the shared object.
211
+
Feel free to support adding this feature to the open source project Groot. The `feature request <https://github.com/BehaviorTree/Groot/issues/10>`_ already exists for this.
0 commit comments