Docu

doc/source/conf.py

@@ -38,6 +38,7 @@ subprocess.call('doxygen Doxyfile.in', shell=True)
 extensions = [
 	'sphinx_rtd_theme',
 	'sphinx.ext.autodoc',
+	'sphinx.ext.todo',
 	'sphinxcontrib.blockdiag',
 	'breathe'
 ]
@@ -74,3 +75,5 @@ breathe_default_members = ('members', 'undoc-members')
 
 blockdiag_html_image_format = 'SVG'
 blockdiag_latex_image_format = 'PDF'
+
+todo_include_todos = True

doc/source/firmware/code/index.rst

@@ -1,7 +1,7 @@
 .. _api:
 
-Firmware Code Documentation
-===========================
+Important Code APIs
+===================
 
 .. toctree::
     :maxdepth: 2

doc/source/firmware/index.rst

@@ -1,11 +1,11 @@
 .. _firmware:
 
-Reflow Controller Firmware Internals
-====================================
+Reflow Controller Firmware
+==========================
 
-This chapter describes the internals of the reflow controller's firmware.
+This chapter describes 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.
+mechanisms and the behavior. For a detailed code documentation see the doxygen output.
 
 .. toctree::
 	:maxdepth: 2

doc/source/firmware/pt1000-processing.rst

@@ -24,7 +24,7 @@ The following block diagram shows the processing chain of the temperature signal
 		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"]
+		PT1000 [label = "LF", shape = endpoint, description="Low Frequency PT1000 resistance value (see: `MAVG Filter <Exponential Moving Average Filter_>`_)"]
 		RAW_STREAM [label = "Stream", shape = endpoint, description="Raw value streaming"];
 
 		ADC -> WATCHDOG;
@@ -106,3 +106,86 @@ and can be changed in code using
 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
+
+The moving average filter's output signal is the Low Frequency (LF) PT1000 resistance signal used for internal PT1000 measurements.
+
+Reading and Converting the PT1000 Value
+---------------------------------------
+
+Calibration
+~~~~~~~~~~~
+
+The functions
+
+.. doxygenfunction:: adc_pt1000_set_resistance_calibration
+	:outline:
+
+and
+
+.. doxygenfunction:: adc_pt1000_get_resistance_calibration
+	:outline:
+
+are used to set the reistance calibration internally. For a guide on how to calibrate the deivce, see the usage page.
+
+.. todo:: Add link here
+
+The calibration is calculated the following way:
+
+.. blockdiag::
+	:desctable:
+	
+	blockdiag {
+		orientation = portrait;
+		
+		LF [label="LF", shape=beginpoint, description="Low Frequency PT1000 Value"];
+		SENS [label="Sens", description="Sensitivity Correction :math:`\sigma`"];
+		OFFSET [label="Offset", description="Offset Correction :math:`O`"];
+		OUT [shape=endpoint, description="Corrected Value"];
+
+		LF -> SENS -> OFFSET -> OUT
+	}
+
+The final calibrated PT1000 resistance is calculated as:
+
+.. math::
+	R_{PT1000_{corr}} = R_{PT1000_{LF}} \cdot (1 + \sigma) + O
+
+The default values, if no calibration is loaded / executed, are:
+
+============== =========
+:math:`\sigma` :math:`O`
+============== =========
+0              1
+============== =========
+
+Get Calibration Corrected Value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The PT1000 value is available through the following function.
+If a calibration is set, it is applied.
+
+.. doxygenfunction:: adc_pt1000_get_current_resistance
+
+Converting the Value
+~~~~~~~~~~~~~~~~~~~~
+
+The valid range for conversion is between
+
+.. doxygendefine:: TEMP_CONVERSION_MIN_RES
+	:outline:
+
+and 
+
+.. doxygendefine:: TEMP_CONVERSION_MAX_RES
+	:outline:
+
+By default, the valid range is:
+
+.. math::
+	1000~\Omega \le R_{PT1000} \le 2200~\Omega
+
+.. doxygenfunction:: temp_converter_convert_resistance_to_temp
+
+The cvonversion function is based on a lookup table with linear interpolation between the data points.
+The lookuptable is stored as a header file and can, if necessary, be recreated using the `create-temp-lookup-table.py` script.
+	

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

@@ -138,15 +138,13 @@ void adc_pt1000_set_resistance_calibration(float offset, float sensitivity_devia
 void adc_pt1000_get_resistance_calibration(float *offset, float *sensitivity_deviation, bool *active);
 
 /**
- * @brief Get the current reistance value
+ * @brief Get the current resistance value
  *
- * If the reistance calibration is enabled, this function applies the calculations of the raw resistance reading and
+ * If the resistance calibration is enabled, this function applies the calculations of the raw resistance reading and
  * returns the corrected value.
  *
  * If an ADC error is set, the status is negative. The status is 2 during the first measurements with a given filter setting. Technically, the resistance value is
  * correct but the filter is not stable yet.
- * Use adc_pt1000_check_error to check the error and reinitialize the ADC.
- *
  *
  * @param[out] resistance Resistance output in Ohms
  * @return Status