Skip to content

Commit c63b5bb

Browse files
mheimhei
authored
Merge pull request #76 from chargebyte/everest/charge_som-new-safety-fw
Charge SOM: update DBC and add Safety Controller Parameterization
2 parents 8751f06 + c00a511 commit c63b5bb

4 files changed

Lines changed: 322 additions & 190 deletions

File tree

‎docs/source/_static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg‎

Lines changed: 4 additions & 0 deletions
Loading

‎docs/source/safety_controller_parameterization.rst‎

Lines changed: 60 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,21 @@ To make the handling of parameters human-friendly, all parameters can be put tog
3232

3333
.. code-block:: yaml
3434
35+
version: 1
3536
pt1000s:
36-
- 75.0 °C
37-
- 85.0 °C
38-
- disabled
37+
- abort-temperature: 75.0 °C
38+
resistance-offset: 0.85 Ω
39+
- abort-temperature: 85.0 °C
40+
resistance-offset: 1.042 Ω
41+
- 80.0 °C
3942
- disabled
4043
4144
contactors:
45+
- type: without-feedback
46+
close-time: 100 ms
47+
open-time: 100 ms
4248
- without-feedback
43-
- without-feedback
49+
- disabled
4450
4551
estops:
4652
- active-low
@@ -52,35 +58,71 @@ To make the handling of parameters human-friendly, all parameters can be put tog
5258
The YAML file is required to be encoded in UTF-8. While most parameters are ASCII only, temperature thresholds require
5359
trailing `°C` suffix which has a special UTF-8 encoding sequence. This might be displayed incorrectly in the editor
5460
when editing on the device itself and/or finally stored wrong in the YAML file.
61+
The same applies to the resistance offsets in Ohm.
5562
When unsure, adapt/create the YAML file on your Linux host system with your preferred editor and transfer it
5663
to the board via Ethernet network (e.g. SCP/SFTP).
5764

5865
Such a YAML file must be converted to a binary parameter block file afterwards. And this binary parameter block file
5966
must finally be flashed to the safety controller's flash memory, see below.
6067

68+
.. important::
69+
70+
The YAML file allows to specify a numeric parameter block version. This version is used internally by the
71+
safety controller firmware to detect the binary structure of the parameter block. It must thus match the
72+
safety firmware's expectation, otherwise the safety controller will refuse to work and enters safe state directly.
73+
6174

6275
Temperature Channel (PT1000) Configuration
6376
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6477

6578
The safety controller supports up to 4 PT1000 temperature channels. Thus the YAML file expects for each channel
66-
either a temperature threshold in °C at which the safety controller stops and/or prevents charging.
67-
In a PT1000 channel is not wired/used, it is required to disable this channel using the special word `disabled`
79+
a temperature threshold in °C at which the safety controller stops and/or prevents charging. Also for each channel,
80+
an offset value in Ohm can be specified. This offset depends on the actual physical wiring and must be determined
81+
in the specific customer setup.
82+
If a PT1000 channel is not wired/used, it is required to disable this channel using the special word `disabled`
6883
instead of a temperature value.
84+
The example YAML file above shows that the PT1000 configuration is an array with up to 4 items. Each item can either
85+
be a single temperature threshold, the special token `disabled` or it is a key-value list. Valid keys are
86+
`abort-temperature` and `resistance-offset`. If no `resistance-offset` is given, then it is assumed to be zero.
87+
88+
The accepted value range for `abort-temperature` is -80.0 °C to 200.0 °C and it is stored with one decimal digit.
89+
90+
The range for `resistance-offset` is -32.0 Ω ... 32.0 Ω and these values are stored with three decimal digits internally.
6991

7092

7193
Contactor and Contactor Feedback Configuration
7294
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7395

