diff --git a/docs/source/cb_energy.rst b/docs/source/cb_energy.rst index a6e7f5f..a7f9da6 100644 --- a/docs/source/cb_energy.rst +++ b/docs/source/cb_energy.rst @@ -4,174 +4,4 @@ CB energy ********************** -.. _introduction_nymea: - -Introduction CB energy -====================== -CB energy is a (home) energy management system. -A CB energy installation consists of two parts: - -The first part is the nymea:core (nymead) which is a server application running on the wallbox. -The main application of the nymea:core is to connect the wallbox with 3rd party local energy assets (PV, meters, home storage, ...) and enables features like: - -* load balancing -* overload protection -* surplus charging -* energy management -* spot market charging -* remote access -* providing charging reports -* target time charging -* and more - -The second part is the CB energy app running on end user platforms like iOS and Android. The app is used to control -nymea:core. -The nymea:core and the different integration plugins for wallbox, meters and inverters are open source -and can be found on `Github `_. -Features like generating chargingsession report and the energy management are closed source and require a license -from chargebyte GmbH. For more information have a look `on our website `_. - - -Both parts have to be in the same network. In order to monitor and control the wallboxes, the Everest charging stack is needed. The Everest stack provides an API module, that is used by CB Energy either on localhost (on the same hardware) or to access other instances in the same local network. - -Note: This documentation is a quick start to get the nymea ecosystem running as fast as possible with Everest charging stack. If you are about to test CB Energy on one of chargebyte's Linux controllers, both EVerest and CB Energy are preinstalled in the latest firmware images. A more detailed documentation can be found `on the nymea website `_. - -.. important:: - The `API module `_ must be installed and active in the EVerest configuration. - - -.. _cb_energy_app: - -CB energy app -============= - -The CB energy app can be installed from the official stores. - -.. raw:: html - - - - - - -
-

- - iOS Badge -

- 		-

- - Android Badge -

