Skip to content

Commit a85afd2

Browse files
FaHaGitFaHaGit
authored
Merge pull request #33 from chargebyte/everest/ccc_introduce_generic_chapters
Introduce generic chapters. These are required so that they can also be integrated for other platforms (like Charge SOM)
2 parents 5ec9af6 + 99ac1ab commit a85afd2

20 files changed

Lines changed: 506 additions & 464 deletions

‎docs/source/cb_energy.rst‎

Lines changed: 1 addition & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -4,174 +4,4 @@
44
CB energy
55
**********************
66

7-
.. _introduction_nymea:
8-
9-
Introduction CB energy
10-
======================
11-
CB energy is a (home) energy management system.
12-
A CB energy installation consists of two parts:
13-
14-
The first part is the nymea:core (nymead) which is a server application running on the wallbox.
15-
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:
16-
17-
* load balancing
18-
* overload protection
19-
* surplus charging
20-
* energy management
21-
* spot market charging
22-
* remote access
23-
* providing charging reports
24-
* target time charging
25-
* and more
26-
27-
The second part is the CB energy app running on end user platforms like iOS and Android. The app is used to control
28-
nymea:core.
29-
The nymea:core and the different integration plugins for wallbox, meters and inverters are open source
30-
and can be found on `Github <https://github.com/nymea>`_.
31-
Features like generating chargingsession report and the energy management are closed source and require a license
32-
from chargebyte GmbH. For more information have a look `on our website <https://chargebyte.com/software/energy-manager>`_.
33-
34-
35-
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.
36-
37-
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>`_.
38-
39-
.. important::
40-
The `API module <https://github.com/EVerest/everest-core/tree/main/modules/API>`_ must be installed and active in the EVerest configuration.
41-
42-
43-
.. _cb_energy_app:
44-
45-
CB energy app
46-
=============
47-
48-
The CB energy app can be installed from the official stores.
49-
50-
.. raw:: html
51-
52-
<table border="0" align="center">
53-
<tr>
54-
<td>
55-
<p>
56-
<a href="https://apps.apple.com/us/app/cb-energy/id6503952899">
57-
<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>
58-
</p>
59-
</td>
60-
<td>
61-
<p>
62-
<a href="https://play.google.com/store/apps/details?id=com.chargebyte.cbenergy&hl=en">
63-
<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>
64-
</p>
65-
</td>
66-
</tr>
67-
</table>
68-
69-
.. _setup_and_configuration:
70-
71-
Setup and configuration
72-
=======================
73-
74-
On a chargebyte controller, the nymea Daemon will start automatically, together with the Everest stack while the system is booting up.
75-
Once the services are running the app will be able to detect the instance automatically on localhost or in the local network.
76-
77-
78-
.. _client_discovery:
79-
80-
Client discovery
81-
================
82-
83-
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.
84-
85-
.. figure:: _static/images/cbenergy/discover.png
86-
:height: 600px
87-
88-
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`.
89-
90-
91-
.. _user_setup:
92-
93-
User setup
94-
================
95-
96-
Once you are connected to the nymea:core, you can start to set up your system.
97-
98-
.. figure:: _static/images/cbenergy/user.png
99-
:height: 600px
100-
101-
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.
102-
This information is stored locally.
103-
104-
105-
106-
.. _setup:
107-
108-
Setup of ecosystem
109-
=========================
110-
111-
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.
112-
113-
.. figure:: _static/images/cbenergy/setup.png
114-
115-
If you are trying CB energy on a chargebyte controller an EVerest connector will be discovered.
116-
117-
118-
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.
119-
120-
.. figure:: _static/images/cbenergy/setup-skip.png
121-
:height: 600px
122-
123-
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.
124-
125-
126-
The final steps of the wizard are
127-
128-
* to set a grid limit for overload protection
129-
* add your initial EV parameters with name, netto battery capacity and minimum charging current as well as phase count of the on-board-charger
130-
131-
.. figure:: _static/images/cbenergy/setup-final.png
132-
133-
You can change this option later in the settings as well.
134-
135-
136-
137-
.. _home:
138-
139-
Home screen
140-
===========
141-
142-
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.
143-
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!
144-
145-
.. figure:: _static/images/cbenergy/home.png
146-
147-
148-
149-
.. _supported_devices:
150-
151-
Supported devices
152-
=================
153-
154-
Here you find a list of `supported devices <https://www.nymea.energy/integrations/>`_.
155-
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.
156-
157-
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>`_.
158-
159-
160-
161-
.. _connection_option:
162-
163-
Manual connection option
164-
========================
165-
166-
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.
167-
There are three options for the connection protocol:
168-
169-
#. TCP
170-
#. Websocket
171-
#. RemoteProxy
172-
173-
For simply hooking up client and server locally, choose TCP and enter the IP address of your nymea:core instance. For the first
174-
time you can keep the port at 2222.
175-
176-
.. figure:: _static/images/cbenergy/manual.png
177-
:height: 600px
7+
.. include:: ../../includes/cb_energy.inc

‎docs/source/development.rst‎

Lines changed: 15 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,11 @@
11
.. _development.rst:
22

3-
***********
4-
Development
5-
***********
3+
.. include:: ../../includes/development.inc
64

7-
As mentioned in the section ":ref:`programming`", customers can create their own applications and
8-
integrate them into a custom firmware image. This section will guide you through the process of creating a custom
9-
EVerest module and integrating it into an image. This is done by either using the Yocto build system or
10-
cross-compiling the application for Tarragon - the Charge Control C hardware platform.
5+
.. _cross_compiling:
116

12-
13-
Setting up Yocto Build Environment
14-
==================================
15-
16-
#. Install the `required packages <https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host>`_
17-
for Yocto on a Linux machine / virtual machine. (**Note**: We normally set up the Yocto build environment
18-
on an Ubuntu 20.04 or later Linux distribution.)
19-
#. Install :code:`repo` to help getting your Yocto environment ready. The :code:`repo` utility makes it
20-
easy to reference several Git repositories within a top-level project, which you can then clone to your
21-
local machine all at once.
22-
23-
.. code-block:: console
24-
25-
mkdir ~/bin
26-
curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
27-
chmod a+x ~/bin/repo
28-
29-
You need to also make sure that :code:`~/bin` is added to your :code:`PATH` variable
30-
(Usually the directory is added automatically in Ubuntu).
31-
32-
.. code-block:: console
33-
34-
echo 'export PATH="$PATH":~/bin' >> ~/.bashrc
35-
36-
#. The :code:`repo` tool should be used to checkout the Yocto layers needed to build the firmware image.
37-
This requires a manifest file containing information about the repositories for the necessary Yocto
38-
layers and the specific branches to be checked out. The manifest file can be found in a repository
39-
called "`chargebyte-bsp <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest>`_".
40-
(**Note**: chargebyte's Yocto build environment is currently based on 'Kirkstone' - a LTS release of the Yocto Project).
41-
42-
.. code-block:: console
43-
44-
mkdir yocto
45-
cd yocto
46-
repo init -u https://github.com/chargebyte/chargebyte-bsp -b kirkstone-everest
47-
repo sync
48-
49-
It should take a couple of minutes to download all the repositories using the command :code:`repo sync`.
50-
After the command is executed, you should be able to find three folders in the created yocto directory:
51-
52-
#. :code:`source`: Where all the repositories representing the layers are cloned.
53-
#. :code:`chargebyte-bsp`: A clone of the 'chargebyte-bsp' repository containing the manifest file and configurations folder.
54-
#. :code:`build`: Initially holds a link to the :code:`conf` folder in :code:`chargebyte-bsp`.
55-
56-
Follow the `documentation <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest/README.md>`_ in the
57-
'chargebyte-bsp' repository to build a firmware image based on the Tarragon board support package (BSP).
58-
This will include EVerest and chargebyte's hardware abstraction layer (HAL).
59-
60-
The next step in this chapter is to write a new EVerest module and build a custom image that incorporates
61-
this new module.
62-
63-
Adding a Custom EVerest Module
64-
==============================
65-
66-
The EVerest documentation explains the `modules in detail <https://everest.github.io/nightly/general/04_detail_module_concept.html>`_
67-
and their `configurations <https://everest.github.io/nightly/general/05_existing_modules.html>`_,
68-
and includes a guide on `how to develop an new EVerest module <https://everest.github.io/nightly/tutorials/new_modules>`_.
69-
70-
This section will focus on integrating the module into the Yocto build system.
71-
72-
#. In order to integrate custom EVerest modules into the Yocto build system, you can either
73-
`create a new Yocto layer <https://docs.yoctoproject.org/dev-manual/layers.html#creating-your-own-layer>`_
74-
or extend an existing one. This section will assume that a new layer has been created and added
75-
to the :code:`BBLAYERS` variable in the :code:`build/conf/bblayers.conf` file.
76-
#. A recipe file is needed to build the module. A recipe is a file with the extension :code:`.bb` and
77-
contains information about the module, such as the source code location, dependencies, and how to build it.
78-
The Yocto documentation provides a `guide on how to write a recipe file <https://docs.yoctoproject.org/dev-manual/new-recipe.html>`_.
79-
Let's assume that the new recipe is called :code:`my-module.bb`. It should look something like this:
80-
81-
.. code-block:: console
82-
83-
SUMMARY = "My Module"
84-
DESCRIPTION = "A new EVerest module"
85-
86-
LICENSE = "APACHE-2.0"
87-
LIC_FILES_CHKSUM = "file://LICENSE;md5=1234567890"
88-
89-
SRC_URI = "git://github.com/my_org/my-module.git;branch=main"
90-
S = "${WORKDIR}/git"
91-
92-
inherit cmake
93-
94-
DEPENDS = "lib1 lib2"
95-
96-
do_install() {
97-
install -d ${D}${bindir}
98-
install -m 0755 ${B}/my-module ${D}${bindir}
99-
}
100-
101-
#. Add the name of the recipe :code:`my-module` to the :code:`IMAGE_INSTALL` variable in the
102-
:code:`build/conf/local.conf` file so that the module is included in the image.
103-
104-
The module is now integrated into the Yocto build system. The next step is to build the custom image.
105-
106-
Creating a Development Image
107-
============================
108-
109-
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>`_"
110-
found in "chargebyte-bsp" repository which produces a Linux root filesystem. This can be either
111-
`flashed <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest/README.md#user-content-flash>`_
112-
directly, or used to `create a firmware image using RAUC <https://github.com/chargebyte/chargebyte-bsp/tree/kirkstone-everest/README.md#user-content-flash>`_.
113-
114-
The custom image should now include the new EVerest module.
115-
116-
.. _cross_compiling_for_tarragon:
117-
118-
Cross-compiling for Tarragon
119-
============================
7+
Cross-compiling
8+
===============
1209

