Skip to content

Commit 7a446b8

Browse files
mheimhei
authored
Merge pull request #63 from chargebyte/everest/charge_som_safety-pb
Safety Controller: add chapter about parameter blocks
2 parents b4ca6c8 + a004ee5 commit 7a446b8

7 files changed

Lines changed: 175 additions & 154 deletions

‎docs/requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
sphinx==7.3.7
22
sphinx-copybutton
3+
sphinx-jinja2
34
linuxdoc

‎docs/source/conf.py‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,19 +13,28 @@
1313
# -- General configuration ---------------------------------------------------
1414
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
1515

16-
extensions = ['linuxdoc.rstFlatTable', 'sphinx_copybutton']
16+
extensions = ['linuxdoc.rstFlatTable', 'sphinx_copybutton', 'sphinx_jinja2']
1717

18-
templates_path = ['_templates']
18+
templates_path = ['_templates', '../../includes/_templates']
1919
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
2020

2121
numfig = True
2222

23+
jinja2_contexts = {
24+
'target-info': {
25+
'PLATFORM_NAME': 'Charge SOM',
26+
'MACHINE': 'chargesom',
27+
'APT_CROSS_MACHINE_SPECIFIC': 'gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-aarch64-linux-gnu',
28+
'MACHINE_FILE_SIGNATURE': 'ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, BuildID[sha1]=af8cd65df0ac1e3e6f0ed3adafcd5aec60ca8f15, for GNU/Linux 3.7.0, stripped'
29+
},
30+
}
31+
2332
# -- Options for HTML output -------------------------------------------------
2433
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
2534

