adding bond documentation for lifecycle manager (openelections#47)

* adding bond information

* add in context

* more context

Author: SteveMacenski

concepts/index.rst

@@ -37,8 +37,8 @@ Action servers are used in this stack to communicate with the highest level BT n
 They are also used for the BT navigator to communicate with the subsequent smaller action servers to compute plans, control efforts, and recoveries.
 Each will have their own unique ``.action`` type in ``nav2_msgs`` for interacting with the servers.
 
-Lifecycle Nodes
-===============
+Lifecycle Nodes and Bond
+========================
 
 Lifecycle (or Managed, more correctly) nodes are unique to ROS 2.
 More information can be `found here <https://design.ros2.org/articles/node_lifecycle.html>`_.
@@ -60,6 +60,11 @@ The networking interfaces are deactivated and stop processing, deallocate memory
 The lifecycle node framework is used extensively through out this project and all servers utilize it.
 It is best convention for all ROS systems to use lifecycle nodes if it is possible.
 
+Within Navigation2, we use a wrapper of LifecycleNodes, ``nav2_util LifecycleNode``.
+This wrapper wraps much of the complexities of LifecycleNodes for typical applications.
+It also includes a ``bond`` connection for the lifecycle manager to ensure that after a server transitions up, it also remains active.
+If a server crashes, it lets the lifecycle manager know and transition down the system to prevent a critical failure. See :ref:`eloquent_migration` for details.
+
 Behavior Trees
 **************
 

configuration/packages/configuring-lifecycle.rst

@@ -10,6 +10,7 @@ Source code on Github_.
 The Lifecycle Manager module implements the method for handling the lifecycle transition states for the stack in a deterministic way.
 It will take in a set of ordered nodes to transition one-by-one into the configurating and activate states to run the stack.
 It will then bring down the stack into the finalized state in the opposite order. 
+It will also create bond connections with the servrs to ensure they are still up and transition down all nodes if any are non-responsive or crashed.
 
 Parameters
 **********
@@ -36,6 +37,17 @@ Parameters
   Description
     Whether to transition nodes to active state on startup.
 
+:bond_timeout_ms:
+
+  ==== =======
+  Type Default                                                   
+  ---- -------
+  int  4000   
+  ==== =======
+
+  Description
+    Timeout to transition down all lifecycle nodes of this manager if a server is non-responsive, in ms. Set to ``0`` to deactivate. Recommended to be always larger than 300ms for all-local node discovery. Note: if a server cleanly exits the manager will immediately be notified.
+
 Example
 *******
 .. code-block:: yaml
@@ -44,3 +56,4 @@ Example
       ros__parameters:
         autostart: true
         node_names: ['controller_server', 'planner_server', 'recoveries_server', 'bt_navigator', 'waypoint_follower']
+        bond_timeout_ms: 4000

index.rst

@@ -49,7 +49,7 @@ It has tools to:
 - build complicated robot behaviors using behavior trees (Nav2 Behavior Trees and BT Navigator)
 - Compute recovery behaviors in case of failure (Nav2 Recoveries)
 - Follow sequential waypoints (Nav2 Waypoint Follower)
-- Manage the lifecycle of the servers (Nav2 Lifecycle Manager)
+- Manage the lifecycle and watchdog for the servers (Nav2 Lifecycle Manager)
 - Plugins to enable your own custom algorithms and behaviors (Nav2 Core)
 
 .. image:: images/architectural_diagram.png

migration/Eloquent.rst

@@ -16,6 +16,10 @@ They are the ``navigation_lifecycle_manager`` and ``localization_lifecycle_manag
 This gives each process their own manager to allow users to switch between SLAM and localization without effecting Navigation.
 It also reduces the redundant code in ``nav2_bringup``.
 
+The lifecycle manager also now contains ``Bond`` connections to each lifecycle server.
+This means that if a server crashes or exits, the lifecycle manager will be constantly checking and transition down its lifecycle nodes for safety.
+This acts as a watchdog during run-time to complement the lifecycle manager's transitioning up and down from active states. See `this PR for details <https://github.com/ros-planning/navigation2/pull/1894>`_.
+
 A fix to the BT navigator was added to remove a rare issue where it may crash due to asynchronous issues.
 As a result, a behavior tree is created for each navigation request rather than resetting an existing tree.
 The creation of this tree will add a small amount of latency.