Merge pull request #123 from Open-STEM/proportional-control

Intro to Proportional control

Author: AnselChang

course/robot_control/intro_to_prop_control.rst

@@ -1,47 +1,85 @@
 Introduction to Proportional Control
 ====================================
 
-Introduction:
--------------
+What is Proportional Control?
+-----------------------------
 
-While the on-off controller works, there are issues that can be solved using another type of controller.
+Imagine you're driving a car and you want to keep at a steady speed. If you're going too slow,
+you press the accelerator a bit, and if you're going too fast, you ease off. But instead of
+just fully pressing or fully releasing the accelerator (like an on-off switch), you adjust
+how hard you press based on how far off you are from your desired speed. That's the basic idea
+behind proportional control. The further you are from your target, the harder you try to correct it.
+If you're a little off, you make a small adjustment. If you're way off, you make a big one.
 
-The on-off controller is a **discrete** controller. This means that the controller has discrete states. It can be "on" or "off". It cannot be "half on" or "half off".
+Let's take this analogy further - you decide that the perfect cruising speed for your car ride is 70 mph.
+This speed represents your desired value or where you ideally want to be. In control theory, this is 
+called the **setpoint**.
 
-A **continuous** controller is one that can have any value. For example, the speed of a car is a continuous controller. It is not limited to "on" or "off".
+You get on the highway, and as you settle into your drive, you glance at your speedometer. It reads 65 mph,
+which is your current value. In control theory, this is called the **process variable**.
 
-Continuous controllers are more effective and offer the user more control over their system, but are also easier to implement. 
+Naturally, you recognize there's a difference between where you want to be (70 mph) and where you currently are
+(65 mph). This difference is the called the **error**, and in this case, it's 5 mph. It's easily calculated by
+the formula:
 
-Basic Definitions + Steps of a Proportional Controller
-------------------------------------------------------
+.. code-block:: python
 
-A proportional controller is the simplest type of continuous controller. It is also known as a P controller. 
+    error = setpoint - process_variable
 
-Before implementing one, we need to define some terms and steps. 
+Knowing the error isn't enough. How should you, the driver, react to it? This is where the concept of Proportional
+control comes into play.
 
-**Target Value** - The value that you want to go to. In this example, let's set our target value to 5 cm
+Think of P control as your driving instinct. Instead of abruptly flooring the accelerator or immediately slamming the
+brakes, you adjust your speed based on your error: how far you are from your desired speed.
 
-**Error** - The difference between the target value and the actual value. For example, if you want to go to 5 cm but you are currently at 3 cm, then the error is 2 cm.
+A measure called **control output** tells you much to adjust. It's calculated as:
 
-**Control Effort** - The value that the controller outputs.
+.. code-block:: python
 
-**kp** - The constant that you scale the error by to get the control effort. For example, if you want to go to 5 cm but you are currently at 3 cm, then the error is 2 cm. If **kp** is 0.5, then the control effort is 1 (0.5 * 2 cm).
+    control_output = Kp * error
 
-Now that we have defined some terms, let's go over the steps to implement a continuous controller.
+where Kp is a constant called the **proportional gain** and acts as a scaling factor for the error.
 
-1.  Define your target value 
-2.  Find the error 
-3.  Multiply the error by a constant **kp** to get the control effort 
-4.  Feed the control effort into your system
+If Kp is high, it's like you have a heavy foot and you'll accelerate hard even for a small error. You'll get there faster, but
+less precisely and you're more likely to overshoot.
+
+On the other hand, if Kp is low, you're more of a cautious driver, gently pressing the accelerator for the same error. You'll
+get there more slowly, but at a much smoother pace.
+
+Having the constant Kp allows you to tune your control system to your liking.
+
+Note that this analogy breaks down somewhat. Imagine your current speed is *greater* than your desired speed. In this case,
+the error is negative. If you plug this into the control output formula, you'll get a negative control output. This means that
+a proportional controller will actually slow you down if you're going too fast, proportional to how far you are from your desired
+speed. So, you can imagine that a proportional controller is like a driver who's always trying to get to the speed limit, utilizing
+both the accelerator and the brakes.
+
+Tuning Kp
+---------
+
+The following graph shows proportional control in action.
+
+.. image:: media/proportional.jpeg
+    :width: 400
+
+The blue line is the reference, and indicates the desired value. Red, green, and purple lines represent the current value over time
+when controlled by a proportional controller with different values of Kp.
+
+With a low Kp, the red line is slow to react to the error, and the controller is sluggish. It takes a long time to reach the desired
+value, and it never quite gets there. This is called **underdamped** behavior.
+
+With a high Kp, the purple line is quick to react to the error, and the controller is aggressive. It reaches the desired value quickly,
+but overshoots, causing the error to become negative. It then corrects itself, but overshoots again, and so on. This is called **overdamped**
+behavior, and results in oscillations around the desired value.
+
+The green line is just right. It reaches the desired value quickly, and doesn't overshoot much. It's an important task to tune Kp so that
+the controller approaches the desired value as quickly and smoothly as possible.
+
+Note: You'll find that, even with excellent tuning, a proportional controller often will either oscillate a little bit, or never quite reach
+the desired value. More advanced control systems like PID aim to minimize these issues, but they are out of the scope of this course.
 
