Skip to content

Commit b4ca6c8

Browse files
mheimhei
committed
Restructure doc tree, factor out safety controller stuff
Signed-off-by: Michael Heimpold <michael.heimpold@chargebyte.com>
1 parent 53bd9e2 commit b4ca6c8

9 files changed

Lines changed: 209 additions & 178 deletions

‎docs/source/everest_bsp.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. _everest_bsp.rst:
2+
3+
EVerest Board Support Package Module
4+
------------------------------------
5+
6+
chargebyte developed a comprehensive hardware abstraction module (HAL, or also called BSP module - board support package)
7+
for EVerest charging stack to support the Charge SOM platform. The module is called ``CbChargeSOMDriver`` and is
8+
available in chargebyte's public EVerest repository as open-source code:
9+
https://github.com/chargebyte/everest-chargebyte/tree/main/modules/CbChargeSOMDriver
10+
11+
This module already implements the required communication protocol to interact with the safety controller.
12+
13+
All Charge SOM boards ship with a Linux system preinstalled on eMMC, which also includes EVerest, the mentioned
14+
BSP module and example configuration files.

‎docs/source/firmware.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55

66
Partitioning
7-
-------------
7+
------------
88

99
The internal eMMC storage of a chargebyte device is divided into several partitions to support two independent systems: system A and system B. This setup enables firmware updates to run in the background while the device continues normal charging operations. Once the update is complete, the system can switch to the updated version with a reboot of the device. Additionally, this approach supports a rollback mechanism in case of update failures. In other words, during a firmware update, the active root file system switches from A to B (or vice versa), leaving the other partition available for rollback if needed.
1010

‎docs/source/getting_started.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,9 @@ Hardware Overview
3030
The following figure shows the basic setup of the DC charger with the Charge SOM Evaluation Kit:
3131

3232
.. figure:: _static/images/dc_charger_charge_som_setup.svg
33-
:width: 900pt
33+
:width: 900pt
3434

35-
Figure: Basic Setup of the DC charger with the Charge SOM
35+
Basic Setup of the DC charger with the Charge SOM
3636

3737
.. note::
3838
The pin assignment of the Charge SOM Evaluation Kit can be found in the datasheet.
@@ -128,10 +128,10 @@ other over the interfaces. The following figure illustrates how the EVerest modu
128128
to each other:
129129

130130
.. figure:: _static/images/admin_panel_bsp_only.png
131-
:width: 600pt
132-
:name: admin_panel_bsp_only
131+
:width: 600pt
132+
:name: admin_panel_bsp_only
133133

134-
Figure: EVerest admin panel view of the bsp-only-dc.yaml configuration
134+
EVerest admin panel view of the bsp-only-dc.yaml configuration
135135

136136
However, not all configuration parameters of the modules are shown here. Only the configuration
137137
parameters that do not match the default configuration of the respective module need

‎docs/source/hardware.rst‎

Lines changed: 9 additions & 164 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. hardware.rst:
1+
.. _hardware.rst:
22

33
########
44
Hardware
@@ -13,9 +13,9 @@ Wiring Overview
1313
***************
1414

1515
.. figure:: _static/images/charge_som_hw_wiring_diagram.svg
16-
:width: 1000pt
16+
:width: 1000pt
1717

18-
Figure: Wiring Overview Diagram for Charge SOM EVB
18+
Wiring Overview Diagram for Charge SOM EVB
1919

2020
This wiring diagram shows an overview of all components which are required at minimum
2121
to build a DC charging station:
@@ -43,9 +43,9 @@ The X19 connector provides signals to switch the high-voltage contactors,
4343
but also for the corresponding feedback signals to detect contactor welding.
4444

4545
.. figure:: _static/images/charge_som_contactor_wiring.drawio.svg
46-
:width: 1000pt
46+
:width: 1000pt
4747

48-
Figure: Recommended Contactor Wiring
48+
Recommended Contactor Wiring
4949

5050
.. note::
5151
The precharge contactor might not be necessary in your setup.
@@ -63,171 +63,16 @@ via RS-485 bus to provide the insulation resistance values which are required
6363
by EVerest's IMD interface.
6464

