add docs on ziegler-nicols tuning

docs/ziegler_tuning.md

@@ -0,0 +1,83 @@
+# PID Tuning Using Ziegler-Nicols
+
+This uses the Ziegler Nicols method to estimate values for the Kp/Ki/Kd PID control values.
+
+The method implemented here is taken from ["Ziegler–Nichols Tuning Method"](https://www.ias.ac.in/article/fulltext/reso/025/10/1385-1397) by Vishakha Vijay Patel
+
+One issue with Ziegler Nicols is that is a **heuristic**: it generally works quite well, but it might not be the optimal values. Further fiddling may be necessary.
+
+## Process Overview
+
+1. First of all, you will record a temperature profile for your kiln.
+2. Next, we use those figures to estimate the parameters.
+
+## Step 1: Record Temperature Profie
+
+This must be done without any interference from the real PID control loop. To do so, run:
+
+```
+python kiln-tuner.py ziegler.csv
+```
+
+The above will drive your kiln to 400 and record the temperature profile to the file `zn.csv`. The file will look something like this:
+
+```
+time,temperature
+4.025461912,45.5407078
+6.035358906,45.5407078
+8.045399904,45.5407078
+10.05544925,45.59087846
+...
+```
+
+## Step 2: Compute the PID parameters
+
+Once you have your zn.csv profile, run the following:
+
+```
+python zieglernicols.py zn.csv
+```
+
+The values will be output to stdout, for example:
+```
+Kp: 3.853985144980333 1/Ki: 87.78173053095107 Kd: 325.9599328488931
+```
+(Note that the Ki value is already inverted ready for use in config.py)
+
+------
+
+## Sanity checking the results
+
+If you run
+```
+python zieglernicols.py zn.csv --showplot
+```
+
+It will display a plot of the parameters. It should look simular to this ![kiln-tuner-example.png](kiln-tuner-example.png)
+(Note: you will need python's `pyplot` installed for this to work.)
+
+The smooth linear part of the chart is very important. If it is too short, try increasing the target temperature (see later).
+
+Note the red diagonal line: this **must** follow the smooth part of your chart closely.
+
+## My diagonal line isn't right
+
+You might need to adjust the line parameters to make it fit your data properly. You can do this as follows:
+
+```
+python zieglernicols.py zn.csv --tangentdivisor 8
+```
+
+`tangentdivisor` modifies which parts of the profile is used to calculate the line.
+
+It is a floating point number >= 2; If necessary, try varying it till you get a better fit.
+
+## Changing the target temperature
+
+By default it is 400. You can change this as follows:
+
+```
+python kiln-tuner.py zn.csv --targettemp 500
+```
+
+(where the target temperature has been changed to 500)

zieglernicols.py

@@ -90,7 +90,7 @@ def calculate(filename, tangentdivisor, showplot):
     Kd = Kp * Td
 
     # outut to the user
-    print(Kp, 1 / Ki, Kd)
+    print(f"Kp: {Kp} 1/Ki: {1/ Ki}, Kd: {Kd}")
 
     if showplot:
         plot(xdata, ydata,