From 97c32b04434f887f483ed2854cb4bff7b63e973a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Tue, 11 Aug 2020 23:21:24 +0200 Subject: [PATCH] Write documentation --- doc/Makefile | 2 + doc/source/conf.py | 1 + doc/source/firmware/flags.rst | 15 + doc/source/firmware/pt1000-processing.rst | 17 +- .../hardware/frontend-schematic_v1.2.svg | 16443 ++++++++++++++++ doc/source/hardware/frontend.rst | 8 + doc/source/hardware/index.rst | 2 + doc/source/index.rst | 1 + doc/source/usage/calibration.rst | 17 + doc/source/usage/command-line.rst | 60 + doc/source/usage/index.rst | 12 + 11 files changed, 16570 insertions(+), 8 deletions(-) create mode 100644 doc/source/hardware/frontend-schematic_v1.2.svg create mode 100644 doc/source/usage/calibration.rst create mode 100644 doc/source/usage/command-line.rst create mode 100644 doc/source/usage/index.rst diff --git a/doc/Makefile b/doc/Makefile index d0c3cbf..20b5dea 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -18,3 +18,5 @@ help: # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +livehtml: + sphinx-autobuild -b html $(SPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html diff --git a/doc/source/conf.py b/doc/source/conf.py index 09f5870..2a5efd0 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -74,6 +74,7 @@ breathe_default_project = "Reflow Controller Firmware" breathe_default_members = ('members', 'undoc-members') blockdiag_html_image_format = 'SVG' +breathe_show_define_initializer = True blockdiag_latex_image_format = 'PDF' todo_include_todos = True diff --git a/doc/source/firmware/flags.rst b/doc/source/firmware/flags.rst index d6513eb..bd7eeba 100644 --- a/doc/source/firmware/flags.rst +++ b/doc/source/firmware/flags.rst @@ -3,6 +3,21 @@ Safety Flags ============ +The safety flags are represented in software by the following enums + +.. doxygenenum:: safety_flag + + +.. _safety_flags_adc_overflow: + +ERR_FLAG_MEAS_ADC_OVERFLOW +-------------------------- + +.. _safety_flags_adc_off: + +ERR_FLAG_MEAS_ADC_OFF +--------------------- + .. _safety_flags_adc_watchdog: ERR_FLAG_MEAS_ADC_WATCHDOG diff --git a/doc/source/firmware/pt1000-processing.rst b/doc/source/firmware/pt1000-processing.rst index a027c6a..703db32 100644 --- a/doc/source/firmware/pt1000-processing.rst +++ b/doc/source/firmware/pt1000-processing.rst @@ -18,6 +18,7 @@ The following block diagram shows the processing chain of the temperature signal blockdiag { orientation = portrait; + FRONTEND[description=":ref:`hw_analog_fe`", label="Frontend"]; ADC[description="`Analog to Digital Converter `_"]; WATCHDOG [label = "WDT", shape=endpoint, description="`Hardware Value Watchdog `_"]; PREFILTER [label=Prefilter, description="`Prefiltering and Downsampling `_"]; @@ -27,7 +28,7 @@ The following block diagram shows the processing chain of the temperature signal 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; + FRONTEND -> ADC -> WATCHDOG; ADC -> PREFILTER [label="1 kHz"]; PREFILTER -> ADC2RES [label="1/6 kHz"]; ADC2RES -> MAVG; @@ -53,10 +54,12 @@ whereas the ADC Peripheral module is defined by 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 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. By default ``n`` is configured to: -The resulting datastream has a sampling rate of 1/6 kHz. +.. doxygendefine:: ADC_PT1000_DMA_AVG_SAMPLES + +Therefore, by default, the resulting datastream has a sampling rate of 1/6 kHz. This depends on the :c:macro:`ADC_PT1000_SAMPLE_CNT_DELAY` and ``n`` Watchdog @@ -125,9 +128,7 @@ 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 +are used to set the reistance calibration internally. For a guide on how to calibrate the deivce, see the corresponding :ref:`usage_calibration` usage page. The calibration is calculated the following way: @@ -187,5 +188,5 @@ By default, the valid range is: .. 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. +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/doc/source/hardware/frontend-schematic_v1.2.svg b/doc/source/hardware/frontend-schematic_v1.2.svg new file mode 100644 index 0000000..9d74329 --- /dev/null +++ b/doc/source/hardware/frontend-schematic_v1.2.svg @@ -0,0 +1,16443 @@ + + + +SVG Picture created as frontend-Frontend.svg date 2020/08/11 22:56:54 + Picture generated by Eeschema-SVG + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +1 + + + + + + +2 + + + + + +3 + + + + + +4 + + + + + + +5 + + + + + +6 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +1 + + + + + + +2 + + + + + +3 + + + + + +4 + + + + + + +5 + + + + + +6 + + + + + + + + + + + + + + + + + + + + +A + + + + + + +B + + + + + +C + + + + + +D + + + + + + + + + + + + + + + + + + + + +A + + + + + + +B + + + + + +C + + + + + +D + + + + + +Date: 2020-02-18 + + + + + + + + + + + + + + + + + + + + + + + + + + + + +KiCad E.D.A. kicad 5.1.6 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Rev: v1.2 + + + + + + + + + + + + + + + +Size: A4 + + + + + + + + + + + + + + + +Id: 3/3 + + + + + + + + + + + + + + + + + +Title: Reflow Oven Controller + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +File: frontend.sch + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Sheet: /Frontend/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Shimatta + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +GND + + + + + + + + + + + + + + +R308 + + + + + +0 + + + + + + + + + + + + + + +C311 + + + + + + + + +22n + + + + + + + + + + + + + + + + +R316 + + + + + + +0 + + + + + + + + + + + + +R311 + + + + + + + +DNP + + + + + + + + + + + + + + + + +C306 + + + + + + +DNP + + + + + + + + + + + + + + + +R310 + + + + + + +1k 0.1% + + + + + + + + + + + + + + + + + + + + + + + +R312 + + + + + + +1k 0.1% + + + + + + + + + + + + + + + + + + + + + + + + +C303 + + + + +100n + + + + + + + + + + + + + + + + + + +C305 + + + + +1u + + + + + + + + + + + + + + + +R306 + + + + + +24k 0.1% + + + + + + + + + + + + + + + + + + + + + + + + +R309 + + + + + +5k 0.1% + + + + + + + + + + + + + + + + + + + + + + + +C304 + + + + + +1u + + + + + + + + + + + + + + + + +R318 + + + + + + + + +680 + + + + + + + + + + + +GND + + + + + + + + + + + + + + +R303 + + + + + +150 + + + + + + + + + + + +GND + + + + + + + + + + +D + + + ++ + + +12 + + + + +- + +13 + + + + +14 + + + + +U301E + + + + + + + +MCP6V34 + + + + + + + + + + + + + + + + + + + + + +C308 + + + + + + +100n + + + + + + + + + + + + + + + + + + + + +C309 + + + + + + +Bridge + + + + + + + + + + + + + + + + + + + + + + +R313 + + + + + + +4k7 + + + + + + + + + + + + + +GND + + + + + + + + + + + + ++3V3 + + + + + + + + + + + + + + ++3.3VA + + + + + + + + + + + + + + + + + + + + + + + + + + +U302 + + + + +TL431LI-DBZ + + + + + + + + + + + + + + + + + + + + + + + + + + +C301 + + + + + +10u + + + + + + + + + + + + +GND + + + + + + + + + + + + + + +R315 + + + + + + +5k 0.1% + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +GND + + + + + +1 + + + + +DQ + + + +2 + + + +VDD + + + + + +3 + + +U303 + + + + +DS18B20 + + + + + + + + + + + + + + + +GND + + + + + + + + + + + + ++3.3VA + + + + + + + + + + + + + + + + + ++3.3VA + + + + + + + + + + + + + + + + + + + + +C313 + + + + + +DNP + + + + + + + + + + +GND + + + + + + + + + + + + + + +R319 + + + + + + +2M + + + + + + + + + +GND + + + + + + + + + + +GND + + + + + + + + + + +GND + + + + + + + + + + + + + + +R314 + + + + + + + +100 + + + + + + + + + + + +GND + + + + + + + + + + +GND + + + + + + + + + + + + + + +R317 + + + + + + +1k 0.1% + + + + + + + + + + + + + + + + + + + + + + + + + +C310 + + + + + + + +DNP + + + + + + + + + + + + +TP303 + + + + + + +TEMP_OUT + + + + + + + + + + + + + + + + + + + + + + +R301 + + + + + + +1k 0.1% + + + + + + + + + + + + + + + + + + + + +TP301 + + + + + + + +VREF + + + + + + + + + + + + + + + +TP302 + + + + + + +IBIAS + + + + + + + + + + + + + + + + + +R304 + + + + + + +1k 0.1% + + + + + + + + + + + + + + + + + + + + +TP304 + + + + + + + +GND + + + + + + + + + + +GND + + + + + + + + + + + +TP305 + + + + + + +GND + + + + + + + + + + + + + + + +C302 + + + + +100n + + + + + + + + + + + + + +GND + + + + + + + + + + + +TP306 + + + + + + +GND + + + + + + + + + + +GND + + + + + + + + + + + + + + +R305 + + + + + +1k 0.1% + + + + + + + + + + + + + + + + + + + +B + + + ++ + + +5 + + +- + +6 + + +7 + +U301C + + + + + + +MCP6V34 + + + + + + + + + + + + + + + + + + + + +R307 + + + + + + + +1k 0.1% + + + + + + + + + + + + + + + + + + + + + + + + +R302 + + + + + +1k 0.1% + + + + + + + + + + + + + + + + + + + + + + + + +C307 + + + + +22n + + + + + + + + + + + +C + + + ++ + + +10 + + + + +8 + + +- + +9 + +U301D + + + + + + +MCP6V34 + + + + + + + + + + + + + + + +GND + + + + + + + + + + + + + + + + + + + + + + + +VSS + + + + + +11 + + + + + + + +VDD + + + + + +4 + + + +U301A + + + + + + + +MCP6V34 + + + + + + + + + + + + + + + +A + + + + +1 + + + +- + +2 + + ++ + + +3 + +U301B + + + + + + +MCP6V34 + + + + + + + + + + + + + + + + + + + + +C312 + + + + + +100n + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +SENS- + + + + + + + + + + + +SENS+ + + + + + + + + + + + + +FORCE- + + + + + + + + + + + + + + +FORCE+ + + + + + + + + + + + + + + + +VREF + + + + + + + + + + + + +TEMP_OUT + + + + + + + + + + + + + + + + +FRONTEND_TEMP + + + + + + + + + + + + + + + + + + + + + + + + +F+ + + + + +S+ + + + +VREF_OP + + + + + + + + + + +S- + + +F- + + + +F+ + + + + +F- + + + +VREF + + + + + + + +TEMP_OUT + + + + + + + + + + + +S- + + +VREF + + + + + + + +S+ + + + +If the circuit oscillates, try: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +R319 = 0 Ohm + + + + + + + + + + + + + + + +R317 = 250 Ohm + + + + + + + + + + + + + + + + + +C313 = 10 uF + + + + + + + + + + + + + + +C314 = 2.2 uF + + + + + + + + + + + + + + + +This must be shorted + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Use low drift types for the marked resistors + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Optional. Presence is detected in SW + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Populate this circuitry, if a temperature compensation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +of the frontend is wanted + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/hardware/frontend.rst b/doc/source/hardware/frontend.rst index d7e8260..7a07f7d 100644 --- a/doc/source/hardware/frontend.rst +++ b/doc/source/hardware/frontend.rst @@ -2,3 +2,11 @@ Analog Frontend =============== + +Schematic +--------- + +.. image:: frontend-schematic_v1.2.svg + :target: /_images/frontend-schematic_v1.2.svg + + diff --git a/doc/source/hardware/index.rst b/doc/source/hardware/index.rst index 228f808..ad35172 100644 --- a/doc/source/hardware/index.rst +++ b/doc/source/hardware/index.rst @@ -3,6 +3,8 @@ Hardware ======== +This guide on the reflow controller's hardware is based on the ``reflow-oven-control-pcb`` -- Version ``v1.2`` + .. toctree:: :maxdepth: 2 :glob: diff --git a/doc/source/index.rst b/doc/source/index.rst index 70f1ac4..f943221 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,5 +16,6 @@ Quick Links :caption: Contents self + usage/index hardware/index firmware/index diff --git a/doc/source/usage/calibration.rst b/doc/source/usage/calibration.rst new file mode 100644 index 0000000..5a036b2 --- /dev/null +++ b/doc/source/usage/calibration.rst @@ -0,0 +1,17 @@ +.. _usage_calibration: + +Calibration +=========== + +In order to provide higher measurement accuracy, the PT1000 measurement can be calibrated. The calibration only calibrates the internal :ref:`hw_analog_fe` and not the PT1000 Sensor element itself. +The Sensor element must be conform with the standard PT1000 norms. + +Tests have shown, that a calibration is most likely not necessary, because the resolution of the 12 bit analog measurement is far worse than the reistance reading error produced by the :ref:`hw_analog_fe`. +Calibration might only be necessary if no precission reistors in the frontend hardware are used. + +Calibration can be performed the following ways: + +Command Line Calibration +------------------------ + +Use the :ref:`command_line` to invoke the :ref:`shell_command_calibrate` command. diff --git a/doc/source/usage/command-line.rst b/doc/source/usage/command-line.rst new file mode 100644 index 0000000..e00c623 --- /dev/null +++ b/doc/source/usage/command-line.rst @@ -0,0 +1,60 @@ +.. _command_line: + +Command Line Interface +====================== + +This section describes the command line interface located on the UART interface. +The command line interface is implemented using a "shellmatta" shell module + +Hardware Settings +----------------- + +General Settings +~~~~~~~~~~~~~~~~ + +The UART is configured for the following settings: + +- 115200 Baud +- 1 Stopbit +- No parity +- 8 data bits + + +Setup in Debug Build +~~~~~~~~~~~~~~~~~~~~ + +If the Reflow controller is build in **debug** mode, the UART is located on the internal spring contact connector, which is also used for the SWD interface. + +Setup in Release Build +~~~~~~~~~~~~~~~~~~~~~~ + +In case of a **release** build, the UART is externally accessible on the DIGIO Header. The voltage level is 3.3 Volt LVCMOS. The inputs are ESD protected. Overvoltage is interally clamped and may dammage the clamping diodes! + +- DIGIO2: Reflow Controller's TX +- DIGIO3: Reflow Controller's RX + + +Shell Commands +-------------- + +The following shell commands are available. + +- `safety-flags `_ (alias: flags) +- `calibrate`_ (alias: cal) + +safety-flags +~~~~~~~~~~~~ + +The ``safety-flags`` (``flags``) command displays the status of all safety flags and analog monitors. See: :ref:`safety_flags` + + +.. _shell_command_calibrate: + +calibrate +~~~~~~~~~ + +The ``calibrate`` (``cal``) command is used to calibrate the :ref:`hw_analog_fe`, in order to ensure correct resistance measurement. +Calibration is most likely not necessary! See the :ref:`usage_calibration` page. + +The command will guide you through the calibration process and will ask for two reference resistors with ``1000 Ohm`` and ``2000 Ohm`` values. +Calibration can be aborted using ``CTRL + C``. diff --git a/doc/source/usage/index.rst b/doc/source/usage/index.rst new file mode 100644 index 0000000..4b1b4a2 --- /dev/null +++ b/doc/source/usage/index.rst @@ -0,0 +1,12 @@ +.. _usage: + +Reflow Controller Usage Guide +============================= + +.. toctree:: + :maxdepth: 2 + + command-line + calibration + +