diff --git a/README.md b/README.md index 7ec69482d..98fe07258 100644 --- a/README.md +++ b/README.md @@ -26,14 +26,14 @@ if there is a suggestion to improve the software. If you find this repo useful for your research, please consider citing our paper: ```bibtex -@misc{talasila2023digital, - title={Digital Twin as a Service (DTaaS): A Platform for Digital Twin Developers and Users}, - author={Prasad Talasila and Cláudio Gomes and Peter Høgh Mikkelsen and Santiago Gil Arboleda and Eduard Kamburjan and Peter Gorm Larsen}, - year={2023}, - eprint={2305.07244}, - archivePrefix={arXiv}, - primaryClass={cs.SE} -} +@INPROCEEDINGS{talasila2023dtaas, + author={Talasila, Prasad and Gomes, Cláudio and Mikkelsen, Peter Høgh and Arboleda, Santiago Gil and Kamburjan, Eduard and Larsen, Peter Gorm}, + booktitle={2023 IEEE Smart World Congress (SWC)}, + title={Digital Twin as a Service (DTaaS): A Platform for Digital Twin Developers and Users}, + year={2023}, + pages={1-8}, + keywords={digital twins;physical twin;automation;life cycle;composition}, + doi={10.1109/SWC57546.2023.10448890}} ``` ## :hammer_and_wrench: Development Setup diff --git a/docs/developer/index.md b/docs/developer/index.md index ba888b565..1f42881e3 100644 --- a/docs/developer/index.md +++ b/docs/developer/index.md @@ -2,8 +2,8 @@ This guide is to help developers get familiar with the project. Please see developer-specific -[Slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/DTaaS-overview.pdf), -[Video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/DTaaS-overview.mp4), +[Slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/DTaaS-developer-overview_march2024.pdf), +[Video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/DTaaS-developer-overview_march2024.mp4), and [Research paper](https://arxiv.org/abs/2305.07244). ## :computer: Development Environment diff --git a/docs/developer/system/C4-L1_diagram.png b/docs/developer/system/C4-L1_diagram.png deleted file mode 100755 index 903ac582b..000000000 Binary files a/docs/developer/system/C4-L1_diagram.png and /dev/null differ diff --git a/docs/developer/system/C4-L2_diagram.png b/docs/developer/system/C4-L2_diagram.png new file mode 100755 index 000000000..6f7f3c770 Binary files /dev/null and b/docs/developer/system/C4-L2_diagram.png differ diff --git a/docs/developer/system/C4-L2_diagram_detailed.png b/docs/developer/system/C4-L2_diagram_detailed.png deleted file mode 100755 index c91c9fd41..000000000 Binary files a/docs/developer/system/C4-L2_diagram_detailed.png and /dev/null differ diff --git a/docs/developer/system/C4-L2_diagram_simplified.png b/docs/developer/system/C4-L2_diagram_simplified.png deleted file mode 100755 index d2ebd6ab5..000000000 Binary files a/docs/developer/system/C4-L2_diagram_simplified.png and /dev/null differ diff --git a/docs/developer/system/DTaaS.drawio b/docs/developer/system/DTaaS.drawio index 52ec9cbff..d237e7710 100755 --- a/docs/developer/system/DTaaS.drawio +++ b/docs/developer/system/DTaaS.drawio @@ -1,12 +1,9 @@ - + - + - - - @@ -82,243 +79,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -560,1191 +320,1468 @@ - - + + - - + + + + + + + + + + + + + + + + + - - + + - - + + - - + + - - + + - - + + - - - - - + + - - - - - + + - - - - - + + - - - - - - + + - - + + - - + + - + - - + + - - - - - - - - - - - - - - - - - + + + + + - - + + + + + + - - + + - - + + - + - - + + - + - - - - - - - - - + + - - + + - - + + - - + + - - + + - + - - + + - - + + - - + + + + + - - + + - - + + - - + + - - + + - - - - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - - - - + + - - + + - - - - - - - - - + + - - + + - - + + - - - - - + + - - + + - - + + - - + + - - - - - + + - - + + - - + + - - - - - + + - - + + - - + + - - + + - - + + - - + + - - - - - + + - - - - - + + - - - - - + + - - - - - - + + - - + + - - + + - - - - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - + + - + - - + + - - - - - + - - - - - + + - - - - + - - + + - - - - - + + - - + + - - + + - - + + - - + + - - - - - - - - - - - + + - - + + - - - - - - - - - - + - - + + - - + + + + + - - - - + - - + + - - + - - - - - + + + + + - + - - + + - - + + - - + + - - + + - - - - - + + - - + + - - + + - - - - - + + - - - - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - + + + + + + + + + + + + + + - + + + + + + + + + + - - + + - + - - + + - + - - + + - - + + - - + + - + - - + + - - - - - + + + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - + + - + - - + + - - - - - + - - + + - - + + - - + + - + + + + + + + - - + + + + + + + + - - - - - + + + + + + + + - - + + + + + - - + + - - + + - - + + - - - - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - - - - - + + - - - - - - - - - + + - - + + - - + + - - - - - + + - - + + - - + + - - + + - - - - - + + + + + - - + + - + + + + - - + + - + - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + - - - - - - + + + + + + - - - + + + + - - - - - - + + + + + + - - - - - - - + + + + + + + + + + - - - - + + + + + + + - - - - - - + + + + + + + + + + + + + + + + + + + + + + + - + - + - - + + - - + + - + + - + - + - - - - - - + + + + + + + + + + - - - + + + - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + - - - + + + + + + + + + + + - - - + + + - - - - - + + + + + - - + - - - - - - + + + + + - - - - + + + + + + + + + + + + + + + - - - - - - + + + + + + + + + + - + + + - - - + + + - - - - - - + + + + + - - + + + - - - + + + + + + + + + + + - - - - - - + + + + + + + + + + + + + + - - - - - + + + + + - + + - + - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - + + + + + - + - - - + + + - - - - - + + + + + + + + + + + + + + + + + + + - - + + + + + + + + + + + + + + + + + + - - + + - - - + + + + + + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + - - - + + + - - - + + + - - - - - + + + + + + + + + - - - + + + + + + + + + + + + + + + + - - + + - - - - - + + - - - + + + - - - + + + + + + + + + - - - - - + + + + + - - + - - - - - + + + + + - - - - + + - + - - - - - - + + + + + - + + + - - - + + + - - - - - - + + + + + + + + + + - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + - + - - - - - - - - - - + + + + + - + + - + - - + + - - - - - - + + + + + + + + + + + + - - - - - - + + + + + - - - - + + - - - - - + + + + + + + + + - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + - - - + - - - - - - + + + + + + + + + + - - - + + + - - - + + + + + + - - - + + + - - - + + + + + + + + + + - - - + + + + + + + + + + + + - - - + + + + + + - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + - - - + + + - - - - - - + + + + + - - + + - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -2886,7 +2923,7 @@ - + @@ -3637,10 +3674,10 @@ - + - + @@ -3680,7 +3717,7 @@ - + @@ -3695,13 +3732,13 @@ - + - + @@ -3717,45 +3754,45 @@ - + - + - + - + - + - + - + - + - + - + - + - + @@ -3765,10 +3802,10 @@ - + - + @@ -3778,32 +3815,32 @@ - + - + - + - + - + - + - + - + diff --git a/docs/developer/system/architecture.md b/docs/developer/system/architecture.md index 14aa925e1..bb97b0f6b 100644 --- a/docs/developer/system/architecture.md +++ b/docs/developer/system/architecture.md @@ -25,11 +25,8 @@ the platform users expect the following features: 1. **Save** – save the state of a DT that’s already in the execution phase. This functionality is required for on demand saving and re-spawning of DTs. -1. **What-if analysis** – explore alternative scenarios to (i) - plan for an optimal next step, (ii) recalibrate new DT - assets, (iii) automated creation of new DTs or their - assets; these newly created DT assets may be used to - perform scientifically valid experiments. +1. **Services** – integrate DTs with on-platform or external + services with which users can interact with. 1. **Share** – share a DT with other users of their organisation. ## System Architecture @@ -40,15 +37,16 @@ The figure shows the system architecture of the the DTaaS software platform. ### System Components -The users interact with the software platform using a website. -The gateway is a single point of entry for direct access to the platform -services. The gateway is responsible for controlling user access to +The users interact with the software platform using a webapp. +The service router is a single point of entry for direct access to the platform +services. The service router is responsible for controlling user access to the microservice components. The service mesh enables discovery of microservices, load balancing and authorization functionalities. -In addition, there are microservices for catering to author, store, -explore, configure, execute and scenario analysis requirements. +In addition, there are microservices for catering to managing +DT reusable assets, platform services, DT lifecycle manager, +DT execution manager, accouting and security. The microservices are complementary and composable; they fulfil core requirements of the system. @@ -57,7 +55,7 @@ The microservices responsible for satisfying the user requirements are: 1. **The security microservice** implements role-based access control (RBAC) in the platform. 1. **The accounting microservice** is responsible for keeping track of the - platform, DT asset and infrastructure usage. Any licensing, + live status of platform, DT asset and infrastructure usage. Any licensing, usage restrictions need to be enforced by the accounting microservice. Accounting is a pre-requisite to commercialisation of the platform. @@ -65,57 +63,39 @@ The microservices responsible for satisfying the user requirements are: infrastructure and resources via the platform, the accounting microservice needs to interface with accounting systems of the external services. - -1. **The data microservice** is a frontend to all the databases - integrated into the platform. A time-series database and a - graph database are essential. These two databases store timeseries - data from PT, events on PT/DT, commands sent by - DT to PT. The PTs uses these databases even when their - respective DTs are not in the execute phase. -1. **The visualisation microservice** is again a frontend to - visualisation software that are natively supported inside the platform. - Any visualisation software running either on external - systems or on client browsers do not need to interact with - this microservice. They can directly use the data provided by - the data microservice. - -## C4 Architectural Diagrams - -The C4 architectural diagrams of the DTaaS software are presented here. - -### Level 1 - -This Level 1 diagram only shows the users and the roles -they play in the DTaaS software. - -C4 Level 1 diagram - -### Level 2 - -This simplified version of Level 2 diagram shows -the software containers of the DTaaS software. - -![C4 Level 2 diagram](C4-L2_diagram_simplified.png) +1. **User Workspaces** are virtual environments in which users can perform + lifecycle operations on DTs. These virtual environments are either docker + containers or virtual machines which provide desktop interface to users. +1. **Reusable Assets** are assets / parts from which DTs are created. + Further explation is available on + the [assets page](../../user/servers/lib/assets.md) +1. **Services** are dedicated services available to all the DTs and + users of the DTaaS platform. Services build upon DTs and + provide user interfaces to users. +1. **DT Execution Manager** provides virtual and isolated execution + environments for DTs. The execution manager is also responsible + for dynamic resource provisioning of cloud resources. +1. **DT Lifecycle Manager** manages the lifecycle operations on all DTs. + It also directs _DT Execution Manager_ to perform execute, save and + terminate operations on DTs. If you are interested, please take a look at -the [detailed diagram](C4-L2_diagram_detailed.png). - -Please note that the given diagram only -covers DT Lifecycle, Reusable Assets and Execution Manager. +the [C4 architectural diagram](C4-L2_diagram.png). -## Mapping +A mapping of the architectural components to related pages in +the documentation is available in the table. -A mapping of the C4 level 2 containers to components -identified in the system architecture is also available in the table. - -| System Component | Container(s) | +| System Component | Doc Page(s) | | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | -| Gateway | [Traefik Gateway](https://github.com/INTO-CPS-Association/DTaaS/tree/feature/distributed-demo/servers/config/gateway#the-gateway-server) | -| Unified Interface | [React Webapplication](../client/client.md) | +| Service Router | [Traefik Gateway](https://github.com/INTO-CPS-Association/DTaaS/tree/feature/distributed-demo/servers/config/gateway#the-gateway-server) | +| Web Application | [React Webapplication](../client/client.md) | | Reusable Assets | [Library Microservice](../servers/lib/lib-ms.md) | -| Data | MQTT, InfluxDB, RabbitMQ, Grafana and MongoDB (not shown in the C4 Level 2 diagram) | -| Visualization | InfluxDB (not shown in the C4 Level 2 diagram) | -| DT Lifecycle | DT Lifecycle Manager and DT Configuration Validator | +| Services | [Third-party Services](./../../admin/services.md) (MQTT, InfluxDB, RabbitMQ, Grafana and MongoDB) | +| DT Lifecycle | Not available yet | | Security | [Gitlab OAuth](../../admin/client/auth.md) | -| Accounting | None | -| Execution Manager | Execution Manager | +| Accounting | Not available yet | +| Execution Manager | Not available yet | + +## References + +Font sources: [fileformat](https://www.fileformat.info) diff --git a/docs/developer/system/architecture.png b/docs/developer/system/architecture.png old mode 100644 new mode 100755 index 49151cd88..2052a51ba Binary files a/docs/developer/system/architecture.png and b/docs/developer/system/architecture.png differ diff --git a/docs/developer/system/current-status-developer-2.png b/docs/developer/system/current-status-developer-2.png index 70349a7a0..e611990d8 100755 Binary files a/docs/developer/system/current-status-developer-2.png and b/docs/developer/system/current-status-developer-2.png differ diff --git a/docs/developer/system/current-status-developer.png b/docs/developer/system/current-status-developer.png index 27512c20b..7cc1b134a 100755 Binary files a/docs/developer/system/current-status-developer.png and b/docs/developer/system/current-status-developer.png differ diff --git a/docs/developer/system/current-status.md b/docs/developer/system/current-status.md index 86f693a23..3b93d9a3a 100644 --- a/docs/developer/system/current-status.md +++ b/docs/developer/system/current-status.md @@ -7,9 +7,7 @@ The figure below shows the current status of the development work. ![Current development status](current-status-developer.png) -If you are interested in C4 representation of the same diagram, -please take a look at -the [C4 L2 diagram](current-status-developer-2.png). +A C4 representation of the same diagram is also [available](current-status-developer-2.png). ## :lock: User Security @@ -89,8 +87,12 @@ The development priorities for the DTaaS software development team are: (API Interface to DT) * Multi-user and microservice security * Increased automation of installation procedures +* Upgrade software stack of user workspaces * DT Configuration DSL ín the form of YAML schema * UI for DT creation -* DT examples -Your contributions and collaboration are highly welcome. +Your contributions are highly welcome. + +## References + +Font sources: [fileformat](https://www.fileformat.info) diff --git a/docs/index.md b/docs/index.md index d971bdc57..370ecd65e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,9 +15,9 @@ with other users. It is also possible to share the services offered by one DT with other users. There is an overview of the software available in the form of -[slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/DTaaS-short-intro.pdf), -[video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/DTaaS-short-intro.mp4), -and [feature walkthrough](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/dtaas-v0.3-demo.mp4). +[slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/DTaaS-short-intro_jan2024.pdf), +[video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/DTaaS-short-intro_jan2024.mp4), +and [feature walkthrough](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/dtaas-v0.4-demo.mp4). ## License diff --git a/docs/user/examples/examples.drawio b/docs/user/examples/examples.drawio index 25224746b..3817a1373 100755 --- a/docs/user/examples/examples.drawio +++ b/docs/user/examples/examples.drawio @@ -1,6 +1,6 @@ - + - + @@ -792,96 +792,96 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + @@ -889,44 +889,44 @@ - + - + - + - + - + - + - + - + - + - + @@ -934,4 +934,643 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/user/examples/flex-cell/README.md b/docs/user/examples/flex-cell/README.md new file mode 100644 index 000000000..9ecc9a388 --- /dev/null +++ b/docs/user/examples/flex-cell/README.md @@ -0,0 +1,249 @@ +# Flex Cell Digital Twin with Two Industrial Robots + +## Overview + +The flex-cell Digital Twin is a case study with two industrial robotic arms, +a UR5e and a Kuka LBR iiwa 7, working in a cooperative setting +on a manufacturing cell. + +![Flex-cell Physical Setup](physical-twin.jpg) + +The case study focuses on the robot positioning in +the discrete cartesian space of the flex-cell working space. +Therefore, it is possible to send (X,Y,Z) commands to both robots, +which refer to the target hole and height they want should move to. + +The flex-cell case study is managed using the `TwinManager` +(formerly `DTManager`), which is packed as a jar library in the tools, +and run from a java main file. + +The `TwinManager` uses Maestro as a slave for co-simulation, +so it generates the output of the co-simulation and can interact with +the real robots at the same time (with the proper configuration and setup). +The mainfile can be changed according to the application scope, i.e., +the `/workspace/examples/tools/flex-cell/FlexCell.java` can be +manipulated to get a different result. + +The `/workspace/examples/models/flex-cell/` folder contains +the `.fmu` files for the kinematic models of the robotic arms, +the `.urdf` files for visualization (including the grippers), and +the `.aasx` files for the schema representation with +Asset Administration Shell. + +The case study also uses RabbitMQFMU to inject values into the co-simulation, +therefore, there is the rabbitmqfmu in the models folder as well. +Right now, RabbitMQFMU is only used for injecting values into +the co-simulation, but not the other way around. +The `TwinManager` is in charge of reading the values from +the co-simulation output and the current state of the physical twins. + +## Example Structure + +![Flex-cell system architecture with the DT Manager](dt-structure.png) + +## Digital Twin Configuration + +This example uses seven models, five tools, six data, two functions, +and one script. The specific assets used are: + +| Asset Type | Names of Assets | Visibility | Reuse in Other Examples | +|:---|:---|:---|:---| +| Model | kukalbriiwa_model.fmu | Private | No | +| | kuka_irw_gripper_rg6.urdf | Private | No | +| | kuka.aasx | Private | No | +| | ur5e_model.fmu | Private | No | +| | ur5e_gripper_2fg7.urdf | Private | No | +| | ur5e.aasx | Private | No | +| | rmq-vhost.fmu | Private | Yes | +| Tool | maestro-2.3.0-jar-with-dependencies.jar | Common | Yes | +| | TwinManagerFramework-0.0.2.jar | Private | Yes | +| | urinterface | Private | No | +| | kukalbrinterface | Private | No | +| | robots_flexcell | Private | No | +| | FlexCell.java (main script) | Private | No | +| Data | publisher-flexcell-physical.py | Private | No | +| | ur5e_mqtt_publisher.py | Private | No | +| | connections.conf | Private | No | +| | outputs.csv | Private | No | +| | kukalbriiwa7_actual.csv | Private | No | +| | ur5e_actual.csv | Private | No | +| Function | plots.py | Private | No | +| | prepare.py | Private | No | + +## Lifecycle Phases + +The lifecycles that are covered include: + +1. Installation of dependencies in the create phase. +1. Preparing the credentials for connections in the prepare phase. +1. Execution of the experiment in the execution phase. +1. Saving experiments in the save phase. +1. Plotting the results of the co-simulation and the real data coming from +1. the robots in the analyze phase. +1. Terminating the background processes and cleaning up the outputs + in the termination phase. + +| Lifecycle Phase | Completed Tasks | +| --------- | ------- | +| Create | Installs Java Development Kit for Maestro tool, Compiles source code of DTManager to create a usable jar package (used as tool) | +| Prepare | Takes the RabbitMQ and MQTT credentials in connections.conf file and configures different assets of DT. | +| Execute | The DT Manager executes the flex-cell DT and produces output in `data/flex-cell/output` directory | +| Save | Save the experimental results | +| Analyze | Uses plotting functions to generate plots of co-simulation results | +| Terminate | Terminating the background processes | +| Clean | Cleans up the output data | + +## Run the example + +To run the example, change your present directory. + +```bash +cd /workspace/examples/digital twins/flex-cell +``` + +If required, change the execute permission of lifecycle scripts +you need to execute, for example: + +```bash +chmod +x lifecycle/create +``` + +This example requires Java 11. The **create** script installs Java 11; +however if you have already installed other Java versions, your default _java_ +might be pointing to another version. You can check and modify the default +version using the following commands. + +```bash +java -version +update-alternatives --config java +``` + +Now, run the following scripts: + +### Create + +Installs Open Java Development Kit 11 and pip dependencies. +Also creates `DTManager` tool (DTManager-0.0.1-Maestro.jar) from source code. + +```bash +lifecycle/create +``` + +### Prepare + +Configure different assets of DT with these credentials. +The `functions/flex-cell/prepare.py` script is used for this purpose. +The only thing needed to set up the connection is to update the file +`/workspace/examples/data/flex-cell/connections.conf` with +the connection parameters for MQTT and RabbitMQ and then execute +the ```prepare``` script. + +```bash +lifecycle/prepare +``` + +The following files are updated with the configuration information: + +1. `/workspace/examples/digital_twins/flex-cell/kuka_actual.conf` +1. `/workspace/examples/digital_twins/flex-cell/ur5e_actual.conf` +1. `/workspace/examples/tools/flex-cell/publisher-flexcell-physical.py` +1. `modelDescription.xml` for the RabbitMQFMU require special credentials + to connect to the RabbitMQ and the MQTT brokers. + +### Execute + +Execute the flex-cell digital twin using DTManager. DTManager in-turn runs +the co-simulation using Maestro. Generates the co-simulation output.csv file +at `/workspace/examples/data/flex-cell/output`. + +```bash +lifecycle/execute +``` + +### Save + +Each execution of the DT is treated as a single run. The results of +one execution are saved as time-stamped co-simulation output file in +The DT Manager executes the flex-cell digital twin and produces output +in `data/flex-cell/output/saved_experiments` directory. + +```bash +lifecycle/execute +``` + +### Analyze + +There are dedicated plotting functions in `functions/flex-cell/plots.py`. +This script plots the co-simulation results against the recorded values +from the two robots. + +```bash +lifecycle/analyze +``` + +### Terminate + +Stops the Maestro running in the background. Also stops any other +jvm process started during **execute** phase. + +```bash +lifecycle/terminate +``` + +### Clean + +Removes the output generated during execute phase. + +```bash +lifecycle/clean +``` + +## Examining the results + +Executing this Digital Twin will generate a co-simulation output, +but the results can also be monitored from updating +the `/workspace/examples/tools/flex-cell/FlexCell.java` with +a specific set of `getAttributeValue` commands, such as shown in the code. +That main file enables the online execution and comparison on Digital Twin +and Physical Twin at the same time and at the same abstraction level. + +The output is generated to the +`/workspace/examples/data/flex-cell/output` folder. +In case a specific experiments is to be saved, the `save` +lifecycle script stores the co-simulation results into +the `/workspace/examples/data/flex-cell/output/saved_experiments` folder. + +In the default example, the co-simulation is run for 10 seconds in +steps of 0.5 seconds. +This can be modified for a longer period and different step size. +The output stored in `outputs.csv` contains the joint position of +both robotic arms and the current discrete (X,Y,Z) position of +the TCP of the robot. +Additional variables can be added, such as the discrete (X,Y,Z) position +of the other joints. + +When connected to the real robots, the tools `urinterface` and +`kukalbrinterface` log their data at a higher sampling rate. + +## References + +The [RabbitMQ FMU](https://github.com/INTO-CPS-Association/fmu-rabbitmq) +github repository contains complete documentation and source code of +the rmq-vhost.fmu. + +More information about the DT Manager and the case study is available in: + +1. D. Lehner, S. Gil, P. H. Mikkelsen, P. G. Larsen and M. Wimmer, + "An Architectural Extension for Digital Twin Platforms to Leverage + Behavioral Models," 2023 IEEE 19th International Conference on + Automation Science and Engineering (CASE), Auckland, + New Zealand, 2023, pp. 1-8, doi: 10.1109/CASE56687.2023.10260417. +1. S. Gil, P. H. Mikkelsen, D. Tola, C. Schou and P. G. Larsen, + "A Modeling Approach for Composed Digital Twins in Cooperative + Systems," 2023 IEEE 28th International Conference on Emerging + Technologies and Factory Automation (ETFA), Sinaia, Romania, 2023, + pp. 1-8, doi: 10.1109/ETFA54631.2023.10275601. +1. S. Gil, C. Schou, P. H. Mikkelsen, and P. G. Larsen, “Integrating + Skills into Digital Twins in Cooperative Systems,” in 2024 IEEE/SICE + International Symposium on System Integration (SII), 2024, pp. 1124–1131, + doi: 10.1109/SII58957.2024.10417610. diff --git a/docs/user/examples/flex-cell/dt-structure.png b/docs/user/examples/flex-cell/dt-structure.png new file mode 100644 index 000000000..cf63ea70f Binary files /dev/null and b/docs/user/examples/flex-cell/dt-structure.png differ diff --git a/docs/user/examples/flex-cell/physical-twin.jpg b/docs/user/examples/flex-cell/physical-twin.jpg new file mode 100644 index 000000000..71d47675d Binary files /dev/null and b/docs/user/examples/flex-cell/physical-twin.jpg differ diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md index 7260ec7f5..d460b61e9 100644 --- a/docs/user/examples/index.md +++ b/docs/user/examples/index.md @@ -33,5 +33,6 @@ to use the examples in the following order. 1. [Desktop Robotti and RabbitMQ](./drobotti-rmqfmu/README.md) 1. [Water Treatment Plant and OPC-UA](./opc-ua-waterplant/README.md) 1. [Three Water Tanks with DT Manager Framework](./three-tank/README.md) +1. [Flex Cell Digital Twin with Two Industrial Robots](./flex-cell/README.md) :material-download: [DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples) diff --git a/docs/user/servers/lib/assets.md b/docs/user/servers/lib/assets.md index cc47ffc76..72ac42855 100644 --- a/docs/user/servers/lib/assets.md +++ b/docs/user/servers/lib/assets.md @@ -6,22 +6,10 @@ assets is a fundamental feature of the platform. ## Kinds of Reusable Assets -The DTaaS software categorizes all the reusable library assets into five categories: +The DTaaS software categorizes all the reusable library assets into six categories: ![Categories of Library Assets](library-assets.png) -### Functions - -The functions responsible for pre- and post-processing of: -data inputs, data outputs, control outputs. The data science -libraries and functions can be used to create useful function -assets for the platform. -In some cases, Digital Twin models require calibration prior -to their use; functions written by domain experts along with -right data inputs can make model calibration an achievable goal. -Another use of functions is to process the sensor and actuator -data of both Physical Twins and Digital Twins. - ### Data The data sources and sinks available to a digital twins. @@ -61,6 +49,18 @@ in a computing environment. Each of these packages are a pre-packaged combination of models and tools put together to create a ready to use Digital Twins. +### Functions + +The functions responsible for pre- and post-processing of: +data inputs, data outputs, control outputs. The data science +libraries and functions can be used to create useful function +assets for the platform. +In some cases, Digital Twin models require calibration prior +to their use; functions written by domain experts along with +right data inputs can make model calibration an achievable goal. +Another use of functions is to process the sensor and actuator +data of both Physical Twins and Digital Twins. + ### Digital Twins These are ready to use digital twins created by one or more users. diff --git a/docs/user/website/index.md b/docs/user/website/index.md index eb126b86a..9ffbf4076 100644 --- a/docs/user/website/index.md +++ b/docs/user/website/index.md @@ -25,7 +25,7 @@ service provider. The DTaaS uses Gitlab as OAuth provider. You can see the Gitlab signin button. A click on this button takes you to Gitlab instance providing authorization for DTaaS. -## Authenticate at Gitlab +## Authorize at Gitlab The username and password authorization takes place on the gitlab website. Enter your username and password in the login form. diff --git a/mkdocs-github.yml b/mkdocs-github.yml index afad65354..eb29fec1e 100644 --- a/mkdocs-github.yml +++ b/mkdocs-github.yml @@ -59,6 +59,7 @@ nav: - Desktop Robotti and RabbitMQ: user/examples/drobotti-rmqfmu/README.md - Water Plant and OPC-UA: user/examples/opc-ua-waterplant/README.md - Three Water Tanks: user/examples/three-tank/README.md + - Flex Cell: user/examples/flex-cell/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: diff --git a/mkdocs.yml b/mkdocs.yml index d45c24297..ba353bb62 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -59,6 +59,7 @@ nav: - Desktop Robotti and RabbitMQ: user/examples/drobotti-rmqfmu/README.md - Water Plant and OPC-UA: user/examples/opc-ua-waterplant/README.md - Three Water Tanks: user/examples/three-tank/README.md + - Flex Cell: user/examples/flex-cell/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: diff --git a/servers/config/gateway/README.md b/servers/config/gateway/README.md new file mode 100644 index 000000000..204e61a5a --- /dev/null +++ b/servers/config/gateway/README.md @@ -0,0 +1,64 @@ +# The gateway server + +Run the Traefik gateway server in HTTP mode to experience the DTaaS application. +HTTPS mode is disabled for now. + +## The background services + +The gateway requires background services to serve the URLs. These background +services must be running in order for the gateway to service user requests. +The default configuration uses two services at the following URLs: + +| Route / URL | Background Service | Service URL | +| :-------------- | :----------------- | :------------- | +| localhost | React Website | localhost:4000 | +| localhost/lib | Lib Microservice | localhost:4001 | +| localhost/user1 | ML Workspace | localhost:8090 | +| localhost/user2 | ML Workspace | localhost:8091 | +| | + +## Start the Gateway + +```bash +docker run -d \ + --name "traefik-gateway" \ + --network=host -v "$PWD/traefik.yml:/etc/traefik/traefik.yml" \ + -v "$PWD/auth:/etc/traefik/auth" \ + -v "$PWD/dynamic:/etc/traefik/dynamic" \ + -v /var/run/docker.sock:/var/run/docker.sock \ + --restart always \ + traefik:v2.10 +``` + +## Authorization + +The dummy username is `foo` and the password is `bar`. +Please change this before starting the gateway. + +```bash +rm auth +htpasswd -c auth +password: +``` + +The change in password becomes effective upon restart of **traefik-gateway** container. + +## Update Configuration + +The gateway serves routes specified in _dynamic/fileConfig.yml_ file. +The **traefik-gateway** gateway comes with ability to receive dynamic configuration. +You can update the configuration in this file to reflect your local setup. +See [Traefik help docs](https://doc.traefik.io/traefik/providers/file/) +for more information. + +The routes / URLs need to be updated for your local setup. +The current version of software only works for non-localhost +setting, i.e. URL other than the localhost. Here is an example, + +| Route / URL | Background Service | Service URL | +| :------------ | :----------------- | :------------- | +| foo.com | React Website | localhost:4000 | +| foo.com/lib | Lib Microservice | localhost:4001 | +| foo.com/user1 | ML Workspace | localhost:8090 | +| foo.com/user2 | ML Workspace | localhost:8091 | +| | diff --git a/servers/config/gateway/auth b/servers/config/gateway/auth new file mode 100644 index 000000000..2e468b945 --- /dev/null +++ b/servers/config/gateway/auth @@ -0,0 +1 @@ +foo:$apr1$fGdMVLcl$dMzJW.JF8Rn6Vzrf5uxaU/ diff --git a/servers/config/gateway/dynamic/fileConfig.docker.yml b/servers/config/gateway/dynamic/fileConfig.docker.yml new file mode 100644 index 000000000..359314a0b --- /dev/null +++ b/servers/config/gateway/dynamic/fileConfig.docker.yml @@ -0,0 +1,48 @@ +http: + routers: + dtaas: + entryPoints: + - http + rule: 'Host(`localhost`)' + middlewares: + - basic-auth + service: dtaas + + user1: + entryPoints: + - http + rule: 'Host(`localhost`) && PathPrefix(`/user1`)' + middlewares: + - basic-auth + service: user1 + + libms: + entryPoints: + - http + rule: 'Host(`localhost`) && PathPrefix(`/lib`)' + service: libms + + + # Middleware: Basic authentication + middlewares: + basic-auth: + basicAuth: + usersFile: "/etc/traefik/auth" + removeHeader: true + + + services: + dtaas: + loadBalancer: + servers: + - url: "http://client:4000" + + user1: + loadBalancer: + servers: + - url: "http://ml-workspace-user1:8080" + + libms: + loadBalancer: + servers: + - url: "http://libms:4001" \ No newline at end of file diff --git a/servers/config/gateway/dynamic/fileConfig.yml b/servers/config/gateway/dynamic/fileConfig.yml new file mode 100644 index 000000000..86c2d0ba7 --- /dev/null +++ b/servers/config/gateway/dynamic/fileConfig.yml @@ -0,0 +1,61 @@ +http: + routers: + dtaas: + entryPoints: + - http + rule: 'Host(`localhost`)' + middlewares: + - basic-auth + service: dtaas + + user1: + entryPoints: + - http + rule: 'Host(`localhost`) && PathPrefix(`/user1`)' + middlewares: + - basic-auth + service: user1 + + user2: + entryPoints: + - http + rule: 'Host(`localhost`) && PathPrefix(`/user2`)' + middlewares: + - basic-auth + service: user2 + + libms: + entryPoints: + - http + rule: 'Host(`localhost`) && PathPrefix(`/lib`)' + service: libms + + + # Middleware: Basic authentication + middlewares: + basic-auth: + basicAuth: + usersFile: "/etc/traefik/auth" + removeHeader: true + + + services: + dtaas: + loadBalancer: + servers: + - url: "http://localhost:4000" + + user1: + loadBalancer: + servers: + - url: "http://localhost:8090" + + user2: + loadBalancer: + servers: + - url: "http://localhost:8091" + + libms: + loadBalancer: + servers: + - url: "http://localhost:4001" \ No newline at end of file diff --git a/servers/config/gateway/traefik.yml b/servers/config/gateway/traefik.yml new file mode 100644 index 000000000..4f79c1d6f --- /dev/null +++ b/servers/config/gateway/traefik.yml @@ -0,0 +1,20 @@ +entryPoints: + http: + address: :80 + +providers: + providersThrottleDuration: 2s + + # File provider for connecting things that are outside of docker / defining middleware + file: + filename: /etc/traefik/dynamic/fileConfig.yml + watch: true + +# Enable traefik ui +#dapi: +# dashboard: true +# insecure: true + +# Log level INFO|DEBUG|ERROR +log: + level: DEBUG