Issue #5: Write documentation for error flags and their handling

doc/source/firmware/error-handling.rst

@@ -0,0 +1,9 @@
+.. _safety_handling:
+
+Error Handling
+==============
+
+.. _safety_panic:
+
+Panic Mode
+----------

doc/source/firmware/flags.rst

@@ -7,23 +7,63 @@ The safety flags are represented in software by the following enums
 
 .. doxygenenum:: safety_flag
 
+The safety flags can be temporarily or permanent. Some temporary flags are reset automatically, once the error condition disappears. Others have to be explicitly cleared. 
 
 .. _safety_flags_adc_overflow:
 
 ERR_FLAG_MEAS_ADC_OVERFLOW
 --------------------------
 
+``ERR_FLAG_MEAS_ADC_OVERFLOW`` is triggered in case of an overflow in the signal path of the measurement ADC. This should never happen unless there is a bug in the software.
+
+========== ============= ============= ===========
+persistent self-clearing Stops PID     Panic Mode
+========== ============= ============= ===========
+yes        no            yes           no
+========== ============= ============= ===========
+
 .. _safety_flags_adc_off:
 
 ERR_FLAG_MEAS_ADC_OFF
 ---------------------
 
+``ERR_FLAG_MEAS_ADC_OFF`` signals that the measurment ADC for the PT1000 sensor is deactivated. This flag is automatically cleared by the firmware
+once the ADC is started.
+
+========== ============= ============= ===========
+persistent self-clearing Stops PID     Panic Mode
+========== ============= ============= ===========
+no         yes           yes           no
+========== ============= ============= ===========
+
+
 .. _safety_flags_adc_watchdog:
 
 ERR_FLAG_MEAS_ADC_WATCHDOG
 --------------------------
 
+``ERR_FLAG_MEAS_ADC_WATCHDOG`` is used as a wire break detection mechanism. This flag is set when the PT1000 measurement ADC detects an invalid resistance measurement.
+
+.. seealso:: :ref:`ADC Watchdog<firmware_meas_adc_watchdog>`
+
+========== ============= ============= ===========
+persistent self-clearing Stops PID     Panic Mode
+========== ============= ============= ===========
+no         no            yes           no
+========== ============= ============= ===========
+
+
 .. _safety_flags_adc_unstable:
 
 ERR_FLAG_MEAS_ADC_UNSTABLE
 --------------------------
+
+``ERR_FLAG_MEAS_ADC_UNSTABLE`` is set after startup of the PT1000 measuremnt or after reconfiguring the filter settings.
+
+.. seealso:: :ref:`firmware_meas_adc_filter`
+
+========== ============= ============= ===========
+persistent self-clearing Stops PID     Panic Mode
+========== ============= ============= ===========
+no         yes           no            no
+========== ============= ============= ===========

doc/source/firmware/pt1000-processing.rst

@@ -92,6 +92,8 @@ The equation is implemented in
 
 and applied during the `Exponential Moving Average Filter`_.
 
+.. _firmware_meas_adc_filter:
+
 Exponential Moving Average Filter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -158,7 +160,7 @@ The default values, if no calibration is loaded / executed, are:
 ============== =========
 :math:`\sigma` :math:`O`
 ============== =========
-0              1
+      0            0
 ============== =========
 
 Get Calibration Corrected Value

doc/source/firmware/safety.rst

@@ -6,7 +6,14 @@ Safety Controller
 The safety controller is the software component that monitors the overall condition of the reflow controller,
 and stops the output driver in case of an error.
 
+Severe error flags, like a drifting reference voltage, stop the PID controller and force the output to zero.
+The controller stays in a usable state. After the errors have been cleared, normal operation may continue.
+
+On the other hand, fatal errors like an over-temperature error, or memory problem, lead to the activation of the :ref:`safety_panic`,
+which forces the output zero, but does not allow any more interaction.
+
 .. toctree::
 	:maxdepth: 2
 	
 	flags
+	error-handling