-
- -.. _setup_and_configuration: - -Setup and configuration -======================= - -On a chargebyte controller, the nymea Daemon will start automatically, together with the Everest stack while the system is booting up. -Once the services are running the app will be able to detect the instance automatically on localhost or in the local network. - - -.. _client_discovery: - -Client discovery -================ - -The CB energy App (client) automatically discovers available instances (servers) in your local network. Please make sure to allow the Smartphone App to have access to your local network devices after installing it. - -.. figure:: _static/images/cbenergy/discover.png - :height: 600px - -If the discovery has not found any wallbox in the local network you can try to setup an manual connection as described in :ref:`connection_option`. - - -.. _user_setup: - -User setup -================ - -Once you are connected to the nymea:core, you can start to set up your system. - -.. figure:: _static/images/cbenergy/user.png - :height: 600px - -It is time to create login credentials to keep the CB energy setup protected. When connecting to the system for the first time, it will prompt for a username and a password. Optionally, you can also provide your name and E-Mail address. -This information is stored locally. - - - -.. _setup: - -Setup of ecosystem -========================= - -In the next step, nymea:core starts a discovery for EV Chargers. This might be the same machine (localhost) or any other supported Charger in the local network. - -.. figure:: _static/images/cbenergy/setup.png - -If you are trying CB energy on a chargebyte controller an EVerest connector will be discovered. - - -After discovering and setting up the wallbox, CB Energy tries to discover other assets like solar inverters and meters. If there aren't any of these devices around, you can skip this step. - -.. figure:: _static/images/cbenergy/setup-skip.png - :height: 600px - -Basically, you don't need solar inverters or meters for controlling the wallbox. If you want to make use of the ``Eco mode``, you need to add at least one meter measuring the overall consumption of the house. - - -The final steps of the wizard are - -* to set a grid limit for overload protection -* add your initial EV parameters with name, netto battery capacity and minimum charging current as well as phase count of the on-board-charger - -.. figure:: _static/images/cbenergy/setup-final.png - -You can change this option later in the settings as well. - - - -.. _home: - -Home screen -=========== - -Well done! At this point you are ready to explore the Home Screen, the charging modes (``Eco`` and ``Quick``) and all the other capabilities of CB energy. -As mentioned in `setup`_, ``Eco mode`` is only available if at least one root meter is registered in the system. With ``Quick mode`` however, you should be able to control basic charging features like starting and stopping a charging session as well as adjusting the charging power. Give it a try! - -.. figure:: _static/images/cbenergy/home.png - - - -.. _supported_devices: - -Supported devices -================= - -Here you find a list of `supported devices `_. -CB energy comes with license, maintenance, support and service level agreement. So for the number of integrations you want to use in your final product (e.g. smart EV charger with embedded HEMS), we make sure all integrations are maintained and work as intended. - -Since the fundamental IoT middleware of CB energy - nymea - is open source, you can add your own integration to the stack. The developer guide can be found `here `_. - - - -.. _connection_option: - -Manual connection option -======================== - -If Discovery between CB energy app (client) and nymea:core (server) fails for some reason (e.g. blocked UPnP/ZeroConf in company network), you can still enter the endpoints manually. -There are three options for the connection protocol: - -#. TCP -#. Websocket -#. RemoteProxy - -For simply hooking up client and server locally, choose TCP and enter the IP address of your nymea:core instance. For the first -time you can keep the port at 2222. - -.. figure:: _static/images/cbenergy/manual.png - :height: 600px +.. include:: ../../includes/cb_energy.inc diff --git a/docs/source/development.rst b/docs/source/development.rst index 2afc9a6..db317fb 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -1,122 +1,11 @@ .. _development.rst: -*********** -Development -*********** +.. include:: ../../includes/development.inc -As mentioned in the section ":ref:`programming`", customers can create their own applications and -integrate them into a custom firmware image. This section will guide you through the process of creating a custom -EVerest module and integrating it into an image. This is done by either using the Yocto build system or -cross-compiling the application for Tarragon - the Charge Control C hardware platform. +.. _cross_compiling: - -Setting up Yocto Build Environment -================================== - -#. Install the `required packages `_ - for Yocto on a Linux machine / virtual machine. (**Note**: We normally set up the Yocto build environment - on an Ubuntu 20.04 or later Linux distribution.) -#. Install :code:`repo` to help getting your Yocto environment ready. The :code:`repo` utility makes it - easy to reference several Git repositories within a top-level project, which you can then clone to your - local machine all at once. - - .. code-block:: console - - mkdir ~/bin - curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo - chmod a+x ~/bin/repo - - You need to also make sure that :code:`~/bin` is added to your :code:`PATH` variable - (Usually the directory is added automatically in Ubuntu). - - .. code-block:: console - - echo 'export PATH="$PATH":~/bin' >> ~/.bashrc - -#. The :code:`repo` tool should be used to checkout the Yocto layers needed to build the firmware image. - This requires a manifest file containing information about the repositories for the necessary Yocto - layers and the specific branches to be checked out. The manifest file can be found in a repository - called "`chargebyte-bsp `_". - (**Note**: chargebyte's Yocto build environment is currently based on 'Kirkstone' - a LTS release of the Yocto Project). - - .. code-block:: console - - mkdir yocto - cd yocto - repo init -u https://github.com/chargebyte/chargebyte-bsp -b kirkstone-everest - repo sync - - It should take a couple of minutes to download all the repositories using the command :code:`repo sync`. - After the command is executed, you should be able to find three folders in the created yocto directory: - - #. :code:`source`: Where all the repositories representing the layers are cloned. - #. :code:`chargebyte-bsp`: A clone of the 'chargebyte-bsp' repository containing the manifest file and configurations folder. - #. :code:`build`: Initially holds a link to the :code:`conf` folder in :code:`chargebyte-bsp`. - -Follow the `documentation `_ in the -'chargebyte-bsp' repository to build a firmware image based on the Tarragon board support package (BSP). -This will include EVerest and chargebyte's hardware abstraction layer (HAL). - -The next step in this chapter is to write a new EVerest module and build a custom image that incorporates -this new module. - -Adding a Custom EVerest Module -============================== - -The EVerest documentation explains the `modules in detail `_ -and their `configurations `_, -and includes a guide on `how to develop an new EVerest module `_. - -This section will focus on integrating the module into the Yocto build system. - -#. In order to integrate custom EVerest modules into the Yocto build system, you can either - `create a new Yocto layer `_ - or extend an existing one. This section will assume that a new layer has been created and added - to the :code:`BBLAYERS` variable in the :code:`build/conf/bblayers.conf` file. -#. A recipe file is needed to build the module. A recipe is a file with the extension :code:`.bb` and - contains information about the module, such as the source code location, dependencies, and how to build it. - The Yocto documentation provides a `guide on how to write a recipe file `_. - Let's assume that the new recipe is called :code:`my-module.bb`. It should look something like this: - - .. code-block:: console - - SUMMARY = "My Module" - DESCRIPTION = "A new EVerest module" - - LICENSE = "APACHE-2.0" - LIC_FILES_CHKSUM = "file://LICENSE;md5=1234567890" - - SRC_URI = "git://github.com/my_org/my-module.git;branch=main" - S = "${WORKDIR}/git" - - inherit cmake - - DEPENDS = "lib1 lib2" - - do_install() { - install -d ${D}${bindir} - install -m 0755 ${B}/my-module ${D}${bindir} - } - -#. Add the name of the recipe :code:`my-module` to the :code:`IMAGE_INSTALL` variable in the - :code:`build/conf/local.conf` file so that the module is included in the image. - -The module is now integrated into the Yocto build system. The next step is to build the custom image. - -Creating a Development Image -============================ - -In order to build the custom image, follow the section "`Building an image `_" -found in "chargebyte-bsp" repository which produces a Linux root filesystem. This can be either -`flashed `_ -directly, or used to `create a firmware image using RAUC `_. - -The custom image should now include the new EVerest module. - -.. _cross_compiling_for_tarragon: - -Cross-compiling for Tarragon -============================ +Cross-compiling +=============== Another way to integrate custom applications into the firmware image is to cross-compile the application for Tarragon and include it in the image. A pre-requisite for this is to have the latest firmware image @@ -138,6 +27,14 @@ how to checkout a dedicated EVerest release. 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 @@ -158,51 +55,7 @@ how to checkout a dedicated EVerest release. #. Store the following lines in the :code:`toolchain.cmake` file: - .. code-block:: cmake - - set(CMAKE_SYSTEM_NAME Linux) - set(CMAKE_SYSTEM_PROCESSOR arm) - - set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-psabi" CACHE STRING "" FORCE ) - set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-psabi" CACHE STRING "" FORCE ) - - 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") - - if(EXISTS ${CMAKE_SYSROOT} AND IS_DIRECTORY ${CMAKE_SYSROOT}) - message(STATUS "SYSROOT found") - else() - message(FATAL_ERROR "ERROR: SYSROOT '${CMAKE_SYSROOT}' not found!!!") - endif() - - 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_C_COMPILER /usr/bin/arm-linux-gnueabihf-gcc) - set(CMAKE_CXX_COMPILER /usr/bin/arm-linux-gnueabihf-g++) - - set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) - set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) - set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) + .. literalinclude:: ../../includes/_static/files/toolchain.cmake #. Create a new :code:`build` directory in "my-module" and navigate to it. @@ -233,7 +86,8 @@ how to checkout a dedicated EVerest release. .. code-block:: console - dist/libexec/everest/modules/MyModule/MyModule: ELF 32-bit LSB shared object, ARM, EABI5 version 1 (GNU/Linux), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, BuildID[sha1]=9f287c2dbdcacd9ecde770df4820de9218deb439, for GNU/Linux 3.2.0, not stripped + dist/libexec/everest/modules/MyModule/MyModule: ELF 32-bit LSB shared object, ARM, EABI5 version 1 (GNU/Linux), + dynamically linked, interpreter /lib/ld-linux-armhf.so.3, BuildID[sha1]=9f287c2dbdcacd9ecde770df4820de9218deb439, for GNU/Linux 3.2.0, not stripped #. The resulting binary and manifest file can be copied to the previously mounted root filesystem. diff --git a/docs/source/everest_charging_stack.rst b/docs/source/everest_charging_stack.rst index b129466..72bc0c3 100644 --- a/docs/source/everest_charging_stack.rst +++ b/docs/source/everest_charging_stack.rst @@ -4,38 +4,10 @@ EVerest charging stack ********************** -Introduction to EVerest -======================= - -EVerest is an open-source modular framework designed to create a comprehensive software stack for -electric vehicle (EV) charging. - -The modular software architecture promotes flexibility and customization, allowing users to configure specific charging -scenarios using interchangeable modules. This architecture is integrated and coordinated using MQTT (Message Queuing -Telemetry Transport). EVerest aims to standardize and simplify the development of EV charging -infrastructure, making it easier for developers and companies to implement robust and scalable charging solutions. -The project includes support for various protocols like ISO 15118, OCPP, and IEC 61851, ensuring broad -compatibility and future-proofing of the charging systems. - -For more information, visit the `EVerest GitHub repository `_. - -Basic configuration -=================== - -In order to test EVerest, you need to build it either natively on host Linux machine or integrate it into a -firmware suitable for a specific target platform using Yocto. To build it natively, follow the instructions -found in the main EVerest repository "`everest-core `_". -Additionally, there is a `quickstart guide `_ -to EVerest, which presents the different EVerest tools, build instructions, and a dive into simulating EVerest. - -For Yocto, EVerest offers "`meta-everest `_"; a Yocto meta layer -that can be used to integrate the EVerest charging stack into a platform-specific firmware image. -chargebyte utilizes this layer to produce firmware images suitable for Charge Control C. Detailed instructions on -how to integrate EVerest into a Charge Control C firmware image can be found on `GitHub `_. - -For setting up a use case with EVerest, such as basic PWM charging, a YAML configuration file is needed. -Various example configurations, including those for software-in-the-loop tests, can be found in -the "`config `_" folder of the everest-core repository. +.. 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.yaml @@ -48,25 +20,9 @@ The use case described in this configuration file includes the following: * 1 contactor for 3 phase * No phase switching -The modules :code:`CbTarragonDriver` and :code:`CbTarragonDIs` are part of the Hardware Abstraction Layer (HAL) -used to integrate Charge Control C with EVerest. This will be explained in the next section. - -Required modules for Charge Control C -===================================== - -As seen from the previous configuration file, some modules are required in order to use EVerest with Charge Control C. +An overview of the EVerest modules that are defined within a configuration file is shown in the next section. -**EvseManager** (`view on GitHub `_) - -The main module in a charging infrastructure EVerest setup. It manages a single EVSE (i.e., one connector for -charging a car) and may control multiple connectors under some circumstances. It handles charging -logic (basic charging and HLC), gathers all relevant data for the charging session, such as energy -delivered during the session, and provides control over the charging port/session. For more information about -its capabilities, refer to the `module documentation `_. - -**EnergyManager** (`view on GitHub `__) - -This module is the global Energy Manager for all EVSE/Charging stations in a building. +.. include:: ../../includes/everest_overview_of_everest_modules.inc **CbTarragonDriver** (`view on GitHub `__) @@ -77,22 +33,6 @@ often refers to these HAL modules as BSPs, such as MicroMegaWattBSP and PhyVerso essential for controlling the Charge Control C. The term "Tarragon" in :code:`CbTarragonDriver` refers to the Charge Control C hardware platform. -**CbTarragonDIs** (`view on GitHub `__) - -The Charge Control C is equipped with multiple digital inputs (For more information, refer to section :ref:`digital_input`). -The module :code:`CbTarragonDIs` is used for setting the reference PWM for these DIs. The reference PWM -sets the threshold voltage for all 12V digital inputs, which is essential for their operation. -The use of this module is optional and depends on the EVSE requirements where the Charge Control C is integrated. - -**CbSystem** (`view on GitHub `__) - -This module is an adaptation of the "`System `_" -module in EVerest. It implements the "`system `__" -interface and, like the :code:`System` module, is responsible for performing system-wide operations but -tailored for chargebyte's hardware platforms. The use of this module depends on the specific use case, -such as if OCPP is required. In such cases, the :code:`CbSystem` module is responsible for executing -commands from OCPP e.g. :code:`UpdateFirmware`. - **CbTarragonPlugLock** (`view on GitHub `__) This module is not mandatory for an EVSE setup using Charge Control C in EVerest. However, if EVerest @@ -102,24 +42,12 @@ 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 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 -via a configuration parameter. - -**OCPP** (`view on GitHub `__) - -This module implements and integrates OCPP 1.6 support within EVerest. - -**OCPP201** (`view on GitHub `__) +**CbTarragonDIs** (`view on GitHub `__) -This module implements and integrates OCPP 2.0.1 support within EVerest. +The Charge Control C is equipped with multiple digital inputs (For more information, refer to section :ref:`digital_input`). +The module :code:`CbTarragonDIs` is used for setting the reference PWM for these DIs. The reference PWM +sets the threshold voltage for all 12V digital inputs, which is essential for their operation. +The use of this module is optional and depends on the EVSE requirements where the Charge Control C is integrated. Energy Management: 3 phase / 1 phase switching ============================================== @@ -235,23 +163,4 @@ The full description of all these parameters can be found in the .. note:: Phase count switching is only possible in basic charging mode. -Further reading -=============== - -For more information on getting started with EVerest, including an overview of the necessary tools and -instructions on writing your own modules, please refer to the official -`EVerest documentation `_. - -EVerest consists of multiple repositories, such as "`everest-core `_" -and "`libocpp `_". Each repository has its own documentation detailing its -specific role within EVerest. It should be noted that Pionix GmbH and the EVerest community maintain -all repositories that are a part of the EVerest GitHub organization. Only the EVerest modules that chargebyte -implemented and that are located in "`everest-chargebyte `_" -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, 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`). +.. include:: ../../includes/everest_further_reading.inc diff --git a/docs/source/firmware.rst b/docs/source/firmware.rst index ebc9eb0..81ae233 100644 --- a/docs/source/firmware.rst +++ b/docs/source/firmware.rst @@ -45,7 +45,7 @@ released versions. Please read the release notes of the firmware image before downloading and installing it. In the release notes you can find information about the changes and new features of the firmware image and also the version information which "everest-core" tag the firmware image is based on. This information - is especially important if you build up your cross-compile environment in section :ref:`cross_compiling_for_tarragon`. + is especially important if you build up your cross-compile environment in section :ref:`cross_compiling`. Please check that your cross-compile environment is using the same "everest-core" tag as the firmware image you want to install. diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 6362dc7..a3d0c5e 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -127,31 +127,4 @@ and let your module interact with this module via the `serial_communication_hub` .. _contact: -Contact -------- - -Support -^^^^^^^ - -EVerest is an open-source project with a lot of modules, which is supported by a big community. -chargebyte is an active part of this community. However chargebyte is not able to provide support -for every aspect of EVerest. In order to get quick answers, here are some suggestions: - -Do you have general questions about EVerest, please use the EVerest community's -`Zulip `_. - -Do you have questions about the chargebyte BSP (incl. Yocto), please use -`our support desk `_. - -Address -^^^^^^^ - -chargebyte GmbH - -Bitterfelder Straße 1-5 - -04129 Leipzig - -Germany - -Website: ``_ +.. include:: ../../includes/troubleshooting_contact.inc diff --git a/includes/_static/files/toolchain.cmake b/includes/_static/files/toolchain.cmake new file mode 100644 index 0000000..ed736af --- /dev/null +++ b/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) diff --git a/docs/source/_static/images/cbenergy/discover.png b/includes/_static/images/cbenergy/discover.png similarity index 100% rename from docs/source/_static/images/cbenergy/discover.png rename to includes/_static/images/cbenergy/discover.png diff --git a/docs/source/_static/images/cbenergy/home.png b/includes/_static/images/cbenergy/home.png similarity index 100% rename from docs/source/_static/images/cbenergy/home.png rename to includes/_static/images/cbenergy/home.png diff --git a/docs/source/_static/images/cbenergy/manual.png b/includes/_static/images/cbenergy/manual.png similarity index 100% rename from docs/source/_static/images/cbenergy/manual.png rename to includes/_static/images/cbenergy/manual.png diff --git a/docs/source/_static/images/cbenergy/setup-final.png b/includes/_static/images/cbenergy/setup-final.png similarity index 100% rename from docs/source/_static/images/cbenergy/setup-final.png rename to includes/_static/images/cbenergy/setup-final.png diff --git a/docs/source/_static/images/cbenergy/setup-skip.png b/includes/_static/images/cbenergy/setup-skip.png similarity index 100% rename from docs/source/_static/images/cbenergy/setup-skip.png rename to includes/_static/images/cbenergy/setup-skip.png diff --git a/docs/source/_static/images/cbenergy/setup.png b/includes/_static/images/cbenergy/setup.png similarity index 100% rename from docs/source/_static/images/cbenergy/setup.png rename to includes/_static/images/cbenergy/setup.png diff --git a/docs/source/_static/images/cbenergy/user.png b/includes/_static/images/cbenergy/user.png similarity index 100% rename from docs/source/_static/images/cbenergy/user.png rename to includes/_static/images/cbenergy/user.png diff --git a/includes/cb_energy.inc b/includes/cb_energy.inc new file mode 100644 index 0000000..7a897eb --- /dev/null +++ b/includes/cb_energy.inc @@ -0,0 +1,171 @@ +.. _introduction_nymea: + +Introduction CB energy +====================== +CB energy is a (home) energy management system. +A CB energy installation consists of two parts: + +The first part is the nymea:core (nymead) which is a server application running on the wallbox. +The main application of the nymea:core is to connect the wallbox with 3rd party local energy assets (PV, meters, home storage, ...) and enables features like: + +* load balancing +* overload protection +* surplus charging +* energy management +* spot market charging +* remote access +* providing charging reports +* target time charging +* and more + +The second part is the CB energy app running on end user platforms like iOS and Android. The app is used to control +nymea:core. +The nymea:core and the different integration plugins for wallbox, meters and inverters are open source +and can be found on `Github `_. +Features like generating charging session report and the energy management are closed source and require a license +from chargebyte GmbH. For more information have a look `on our website `_. + + +Both parts have to be in the same network. In order to monitor and control the wallboxes, the Everest charging stack is needed. The Everest stack provides an API module, that is used by CB Energy either on localhost (on the same hardware) or to access other instances in the same local network. + +Note: This documentation is a quick start to get the nymea ecosystem running as fast as possible with Everest charging stack. If you are testing CB Energy on one of chargebyte's Linux controllers, both EVerest and CB Energy are preinstalled in the latest firmware images. A more detailed documentation can be found `on the nymea website `_. + +.. important:: + The `API module `_ must be installed and active in the EVerest configuration. + + +.. _cb_energy_app: + +CB energy app +============= + +The CB energy app can be installed from the official stores. + +.. raw:: html + + + + + + +
+

