From cb3c9896830fe592b5033ef0d296db87a79cba96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Tue, 4 Aug 2020 00:55:16 +0200 Subject: [PATCH] Docu --- doc/source/conf.py | 3 + .../code/{dmas.rst_unused => dmas.rst} | 0 doc/source/firmware/code/index.rst | 4 +- doc/source/firmware/index.rst | 8 +- doc/source/firmware/pt1000-processing.rst | 85 ++++++++++++++++++- .../include/reflow-controller/adc-meas.h | 6 +- 6 files changed, 95 insertions(+), 11 deletions(-) rename doc/source/firmware/code/{dmas.rst_unused => dmas.rst} (100%) diff --git a/doc/source/conf.py b/doc/source/conf.py index f14b3c6..09f5870 100644 --- a/doc/source/conf.py +++ b/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 diff --git a/doc/source/firmware/code/dmas.rst_unused b/doc/source/firmware/code/dmas.rst similarity index 100% rename from doc/source/firmware/code/dmas.rst_unused rename to doc/source/firmware/code/dmas.rst diff --git a/doc/source/firmware/code/index.rst b/doc/source/firmware/code/index.rst index bc5ae08..91732d7 100644 --- a/doc/source/firmware/code/index.rst +++ b/doc/source/firmware/code/index.rst @@ -1,7 +1,7 @@ .. _api: -Firmware Code Documentation -=========================== +Important Code APIs +=================== .. toctree:: :maxdepth: 2 diff --git a/doc/source/firmware/index.rst b/doc/source/firmware/index.rst index dd4e39f..7550976 100644 --- a/doc/source/firmware/index.rst +++ b/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 diff --git a/doc/source/firmware/pt1000-processing.rst b/doc/source/firmware/pt1000-processing.rst index d5ceb6a..a027c6a 100644 --- a/doc/source/firmware/pt1000-processing.rst +++ b/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 `_"] 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 `_)"] 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. + diff --git a/stm-firmware/include/reflow-controller/adc-meas.h b/stm-firmware/include/reflow-controller/adc-meas.h index c8b2575..6e8e850 100644 --- a/stm-firmware/include/reflow-controller/adc-meas.h +++ b/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