Add doc build snapshot top-level-framework

EVerest · Feb 15, 2024 · fd39429 · fd39429
1 parent 9a31e88
commit fd39429
Show file tree

Hide file tree

Showing 25 changed files with 231 additions and 182 deletions.
diff --git a/docs/index.html b/docs/index.html
@@ -4,7 +4,7 @@
         <title>
             Redirectiong...
         </title>
-        <meta http-equiv="refresh" content="0;url=./nightly">
+        <meta http-equiv="refresh" content="0;url=./top-level-framework">
     </head>
     <body>
     </body>

diff --git a/docs/latest/_images/0-0-everest-top-level-diagram.png b/docs/latest/_images/0-0-everest-top-level-diagram.png
diff --git a/docs/latest/_images/0-1-everest-top-level-diagram-module-details.png b/docs/latest/_images/0-1-everest-top-level-diagram-module-details.png
diff --git a/docs/latest/_images/0-2-everest-top-level-diagram-module-communication.png b/docs/latest/_images/0-2-everest-top-level-diagram-module-communication.png
diff --git a/docs/latest/_images/0-3-everest-top-level-diagram-module-categories.png b/docs/latest/_images/0-3-everest-top-level-diagram-module-categories.png
diff --git a/docs/latest/_images/quick-start-high-level-1.png b/docs/latest/_images/quick-start-high-level-1.png
diff --git a/docs/latest/_images/quick-start-high-level-2.png b/docs/latest/_images/quick-start-high-level-2.png
diff --git a/docs/latest/_images/quick-start-high-level-3.png b/docs/latest/_images/quick-start-high-level-3.png
diff --git a/docs/latest/_sources/general/01_framework.rst.txt b/docs/latest/_sources/general/01_framework.rst.txt
@@ -2,48 +2,125 @@
 
 EVerest framework
 #################
-You can think of EVerest as an operating system for EV chargers with implementations of communication protocols, software modules for representations of hardware devices (chargers, cars, …) and tools for simulating the charging process.
+You can think of EVerest as an operating system for EV chargers with
+implementations of communication protocols, software modules for
+representations of hardware devices (chargers, cars, …) and tools
+for simulating the charging process.
 
 It's a full stack environment for EV charging.
 
 *********************
 A Visual Introduction
 *********************
 
-A first very high level overview of the framework can be seen here:
+The EVerest framework helps with building your dedicated development scenario
+with all needed modules for your specific developer's use case.
+The modules are connected by using the principle of loose coupling.
 
-.. image:: img/quick-start-high-level-1.png
+Modules in EVerest can be everything like hardware drivers, protocols,
+authentication logic and more.
+Build up your development scenario as needed and enhance it by adding your own
+additional modules.
 
-The EVerest framework helps with building your dedicated development scenario with all needed modules for your specific developer's use case. The modules are connected by using the principle of loose coupling.
+Having this in mind, you can take a look at the following high level overview
+of the framework:
 
-Modules in EVerest can be everything like hardware drivers, protocols, authentication logic and more. Build up your development scenario as needed and enhance it by adding your own additional modules.
+.. image:: img/0-0-everest-top-level-diagram.png
+  :width: 760px
 
-Another way to look at EVerest is its layer architecture:
+The upper part (light grey background) of this picture is part of EVerest. The
+lower part of the picture shows two technologies that are used by EVerest but
+are not part of the EVerest repositories.
 
-.. image:: img/quick-start-high-level-2.png
+The EVerest framework launches all modules that are configured for your
+workspace.
+You will see later how configuration of modules and dependencies is done.
 
-Depending on your project use case, you can define the suitable module stack and configure module connections and module parameters.
+The modules communicate via an MQTT broker.
+MQTT is currently the default messaging technology coming with EVerest.
+You could change that to other solutions (with some smaller development
+efforts).
+Same with NodeRED.
 
-What modules EVerest already delivers as ready-to-use implementations and which features they currently ship will be explained in detail in the modules documentation.
+At the right side of the picture, you see the main tools in EVerest, which
+will be explained later in this documentation in more detail.
+Up to now, some sneak preview:
 
-*****************
-Tools And Helpers
-*****************
+- **Admin Panel**: Tool to show all modules connections and dependencies
+  including the parameters set for the modules.
+- **EVerest Dependency Manager** (edm): Tool that helps you getting all
+  needed repositories from Git for your specific setup.
+- **ev-cli**: Generates module and interface scaffolds based on templates.
+  This way you can start implementing new modules very fast.
 
