Skip to content

Charge SOM: update DBC and add Safety Controller Parameterization #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mhei merged 4 commits into from
Nov 4, 2025
Merged

Charge SOM: update DBC and add Safety Controller Parameterization #76

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2439852
Update DBC and generated UART frame documentation
mhei Oct 30, 2025
aa72c93
Adapt parameter block documentation to safety fw v0.2.6
mhei Oct 30, 2025
9b7d3a0
Add reference/example circuit for contactor feedback signal
mhei Nov 3, 2025
c00a511
Reword the feedback open/close time description
mhei Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/source/_static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
74 changes: 60 additions & 14 deletions docs/source/safety_controller_parameterization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _safety_controller_parameterization.rst:

Safety Controller Parameterization
----------------------------------

Check warning on line 4 in docs/source/safety_controller_parameterization.rst

View workflow job for this annotation

GitHub Actions / build 

duplicate label safety_controller_parameterization.rst, other instance in /github/workspace/docs/source/safety_controller.rst


Overview
Expand Down Expand Up @@ -32,15 +32,21 @@

.. 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
Expand All @@ -52,35 +58,71 @@
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 feedback contacts.
The feedback 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.

.. figure:: _static/images/charge_som_contactor_feedback_evb-circuit.drawio.svg
:width: 800px

Simplified Reference Circuit used on Charge SOM's EVB for Contactor Feedback Signal

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 also
required to specify the opening 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 the expected level. If the level
differs from the expectation, then the 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 which will result in an error due to the physical latency in the contactor).

Both `close-time` and `open-time` accept integer values in the range 10 to 2550 ms. Internally, the
safety controller operates with time slots of 10 ms, so the last digit of the given integer is just discarded.
(In other words, the given integer is integer-divided by 10 before it is stored in the parameter block.)


Emergency Input Configuration
Expand All @@ -105,15 +147,19 @@

# 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
Expand Down
126 changes: 95 additions & 31 deletions docs/source/safety_protocol.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ ChargeControl1

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

**Senders**: Default_HostController
**Senders**: chargeSOM_HostController

.. list-table:: Signals in ChargeControl1
:widths: 30 6 6 10 7 7 7 6 30
Expand Down Expand Up @@ -58,6 +58,15 @@ ChargeControl1
- 0
-
- 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.
* - CC_Contactor3State
- 18
- 1
-
- No
- 1
- 0
-
- 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.

**Bitfield Layout**

Expand All @@ -70,7 +79,7 @@ ChargeControl1
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
1| | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
2| | | | | | | CC_Contactor2State | CC_Contactor1State |
2| | | | | | CC_Contactor3State | CC_Contactor2State | CC_Contactor1State |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
3| | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
Expand All @@ -92,7 +101,7 @@ ChargeState1

**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.

**Senders**: Safety Controller
**Senders**: chargeSOM_SafetyController

.. list-table:: Signals in ChargeState1
:widths: 30 6 6 10 7 7 7 6 30
Expand All @@ -116,6 +125,15 @@ ChargeState1
- 0
- %
- The current duty cycle between 0.0% and 100.0%. If the PWM is not aczive this signal is 0
* - CS_SafeStateActive
- 3
- 2
-
- No
- 1
- 0
-
- This signal reports, if the controller is in safeState or not.
* - CS_PWM_Active
- 7
- 1
Expand Down Expand Up @@ -169,34 +187,25 @@ ChargeState1
- 1
- 0
-
- Is set when the contactor is closed
* - CS_Contactor1Error
- 34
- 1
-
- No
- 1
- 0
-
- Is set when an error in the contactor is detected
- State of contactor 1
* - CS_Contactor2State
- 36
- 35
- 2
-
- No
- 1
- 0
-
- Is set when the contactor is closed
* - CS_Contactor2Error
- State of contactor 2
* - CS_Contactor3State
- 37
- 1
- 2
-
- No
- 1
- 0
-
- Is set when an error in the contactor is detected
- State of contactor 3
* - CS_HV_Ready
- 38
- 1
Expand Down Expand Up @@ -233,9 +242,24 @@ ChargeState1
- 0
-
- *No description available*
* - CS_SafeStateReason
- 55
- 8
-
- No
- 1
- 0
-
- This signal describes in which module a fault was detected, why the controller went into safeState

**Value Descriptions**

- **CS_SafeStateActive**

- 0x0 = NormalState
- 0x1 = SafeState
- 0x3 = SNA
Copy link
Member

