Adapt parameter block documentation to safety fw v0.2.6

Signed-off-by: Michael Heimpold <michael.heimpold@chargebyte.com>

Author: mhei

docs/source/safety_controller_parameterization.rst

@@ -32,15 +32,21 @@ To make the handling of parameters human-friendly, all parameters can be put tog
 
 .. code-block:: yaml
 
+   version: 1
    pt1000s:
-     - 75.0 °C
-     - 85.0 °C
-     - disabled
+     - abort-temperature: 75.0 °C
+       resistance-offset: 0.85 Ω
+     - abort-temperature: 85.0 °C
+       resistance-offset: 1.042 Ω
+     - 80.0 °C
      - disabled
 
    contactors:
+     - type: without-feedback
+       close-time: 100 ms
+       open-time: 100 ms
      - without-feedback
-     - without-feedback
+     - disabled
 
    estops:
      - active-low
@@ -52,35 +58,64 @@ To make the handling of parameters human-friendly, all parameters can be put tog
    The YAML file is required to be encoded in UTF-8. While most parameters are ASCII only, temperature thresholds require
    trailing `°C` suffix which has a special UTF-8 encoding sequence. This might be displayed incorrectly in the editor
    when editing on the device itself and/or finally stored wrong in the YAML file.
+   The same applies to the resistance offsets in Ohm.
    When unsure, adapt/create the YAML file on your Linux host system with your preferred editor and transfer it
    to the board via Ethernet network (e.g. SCP/SFTP).
 
 Such a YAML file must be converted to a binary parameter block file afterwards. And this binary parameter block file
 must finally be flashed to the safety controller's flash memory, see below.
 
+.. important::
+
+   The YAML file allows to specify a numeric parameter block version. This version is used internally by the
+   safety controller firmware to detect the binary structure of the parameter block. It must thus match the
+   safety firmware's expectation, otherwise the safety controller will refuse to work and enters safe state directly.
+
 
 Temperature Channel (PT1000) Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The safety controller supports up to 4 PT1000 temperature channels. Thus the YAML file expects for each channel
-either a temperature threshold in °C at which the safety controller stops and/or prevents charging.
-In a PT1000 channel is not wired/used, it is required to disable this channel using the special word `disabled`
+a temperature threshold in °C at which the safety controller stops and/or prevents charging. Also for each channel,
+an offset value in Ohm can be specified. This offset depends on the actual physical wiring and must be determined
+in the specific customer setup.
+If a PT1000 channel is not wired/used, it is required to disable this channel using the special word `disabled`
 instead of a temperature value.
+The example YAML file above shows that the PT1000 configuration is an array with up to 4 items. Each item can either
+be a single temperature threshold, the special token `disabled` or it is a key-value list. Valid keys are
+`abort-temperature` and `resistance-offset`. If no `resistance-offset` is given, then it is assumed to be zero.
+
+The accepted value range for `abort-temperature` is -80.0 °C to 200.0 °C and it is stored with one decimal digit.
+
+The range for `resistance-offset` is -32.0 Ω ... 32.0 Ω and these values are stored with three decimal digits internally.
 
 
 Contactor and Contactor Feedback Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The safety controller allows to control up to 2 high-voltage contactors and can monitor corresponding mirror contacts.
-The mirror contacts need to have `Normally Closed` semantic. In the YAML parameterization, it is possible to
-specify whether the safety controller should actually switch the corresponding output pin and whether to monitor
-the feedback input pins.
+The safety controller allows to control up to 3 high-voltage contactors and can monitor corresponding mirror contacts.
+The mirror contacts support `Normally Closed` and `Normally Open` semantic, but customer must follow chargebyte's
+Charge SOM's EVB reference design otherwise the logic might be inverted.
+In the YAML parameterization, it is possible to specify whether the safety controller should actually switch the
+corresponding output pin and whether to monitor the feedback input pins. When using the feedback, it is usually also
+required to specify the open and closing times of the used contactor. These times are expected in milliseconds and
+used by the Safety Firmware to check after the given time whether the feedback pin has expected level. If the level
+differs from the expectation, then Safety Firmware assumes a malfunction and thus enters safe state.
 
-Possible parameter values are:
+The example YAML file above shows all allowed variants how to parameterize a contactor.
+Possible values for the `type` are:
 
 - `disabled`
 - `without-feedback`
-- `with-feedback`
+- `with-feedback-normally-open`
+- `with-feedback-normally-closed`
+
+Since the open/close timings make no sense in case of `disabled` or `without-feedback`, it is possible to use these
+tokens directly as array item (actually, it is also possible to use the `with-feedback...` ones, but then the timings
+are considered zero).
+
+Both `close-time` and `open-time` accept integer values in the range 0 to 2550 ms, however the given value is
+divided by 10 before it is actually stored internally.
 
 
 Emergency Input Configuration
@@ -105,15 +140,19 @@ The following session transcript shows how the install procedure works:
 
    # create a YAML file on-the-fly
    $ cat <<EOL > /tmp/my-parameters.yaml
+   version: 1
    pt1000s:
-     - 75.0 °C
-     - 85.0 °C
+     - abort-temperature: 85.0 °C
+       resistance-offset: 0.85 Ω
+     - abort-temperature: 75.0 °C
+       resistance-offset: 1.1 Ω
      - disabled
      - disabled
 
    contactors:
      - without-feedback
      - without-feedback
+     - disabled
 
    estops:
      - active-low