diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml new file mode 100644 index 0000000..cafca54 --- /dev/null +++ b/.github/workflows/linkcheck.yml @@ -0,0 +1,28 @@ +name: Link check + +# Allow to trigger on pull requests and manually via Github Actions +on: + pull_request: + workflow_dispatch: + +jobs: + build: + # Use Ubuntu as environment + runs-on: ubuntu-latest + + steps: + - name: Checkout repository with submodules + uses: actions/checkout@v4 + with: + submodules: recursive + fetch-depth: 0 + + - name: Initialize and update submodules + run: git submodule update --init --recursive + # This external action cares about all the sphinx stuff + - name: Build project + uses: ammaraskar/sphinx-action@4.3.2 + with: + build-command: "sphinx-build -b linkcheck source/ build/" + docs-folder: "docs/" + diff --git a/.gitignore b/.gitignore index e69de29..f912c7a 100644 --- a/.gitignore +++ b/.gitignore @@ -0,0 +1,27 @@ +# Ignore node_modules directory +node_modules/ + +# Ignore build output +dist/ + +# Ignore IDE and editor files +*~ +.vscode/ +.idea/ + +# Ignore logs and temporary files +*.log +*.tmp + +# Ignore environment-specific files +.env +.env.local +.env.development +.env.production + +# Ignore sensitive or private information +secrets.txt +credentials.json + +# Ignore output folder for testing +output/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..011bc4e --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "includes"] + path = includes + url = https://github.com/chargebyte/chargebyte-docs.git + branch = shared-docs diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..ba8f698 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,16 @@ +version: "2" + +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + +python: + install: + - requirements: docs/requirements.txt + +sphinx: + configuration: docs/source/conf.py + +submodules: + include: all #includes all git-submodules diff --git a/README.rst b/README.rst index 84a6420..347f4e7 100644 --- a/README.rst +++ b/README.rst @@ -1,16 +1,64 @@ -chargebyte GmbH Product Documentation -============================= +Charge SOM Product Documentation +================================ -Welcome to the documentation for products of chargebyte GmbH. +This is the product documentation project for the Charge SOM, a product of chargebyte GmbH. +This documentation is intended for users, developers, and administrators of the Charge SOM. +This documentation is hosted on Read the Docs and can be accessed at +https://chargebyte-docs.readthedocs.io/en/latest/. -This documentation contains all necessary information and guides for the use and understanding of our products. Contents: --------- -- Product specifc User Guides and Manuals (In Progress) -- Developer Documentation (In Progress) -- FAQs and Troubleshooting (In Progress) +- Charge SOM User Guide + +Repo initialization: +------------------- +This repository is using git submodules to share documents between the user guides. +After cloning of the project please execute the following command: + +git submodule update --init --force --remote + + +Building the documentation locally: +----------------------------------- + +To build the documentation locally, you need to have Python and pip installed on your system. +You can install the required dependencies by running the following command: + +pip install -r requirements.txt + +After installing the dependencies, you can build the documentation by running the following command: + +sphinx-build -a docs/source {output_directory} + +The output directory is the directory where the generated HTML files will be stored. + + +Contributing: +------------- + +If you would like to contribute to the documentation, please fork the repository and create a pull +request with your changes. Please make sure to follow the guidelines for contributing to the +documentation: + +- The branch name for the pull request should be `everest/csom_{your_branch_name}`. +- Maximum line length should be 120 characters (Preferably 100 characters). +- Images should be stored in the `docs/source/_static/images` directory +- CSS files should be stored in the `docs/source/_static/css` directory +- Source and config files should be stored in the `docs/source/_static/files` directory +- A documentation file should be written in reStructuredText format +- A documentation file should start with referenceable label of the file name (e.g. ".. _hardware.rst:") +- Sections and chapters should be separated by one blank line after the title and two blank lines before the title +- Sections with a chapter title before, need to have only one blank line before the title +- First letters of section and chapter titles should be capitalized (e.g. "Charge SOM User Guide") + + +License: +-------- + +See the LICENSE file for license rights and limitations (Apache 2.0). + Contact: -------- @@ -18,4 +66,3 @@ Contact: If you have any questions or inquiries, please contact our support team at https://chargebyte.com/support. Thank you for using products from chargebyte GmbH! - diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..240edc8 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx==7.3.7 +sphinx-copybutton +linuxdoc diff --git a/docs/source/_static/cb_logo.png b/docs/source/_static/cb_logo.png new file mode 100755 index 0000000..acf62cc Binary files /dev/null and b/docs/source/_static/cb_logo.png differ diff --git a/docs/source/_static/css/cb_theme.css b/docs/source/_static/css/cb_theme.css new file mode 100644 index 0000000..9266f45 --- /dev/null +++ b/docs/source/_static/css/cb_theme.css @@ -0,0 +1,276 @@ +@import '../classic.css'; + +@font-face { + font-family: "Open Sans"; + src: url(../font/OpenSans-Light.ttf); +} + +body { + background-color: #111827 !important; + font-family: "Open Sans", sans-serif !important; +} + +.document .bodywrapper { + background-color: #111827 !important; +} + +.document .bodywrapper .body { + background-color: #111827 !important; + width: 100% !important; + max-width: 92% !important; + font-family: "Open Sans", sans-serif !important; + color: #fff !important; + box-shadow: rgba(6, 24, 44, 0.4) 0px 0px 0px 2px, rgba(6, 24, 44, 0.65) 0px 4px 6px -1px, rgba(255, 255, 255, 0.08) 0px 1px 0px inset !important; +} + +.document .bodywrapper .body p { + font-size: 18px !important; + font-family: "Open Sans", sans-serif !important; + font-weight: 100 !important; + line-height: 1.5 !important; +} + +.document .bodywrapper .body p span.caption-text { + font-size: 30px !important; +} + +.document .bodywrapper .body p strong, +.document .bodywrapper .body p a span { + color: #ff8200 !important; + font-size: 20px !important; +} + +.document .bodywrapper .body .toctree-wrapper.compound ul li.toctree-l1 a { + color: #ff8200 !important; + font-size: 24px !important; + font-family: "Open Sans", sans-serif !important; + font-weight: 100 !important; + line-height: 2 !important; +} + +.document .bodywrapper .body .toctree-wrapper.compound ul li ul li.toctree-l2 a { + font-family: "Open Sans", sans-serif !important; + color: #fff !important; + font-size: 18px !important; +} + +.document .sphinxsidebar { + background-color: #111827 !important; +} + +.document .sphinxsidebar .sphinxsidebarwrapper .logo { + margin: 0 !important; +} + +.document .sphinxsidebar .sphinxsidebarwrapper h4 { + font-size: 18px !important; + font-family: "Open Sans", sans-serif !important; +} + +.document .sphinxsidebar .sphinxsidebarwrapper .topless a { + font-size: 18px !important; + font-family: "Open Sans", sans-serif !important; + color: #fff !important; +} + +.document .sphinxsidebar .sphinxsidebarwrapper p { + margin: 5px 10px 10px 0px !important; + font-family: "Open Sans", sans-serif !important; +} + +.document .sphinxsidebar .sphinxsidebarwrapper #searchlabel { + font-size: 18px !important; + font-family: "Open Sans", sans-serif !important; + color: #fff !important; +} + +.document .sphinxsidebar a { + color: #fff !important; +} + +.document .bodywrapper h1 { + font-size: 50px !important; + font-family: "Open Sans", sans-serif !important; + font-weight: 800 !important; + background-color: transparent !important; + color: #fff !important; + text-align: center !important; + border-bottom: none !important; +} + +.document .bodywrapper h2 { + font-size: 36px !important; + font-family: "Open Sans", sans-serif !important; + font-weight: 600 !important; + margin: 0 !important; + padding: 0 !important; + border-bottom: none !important; + background-color: #111827 !important; + color: #ff8200 !important; +} + +.document .bodywrapper h3 { + font-size: 30px !important; + font-family: "Open Sans", sans-serif !important; + font-weight: 600 !important; + margin: 0 !important; + padding: 0 !important; + background-color: #111827 !important; + color: #fff !important; + width: fit-content !important; +} + +.document .bodywrapper h4 { + font-size: 26px !important; + font-family: "Open Sans", sans-serif !important; + font-weight: 600 !important; + margin: 0 !important; + padding: 0 !important; + background-color: #ff8200 !important; + border-bottom: none !important; + color: #fff !important; +} + +.document .bodywrapper .highlight { + background: #153659 !important; +} + +.document .bodywrapper section p a { + color: #ff8200 !important; +} + +.document .bodywrapper section img { + background: #1c354f; +} + +.document .bodywrapper .highlight .nt { + color: #8cb0ff !important; +} + +.document .bodywrapper .highlight .c1, +.document .bodywrapper .highlight .s, +.document .bodywrapper .highlight .s2 { + color: #fff !important; +} + +.document .bodywrapper .highlight .nb { + color: #ff8200 !important; +} + +.related { + background-color: #162235 !important; + height: 80px; + display: flex; + flex-direction: column; + justify-content: center; + border-bottom: 1px solid #ccc; +} + +.related ul { + background-color: #162235 !important; +} + +.related ul li { + font-size: 18px !important; + font-weight: 600 !important; + font-family: "Open Sans", sans-serif !important; +} + +.related ul li.right a { + text-transform: capitalize; + padding: 10px 15px; + background-color: #ff8200; + border-radius: 5px; +} + +.related ul li.right a:hover { + padding: 11px 17px; + text-decoration: none; +} + +.footer { + background-color: #111827 !important; +} + +.document .bodywrapper .warning { + background-color: #1c354f !important; + padding: 20px 10px !important; +} + +.document .bodywrapper th, +dl.field-list>dt { + background-color: #1c354f !important; +} + +.document .bodywrapper .note { + background-color: #1c354f !important; +} + +.document .bodywrapper .highlight .go { + color: #ddd !important +} + +.document .bodywrapper code { + background-color: #284a6d !important; +} + +@media only screen and (max-width: 600px) { + .document .bodywrapper { + margin: 0 0 0 150px !important; + } + + .document .bodywrapper .body { + max-width: 78% !important; + } + + .document h1 { + margin: 0 !important; + padding: 0 !important; + font-size: 25px !important; + } + + .document .bodywrapper h2 { + font-size: 23px !important; + } + + .document .bodywrapper h3 { + font-size: 21px !important; + } + + .document .bodywrapper h4 { + font-size: 19px !important; + } + + .document .sphinxsidebar { + width: 150px !important; + } + + .document .bodywrapper .body p { + font-size: 14px !important; + } + + .document .bodywrapper .body p strong, + .document .bodywrapper .body p a span { + font-size: 17px !important; + } + + .document .bodywrapper .body p span.caption-text { + font-size: 22px !important; + } + + .document .bodywrapper .body .toctree-wrapper.compound ul li.toctree-l1 a { + font-size: 20px !important; + } + + .document .bodywrapper .body .toctree-wrapper.compound ul { + padding: 5px !important; + } + + .document .bodywrapper .body .toctree-wrapper.compound ul li ul li.toctree-l2 a { + font-size: 16px !important; + } + + .document .bodywrapper .body .toctree-wrapper.compound ul li ul { + padding: 0 0 0 10px; + } +} diff --git a/docs/source/_static/files/bsp-only-dc.yaml b/docs/source/_static/files/bsp-only-dc.yaml new file mode 100644 index 0000000..b42d389 --- /dev/null +++ b/docs/source/_static/files/bsp-only-dc.yaml @@ -0,0 +1,116 @@ +# +# This is an example configuration for free DC charging +# +active_modules: + api: + module: API + connections: + evse_manager: + - module_id: connector + implementation_id: evse + error_history: + - module_id: error_history + implementation_id: error_history + bsp: + module: CbChargeSOMDriver + connector: + module: EvseManager + config_module: + connector_id: 1 + charge_mode: DC + evse_id: DE*CHB*E123456*1 + evse_id_din: 49A80737A45678 + session_logging: true + session_logging_path: /tmp/everest-logs + session_logging_xml: false + connections: + bsp: + - module_id: bsp + implementation_id: evse_board_support + slac: + - module_id: evse_slac + implementation_id: main + powersupply_DC: + - module_id: powersupply_dc + implementation_id: main + imd: + - module_id: imd + implementation_id: main + hlc: + - module_id: iso15118_charger + implementation_id: charger + energy_manager: + module: EnergyManager + connections: + energy_trunk: + - module_id: grid_connection_point + implementation_id: energy_grid + grid_connection_point: + module: EnergyNode + config_module: + fuse_limit_A: 16 + phase_count: 3 + connections: + energy_consumer: + - module_id: connector + implementation_id: energy_grid + error_history: + module: ErrorHistory + config_implementation: + error_history: + database_path: /tmp/error_history.db + iso15118_charger: + module: EvseV2G + config_module: + device: eth1 + connections: + security: + - module_id: evse_security + implementation_id: main + evse_security: + module: EvseSecurity + config_module: + private_key_password: "123456" + evse_slac: + module: EvseSlac + config_implementation: + main: + device: eth1 + auth: + module: Auth + config_module: + connection_timeout: 10 + prioritize_authorization_over_stopping_transaction: true + selection_algorithm: PlugEvents + connections: + token_provider: + - module_id: token_provider + implementation_id: main + token_validator: + - module_id: token_validator + implementation_id: main + evse_manager: + - module_id: connector + implementation_id: evse + powersupply_dc: + module: DCSupplySimulator + imd: + module: IMDSimulator + token_provider: + module: DummyTokenProvider + config_implementation: + main: + timeout: 10 + token: DEADBEEF + type: RFID + connections: + evse: + - module_id: connector + implementation_id: evse + token_validator: + module: DummyTokenValidator + config_implementation: + main: + sleep: 0.25 + validation_reason: Token seems valid + validation_result: Accepted diff --git a/docs/source/_static/font/OpenSans-Light.ttf b/docs/source/_static/font/OpenSans-Light.ttf new file mode 100644 index 0000000..ea175cc Binary files /dev/null and b/docs/source/_static/font/OpenSans-Light.ttf differ diff --git a/docs/source/_static/font/OpenSans-Regular.ttf b/docs/source/_static/font/OpenSans-Regular.ttf new file mode 100644 index 0000000..67803bb Binary files /dev/null and b/docs/source/_static/font/OpenSans-Regular.ttf differ diff --git a/docs/source/_static/images/admin_panel_bsp_only.png b/docs/source/_static/images/admin_panel_bsp_only.png new file mode 100755 index 0000000..3255b3e Binary files /dev/null and b/docs/source/_static/images/admin_panel_bsp_only.png differ diff --git a/docs/source/_static/images/attention_sign.png b/docs/source/_static/images/attention_sign.png new file mode 100755 index 0000000..bf91aa7 Binary files /dev/null and b/docs/source/_static/images/attention_sign.png differ diff --git a/docs/source/_static/images/dc_charger_charge_som_setup.svg b/docs/source/_static/images/dc_charger_charge_som_setup.svg new file mode 100755 index 0000000..6021068 --- /dev/null +++ b/docs/source/_static/images/dc_charger_charge_som_setup.svg @@ -0,0 +1,160 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/_static/images/dimensions.svg b/docs/source/_static/images/dimensions.svg new file mode 100755 index 0000000..31c9470 --- /dev/null +++ b/docs/source/_static/images/dimensions.svg @@ -0,0 +1,9096 @@ + +image/svg+xml4x Ø4 +120,00±0,3113,506,50 + +107,30±0,382,6524,65PCB thickness: 1,56±13% diff --git a/docs/source/_static/images/motor_logic.svg b/docs/source/_static/images/motor_logic.svg new file mode 100755 index 0000000..77ddc61 --- /dev/null +++ b/docs/source/_static/images/motor_logic.svg @@ -0,0 +1,288 @@ + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + IN1 + IN2 + M+ + M- + 1 + 0 + 1 + 0 + 1 + 0 + 1 + 0 + + + + + + + + + + diff --git a/docs/source/_static/images/putty_config_serial_1.png b/docs/source/_static/images/putty_config_serial_1.png new file mode 100755 index 0000000..453893e Binary files /dev/null and b/docs/source/_static/images/putty_config_serial_1.png differ diff --git a/docs/source/_static/images/putty_config_serial_2.png b/docs/source/_static/images/putty_config_serial_2.png new file mode 100755 index 0000000..ce87a29 Binary files /dev/null and b/docs/source/_static/images/putty_config_serial_2.png differ diff --git a/docs/source/_static/images/putty_config_ssh_fallback_ip.png b/docs/source/_static/images/putty_config_ssh_fallback_ip.png new file mode 100755 index 0000000..c191fe3 Binary files /dev/null and b/docs/source/_static/images/putty_config_ssh_fallback_ip.png differ diff --git a/docs/source/_static/images/rauc_status.png b/docs/source/_static/images/rauc_status.png new file mode 100755 index 0000000..37c9655 Binary files /dev/null and b/docs/source/_static/images/rauc_status.png differ diff --git a/docs/source/_static/images/rauc_status_mark_other.png b/docs/source/_static/images/rauc_status_mark_other.png new file mode 100755 index 0000000..4094e1d Binary files /dev/null and b/docs/source/_static/images/rauc_status_mark_other.png differ diff --git a/docs/source/cb_energy.rst b/docs/source/cb_energy.rst new file mode 100644 index 0000000..5857cfb --- /dev/null +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..712bd95 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,40 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Charge SOM User Guide' +copyright = '2025, chargebyte GmbH' +author = 'chargebyte GmbH' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['linuxdoc.rstFlatTable', 'sphinx_copybutton'] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'classic' +html_static_path = ['_static'] +html_logo = '_static/cb_logo.png' +html_css_files = [ + 'css/cb_theme.css', +] + +# Disable link "index" +html_use_index = False + +# Disable link "Show Source" +html_show_sourcelink = False + +# -- Options for the linkcheck builder --------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder + +linkcheck_anchors = False diff --git a/docs/source/development.rst b/docs/source/development.rst new file mode 100644 index 0000000..a8793d5 --- /dev/null +++ b/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 `_, +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 `_ + 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=.crt .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 .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 diff --git a/docs/source/everest_charging_stack.rst b/docs/source/everest_charging_stack.rst new file mode 100644 index 0000000..f8eee0e --- /dev/null +++ b/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 `__) + +This module simulates a DC power supply device. + +**CbChargeSOMDriver** (`view on GitHub `__) + +This is the Hardware Abstraction Layer (HAL) for Charge SOM in EVerest. It implements +the `evse_board_support `_ +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 diff --git a/docs/source/firmware.rst b/docs/source/firmware.rst new file mode 100644 index 0000000..2dce4d9 --- /dev/null +++ b/docs/source/firmware.rst @@ -0,0 +1,48 @@ +.. _firmware.rst: + +.. include:: ../../includes/firmware_upgrade.inc + + +Partitioning +------------- + +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. + +.. list-table:: eMMC Partitioning + :header-rows: 1 + :widths: 20 10 50 + + * - Partition + - Size + - Description + * - /dev/mmcblk0p1 + - 2 GB + - Root file system A + * - /dev/mmcblk0p2 + - 2 GB + - Root file system B + * - /dev/mmcblk0p3 + - 3.3 GB + - Extended Partition Container + * - /dev/mmcblk0p5 + - 2.8 GB + - Data Partition (/srv). This partition can be accessed by both root file systems and will be not changed during update process. + * - /dev/mmcblk0p6 + - 256 MB + - Logging file system A (/var/log) + * - /dev/mmcblk0p7 + - 256 MB + - Logging file system B (/var/log) + +.. image:: ../../includes/_static/images/mountpoints.svg + :alt: Filesystem-Mountpoints + :align: center + +.. adding a center-aligned caption for the image +.. raw:: html + +
+ Filesystem Mountpoints +
+ +.. include:: ../../includes/firmware_programming.inc diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 0000000..36283f4 --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,371 @@ +.. _getting_started.rst: + +Getting Started +=============== + +This chapter is intended to help you get started as easily as possible with EV charging together +with the Charge SOM Evaluation Kit and the EVerest charging stack. For this purpose, a basic DC +charger is set up as an example and explained step by step. + + +Setting Up the Hardware +------------------------ + + +Hardware Components +^^^^^^^^^^^^^^^^^^^ + +The following hardware components are required to set up the basic DC charger: + +- Charge SOM Evaluation Kit +- 12 V DC Power Supply +- Ethernet cable for SSH connection or USB to serial adapter for serial connection +- DIN70121 or ISO15118-2 EV simulator (e.g. `Charge Module S Evaluation board `_. ) +- Wiring material + + +Hardware Overview +^^^^^^^^^^^^^^^^^ + +The following figure shows the basic setup of the DC charger with the Charge SOM Evaluation Kit: + +.. figure:: _static/images/dc_charger_charge_som_setup.svg + :width: 900pt + + Figure: Basic Setup of the DC charger with the Charge SOM + +.. note:: + The pin assignment of the Charge SOM Evaluation Kit can be found in the datasheet. + +.. note:: + Before you start setting up the hardware, please check whether the HW components used are also + listed in `Hardware Components section`_. + +.. _Hardware Components section: #hardware-components + + +First Startup +------------- + +Boot Process +^^^^^^^^^^^^ + +Here are some key points about the boot process of the Charge controller: + +- The file system basically consists of three ext4 partitions. Two partitions are used as slots for + the RAUC update process. The third partition is not touched by the RAUC update process and is usually + used for storing update bundles, logs, etc. +- After connecting the Charge controller to the power supply, the U-Boot bootloader starts the + currently active slot managed by RAUC. +- The LED status indicators on the carrier board provide information about the current status of + the boot process. +- EVerest is automatically started with the default configuration of chargebyte after the boot + process is completed. The initial configuration is explained in the `Initial Configuration`_ section. + + +Understanding LED Status Indicators +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Now you can connect the Charge SOM Evaluation Kit (X24) to the power supply. The LED status indicator on the +carrier board provide information about the current status of the boot process. The following table +shows the meaning of the LED status indicators: + +.. raw:: html + +
+ Table: Charge SOM Evaluation Kit LED Status Indicators +
+ ++--------------------------+---------------------------------+--------------------------------------+ +| State | LED indication | Behavior | ++==========================+=================================+======================================+ +| Boot process running | LED (red) | periodic blinking for approx. 4 sec. | ++--------------------------+---------------------------------+--------------------------------------+ +| Operating system running | LED (red) | rhythmic blinking | ++--------------------------+---------------------------------+--------------------------------------+ + + +.. include:: ../../includes/connecting.inc + + +Initial Configuration +--------------------- + +Now you are connected to the Charge SOM and we can take a deeper look at the initial +configuration. + +The configuration files of the EVerest charging stack are stored in the directory "/etc/everest". +EVerest uses the YAML format for the configuration files. EVerest runs as a systemd service that +by default uses "/etc/everest/config.yaml" as a configuration setup. If you take a look at the +content of the configuration file, you will see that it is only a reference to the +"bsp-only-dc.yaml" file. + +.. note:: + If you create an own configuration file, you can also store it in the "/etc/everest" directory + and create a symbolic link to it like "ln -sf /etc/everest/my-config.yaml /etc/everest/config.yaml". + +.. code-block:: bash + + root@chargesom:/etc/everest# ls -l /etc/everest/ + total 28 + -rw-r--r-- 1 root root 1134 Jun 20 07:45 bsp-only-dc.yaml + lrwxrwxrwx 1 root root 14 Jun 25 19:26 config.yaml -> my-config.yaml + +Let's take a look at the content of the bsp-only-dc.yaml configuration file. This file is already +prepared for the basic DC charger setup. + +Just type "less /etc/everest/bsp-only-dc.conf" to see the content of the configuration file: + +.. literalinclude:: _static/files/bsp-only-dc.yaml + :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: + +.. figure:: _static/images/admin_panel_bsp_only.png + :width: 600pt + :name: admin_panel_bsp_only + + Figure: EVerest admin panel view of the bsp-only-dc.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 CbChargeSOMDriver module. +The configuration of the CbChargeSOMDriver module can be found in "/usr/libexec/everest/modules/CbChargeSOMDriver" +directory. + +Each module has a description of all configuration parameter including their defaults. +This file is called "manifest.yaml" and is stored in the main directory of the module. +In order to see the content of the configuration file you can take a look using +"less /usr/libexec/everest/modules/CbChargeSOMDriver/manifest.yaml" to see the +content of the manifest file and check whether the configuration fits to your hardware setup. + +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. + +Here is an excerpt of an EVerest configuration to change the parameter "evse_id" to +"MY*CUS*T654321*1" of the CbChargeSOMDriver module. + +.. code-block:: sh + + bsp: + module: CbChargeSOMDriver + connector: + module: EvseManager + config_module: + connector_id: 1 + charge_mode: DC + evse_id: MY*CUS*T654321*1 + +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. + +.. 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. + +.. note:: + If you have made a mistake in the configuration file, the EVerest charging stack will not + 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 +-------------------------------------------- + +Before we start the first charging session, we shall open the EVerest log to monitor the charging +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. For more information about the +EVerest log, see the :ref:`logging_and_debugging` chapter. + +The EVerest log should look like this: + +.. code-block:: sh + + root@chargesom:~# journalctl -f -u everest -n 50 + 2024-12-13T15:45:00.514151+0100 chargesom sh[237]: Starting to migrate EVerest configurations + 2024-12-13T15:45:00.532706+0100 chargesom sh[237]: EVerest configurations migrated successfully + 2024-12-13T15:45:00.561214+0100 chargesom systemd[1]: Started EVerest. + 2024-12-13T15:45:00.779573+0100 chargesom manager[241]: [INFO] manager :: ________ __ _ + 2024-12-13T15:45:00.779573+0100 chargesom manager[241]: [INFO] manager :: | ____\ \ / / | | + 2024-12-13T15:45:00.779573+0100 chargesom manager[241]: [INFO] manager :: | |__ \ \ / /__ _ __ ___ ___| |_ + 2024-12-13T15:45:00.779573+0100 chargesom manager[241]: [INFO] manager :: | __| \ \/ / _ \ '__/ _ \/ __| __| + 2024-12-13T15:45:00.779573+0100 chargesom manager[241]: [INFO] manager :: | |____ \ / __/ | | __/\__ \ |_ + 2024-12-13T15:45:00.779573+0100 chargesom manager[241]: [INFO] manager :: |______| \/ \___|_| \___||___/\__| + 2024-12-13T15:45:00.779573+0100 chargesom manager[241]: [INFO] manager :: + 2024-12-13T15:45:00.781629+0100 chargesom manager[241]: [INFO] manager :: everest-framework 0.17.2 main@v0.17.2-dirty + 2024-12-13T15:45:00.781629+0100 chargesom manager[241]: [INFO] manager :: everest-core 2024.9.0 main@2024.9.0-rc1-40-g1e06aaab-dirty + 2024-12-13T15:45:00.781629+0100 chargesom manager[241]: [INFO] manager :: + 2024-12-13T15:45:00.781629+0100 chargesom manager[241]: [INFO] manager :: Using MQTT broker localhost:1883 + 2024-12-13T15:45:00.811618+0100 chargesom manager[242]: [INFO] everest_ctrl :: Launching controller service on port 8849 + 2024-12-13T15:45:00.862280+0100 chargesom manager[241]: [INFO] manager :: Loading config file at: /etc/everest/config.yaml + 2024-12-13T15:45:01.239004+0100 chargesom manager[241]: [INFO] manager :: Config loading completed in 451ms + 2024-12-13T15:45:03.899562+0100 chargesom manager[260]: [INFO] api:API :: Module api initialized [2594ms] + 2024-12-13T15:45:04.376658+0100 chargesom manager[266]: [INFO] evse_security:E :: Module evse_security initialized [2751ms] + 2024-12-13T15:45:04.704404+0100 chargesom manager[264]: [INFO] energy_manager: :: Module energy_manager initialized [3237ms] + 2024-12-13T15:45:05.093575+0100 chargesom manager[261]: [INFO] auth:Auth :: Module auth initialized [3776ms] + 2024-12-13T15:45:05.237957+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Module evse_slac initialized [3623ms] + 2024-12-13T15:45:05.364804+0100 chargesom manager[269]: [INFO] imd:IMDSimulato :: Module imd initialized [3755ms] + 2024-12-13T15:45:05.485234+0100 chargesom manager[262]: [INFO] bsp:CbChargeSOM :: chargebyte's Charge SOM EVerest module (version: 0.16.0) + 2024-12-13T15:45:05.486334+0100 chargesom manager[262]: [INFO] bsp:CbChargeSOM :: Module bsp initialized [4145ms] + 2024-12-13T15:45:05.569128+0100 chargesom manager[271]: [INFO] powersupply_dc: :: Module powersupply_dc initialized [3777ms] + 2024-12-13T15:45:05.578465+0100 chargesom manager[268]: [INFO] grid_connection :: Module grid_connection_point initialized [4042ms] + 2024-12-13T15:45:05.643080+0100 chargesom manager[270]: [INFO] iso15118_charge :: Module iso15118_charger initialized [3811ms] + 2024-12-13T15:45:05.660663+0100 chargesom manager[265]: [INFO] error_history:E :: Resetting database + 2024-12-13T15:45:05.672632+0100 chargesom manager[273]: [INFO] token_validator :: Module token_validator initialized [3779ms] + 2024-12-13T15:45:05.684368+0100 chargesom manager[265]: [INFO] error_history:E :: Module error_history initialized [4205ms] + 2024-12-13T15:45:05.706916+0100 chargesom manager[272]: [INFO] token_provider: :: Module token_provider initialized [3957ms] + 2024-12-13T15:45:05.857535+0100 chargesom manager[263]: [INFO] connector:EvseM :: Module connector initialized [4295ms] + 2024-12-13T15:45:05.904734+0100 chargesom manager[241]: [INFO] manager :: πŸš™πŸš™πŸš™ All modules are initialized. EVerest up and running [5162ms] πŸš™πŸš™πŸš™ + 2024-12-13T15:45:05.911103+0100 chargesom manager[270]: [INFO] iso15118_charge :: TCP server on eth1 is listening on port [fe80::2c04:d5ff:fe18:78a7%3]:61341 + 2024-12-13T15:45:05.911444+0100 chargesom manager[270]: [INFO] iso15118_charge :: SDP socket setup succeeded + 2024-12-13T15:45:05.937212+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Starting the SLAC state machine + 2024-12-13T15:45:06.137657+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Entered Reset state + 2024-12-13T15:45:06.138098+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: New NMK key: 32:47:36:36:38:36:4F:55:58:34:4A:39:45:4A:46:4A + 2024-12-13T15:45:06.141405+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Received CM_SET_KEY_CNF + 2024-12-13T15:45:06.142173+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Entered Idle state + 2024-12-13T15:45:06.390594+0100 chargesom manager[270]: [INFO] iso15118_charge :: Ignoring bidirectional SupportedEnergyTransferMode + 2024-12-13T15:45:11.539400+0100 chargesom manager[263]: [INFO] connector:EvseM :: Cleaning up any other transaction on start up + 2024-12-13T15:45:11.672232+0100 chargesom manager[263]: [INFO] connector:EvseM :: πŸŒ€πŸŒ€πŸŒ€ Ready to start charging πŸŒ€πŸŒ€πŸŒ€ + 2024-12-13T15:45:11.672232+0100 chargesom manager[263]: [WARN] connector:EvseM void module::EvseManager::ready_to_start_charging() :: No powermeter value received yet! + 2024-12-13T15:45:11.805756+0100 chargesom manager[262]: [INFO] bsp:CbChargeSOM :: handle_enable: Setting new duty cycle of 100.00% + 2024-12-13T15:45:12.119474+0100 chargesom manager[262]: [INFO] bsp:CbChargeSOM :: handle_pwm_off: Setting new duty cycle of 100.00% + 2024-12-13T15:45:12.190889+0100 chargesom manager[263]: [INFO] connector:EvseM :: All errors cleared + 2024-12-13T15:45:12.260924+0100 chargesom manager[262]: [INFO] bsp:CbChargeSOM :: CP state change from PowerOn to A, U_CP+: 12196 mV, U_CP-: -303 mV + 2024-12-13T15:45:12.305158+0100 chargesom manager[262]: [INFO] bsp:CbChargeSOM :: handle_pwm_off: Setting new duty cycle of 100.00% + +Before connecting the CP line between Charge SOM Evaluation Kit and the EV simulator, please make +sure that the following things are fulfilled: + +- GND from X18 is connected to the EV simulator +- PP from X18 is not connected to the EV simulator +- EV simulator is powered up +- EV simulator must configured to DIN 70121 or ISO 15118-2 DC EIM (No TLS) + +After connecting the CP line, a CP state change from "A" to "B" should be visible in the EVerest log. +The duty cycle should directly switch from 100% to 5%. The duty cycle change indicates the EVSE is +now ready for high level communication. + +The EVerest log messages should look like this: + +.. code-block:: sh + + 2024-12-13T15:52:01.800939+0100 chargesom manager[262]: [INFO] bsp:CbChargeSOM :: CP state change from A to B, U_CP+: 9150 mV, U_CP-: -300 mV + 2024-12-13T15:52:01.843375+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Entered Matching state, waiting for CM_SLAC_PARM_REQ + 2024-12-13T15:52:01.959010+0100 chargesom manager[263]: [INFO] connector:EvseM :: SYS Session logging started. + 2024-12-13T15:52:01.960014+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE IEC Session Started: EVConnected + 2024-12-13T15:52:01.962704+0100 chargesom manager[272]: [INFO] token_provider: :: Publishing new dummy token: { + 2024-12-13T15:52:01.962704+0100 chargesom manager[272]: "type": "ISO14443", + 2024-12-13T15:52:01.962704+0100 chargesom manager[272]: "value": "DEADBEEF" + 2024-12-13T15:52:01.962704+0100 chargesom manager[272]: } (RFID) + 2024-12-13T15:52:01.967069+0100 chargesom manager[261]: [INFO] auth:Auth :: Received new token: { + 2024-12-13T15:52:01.967069+0100 chargesom manager[261]: "authorization_type": "RFID", + 2024-12-13T15:52:01.967069+0100 chargesom manager[261]: "id_token": { + 2024-12-13T15:52:01.967069+0100 chargesom manager[261]: "type": "ISO14443", + 2024-12-13T15:52:01.967069+0100 chargesom manager[261]: "value": "DEADBEEF" + 2024-12-13T15:52:01.967069+0100 chargesom manager[261]: } + 2024-12-13T15:52:01.967069+0100 chargesom manager[261]: } + 2024-12-13T15:52:01.970206+0100 chargesom manager[273]: [INFO] token_validator :: Got validation request for token: DEADBEEF + 2024-12-13T15:52:02.220655+0100 chargesom manager[273]: [INFO] token_validator :: Returning validation status: Accepted + 2024-12-13T15:52:02.223254+0100 chargesom manager[261]: [INFO] auth:Auth :: Providing authorization to connector#1 + 2024-12-13T15:52:02.960278+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE IEC Set PWM On (5.000000074505806%) took 0 ms + 2024-12-13T15:52:02.962409+0100 chargesom manager[262]: [INFO] bsp:CbChargeSOM :: handle_pwm_on: Setting new duty cycle of 5.00% + 2024-12-13T15:52:03.105628+0100 chargesom manager[261]: [INFO] auth:Auth :: Result for token: DEADBEEF: ACCEPTED + 2024-12-13T15:52:03.155035+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE IEC EIM Authorization received + 2024-12-13T15:52:03.155499+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE IEC Transaction Started (0 kWh) + 2024-12-13T15:52:03.156415+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE IEC DC mode. We are in 5percent mode so we can continue without further action. + 2024-12-13T15:52:03.156895+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE IEC Charger state: Wait for Auth->PrepareCharging + +After that, the EV simulator should establish a powerline connection to the Charge SOM via SLAC. + +.. code-block:: sh + + 2024-12-13T15:52:04.060237+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): initialized, waiting for CM_START_ATTEN_CHAR_IND + 2024-12-13T15:52:04.076565+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_START_ATTEN_CHAR_IND, going to substate SOUNDING + 2024-12-13T15:52:04.116823+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): needs to be in state WAIT_FOR_START_ATTEN_CHAR for CM_START_ATTEN_CHAR_IND + 2024-12-13T15:52:04.153137+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): needs to be in state WAIT_FOR_START_ATTEN_CHAR for CM_START_ATTEN_CHAR_IND + 2024-12-13T15:52:04.187964+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.195990+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.223092+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.230817+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.259234+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.267262+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.294947+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.302506+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.330610+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.338308+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.365795+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.373390+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.401378+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.409026+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.437202+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.444880+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.473470+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.481479+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.509108+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_MNBC_SOUND_IND + 2024-12-13T15:52:04.517101+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_PROFILE_IND + 2024-12-13T15:52:04.517383+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received all sounds, going to substate FINALIZE_SOUNDING + 2024-12-13T15:52:04.561486+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): Finalize sounding, sending CM_ATTEN_CHAR_IND + 2024-12-13T15:52:04.577453+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): received CM_ATTEN_CHAR_RSP, going to substate WAIT_FOR_SLAC_MATCH + 2024-12-13T15:52:04.615447+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Session (run_id=D895B977488179F2, ev_mac=00:01:87:05:A0:84): Received CM_SLAC_MATCH_REQ, sending CM_SLAC_MATCH_CNF -> session complete + 2024-12-13T15:52:04.616909+0100 chargesom manager[267]: [INFO] evse_slac:EvseS :: Entered Matched state + 2024-12-13T15:52:04.637408+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO SLAC MATCHED + 2024-12-13T15:52:04.661360+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO D-LINK_READY (true) + +Now the EV simulator discovers the V2G service of the Charge SOM and establishes a TCP connection. +Both hosts negotiate the protocol ISO 15118-2 and start a charging session. Since the setup +lacks some components of a real DC charger (e.g. HV contactors, power modules) only the state +ChargeParameterDiscovery will be reached. + +.. code-block:: sh + + 2024-12-13T15:52:06.094909+0100 chargesom manager[270]: [INFO] iso15118_charge :: Received packet from [fe80::201:87ff:fe05:a084]:52403 with security 0x10 and protocol 0x00 + 2024-12-13T15:52:06.094909+0100 chargesom manager[270]: [INFO] iso15118_charge :: SDP requested NO-TLS, announcing NO-TLS + 2024-12-13T15:52:06.094909+0100 chargesom manager[270]: [INFO] iso15118_charge :: sendto([fe80::201:87ff:fe05:a084]:52403) succeeded + 2024-12-13T15:52:06.136758+0100 chargesom manager[270]: [INFO] iso15118_charge :: Incoming connection on eth1 from [a00:f192:0:0:fe80::]:61842 + 2024-12-13T15:52:06.137338+0100 chargesom manager[270]: [INFO] iso15118_charge :: Started new TCP connection thread + 2024-12-13T15:52:06.413206+0100 chargesom manager[270]: [INFO] iso15118_charge :: Handling SupportedAppProtocolReq + 2024-12-13T15:52:06.414011+0100 chargesom manager[270]: [INFO] iso15118_charge :: Protocol negotiation was successful. Selected protocol is ISO15118 + 2024-12-13T15:52:06.445910+0100 chargesom manager[263]: [INFO] connector:EvseM :: CAR ISO V2G SupportedAppProtocolReq + 2024-12-13T15:52:06.457489+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO V2G SupportedAppProtocolRes + 2024-12-13T15:52:06.735253+0100 chargesom manager[270]: [INFO] iso15118_charge :: SessionSetupReq.EVCCID: 00:01:87:05:A0:84 + 2024-12-13T15:52:06.735253+0100 chargesom manager[270]: [INFO] iso15118_charge :: No session_id found or not equal to the id from the preceding v2g session. Generating random session id. + 2024-12-13T15:52:06.735253+0100 chargesom manager[270]: [INFO] iso15118_charge :: Created new session with id 0x17000314371076655851 + 2024-12-13T15:52:06.736833+0100 chargesom manager[263]: [INFO] connector:EvseM :: CAR ISO V2G SessionSetupReq + 2024-12-13T15:52:06.845708+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO V2G SessionSetupRes + 2024-12-13T15:52:07.142205+0100 chargesom manager[263]: [INFO] connector:EvseM :: CAR ISO V2G ServiceDiscoveryReq + 2024-12-13T15:52:07.240688+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO V2G ServiceDiscoveryRes + 2024-12-13T15:52:07.567095+0100 chargesom manager[263]: [INFO] connector:EvseM :: CAR ISO V2G ServiceDetailReq + 2024-12-13T15:52:07.621170+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO V2G ServiceDetailRes + 2024-12-13T15:52:07.921406+0100 chargesom manager[270]: [INFO] iso15118_charge :: SelectedPaymentOption: ExternalPayment + 2024-12-13T15:52:07.924122+0100 chargesom manager[263]: [INFO] connector:EvseM :: CAR ISO V2G PaymentServiceSelectionReq + 2024-12-13T15:52:08.053648+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO V2G PaymentServiceSelectionRes + 2024-12-13T15:52:08.338864+0100 chargesom manager[263]: [INFO] connector:EvseM :: CAR ISO V2G AuthorizationReq + 2024-12-13T15:52:08.391710+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO V2G AuthorizationRes + 2024-12-13T15:52:08.689864+0100 chargesom manager[263]: [INFO] connector:EvseM :: CAR ISO V2G AuthorizationReq + 2024-12-13T15:52:08.764375+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO V2G AuthorizationRes + 2024-12-13T15:52:09.049641+0100 chargesom manager[270]: [INFO] iso15118_charge :: Parameter-phase started + 2024-12-13T15:52:09.049641+0100 chargesom manager[270]: [INFO] iso15118_charge :: Selected energy transfer mode: DC_extended + 2024-12-13T15:52:09.057571+0100 chargesom manager[263]: [INFO] connector:EvseM :: Received EV maximum limits: { + 2024-12-13T15:52:09.057571+0100 chargesom manager[263]: "dc_ev_maximum_current_limit": 0.0, + 2024-12-13T15:52:09.057571+0100 chargesom manager[263]: "dc_ev_maximum_voltage_limit": 0.0 + 2024-12-13T15:52:09.057571+0100 chargesom manager[263]: } + 2024-12-13T15:52:09.058568+0100 chargesom manager[263]: [INFO] connector:EvseM :: CAR ISO V2G ChargeParameterDiscoveryReq + 2024-12-13T15:52:09.147996+0100 chargesom manager[263]: [INFO] connector:EvseM :: EVSE ISO V2G ChargeParameterDiscoveryRes + +Congratulations! You have successfully established a charging session with the EVerest +charging stack and the Charge SOM. Now you are prepared to start your own charging project and +adjust your setup to your needs. The following chapters will help you understand the EVerest +charging stack and Charge SOM in more detail and gain deeper insight into the configuration. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..3885c2b --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,27 @@ +.. Charge SOM User Guide documentation master file, created by + sphinx-quickstart on Mon Jun 10 15:58:54 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Charge SOM User Guide! +======================================================= + +**Charge SOM** is an IEC 61851 and ISO 15118 compliant charging controller, born to beat in +every kind of electric DC vehicle charging station. This user guide explains the possibilities of +setting up such a system with the Charge SOM, based on the open source charging stack +EVerest. + +This documentation starts with a short introduction and then goes straight into a hands-on chapter +:doc:`getting_started` with a simple example of how to set up a simple DC charger based on the +Charge SOM Evaluation Kit. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + getting_started + firmware + everest_charging_stack + cb_energy + development + troubleshooting diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 0000000..ea33437 --- /dev/null +++ b/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 `_ 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 `_ +and a `library `_, +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 `_ +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 `_ 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. + 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 `_. + +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 `_ +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 `_, +and let your module interact with this module via the `serial_communication_hub` interface. + +.. _contact: + +.. include:: ../../includes/troubleshooting_contact.inc diff --git a/includes b/includes new file mode 160000 index 0000000..770a838 --- /dev/null +++ b/includes @@ -0,0 +1 @@ +Subproject commit 770a8386ec0aeae33285329582e6ee0242105266