Skip to content

Commit 8462b11

Browse files
mheimhei
authored
Merge pull request #75 from chargebyte/everest/charge_control_y-new-safety-fw
CCY: Update DBC and add Safety Controller Parameterization
2 parents d0b9dd8 + e939950 commit 8462b11

8 files changed

Lines changed: 381 additions & 181 deletions

‎docs/source/everest_charging_stack.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ An overview of the EVerest modules is shown in the next section.
2222

2323
.. include:: ../../includes/everest_overview_of_everest_modules.inc
2424

25-
**DCSupplySimulator** (`view on GitHub <https://github.com/EVerest/everest-core/blob/main/modules/simulation/DCSupplySimulator/manifest.yaml>`__)
25+
**DCSupplySimulator** (`view on GitHub <https://github.com/EVerest/everest-core/blob/main/modules/Simulation/DCSupplySimulator/manifest.yaml>`__)
2626

2727
This module simulates a DC power supply device.
2828

‎docs/source/safety_controller.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ This state can only be left by a reset.
8888
.. figure:: _static/images/safety_controller_states.svg
8989
:width: 1000pt
9090

91+
.. include:: safety_controller_parameterization.rst
92+
9193
.. include:: safety_controller_uart.rst
9294

9395
.. include:: everest_bsp.rst