2635
html_title = project
2736
html_theme = 'classic'
28-
html_static_path = ['_static']
37+
html_static_path = ['_static', '../../includes/_static']
2938
html_logo = '_static/cb_logo.png'
3039
html_css_files = [
3140
'css/cb_theme.css',

‎docs/source/development.rst‎

Lines changed: 4 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,12 @@
11
.. _development.rst:
22

3-
.. include:: ../../includes/development.inc
3+
.. include:: ../../includes/development_intro.inc
44

5-
.. _cross_compiling:
5+
.. _development_cross_compiling_everest_modules:
66

7-
Cross-compiling for Charge SOM
8-
==============================
9-
10-
Cross-compilation is the fastest and most convenient way to test your own modules directly on the target
11-
system during development. The cross-compiled project can then either be transferred directly via SFTP
12-
to the charge controller or integrated into a firmware image and installed on the target using the `rauc` command.
13-
14-
The following steps describe how to cross-compile a module for the Charge SOM platform.
15-
16-
#. On an Ubuntu or Debian-based Linux distribution, install the cross-compilers for Charge SOM:
17-
18-
.. code-block:: console
19-
20-
sudo apt install build-essential libc6-arm64-cross gcc-aarch64-linux-gnu g++-aarch64-linux-gnu binutils-arm-linux-gnueabihf gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
21-
22-
#. Download chargebyte's `digital certificate <https://chargebyte.com/controllers-and-modules/evse-controllers/charge-control-c#downloads>`_
23-
and use it to extract the root filesystem from the firmware image. The digital certificate is the same between Charge SOM and Charge Control C.
24-
25-
.. code-block:: console
26-
27-
rauc extract --keyring=<chargebyte_certificate>.crt <shipped_firmware>.image bundle-staging
28-
29-
.. note::
30-
Alternatively, if the above command does not work, you can use the following command:
31-
32-
.. code-block:: console
33-
34-
unsquashfs -d bundle-staging <shipped_firmware>.image
35-
36-
However, this will not verify the signature of the firmware image.
37-
38-
#. Mount the extracted ext4 root filesystem image as a loop device:
39-
40-
.. code-block:: console
41-
42-
sudo mkdir -p /mnt/rootfs
43-
sudo mount bundle-staging/core-image-minimal-chargesom.ext4 /mnt/rootfs
44-
45-
#. Create a new directory in your `everest-workspace` directory (in parallel to the `everest-core` directory) and
46-
create a new file named :code:`toolchain.cmake`:
47-
48-
.. code-block:: console
49-
50-
cd everest-workspace
51-
mkdir toolchain
52-
cd toolchain
53-
touch toolchain.cmake
54-
55-
#. Save the following content in the :code:`toolchain.cmake` file:
56-
57-
.. literalinclude:: ../../includes/_static/files/toolchain.cmake
58-
59-
#. The resulting directory structure should look like this:
60-
61-
.. code-block:: console
62-
63-
everest-workspace/
64-
|── {MyEVerestModule}
65-
├── everest-core
66-
└── toolchain
67-
└── toolchain.cmake
68-
69-
#. Create a new :code:`build_csom` directory in the EVerest project directory (e.g. within your own EVerest
70-
module project directory or :code:`everest-core` if you want to build the everest-core modules):
71-
72-
.. code-block:: console
73-
74-
cd ../{MyEVerestModule}
75-
mkdir build_csom
76-
cd build_csom
77-
78-
#. Run the following command inside the `build_csom` directory to configure the build:
79-
80-
.. code-block:: console
81-
82-
cmake -DCMAKE_TOOLCHAIN_FILE=../../toolchain/toolchain.cmake -DCMAKE_SYSROOT=/mnt/rootfs ..
83-
84-
#. When this completes successfully, start cross-compiling using :code:`make`:
85-
86-
.. code-block:: console
87-
88-
make install -j$(nproc)
89-
90-
#. If the build was successful, a dist directory will be created with the cross-compiled binaries and
91-
the manifest files of the modules. Please check if the following directory structure was created:
92-
93-
.. code-block:: console
94-
95-
dist/
96-
└── libexec
97-
└── everest
98-
└── modules
99-
└── {MyEVerestModule}
100-
├── {MyEVerestModule} (binary)
101-
└── manifest.yaml (manifest file)
102-
103-
#. Verify that the resulting binaries were compiled for the Charge SOM platform:
104-
105-
.. code-block:: console
106-
107-
file dist/libexec/everest/modules/{MyEVerestModule}/{MyEVerestModule}
108-
109-
The output should be something like:
110-
111-
.. code-block:: console
112-
113-
dist/libexec/everest/modules/{MyEVerestModule}/{MyEVerestModule}: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV),
114-
dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, BuildID[sha1]=ad2342fdd3b8fb1949fc3e13b77382d3da72f28a, for GNU/Linux 3.7.0, stripped
115-
116-
#. The resulting binary and manifest can be found in the :code:`dist/libexec/everest/modules/{MyEVerestModule}`
117-
directory. If you want to test the module on the target system, you can copy the module directory using
118-
:code:`scp` or :code:`rsync`:
119-
120-
.. code-block:: console
121-
122-
scp -r dist/libexec/everest/modules/{MyEVerestModule} root@<ip_address>:/usr/libexec/everest/modules/
123-
124-
#. To include the new module in a firmware image, copy the module directory into the mounted root filesystem:
125-
126-
.. code-block:: console
127-
128-
sudo cp -av dist/libexec/everest/modules/{MyEVerestModule} /mnt/rootfs/usr/libexec/everest/modules/
129-
130-
#. Unmount the loop device:
131-
132-
.. code-block:: console
133-
134-
sudo umount /mnt/rootfs
135-
136-
#. Ensure that the modified filesystem is in a clean state:
137-
138-
.. code-block:: console
139-
140-
fsck.ext4 -f bundle-staging/core-image-minimal-chargesom.ext4
141-
142-
#. Follow the steps under the section :ref:`firmware_customization` to install your PKI certificate, repackage
143-
the modified root filesystem into a firmware update image, and test the new firmware.
144-
145-
.. _creating_fw_images:
7+
.. jinja:: target-info
8+
:file: ../../includes/_templates/development_cross_compiling_everest_modules.rst.j2
1469

