Charge SOM: Add logging and debugging section

docs/source/cb_energy.rst

@@ -0,0 +1,12 @@
+.. _cb_energy.rst:
+
+**********************
+CB energy
+**********************
+
+.. note::
+    CB Energy is currently intended only for connecting an EVerest AC charger. In the future, bi-directional
+    charging and service operations are planned, which can also be used specifically for DC chargers.
+    Feel free to contact us (:ref:`contact`) if we have sparked your interest in using CB Energy for your DC solution.
+
+.. include:: ../../includes/cb_energy.inc

docs/source/development.rst

@@ -0,0 +1,113 @@
+.. _development.rst:
+
+.. include:: ../../includes/development.inc
+
+.. _cross_compiling:
+
+Cross-compiling for Charge SOM
+==============================
+
+Another way to integrate custom applications into the firmware image is to cross-compile the application
+for Charge SOM and include it in the image. A pre-requisite for this is to have the latest firmware image
+as a developer build. Always keep in mind, if you want to build a new EVerest module it must be
+compatible to the EVerest release within the firmware. Please have a look at the official
+`EVerest documentation <https://everest.github.io/nightly/dev_tools/edm.html#setting-up-and-updating-a-workspace>`_,
+how to checkout a dedicated EVerest release.
+
+#. On an Ubuntu or Debian-based Linux distribution, install the cross-compilers for Charge SOM.
+
+   .. code-block:: console
+
+      sudo apt install build-essential libc6-arm64-cross gcc-aarch64-linux-gnu binutils-arm-linux-gnueabihf gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
+
+#. Download chargebyte's `digital certificate <https://chargebyte.com/controllers-and-modules/evse-controllers/charge-control-c#downloads>`_
+   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.
+
+   .. code-block:: console
+
+      rauc extract --keyring=<chargebyte_certificate>.crt <shipped_firmware>.image bundle-staging
+
+   .. note::
+      Alternatively, if the above command does not work, you can use the following command:
+       .. code-block:: console
+
+          unsquashfs -d bundle-staging <shipped_firmware>.image
+
+      But this will not verify the signature of the firmware image.
+
+#. Mount the ext4 root filesystem image as a loop device.
+
+   .. code-block:: console
+
+      sudo mkdir -p /mnt/rootfs
+      sudo mount bundle-staging/core-image-minimal-chargesom.ext4 /mnt/rootfs
+
+#. Create a new directory in the folder where the new module was created (my-module) and create a new
+   file called :code:`toolchain.cmake`. This file is used to set the toolchain for the cross-compilation.
+
+   .. code-block:: console
+
+      cd my-module
+      mkdir toolchain
+      cd toolchain
+      touch toolchain.cmake
+
+
+#. Store the following lines in the :code:`toolchain.cmake` file:
+
+   .. literalinclude:: ../../includes/_static/files/toolchain.cmake
+
+#. Create a new :code:`build` directory in "my-module" and navigate to it.
+
+   .. code-block:: console
+
+      mkdir build
+      cd build
+
+#. Run the following command inside to configure the build.
+
+   .. code-block:: console
+
+      cmake -DCMAKE_TOOLCHAIN_FILE=../toolchain/toolchain.cmake -DCMAKE_SYSROOT=/mnt/rootfs ..
+
+#. When this ends successfully, start cross-compiling using :code:`make`:
+
+   .. code-block:: console
+
+      make install -j$(nproc)
+
+#. Test that the resulting binaries are compiled for Charge SOM as a target:
+
+   .. code-block:: console
+
+      file dist/libexec/everest/modules/MyModule/MyModule
+
+   The output should be something like:
+
+   .. code-block:: console
+
+      dist/libexec/everest/modules/MyModule/MyModule: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV),
+      dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, BuildID[sha1]=ad2342fdd3b8fb1949fc3e13b77382d3da72f28a, for GNU/Linux 3.7.0, stripped
+
+#. The resulting binary and manifest file can be copied to the previously mounted root filesystem.
+
+   .. code-block:: console
+
+      cp dist/libexec/everest/modules/MyModule /mnt/rootfs/usr/libexec/everest/modules/
+
+#. umount the loop device.
+
+   .. code-block:: console
+
+      sudo umount /mnt/rootfs
+
+#. Make sure that the customized filesystem is in a clean state.
+
+   .. code-block:: console
+
+      fsck.ext4 -f bundle-staging/core-image-minimal-chargesom.ext4
+
+#. Follow the steps under the section :ref:`firmware_customization` to install your PKI certificate, pack
+   the modified root filesystem image again into the firmware update image, and test the new firmware image.
+
+.. include:: ../../includes/development_debugging_and_logging.inc

