Merge pull request #16 from rosflight/controller_documentation

Controller documentation

docs/developer-guide/rosplane/controller/controller-base.md

@@ -0,0 +1,53 @@
+# Controller Base
+
+## Overview
+
+The controller base implements the basic ROS interfaces for the controller.
+This includes setting up subscribers, publishers and initializing parameter management.
+The idea of the base class, is that all interfacing with ROS and shared resources across all inheritance levels happens or are contained in this class.
+
+## ROS interfaces
+
+The controller base has the following ROS interactions.
+
+| ![Diagram of Controller ROS Interactions](../../../assets/controller_assets/Controller_ROS.png "Controller ROS Interactions") |
+|:--:|
+|*Figure 1: Controller's ROS interactions.*|
+
+The controller has four ROS interfaces that are tracked as member variables of the class.
+These interfaces are the only points of contact that influence the every layer of the controller along side the node parameters.
+Each of the callbacks for the subscribers are also contained in `controller_base`.
+
+| ROS Interface | Topic | Explanation | Message Type |
+|:------:|:-------:| :---: | :---: |
+| <div style="white-space: nowrap;">`actuators_pub_`<div> | `/command` | Publishes the acutator commands for the aircraft. The publishing rate is controller by the `timer_` object. | Command.msg |
+| <div style="white-space: nowrap;">`internals_pub_`<div> | `/controller_inners_debug` | Publishes the intermediate values created by the outer control loops. Published simultaneously as the commands when there is at least one subscriber to the topic. | ControllerInnersDebug.msg |
+| <div style="white-space: nowrap;">`controller_commands_sub_`<div> | `/controller_commands` | Subscribes to the commands for the controller. | ControllerCommands.msg |
+| <div style="white-space: nowrap;">`vehicle_state_sub_`<div> | `/estimated_state` | Subscribes to the estimated state of the aircraft. | State.msg |
+
+!!! note 
+    The command message is from the `rosflight_msgs` package not the `rosplane_msgs` package.
+
+## Parameter Management
+
+See the [Parameter Management](../parameter-management.md) page for more details on how parameter management works.
+
+### List of Parameters
+
+| Parameter | Explanation | Range |
+|:--:|:--:|:--:|
+| pwm_rad_e | Radian to PWM conversion for the elevator. | $\geq 1.0$ (double) |
+| pwm_rad_a | Radian to PWM conversion for the ailerons. | $\geq 1.0$ (double) |
+| pwm_rad_r | Radian to PWM conversion for the rudder. | $\geq 1.0$ (double) |
+| frequency | Frequency of the timer, effective control loop closure frequency. | $\geq 100$ (hertz, int) |
+
+## Modifying Controller Base
+
+The `controller_base` class should only contain things that are necessary for each layer of the controller.
+If you are considering adding something to the controller, but it only applies to one layer, perhaps reconsider.
+All ROS related items should also be stored here.
+For example, if you needed to use another topic subscription, the new subscriber should be created and stored in `controller_base`.
+
+As shown in the [Controller Software Architecture](./controller-software-architecture.md) page, you may need to modify the `main` function in `controller_base.cpp` to use a newly implemented controller.
+
+

docs/developer-guide/rosplane/controller/controller-general-overview.md

