CCY: Update DBC and add Safety Controller Parameterization

docs/source/everest_charging_stack.rst

@@ -22,7 +22,7 @@ An overview of the EVerest modules is shown in the next section.
 
 .. include:: ../../includes/everest_overview_of_everest_modules.inc
 
-**DCSupplySimulator** (`view on GitHub <https://github.com/EVerest/everest-core/blob/main/modules/simulation/DCSupplySimulator/manifest.yaml>`__)
+**DCSupplySimulator** (`view on GitHub <https://github.com/EVerest/everest-core/blob/main/modules/Simulation/DCSupplySimulator/manifest.yaml>`__)
 
 This module simulates a DC power supply device.
 

docs/source/safety_controller.rst

@@ -88,6 +88,8 @@ This state can only be left by a reset.
 .. figure:: _static/images/safety_controller_states.svg
    :width: 1000pt
 
+.. include:: safety_controller_parameterization.rst
+
 .. include:: safety_controller_uart.rst
 
 .. include:: everest_bsp.rst

docs/source/safety_controller_parameterization.rst

@@ -0,0 +1,162 @@
+.. _safety_controller_parameterization.rst:
+
+Safety Controller Parameterization
+----------------------------------
+
+
+Overview
+^^^^^^^^
+
+The safety controller can or must be parameterized to a certain extent. For example, it is required to know
+which temperature channels are actually in use and at which temperature thresholds the charging process needs to
+be stopped to avoid injuries to users and/or prevent damage to the EVSE itself.
+It also supports an emergency input channel which can be disabled when not connected/required in
+the actual customer setup.
+
+These safety controller parameters are stored as a binary parameter block, directly in the safety controller's flash.
+When shipped from factory, there is a default parameter block installed which allows easy evaluation of the product,
+but is not intended for production usage in the field.
+Customers are encouraged to adjust the parameters to their requirements/needs during deployment of the board into
+an actual charger.
+
+To adjust the parameters, some small command line tools are included in the shipped Linux firmware which allow
+to create/modify the parameters on the board itself. However, it is also possible to use these tools on a Linux
+host system (e.g. in a virtual machine) and then to transfer the created parameter block to each board
+and install it.
+
+The mentioned tools are part of the `ra-utils repository <https://github.com/chargebyte/ra-utils>`__ on Github.
+
+To make the handling of parameters human-friendly, all parameters can be put together using a YAML text file.
+
+.. code-block:: yaml
+
+   version: 1
+   pt1000s:
+     - abort-temperature: 75.0 °C
+       resistance-offset: 0.85 Ω
+     - abort-temperature: 85.0 °C
+       resistance-offset: 1.042 Ω
+     - 80.0 °C
+     - disabled
+
+   contactors:
+     - with-feedback-normally-open
+     - disabled
+     - disabled
+
+   estops:
+     - active-low
+     - disabled
+     - disabled
+
+.. important::
+
+   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
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On Charge Control Y, the high-voltage contactors are not controlled directly by the safety controller firmware.
+Please do not modify the shipped factory settings as there are board revision specific differences.
+
+
+Emergency Input Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The safety controller can monitor up to 3 emergency inputs, however on Charge Control Y only one physical
+emergency input is available. So the second and third inputs must kept disabled.
+
+Possible configuration values for the first one are:
+
+- `disabled`
+- `active-low`
+
+
+Installing a Parameter Block
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Once the YAML file is created and fits your charger setup, it is required to convert it to a binary parameter block file.
+In the mentioned repository, there exists a tool `ra-pb-create` to generate such a binary file from the YAML file.
+The following session transcript shows how the install procedure works:
+
+.. code-block:: sh
+
+   # create a YAML file on-the-fly
+   $ cat <<EOL > /tmp/my-parameters.yaml
+   version: 1
+   pt1000s:
+     - abort-temperature: 75.0 °C
+       resistance-offset: 0.85 Ω
+     - abort-temperature: 85.0 °C
+       resistance-offset: 1.042 Ω
+     - 80.0 °C
+     - disabled
+
+   contactors:
+     - with-feedback-normally-open
+     - disabled
+     - disabled
+
+   estops:
+     - active-low
+     - disabled
+     - disabled
+   EOL
+
+   # convert YAML to binary
+   ra-pb-create -i /tmp/my-parameters.yaml -o /tmp/my-parameters.bin
+
+   # stop EVerest - to have exclusive access to safety controller
+   systemctl stop everest
+
+   # flash the parameter block
+   ra-update -a data flash /tmp/my-parameters.bin
+
+   # restart EVerest
+   systemctl start everest
+
+
+Checking the Installed Parameter Block
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To check which settings are currently used by the safety controller firmware, it is possible to read back the parameter block.
+
+.. code-block:: sh
+
+   systemctrl stop everest
+   ra-update -a data dump | ra-pb-dump
+
+This will print the current settings in YAML format on stdout.