Start documentation of PID controller

doc/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "restructuredtext.confPath": "${workspaceFolder}/source"
+}

doc/source/firmware/index.rst

@@ -11,6 +11,7 @@ mechanisms and the behavior. For a detailed code documentation see the doxygen o
 	:maxdepth: 2
 	
 	pt1000-processing
+	pid-controller
 	safety/index
 	code/index
 

doc/source/firmware/pid-controller.rst

@@ -0,0 +1,36 @@
+.. _pid_controller:
+
+PID Controller
+==============
+
+The PID controller is the main element of the oven. It controls the output of the solid state relais in order to achieve the desired temperature.
+
+The PID controller is implemented in the ``pid-controller.c`` file. See the :ref:`pid_code_api` for details.
+
+Functional Description
+----------------------
+
+The following figure shows the PID controller's structure.
+
+.. drawio-image:: pid.drawio
+
+The controller is composed of 3 paths. The proportional, the derivate, and the integrator path.
+Compared to a textbook PID controller, this version contains a few additional features.
+
+The integrator has a configurable maximum limit of :c:var:`pid_controller.integral_max`. Once this value is reached (plus or minus), the integrator freezes.
+The integrator is also frozen in case the output value is in saturation. This serves as an anti-windup protection.
+
+The output value saturates at configurable high and low limits (:c:var:`pid_controller.output_sat_max` and :c:var:`pid_controller.output_sat_min`). The controller instance used for the
+reflow oven's solid state relais output is saturated by software to a limit of 0 to 100.
+
+In addition to the above features, the derivate term contains an additional first order low pass filter in order to prevent coupling of high frequency noise amplified by the derivate term.
+The low pass filter is charcterized by its time constant :math:`k_{d\tau}`.
+
+
+.. _pid_code_api:
+
+PID Controller Code API
+-----------------------
+
+.. doxygengroup:: pid-controller
+   :project: Reflow Controller Firmware

doc/source/firmware/pid.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2021-06-14T21:01:35.428Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/14.1.8 Chrome/87.0.4280.88 Electron/11.1.1 Safari/537.36" etag="ORruDkFRflEPSgIrI-Cx" version="14.1.8" type="device"><diagram name="Page-1" id="b520641d-4fe3-3701-9064-5fc419738815">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</diagram></mxfile>