From bb88fcffa55d503e5794d830fc5275a862f54ce2 Mon Sep 17 00:00:00 2001 From: Fabian Hartung Date: Tue, 7 Jan 2025 14:34:49 +0100 Subject: [PATCH 1/5] Improve documentation clarity for EVerest configuration and module management Signed-off-by: Fabian Hartung --- docs/source/getting_started.rst | 71 +++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 29 deletions(-) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index cc0859a..d2fd941 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -159,11 +159,11 @@ Just type "less /etc/everest/bsp-only.conf" to see the content of the configurat :language: yaml :linenos: -In general, the EVerest charging stack consists of different modules, each of which fulfills a -specific task. An EVerest module provides and requests interfaces. The configuration file shows -which EVerest modules are activated, how they are configured and how they are connected to each -other over the interfaces. The following figure illustrates how the EVerest modules are connected -to each other: +In general, the EVerest charging stack consists of different modules, each designed for a specific task. +An EVerest module provides and requests interfaces and defines module-specific configuration parameters. +The EVerest configuration file specifies the activated modules, their configurations, and their connections +via these interfaces. The following figure illustrates how the EVerest modules are connected to each +other in the bsp-only.yaml configuration file: .. figure:: _static/images/admin_panel_bsp_only.png :width: 500pt @@ -171,45 +171,58 @@ to each other: Figure: EVerest admin panel view of the bsp-only.yaml configuration -However, not all configuration parameters of the modules are shown here. Only the configuration -parameters that do not match the default configuration of the respective module need -to be specified here. Depending on the installed hardware components, the configuration file may -need to be adapted. The hardware related tasks are mainly handled by the CbTarragonDriver module. -The configuration of the CbTarragonDriver module can be found in "/usr/libexec/everest/modules/CbTarragonDriver" -directory. +However, not all configuration parameters of the modules are shown here. Only those that deviate from +the module's default configuration need to be specified. -Each module has a specific configuration file. This file is called "manifest.yaml" and is stored -in the main directory of the module. -Here you can also see all other configuration parameters of the respective module. -Now please type "less /usr/libexec/everest/modules/CbTarragonDriver/manifest.yaml" to see the -content of the configuration file and check whether the configuration fits to your hardware setup. +Each module has a specific configuration file called "manifest.yaml", located in the module's main directory +("/usr/libexec/everest/modules/{module_name}"). This file is used by the EVerest stack to verify configuration +consistency and to load the default module configuration. As a user the manifest.yaml can also be used +in order to check which configurations are possible and how the default values are set. + +The hardware related tasks are mainly handled by the CbTarragonDriver module. To view the content of +the module's manifest file, use the following command: + +.. code-block:: sh + + less /usr/libexec/everest/modules/CbTarragonDriver/manifest.yaml If you want to change a configuration parameter of a module, which is not part of your EVerest YAML configuration file, just copy the specific configuration key from the "manifest.yaml" file of the module to the module specific "config_module" space in your EVerest configuration and adjust the -value. Please note if you change it directly in the "manifest.yaml" file of a module, the changes -will be get lost after a software update. +value. If a default value in the manifest file meets your requirements, there is no need to redefine +it in your EVerest configuration. -Here is an excerpt of an EVerest configuration to change the parameter "connector_type" to -"IEC62196Type2Cable" of the CbTarragonDriver module. +.. note:: + Do not modify the manifest.yaml file directly to change default behavior. Always make adjustments + in your EVerest configuration file to override the default values of the module parameters. + +Here is an example of how to change the "connector_type" parameter of the CbTarragonDriver module to +"IEC62196Type2Cable" in the EVerest configuration file. + +Snippet of a EVerest configuration file: .. code-block:: sh - tarragon_bsp: - module: CbTarragonDriver - config_module: - contactor_1_feedback_type: none - relay_2_name: none - connector_type: IEC62196Type2Cable + tarragon_bsp: + module: CbTarragonDriver + config_module: + contactor_1_feedback_type: none + relay_2_name: none + connector_type: IEC62196Type2Cable +By following these guidelines, you can now customize and manage your EVerest charging stack configuration +to suit your hardware and application requirements. After adjusting the configuration file, you have +to restart the EVerest charging stack to apply the changes: + +.. code-block:: sh -After adjusting the configuration file, you have to restart the EVerest charging stack to apply the -changes. Just type "systemctl restart everest" to restart the EVerest charging stack. + systemctl restart everest .. note:: You can also use the `EVerest admin panel `_ to adjust the EVerest configuration in a GUI. This tool must currently be installed manually on your - developer computer, because the resources on the board are limited. + developer computer, because the resources on the board are limited. Please note that the tool can + only display a configuration correctly if all interface and module descriptions are provided. .. note:: If you have made a mistake in the configuration file, the EVerest charging stack will not From 7b4d8da782d5bf1c72f6914418325613c9187b4c Mon Sep 17 00:00:00 2001 From: Fabian Hartung Date: Thu, 9 Jan 2025 11:51:17 +0100 Subject: [PATCH 2/5] Add missing information about EVerest modules, eMMC Partitioning and support Signed-off-by: Fabian Hartung --- docs/source/everest_charging_stack.rst | 24 ++++++++++++++++++++++-- docs/source/firmware.rst | 2 +- docs/source/troubleshooting.rst | 1 + 3 files changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/source/everest_charging_stack.rst b/docs/source/everest_charging_stack.rst index 62fa061..d09a26e 100644 --- a/docs/source/everest_charging_stack.rst +++ b/docs/source/everest_charging_stack.rst @@ -102,6 +102,25 @@ can be utilized. This module is a driver for plug lock control and implements It is designed to support all types of plug locks on connector X9 of the Charge Control C. Check section :ref:`locking_motor` to understand how to connect the locking motor to the Charge Control C. +**API** (`view on GitHub `__) + +This module is not mandatory for an EVSE setup using Charge Control C in EVerest. However, the module +:code:`API` is responsible to provide a simple MQTT based API to EVerest internals. + +**ErrorHistory** (`view on GitHub `__) + +This module is not mandatory for an EVSE setup using Charge Control C in EVerest. This module is responsible +for storing EVerest error events in a database file. The location of the database file can be defined +over a configuration parameter. + +**OCPP** (`view on GitHub `__) + +This module implements and integrates OCPP 1.6 support within EVerest. + +**OCPP201** (`view on GitHub `__) + +This module implements and integrates OCPP 2.0.1 support within EVerest. + Further reading =============== @@ -119,5 +138,6 @@ are maintained by chargebyte. For interesting discussions and solutions to common problems, visit the EVerest community's `Zulip `_ channels. -For support and issues related to the EVerest modules developed by chargebyte, refer to section X for -instructions on how to report problems and insights on contribution. +For support and issues related to the EVerest modules developed by chargebyte, please check the +:ref:`troubleshooting.rst` section of the documentation first. If you can't find the answer, please don't +hesitate to contact chargebyte's support team (:ref:`contact`). diff --git a/docs/source/firmware.rst b/docs/source/firmware.rst index e13c1e4..a594bac 100644 --- a/docs/source/firmware.rst +++ b/docs/source/firmware.rst @@ -258,7 +258,7 @@ The internal eMMC storage of a Charge Control device is divided into several par - 1 GB - Root file system B * - /dev/mmcblk0p3 - - + - 1.3 GB - Extended Partition Container * - /dev/mmcblk0p5 - 1 GB diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 0a8036f..f5d85cf 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -119,6 +119,7 @@ EVerest already has a module which takes care of Modbus communication. Please ha `SerialCommHub `_, and let your module interact with this module via the `serial_communication_hub` interface. +.. _contact: Contact ------- From 11b1aa3a22e1699119ae22aefb813ff3a41d1d47 Mon Sep 17 00:00:00 2001 From: Fabian Hartung Date: Thu, 9 Jan 2025 11:56:00 +0100 Subject: [PATCH 3/5] Adapt troubleshooting documentation for OCPP 2.0.1 to EVerest 2024.9.0 release (refs EVEREST-1291) Signed-off-by: Fabian Hartung --- docs/source/troubleshooting.rst | 64 ++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index f5d85cf..f59203e 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -71,35 +71,41 @@ Please note that the implementation is still under development and integrated in How do I set up OCPP 2.0.1 on Charge Control C with EVerest? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Unfortunately, some manual steps on a development PC are necessary. First, check out the -libocpp and change into the OCPP 2.0.1 config directory: - -.. code-block:: console - - git clone https://github.com/EVerest/libocpp.git - cd libocpp/config/v201 - -Now adapt OCPP 2.0.1 config.json to your needs (e.g. NetworkConnectionProfiles): - -.. code-block:: console - - gedit config.json - -After that you can create the device model database and insert the configuration: - -.. code-block:: console - - python3 init_device_model_db.py --db device_model_storage.db --schemas component_schemas/ init - python3 init_device_model_db.py --db device_model_storage.db --schemas component_schemas/ --config config.json insert - -Then copy the device model database onto the Charge Control C (adapt IP address to your environment): - -.. code-block:: console - - scp device_model_storage.db root@:/var/lib/everest/ocpp201 - -Finally make sure the DeviceModelDatabasePath in your global YAML configuration points to -/var/lib/everest/ocpp201/device_model_storage.db and then restart EVerest on the Charge Control C. +To support OCPP 2.0.1, the EVerest OCPP201 module must be integrated into the EVerest configuration. +This module uses the `libocpp library `_ to implement the OCPP 2.0.1 +protocol. +The `OCPP201 module documentation `_ +already contains some information about the module parameters, the provided and required interfaces, +and the initial creation of the OCPP 2.0.1 database. + +The most important points are summarised here: + +1. The OCPP201 module must be included in your EVerest configuration. +2. The CbSystem module can be used to fulfill the requirement of the system interface. +3. While configuring the OCPP 2.0.1 module, ensure that you are using OCPP configuration and database + paths which are covered by the update mechanism. The following paths are recommended: + + - `CoreDatabasePath`: /var/lib/everest/ocpp201 + - `DeviceModelDatabasePath`: /var/lib/everest/ocpp201/device_model_storage.db + - `DeviceModelConfigPath`: /var/lib/everest/ocpp201/component_config + + Otherwise, if you don't want to use a persistent storage, you can also deploy those files in your + RAUC image. +4. The `CoreDatabasePath` is used, among other things, to store OCPP transaction data. +5. The OCPP 2.0.1 device model initialization is done automatically by the OCPP201 module after the + first start of EVerest. The database is stored the `DeviceModelDatabasePath`. +6. The component config files are stored in the `DeviceModelConfigPath`. Component config files are + used to initialize or update the device model database. To update a component config file, just the + place a `component config file `_ + in the same directory structure in the DeviceModelConfigPath and change the values accordingly. + Importent keys of the component config files are: + + - `standardized/InternalCtrlr.json: ChargePointId`: In "attributes" adapt the "value" key to configure the ChargePointId. Used to identify the Charging Station. + - `standardized/InternalCtrlr.json: NetworkConnectionProfiles`: In "attributes" adapt the "ocppCsmsUrl" key. The URL in "ocppCsmsUrl" is used to connect to the CSMS. + - `standardized/SecurityCtrlr.json: SecurityCtrlrIdentity`: In "attributes" adapt the "value" key to configure the SecurityCtrlrIdentity. It is the Charging Station identity. + + For further information about the device model initialization, please refer to the + `libocpp documentation `_. I tried to compile chargebyte's Hardware EVerest Modules, but it fails to build. How can it fix this? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 1830eca26a8532183c7cfdd226ea901d57e126af Mon Sep 17 00:00:00 2001 From: Fabian Hartung Date: Thu, 9 Jan 2025 11:59:54 +0100 Subject: [PATCH 4/5] Remove unnecessary blank lines in firmware and troubleshooting documentation Signed-off-by: Fabian Hartung --- docs/source/firmware.rst | 2 -- docs/source/troubleshooting.rst | 2 -- 2 files changed, 4 deletions(-) diff --git a/docs/source/firmware.rst b/docs/source/firmware.rst index a594bac..ebc9eb0 100644 --- a/docs/source/firmware.rst +++ b/docs/source/firmware.rst @@ -563,5 +563,3 @@ During development it may be useful to access/mount the inactive partition. Then mount-other-rootfs /mnt Note, that this helper script does not modify any RAUC status information regarding this slot. - - diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index f59203e..073592c 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -155,5 +155,3 @@ Bitterfelder Straße 1-5 Germany Website: ``_ - - From 6cf08f73aeac3f3e4fd162c994b08f2e77848791 Mon Sep 17 00:00:00 2001 From: Fabian Hartung Date: Thu, 9 Jan 2025 15:17:21 +0100 Subject: [PATCH 5/5] Fix typos and improve code block formatting in documentation Signed-off-by: Fabian Hartung --- docs/source/everest_charging_stack.rst | 4 ++-- docs/source/getting_started.rst | 16 ++++++++-------- docs/source/troubleshooting.rst | 2 +- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/source/everest_charging_stack.rst b/docs/source/everest_charging_stack.rst index d09a26e..e87152c 100644 --- a/docs/source/everest_charging_stack.rst +++ b/docs/source/everest_charging_stack.rst @@ -105,13 +105,13 @@ section :ref:`locking_motor` to understand how to connect the locking motor to t **API** (`view on GitHub `__) This module is not mandatory for an EVSE setup using Charge Control C in EVerest. However, the module -:code:`API` is responsible to provide a simple MQTT based API to EVerest internals. +:code:`API` is responsible for providing a simple MQTT based API to EVerest internals. **ErrorHistory** (`view on GitHub `__) This module is not mandatory for an EVSE setup using Charge Control C in EVerest. This module is responsible for storing EVerest error events in a database file. The location of the database file can be defined -over a configuration parameter. +via a configuration parameter. **OCPP** (`view on GitHub `__) diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index d2fd941..e635d89 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -182,7 +182,7 @@ in order to check which configurations are possible and how the default values a The hardware related tasks are mainly handled by the CbTarragonDriver module. To view the content of the module's manifest file, use the following command: -.. code-block:: sh +.. code-block:: console less /usr/libexec/everest/modules/CbTarragonDriver/manifest.yaml @@ -201,7 +201,7 @@ Here is an example of how to change the "connector_type" parameter of the CbTarr Snippet of a EVerest configuration file: -.. code-block:: sh +.. code-block:: yaml tarragon_bsp: module: CbTarragonDriver @@ -214,7 +214,7 @@ By following these guidelines, you can now customize and manage your EVerest cha to suit your hardware and application requirements. After adjusting the configuration file, you have to restart the EVerest charging stack to apply the changes: -.. code-block:: sh +.. code-block:: console systemctl restart everest @@ -241,7 +241,7 @@ charging stack and to follow the charging process in real time. The EVerest log should look like this: -.. code-block:: sh +.. code-block:: console root@tarragon:~# journalctl -f -u everest -n 50 2024-06-19T19:26:08.986317+0200 tarragon systemd[1]: Started EVerest. @@ -292,7 +292,7 @@ Therefore, the duty cycle should directly switch from 100% to ~26.7%. The duty c The last EVerest log messages should look like this: -.. code-block:: sh +.. code-block:: console 2024-06-20T07:45:49.386995+0200 tarragon manager[18942]: [INFO] tarragon_bsp:Cb :: CP state change from A to B, U_CP+: 9637 mV, U_CP-: -2 mV Read PP ampacity value: A_16 (U_PP: 3297 mV) @@ -307,7 +307,7 @@ EVSE Test Adapter. After switching the CP state from "B" to "C", the EVSE contactor should close and the charging process should start. The last EVerest log messages should look like this: -.. code-block:: sh +.. code-block:: console 2024-06-21T07:45:50.605759+0200 tarragon manager[5733]: [INFO] tarragon_bsp:Cb :: CP state change from B to C, U_CP+: 5996 mV, U_CP-: -11817 mV 2024-06-21T07:45:50.766409+0200 tarragon manager[5733]: [INFO] tarragon_bsp:Cb :: Closing contactor... @@ -317,7 +317,7 @@ The charging process can be stopped by a CP state change from "C" to "B" via the The last EVerest log messages should look like this: -.. code-block:: sh +.. code-block:: console 2024-06-21T07:48:04.406373+0200 tarragon manager[5733]: [INFO] tarragon_bsp:Cb :: CP state change from C to B, U_CP+: 8842 mV, U_CP-: -11826 mV 2024-06-21T07:48:04.641265+0200 tarragon manager[5733]: [INFO] tarragon_bsp:Cb :: Opening contactor... @@ -329,7 +329,7 @@ from "B" to "C". The last EVerest log messages after removing the plug should look like this: -.. code-block:: sh +.. code-block:: console 2024-06-21T07:52:51.287007+0200 tarragon manager[5733]: [INFO] tarragon_bsp:Cb :: CP state change from B to A, U_CP+: 11927 mV, U_CP-: -11970 mV 2024-06-21T07:52:51.368428+0200 tarragon manager[5733]: [INFO] tarragon_bsp:Cb :: handle_pwm_off: Setting new duty cycle of 100.00% diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 073592c..2d4cd78 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -98,7 +98,7 @@ The most important points are summarised here: used to initialize or update the device model database. To update a component config file, just the place a `component config file `_ in the same directory structure in the DeviceModelConfigPath and change the values accordingly. - Importent keys of the component config files are: + Important keys of the component config files are: - `standardized/InternalCtrlr.json: ChargePointId`: In "attributes" adapt the "value" key to configure the ChargePointId. Used to identify the Charging Station. - `standardized/InternalCtrlr.json: NetworkConnectionProfiles`: In "attributes" adapt the "ocppCsmsUrl" key. The URL in "ocppCsmsUrl" is used to connect to the CSMS.