@lategoodbye lategoodbye Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does it mean?

Copy link
Member Author

@mhei mhei Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SignalNotAvailable


- **CS_CurrentCpState**

- 0x0 = Unknown
Expand All @@ -260,14 +284,23 @@ ChargeState1

- **CS_Contactor1State**

- 0x0 = OPEN
- 0x1 = CLOSE
- 0x0 = UNDEFINED
- 0x1 = OPEN
- 0x2 = CLOSE
- 0x3 = NotConfigured

- **CS_Contactor2State**

- 0x0 = OPEN
- 0x1 = CLOSE
- 0x0 = UNDEFINED
- 0x1 = OPEN
- 0x2 = CLOSE
- 0x3 = NotConfigured

- **CS_Contactor3State**

- 0x0 = UNDEFINED
- 0x1 = OPEN
- 0x2 = CLOSE
- 0x3 = NotConfigured

- **CS_Estop1ChargingAbort**
Expand All @@ -288,26 +321,48 @@ ChargeState1
- 0x1 = TRUE
- 0x3 = NotConfigured

- **CS_SafeStateReason**

- 0x0 = NoStop
- 0x1 = InternalError
- 0x2 = ComTimeout
- 0x3 = Temp1_Malfunction
- 0x4 = Temp2_Malfunction
- 0x5 = Temp3_Malfunction
- 0x6 = Temp4_Malfunction
- 0x7 = Temp1_Overtemp
- 0x8 = Temp2_Overtemp
- 0x9 = Temp3_Overtemp
- 0xA = Temp4_Overtemp
- 0xB = PP_Malfunction
- 0xC = CP_Malfunction
- 0xD = CP_ShortCircuit
- 0xE = CP_DiodeFault
- 0xF = HVSW_Malfunction
- 0x10 = EmergencyInput1
- 0x11 = EmergencyInput2
- 0x12 = EmergencyInput3

**Bitfield Layout**

::

+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
0| CS_PWM_Active | | | | | |CS_CurrentDutyCycle | |
0| CS_PWM_Active | | | | CS_SafeStateActive | |CS_CurrentDutyCycle | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
1| | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
2| | | | CS_DiodeFault | CS_CpShortCircuit | CS_CurrentCpState | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
3| | | | | | CS_CurrentPpState | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
4| | CS_HV_Ready | CS_Contactor2Error | CS_Contactor2State | | CS_Contactor1Error | CS_Contactor1State | |
4| | CS_HV_Ready | CS_Contactor3State | | CS_Contactor2State | | CS_Contactor1State | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
5| | |CS_Estop3ChargingAbo| |CS_Estop2ChargingAbo| |CS_Estop1ChargingAbo| |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
6| | | | | | | | |
6| CS_SafeStateReason | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
7| | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
Expand All @@ -321,7 +376,7 @@ PT1000State

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

**Senders**: Safety Controller
**Senders**: chargeSOM_SafetyController

.. list-table:: Signals in PT1000State
:widths: 30 6 6 10 7 7 7 6 30
Expand Down Expand Up @@ -496,7 +551,7 @@ FirmwareVersion

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

**Senders**: Safety Controller
**Senders**: chargeSOM_SafetyController

.. list-table:: Signals in FirmwareVersion
:widths: 30 6 6 10 7 7 7 6 30
Expand Down Expand Up @@ -556,6 +611,15 @@ FirmwareVersion
- 0
-
- The type of firmware. See possible values below
* - ParameterVersion
- 47
- 16
- Big Endian
- No
- 1
- 0
-
- Version of the parameter file

**Value Descriptions**

Expand Down Expand Up @@ -585,9 +649,9 @@ FirmwareVersion
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
3| PlatformType | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
4| ApplicationType | | | | | | | |
4| ParameterVersion | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
5| | | | | | | | |
5| ParameterVersion | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
6| | | | | | | | |
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
Expand All @@ -603,7 +667,7 @@ GitHash

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

**Senders**: Safety Controller
**Senders**: chargeSOM_SafetyController

.. list-table:: Signals in GitHash
:widths: 30 6 6 10 7 7 7 6 30
Expand Down Expand Up @@ -661,7 +725,7 @@ InquiryPacket

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

**Senders**: Default_HostController, CCY_HostController
**Senders**: chargeSOM_HostController, CCY_HostController

.. list-table:: Signals in InquiryPacket
:widths: 30 6 6 10 7 7 7 6 30
Expand Down
Loading
Loading