feat(documentation): add documentation for the registry module

documentation/source/build_from_scratch.rst

@@ -0,0 +1,54 @@
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
+
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
+
+==========================================
+Build the Registry Module from the Scratch
+==========================================
+To run the SWAP-IT registry module, a local installed version of the C-based OPC UA SDK `open62541 <https://github.com/open62541/open62541>`_, version 1.4.6, is required, as well as a local installed version of the `open62541-server-template <https://github.com/FraunhoferIOSB/swap-it-open62541-server-template>`_.
+
+Installation Requirements
+=========================
+
+.. code-block:: c
+
+    /*install dependencies check and open62541*/
+    apt-get -y update
+    apt-get -y install git build-essential gcc pkg-config cmake python3 check
+    git clone https://github.com/open62541/open62541
+    cd open62541
+
+    /*switch to open62541 version 1.4.6*/
+    git fetch --all --tags
+    git checkout tags/v1.4.6 -b v1.4.6-branch
+
+    /* init submodules, build and install open62541*/
+    git submodule update --init --recursive
+    mkdir build && cd build
+    cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo -DUA_NAMESPACE_ZERO=FULL -DUA_ENABLE_JSON_ENCODING=ON -DUA_MULTITHREADING=200 ..
+    make install
+
+    /*install the server template*/
+    git clone https://github.com/FraunhoferIOSB/swap-it-open62541-server-template
+    cd swap-it-open62541-server-template
+    mkdir build && cd build
+    cmake ..
+    make install
+
+Build and Deploy the Registry Module
+====================================
+
+After installing the dependencies, the registry module can be deployed with
+
+.. code-block:: c
+
+    /*build and start the registry module*/
+    git clone https://github.com/FraunhoferIOSB/swap-it-registry-module
+    cd swap-it-registry-module
+    mkdir build && cd build
+    cmake ..
+    make
+    ./swap-it-registry-module

documentation/source/contact.rst

@@ -0,0 +1,14 @@
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
+
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
+
+
+========
+Contact
+========
+
+For further questions about the SWAP-IT software components or the patient zero application,
+please contact Florian Düwel (florian.duewel@fraunhofer.iosb.de) or Andreas Ebner (andreas.ebner@fraunhofer.iosb.de).

documentation/source/deploy_from_docker.rst

@@ -0,0 +1,20 @@
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
+
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
+
+=================================
+Deploy pre-build Docker container
+=================================
+
+The `SWAP-IT Demo Scenario <https://github.com/swap-it/demo-scenario>`_ Repository provides pre-build docker container for SWAP-IT software components. From there, a pre-build container of the Registry Module can be deployed with:
+
+.. code-block:: c
+
+    //pull the image
+    docker pull ghcr.io/swap-it/demo-scenario/device_registry:latest
+
+    //start the image
+    docker run -p 8000:8000 --add-host host.docker.internal:host-gateway ghcr.io/swap-it/demo-scenario/device_registry:latest

documentation/source/getting_started.rst

@@ -0,0 +1,20 @@
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
+
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
+
+
+================
+Getting Started
+================
+
+The SWAP-IT Registry Module can either be build, or deployed from a pre-build docker container. The default url of the registry module is: **opc.tcp://localhost:8000**
+
+.. toctree::
+   :maxdepth: 2
+
+   build_from_scratch
+   deploy_from_docker
+   tutorials

documentation/source/glossary.rst

@@ -0,0 +1,34 @@
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
+
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
+
+
+========
+Glossary
+========
+.. glossary::
+
+    PFDL Scheduler
+        Generates a petri net out of a PFDL description of a process and schedules the specified services and tasks.
+
+    Execution Engine
+        Interface between the PFDL scheduler and field level resources that executes the scheduled services on the field level. In addition, it handles the parameter flow between services and tasks.
+
+    Process Agent
+        Agent consisting of a PFDL scheduler and an Execution Engine. It drives the execution of the process specified within a PFDL.
+
+    Device Registry
+        Registry Module where resource OPC UA server, representing field level devices, can register themself and thus, make themself available to execute PFDL services. In addition,
+        the Device Registry has a build-in functionality to filter suitable resources for a service execution based on a resource's capabilities.
+
+    Assignment Agent
+        Entity that interacts with an Execution Engine and a Device Registry to assign a service to one concrete resource out of a set of possible resources.
+
+    OPC UA Information Model
+        Contains all nodes and references to map a specific entity to an OPC UA server.
+
+    PFDL
+      The Production Flow Description Language is a domain specific language that describes a production order. It is parsed by the scheduler and transformed into a structure to schedule the execution.

documentation/source/index.rst

@@ -1,20 +1,47 @@
-.. SWAP-IT Registry Module documentation master file, created by
-   sphinx-quickstart on Tue Nov 26 17:03:09 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
 
-Welcome to SWAP-IT Registry Module's documentation!
-===================================================
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 4
+
+
+.. _SWAP_IT_REGISTRY_MODULE:
+
+=======================
+SWAP-IT Registry Module
+=======================
+
+The SWAP-IT Registry Module is a base module of the `SWAP-IT Architecture <https://github.com/swap-it/demo-scenario>`_. The module is supposed to map server of SWAP-Assets and thus,
+make them available for process execution steps. Doing so, the Registry Module provides three main functionalities,
+which can be accessed through OPC UA Method calls:
+
+1. **Register Asset:** The addition of an Asset to the Registry Module. The Data Values are mapped to the registry module and the
+asset can be considered for process execution steps within the SWAP-IT Architecture.
+
+2. **Unregister Asset:** The removal of an Asset from the Registry Module. The Data Values are no longer mapped to the registry module and the
+asset cannot be considered for process execution steps within the SWAP-IT Architecture anymore.
+
+3. **Filter Asset:** Provision of assets to the swap-it-execution-engine from a set of registered assets. The Filter Asset Method can
+evaluate product capabilities and match them against asset capabilities.
+
+
+.. figure:: /images/registry_overview.png
+   :alt: SWAP-IT Overview
+   :width: 100%
+
+.. toctree::
+   :maxdepth: 4
    :caption: Contents:
 
