Add extracted tools: CitrineOS, OpenOCPP, ShapeShifter

- CitrineOS core extracted (CSMS OCPP 2.0.1)
- OpenOCPP extracted (firmware OCPP 1.6J/2.0.1)
- ShapeShifter library installed (pip install -e)
- ShapeShifter specification extracted
- EVerest extracted

TODO updated with progress

tools/EVerest-main/docs/source/tutorials/setup-devcontainer/devrd.rst

@@ -0,0 +1,142 @@
+:title: Managed by devrd CLI
+
+######################################################
+Setup Variant: Service Containers Managed by devrd cli
+######################################################
+
+This variant utilizes the devrd CLI to manage service containers,
+making it an ideal choice for users who do not use VSCode.
+It provides dedicated control of the service containers independent
+of the devcontainer lifecycle. The devcontainer itself will not start
+or stop any service containers.
+
+.. note::
+
+    When using this variant and still using VSCode, the VSCode
+    built-in terminal cannot execute commands directly within the devcontainer.
+    Instead, use the devrd CLI to open an interactive session (see below).
+
+******************************
+What to expect from this setup
+******************************
+
+If one prefers to run the devcontainer outside VSCode, this setup variant is
+the right choice.
+
+The devrd cli will help to manage the service containers independent
+of the devcontainer lifecycle. So one can start and stop the service containers
+at any time.
+The contents of the EVerest repo are mapped inside the container
+in the directory ``/workspace``.
+
+*************
+Prerequisites
+*************
+
+To install the prerequisites, please check your operating system or distribution online documentation:
+
+- Docker installed [#docker]_
+- Docker compose installed version V2 (not working with V1) [#docker_compose]_
+
+**************
+Required Steps
+**************
+
+1. **Clone the EVerest repository**
+
+   If you have not done this yet, clone the EVerest repository
+   from GitHub to your local machine:
+
+   .. code-block:: bash
+
+       git clone https://github.com/EVerest/EVerest.git path/to/EVerest
+    
+   Where ``path/to/EVerest`` is the path where you want to
+   clone the repository to.
+
+2. **Build and start the devcontainer and service containers**
+
+   Change into the cloned repository directory:
+
+   .. code-block:: bash
+
+       cd path/to/EVerest
+
+   Then build and start the devcontainer and the service containers
+   with the devrd cli:
+
+   .. code-block:: bash
+
+       ./applications/devrd/devrd start
+
+   This will build and start the devcontainer and all service containers.
+   If not yet existing, devrd will generate the ``.devcontainer/.env`` file.
+
+3. **Open an interactive shell in the devcontainer**
+
+   To run commands inside the devcontainer, open an interactive shell
+   with the devrd cli:
+
+   .. code-block:: bash
+
+       ./applications/devrd/devrd prompt
+
+   This will open an interactive shell inside the devcontainer.
+   The contents of the EVerest repository are mapped
+   to the ``/workspace`` directory inside the container.
+
+   You can now run all development commands inside this shell.
+
+   To exit the shell, simply type ``exit`` or press ``Ctrl+D``.
+
+See the :doc:`howto </how-to-guides/devcontainer-usage/index>` to learn how to
+execute EVerest in a SIL using containers.
+
+*************************************
+Optional: Install bash/zsh completion
+*************************************
+
+If you want to enable completion on your host system follow the steps below.
+
+Install bash completion
+-----------------------
+
+Add the following lines to your ``~/.bashrc`` file:
+
+.. code-block:: bash
+
+    # bash completion for devrd cli
+    source applications/devrd/devrd-completion.bash
+
+Then reload your ``~/.bashrc`` file:
+
+.. code-block:: bash
+
+    source ~/.bashrc
+
+Install zsh completion
+----------------------
+
+Add the following lines to your ``~/.zshrc`` file:
+
+.. code-block:: bash
+
+    # zsh completion for devrd cli
+    autoload -U compinit && compinit
+    source applications/devrd/devrd-completion.zsh
+
+Then reload your ``~/.zshrc`` file:
+
+.. code-block:: bash
+
+    source ~/.zshrc
+
+See the :doc:`separate troubleshooting section <troubleshooting>` for help
+on devcontainer-specific issues.
+
+----
+
+**Authors:** Florian Mihut, Andreas Heinrich
+
+.. [#docker] `<https://docs.docker.com/engine/install/>`_
+.. [#docker_compose] `<https://docs.docker.com/compose/install>`_

tools/EVerest-main/docs/source/tutorials/setup-devcontainer/index.rst

@@ -0,0 +1,37 @@
+#######################################
+Setup the EVerest Development Container
+#######################################
+
+There are two variants for the devcontainer setup:
+
+.. grid:: 1 2 2 2
+    :gutter: 2
+
+    .. grid-item-card:: Service Containers managed by VSCode
+        :link: /tutorials/setup-devcontainer/vscode
+        :link-type: doc
+
+        Uses the VSCode Dev Containers extension, which manages both
+        the devcontainer and the service containers.
+
+    .. grid-item-card:: Service Containers managed by devrd cli
+        :link: /tutorials/setup-devcontainer/devrd
+        :link-type: doc
+
+        Uses the devrd cli to manage the service containers.
+        This variant can be used if one is not using VSCode or needs dedicated
+        control over the service containers.
+
+Also consider these documents:
+
+- :doc:`troubleshooting section <troubleshooting>` that deals for devcontainer-specific issues.
+- :doc:`How-to Guide: How to use a development container for EVerest development and sil testing </how-to-guides/devcontainer-usage/index>`
+- :doc:`Internals of the EVerest Development Container </explanation/devcontainer-internal/index>`
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    Managed by devrd CLI <devrd>
+    Managed by VSCode <vscode>
+    troubleshooting

tools/EVerest-main/docs/source/tutorials/setup-devcontainer/troubleshooting.rst

@@ -0,0 +1,110 @@
+###############
+Troubleshooting
+###############
+
+Port conflicts
+--------------
+
+Each instance uses the same ports (1883, 1880, 4000, etc.). Please note that only one instance can run at a time.
+If another process is using the port you need here is how to detect it and make it available:
+
+.. code-block:: bash
+
+    sudo lsof -ti:1880 \| xargs sudo kill -9
+    ./applications/devrd/devrd start
+
+If a system service is using a port (e.g. mosquitto) stopping/disabling this service may be required.
+
+Regenerate environment configuration
+------------------------------------
+
+If you suspect that the environment variables in the ``.env`` file
+are not correct, you can regenerate it with:
+
+.. code-block:: bash
+
+    ./applications/devrd/devrd env
+
+Customize environment variables
+--------------------------------
+
+To customize specific environment variables, you can edit the
+``.devcontainer/.env`` file directly or pass them as arguments to the ``./applications/devrd/devrd env`` command.
+
+.. note::
+
+    If you manually edit the ``.env`` file and change ``EVEREST_TOOL_BRANCH``
+    or other build arguments, you must rebuild the container for changes to take effect:
+
+Rebuild devrd setup
+-------------------
+
+The setup can be rebuild with:
+
+Option 1: Force rebuild (recommended)
+
+.. code-block:: bash
+
+    ./applications/devrd/devrd env                    # Regenerate .env if you edited it manually
+    ./applications/devrd/devrd build                  # Rebuild with new environment variables
+
+Option 2: Clean rebuild (if rebuild doesn't work)
+
+.. code-block:: bash
+
+    ./applications/devrd/devrd stop                   # Stop all containers, images, and volumes
+    ./applications/devrd/devrd purge                  # Remove all containers, images, and volumes
+    ./applications/devrd/devrd build                  # Rebuild from scratch
+
+
+Purge and rebuild devrd setup
+-----------------------------
+
+.. code-block:: bash
+
+    ./applications/devrd/devrd purge                  # Remove all resources for current folder
+    ./applications/devrd/devrd build                  # Will generate .env if missing
+
+
+Volume conflicts
+----------------
+
+Docker volumes are shared. Use
+
+.. code-block:: bash
+
+    ./applications/devrd/devrd purge
+
+before switching instances.
+
+SSH keys
+--------
+
+Ensure your SSH agent has the necessary keys for all repositories.
+
+Container naming
+----------------
+
+Docker containers are named based on the workspace directory to avoid conflicts.
+
+Switching between instances
+---------------------------
+
+When switching between different EVerest instances (e.g., different branches or forks),
+use the following commands:
+
+.. code-block:: bash
+
+    # Stop current instance
+    ./applications/devrd/devrd stop
+
+    # Purge if switching to different branch/project
+    ./applications/devrd/devrd purge
+
+    # Start new instance
+    cd ~/different-everest-directory
+    ./applications/devrd/devrd start
+
+----
+
+**Authors:** Florian Mihut, Andreas Heinrich

tools/EVerest-main/docs/source/tutorials/setup-devcontainer/vscode.rst

@@ -0,0 +1,109 @@
+:title: Managed by VSCode
+
+###################################################
+Setup Variant: Service Containers Managed by VSCode
+###################################################
+
+This variant makes use of the VSCode Dev Containers extension [#vscode_devcontainter]_
+.
+This will allow to run commands in the VSCode built-in terminal.
+It will manage the service containers by starting them together with
+the `devcontainer` itself. Dedicated control of individual services
+is not possible with this variant.
+
+******************************
+What to expect from this setup
+******************************
+
+By following the steps in this tutorial you will setup a development
+environment for EVerest using a development container (devcontainer).
+VSCode will automatically build the container. After this all development
+happens inside the container.
+
+The contents of the EVerest repo are mapped inside the container
+in the directory ``/workspace``
+You can exit VSCode at any time, re-running it will cause VSCode to ask you
+again to reopen in container.
+
+Opening the EVerest repository in the VSCode devcontainer will
+automatically start all of the provided service containers.
+
+*************
+Prerequisites
+*************
+
+To install the prerequisites, please check your operating system or distribution online documentation:
+
+- Docker installed [#docker]_
+- Docker compose installed version V2 (not working with V1) [#docker_compose]_
+- VS Code with Dev Containers extension installed [#vscode_devcontainter]_
+
+**************
+Required Steps
+**************
+
+1. **Clone the EVerest repository**
+
+   If you have not done this yet, clone the EVerest repository
+   from GitHub to your local machine:
+
+   .. code-block:: bash
+
+       git clone https://github.com/EVerest/EVerest.git path/to/EVerest
+
+   Where ``path/to/EVerest`` is the path where you want to
+   clone the repository to.
+
+2. **Open in VSCode**
+
+   Then open this repository in VSCode:
+
+   .. code-block:: bash
+
+       code path/to/EVerest
+   
+   Choose **Reopen in container** when prompted by VSCode.
+
+Now VSCode will build the devcontainer.
+This can take some time depending on your machine and internet connection.
+After this you can use the built-in terminal in VSCode to run commands
+inside the devcontainer as for example to build EVerest.
+
+*************
+Example Usage
+*************
+
+You can now use VSCode's terminal to issue commands inside the devcontainer, e.g. for building:
+
+.. code-block:: bash
+
+    docker@16898a21b4f1:/workspace$ mkdir build
+    docker@16898a21b4f1:/workspace$ cd build
+    docker@16898a21b4f1:/workspace$ cmake ..
+    docker@16898a21b4f1:/workspace$ cmake --build . --parallel 8
+
+This will readily build EVerest regardless of your host system setup.
+
+****************************************
+Tips for VSCode Dev Containers Extension
+****************************************
+
+When the repository is opened in VSCode you can enter the devcontainer at
+any time by running the command **Dev Containers: Reopen in Container** from the
+command palette (F1).
+You can also stop the devcontainer by running the command **Dev Containers: Reopen Folder Locally**.
+
+***************
+Troubleshooting
+***************
+
+See the :doc:`separate troubleshooting section <troubleshooting>` for help
+on devcontainer-specific issues.
+
+----
+
+**Authors:** Florian Mihut, Andreas Heinrich
+
+.. [#docker] `<https://docs.docker.com/engine/install/>`_
+.. [#docker_compose] `<https://docs.docker.com/compose/install>`_
+.. [#vscode_devcontainter] `<https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers>`_