-Additionally, you have some tools and helpers that work with the framework which makes your EVerest developer's life easier:
+***************************
+Examples of EVerest Modules
+***************************
 
-.. image:: img/quick-start-high-level-3.png
+This picture shows some of the main modules in EVerest:
 
-To understand the benefit delivered by those tools, let's have a sneak preview:
+.. image:: img/0-3-everest-top-level-diagram-module-categories.png
+  :width: 450px
 
-- **Admin Panel**: Tool to show all modules connections and dependencies including the parameters set for the modules.
-- **EVerest Dependency Manager** (edm): Tool that helps you getting all needed repositories from Git for your specific setup.
-- **ev-cli**: Generates module and interface scaffolds based on templates. This way you can start implementing new modules very fast.
-- **MQTT Explorer**: Great for debugging the messages sent between your modules during development phase.
-- **NodeRed** for simulating your EVerest setup
-- **SteVe**: Just in case you want to test your EVerest instance with some OCPP backend functionality: SteVe is an external tool that lets you do exactly that.
+The central module in EV charging scenarios will be the EvseManager.
+It consists of some central controlling logic for charging configurations.
 
-How to setup and use those tools will be shown later.
+All other modules shown can be organized in workspaces depending on your
+individual setup.
+Later in this documentation, you will learn how to create configurations
+to set the dependencies and config values of those modules to suit your
+needs.
+
+*************************
+High Level Module Concept
+*************************
+
+To get an idea, what an EVerest module consists of, see the following
+illustration:
+
+.. image:: img/0-1-everest-top-level-diagram-module-details.png
+  :width: 520px
+
+The top box within the dashed line shows the definition of a module in EVerest.
+The heart of it is the manifest file.
+The manifest holds the definition of configuration keys.
+
+.. note::
+    The manifest file is not the place to put the values of the config options.
+    The manifest just defines what can be configured later, e.g. the "max
+    voltage" of a device.
+    The values of those config parameters are put in the configuration files
+    that build up your workspace, which will be explained later.
+
+The manifest also declares which interfaces are provided or required by a
+module.
+"Provided" means that a module has implemented an interface.
+"Required" means that a module needs a connection to another module which has
+implemented the dedicated interface.
+
+For a more detailed explanation of that concept and what "type" definitions
+mean in EVerest, see the
+:ref:`EVerest Module Concept page <moduleconcept_main>`
+
+Alternatively, you can also see the concept in action in a
+ :ref:`tutorial that shows how to create modules <tutorial_create_modules_main>`.
+
+Having defined EVerest modules, they need to have a way to communicate.
+This illustration shows what is happening there:
+
+.. image:: img/0-2-everest-top-level-diagram-module-communication.png
+  :width: 450px
+
+Module A and Module B are communicating via an MQTT broker.
+
+Modules can publish variables (VARs) which other modules can subscribe to.
+
+Modules can also call commands (CMDs) of other modules.
+This is also triggered via MQTT messages.
+
+********************
+Module Communication
+********************
 
 *************************************
 System Requirements and Prerequisites

diff --git a/docs/latest/_sources/general/faq.rst.txt b/docs/latest/_sources/general/faq.rst.txt
@@ -187,62 +187,3 @@ You may want to have a look at https://github.com/mobilityhouse/ocpp and
 implement message handlers to get the communication working. Or you can have
 a look at https://github.com/thoughtworks/maeve-csms. Note: This has not been
 officially tested by us.