@@ -0,0 +1,93 @@
+# ROSplane Controller
+
+## Overview
+
+The ROSplane controller generates the controller commands to achieve the commanded states that the path follower directs.
+The controller has the basic function of controlling roll, pitch, yaw, airspeed, course and altitude.
+Higher functions of controlling position and tracking paths is handled by other nodes, the path follower and manager specifically.
+To gain the best understanding of the Controller and its role, read chapter 1 of the UAV book, or the ROSplane Overview page.
+
+<!-- TODO add glam GIF or pic of response to show how awesome ROSplane is  -->
+
+## Interfaces
+
+| ![Diagram of Controller ROS Interactions](../../../assets/controller_assets/Controller_ROS.png "Controller ROS Interactions") |
+|:--:|
+|*Figure 1: Controller's ROS interactions.*|
+
+### Input
+
+The controller receives controller commands using the ControllerCommands message on the `\controller_commands` topic from the `path_follower` node. 
+This set of commands are outlined below, along with a short explanation of each.
+
+| Message Field | Explanation | Units |
+|:------:|:-------:| :---: |
+| header | This contains time stamp information. | Time in Seconds and Nanoseconds (int) |
+| va_c | The commanded airspeed. | Meters per second (float) |
+| h_c | The commanded altitude. | Meters (float) |
+| chi_c | The commanded course. | Radians (float) |
+| phi_ff | Feedforward roll term (for orbits) | Radians (float) |
+| aux[4] | Four array of auxiliary commands | None (float) |
+| aux_valid | Indicates whether aux vector contains actual information. | True/False (bool) |
+
+The controller uses these targets to control the aircraft.
+This drives the aircraft to approach and follow the path as the path_follower commands.
+See the Path Follower page for more information.
+See the Successive Loop Closure Controller Outline for more information on how these commands are used specifically.
+
+!!! note 
+    Poor path performance may be due to controller or the path follower, see the Tuning Guide in the User Guide section for more details.
+
+### Output
+
+The controller calculates the control surface outputs in percent deflection (based around zero) and throttle.
+It formats and the publishes these outputs in the Command message on the `/command` topic.
+There are a further four auxiliary channels that can be used in the Command message, however they are unused typically.
+A summary of the parts of the command message are as follows.
+
+| Message Field | Explanation | Units |
+|:------:|:-------:| :---: |
+| header | This contains time stamp information. | Time in Seconds and Nanoseconds (int) |
+| mode | The control mode (used in multi-rotors) | None (int) |
+| ignore | A bitmask to ignore particular values. | None (int) |
+| x | Aileron Command | Percent deflection in direction [-1.0, 1.0] (float) |
+| y | Elevator Command | Percent deflection in direction [-1.0, 1.0] (float) |
+| z | Rudder Command | Percent deflection in direction [-1.0, 1.0] (float) |
+| f | Throttle Command | Percent of full throttle [0.0, 1.0] (float) |
+
+These are passed to `rosflight_io`, which formats them into MAVLink messages and forwards them onto the FCU.
+!!! note 
+    For this to work the parameters on the `rosflight_firmware` must be set to work for an airplane.
+    See the User Guide on first time start up or README.md for the repository for more details on firmware setup.
+
+## Running the Controller
+
+As mentioned in the ROSplane ROS overview, the controller is in the main `rosplane` ROS package.
+The ROS executable is `rosplane_controller`, yielding the run command:
+
+`ros2 run rosplane rosplane_controller`
+
+The type of controller used is passed right after the executable name, substitute `control_type` for controller being used.
+
+`ros2 run rosplane rosplane_controller control_type`
+
+To pass a set of parameters for the controller from a yaml file using the `--ros-args` option.
+
+`ros2 run rosplane rosplane_controller --ros-args --params-file path/to/params.yaml`
+
+Putting it all together,
+
+`ros2 run rosplane rosplane_controller control_type --ros-args --params-file path/to/params.yaml`
+
+A table of arguments and parameter files that work out of the box is given in the following table.
+!!! note 
+    Filepaths will need to be altered to work.
+!!! note
+    The most common way of running the controller is in through a launch file with the rest of the ROSplane pipeline running as well.
+    See the ROSplane Overview in the Developer and User Guides for more details.
+
+
+| Argument | Explanation | Values |
+|:------:|:-------:| :---: |
+| --params-file | The parameters file that contains the gains and other important parameters. | `rosflight_ws/src/rosplane/rosplane/params/anaconda_autopilot_params.yaml`,`rosflight_ws/src/rosplane/rosplane/params/skyhunter_autopilot_params.yaml` |
+| control_type | These arguements are passed directly to the main function defined in the controller. | `default`, `total_energy` |