+   swap-it-architecture
+   getting_started
+   related_projects
+   glossary
+   contact
 
 
-Indices and tables
-==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

documentation/source/related_projects.rst

@@ -0,0 +1,19 @@
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
+
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
+
+
+================
+Related-Projects
+================
+Further open source applications from the SWAP-IT context are:
+
+- `PFDL-Scheduler <https://github.com/iml130/pfdl>`_
+- `Process-Agent <https://github.com/FraunhoferIOSB/swap-it-execution-engine>`_
+- `open62541-server-template <https://github.com/FraunhoferIOSB/swap-it-open62541-server-template>`_
+- `open62541 OPC UA SDK <https://github.com/open62541/open62541>`_
+- `Common Information Model <https://github.com/FraunhoferIOSB/swap-it-common-information-model>`_
+- `SWAP-IT Demonstration Scenario <https://github.com/swap-it/demo-scenario>`_

documentation/source/swap-it-architecture.rst

@@ -0,0 +1,50 @@
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
+
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
+
+====================
+SWAP-IT Architecture
+====================
+
+The SWAP-IT architecture introduces a modular, scalable and lightweight architecture utilizing simplified semantic information
+models. In general, components of the architecture are split into two types of modules. On the one hand, the *Basic Modules* are the core components of the architecture
+by enabling the interaction with the loosely coupled components. All basic components will be published as open source software projects for a simple adaption to enable an automate integration of new processes, based on the
+`Production Flow Description Language (PFDL) <https://github.com/iml130/pfdl>`_. On the other hand, *Use Case specific Modules* integrate existing shop floor assets, either physical assets, such as production resources, or non physical assets,
+such as optimization approaches to assign jobs to resources. Since these components can vary from production environment to production environment,
+the SWAP-IT architecture provides an easy integration mechanism for existing and new assets. As a result, the SWAP-IT architecture enables industrial production environments with a high degrees
+of flexibility, easy process integration and in addition, addresses further challenges of production environments, such as an automated
+resource parameterization for individual products, or an easy integration of new assets into a shop floor.
+
+.. figure:: /images/swap_it_general.PNG
+   :alt: SWAP-IT Overview
+   :width: 100%
+
+For this to be achieved, one process module executes exactly one process that is specified in the PFDL format.
+The Enterprise Resource Planning (ERP) module is utilized to submit orders and the registry module makes resources available for process agents. Each resource on a shop floor is defined as a SWAP-IT Asset (*Use-Case Specific Modules*). Such assets can easily
+be defined by utilizing the SWAP-IT `Common Information Model <https://github.com/FraunhoferIOSB/swap-it-common-information-model>`_. As a result, new assets can easily be integrated into the architecture.
+An example interaction between the SWAP-IT assets is shown in the sequence diagram below. As starting point, each shop floor *Asset* that should be available for the execution of process steps has to register itself in the *Registry Module*. Here, an arbitrary number of assets, that
+are able to execute any given process step, can register themself within the *Registry Module*.
+An Process execution starts with the submission of an order from a *Customer*. Afterwards, the *ERP Module* generates the process description (*PFDL*) for the order and transmits it to a *Process Agent*. Within the *Process Agent* the *PFDL Scheduler* interprets
+the the PFDL and starts to schedule specified services. Each scheduled service is then transmitted to the *Execution Engine*, which in turn, requests all suitable *Assets* to execute the service from the *Registry Module*. Afterwards, the *Execution Engine* interacts
+with an *Assignment Asset* to find the best asset in the context of the specified optimization approach. While these interaction steps are the recommended way to assign a service to an *Asset*, the architecture incorporates additional assignment approaches. Further details
+about these approaches can be found in the  `Process Agent Project <https://fraunhoferiosb.github.io/swap-it-execution-engine/ResourceAssignment.html>`_. After an *Asset* is found, the *Execution Engine* initiates the service execution on this particular asset and then, returns the service result to the *PFDL Scheduler*. Although the
+sequence diagram only displays a single service execution, the *Process Agent* can execute an arbitrary number of process steps until the production process of a product is completed. After the completion of the production process, the *ERP Module* receives a notification from
+the *Process Agent* and can inform the customer that the order is completed.
+
+.. figure:: /images/SWAPSequence.PNG
+   :alt: Sequence Diagram SWAP-It Components
+   :width: 100%
+
+
+SWAP-IT Software
+================
+
+The application consists of a set of loosely coupled software components. The figure below depicts all software components that are currently available as open source projects, or will be published as open source projects within 2024.
+The development status and the interaction of these components is shown in the figure below.
+
+.. figure:: /images/img_1.png
+   :alt: Development Status SWAP-IT Software Components
+   :width: 100%

documentation/source/tutorials.rst

@@ -0,0 +1,10 @@
+..
+    Licensed under the MIT License.
+    For details on the licensing terms, see the LICENSE file.
+    SPDX-License-Identifier: MIT
+
+   Copyright 2024 (c) Fraunhofer IOSB (Author: Florian Düwel)
+
+============
+Tutorials
+============