Skip to content

CCC: introduce generic chapters #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FaHaGit merged 12 commits into from
Mar 6, 2025
Merged

CCC: introduce generic chapters #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
3a7ca36
Prepare generic chapters for everest_charging_stack.rst
FaHaGit Mar 6, 2025
f3340a6
Introduce generic chapters for everest_charing_stack.rst
FaHaGit Mar 6, 2025
7238f10
Introduce generic chapter for troubleshooting.rst
FaHaGit Mar 6, 2025
c21d23e
development: add alternative command for extracting firmware images
FaHaGit Mar 6, 2025
e3fa2ac
Prepare generic chapters for development.rst
FaHaGit Mar 6, 2025
2d9a410
Introduce generic chapter for development.rst
FaHaGit Mar 6, 2025
922c951
Introduce generic chapter for cb_energy.rst
FaHaGit Mar 6, 2025
e599d8b
Update support desk link in troubleshooting contact section
FaHaGit Mar 6, 2025
2af3107
everest: fix: correct minor grammatical errors in documentation
FaHaGit Mar 6, 2025
8c54d3d
development: fix: correct capitalization of hardware platform names
FaHaGit Mar 6, 2025
ebd2ddb
energy: fix: correct minor grammatical errors
FaHaGit Mar 6, 2025
99ac1ab
energy: fix: correct capitalization and grammatical errors
FaHaGit Mar 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 1 addition & 171 deletions docs/source/cb_energy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/nymea>`_.
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 <https://chargebyte.com/software/energy-manager>`_.


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 <https://nymea.io>`_.

.. important::
The `API module <https://github.com/EVerest/everest-core/tree/main/modules/API>`_ 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

<table border="0" align="center">
<tr>
<td>
<p>
<a href="https://apps.apple.com/us/app/cb-energy/id6503952899">
<img border="0" align="middle" alt="iOS Badge" src="https://developer.apple.com/app-store/marketing/guidelines/images/badge-example-preferred_2x.png" width=200>
</p>
</td>
<td>
<p>
<a href="https://play.google.com/store/apps/details?id=com.chargebyte.cbenergy&hl=en">
<img border="0" align="middle" alt="Android Badge" src="https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png" width=256>
</p>
</td>
</tr>
</table>

.. _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 <https://www.nymea.energy/integrations/>`_.
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 <https://nymea.io/documentation/developers/integrations/getting-started-integration>`_.



.. _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
176 changes: 15 additions & 161 deletions docs/source/development.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host>`_
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 <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest>`_".
(**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 <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest/README.md>`_ 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 <https://everest.github.io/nightly/general/04_detail_module_concept.html>`_
and their `configurations <https://everest.github.io/nightly/general/05_existing_modules.html>`_,
and includes a guide on `how to develop an new EVerest module <https://everest.github.io/nightly/tutorials/new_modules>`_.

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 <https://docs.yoctoproject.org/dev-manual/layers.html#creating-your-own-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 <https://docs.yoctoproject.org/dev-manual/new-recipe.html>`_.
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 <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest/README.md#user-content-build>`_"
found in "chargebyte-bsp" repository which produces a Linux root filesystem. This can be either
`flashed <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest/README.md#user-content-flash>`_
directly, or used to `create a firmware image using RAUC <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest/README.md#user-content-flash>`_.

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
Expand All @@ -138,6 +27,14 @@ how to checkout a dedicated EVerest release.

rauc extract --keyring=<chargebyte_certificate>.crt <shipped_firmware>.image bundle-staging

.. note::
Alternatively, if the above command does not work, you can use the following command:
.. code-block:: console

unsquashfs -d bundle-staging <shipped_firmware>.image

But this will not verify the signature of the firmware image.

#. Mount the ext4 root filesystem image as a loop device.

.. code-block:: console
Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
Loading