Nav2 route server docs (P1)

commander_api/index.rst

@@ -89,12 +89,12 @@ New as of September 2023: the simple navigator constructor will accept a `namesp
 +---------------------------------------+----------------------------------------------------------------------------+
 | cancelTask()                          | Cancel an ongoing task, including route tasks.                             |
 +---------------------------------------+----------------------------------------------------------------------------+
-| isTaskComplete(trackingRoute=False)   | Checks if task is complete yet, times out at ``100ms``. Returns            |
-|                                       | ``True`` if completed and ``False`` if still going. If checking a route    |
-|                                       | tracking task, set default argument to ``True``.                           |
+| isTaskComplete(task=RunningTask.NONE) | Checks if task is complete yet, times out at ``100ms``. Returns            |
+|                                       | ``True`` if completed and ``False`` if still going. Provide the task ID    |
+|                                       | from the long-running task (follow path, compute and track route, etc)     |
 +---------------------------------------+----------------------------------------------------------------------------+
-| getFeedback(trackingRoute=False)      | Gets feedback from task, returns action server feedback msg.               |
-|                                       | If getting feedback on a tracking task, set default argument to ``True``.  |
+| getFeedback(task=RunningTask.NONE)    | Gets feedback from task, returns action server feedback msg.               |
+|                                       | provide the task ID for the task you are requesting.                       |
 +---------------------------------------+----------------------------------------------------------------------------+
 | getResult()                           | Gets final result of task, to be called after ``isTaskComplete``           |
 |                                       | returns ``True``. Returns action server result msg.                        |
@@ -105,6 +105,12 @@ New as of September 2023: the simple navigator constructor will accept a `namesp
 | getPathThroughPoses(start, goals,     | Gets a path through a starting to a set of goals, a list                   |
 | planner_id='', use_start=False)       | of ``PoseStamped``, ``nav_msgs/Path``.                                     |
 +---------------------------------------+----------------------------------------------------------------------------+
+| getRoute(start, goal,                 | Gets a route from a set start and goal nodeIDs or PoseStamped.             |
+| use_start=False)                      | Use Start if given, otherwises uses TF to obtain robot pose.               |
++---------------------------------------+----------------------------------------------------------------------------+
+| getAndTrackRoute(start, goal,         | Gets a route from a set of start and goal NodeIDs or PoseStamped.          |
+| use_start=False)                      | Uses start if given, otherwise uses TF to obtain the robot pose.           |
++---------------------------------------+----------------------------------------------------------------------------+
 | dockRobot(dock_pose, dock_type)       | Attempts to dock the robot at a given docking pose and type, without using |
 |                                       | docking database of known docks.                                           |
 +---------------------------------------+----------------------------------------------------------------------------+
@@ -231,6 +237,7 @@ The ``nav2_simple_commander`` has a few examples to highlight the API functions
 - ``example_waypoint_follower.py`` - Demonstrates the waypoint following capabilities of the navigator, as well as a number of auxiliary methods.
 - ``example_follow_path.py`` - Demonstrates the path following capabilities of the navigator, as well as a number of auxiliary methods like path smoothing.
 - ``example_assisted_teleop.py`` - Demonstrates the assisted teleop capabilities of the navigator.
+- ``example_route.py`` - Demonstrates the route server capabilities of the navigator.
 
 The ``nav2_simple_commander`` has a few demonstrations to highlight a couple of simple autonomy applications you can build using the API:
 

concepts/index.rst

@@ -107,9 +107,10 @@ Recoveries are used to get the robot out of a bad situation or attempt to deal w
 Smoothers can be used for additional quality improvements of the planned path.
 In this section, the general concepts around them and their uses in this project are analyzed.
 
-Planner, Controller, Smoother and Recovery Servers
-==================================================
-Four of the action servers in this project are the planner, behavior, smoother and controller servers.
+Planner, Controller, Smoother, Route, and Behavior Servers
+==========================================================
+
+Four of the action servers in this project are the planner, behavior, smoother, route, and controller servers.
 
 These action servers are used to host a map of algorithm plugins to complete various tasks.
 They also host the environmental representation used by the algorithm plugins to compute their outputs.
@@ -131,6 +132,10 @@ This is done because of the wide variety of behavior actions that may be created
 The behavior server also contains a costmap subscriber to the local costmap, receiving real-time updates from the controller server, to compute its tasks.
 We do this to avoid having multiple instances of the local costmap which are computationally expensive to duplicate.
 
+The route server does not contain multiple "routing algorithms" like the planner or controller servers.
+Instead, it computes a route using a navigation graph using a set of plugins for scoring edges in the graph, parsing graph files, and performing operations along the route, if necessary.
+Rather than freespace planning, this computes a route using a graph that can be generated to represent lanes, areas the robot is allowed to navigate, a teach-and-repeat route, urban roadways, and more.
+
 Alternatively, since the BT nodes are trivial plugins calling an action, new BT nodes can be created to call other action servers with other action types.
 It is advisable to use the provided servers if possible at all times.
 If, due to the plugin or action interfaces, a new server is needed, that can be sustained with the framework.
@@ -173,7 +178,7 @@ However, many classes of controllers and local planners exist.
 It is the goal of this project that all controller algorithms can be plugins in this server for common research and industrial tasks.
 
 Behaviors
-==========
+=========
 
 Recovery behaviors are a mainstay of fault-tolerant systems.
 The goal of recoveries are to deal with unknown or failure conditions of the system and autonomously handle them.
@@ -200,6 +205,13 @@ Use of a separate smoother over one that is included as part of a planner is adv
 The general task in Nav2 for a smoother is to receive a path and return its improved version.
 However, for different input paths, criteria of the improvements and methods of acquiring them exist, creating space for a multitude of smoothers that can be registered in this server.
 
+Route
+=====
+
+The route server is a specialized planner that computes a route using a navigation graph, rather than the freespace costmap.
+The route is computed as the optimal way from the start to the goal through the set of nodes and directional edges in the pre-defined navigation graph.
+This navigation graph can be generated to represent lanes, areas the robot is allowed to navigate, a teach-and-repeat route, urban roadways, and more.
+
 Robot Footprints
 ================
 

configuration/index.rst

@@ -36,3 +36,4 @@ the best navigation performance.
    packages/configuring-waypoint-follower.rst
    packages/configuring-loopback-sim.rst
    packages/configuring-docking-server.rst
+   packages/configuring-route-server.rst