Updated documentation for control abstractions.

rotorpy/controllers/README.md

@@ -1,5 +1,15 @@
 # Controller Module
 
-The simulator is packaged with a geometric tracking controller for a quadrotor, found in `quadrotor_control.py`. Based on [this paper](https://mathweb.ucsd.edu/~mleok/pdf/LeLeMc2010_quadrotor.pdf) the controller takes flat outputs (position and yaw) and outputs a dictionary containing different control abstractions (angle, rate, motor speeds). The `Multirotor` vehicle will use the commanded motor speeds in the dynamics. 
+The simulator is packaged with a geometric tracking controller for a quadrotor, found in `quadrotor_control.py`. Based on [this paper](https://mathweb.ucsd.edu/~mleok/pdf/LeLeMc2010_quadrotor.pdf) the controller takes flat outputs (position and yaw) and outputs a dictionary containing different control abstractions (e.g., angle, rate, motor speeds).
 
-Other controllers can be developed but must complement the vehicle and the trajectory it is trying to stabilize to. 
+Currently, the `Multirotor` object accepts the following controller inputs (abstractions): 
+- `cmd_motor_speeds`: the lowest control abstraction. The controller directly commands individual motor speeds.
+- `cmd_motor_thrusts`: one step up, the controller commands individual thrusts for each motor.
+- `cmd_ctbr`: the controller commands a collective thrust (ct) and body rates (br) on each axis. 
+- `cmd_ctbm`: the controller commands a collective thrust (ct) and body moments (bm) on each axis.
+- `cmd_ctatt`: the controller commands a collective thrust (ct) and attitude (as a quaternion). 
+- `cmd_vel`: the controller commands a velocity vector in the world frame. Assumes `yaw` is 0.
+
+For higher control abstractions, e.g. `cmd_vel` or `cmd_ctatt`, the lower level controllers are hidden in `Multirotor`. The gains for these controllers were hand-tuned for the Crazyflie parameters, so they may need tuning if a different vehicle is being used. 
+
+Other controllers can be developed but must complement the vehicle and the trajectory they are trying to stabilize to. 

rotorpy/controllers/controller_template.py

@@ -4,18 +4,23 @@ Imports
 import numpy as np
 from scipy.spatial.transform import Rotation  # This is a useful library for working with attitude.
 
-class ControlTemplate(object):
+class MultirotorControlTemplate(object):
     """
     The controller is implemented as a class with two required methods: __init__() and update(). 
     The __init__() is used to instantiate the controller, and this is where any model parameters or 
     controller gains should be set. 
     In update(), the current time, state, and desired flat outputs are passed into the controller at 
-    each simulation step. The output of the controller should be the commanded motor speeds, 
-    commanded thrust, commanded moment, and commanded attitude (in quaternion [x,y,z,w] format). 
+    each simulation step. The output of the controller depends on the control abstraction for Multirotor...
+        if cmd_motor_speeds: the output dict should contain the key 'cmd_motor_speeds'
+        if cmd_motor_thrusts: the output dict should contain the key 'cmd_rotor_thrusts'
+        if cmd_vel: the output dict should contain the key 'cmd_v'
+        if cmd_ctatt: the output dict should contain the keys 'cmd_thrust' and 'cmd_q'
+        if cmd_ctbr: the output dict should contain the keys 'cmd_thrust' and 'cmd_w'
+        if cmd_ctbm: the output dict should contain the keys 'cmd_thrust' and 'cmd_moment'
     """
     def __init__(self, vehicle_params):
         """
-
+        Use this constructor to save vehicle parameters, set controller gains, etc. 
         Parameters:
             vehicle_params, dict with keys specified in a python file under /rotorpy/vehicles/
 
@@ -44,18 +49,30 @@ class ControlTemplate(object):
 
         Outputs:
             control_input, a dict describing the present computed control inputs with keys
-                cmd_motor_speeds, rad/s
-                cmd_thrust, N (for debugging and laboratory; not used by simulator)
-                cmd_moment, N*m (for debugging; not used by simulator)
-                cmd_q, quaternion [i,j,k,w] (for laboratory; not used by simulator)
+
+                key, description, unit, (applicable control abstraction)                                                        
+                cmd_motor_speeds, the commanded speed for each motor, rad/s, (cmd_motor_speeds)
+                cmd_thrust, the collective thrust of all rotors, N, (cmd_ctatt, cmd_ctbr, cmd_ctbm)
+                cmd_moment, the control moments on each boxy axis, N*m, (cmd_ctbm)
+                cmd_q, desired attitude as a quaternion [i,j,k,w], , (cmd_ctatt)
+                cmd_w, desired angular rates in body frame, rad/s, (cmd_ctbr)
+                cmd_v, desired velocity vector in world frame, m/s (cmd_vel)
         """
+
+        # Only some of these are necessary depending on your desired control abstraction. 
         cmd_motor_speeds = np.zeros((4,))
+        cmd_motor_thrusts = np.zeros((4,))
         cmd_thrust = 0
         cmd_moment = np.zeros((3,))
         cmd_q = np.array([0,0,0,1])
+        cmd_w = np.zeros((3,))
+        cmd_v = np.zeros((3,))
 
         control_input = {'cmd_motor_speeds':cmd_motor_speeds,
+                         'cmd_motor_thrusts':cmd_motor_thrusts,
                          'cmd_thrust':cmd_thrust,
                          'cmd_moment':cmd_moment,
-                         'cmd_q':cmd_q}
+                         'cmd_q':cmd_q,
+                         'cmd_w':cmd_w,
+                         'cmd_v':cmd_v}
         return control_input