path follower documentation

docs/developer-guide/rosplane/navigation/navigation-overview.md

@@ -7,7 +7,7 @@ In their work, the path planning functionality of the aircraft is split into thr
 !!! note
     This is not a full description of the architecture.
     For example, the state estimator is not shown, and not all of the inputs to each of the blocks is included.
-    These elements were removed from the figure for clarity.
+    These elements were removed from the figure for simplicity.
 
 | ![Diagram of Path Planning Architecture](../../../assets/path_planner_assets/path-planning-overview.svg "Path Planning Architecture") |
 | :--: |

docs/developer-guide/rosplane/navigation/path-follower.md

@@ -1,5 +1,80 @@
 # Path Follower
 
 ## Overview
-The path follower subscribes to the current path published by the path manager. 
-It takes in the 
+The role of the path follower is to generate the correct airspeed, course, and altitude commands for the autopilot such that the aircraft follows the paths published by `path_manager`.
+
+
+More information on the `path_follower` can be found in *Small Unmanned Aircraft: Theory and Practice* by Dr. Randal Beard and Dr. Tim McLain.
+
+## Path Follower Base
+The path follower base contains all the ROS2 interfaces required for the path follower.
+A list of these interfaces is below.
+
+The `path_follower_base::follow` method is a virtual method that should be implemented by a derived class.
+The `path_follower_base` publishes the controller commands calculated by the implementation of `path_follower_base::follow`.
+
+### List of ROS2 Interfaces
+
+| **ROS2 Interface** | **Topic or Service** | **Explanation** | **Message or Service Type** |
+| :---: | :---: | :---: | :---: |
+| `vehicle_state_sub_` | `/estimated_state` | Subscribes to the estimated aircraft state | `rosplane_msgs::msg::State` |
+| `current_path_sub_` | `/current_path` | Subscribes to the current path messages published by `path_manager` | `rosplane_msgs::msg::CurrentPath` |
+| `controller_commands_pub_` | `/controller_commands` | Publishes control commands to the autopilot | `rosplane_msgs::msg::ControllerCommand` |
+| `update_timer_` | -- | ROS2 timer that controls how frequently `controller_commands_pub_` publishes | -- |
+
+### Interface with the Autopilot
+The `path_follower` node interfaces with the MAV autopilot by publishing to the `/controller_commands` topic.
+The `/controller_commands` topic contains the following information calculated by the `path_follower`:
+
+| **Member** | **Description** | **Type / units** | **Required** |
+| :---: | :---: | :---: | :---: |
+| `header` | Standard message header that contains a valid timestamp | `std_msgs::msg::Header` | Yes |
+| `va_c` | Commanded airspeed | `double`, m/s | Yes |
+| `h_c` | Commanded altitude | `double`, m | Yes |
+| `chi_c` | Commanded course | `double`, rad | Yes |
+| `phi_ff` | Feedforward command (for orbits) | `double`, rad | No |
+
+## Path Follower Example
+The `path_follower_example` class contains the implementation of the `path_follower_base::follow` method.
+This method contains the control command computations for straight line and orbit-type paths as outlined in *Small Unmanned Aircraft: Theory and Practice*.
+
+## Parameters
+See the [Parameter Management](../parameter-management.md) page for more details on how parameter management works.
+
+### List of Parameters
+| **Parameter** | **Explanation** | **Type / Units** | **Range** |
+| :---: | :---: | :---: | :---: |
+| `chi_infty` | At infinity, the angle at which the aircraft will approach the desired line | double (rad) | $\frac{\pi}{2} \geq \chi^{\infty} > 0.0$ |
+| `k_path` | Constant that determines how quickly commanded course transitions from $\chi^{\infty}$ to 0 during line following | double | $> 0.0$|
+| `k_orbit` | Constant that determines how quickly commanded course transitions from $\lambda \frac{\pi}{2}$ to 0 during an orbit | double | $> 0.0$|
+
+Since there are two different types of lines generated by the `path_manager` (straight lines and orbits), the `path_follower` uses different parameters to calculate the control output for each path type.
+
+For **line following**, `path_follower` uses 
+
+- `chi_infty` and 
+- `k_path` to compute the control commands.
+
+As described in *Small Unmanned Aircraft: Theory and Practice*, these two parameters define a vector field for the commanded course.
+The `chi_infty` parameter describes the angle at which the aircratft will approach a target line if the aircraft is infinitely far from the target line.
+For example, if `chi_infty` is set to $\frac{\pi}{2}$, then the aircraft will approach the target line at an angle perpindicular to the line when the aircraft is far away.
+
+The `k_path` parameter defines how quickly the vectors at `chi_infty` "smooth" into the target line.
+When `k_path` is large, the transition will be abrupt, and when `k_path` is small, the transition will be smoother.
+
+During **orbit following**, `path_follower` uses
+
+- `k_orbit` to compute the control commands.
+
+If the aircraft is very far away from the orbit, it will align itself so it flies directly at the center of the orbit.
+The `k_orbit` parameter is similar to the `k_path` parameter in that it determines how quickly the commanded angle of the aircraft will change from directly toward the center to the orbit direction.
+
+!!! note
+    When tuning, make sure you are changing the correct gains for the type of line (straight or orbit) the aircraft is tracking.
+    `chi_infty` and `k_path` will not affect the orbit performance!
+
+
+## Modifying the Path Follower
+Changes to any of the ROS2 interface should be done in the `path_follower_base`.
+
+Changes to how `path_follower` computes control commands to follow paths given by the `path_manager` should be done in the `path_manager_example`.

docs/developer-guide/rosplane/navigation/path-manager.md

@@ -74,4 +74,4 @@ If the aircraft is pointing slightly right as it approaches the waypoint, it wil
 Changes or additions to any ROS2 interfaces should be done in the `path_manager_base` field.
 
 Changes to how `path_manager` "manages" the waypoints should be done by overriding the `path_manager_base::manage` method.
-If you wish to change the way paths are defined, make sure that the `/current_path` topic is rewritten to contain the required information.
+If you wish to change the way paths are defined, make sure that the `/current_path` topic is rewritten to contain the required information, and then make sure the `path_follower` knows how to handle the new definition.

mkdocs.yml

@@ -79,7 +79,7 @@ nav:
         - Total Energy Controller: developer-guide/rosplane/controller/controller-total-energy.md
       - Parameter Management: developer-guide/rosplane/parameter-management.md
       - Navigation: 
-        - Path Planning Overview: developer-guide/rosplane/navigation/navigation-overview.md
+        - Navigation Overview: developer-guide/rosplane/navigation/navigation-overview.md
         - Path Planner: developer-guide/rosplane/navigation/path-planner.md
         - Path Manager: developer-guide/rosplane/navigation/path-manager.md
         - Path Follower: developer-guide/rosplane/navigation/path-follower.md