6565
.. figure:: _static/images/charge_som_wiring_bender_imd.drawio.svg
66-
:width: 1000pt
66+
:width: 1000pt
6767

68-
Figure: Wiring for Bender's IMD to Charge SOM EVB
68+
Wiring for Bender's IMD to Charge SOM EVB
6969

7070

71-
*****************
72-
Safety Controller
73-
*****************
74-
75-
Overview
76-
========
77-
78-
The Charge SOM platform is equipped with an additional MCU (aka Safety Controller) which is responsible for
79-
managing all low-level aspects which are critical for electrical safety. The firmware for this MCU is
80-
developed by chargebyte and is not open-source. The Charge SOM boards ship with the safety controller firmware
81-
preinstalled.
82-
83-
The host controller firmware, e.g. the Linux system, communicates with the safety controller using an UART.
84-
On Linux side, this is UART interface ``/dev/ttyLP2``. The communication with the safety controller firmware
85-
over this UART requires a proprietary protocol, see the following chapter. The required UART settings are listed
86-
in the following table.
87-
88-
+-----------------+-------------+
89-
| Setting | Value |
90-
+=================+=============+
91-
| Linux Interface | /dev/ttyLP2 |
92-
+-----------------+-------------+
93-
| Baudrate | 115200 |
94-
+-----------------+-------------+
95-
| Databits | 8 |
96-
+-----------------+-------------+
97-
| Parity | none |
98-
+-----------------+-------------+
99-
| Stopbits | 1 |
100-
+-----------------+-------------+
101-
102-
System Architecture
103-
===================
104-
.. figure:: _static/images/system_architecture.svg
105-
:width: 1000pt
106-
107-
Figure: Simplified system architecture for the safety controller on the chargeSOM
108-
109-
The safety controller manages the Control Pilot (CP) line, acting as a critical interface for monitoring and controlling the high-voltage (HV) system in accordance with EV safety standards. Its core function is to **enforce safe operating states** based on system diagnostics and environmental conditions.
110-
111-
Fault Detection & Safety Response
112-
---------------------------------
113-
114-
When an error is detected—such as a fault in the system, a triggered emergency input, or a thermal violation—the controller transitions to **State F**, a fail-safe state that prevents further system operation to protect both the hardware and the user.
115-
116-
HV Ready Enablement
117-
-------------------
118-
119-
The controller verifies that **no system errors are present** and that the CP line is in **State C**. Only under these safe conditions does it enable the HV Ready signal, which may be used to energize the HV interlock or permit charging/operation.
120-
121-
Emergency Inputs
122-
----------------------------------
123-
124-
The simplified system architecture shows only one emergency input. In the real system, there are 3 independent emergency input signals available: SAFETY_ESTOP1, SAFETY_ESTOP2 and SAFETY_ESTOP3. The inputs are active low. This means an emergency stop needs to pull the input to Gnd. The emergency inputs can be parameterized out.
125-
126-
127-
Temperature Monitoring
128-
----------------------------------
129-
130-
The simplified system architecture shows only one temperature input. In the real system, there are 4 independent temperature measurement circuits for PT1000 sensors. The safety software monitors the temperature circuit for hardware errors and for overtemperaure. The temperature threshold can be parameterized.
131-
132-
HV Connector Control
133-
--------------------
134-
135-
If State C is confirmed and all safety criteria are met, the controller is also capable of closing HV connectors to complete the high-voltage path. Therefore it enables the 2 connectors SAFETY_HVSW1_HS and SAFETY_HVSW2_HS under the condition that State C is detected, the system is HV-ready and the host processor commands to close the contactors.
136-
137-
138-
Reset Behaviour and Controller states
139-
=====================================
140-
The safety controller starts in an initialization state, to give the peripherals time to reach an defined state. It leaves the initialization state to a running state, after the reception of the first UART message from the host. Only periodic messages leaves the init state. With the reception of inquiriy messages, the safety controller stays in initialization. This gives the option to fetch version information in an init state. In running state, it monitors the peripherals and sends out UART messages. If any error occurs, the system goes into safe state. This state can only be left by a reset.
141-
142-
.. figure:: _static/images/safety_controller_states.svg
143-
:width: 1000pt
144-
145-
146-
147-
Safety Controller Communication Protocol
148-
========================================
149-
150-
Packet format descriptions
151-
--------------------------
152-
153-
Data packet format
154-
155-
Data packets contain payload and can be sent out from host to safety controller or vice versa. Data packets from safety controller to host can be transmitted periodically or by request via an inquiry packet. Only one inquiry packet can be requested before requesting the next one.
156-
157-
+--------+--------+--------+-------------------+
158-
| Symbol | Size | Code | Description |
159-
+========+========+========+===================+
160-
| SOF | 1 byte | 0xA5 | Start of frame |
161-
+--------+--------+--------+-------------------+
162-
| ID | 1 byte | | Packet Identifier |
163-
+--------+--------+--------+-------------------+
164-
| Data | 8 byte | | Payload |
165-
+--------+--------+--------+-------------------+
166-
| CRC | 1 byte | | CRC checksum |
167-
+--------+--------+--------+-------------------+
168-
| EOF | 1 byte | 0x03 | End of frame |
169-
+--------+--------+--------+-------------------+
170-
171-
172-
Packet Identifier (ID)
173-
----------------------
174-
175-
The values of the packet identifier (PacketId) are mapped to the messages as summarized below.
176-
177-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
178-
| PacketId | Description | Communication Dir. | Periodicity | Triggered by Inquiry |
179-
+==========+===========================+=====================+=============================================================+======================+
180-
| 0x06 | Charge Control | Host → Safety | periodically, every 100ms OR immediately if changes occur | No |
181-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
182-
| 0x07 | Charge State | Safety → Host | periodically, every 100ms | No |
183-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
184-
| 0x08 | PT1000 State | Safety → Host | periodically, every 100ms | No |
185-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
186-
| 0x0A | Firmware Version | Safety → Host | no, only upon request via inquiry packet | Yes |
187-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
188-
| 0x0B | GIT Hash | Safety → Host | no, only upon request via inquiry packet | Yes |
189-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
190-
| 0xFF | Inquiry packet | Host → Safety | no, only to trigger inquiries | No |
191-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
192-
193-
CRC checksum field
194-
------------------
195-
196-
The checksum is defined over:
197-
198-
::
199-
200-
Width = 8
201-
Poly = 0x1d
202-
XorIn = 0xff
203-
ReflectIn = False
204-
XorOut = 0xff
205-
ReflectOut = False
206-
Algorithm = table-driven
207-
Name = CRC8 SAE J1850
208-
209-
.. include:: safety_protocol.rst
210-
211-
212-
************************************
213-
EVerest Board Support Package Module
214-
************************************
215-
216-
chargebyte developed a comprehensive hardware abstraction module (HAL, or also called BSP module - board support package)
217-
for EVerest charging stack to support the Charge SOM platform. The module is called ``CbChargeSOMDriver`` and is
218-
available in chargebyte's public EVerest repository as open-source code:
219-
https://github.com/chargebyte/everest-chargebyte/tree/main/modules/CbChargeSOMDriver
220-
221-
This module already implements the required communication protocol to interact with the safety controller.
222-
223-
All Charge SOM boards ship with a Linux system preinstalled on eMMC, which also includes EVerest, the mentioned
224-
BSP module and example configuration files.
225-
22671
**************
227-
I2C interfaces
72+
I²C Interfaces
22873
**************
22974