74-
The safety controller allows to control up to 2 high-voltage contactors and can monitor corresponding mirror contacts.
75-
The mirror contacts need to have `Normally Closed` semantic. In the YAML parameterization, it is possible to
76-
specify whether the safety controller should actually switch the corresponding output pin and whether to monitor
77-
the feedback input pins.
96+
The safety controller allows to control up to 3 high-voltage contactors and can monitor corresponding feedback contacts.
97+
The feedback contacts support `Normally Closed` and `Normally Open` semantic, but customer must follow chargebyte's
98+
Charge SOM's EVB reference design otherwise the logic might be inverted.
99+
100+
.. figure:: _static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg
101+
:width: 800px
102+
103+
Simplified Reference Circuit used on Charge SOM's EVB for Contactor Feedback Signal
104+
105+
In the YAML parameterization, it is possible to specify whether the safety controller should actually switch the
106+
corresponding output pin and whether to monitor the feedback input pins. When using the feedback, it is also
107+
required to specify the opening and closing times of the used contactor. These times are expected in milliseconds and
108+
used by the safety firmware to check after the given time whether the feedback pin has the expected level. If the level
109+
differs from the expectation, then the safety firmware assumes a malfunction and thus enters safe state.
78110

79-
Possible parameter values are:
111+
The example YAML file above shows all allowed variants how to parameterize a contactor.
112+
Possible values for the `type` are:
80113

81114
- `disabled`
82115
- `without-feedback`
83-
- `with-feedback`
116+
- `with-feedback-normally-open`
117+
- `with-feedback-normally-closed`
118+
119+
Since the open/close timings make no sense in case of `disabled` or `without-feedback`, it is possible to use these
120+
tokens directly as array item (actually, it is also possible to use the `with-feedback...` ones, but then the timings
121+
are considered zero which will result in an error due to the physical latency in the contactor).
122+
123+
Both `close-time` and `open-time` accept integer values in the range 10 to 2550 ms. Internally, the
124+
safety controller operates with time slots of 10 ms, so the last digit of the given integer is just discarded.
125+
(In other words, the given integer is integer-divided by 10 before it is stored in the parameter block.)
84126

85127

86128
Emergency Input Configuration
@@ -105,15 +147,19 @@ The following session transcript shows how the install procedure works:
105147
106148
# create a YAML file on-the-fly
107149
$ cat <<EOL > /tmp/my-parameters.yaml
150+
version: 1
108151
pt1000s:
109-
- 75.0 °C
110-
- 85.0 °C
152+
- abort-temperature: 85.0 °C
153+
resistance-offset: 0.85 Ω
154+
- abort-temperature: 75.0 °C
155+
resistance-offset: 1.1 Ω
111156
- disabled
112157
- disabled
113158
114159
contactors:
115160
- without-feedback
116161
- without-feedback
162+
- disabled
117163
118164
estops:
119165
- active-low

‎docs/source/safety_protocol.rst‎

Lines changed: 95 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ChargeControl1
77

88
**Description**: This message shall be sent from the host processor to the safety controller to control the peripherals connected to the safety controller.
99

10-
**Senders**: Default_HostController
10+
**Senders**: chargeSOM_HostController
1111

1212
.. list-table:: Signals in ChargeControl1
1313
:widths: 30 6 6 10 7 7 7 6 30
@@ -58,6 +58,15 @@ ChargeControl1
5858
- 0
5959
-
6060
- Request to close the contactor state. A value of 0 means open contactor, a value of 1 means closed contactor. The contactors are only closed if the system has no errors and is in state C.
61+
* - CC_Contactor3State
62+
- 18
63+
- 1
64+
-
65+
- No
66+
- 1
67+
- 0
68+
-
69+
- Request to close the contactor state. A value of 0 means open contactor, a value of 1 means closed contactor. The contactors are only closed if the system has no errors and is in state C.
6170

6271
**Bitfield Layout**
6372

@@ -70,7 +79,7 @@ ChargeControl1
7079
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
7180
1| | | | | | | | |
7281
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
73-
2| | | | | | | CC_Contactor2State | CC_Contactor1State |
82+
2| | | | | | CC_Contactor3State | CC_Contactor2State | CC_Contactor1State |
7483
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
7584
3| | | | | | | | |
7685
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
@@ -92,7 +101,7 @@ ChargeState1
92101

