Skip to content

Commit 2b28f91

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

9 files changed

Lines changed: 121 additions & 117 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 Control Y. The module is called ``CbParsleyDriver`` and is
8+
available in chargebyte's public EVerest repository as open-source code:
9+
https://github.com/chargebyte/everest-chargebyte/tree/main/modules/CbParsleyDriver
10+
11+
This module already implements the required communication protocol to interact with the safety controller.
12+
13+
All Charge Control Y 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: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ The following figure shows the basic setup of the MCS charger with the Charge Co
3333
.. figure:: _static/images/ccy_setup.svg
3434
:width: 900pt
3535

36-
Figure: Basic Setup of the MCS charger with Charge Control Y
36+
Basic Setup of the MCS charger with Charge Control Y
3737

3838

3939
First Startup
@@ -123,7 +123,7 @@ to each other:
123123
:width: 600pt
124124
:name: admin_panel_bsp_only
125125

126-
Figure: EVerest admin panel view of the bsp-only.yaml configuration
126+
EVerest admin panel view of the bsp-only.yaml configuration
127127

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

‎docs/source/hardware.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ IO
143143
- Ground (MCS)
144144

145145

146-
Wiring overview
146+
Wiring Overview
147147
---------------
148148

149149

@@ -153,7 +153,7 @@ PT1000 Temperature Sensors
153153
.. figure:: _static/images/wiring_temp_sensors.svg
154154
:width: 1000pt
155155

156-
Figure: Wiring overview for the PT1000 Temperature Sensors
156+
Wiring overview for the PT1000 Temperature Sensors
157157

158158
This wiring diagram shows an overview of connecting the temperature sensors to the Charge Control Y:
159159

@@ -168,9 +168,9 @@ Emergency Input
168168
^^^^^^^^^^^^^^^
169169

170170
.. figure:: _static/images/wiring_emergency_in.svg
171-
:width: 1000pt
171+
:width: 1000pt
172172

173-
Figure: Wiring overview for the emergency input
173+
Wiring overview for the Emergency Input
174174

175175
This wiring diagram shows an overview of connecting the emergeny input to the Charge Control Y:
176176

‎docs/source/introduction.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. introduction.rst:
1+
.. _introduction.rst:
22

33
Introduction
44
============
@@ -10,12 +10,12 @@ to fit your requirements best.
1010
.. figure:: _static/images/CCY_V0R4A_closed-case.png
1111
:width: 900pt
1212

13-
Figure: Charge Control Y front view with closed case
13+
Charge Control Y front view with closed case
1414

1515
.. figure:: _static/images/CCY_V0R4A_open-case.png
1616
:width: 900pt
1717

18-
Figure: Charge Control Y rear view with open case
18+
Charge Control Y rear view with open case
1919

2020

2121
Product Description
@@ -59,4 +59,4 @@ Order Information
5959
-----------------
6060

6161
You can acquire an Evaluation Kit using the order code ‘CBCCY-STD-000’.
62-
For more information, please contact 'info@chargebyte.com'.
62+
For more information, please contact `info@chargebyte.com <mailto:info@chargebyte.com>`_.

‎docs/source/safety_controller.rst‎

Lines changed: 21 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
1-
.. safety_controller.rst:
1+
.. _safety_controller.rst:
22

3-
*****************
43
Safety Controller
5-
*****************
4+
=================
65

76
Overview
8-
========
7+
--------
98

109
The Charge Control Y is equipped with an additional MCU (aka Safety Controller) which is responsible for
1110
managing all low-level aspects which are critical for electrical safety. The firmware for this MCU is
@@ -33,38 +32,39 @@ in the following table.
3332

3433

3534
System Architecture
36-
===================
35+
-------------------
36+
3737
.. figure:: _static/images/system_architecture_ccy.svg
3838
:width: 1000pt
3939

40-
Figure: Simplified system architecture for the safety controller on the Charge Control Y
40+
Simplified System Architecture for the Safety Controller on the Charge Control Y
4141

4242
The safety controller manages the Charge Enable (CE) line, acting as a critical interface for monitoring
4343
Insertion Detection (ID) as well as Emergency Input and temperature sensors and therefore controlling the
44-
HV ready switch in accordance with EV safety standards. Its core function is to **enforce safe operating states**
45-
based on system diagnostics and environmental conditions.
44+
HV ready switch in accordance with EV safety standards.
45+
Its core function is to **enforce safe operating states** based on system diagnostics and environmental conditions.
4646

4747

4848
Fault Detection & Safety Response
4949
---------------------------------
5050

5151
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
52+
controller transitions to **State EC**, a fail-safe state that prevents further system operation to protect both
5353
the hardware and the user.
5454

5555