docs/source/everest_charging_stack.rst

@@ -0,0 +1,39 @@
+.. _everest_charging_stack.rst:
+
+**********************
+EVerest charging stack
+**********************
+
+.. include:: ../../includes/everest_introduction_to_everest.inc
+
+.. include:: ../../includes/everest_basic_configuration.inc
+
+Below is an example configuration file provided by chargebyte in its images:
+
+.. literalinclude:: _static/files/bsp-only-dc.yaml
+
+The use case described in this configuration file includes the following:
+
+* DC charging mode
+* No TLS (Transport Layer Security) enabled for HLC (High Level Communication)
+* 3 phase, 16A fuse limit
+* Simulation of the IMD (Insulation Monitoring Device)
+* Simulation of the DC Supply Device
+
+An overview of the EVerest modules is shown in the next section.
+
+.. include:: ../../includes/everest_overview_of_everest_modules.inc
+
+**DCSupplySimulator** (`view on GitHub <https://github.com/EVerest/everest-core/blob/main/modules/simulation/DCSupplySimulator/manifest.yaml>`__)
+
+This module simulates a DC power supply device.
+
+**CbChargeSOMDriver** (`view on GitHub <https://github.com/chargebyte/everest-chargebyte/tree/main/modules/CbChargeSOMDriver>`__)
+
+This is the Hardware Abstraction Layer (HAL) for Charge SOM in EVerest. It implements
+the `evse_board_support <https://github.com/EVerest/everest-core/blob/main/interfaces/evse_board_support.yaml>`_
+interface, enabling communication with the :code:`EvseManager` and control of the board. The EVerest community
+often refers to these HAL modules as BSPs, such as MicroMegaWattBSP and PhyVersoBSP. This module is
+essential for controlling the Charge SOM.
+
+.. include:: ../../includes/everest_further_reading.inc

docs/source/getting_started.rst

@@ -178,6 +178,7 @@ changes. Just type "systemctl restart everest" to restart the EVerest charging s
    start. Therefore, it is recommended to back up the original configuration file before making
    changes.
 
+.. _start_charging_and_monitoring:
 
 Starting and Monitoring the Charging Process
 --------------------------------------------
@@ -186,7 +187,8 @@ Before we start the first charging session, we shall open the EVerest log to mon
 process. The EVerest log is stored in the systemd journal and can be accessed via the journalctl
 command. The journalctl command provides a lot of options to filter the log messages. 
 Now just type "journalctl -f -u everest -n 50" to see the last 50 log messages of the EVerest
-charging stack and to follow the charging process in real time.
+charging stack and to follow the charging process in real time. For more information about the
+EVerest log, see the :ref:`logging_and_debugging` chapter.
 
 The EVerest log should look like this:
 

docs/source/index.rst

@@ -20,3 +20,7 @@ Charge SOM Evaluation Kit.
    :caption: Contents:
 
    getting_started
+   everest_charging_stack
+   cb_energy
+   development
+   troubleshooting

docs/source/troubleshooting.rst