‎docs/source/safety_controller_parameterization.rst‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
.. _safety_controller_parameterization.rst:
2+
3+
Safety Controller Parameterization
4+
----------------------------------
5+
6+
7+
Overview
8+
^^^^^^^^
9+
10+
The safety controller can or must be parameterized to a certain extent. For example, it is required to know
11+
which temperature channels are actually in use and at which temperature thresholds the charging process needs to
12+
be stopped to avoid injuries to users and/or prevent damage to the EVSE itself.
13+
It also supports an emergency input channel which can be disabled when not connected/required in
14+
the actual customer setup.
15+
16+
These safety controller parameters are stored as a binary parameter block, directly in the safety controller's flash.
17+
When shipped from factory, there is a default parameter block installed which allows easy evaluation of the product,
18+
but is not intended for production usage in the field.
19+
Customers are encouraged to adjust the parameters to their requirements/needs during deployment of the board into
20+
an actual charger.
21+
22+
To adjust the parameters, some small command line tools are included in the shipped Linux firmware which allow
23+
to create/modify the parameters on the board itself. However, it is also possible to use these tools on a Linux
24+
host system (e.g. in a virtual machine) and then to transfer the created parameter block to each board
25+
and install it.
26+
27+
The mentioned tools are part of the `ra-utils repository <https://github.com/chargebyte/ra-utils>`__ on Github.
28+
29+
To make the handling of parameters human-friendly, all parameters can be put together using a YAML text file.
30+
31+
.. code-block:: yaml
32+
33+
version: 1
34+
pt1000s:
35+
- abort-temperature: 75.0 °C
36+
resistance-offset: 0.85 Ω
37+
- abort-temperature: 85.0 °C
38+
resistance-offset: 1.042 Ω
39+
- 80.0 °C
40+
- disabled
41+
42+
contactors:
43+
- with-feedback-normally-open
44+
- disabled
45+
- disabled
46+
47+
estops:
48+
- active-low
49+
- disabled
50+
- disabled
51+
52+
.. important::
53+
54+
The YAML file is required to be encoded in UTF-8. While most parameters are ASCII only, temperature thresholds require
55+
trailing `°C` suffix which has a special UTF-8 encoding sequence. This might be displayed incorrectly in the editor
56+
when editing on the device itself and/or finally stored wrong in the YAML file.
57+
The same applies to the resistance offsets in Ohm.
58+
When unsure, adapt/create the YAML file on your Linux host system with your preferred editor and transfer it
59+
to the board via Ethernet network (e.g. SCP/SFTP).
60+
61+
Such a YAML file must be converted to a binary parameter block file afterwards. And this binary parameter block file
62+
must finally be flashed to the safety controller's flash memory, see below.
63+
64+
.. important::
65+
66+
The YAML file allows to specify a numeric parameter block version. This version is used internally by the
67+
safety controller firmware to detect the binary structure of the parameter block. It must thus match the
68+
safety firmware's expectation, otherwise the safety controller will refuse to work and enters safe state directly.
69+
70+
71+
Temperature Channel (PT1000) Configuration
72+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
73+
74+
The safety controller supports up to 4 PT1000 temperature channels. Thus the YAML file expects for each channel
75+
a temperature threshold in °C at which the safety controller stops and/or prevents charging. Also for each channel,
76+
an offset value in Ohm can be specified. This offset depends on the actual physical wiring and must be determined
77+
in the specific customer setup.
78+
If a PT1000 channel is not wired/used, it is required to disable this channel using the special word `disabled`
79+
instead of a temperature value.
80+
The example YAML file above shows that the PT1000 configuration is an array with up to 4 items. Each item can either
81+
be a single temperature threshold, the special token `disabled` or it is a key-value list. Valid keys are
82+
`abort-temperature` and `resistance-offset`. If no `resistance-offset` is given, then it is assumed to be zero.
83+
84+
The accepted value range for `abort-temperature` is -80.0 °C to 200.0 °C and it is stored with one decimal digit.
85+
86+
The range for `resistance-offset` is -32.0 Ω ... 32.0 Ω and these values are stored with three decimal digits internally.
87+
88+
89+
Contactor and Contactor Feedback Configuration
90+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
91+
92+
On Charge Control Y, the high-voltage contactors are not controlled directly by the safety controller firmware.
93+
Please do not modify the shipped factory settings as there are board revision specific differences.
94+
95+
96+
Emergency Input Configuration
97+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98+
99+
The safety controller can monitor up to 3 emergency inputs, however on Charge Control Y only one physical
100+
emergency input is available. So the second and third inputs must kept disabled.
101+
102+
Possible configuration values for the first one are:
103+
104+
- `disabled`
105+
- `active-low`
106+
107+
108+
Installing a Parameter Block
109+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
110+
111+
Once the YAML file is created and fits your charger setup, it is required to convert it to a binary parameter block file.
112+
In the mentioned repository, there exists a tool `ra-pb-create` to generate such a binary file from the YAML file.
113+
The following session transcript shows how the install procedure works:
114+
115+
.. code-block:: sh
116+
117+
# create a YAML file on-the-fly
118+
$ cat <<EOL > /tmp/my-parameters.yaml
119+
version: 1
120+
pt1000s:
121+
- abort-temperature: 75.0 °C
122+
resistance-offset: 0.85 Ω
123+
- abort-temperature: 85.0 °C
124+
resistance-offset: 1.042 Ω
125+
- 80.0 °C
126+
- disabled
127+
128+
contactors:
129+
- with-feedback-normally-open
130+
- disabled
131+
- disabled
132+
133+
estops:
134+
- active-low
135+
- disabled
136+
- disabled
137+
EOL
138+
139+
# convert YAML to binary
140+
ra-pb-create -i /tmp/my-parameters.yaml -o /tmp/my-parameters.bin
141+
142+
# stop EVerest - to have exclusive access to safety controller
143+
systemctl stop everest
144+
145+
# flash the parameter block
146+
ra-update -a data flash /tmp/my-parameters.bin
147+
148+
# restart EVerest
149+
systemctl start everest
150+
151+
152+
Checking the Installed Parameter Block
153+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
154+
155+
To check which settings are currently used by the safety controller firmware, it is possible to read back the parameter block.
156+
157+
.. code-block:: sh
158+
159+
systemctrl stop everest
160+
ra-update -a data dump | ra-pb-dump
161+
162+
This will print the current settings in YAML format on stdout.

0 commit comments

Comments
 (0)