5656
HV Ready Enablement
5757
-------------------
5858

59-
The controller verifies that **no system errors are present** and that the CE line is in **State C**. Only under
60-
these safe conditions it does enable the HV Ready signal, which may be used to energize the HV interlock or
59+
The controller verifies that **no system errors are present** and that the CE 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
6161
permit charging/operation.
6262

6363

64-
Emergency Inputs
65-
-----------------
64+
Emergency Input
65+
---------------
6666

67-
The inputs are active-low. This means an emergency stop needs to pull the input to Gnd EVSE.
67+
The input is active-low. This means an emergency stop needs to pull the input to Gnd (EVSE).
6868

6969

7070
Temperature Monitoring
@@ -75,96 +75,19 @@ temperature measurement circuits for PT1000 sensors. The safety software monitor
7575
hardware errors and for overtemperaure. The temperature threshold can be parameterized.
7676

7777

78-
Reset Behaviour and Controller states
79-
=====================================
78+
Reset Behaviour and Controller States
79+
-------------------------------------
8080

81-
The safety controller starts in an initialization state, to give the peripherals time to reach an defined state.
81+
The safety controller starts in an initialization state, to give the peripherals time to reach a defined state.
8282
It leaves the initialization state to a running state, after the reception of the first UART message from the host.
83-
Only periodic messages leaves the init state. With the reception of inquiriy messages, the safety controller stays in
84-
initialization. This gives the option to fetch version information in an init state. In running state, it monitors the
83+
Only periodic messages leave the init state. With the reception of inquiry messages, the safety controller stays in
84+
initialization. This gives the option to fetch version information in the init state. In running state, it monitors the
8585
peripherals and sends out UART messages. If any error occurs, the system goes into safe state.
8686
This state can only be left by a reset.
8787

8888
.. figure:: _static/images/safety_controller_states.svg
8989
:width: 1000pt
9090

91+
.. include:: safety_controller_uart.rst
9192

92-
Safety Controller Communication Protocol
93-
========================================
94-
95-
Packet Format Descriptions
96-
--------------------------
97-
98-
Data packet format
99-
100-
Data packets contain payload and can be sent out from host to safety controller or vice versa. Data packets from safety
101-
controller to host can be transmitted periodically or by request via an inquiry packet.
102-
Only one inquiry packet can be requested before requesting the next one.
103-
104-
+--------+--------+--------+-------------------+
105-
| Symbol | Size | Code | Description |
106-
+========+========+========+===================+
107-
| SOF | 1 byte | 0xA5 | Start of frame |
108-
+--------+--------+--------+-------------------+
109-
| ID | 1 byte | | Packet Identifier |
110-
+--------+--------+--------+-------------------+
111-
| Data | 8 byte | | Payload |
112-
+--------+--------+--------+-------------------+
113-
| CRC | 1 byte | | CRC checksum |
114-
+--------+--------+--------+-------------------+
115-
| EOF | 1 byte | 0x03 | End of frame |
116-
+--------+--------+--------+-------------------+
117-
118-
119-
Packet Identifier (ID)
120-
----------------------
121-
122-
The values of the packet identifier (PacketId) are mapped to the messages as summarized below.
123-
124-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
125-
| PacketId | Description | Communication Dir. | Periodicity | Triggered by Inquiry |
126-
+==========+===========================+=====================+=============================================================+======================+
127-
| 0x06 | Charge Control | Host → Safety | periodically, every 100ms OR immediately if changes occur | No |
128-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
129-
| 0x07 | Charge State | Safety → Host | periodically, every 100ms | No |
130-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
131-
| 0x08 | PT1000 State | Safety → Host | periodically, every 100ms | No |
132-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
133-
| 0x0A | Firmware Version | Safety → Host | no, only upon request via inquiry packet | Yes |
134-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
135-
| 0x0B | GIT Hash | Safety → Host | no, only upon request via inquiry packet | Yes |
136-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
137-
| 0xFF | Inquiry packet | Host → Safety | no, only to trigger inquiries | No |
138-
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
139-
140-
CRC Checksum Field
141-
------------------
142-
143-
The checksum is defined over:
144-
145-
::
146-
147-
Width = 8
148-
Poly = 0x1d
149-
XorIn = 0xff
150-
ReflectIn = False
151-
XorOut = 0xff
152-
ReflectOut = False
153-
Algorithm = table-driven
154-
Name = CRC8 SAE J1850
155-
156-
.. include:: safety_protocol.rst
157-
158-
159-
EVerest Board Support Package Module
160-
====================================
161-
162-
chargebyte developed a comprehensive hardware abstraction module (HAL, or also called BSP module - board support package)
163-
for EVerest charging stack to support the Charge Control Y. The module is called ``CbParsleyDriver`` and is
164-
available in chargebyte's public EVerest repository as open-source code:
165-
https://github.com/chargebyte/everest-chargebyte/tree/main/modules/CbParsleyDriver
166-
167-
This module already implements the required communication protocol to interact with the safety controller.
168-
169-
All Charge Control Y boards ship with a Linux system preinstalled on eMMC, which also includes EVerest, the mentioned
170-
BSP module and example configuration files.
93+
.. include:: everest_bsp.rst