12110
Another way to integrate custom applications into the firmware image is to cross-compile the application
12211
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.
13827
13928
rauc extract --keyring=<chargebyte_certificate>.crt <shipped_firmware>.image bundle-staging
14029
30+
.. note::
31+
Alternatively, if the above command does not work, you can use the following command:
32+
.. code-block:: console
33+
34+
unsquashfs -d bundle-staging <shipped_firmware>.image
35+
36+
But this will not verify the signature of the firmware image.
37+
14138
#. Mount the ext4 root filesystem image as a loop device.
14239

14340
.. code-block:: console
@@ -158,51 +55,7 @@ how to checkout a dedicated EVerest release.
15855
15956
#. Store the following lines in the :code:`toolchain.cmake` file:
16057

161-
.. code-block:: cmake
162-
163-
set(CMAKE_SYSTEM_NAME Linux)
164-
set(CMAKE_SYSTEM_PROCESSOR arm)
165-
166-
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-psabi" CACHE STRING "" FORCE )
167-
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-psabi" CACHE STRING "" FORCE )
168-
169-
if(CMAKE_BUILD_TYPE MATCHES Debug)
170-
# Debug flags
171-
message("Enabling Debug build")
172-
set(CMAKE_CXX_FLAGS_DEBUG "-g")
173-
else()
174-
# Enable compiler optimization flags
175-
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Os")
176-
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Os")
177-
178-
# Strip debug symbols
179-
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s")
180-
endif()
181-
182-
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -L${CMAKE_SYSROOT}/usr/lib")
183-
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -L${CMAKE_SYSROOT}/usr/lib")
184-
185-
if(EXISTS ${CMAKE_SYSROOT} AND IS_DIRECTORY ${CMAKE_SYSROOT})
186-
message(STATUS "SYSROOT found")
187-
else()
188-
message(FATAL_ERROR "ERROR: SYSROOT '${CMAKE_SYSROOT}' not found!!!")
189-
endif()
190-
191-
set(ENV{PKG_CONFIG_PATH} "${CMAKE_SYSROOT}/usr/lib/pkgconfig:$ENV{PKG_CONFIG_PATH}")
192-
193-
set(CMAKE_CXX_STANDARD_LIBRARIES "${CMAKE_SYSROOT}/usr/lib/libstdc++.so")
194-
195-
set(NODEJS_INCLUDE_DIR /usr/include/node) # make sure that nodejs is installed. If not, sudo apt-get install nodejs-dev
196-
197-
set(PYTHON_INCLUDE_DIRS "${CMAKE_SYSROOT}/usr/include/python3.10")
198-
set(PYTHON_LIBRARIES "${CMAKE_SYSROOT}/usr/lib/libpython3.10.so")
199-
200-
set(CMAKE_C_COMPILER /usr/bin/arm-linux-gnueabihf-gcc)
201-
set(CMAKE_CXX_COMPILER /usr/bin/arm-linux-gnueabihf-g++)
202-
203-
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
204-
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
205-
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
58+
.. literalinclude:: ../../includes/_static/files/toolchain.cmake
20659

20760
#. Create a new :code:`build` directory in "my-module" and navigate to it.
20861

@@ -233,7 +86,8 @@ how to checkout a dedicated EVerest release.
23386

23487
.. code-block:: console
23588
236-
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
89+
dist/libexec/everest/modules/MyModule/MyModule: ELF 32-bit LSB shared object, ARM, EABI5 version 1 (GNU/Linux),
90+
dynamically linked, interpreter /lib/ld-linux-armhf.so.3, BuildID[sha1]=9f287c2dbdcacd9ecde770df4820de9218deb439, for GNU/Linux 3.2.0, not stripped
23791
23892
#. The resulting binary and manifest file can be copied to the previously mounted root filesystem.
23993

0 commit comments

Comments
 (0)