Improve sphinx

This commit is contained in:
Mario Hüttel 2020-08-03 21:13:04 +02:00
parent d6815f8285
commit f6f01b0510
18 changed files with 3630 additions and 4 deletions

View File

@ -38,7 +38,7 @@ PROJECT_NAME = "Reflow Oven Controller"
# could be handy for archiving the generated documentation or if some version # could be handy for archiving the generated documentation or if some version
# control system is used. # control system is used.
PROJECT_NUMBER = $(PROJECT_VERSION) PROJECT_NUMBER =
# Using the PROJECT_BRIEF tag one can provide an optional one line description # 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 # 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. # normally produced when WARNINGS is set to YES.
# The default value is: NO. # 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 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation. # be included in the documentation.
@ -485,7 +485,7 @@ EXTRACT_PACKAGE = NO
# included in the documentation. # included in the documentation.
# The default value is: NO. # 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 # 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, # locally in source files will be included in the documentation. If set to NO,

3432
doc/source/_static/ibom.html Normal file

File diff suppressed because one or more lines are too long

View File

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

View File

@ -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
--------------------------

View File

@ -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

View File

@ -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

View File

@ -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

View File

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

View File

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

View File

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

View File

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

View File

@ -18,6 +18,11 @@
* If not, see <http://www.gnu.org/licenses/>. * 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 <reflow-controller/adc-meas.h>
#include <stm32/stm32f4xx.h> #include <stm32/stm32f4xx.h>
#include <cmsis/core_cm4.h> #include <cmsis/core_cm4.h>
@ -30,7 +35,13 @@ static float pt1000_offset;
static float pt1000_sens_dev; static float pt1000_sens_dev;
static bool calibration_active; static bool calibration_active;
static float filter_alpha; 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 float pt1000_res_raw_lf;
static volatile int * volatile streaming_flag_ptr = NULL; static volatile int * volatile streaming_flag_ptr = NULL;
static uint32_t filter_startup_cnt; static uint32_t filter_startup_cnt;
static volatile float adc_pt1000_raw_reading_hf; 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_count;
volatile uint32_t stream_pos; volatile uint32_t stream_pos;
/**
* @brief Conversion macro: ADC value to resistance
*/
#define ADC_TO_RES(adc) ((float)(adc) / 4096.0f * 2500.0f) #define ADC_TO_RES(adc) ((float)(adc) / 4096.0f * 2500.0f)
static inline void adc_pt1000_stop_sample_frequency_timer() static inline void adc_pt1000_stop_sample_frequency_timer()

View File

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