- changed the pid tuning page to a manual, pracitical approach

docs/pid_tuning.md

@@ -10,45 +10,41 @@ A controller with properly tuned PID values reacts quickly to changes in the set
 
 ## Try the Existing Values
 
-My kiln is Skutt KS-1018 with a kiln vent.  Try the current settings for pid_kp, pid_ki, and pid_kd and if they work for you, you're done.  Otherwise, you have some experimentation ahead of you.  The following exercise took me about 2 hours of testing. 
+My kiln is Skutt KS-1018 with a kiln vent.  Try the current settings for pid_kp, pid_ki, and pid_kd and if they work for you, you're done.  Otherwise, you have some experimentation ahead of you.  The following exercise took me about an hour of testing. 
 
 ## The Tuning Process
 
-in config.py set the PID values like so...
+I'm a big fan of manual tuning. Let's start with some reasonable values for PID settings in config.py...
 
-    pid_kp = 1.0
-    pid_ki = 0.0
-    pid_kd = 0.0
+    pid_kp = 20
+    pid_ki = 50
+    pid_kd = 100
 
-run a test schedule. I used a schedule that switches between 200 and 250 F every 30 minutes.
+When you change values, change only one at a time and watch the impact. Change values by either doubling or halving.
 
-What you are looking for is overshoot (in my case 25F) past 200F to 225F. The next thing the controller should do is undershoot by just a little below the set point of 200F. If these two things happen, great.  If not, you will need to change pid_kp to a higher or lower value.
+Run a test schedule. I used a schedule that switches between 200 and 250 F every 30 minutes. The kiln will likely shoot past 200. This is normal. We'll eventually get rid of most of the overshoot, but probably not all.
 
-Once you get the overshoot and minimal undershoot, you need to record some values.  First grab the overshoot... in my case 25F.
+Let's balance pid_ki first (the integral). The lower the pid_ki, the greater the impact it will have on the system. If a system is consistently low or high, the integral is used to help bring the system closer to the set point. The integral accumulates over time and has [potentially] a bigger and bigger impact.
 
-    pid_kp = 25
+* If you have a steady state (no oscillations), but the temperature is always above the set point, increase pid_ki.
+* If you have a steady state (no oscillations), but the temperature is always above the set point, decrease pid_ki.
+* If you have an oscillation but the temperature is mostly above the setpoint, increase pid_ki.
+* If you have an oscillation but the temperature is mostly below the setpoint, decrease pid_ki.
 
-Measure the time in seconds from high peak to low peak. In my case this was 725 seconds.  Multiply that number by 1.5 to get the Integral. So 725 * 1.5 = 1088.
+Let's set pid_kp next (proportional). Think of pid_kp as a dimmable light switch that turns on the heat when below the set point and turns it off when above. The brightness of the dimmable light is defined by pid_kp. Be careful reducing pid_kp too much. It can result in strange behavior.
 
-    pid_ki = 1088
+* If you have oscillations that don't stop or increase in size, reduce pid_kp
+* If you have too much overshoot (after adjusting pid_kd), reduce pid_kp
+* If you approach the set point wayyy tooo sloooowly, increase pid_kp
+ 
+Now set pid_kd (derivative). pid_kd makes an impact when there is a change in temperature. It's used to reduce oscillations.
 
-Now set the derivative at 1/5 of the Integral. So 1088/5 = 217
+* If you have oscillations that take too long to settle, increase pid_kp
+* If you have crazy, unpredictable changes in temperature, reduce pid_kp
 
-    pid_kd = 217
-
-in essence these values mean...
-
-| setting | Value | Action |
-| ------- | ----- | ------ |
-| pid_kp | 25 | react pretty slowly |
-| pid_ki | 1088 | predict really far forward in time and make changes early |
-| pid_kd | 217 | heavily dampen oscillations |
-
-Now, run the test schedule again and see how well it works.  Expect some overshoot as the kiln reaches the set temperature the first time, but no oscillation.  Any holds or ramps after that should have a smooth transition and should remain really close to the set point [1 or 2 degrees F].
+Expect some overshoot as the kiln reaches the set temperature the first time, but no oscillation.  Any holds or ramps after that should have a smooth transition and should remain really close to the set point [1 or 2 degrees F].
 
 ## Troubleshooting
 
 * only change one value at a time, then test it.
-* If there is too much overshoot, decrease pid_kp.
-* If the temp is always below the set point, decrease pid_ki (which increases the integral action).
 * if the above does not work, try the Ziegler / Nichols method https://blog.opticontrols.com/archives/477