230-
The i.MX93 on the Charge SOM provides several I2C interfaces:
75+
The i.MX93 on the Charge SOM provides several I²C interfaces:
23176

23277
+----------+------------+-------------------------------------+-----------------+
23378
| Hardware | Linux | Usage | Clock frequency |

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Charge SOM Evaluation Kit.
2222
getting_started
2323
peripheral_compat_list
2424
hardware
25+
safety_controller
2526
firmware
2627
everest_charging_stack
2728
cb_energy

‎docs/source/safety_controller.rst‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
.. _safety_controller.rst:
2+
3+
Safety Controller
4+
=================
5+
6+
7+
Overview
8+
--------
9+
10+
The Charge SOM platform is equipped with an additional MCU (aka Safety Controller) which is responsible for
11+
managing all low-level aspects which are critical for electrical safety. The firmware for this MCU is
12+
developed by chargebyte and is not open-source. The Charge SOM boards ship with the safety controller firmware
13+
preinstalled.
14+
15+
The host controller firmware, e.g. the Linux system, communicates with the safety controller using an UART.
16+
On Linux side, this is UART interface ``/dev/ttyLP2``. The communication with the safety controller firmware
17+
over this UART requires a proprietary protocol, see the following chapter. The required UART settings are listed
18+
in the following table.
19+
20+
+-----------------+-------------+
21+
| Setting | Value |
22+
+=================+=============+
23+
| Linux Interface | /dev/ttyLP2 |
24+
+-----------------+-------------+
25+
| Baudrate | 115200 |
26+
+-----------------+-------------+
27+
| Databits | 8 |
28+
+-----------------+-------------+
29+
| Parity | none |
30+
+-----------------+-------------+
31+
| Stopbits | 1 |
32+
+-----------------+-------------+
33+
34+
35+
System Architecture
36+
-------------------
37+
38+
.. figure:: _static/images/system_architecture.svg
39+
:width: 1000pt
40+
41+
Simplified System Architecture for the Safety Controller on the Charge SOM platform
42+
43+
The safety controller manages the Control Pilot (CP) line, acting as a critical interface for monitoring and
44+
controlling the high-voltage (HV) system in accordance with EV safety standards.
45+
Its core function is to **enforce safe operating states** based on system diagnostics and environmental conditions.
46+
47+
48+
Fault Detection & Safety Response
49+
---------------------------------
50+
51+
When an error is detected — such as a fault in the system, a triggered emergency input, or a thermal violation — the
52+
controller transitions to **State F**, a fail-safe state that prevents further system operation to protect both
53+
the hardware and the user.
54+
55+
56+
HV Ready Enablement
57+
-------------------
58+
59+
The controller verifies that **no system errors are present** and that the CP line is in **State C**.
60+
Only under these safe conditions it does enable the HV Ready signal, which may be used to energize the HV interlock or
61+
permit charging/operation.
62+
63+
64+
Emergency Inputs
65+
----------------
66+
67+
The simplified system architecture shows only one emergency input. In the real system, there are 3 independent
68+
emergency input signals available: SAFETY_ESTOP1, SAFETY_ESTOP2 and SAFETY_ESTOP3.
69+
The inputs are active low. This means an emergency stop needs to pull the input to Gnd.
70+
The emergency inputs can be parameterized out.
71+
72+
73+
Temperature Monitoring
74+
----------------------
75+
76+
The simplified system architecture shows only one temperature input. In the real system, there are 4 independent
77+
temperature measurement circuits for PT1000 sensors. The safety software monitors the temperature circuit for
78+
hardware errors and for overtemperaure. The temperature threshold can be parameterized.
79+
80+
81+
HV Contactor Control
82+
--------------------
83+
84+
If State C is confirmed and all safety criteria are met, the controller is also capable of closing HV connectors
85+
to complete the high-voltage path. Therefore it enables the 2 connectors SAFETY_HVSW1_HS and SAFETY_HVSW2_HS under
86+
the condition that State C is detected, the system is HV-ready and the host processor commands to close the contactors.
87+
88+
89+
Reset Behaviour and Controller States
90+
-------------------------------------
91+
92+
The safety controller starts in an initialization state, to give the peripherals time to reach a defined state.
93+
It leaves the initialization state to a running state, after the reception of the first UART message from the host.
94+
Only periodic messages leave the init state. With the reception of inquiry messages, the safety controller stays in
95+
initialization. This gives the option to fetch version information in the init state. In running state, it monitors the
96+
peripherals and sends out UART messages. If any error occurs, the system goes into safe state.
97+
This state can only be left by a reset.
98+
99+
.. figure:: _static/images/safety_controller_states.svg
100+
:width: 1000pt
101+
102+
.. include:: safety_controller_uart.rst
103+
104+
.. include:: everest_bsp.rst

0 commit comments

Comments
 (0)