14710
.. include:: ../../includes/development_creating_fw_images.inc
14811

149-
.. _debugging_and_logging:
150-
15112
.. include:: ../../includes/development_debugging_and_logging.inc

‎docs/source/everest_charging_stack.rst‎

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

2525
.. include:: ../../includes/everest_overview_of_everest_modules.inc
2626

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

2929
This module simulates a DC power supply device.
3030

‎docs/source/safety_controller.rst‎

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

102+
.. include:: safety_controller_parameterization.rst
103+
102104
.. include:: safety_controller_uart.rst
103105

104106
.. include:: everest_bsp.rst

‎docs/source/safety_controller_parameterization.rst‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
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+
Futhermore, the safety controller can control high-voltage contactors and can then monitor feedback contacts to
14+
detect contactor welding.
15+
It also supports up to four emergency input channels, each can be disabled when not connected/required in
16+
the actual customer setup.
17+
18+
These safety controller parameters are stored as a binary parameter block, directly in the safety controller's flash.
19+
When shipped from factory, there is a default parameter block installed which allows easy evaluation of the product,
20+
but is not intended for production usage in the field.
21+
Customers are encouraged to adjust the parameters to their requirements/needs during deployment of the board into
22+
an actual charger.
23+
24+
To adjust the parameters, some small command line tools are included in the shipped Linux firmware which allow
25+
to create/modify the parameters on the board itself. However, it is also possible to use these tools on a Linux
26+
host system (e.g. in a virtual machine) and then to transfer the created parameter block to each board
27+
and install it.
28+
29+
The mentioned tools are part of the `ra-utils repository <https://github.com/chargebyte/ra-utils>`__ on Github.
30+
31+
To make the handling of parameters human-friendly, all parameters can be put together using a YAML text file.
32+
33+
.. code-block:: yaml
34+
35+
pt1000s:
36+
- 75.0 °C
37+
- 85.0 °C
38+
- disabled
39+
- disabled
40+
41+
contactors:
42+
- without-feedback
43+
- without-feedback
44+
45+
estops:
46+
- active-low
47+
- disabled
48+
- disabled
49+
50+
.. important::
51+
52+
The YAML file is required to be encoded in UTF-8. While most parameters are ASCII only, temperature thresholds require
53+
trailing `°C` suffix which has a special UTF-8 encoding sequence. This might be displayed incorrectly in the editor
54+
when editing on the device itself and/or finally stored wrong in the YAML file.
55+
When unsure, adapt/create the YAML file on your Linux host system with your preferred editor and transfer it
56+
to the board via Ethernet network (e.g. SCP/SFTP).
57+
58+
Such a YAML file must be converted to a binary parameter block file afterwards. And this binary parameter block file
59+
must finally be flashed to the safety controller's flash memory, see below.
60+
61+
62+
Temperature Channel (PT1000) Configuration
63+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
64+
65+
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`
68+
instead of a temperature value.
69+
70+
71+
Contactor and Contactor Feedback Configuration
72+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
73+
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.
78+
79+
Possible parameter values are:
80+
81+
- `disabled`
82+
- `without-feedback`
83+
- `with-feedback`
84+
85+
86+
Emergency Input Configuration
87+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88+
89+
The safety controller can monitor up to 3 emergency inputs.
90+
91+
Possible configuration values are:
92+
93+
- `disabled`
94+
- `active-low`
95+
96+
97+
Installing a Parameter Block
98+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
99+
100+
Once the YAML file is created and fits your charger setup, it is required to convert it to a binary parameter block file.
101+
In the mentioned repository, there exists a tool `ra-pb-create` to generate such a binary file from the YAML file.
102+
The following session transcript shows how the install procedure works:
103+
104+
.. code-block:: sh
105+
106+
# create a YAML file on-the-fly
107+
$ cat <<EOL > /tmp/my-parameters.yaml
108+
pt1000s:
109+
- 75.0 °C
110+
- 85.0 °C
111+
- disabled
112+
- disabled
113+
114+
contactors:
115+
- without-feedback
116+
- without-feedback
117+
118+
estops:
119+
- active-low
120+
- disabled
121+
- disabled
122+
EOL
123+
124+
# convert YAML to binary
125+
ra-pb-create -i /tmp/my-parameters.yaml -o /tmp/my-parameters.bin
126+
127+
# stop EVerest - to have exclusive access to safety controller
128+
systemctl stop everest
129+
130+
# flash the parameter block
131+
ra-update -a data flash /tmp/my-parameters.bin
132+
133+
# restart EVerest
134+
systemctl start everest
135+
136+
137+
Checking the Installed Parameter Block
138+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
139+
140+
To check which settings are currently used by the safety controller firmware, it is possible to read back the parameter block.
141+
142+
.. code-block:: sh
143+
144+
systemctrl stop everest
145+
ra-update -a data dump | ra-pb-dump
146+
147+
This will print the current settings in YAML format on stdout.

‎docs/source/troubleshooting.rst‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,11 @@ The Charge SOM hardware is not designed to be used as an EV simulator. Please re
3434
I want to control EVerest via CAN, how can I achieve this?
3535
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3636

37-
Currently, there is no such EVerest module available, you will need to implement it on your own. But
38-
at least there is a `module <https://github.com/EVerest/everest-core/tree/main/modules/DPM1000>`_
39-
and a `library <https://github.com/EVerest/everest-core/tree/main/lib/staging/can_dpm1000>`_,
40-
which uses the CAN interface.
37+
Currently there is no such EVerest module available, you will need to implement it on your own.
38+
39+
But at least there is are `DC power supply modules <https://github.com/EVerest/everest-core/tree/main/modules/HardwareDrivers/PowerSupplies>`_
40+
and a `library <https://github.com/EVerest/everest-core/tree/main/lib/everest/can_dpm1000>`_,
41+
which uses the CAN interface. This might help as a starting point.
4142

