Improve sphinx

doc/source/firmware/code/dmas.rst_unused

@@ -0,0 +1,8 @@
+.. _api_dmas:
+
+Peripheral DMA Library Code
+====================================
+
+.. doxygengroup:: dma-ring-buffer
+   :project: Reflow Controller Firmware
+

doc/source/firmware/code/index.rst

@@ -0,0 +1,11 @@
+.. _api:
+
+Firmware Code Documentation
+===========================
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    *
+    safety/safety-controller

doc/source/firmware/code/main.rst

@@ -0,0 +1,8 @@
+.. _api_main:
+
+Reflow Controller Firmware Main File
+====================================
+
+.. doxygenfile:: main.c
+   :project: Reflow Controller Firmware
+

doc/source/firmware/code/safety/safety-adc.rst

@@ -0,0 +1,8 @@
+.. _dox_safety_adc:
+
+Safety ADC
+====================================
+
+.. doxygengroup:: safety-adc
+   :project: Reflow Controller Firmware
+

doc/source/firmware/code/safety/safety-controller.rst

@@ -0,0 +1,14 @@
+.. _dox_safety_controller:
+
+Safety Controller
+====================================
+
+.. toctree::
+   :maxdepth: 1
+
+   safety-adc
+
+
+.. doxygengroup:: safety-controller
+   :project: Reflow Controller Firmware
+

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