-
-Testing
-=======
-
-.. _faq_testing:
-
-Unit tests
-----------
-
-**How can I run the unit tests?**
-
-To run the unit tests, you need to build with the cmake flag `-DBUILD_TESTING=ON`
-and then run `make test` in the build directory.
-
-**How do I name test targets in CMake?**
-
-Test targets should be prefixed by the project name, to avoid conflicts when Building
-libraries as dependency for other projects.
-The best practice is to use the following naming scheme:
-
-.. code-block:: cmake
-
-  add_executable(${PROJECT_NAME}_tests)
-
-Furthermore, the unit test should be include by the following condition:
-
-.. code-block:: cmake
-
-  if((${CMAKE_PROJECT_NAME} STREQUAL ${PROJECT_NAME} OR ${PROJECT_NAME}_BUILD_TESTING) AND BUILD_TESTING)
-    add_executable(${PROJECT_NAME}_tests)
-  endif()
-
-This ensures that the test is only build when the project is build as a standalone project or
-when the project is build as a dependency and the BUILD_TESTING flag is set and the ${PROJECT_NAME}_BUILD_TESTING flag is set.
-
-Integration tests
------------------
-
-**How can I run the integration tests?**
-
-To run the integration tests, you need to build and install everest-core:
-
-.. code-block:: bash
-
-  make
-  make install
-
-Then you need to install the testing tool:
-
-.. code-block:: bash
-
-  make install_everest_testing
-
-Now you can run the integration tests in the source directory:
-
-.. code-block:: bash
-
-  cd ${SOURCE_DIR}/tests
-  pytest --everest-prefix ${INSTALL_PREFIX} core_tests/*.py framework_tests/*.py
diff --git a/docs/latest/_sources/tutorials/how_to_ocpp/index.rst.txt b/docs/latest/_sources/tutorials/how_to_ocpp/index.rst.txt
@@ -26,7 +26,7 @@ Prerequisites
 =============
 
 If you're new to EVerest start with our
-:ref:`Quick Start Guide <quickstartguide_main>`
+`Quick Start Guide <02_quick_start_guide.html>`_
 to get a simulation in EVerest running for the first time.
 It is important that you have set up the required docker containers for
 Mosquitto and SteVe, which we will use as an example CSMS.
@@ -204,7 +204,7 @@ Configuring OCPP within EVerest
 ===============================
 
 To be able to follow the further explanations, you should be familiar with the configuration of EVerest modules.
-Take a look into :ref:`EVerest Module Concept <moduleconcept_main>` for that.
+Take a look into `EVerest Module Concept <04_module_concept.html>`_ for that.
 
 To configure the OCPP module of everest-core, find the available configuration parameters `in the manifest
 of the module <https://github.com/EVerest/everest-core/blob/main/modules/OCPP/manifest.yaml>`_.

diff --git a/docs/latest/appendix/02_snapshot.html b/docs/latest/appendix/02_snapshot.html
@@ -49,8 +49,8 @@ <h3>Navigation</h3>
 <span class="w">  </span><span class="nt">git_tag</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2024.2.0</span>
 <span class="nt">everest</span><span class="p">:</span>
 <span class="w">  </span><span class="nt">git</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">[email protected]:EVerest/EVerest.git</span>
-<span class="w">  </span><span class="nt">git_rev</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ae069aeb56b6fb42a0f7ba0a74df729fafa29b0d</span>
-<span class="w">  </span><span class="nt">git_tag</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">main</span>
+<span class="w">  </span><span class="nt">git_rev</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2a205779b8bdc1f068dbb9d9f690c6c92a6cd971</span>
+<span class="w">  </span><span class="nt">git_tag</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">doc/mz-framework-top-level</span>
 <span class="nt">everest-core</span><span class="p">:</span>
 <span class="w">  </span><span class="nt">git</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">[email protected]:EVerest/everest-core.git</span>
 <span class="w">  </span><span class="nt">git_rev</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ababee912a950d761975e6fbb82404d54a15f231</span>
@@ -68,7 +68,7 @@ <h3>Navigation</h3>
 <span class="w">  </span><span class="nt">git_tag</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">v0.2.0</span>
 <span class="nt">everest.github.io</span><span class="p">:</span>
 <span class="w">  </span><span class="nt">git</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">[email protected]:everest/everest.github.io.git</span>
-<span class="w">  </span><span class="nt">git_rev</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">0100d8ce8b7dfaea9bd4f866124075c4818c41b6</span>
+<span class="w">  </span><span class="nt">git_rev</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">9a31e88676eb8828960afbbe26e27f3c42a7d7f9</span>
 <span class="nt">ext-mbedtls</span><span class="p">:</span>
 <span class="w">  </span><span class="nt">cmake_condition</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">EVEREST_DEPENDENCY_ENABLED_MBEDTLS</span>
 <span class="w">  </span><span class="nt">git</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://github.com/EVerest/ext-mbedtls.git</span>
@@ -99,7 +99,6 @@ <h3>Navigation</h3>
 <span class="w">  </span><span class="nt">git_tag</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">v0.2.1</span>
 <span class="w">  </span><span class="nt">options</span><span class="p">:</span>
 <span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">BUILD_EXAMPLES OFF</span>
-<span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CMAKE_POSITION_INDEPENDENT_CODE ON</span>
 <span class="nt">libmodbus</span><span class="p">:</span>
 <span class="w">  </span><span class="nt">cmake_condition</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">EVEREST_DEPENDENCY_ENABLED_LIBMODBUS</span>
 <span class="w">  </span><span class="nt">git</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">https://github.com/EVerest/libmodbus.git</span>