4243

4344
What is the difference between CHSTOP_IN and SAFETY_ESTOPx?
@@ -100,7 +101,7 @@ How do I set up OCPP 2.0.1 on Charge SOM with EVerest?
100101
To support OCPP 2.0.1, the EVerest OCPP201 module must be integrated into the EVerest configuration.
101102
This module uses the `libocpp library <https://github.com/EVerest/libocpp>`_ to implement the OCPP 2.0.1
102103
protocol.
103-
The `OCPP201 module documentation <https://github.com/EVerest/everest-core/blob/main/modules/OCPP201/doc.rst>`_
104+
The `OCPP201 module documentation <https://github.com/EVerest/everest-core/blob/main/modules/EVSE/OCPP201/doc.rst>`_
104105
already contains some information about the module parameters, the provided and required interfaces,
105106
and the initial creation of the OCPP 2.0.1 database.
106107

@@ -121,8 +122,8 @@ The most important points are summarised here:
121122
5. The OCPP 2.0.1 device model initialization is done automatically by the OCPP201 module after the
122123
first start of EVerest. The database is stored the `DeviceModelDatabasePath`.
123124
6. The component config files are stored in the `DeviceModelConfigPath`. Component config files are
124-
used to initialize or update the device model database. To update a component config file, just the
125-
place a `component config file <https://github.com/EVerest/libocpp/tree/v0.16.2/config/v201/component_config>`_
125+
used to initialize or update the device model database. To update a component config file, just
126+
place a `component config file <https://github.com/EVerest/libocpp/tree/main/config/v2/component_config>`_
126127
in the same directory structure in the DeviceModelConfigPath and change the values accordingly.
127128
Important keys of the component config files are:
128129

0 commit comments

Comments
 (0)