From 324e6d506dd5aca278fd90f49ce7e6cc095d3790 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mario=20H=C3=BCttel?= <mario.huettel@gmx.net>
Date: Sat, 22 Aug 2020 23:57:04 +0200
Subject: [PATCH] Issue #5: Write documentation for error flags and their
 handling

---
 doc/source/firmware/error-handling.rst    |  9 +++++
 doc/source/firmware/flags.rst             | 40 +++++++++++++++++++++++
 doc/source/firmware/pt1000-processing.rst |  4 ++-
 doc/source/firmware/safety.rst            |  7 ++++
 4 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 doc/source/firmware/error-handling.rst

diff --git a/doc/source/firmware/error-handling.rst b/doc/source/firmware/error-handling.rst
new file mode 100644
index 0000000..16871ae
--- /dev/null
+++ b/doc/source/firmware/error-handling.rst
@@ -0,0 +1,9 @@
+.. _safety_handling:
+
+Error Handling
+==============
+
+.. _safety_panic:
+
+Panic Mode
+----------
\ No newline at end of file
diff --git a/doc/source/firmware/flags.rst b/doc/source/firmware/flags.rst
index bd7eeba..808ef87 100644
--- a/doc/source/firmware/flags.rst
+++ b/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
+========== ============= ============= ===========
\ No newline at end of file
diff --git a/doc/source/firmware/pt1000-processing.rst b/doc/source/firmware/pt1000-processing.rst
index deacf45..492d232 100644
--- a/doc/source/firmware/pt1000-processing.rst
+++ b/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
diff --git a/doc/source/firmware/safety.rst b/doc/source/firmware/safety.rst
index 7544bbe..2c8aac9 100644
--- a/doc/source/firmware/safety.rst
+++ b/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