From 8a9bd0df6e04e20bedda8d363fd973f110ff2325 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mario=20H=C3=BCttel?= <mario.huettel@gmx.net>
Date: Thu, 15 Jul 2021 00:20:03 +0200
Subject: [PATCH] Add documentation for reflow controller

---
 .../reflow-controller/pid-controller.h        | 115 ++++++++++++++++++
 stm-firmware/pid-controller.c                 |   6 +
 2 files changed, 121 insertions(+)

diff --git a/stm-firmware/include/reflow-controller/pid-controller.h b/stm-firmware/include/reflow-controller/pid-controller.h
index d02cc86..16a383e 100644
--- a/stm-firmware/include/reflow-controller/pid-controller.h
+++ b/stm-firmware/include/reflow-controller/pid-controller.h
@@ -18,35 +18,150 @@
 * If not, see <http://www.gnu.org/licenses/>.
 */
 
+/** @addtogroup pid-controller
+ *  @{
+ */
+
 #ifndef __PID_CONTROLLER_H__
 #define __PID_CONTROLLER_H__
 
+/**
+ * @brief Representation of a PID controller
+ */
 struct pid_controller {
+	/**
+	 * @brief Derivate term @f$k_d@f$
+	 */
 	float k_deriv;
+
+	/**
+	 * @brief Integral term @f$k_i@f$
+	 */
 	float k_int;
+
+	/**
+	 * @brief Proportional term @f$k_p@f$
+	 */
 	float k_p;
+
+	/**
+	 * @brief Internally precalculated auxiliary value. @f$k_{i_t} = \frac{1}{2}k_{i} \cdot T_s@f$
+	 *
+	 * This value is caluclated during the @ref pid_init function to reduce calculations during the continous
+	 * PID sampling.
+	 */
 	float k_int_t;
+
+	/**
+	 * @brief Internally precalculated auxiliary value. @f$k_{d_t} = 2\frac{k_{d}}{T_s + 2 k_{d\tau}}@f$
+	 *
+	 * This value is caluclated during the @ref pid_init function to reduce calculations during the continous
+	 * PID sampling.
+	 */
 	float k_deriv_t;
+
+	/**
+	 * @brief Internally precalculated auxiliary value. @f$\overline{k_{d_t}} = \frac{2 k_{d\tau} - T_s}{ 2k_{d\tau} + T_s}@f$
+	 *
+	 * This value is caluclated during the @ref pid_init function to reduce calculations during the continous
+	 * PID sampling.
+	 */
 	float k_inv_deriv_t;
+
+	/**
+	 * @brief Saturation of output value
+	 * @note This value is set to 100 (corresponding to 100%) for the temperature controller
+	 */
 	float output_sat_max;
+
+	/**
+	 * @brief Minumum saturation of PID output value.
+	 * @note This value is set to 0 for the temperature controller as the oven driver is not able to cool
+	 */
 	float output_sat_min;
+
+	/**
+	 * @brief Maximum value @f$i_{max}@f$ the inegrator in the PID controller can reach.
+	 *
+	 * The output of the integral term of the PID controller is limited to @f$\pm i_{max}@f$
+	 *
+	 */
 	float integral_max;
+
+	/**
+	 * @brief Sampling period @f$T_s@f$ of the PID controller in seconds
+	 */
 	float sample_period;
+
+	/**
+	 * @brief Output value of the PID controller
+	 */
 	volatile float control_output;
+
+	/**
+	 * @brief Internal state variable holding the last input value.
+	 */
 	volatile float last_in;
+
+	/**
+	 * @brief integral term's value
+	 */
 	volatile float integral;
+
+	/**
+	 * @brief derivate term's value
+	 */
 	volatile float derivate;
 };
 
+/**
+ * @brief Initialize a @ref pid_controller struct
+ * @param pid Struct to initilaize
+ * @param k_deriv Derivate term
+ * @param k_int integral term
+ * @param k_p Proportional term
+ * @param output_sat_min Minimum output saturation
+ * @param output_sat_max Maximum output saturation
+ * @param integral_max Maximum integral term
+ * @param kd_tau Time constant of derivate term low pass filter
+ * @param sample_period Sample time in seconds
+ */
 void pid_init(struct pid_controller *pid, float k_deriv, float k_int, float k_p,
 	      float output_sat_min, float output_sat_max, float integral_max, float kd_tau, float sample_period);
 
+/**
+ * @brief Reset a PID controller.
+ *
+ * This sets all internal states to 0.
+ *
+ * @param pid Controller
+ */
 void pid_zero(struct pid_controller *pid);
 
+/**
+ * @brief Execute a tiome step of the PID controller. This function must be periodically called in an pid_controller::sample_period interval
+ * @note This function does not check its calling interval. It must be ensured by the caller.
+ * @param pid Pid controller to execute
+ * @param deviation Input deviation
+ * @return Current controller output after the calculated time step
+ */
 float pid_sample(struct pid_controller *pid, float deviation);
 
+/**
+ * @brief Retrieve the controller's current output
+ * @param pid Pid controller
+ * @return Output
+ */
 float pid_get_control_output(const struct pid_controller *pid);
 
+/**
+ * @brief Duplicate a PID controller
+ * @param dest destination controller
+ * @param src Source controller
+ * @return 0 if successful
+ */
 int pid_copy(struct pid_controller *dest, const struct pid_controller *src);
 
 #endif /* __PID_CONTROLLER_H__ */
+
+/** @} */
diff --git a/stm-firmware/pid-controller.c b/stm-firmware/pid-controller.c
index dbae742..20658e4 100644
--- a/stm-firmware/pid-controller.c
+++ b/stm-firmware/pid-controller.c
@@ -18,6 +18,10 @@
  * If not, see <http://www.gnu.org/licenses/>.
  */
 
+/** @addtogroup pid-controller
+ *  @{
+ */
+
 #include <reflow-controller/pid-controller.h>
 #include <string.h>
 
@@ -109,3 +113,5 @@ float pid_get_control_output(const struct pid_controller *pid)
 
 	return pid->control_output;
 }
+
+/** @} */