‎docs/source/safety_controller_uart.rst‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
.. _safety_controller_uart.rst:
2+
3+
Safety Controller Communication Protocol
4+
----------------------------------------
5+
6+
Packet Format Description
7+
^^^^^^^^^^^^^^^^^^^^^^^^^
8+
9+
Data packet format
10+
11+
Data packets contain payload and can be sent out from host to safety controller or vice versa. Data packets from safety
12+
controller to host can be transmitted periodically or by request via an inquiry packet.
13+
Only one inquiry packet can be requested before requesting the next one.
14+
15+
+--------+--------+--------+-------------------+
16+
| Symbol | Size | Code | Description |
17+
+========+========+========+===================+
18+
| SOF | 1 byte | 0xA5 | Start of Frame |
19+
+--------+--------+--------+-------------------+
20+
| ID | 1 byte | | Packet Identifier |
21+
+--------+--------+--------+-------------------+
22+
| Data | 8 byte | | Payload |
23+
+--------+--------+--------+-------------------+
24+
| CRC | 1 byte | | CRC Checksum |
25+
+--------+--------+--------+-------------------+
26+
| EOF | 1 byte | 0x03 | End of Frame |
27+
+--------+--------+--------+-------------------+
28+
29+
30+
Packet Identifier (ID)
31+
^^^^^^^^^^^^^^^^^^^^^^
32+
33+
The values of the packet identifier (PacketId) are mapped to the messages as summarized below.
34+
35+
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
36+
| PacketId | Description | Communication Dir. | Periodicity | Triggered by Inquiry |
37+
+==========+===========================+=====================+=============================================================+======================+
38+
| 0x11 | Charge Control 2 | Host → Safety | periodically, every 100ms OR immediately if changes occur | No |
39+
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
40+
| 0x10 | Charge State 2 | Safety → Host | periodically, every 100ms | No |
41+
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
42+
| 0x08 | PT1000 State | Safety → Host | periodically, every 100ms | No |
43+
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
44+
| 0x0A | Firmware Version | Safety → Host | no, only upon request via inquiry packet | Yes |
45+
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
46+
| 0x0B | GIT Hash | Safety → Host | no, only upon request via inquiry packet | Yes |
47+
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
48+
| 0xFF | Inquiry Packet | Host → Safety | no, only to trigger inquiries | No |
49+
+----------+---------------------------+---------------------+-------------------------------------------------------------+----------------------+
50+
51+
CRC Checksum Field
52+
^^^^^^^^^^^^^^^^^^
53+
54+
The checksum is defined over:
55+
56+
::
57+
58+
Width = 8
59+
Poly = 0x1d
60+
XorIn = 0xff
61+
ReflectIn = False
62+
XorOut = 0xff
63+
ReflectOut = False
64+
Algorithm = table-driven
65+
Name = CRC8 SAE J1850
66+
67+
.. include:: safety_protocol.rst

‎docs/source/safety_protocol.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
ChargeControl2
2-
==============
2+
^^^^^^^^^^^^^^
33

44
**ID**: 0x11 (17)
55

@@ -74,7 +74,7 @@ ChargeControl2
7474
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
7575

7676
ChargeState2
77-
============
77+
^^^^^^^^^^^^
7878

7979
**ID**: 0x10 (16)
8080

@@ -203,7 +203,7 @@ ChargeState2
203203
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
204204

205205
PT1000State
206-
===========
206+
^^^^^^^^^^^
207207

208208
**ID**: 0x8 (8)
209209

@@ -378,7 +378,7 @@ PT1000State
378378
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
379379

380380
FirmwareVersion
381-
===============
381+
^^^^^^^^^^^^^^^
382382

383383
**ID**: 0xA (10)
384384

@@ -485,7 +485,7 @@ FirmwareVersion
485485
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
486486

487487
GitHash
488-
=======
488+
^^^^^^^
489489

490490
**ID**: 0xB (11)
491491

@@ -543,7 +543,7 @@ GitHash
543543
+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+--------------------+
544544

545545
InquiryPacket
546-
=============
546+
^^^^^^^^^^^^^
547547

548548
**ID**: 0xFF (255)
549549

0 commit comments

Comments
 (0)