93102
**Description**: This message shall be sent from safety controller to host processor for indicating the state of the charging session as well as the state of connected peripherals.
94103

95-
**Senders**: Safety Controller
104+
**Senders**: chargeSOM_SafetyController
96105

97106
.. list-table:: Signals in ChargeState1
98107
:widths: 30 6 6 10 7 7 7 6 30
@@ -116,6 +125,15 @@ ChargeState1
116125
- 0
117126
- %
118127
- The current duty cycle between 0.0% and 100.0%. If the PWM is not aczive this signal is 0
128+
* - CS_SafeStateActive
129+
- 3
130+
- 2
131+
-
132+
- No
133+
- 1
134+
- 0
135+
-
136+
- This signal reports, if the controller is in safeState or not.
119137
* - CS_PWM_Active
120138
- 7
121139
- 1
@@ -169,34 +187,25 @@ ChargeState1
169187
- 1
170188
- 0
171189
-
172-
- Is set when the contactor is closed
173-
* - CS_Contactor1Error
174-
- 34
175-
- 1
176-
-
177-
- No
178-
- 1
179-
- 0
180-
-
181-
- Is set when an error in the contactor is detected
190+
- State of contactor 1
182191
* - CS_Contactor2State
183-
- 36
192+
- 35
184193
- 2
185194
-
186195
- No
187196
- 1
188197
- 0
189198
-
190-
- Is set when the contactor is closed
191-
* - CS_Contactor2Error
199+
- State of contactor 2
200+
* - CS_Contactor3State
192201
- 37
193-
- 1
202+
- 2
194203
-
195204
- No
196205
- 1
197206
- 0
198207
-
199-
- Is set when an error in the contactor is detected
208+
- State of contactor 3
200209
* - CS_HV_Ready
201210
- 38
202211
- 1
@@ -233,9 +242,24 @@ ChargeState1
233242
- 0
234243
-
235244
- *No description available*
245+
* - CS_SafeStateReason
246+
- 55
247+
- 8
248+
-
249+
- No
250+
- 1
251+
- 0
252+
-
253+
- This signal describes in which module a fault was detected, why the controller went into safeState
236254

237255
**Value Descriptions**
238256

257+
- **CS_SafeStateActive**
258+
259+
- 0x0 = NormalState
260+
- 0x1 = SafeState
261+
- 0x3 = SNA
262+
239263
- **CS_CurrentCpState**
240264

241265
- 0x0 = Unknown
@@ -260,14 +284,23 @@ ChargeState1
260284

261285
- **CS_Contactor1State**
262286

263-
- 0x0 = OPEN
264-
- 0x1 = CLOSE
287+
- 0x0 = UNDEFINED
288+
- 0x1 = OPEN
289+
- 0x2 = CLOSE
265290
- 0x3 = NotConfigured
266291

267292
- **CS_Contactor2State**
268293

269-
- 0x0 = OPEN
270-
- 0x1 = CLOSE
294+
- 0x0 = UNDEFINED
295+
- 0x1 = OPEN
296+
- 0x2 = CLOSE
297+
- 0x3 = NotConfigured
298+
299+
- **CS_Contactor3State**
300+
301+
- 0x0 = UNDEFINED
302+
- 0x1 = OPEN
303+
- 0x2 = CLOSE
271304
- 0x3 = NotConfigured
272305

273306
- **CS_Estop1ChargingAbort**
@@ -288,26 +321,48 @@ ChargeState1
288321
- 0x1 = TRUE
289322
- 0x3 = NotConfigured
290323

