Add CI Testing Section

README.md

@@ -5,9 +5,11 @@ This folder holds the source and configuration files used to generate the
 [Navigation2 documentation](https://navigation.ros.org) web site.
 
 Dependencies for Build: 
-* [Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html)
+
 * `sudo apt install python3-pip`
-* `pip3 install breathe==4.12.0 sphinx_rtd_theme sphinxcontrib-plantuml`
+* `pip3 install sphinx==1.7.5 docutils==0.14 sphinx_rtd_theme breathe==4.9.1 sphinxcontrib-plantuml`
+
+(as in the .circleci/config.yaml)
 
 Build the docs locally with `make html` and you'll find the built docs entry point in `_build/html/index.html`.
 

configuration/packages/configuring-bt-navigator.rst

@@ -53,6 +53,43 @@ Parameters
   Description
     List of behavior tree node shared libraries.
 
+:enable_groot_monitoring:
+
+  ==== =======
+  Type Default
+  ---- -------
+  bool false
+  ==== =======
+
+  Description
+    Enable live Groot monitoring of the current BT status.
+    This is possible due to attaching a ZMQ server and publisher to the active behavior tree.
+    Consider checking out the :ref:`groot_introduction` tutorial for using this feature. 
+
+    **Attention:** Groot will only work after the behavior tree is running, which means that the nav2 stack has to receive a goal first.
+
+:groot_zmq_publisher_port:
+
+  ====== ======= ======= ========
+  Type   Default Unit    Optional
+  ------ ------- ------- --------
+  int    1666    Port    yes
+  ====== ======= ======= ========
+
+  Description
+    ZMQ publisher port for the Groot monitor. Used to consecutive publish the current status of the BT as flatbuffer.
+
+:groot_zmq_server_port:
+
+  ====== ======= ======= ========
+  Type   Default Unit    Optional
+  ------ ------- ------- --------
+  int    1667    Port    yes
+  ====== ======= ======= ========
+
+  Description
+    ZMQ server port for the Groot monitor. Used to send the current bt factory + configuration as flatbuffer on an (empty) request by Groot.
+
 :transform_tolerance:
 
   ====== ======= ======= 
@@ -118,6 +155,9 @@ Example
         global_frame: map
         robot_base_frame: base_link
         transform_tolerance: 0.1
+        enable_groot_monitoring: True
+        groot_zmq_publisher_port: 1666
+        groot_zmq_server_port: 1667
         bt_xml_filename: replace/with/path/to/bt.xml
         plugin_lib_names: 
         - nav2_compute_path_to_pose_action_bt_node

plugin_tutorials/docs/writing_new_bt_plugin.rst

@@ -169,7 +169,7 @@ In BehaviorTree.CPP, exporting and loading plugins is handled by the ``BT_REGIST
 In this macro, we must create a ``NodeBuilder`` so that our custom action node can have a non-default constructor signature (for the action and xml names).
 This lambda will return a unique pointer to the behavior tree node we have created.
 Fill in the constructor with the relavent information, giving it the ``name`` and ``config`` given in the function arguments.
-Then define the ROS 2 action server's name that this BT node will call, in this case, its the `wWait`` action.
+Then define the ROS 2 action server's name that this BT node will call, in this case, its the ``wait`` action.
 
 We finally give the builder to a factory to register.
 ``Wait`` given to the factory is the name in the behavior tree XML file that corresponds to this BT node plugin.

tutorials/docs/groot.rst

@@ -0,0 +1,88 @@
+.. _groot_introduction:
+
+Groot - The fancy BehaviorTree Editor
+*************************************
+- `Overview`_ 
+- `Edit Custom Behavior Trees`_
+- `Live Monitoring Behavior Trees`_
+
+Overview
+========
+
+ .. image:: images/Groot/groot_start_menu.png
+
+`Groot <https://github.com/BehaviorTree/Groot>`_ is the companion application of 
+`BehaviorTree.CPP <https://github.com/BehaviorTree/BehaviorTree.CPP>`_ to create, edit, and monitor behavior trees.
+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.
+`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.
+
+Edit Custom Behavior Trees
+==========================
+
+.. .. image:: images/Groot/codecov.io_show_covered_code.png
+  :width: 80%
+
+A few steps are necessary to view and edit existing behavior trees:
+
+1. Open Groot in editor mode
+2. Select the `Load palette from file` option  (import button) near the top left corner.
+
+
+.. image:: images/Groot/groot_bt_editor.png
+  :width: 49%
+
+.. image:: images/Groot/groot_with_nav2_custom_nodes.png
+  :width: 49%
+
+3. Open the file `/path/to/navigation2/nav2_behavior_tree/nav2_tree_nodes.xml` to import all the behavior tree nodes used for navigation.
+4. Select `Load tree` option near the top left corner
+5. Browse the tree you want to visualize the select ok.
+
+.. image:: images/Groot/bt_w_replanning_and_recovery.png
+
+.. note::
+  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.
+  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``.
+  Now you can reload the pallet from this updated file and should be able to work with the tree.
+
+  Monitoring mode is unaffected from this, as the whole factory with sufficient meta data gets transferred upon connection.
+  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.
+  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.
+
+Also, the Groot editor allows for creating new custom nodes via its graphical user interface. This also works with nav2 except custom control nodes.
+
+Live Monitoring Behavior Trees
+==============================
+
+.. raw:: html
+
+  <a href="https://gifyu.com/image/cFdR"><img src="https://s7.gifyu.com/images/Groot-Test-5FPS.gif" alt="Groot-Test-5FPS.gif" border="0" /></a>
+
+In order to live monitor a running behavior tree, a few easy steps are necessary.
+
+Behavior trees of the BT.cpp V3 kind do not automatically include monitoring. 
+This is and always should be an optional feature as it involves opening an additional communication layer: ``ZMQ``.
+
+Adding the monitoring feature to nav2 therefore involves activating a special parameter listed in :ref:`configuring_bt_navigator`.
+After activating ``enable_groot_monitoring``, the zmq network ports for a ``zmq-server`` and ``zmq-publisher`` can be set optionally.
+
+Given the launch-parameters are set correctly, the navigation2 stack has to be started normally first.
+Regardless of simulation or real hardware, **monitoring only works if the behavior tree is currently running!**
+
+A step-by-step guide for simulation can look like this:
+
+  1. complete :ref:`getting_started` and be able to run the tb3 simulation
+  2. set ``enable_groot_monitoring`` to ``True`` in the ``params.yaml`` file
+  3. (re-)start the tb3 simulation (optionally with ``headless:=True`` for only RVIZ as GUI)
+  4. set the initial pose of the robot -> this will activate the whole navigation2 stack (check if they are active)
+  5. start Groot and choose the monitor mode
+  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)
+  7. the behavior tree should now be visible in Groot
+  8. send a new goal to your robot (can also include a new behaviorTree.xml, which gets loaded automatically)
+  9. watch your robot drive in simulation and see how Groot automatically watches the state of your behavior tree 
+
+Real world robots can easily be adapted to this. Just change the ``Server IP`` 
+and zmq network ports accordingly to your local environment.
+
+Reloading of the behavior tree in Groot is done on multiple occasions, 
+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.