From f6f01b0510bc565f95fbfa18b16d238a6e52eeff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Mon, 3 Aug 2020 21:13:04 +0200 Subject: [PATCH] Improve sphinx --- doc/source/Doxyfile.in | 6 +- doc/source/_static/ibom.html | 3432 +++++++++++++++++ doc/source/conf.py | 3 + .../code/dmas.rst_unused} | 0 doc/source/{api => firmware/code}/index.rst | 0 doc/source/{api => firmware/code}/main.rst | 0 .../code}/safety/safety-adc.rst | 0 .../code}/safety/safety-controller.rst | 0 doc/source/firmware/flags.rst | 14 + doc/source/firmware/index.rst | 16 + doc/source/firmware/pt1000-processing.rst | 108 + doc/source/firmware/safety.rst | 12 + doc/source/hardware/controller-bom.rst | 8 + doc/source/hardware/frontend.rst | 4 + doc/source/hardware/index.rst | 10 + doc/source/index.rst | 3 +- stm-firmware/adc-meas.c | 14 + .../include/reflow-controller/adc-meas.h | 4 + 18 files changed, 3630 insertions(+), 4 deletions(-) create mode 100644 doc/source/_static/ibom.html rename doc/source/{api/dmas.rst => firmware/code/dmas.rst_unused} (100%) rename doc/source/{api => firmware/code}/index.rst (100%) rename doc/source/{api => firmware/code}/main.rst (100%) rename doc/source/{api => firmware/code}/safety/safety-adc.rst (100%) rename doc/source/{api => firmware/code}/safety/safety-controller.rst (100%) create mode 100644 doc/source/firmware/flags.rst create mode 100644 doc/source/firmware/index.rst create mode 100644 doc/source/firmware/pt1000-processing.rst create mode 100644 doc/source/firmware/safety.rst create mode 100644 doc/source/hardware/controller-bom.rst create mode 100644 doc/source/hardware/frontend.rst create mode 100644 doc/source/hardware/index.rst diff --git a/doc/source/Doxyfile.in b/doc/source/Doxyfile.in index 1fe3506..fe2dbcd 100644 --- a/doc/source/Doxyfile.in +++ b/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, diff --git a/doc/source/_static/ibom.html b/doc/source/_static/ibom.html new file mode 100644 index 0000000..26202b7 --- /dev/null +++ b/doc/source/_static/ibom.html @@ -0,0 +1,3432 @@ + + + + + + + Interactive BOM for KiCAD + + + + + +
+
+
+
+ +
+ + + + +
+ +
+ + + + + + +
+
+
+ + + +
+
+ + + +
+
+ + + +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Board statsFrontBackTotal
Components~~~
Groups~~~
SMD pads~~~
TH pads~
+ + + + + + + +
Checkboxes
+
+
+
+ +
+
+
Save board image
+
+ + X + +
+ +
+ + +
+
+
+ Config and checkbox state +
+ + +
+
+
+
+
+
+ + + + + + + + + + + +
+ Title + + Revision +
+ Company + + Date +
+
+
+
+
+
+ + +
+ +
+
+
+ + + + + +
+
+
+
+
+ + + + +
+
+
+
+ + + + +
+
+
+
+
+ + + diff --git a/doc/source/conf.py b/doc/source/conf.py index 71d3a95..f14b3c6 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', + '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' diff --git a/doc/source/api/dmas.rst b/doc/source/firmware/code/dmas.rst_unused similarity index 100% rename from doc/source/api/dmas.rst rename to doc/source/firmware/code/dmas.rst_unused diff --git a/doc/source/api/index.rst b/doc/source/firmware/code/index.rst similarity index 100% rename from doc/source/api/index.rst rename to doc/source/firmware/code/index.rst diff --git a/doc/source/api/main.rst b/doc/source/firmware/code/main.rst similarity index 100% rename from doc/source/api/main.rst rename to doc/source/firmware/code/main.rst diff --git a/doc/source/api/safety/safety-adc.rst b/doc/source/firmware/code/safety/safety-adc.rst similarity index 100% rename from doc/source/api/safety/safety-adc.rst rename to doc/source/firmware/code/safety/safety-adc.rst diff --git a/doc/source/api/safety/safety-controller.rst b/doc/source/firmware/code/safety/safety-controller.rst similarity index 100% rename from doc/source/api/safety/safety-controller.rst rename to doc/source/firmware/code/safety/safety-controller.rst diff --git a/doc/source/firmware/flags.rst b/doc/source/firmware/flags.rst new file mode 100644 index 0000000..d6513eb --- /dev/null +++ b/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 +-------------------------- diff --git a/doc/source/firmware/index.rst b/doc/source/firmware/index.rst new file mode 100644 index 0000000..dd4e39f --- /dev/null +++ b/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 + diff --git a/doc/source/firmware/pt1000-processing.rst b/doc/source/firmware/pt1000-processing.rst new file mode 100644 index 0000000..d5ceb6a --- /dev/null +++ b/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 `_"]; + WATCHDOG [label = "WDT", shape=endpoint, description="`Hardware Value Watchdog `_"]; + PREFILTER [label=Prefilter, description="`Prefiltering and Downsampling `_"]; + 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"] + 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 `_, 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 diff --git a/doc/source/firmware/safety.rst b/doc/source/firmware/safety.rst new file mode 100644 index 0000000..7544bbe --- /dev/null +++ b/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 diff --git a/doc/source/hardware/controller-bom.rst b/doc/source/hardware/controller-bom.rst new file mode 100644 index 0000000..ff8a652 --- /dev/null +++ b/doc/source/hardware/controller-bom.rst @@ -0,0 +1,8 @@ +.. _hw_bom: + +Interactive BoM of Controller Board +=================================== + +.. raw:: html + + diff --git a/doc/source/hardware/frontend.rst b/doc/source/hardware/frontend.rst new file mode 100644 index 0000000..d7e8260 --- /dev/null +++ b/doc/source/hardware/frontend.rst @@ -0,0 +1,4 @@ +.. _hw_analog_fe: + +Analog Frontend +=============== diff --git a/doc/source/hardware/index.rst b/doc/source/hardware/index.rst new file mode 100644 index 0000000..228f808 --- /dev/null +++ b/doc/source/hardware/index.rst @@ -0,0 +1,10 @@ +.. _hw: + +Hardware +======== + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/doc/source/index.rst b/doc/source/index.rst index c0c356e..70f1ac4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,4 +16,5 @@ Quick Links :caption: Contents self - api/index + hardware/index + firmware/index diff --git a/stm-firmware/adc-meas.c b/stm-firmware/adc-meas.c index a4c25ef..635353d 100644 --- a/stm-firmware/adc-meas.c +++ b/stm-firmware/adc-meas.c @@ -18,6 +18,11 @@ * If not, see . */ +/** + * @file adc-meas.c + * @brief Implementation of the PT1000 measurement ADC and filtering functions + */ + #include #include #include @@ -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() diff --git a/stm-firmware/include/reflow-controller/adc-meas.h b/stm-firmware/include/reflow-controller/adc-meas.h index 235b58f..c8b2575 100644 --- a/stm-firmware/include/reflow-controller/adc-meas.h +++ b/stm-firmware/include/reflow-controller/adc-meas.h @@ -18,6 +18,10 @@ * If not, see . */ +/** + * @file adc-meas.h + */ + #ifndef __ADCMEAS_H__ #define __ADCMEAS_H__