@@ -0,0 +1,103 @@
+.. _troubleshooting.rst:
+
+Troubleshooting
+===============
+
+Frequently Asked Questions
+--------------------------
+
+.. contents::
+   :local:
+
+
+Is it possible to use the Charge SOM as an EV simulator?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Charge SOM hardware is not designed to be used as an EV simulator. Please refer to our
+`website <https://www.chargebyte.com/>`_ for more suitable products.
+
+
+I want to control EVerest via CAN, how can I achieve this?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently, there is no such EVerest module available, you will need to implement it on your own. But
+at least there is a `module <https://github.com/EVerest/everest-core/tree/main/modules/DPM1000>`_
+and a `library <https://github.com/EVerest/everest-core/tree/main/lib/staging/can_dpm1000>`_,
+which uses the CAN interface.
+
+
+How can I access the EVerest admin panel on Charge SOM?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently, the Charge SOM does not have integrated the `EVerest admin panel <https://github.com/EVerest/everest-admin-panel>`_
+Please use your development environment to set up your configuration file. Alternatively, you can use a plain text
+editor.
+
+
+Does EVerest on Charge SOM support ISO 15118-20 yet?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The required module for ISO 15118-20 has been included in the image since the Charge SOM EVerest release 0.2.0.
+Please note that the implementation is still under development.
+
+
+How do I set up OCPP 2.0.1 on Charge SOM with EVerest?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To support OCPP 2.0.1, the EVerest OCPP201 module must be integrated into the EVerest configuration.
+This module uses the `libocpp library <https://github.com/EVerest/libocpp>`_ to implement the OCPP 2.0.1
+protocol.
+The `OCPP201 module documentation <https://github.com/EVerest/everest-core/blob/main/modules/OCPP201/doc.rst>`_
+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 <https://github.com/EVerest/libocpp/tree/v0.16.2/config/v201/component_config>`_
+   in the same directory structure in the DeviceModelConfigPath and change the values accordingly.
+   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.
+   - `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 <https://github.com/EVerest/libocpp/blob/main/doc/v2/ocpp_201_device_model_initialization.md>`_.
+
+I tried to compile chargebyte's Hardware EVerest Modules, but it fails to build. How can it fix this?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The EVerest mainline development is very dynamic and doesn't guarantee any
+stable API along the EVerest modules. So after almost every EVerest release,
+chargebyte needs to adapt their modules to the latest API changes.
+
+Please have a look at the `compatibility matrix <https://github.com/chargebyte/everest-chargebyte/blob/main/README.md>`_
+to see which EVerest release works with which chargebyte EVerest Modules release.
+
+
+I would like to implement a custom Modbus device in EVerest. Where should I start?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+EVerest already has a module which takes care of Modbus communication. Please have a look at
+`SerialCommHub <https://everest.github.io/nightly/_generated/modules/SerialCommHub.html>`_,
+and let your module interact with this module via the `serial_communication_hub` interface.
+
+.. _contact:
+
+.. include:: ../../includes/troubleshooting_contact.inc

includes/_static/files/toolchain.cmake

@@ -0,0 +1,52 @@
+set(CMAKE_SYSTEM_NAME Linux)
+
+if(EXISTS ${CMAKE_SYSROOT} AND IS_DIRECTORY ${CMAKE_SYSROOT})
+  execute_process(COMMAND file ${CMAKE_SYSROOT}/bin/bash.bash
+		  OUTPUT_VARIABLE TARGET_BASH_OUTPUT)
+  if(TARGET_BASH_OUTPUT MATCHES aarch64)
+    message(STATUS "Setting architecture to aarch64")
+    set(CMAKE_SYSTEM_PROCESSOR aarch64)
+    set(CMAKE_C_COMPILER /usr/bin/aarch64-linux-gnu-gcc)
+    set(CMAKE_CXX_COMPILER /usr/bin/aarch64-linux-gnu-g++)
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} " CACHE STRING "" FORCE )
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} " CACHE STRING "" FORCE )
+  else()
+    message(STATUS "Setting architecture to arm")
+    set(CMAKE_SYSTEM_PROCESSOR arm)
+    set(CMAKE_C_COMPILER /usr/bin/arm-linux-gnueabihf-gcc)
+    set(CMAKE_CXX_COMPILER /usr/bin/arm-linux-gnueabihf-g++)
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-psabi" CACHE STRING "" FORCE )
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-psabi" CACHE STRING "" FORCE )
+  endif()
+else()
+  message(FATAL_ERROR "ERROR: SYSROOT '${CMAKE_SYSROOT}' not found!!!")
+endif()
+
+ if(CMAKE_BUILD_TYPE MATCHES Debug)
+    # Debug flags
+    message("Enabling Debug build")
+    set(CMAKE_CXX_FLAGS_DEBUG "-g")
+else()
+    # Enable compiler optimization flags
+    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Os")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Os")
+
+    # Strip debug symbols
+    set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s")
+endif()
+
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -L${CMAKE_SYSROOT}/usr/lib")
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -L${CMAKE_SYSROOT}/usr/lib")
+
+set(ENV{PKG_CONFIG_PATH} "${CMAKE_SYSROOT}/usr/lib/pkgconfig:$ENV{PKG_CONFIG_PATH}")
+
+set(CMAKE_CXX_STANDARD_LIBRARIES "${CMAKE_SYSROOT}/usr/lib/libstdc++.so")
+
+set(NODEJS_INCLUDE_DIR /usr/include/node) # make sure that nodejs is installed. If not, sudo apt-get install nodejs-dev
+
+set(PYTHON_INCLUDE_DIRS "${CMAKE_SYSROOT}/usr/include/python3.10")
+set(PYTHON_LIBRARIES "${CMAKE_SYSROOT}/usr/lib/libpython3.10.so")
+
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)