Write documentation

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

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

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

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 <ADC_>`_"];
 		WATCHDOG [label = "WDT", shape=endpoint, description="`Hardware Value Watchdog <Watchdog_>`_"];
 		PREFILTER [label=Prefilter, description="`Prefiltering and Downsampling <Prefilter_>`_"];
@@ -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 <Exponential Moving Average 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 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 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.
+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.
-
-.. todo:: Add link here
 
 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.
 	

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

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:

doc/source/index.rst

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

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.

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 <https://git.shimatta.net/shimatta/shellmatta>
+
+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 <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``.

doc/source/usage/index.rst

@@ -0,0 +1,12 @@
+.. _usage:
+
+Reflow Controller Usage Guide
+=============================
+
+.. toctree::
+	:maxdepth: 2
+	
+	command-line
+	calibration
+
+