-Tips on finding "kp"
---------------------
 
-Finding the right value for **kp** is a bit tricky. If **kp** is too small, then the system will not respond fast enough. If **kp** is too large, then the system will overshoot the target value and oscillate around it.
 
-When first finding a **kp** value, you want to "scale" an expected range of errors into an acceptable control signal. 
 
-For example, if your expected error ranges from 0-40 but your control signal ranges from 0-1, a "good" starting kp value would be 0.025 (1/40).\
 
-From there, you can adjust the kp value to get the desired response after testing. 
 

course/robot_control/media/gyroturn-blockly.png

@@ -1,45 +1,87 @@
 Implementing a Proportional Controller
 ======================================
 
-Now that you've learned about proportional controllers, let's implement one on the distance tracking activity
+Now that you've learned about how proportional controllers, let's implement one for our distance tracking activity,
+where we want to keep the robot some distance from the object in front of it using the rangefinder!
 
-Steps
------
+Defining Terminology
+--------------------
 
-The first step when creating a proportional controller is to define your target and error terms. 
+Let's identify the terms we'll need to use in our code:
 
-For our target, let's set it to 20 cm. 
+**Set Point** or desired value: In this example, this is some set distance from the rangefinder we want the robot to be at. 
+For this example, let's say 20cm.
 
-In this case, the error is the difference between the target and the current distance from the object in front of the XRP. 
+**Process Variable** or current value: We obtain our measured value from reading the rangerfinder value. This is
+:code:`rangefinder.distance()`.
 
-Now, we need to define our proportional gain. 
+Our goal is for our process variable (the rangefinder distance) to approach the set point (20 cm).
 
-    The first step of this is understanding the range of values that the error can take.
+Thus, our **error** is calculated as :code:`error = rangefinder.distance() - 20`. Note that :code:`error = 20 - rangefinder.distance()`
+is also "correct". The distinction in sign is simply whichever makes more sense for your application. Here, if we had an error of 30cm,
+we would want to drive forward 10cm, so we would want a positive error to make our motors spin forward.
 
-    The error can be any value between -20 and 20, meaning we're really close or really far. 
+**Control Output**: In this case, this is our motor effort. This is because we want to drive with a speed proportional
+to the distance error. As a reminder for P control, this will be calculated as :code:`motor_effort = Kp * error`.
 
-    Then, the error would need to be scaled for an appropriate control signal (something from -1 to 1)
+**Kp**: This is our proportional gain. Though we will need to tune this value, we can guess a somewhat reasonable value
+by considering the range of values our error can take, and the domain of our control output. In this case, if we're 30cm away
+from the object, our error will be 10. We can guess that at this sufficient distance we will want to drive forward at a maximum
+effort of 1, as effort is restricted to the domain :math:`[-1, 1]`. Thus, we can guess that :code:`Kp = 1/10 = 0.1`. Of course,
+this isn't likely the final value that works best for your robot, but it's a good starting point.
 
-    Therefore, a good starting kp value would be 0.05. 
+Implementing the Controller
+---------------------------
 
+Now that we've defined our terms, let's write the code!
 
-Finally, we need to set the speed of the XRP to our error times kp.
+Let's start by defining our proportional gain and our set point:
 
-This is an example program that implements a proportional controller. 
+.. tab-set::
 
-.. error:: 
+    .. tab-item:: Python
 
-    TODO add code to complete this
-    
-.. admonition:: Try it out
-    
-    Now that you've designed a successful proportional controller, let's try some other values for kp.
+        .. code-block:: python
+
+            Kp = 0.1
+            desired_distance = 20
+
+    .. tab-item:: Blockly
+
+        .. image:: media/variables.png
+            :width: 300
+
+Next, we want to enter some sort of loop to continuously read our rangefinder value and update our motor effort from our controller output.
+
+.. tab-set::
 
-    First, let's try making kp too small (0.01). What happens?
+    .. tab-item:: Python
 
-    When kp is too small, the XRP doesn't react fast enough to the error, and it takes a long time to get to the target. 
+        .. code-block:: python
 
-    Next, let's try making kp too big (1). What happens?
+            Kp = 0.1
+            desired_distance = 20
+            while True:
+                error = rangefinder.distance() - desired_distance
+                motor_effort = Kp * error
+                drivetrain.set_effort(motor_effort, motor_effort)
+                time.sleep(0.05)
 
-    The behavior you're seeing is called oscillation and happens when kp is too high. 
+    .. tab-item:: Blockly
+
+        .. image:: media/pcode.png
+            :width: 500
+
+Each iteration of the loop consists of the following steps:
+    #. Read the rangefinder value to get the current distance
+    #. Calculate the error
+    #. Calculate the control output through Kp * error
+    #. Set the drivetrain motor efforts to the control output
+    #. Wait for a short period of time
+
+This code should give us a working solution to maintain a set distance from the object in front of the robot!
+
+.. admonition:: Try it out
 
+    Try moving the object in front of the robot and watch the robot attempt to maintain the set distance! What
+    happens when you increase Kp? Decrease it? What value of Kp works best for your robot?