Improve sphinx

doc/source/Doxyfile.in

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Reflow Oven Controller"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = $(PROJECT_VERSION)
+PROJECT_NUMBER         =
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -461,7 +461,7 @@ LOOKUP_CACHE_SIZE      = 0
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.
@@ -485,7 +485,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO,

doc/source/conf.py

@@ -38,6 +38,7 @@ subprocess.call('doxygen Doxyfile.in', shell=True)
 extensions = [
 	'sphinx_rtd_theme',
 	'sphinx.ext.autodoc',
+	'sphinxcontrib.blockdiag',
 	'breathe'
 ]
 
@@ -71,3 +72,5 @@ breathe_domain_by_extension = { "h" : "c",
 breathe_default_project = "Reflow Controller Firmware"
 breathe_default_members = ('members', 'undoc-members')
 
+blockdiag_html_image_format = 'SVG'
+blockdiag_latex_image_format = 'PDF'

doc/source/firmware/flags.rst

@@ -0,0 +1,14 @@
+.. _safety_flags:
+
+Safety Flags
+============
+
+.. _safety_flags_adc_watchdog:
+
+ERR_FLAG_MEAS_ADC_WATCHDOG
+--------------------------
+
+.. _safety_flags_adc_unstable:
+
+ERR_FLAG_MEAS_ADC_UNSTABLE
+--------------------------

doc/source/firmware/index.rst

@@ -0,0 +1,16 @@
+.. _firmware:
+
+Reflow Controller Firmware Internals
+====================================
+
+This chapter describes the internals of the reflow controller's firmware.
+This is in most cases not intended to be a code documentation but an overview over the functional
+mechanisms and  the behavior.
+
+.. toctree::
+	:maxdepth: 2
+	
+	pt1000-processing
+	safety
+	code/index
+

doc/source/firmware/pt1000-processing.rst

@@ -0,0 +1,108 @@
+.. _pt1000_processing:
+
+PT1000 Temperature Value Processing
+===================================
+
+The PT1000 temperature sensor is the sensing element used for determining the Reflow Oven Temperature.
+
+The PT1000 value processing is enabled by default and not intended to be turned off.
+
+PT1000 Value Sampling
+---------------------
+
+The following block diagram shows the processing chain of the temperature signal.
+
+.. blockdiag::
+	:desctable:
+	
+	blockdiag {
+		orientation = portrait;
+		
+		ADC[description="`Analog to Digital Converter <ADC_>`_"];
+		WATCHDOG [label = "WDT", shape=endpoint, description="`Hardware Value Watchdog <Watchdog_>`_"];
+		PREFILTER [label=Prefilter, description="`Prefiltering and Downsampling <Prefilter_>`_"];
+		ADC2RES [label= "Val -> Ohm", description="`Conversion from ADC value to resistance in Ohms <ADC Value to Ohm_>`_"]		
+		MAVG [label="MAVG Filter", description="`Exponential Moving Average Filter`_"];
+		RAW_HF [label="HF", shape = endpoint, description="High Frequency raw value reading"];
+		PT1000 [label = "LF", shape = endpoint, description="Low Frequency PT1000 resistance value"]
+		RAW_STREAM [label = "Stream", shape = endpoint, description="Raw value streaming"];
+
+		ADC -> WATCHDOG;
+		ADC -> PREFILTER [label="1 kHz"];
+		PREFILTER -> ADC2RES [label="1/6 kHz"];
+		ADC2RES -> MAVG;
+		MAVG -> PT1000 [label="1/6 kHz"];
+		PREFILTER -> RAW_HF [label="1/6 kHz"];
+		PREFILTER -> RAW_STREAM [label="1/6 kHz"];		
+	}
+
+ADC
+~~~
+
+The internal ADC of the STM32F407 controller is used to sample the analog signal from the :ref:`hw_analog_fe`. The ADC is triggered by the hardware Timer *TIM2* each millisecond, which results in a sampling frequency of
+1 kHz. The ADC module provides an analog value `watchdog <Watchdog_>`_, which is used to detect wirebreaks and other hardware errors that result in a wrong resistance measurement.
+
+The sample frequency is controlled by
+
+.. doxygendefine:: ADC_PT1000_SAMPLE_CNT_DELAY
+
+whereas the ADC Peripheral module is defined by
+
+.. doxygendefine:: ADC_PT1000_PERIPH
+
+Prefilter
+~~~~~~~~~
+
+The analog value prefilter is used to filter outliers. It is triggered after a certain amount *n* of values have been sampled by the `ADC`_.
+The filter then removes the two most extreme values and computes the average of the remaining *n-2* values.
+
+The resulting datastream has a sampling rate of 1/6 kHz.
+
+
+Watchdog
+~~~~~~~~
+
+The analog watchdog supervises the measured value of the `ADC`_. It is configured by the following defines:
+
+.. doxygendefine:: ADC_PT1000_LOWER_WATCHDOG
+
+.. doxygendefine:: ADC_PT1000_UPPER_WATCHDOG
+
+.. doxygendefine:: ADC_PT1000_WATCHDOG_SAMPLE_COUNT
+
+The watchdog will set the :ref:`safety_flags_adc_watchdog` error flag.
+
+ADC Value to Ohm
+~~~~~~~~~~~~~~~~
+
+This block converts the analog value to an Ohm resistance value.
+The formula is:
+
+.. math::
+	R(V) = \frac{V}{4096} \cdot 2500~\Omega
+
+The equation is implemented in 
+
+.. doxygendefine:: ADC_TO_RES
+
+and applied during the `Exponential Moving Average Filter`_.
+
+Exponential Moving Average Filter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The external moving average filter filters the measured resistance value. It's equation is:
+
+.. math::
+	y[n] = (1-\alpha) y[n-1] + \alpha x[n]
+
+The filter constant *alpha* defaults to the define
+
+.. doxygendefine:: ADC_PT1000_FILTER_WEIGHT
+
+and can be changed in code using
+
+.. doxygenfunction:: adc_pt1000_set_moving_average_filter_param
+
+After initial startup and after each change of the filter constant, the filter will set the :ref:`safety_flags_adc_unstable` flag for a defined sample count of:
+
+.. doxygendefine:: ADC_FILTER_STARTUP_CYCLES

doc/source/firmware/safety.rst

@@ -0,0 +1,12 @@
+.. _firmware_safety:
+
+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.
+
+.. toctree::
+	:maxdepth: 2
+	
+	flags

doc/source/hardware/controller-bom.rst

@@ -0,0 +1,8 @@
+.. _hw_bom:
+
+Interactive BoM of Controller Board
+===================================
+
+.. raw:: html
+
+    <iframe src="../_static/ibom.html" width="100%" height="1500"></iframe>

doc/source/hardware/frontend.rst

@@ -0,0 +1,4 @@
+.. _hw_analog_fe:
+
+Analog Frontend
+===============

doc/source/hardware/index.rst

@@ -0,0 +1,10 @@
+.. _hw:
+
+Hardware
+========
+
+.. toctree::
+	:maxdepth: 2
+	:glob:
+
+	*

doc/source/index.rst

@@ -16,4 +16,5 @@ Quick Links
 	:caption: Contents
 
 	self
-	api/index
+	hardware/index
+	firmware/index

stm-firmware/adc-meas.c

@@ -18,6 +18,11 @@
  * If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file adc-meas.c
+ * @brief Implementation of the PT1000 measurement ADC and filtering functions
+ */
+
 #include <reflow-controller/adc-meas.h>
 #include <stm32/stm32f4xx.h>
 #include <cmsis/core_cm4.h>
@@ -30,7 +35,13 @@ static float pt1000_offset;
 static float pt1000_sens_dev;
 static bool calibration_active;
 static float filter_alpha;
+
+/**
+ * @brief Filtered PT1000 resistance value.
+ * @note This value is not yet calibrated. Use @ref adc_pt1000_get_current_resistance to get this value with calibration.
+ */
 static volatile float pt1000_res_raw_lf;
+
 static volatile int * volatile streaming_flag_ptr = NULL;
 static uint32_t filter_startup_cnt;
 static volatile float adc_pt1000_raw_reading_hf;
@@ -41,6 +52,9 @@ volatile float * volatile stream_buffer = NULL;
 volatile uint32_t stream_count;
 volatile uint32_t stream_pos;
 
+/**
+ * @brief Conversion macro: ADC value to resistance
+ */
 #define ADC_TO_RES(adc) ((float)(adc) / 4096.0f * 2500.0f)
 
 static inline void adc_pt1000_stop_sample_frequency_timer()

stm-firmware/include/reflow-controller/adc-meas.h

@@ -18,6 +18,10 @@
  * If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @file adc-meas.h
+ */
+
 #ifndef __ADCMEAS_H__
 #define __ADCMEAS_H__