+ + iOS Badge +

+ 		+

+ + Android Badge +

+
+ +.. _setup_and_configuration: + +Setup and configuration +======================= + +On a chargebyte controller, the nymea Daemon will start automatically, together with the Everest stack while the system is booting up. +Once the services are running the app will be able to detect the instance automatically on localhost or in the local network. + + +.. _client_discovery: + +Client discovery +================ + +The CB energy App (client) automatically discovers available instances (servers) in your local network. Please make sure to allow the Smartphone App to have access to your local network devices after installing it. + +.. figure:: ../../includes/_static/images/cbenergy/discover.png + :height: 600px + +If the discovery has not found any wallbox in the local network you can try to set up a manual connection as described in :ref:`connection_option`. + + +.. _user_setup: + +User setup +================ + +Once you are connected to the nymea:core, you can start to set up your system. + +.. figure:: ../../includes/_static/images/cbenergy/user.png + :height: 600px + +It is time to create login credentials to keep the CB energy setup protected. When connecting to the system for the first time, it will prompt for a username and a password. Optionally, you can also provide your name and e-mail address. +This information is stored locally. + + + +.. _setup: + +Setup of ecosystem +========================= + +In the next step, nymea:core starts a discovery for EV chargers. This might be the same machine (localhost) or any other supported charger in the local network. + +.. figure:: ../../includes/_static/images/cbenergy/setup.png + +If you are trying CB energy on a chargebyte controller an EVerest connector will be discovered. + + +After discovering and setting up the wallbox, CB Energy tries to discover other assets like solar inverters and meters. If there aren't any of these devices around, you can skip this step. + +.. figure:: ../../includes/_static/images/cbenergy/setup-skip.png + :height: 600px + +Basically, you don't need solar inverters or meters for controlling the wallbox. If you want to make use of the ``Eco mode``, you need to add at least one meter measuring the overall consumption of the house. + + +The final steps of the wizard are + +* to set a grid limit for overload protection +* add your initial EV parameters with name, netto battery capacity and minimum charging current as well as phase count of the on-board-charger + +.. figure:: ../../includes/_static/images/cbenergy/setup-final.png + +You can change this option later in the settings as well. + + + +.. _home: + +Home screen +=========== + +Well done! At this point you are ready to explore the Home Screen, the charging modes (``Eco`` and ``Quick``) and all the other capabilities of CB energy. +As mentioned in `setup`_, ``Eco mode`` is only available if at least one root meter is registered in the system. With ``Quick mode`` however, you should be able to control basic charging features like starting and stopping a charging session as well as adjusting the charging power. Give it a try! + +.. figure:: ../../includes/_static/images/cbenergy/home.png + + + +.. _supported_devices: + +Supported devices +================= + +Here you find a list of `supported devices `_. +CB energy comes with license, maintenance, support and service level agreement. So for the number of integrations you want to use in your final product (e.g. smart EV charger with embedded HEMS), we make sure all integrations are maintained and work as intended. + +Since the fundamental IoT middleware of CB energy - nymea - is open source, you can add your own integration to the stack. The developer guide can be found `here `_. + + + +.. _connection_option: + +Manual connection option +======================== + +If discovery between CB energy app (client) and nymea:core (server) fails for some reason (e.g. blocked UPnP/ZeroConf in company network), you can still enter the endpoints manually. +There are three options for the connection protocol: + +#. TCP +#. Websocket +#. RemoteProxy + +For simply hooking up client and server locally, choose TCP and enter the IP address of your nymea:core instance. For the first +time you can keep the port at 2222. + +.. figure:: ../../includes/_static/images/cbenergy/manual.png + :height: 600px diff --git a/includes/development.inc b/includes/development.inc new file mode 100644 index 0000000..7d062c5 --- /dev/null +++ b/includes/development.inc @@ -0,0 +1,114 @@ +*********** +Development +*********** + +As mentioned in the section ":ref:`programming`", customers can create their own applications and +integrate them into a custom firmware image. This section will guide you through the process of creating a custom +EVerest module and integrating it into an image. This is done by either using the Yocto build system or +cross-compiling the application for the chargebyte hardware platform. + + +Setting up Yocto Build Environment +================================== + +#. Install the `required packages `_ + for Yocto on a Linux machine / virtual machine. (**Note**: We normally set up the Yocto build environment + on an Ubuntu 20.04 or later Linux distribution.) +#. Install :code:`repo` to help getting your Yocto environment ready. The :code:`repo` utility makes it + easy to reference several Git repositories within a top-level project, which you can then clone to your + local machine all at once. + + .. code-block:: console + + mkdir ~/bin + curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo + chmod a+x ~/bin/repo + + You need to also make sure that :code:`~/bin` is added to your :code:`PATH` variable + (Usually the directory is added automatically in Ubuntu). + + .. code-block:: console + + echo 'export PATH="$PATH":~/bin' >> ~/.bashrc + +#. The :code:`repo` tool should be used to checkout the Yocto layers needed to build the firmware image. + This requires a manifest file containing information about the repositories for the necessary Yocto + layers and the specific branches to be checked out. The manifest file can be found in a repository + called "`chargebyte-bsp `_". + (**Note**: chargebyte's Yocto build environment is currently based on 'Kirkstone' - a LTS release of the Yocto Project). + + .. code-block:: console + + mkdir yocto + cd yocto + repo init -u https://github.com/chargebyte/chargebyte-bsp -b kirkstone-everest + repo sync + + It should take a couple of minutes to download all the repositories using the command :code:`repo sync`. + After the command is executed, you should be able to find three folders in the created yocto directory: + + #. :code:`source`: Where all the repositories representing the layers are cloned. + #. :code:`chargebyte-bsp`: A clone of the 'chargebyte-bsp' repository containing the manifest file and configurations folder. + #. :code:`build`: Initially holds a link to the :code:`conf` folder in :code:`chargebyte-bsp`. + +Follow the `documentation `_ in the +'chargebyte-bsp' repository to build a firmware image based on the hardware platform specific board support package (BSP). +Currently supported are the hardware platforms Tarragon (Charge Control C) and Charge SOM. + +This will include EVerest and chargebyte's hardware abstraction layer (HAL). + +The next step in this chapter is to write a new EVerest module and build a custom image that incorporates +this new module. + +Adding a Custom EVerest Module +============================== + +The EVerest documentation explains the `modules in detail `_ +and their `configurations `_, +and includes a guide on `how to develop an new EVerest module `_. + +This section will focus on integrating the module into the Yocto build system. + +#. In order to integrate custom EVerest modules into the Yocto build system, you can either + `create a new Yocto layer `_ + or extend an existing one. This section will assume that a new layer has been created and added + to the :code:`BBLAYERS` variable in the :code:`build/conf/bblayers.conf` file. +#. A recipe file is needed to build the module. A recipe is a file with the extension :code:`.bb` and + contains information about the module, such as the source code location, dependencies, and how to build it. + The Yocto documentation provides a `guide on how to write a recipe file `_. + Let's assume that the new recipe is called :code:`my-module.bb`. It should look something like this: + + .. code-block:: console + + SUMMARY = "My Module" + DESCRIPTION = "A new EVerest module" + + LICENSE = "APACHE-2.0" + LIC_FILES_CHKSUM = "file://LICENSE;md5=1234567890" + + SRC_URI = "git://github.com/my_org/my-module.git;branch=main" + S = "${WORKDIR}/git" + + inherit cmake + + DEPENDS = "lib1 lib2" + + do_install() { + install -d ${D}${bindir} + install -m 0755 ${B}/my-module ${D}${bindir} + } + +#. Add the name of the recipe :code:`my-module` to the :code:`IMAGE_INSTALL` variable in the + :code:`build/conf/local.conf` file so that the module is included in the image. + +The module is now integrated into the Yocto build system. The next step is to build the custom image. + +Creating a Development Image +============================ + +In order to build the custom image, follow the section "`Building an image `_" +found in "chargebyte-bsp" repository which produces a Linux root filesystem. This can be either +`flashed `_ +directly, or used to `create a firmware image using RAUC `_. + +The custom image should now include the new EVerest module. diff --git a/includes/everest_basic_configuration.inc b/includes/everest_basic_configuration.inc new file mode 100644 index 0000000..a54f52f --- /dev/null +++ b/includes/everest_basic_configuration.inc @@ -0,0 +1,17 @@ +Basic configuration +=================== + +In order to test EVerest, you need to build it either natively on host Linux machine or integrate it into a +firmware suitable for a specific target platform using Yocto. To build it natively, follow the instructions +found in the main EVerest repository "`everest-core `_". +Additionally, there is a `quickstart guide `_ +to EVerest, which presents the different EVerest tools, build instructions, and a dive into simulating EVerest. + +For Yocto, EVerest offers "`meta-everest `_"; a Yocto meta layer +that can be used to integrate the EVerest charging stack into a platform-specific firmware image. +chargebyte utilizes this layer to produce firmware images suitable for chargebyte hardware platforms. Detailed instructions on +how to integrate EVerest into a chargebyte firmware image can be found on `GitHub `_. + +For setting up a use case with EVerest, such as basic setups for AC or DC charging, a YAML configuration file is needed. +Various example configurations, including those for software-in-the-loop tests, can be found in +the "`config `_" folder of the everest-core repository. diff --git a/includes/everest_further_reading.inc b/includes/everest_further_reading.inc new file mode 100644 index 0000000..23b99a4 --- /dev/null +++ b/includes/everest_further_reading.inc @@ -0,0 +1,20 @@ +Further reading +=============== + +For more information on getting started with EVerest, including an overview of the necessary tools and +instructions on writing your own modules, please refer to the official +`EVerest documentation `_. + +EVerest consists of multiple repositories, such as "`everest-core `_" +and "`libocpp `_". Each repository has its own documentation detailing its +specific role within EVerest. It should be noted that Pionix GmbH and the EVerest community maintain +all repositories that are a part of the EVerest GitHub organization. Only the EVerest modules that chargebyte +implemented and that are located in "`everest-chargebyte `_" +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, 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/includes/everest_introduction_to_everest.inc b/includes/everest_introduction_to_everest.inc new file mode 100644 index 0000000..ff14cc5 --- /dev/null +++ b/includes/everest_introduction_to_everest.inc @@ -0,0 +1,14 @@ +Introduction to EVerest +======================= + +EVerest is an open-source modular framework designed to create a comprehensive software stack for +electric vehicle (EV) charging. + +The modular software architecture promotes flexibility and customization, allowing users to configure specific charging +scenarios using interchangeable modules. This architecture is integrated and coordinated using MQTT (Message Queuing +Telemetry Transport). EVerest aims to standardize and simplify the development of EV charging +infrastructure, making it easier for developers and companies to implement robust and scalable charging solutions. +The project includes support for various protocols like ISO 15118, OCPP, and IEC 61851, ensuring broad +compatibility and future-proofing of the charging systems. + +For more information, visit the `EVerest GitHub repository `_. diff --git a/includes/everest_overview_of_everest_modules.inc b/includes/everest_overview_of_everest_modules.inc new file mode 100644 index 0000000..9b01202 --- /dev/null +++ b/includes/everest_overview_of_everest_modules.inc @@ -0,0 +1,60 @@ +Overview of EVerest modules +============================ + +As seen from the previous configuration file, some modules are required in order to use EVerest. +Which modules are required is highly dependent on the use case you want to release. The following +is a list of modules that are part of the chargebyte EVerest charging software: + +**EvseManager** (`view on GitHub `_) + +The main module in a charging infrastructure EVerest setup. It manages a single EVSE (i.e., one connector for +charging a car) and may control multiple connectors under some circumstances. It handles charging +logic (basic charging and HLC), gathers all relevant data for the charging session, such as energy +delivered during the session, and provides control over the charging port/session. For more information about +its capabilities, refer to the `module documentation `_. + +**EnergyManager** (`view on GitHub `__) + +This module is the global Energy Manager for all EVSE/Charging stations in a building. + +**API** (`view on GitHub `__) + +This module is not mandatory for an EVSE setup in EVerest. However, the module +: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 in EVerest. This module is responsible +for storing EVerest error events in a database file. The location of the database file can be defined +via a configuration parameter. + +**DummyTokenProvider** (`view on GitHub `__) + +This module is used for automatically providing an authorization token, instead of requiring e.g. an +actual RFID reader. It listens to the AuthRequired event from evse_manager module and then publishes one token. + +**DummyTokenValidator** (`view on GitHub `__) + +This module always returning the same configured token validation result for every token. The +validation result is a configuration key in the manifest of the module. + +**CbSystem** (`view on GitHub `__) + +This module is an adaptation of the "`System `_" +module in EVerest. It implements the "`system `__" +interface and, like the :code:`System` module, is responsible for performing system-wide operations but +tailored for chargebyte's hardware platforms. The use of this module depends on the specific use case, +such as if OCPP is required. In such cases, the :code:`CbSystem` module is responsible for executing +commands from OCPP e.g. :code:`UpdateFirmware`. + +**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. + +**AuthListValidator** + +This module validating if an incoming token exists in a in a predefined list of authorized tokens. diff --git a/includes/troubleshooting_contact.inc b/includes/troubleshooting_contact.inc new file mode 100644 index 0000000..4fa4ea8 --- /dev/null +++ b/includes/troubleshooting_contact.inc @@ -0,0 +1,28 @@ +Contact +------- + +Support +^^^^^^^ + +EVerest is an open-source project with a lot of modules, which is supported by a big community. +chargebyte is an active part of this community. However chargebyte is not able to provide support +for every aspect of EVerest. In order to get quick answers, here are some suggestions: + +Do you have general questions about EVerest, please use the EVerest community's +`Zulip `_. + +Do you have questions about the chargebyte BSP (incl. Yocto), please use +`our support desk `_. + +Address +^^^^^^^ + +chargebyte GmbH + +Bitterfelder Straße 1-5 + +04129 Leipzig + +Germany + +Website: ``_