324+
- **CS_SafeStateReason**
325+
326+
- 0x0 = NoStop
327+
- 0x1 = InternalError
328+
- 0x2 = ComTimeout
329+
- 0x3 = Temp1_Malfunction
330+
- 0x4 = Temp2_Malfunction
331+
- 0x5 = Temp3_Malfunction
332+
- 0x6 = Temp4_Malfunction
333+
- 0x7 = Temp1_Overtemp
334+
- 0x8 = Temp2_Overtemp
335+
- 0x9 = Temp3_Overtemp
336+
- 0xA = Temp4_Overtemp
337+
- 0xB = PP_Malfunction
338+
- 0xC = CP_Malfunction
339+
- 0xD = CP_ShortCircuit
340+
- 0xE = CP_DiodeFault
341+
- 0xF = HVSW_Malfunction
342+
- 0x10 = EmergencyInput1
343+
- 0x11 = EmergencyInput2
344+
- 0x12 = EmergencyInput3
345+
291346
**Bitfield Layout**
292347

293348
::
294349

295350
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
296351
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
297352
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
298-
0| CS_PWM_Active | | | | | |CS_CurrentDutyCycle | |
353+
0| CS_PWM_Active | | | | CS_SafeStateActive | |CS_CurrentDutyCycle | |
299354
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
300355
1| | | | | | | | |
301356
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
302357
2| | | | CS_DiodeFault | CS_CpShortCircuit | CS_CurrentCpState | | |
303358
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
304359
3| | | | | | CS_CurrentPpState | | |
305360
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
306-
4| | CS_HV_Ready | CS_Contactor2Error | CS_Contactor2State | | CS_Contactor1Error | CS_Contactor1State | |
361+
4| | CS_HV_Ready | CS_Contactor3State | | CS_Contactor2State | | CS_Contactor1State | |
307362
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
308363
5| | |CS_Estop3ChargingAbo| |CS_Estop2ChargingAbo| |CS_Estop1ChargingAbo| |
309364
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
310-
6| | | | | | | | |
365+
6| CS_SafeStateReason | | | | | | | |
311366
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
312367
7| | | | | | | | |
313368
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
@@ -321,7 +376,7 @@ PT1000State
321376

322377
**Description**: This message shall be sent from safety controller to host processor for indicating the state of the connected temperature sensors
323378

324-
**Senders**: Safety Controller
379+
**Senders**: chargeSOM_SafetyController
325380

326381
.. list-table:: Signals in PT1000State
327382
:widths: 30 6 6 10 7 7 7 6 30
@@ -496,7 +551,7 @@ FirmwareVersion
496551

497552
**Description**: This message provides information about the type and version of the flashed firmware
498553

499-
**Senders**: Safety Controller
554+
**Senders**: chargeSOM_SafetyController
500555

501556
.. list-table:: Signals in FirmwareVersion
502557
:widths: 30 6 6 10 7 7 7 6 30
@@ -556,6 +611,15 @@ FirmwareVersion
556611
- 0
557612
-
558613
- The type of firmware. See possible values below
614+
* - ParameterVersion
615+
- 47
616+
- 16
617+
- Big Endian
618+
- No
619+
- 1
620+
- 0
621+
-
622+
- Version of the parameter file
559623

560624
**Value Descriptions**
561625

@@ -585,9 +649,9 @@ FirmwareVersion
585649
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
586650
3| PlatformType | | | | | | | |
587651
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
588-
4| ApplicationType | | | | | | | |
652+
4| ParameterVersion | | | | | | | |
589653
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
590-
5| | | | | | | | |
654+
5| ParameterVersion | | | | | | | |
591655
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
592656
6| | | | | | | | |
593657
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
@@ -603,7 +667,7 @@ GitHash
603667

604668
**Description**: This message provides information about the GIT hash, written in the firmware
605669

606-
**Senders**: Safety Controller
670+
**Senders**: chargeSOM_SafetyController
607671

608672
.. list-table:: Signals in GitHash
609673
:widths: 30 6 6 10 7 7 7 6 30
@@ -661,7 +725,7 @@ InquiryPacket
661725

662726
**Description**: This packet is used to request a special message from the safety controller
663727

664-
**Senders**: Default_HostController, CCY_HostController
728+
**Senders**: chargeSOM_HostController, CCY_HostController
665729

666730
.. list-table:: Signals in InquiryPacket
667731
:widths: 30 6 6 10 7 7 7 6 30

0 commit comments

Comments
 (0)