Coverage server docs (ros-navigation#488)

* adding coverage server docs

* moving file

behavior_trees/index.rst

@@ -48,5 +48,6 @@ This tree contains:
 - No integration with automatic door, elevator, or other APIs
 - No user provided custom BT nodes
 - No subtrees for other behaviors like docking, following, etc.
+- No use of other types of planners, like complete coverage (where useful)
 
 All of this, and more, can be set and configured for your customized navigation logic in Nav2.

configuration/index.rst

@@ -14,6 +14,7 @@ the best navigation performance.
    packages/configuring-costmaps.rst
    packages/configuring-lifecycle.rst
    packages/configuring-planner-server.rst
+   packages/configuring-coverage-server.rst
    packages/configuring-navfn.rst
    packages/configuring-smac-planner.rst
    packages/configuring-thetastar.rst

configuration/packages/bt-plugins/actions/CancelCoverage.rst

@@ -0,0 +1,39 @@
+.. _bt_cancel_coverage:
+
+CancelCoverage
+=============
+
+Used to cancel the goals given to the complete coverage action server. The server address can be remapped using the ``server_name`` input port.
+
+Input Ports
+-----------
+
+:service_name:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  string N/A  
+  ====== =======
+
+  Description
+    	Service name.
+
+
+:server_timeout:
+
+  ====== =======
+  Type   Default
+  ------ -------
+  double 10  
+  ====== =======
+
+  Description
+    	Server timeout (ms).
+
+Example
+-------
+
+.. code-block:: xml
+
+  <CancelCoverage server_name="compute_complete_coverage" server_timeout="10"/>

configuration/packages/bt-plugins/actions/ComputeCoveragePath.rst

@@ -0,0 +1,135 @@
+.. _bt_compute_path_through_poses_action:
+
+ComputeCoveragePath
+===================
+
+Invokes the ComputeCoveragePath ROS 2 action server, which is implemented by the opennav_coverage_ server module. 
+The server address can be remapped using the ``server_name`` input port.
+This server can take in both cartesian and GPS coordinates and is implemented using the ``Fields2Cover`` library.
+
+.. _opennav_coverage: https://github.com/open-navigation/opennav_coverage
+
+Input Ports
+-----------
+:generate_headland:
+
+  ===================================== =======
+  Type                                  Default
+  ------------------------------------- -------
+  bool                                  true  
+  ===================================== =======
+
+  Description
+    	Whether or not to generate a headland of the field or polygon to compute coverage of
+
+:generate_route:
+
+  ============================================= =======
+  Type                                          Default
+  --------------------------------------------- -------
+  bool                                          true  
+  ============================================= =======
+
+  Description
+    	Whether or not to generate a route, e.g. an ordered set of swaths
+
+:generate_path:
+
+  ============== =======
+  Type           Default
+  -------------- -------
+  bool           true  
+  ============== =======
+
+  Description
+      Whether or not to generate a path, e.g. adding path connectors to the ordered route
+
+:file_field:
+
+  ============== =======
+  Type           Default
+  -------------- -------
+  string         N/A  
+  ============== =======
+
+  Description
+    	The filepath to the field's GML file to use, if not specifying the field via ``polygons``
+
+
+:file_field_id:
+
+  ============== =======
+  Type           Default
+  -------------- -------
+  int            0  
+  ============== =======
+
+  Description
+    	The ID of the field in the GML File to use, if multiple exist in the same file. This is the ordered number of the fields in the file.
+
+:polygons:
+
+  =================================== =======
+  Type                                Default
+  ----------------------------------- -------
+  vector<geometry_msgs::msg::Polygon>  N/A 
+  =================================== =======
+
+  Description
+      The polygons of the field, if not specifying via a GML file. The first polygon should be the outermost region, whereas additional polygons are voids.
+
+:polygons_frame_id:
+
+  =================================== =======
+  Type                                Default
+  ----------------------------------- -------
+  string                              "map" 
+  =================================== =======
+
+  Description
+      The polygon's frame ID, since the GML file provides the frame ID for its format, this is the frame ID for user-defined input ``polygons``.
+
+Output Ports
+------------
+
+:nav_path:
+
+  ========================== =======
+  Type                       Default
+  -------------------------- -------
+  nav_msgs::msg::Path         N/A  
+  ========================== =======
+
+  Description
+    	Path created by action server in the form of a navigation path. Takes in a blackboard variable, e.g. "{path}".
+
+:coverage_path:
+
+  ========================== =======
+  Type                       Default
+  -------------------------- -------
+  vector<PathComponents>      N/A  
+  ========================== =======
+
+  Description
+      An ordered set of swaths and turns corresponding to the coverage path when its important to distinguish between turns and swaths for applications. A ``opennav_coverage::utils::PathComponentsIterator`` object is provided to help make this easy to use by iterating through the outputs's path components to return you the next swath and turn one at a time.
+
+:error_code_id:
+
+  ============== =======
+  Type           Default
+  -------------- -------
+  uint16          N/A  
+  ============== =======
+
+  Description
+    	Compute coverage error code. See ``ComputeCoveragePath`` action message for the enumerated set of error codes.
+
+Example
+-------
+
+.. code-block:: xml
+
+  <ComputeCoveragePath file_field="{field_filepath}" nav_path="{path}" coverage_path="{cov_path}" server_name="ComputeCoverage" server_timeout="10" error_code_id="{compute_coverage_error_code}"/>
+
+Note: the blackboard IDs for the path, error code, and more may be adjusted,but need to match the corresponding parameters in the ``CoverageNavigator`` plugin to set on the blackboard for use from the action server.

configuration/packages/configuring-bt-navigator.rst

@@ -13,6 +13,8 @@ in the navigation task and provide a way to easily specify complex robot behavio
 
 Consider checking out the :ref:`groot_introduction` 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).
+
 Parameters
 **********
 

configuration/packages/configuring-bt-xml.rst

@@ -39,6 +39,8 @@ Action Plugins
   bt-plugins/actions/GoalCheckerSelector.rst
   bt-plugins/actions/NavigateThroughPoses.rst
   bt-plugins/actions/ComputePathThroughPoses.rst
+  bt-plugins/actions/ComputeCoveragePath.rst
+  bt-plugins/actions/CancelCoverage.rst
   bt-plugins/actions/RemovePassedGoals.rst
   bt-plugins/actions/CancelControl.rst
   bt-plugins/actions/CancelBackUp.rst