diff --git a/client/DEVELOPER.md b/client/DEVELOPER.md index 7ebf2d7f9..7133eefe1 100644 --- a/client/DEVELOPER.md +++ b/client/DEVELOPER.md @@ -88,6 +88,16 @@ It is therefore reccommend to keep the configurations in the `client/config/` directory and use one of the `yarn config` sub-commands to switch between them. +The purpose of different configuration files are given in the table below. + +| Configuration File Name | Usage Scenario | +|:--------|:--------| +| `dev.js` | Check functionality of the client application without using any other parts of the DTaaS software | +| `gitlab.js` | Used for testing the gitlab code written in `src/utils/gitlab.ts`. These credentials are not used by the client application | +| `local.js` | Used by the `docker/compose.dev.yml` to setup a check the complete DTaaS application on the developer computer | +| `prod.js` | Used for running the client application on a production server. This file is kept here for reference. The `deploy/config/client/env.js` is used during installations. | +| `test.js` | Used by all the tests | + ## Example configuration for developers The first step is to collect the URL of gitlab acting as oauth provider. diff --git a/client/config/dev.js b/client/config/dev.js index e8b36f844..3dfe3b0a3 100644 --- a/client/config/dev.js +++ b/client/config/dev.js @@ -1,7 +1,7 @@ if (typeof window !== 'undefined') { window.env = { REACT_APP_ENVIRONMENT: 'dev', - REACT_APP_URL: 'http://localhost/', + REACT_APP_URL: 'http://localhost:4000/', REACT_APP_URL_BASENAME: '', REACT_APP_URL_DTLINK: '/lab', REACT_APP_URL_LIBLINK: '', @@ -12,8 +12,8 @@ if (typeof window !== 'undefined') { REACT_APP_CLIENT_ID: '1be55736756190b3ace4c2c4fb19bde386d1dcc748d20b47ea8cfb5935b8446c', REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/', - REACT_APP_REDIRECT_URI: 'http://localhost/Library', - REACT_APP_LOGOUT_REDIRECT_URI: 'http://localhost/', + REACT_APP_REDIRECT_URI: 'http://localhost:4000/Library', + REACT_APP_LOGOUT_REDIRECT_URI: 'http://localhost:4000', REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', }; }; diff --git a/client/package.json b/client/package.json index 8231082a5..bd2088bf5 100644 --- a/client/package.json +++ b/client/package.json @@ -16,7 +16,7 @@ "type": "module", "scripts": { "build": "npx shx cp config/gitlab.json src/util/gitlab.json && npx react-scripts build && npx rimraf src/util/gitlab.json", - "clean": "npx rimraf build/ dist/ node_modules/ coverage/ playwright-report/ *.svg src/util/gitlab.json", + "clean": "npx rimraf build/ dist/ node_modules/ coverage/ playwright-report/ test-results/ *.svg src/util/gitlab.json", "config:dev": "npx shx cp config/dev.js public/env.js && npx shx cp config/dev.js build/env.js", "config:local": "npx shx cp config/local.js public/env.js && npx shx cp config/local.js build/env.js", "config:prod": "npx shx cp config/prod.js public/env.js && npx shx cp config/prod.js build/env.js", diff --git a/client/test/README.md b/client/test/README.md index c87a8ad14..ec1f512bb 100644 --- a/client/test/README.md +++ b/client/test/README.md @@ -1,42 +1,25 @@ # End-to-End (E2E) Tests -The E2E tests require playwright test runner, an on-premise GitLab OAuth setup and -configured `config/test.js` and `test/.env` files. When everything is set up, you -can run the tests by running `yarn test:e2e`. +The E2E tests require playwright test runner and an on-premise GitLab OAuth setup. +The has CAPTCHA protection blocking the end-to-end tests. +Thus on-premise or third-party Gitlab instance hosted without CAPTCHA protection +is needed. -It is also possible to test the hosted DTaaS applications hosted at a URL, -say `https://foo.com` using `yarn test:e2e:ext`. Remember to set the environment -variable in `test/.env` to the URL of the hosted DTaaS application. An example -is shown below: +Make sure you have an active internet connection while running these tests, +as the tests simulate real user interactions with your GitLab account. -```js -if (typeof window !== 'undefined') { - window.env = { - REACT_APP_ENVIRONMENT: 'test', - REACT_APP_URL: 'https://foo.com/', - REACT_APP_URL_BASENAME: '', - REACT_APP_URL_DTLINK: '/lab', - REACT_APP_URL_LIBLINK: '', - REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword', - REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/', - REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab', - REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '', - - REACT_APP_CLIENT_ID: '1be55736756190b3ace4c2c4fb19bde386d1dcc748d20b47ea8cfb5935b8446c', - REACT_APP_AUTH_AUTHORITY: 'https://gitlab.com/', - REACT_APP_REDIRECT_URI: 'https://foo.com/Library', - REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/', - REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', - }; -}; -``` +There are two possible testing setups you can create. + +1. Host website on the developer computer and test from developer computer. + This is the default E2E testing scenario. + The DTaaS client application will be running at `http://localhost:4000`. +1. Host website on the integration server and test from the integration server. + The DTaaS client application will be running at `https://foo.com`. -The `yarn install` and `yarn config:test` need to be run before `yarn test:e2e:ext` -can be run successfully. Also note that if you are deploying the client -application with Traeffik forward authorization, the tests will fail due to -the additionally required Gitlab authorization. +The following sections describe configuration and yarn test commands for +both these scenarios. -## Playwright +## Install Playwright The E2E tests use playwright test runner. You also need to have the software installed. If it is not installed, you can install it with the following command. @@ -45,21 +28,31 @@ installed. If it is not installed, you can install it with the following command yarn playwright install --with-deps ``` -## OAuth Setup +## Setup Test Configuration -You can follow the instructions in [authorization page -](../../docs/admin/client/auth.md)to setup OAuth for the react client website. -Remember to add the `http://localhost:4000` as callback URL in the OAuth -application. The GitLab will still be running on a remote machine. +### OAuth Setup + +You can follow the instructions in +[authorization page](../../docs/admin/client/auth.md) to setup OAuth for +the react client website. +Remember to add the correct callback URL in the OAuth +application. Depending the location of the client website, +one of the following URLs must be registered as callback URL. + +| Location of client application | URL | +|:---|:---| +| Localhost | `http://localhost:4000` | +| External / Integration server | `https://foo.com` | + +The GitLab will still be running on a remote machine. It is not possible to run both the GitLab and react client website on localhost. -## config/test.js file +### Client Configuration -Before running the E2E tests, you need to update the `config/test.js` file. -If you have a live DTaaS client website running, you can copy the `build/env.js` -into `config/test.js`. +Before running the E2E tests, you need to update +the client configuration file available at `config/test.js`. -Open `config/test.js` in a text editor and make sure the configuration matches +Make sure the configuration in `config/test.js` matches the details of your testing environment. For instance, you need to adjust: * `REACT_APP_URL` @@ -69,66 +62,10 @@ the details of your testing environment. For instance, you need to adjust: to reflect your test setup. More information on about the environment settings is available in [authorization](../../docs/admin/client/auth.md) and -[client deployment](../../docs/admin/client/CLIENT.md) pages. +[client configuration](../../docs/admin/client/config.md) pages. Here's an example of relevant values for variables. This example is suitable for -testing on developer computer. - -```js -REACT_APP_URL="http://localhost:4000" -REACT_APP_AUTH_AUTHORITY="http://gitlab.foo.com" -REACT_APP_REDIRECT_URI="http://localhost:4000/Library" -REACT_APP_LOGOUT_REDIRECT_URI="http://localhost:4000" -``` - -Finally, run `yarn config:test` to copy the config file into the `build` -and `public` folders. - -## env file - -You need to create a `test/.env` file where you will store the GitLab user -credentials and application URL for the website. The credentials will be -used by playwright to simulate real user interactions during the E2E tests. - -A template for `test/.env` is given here: - -```env -REACT_APP_TEST_USERNAME=your_username -REACT_APP_TEST_PASSWORD=your_password -REACT_APP_URL='https://foo.com' -``` - -Replace _your_username_ and _your_password_ with the actual username and password -of your GitLab account or the testing account that you intend to use. Finally -replace _foo.com_ with the URL of your application, as you did in `env.js`. - -Here's an example for test setup on the developer machine and on the -integration server: - -```env -REACT_APP_TEST_USERNAME=TestUsername -REACT_APP_TEST_PASSWORD=TestPassword123 -REACT_APP_URL='http://localhost:4000' -``` - -## Testing on localhost - -If you want to handle starting the react client server yourself, there are two -possible testing setups you can create. - -1. Host website on the developer computer and test from developer computer -1. Host website on the integration server and test from the integration server - -If you use `localhost` in the `REACT_APP_URL` the above the two mentioned setups -are essentially the same. -In order to run the tests on the integration server, you need to disable the -HTTP authorization (if setup in the first place) on the Traefik server and -let the website be accessible without any authenticaiton. - -### The configuration files for the test on localhost - -The `config/test.js` file is given below. The `build/env.js` also holds the -same content. +testing on developer computer, i.e., `localhost`. ```js window.env = { @@ -150,26 +87,8 @@ window.env = { }; ``` -## test/.env - localhost - -```ini -REACT_APP_TEST_USERNAME=TestUsername -REACT_APP_TEST_PASSWORD=TestPassword123 -REACT_APP_URL='http://localhost:4000' -``` - -Please note that the username and password are the user -credentials on `gitlab.foo.com`. - -## Testing on the integration server - -In this test setup, the DTaaS application is running at `https://foo.com` and -the GitLab instance is running at `https://gitlab.foo.com`. The E2E test shall -be run from the developer computer. The codebase commit should be the same on -both the developer computer and integration server. - -The `config/test.js` file on the developer computer is given below. The -`build/env.js` of the integration server also holds the same content. +The matching values for the running the DTaaS client applicat on an integration +server hosted at `https://foo.com` are: ```js window.env = { @@ -191,38 +110,76 @@ window.env = { }; ``` -## test/.env - Integration server +### Test User Credentials + +You need to create a test environment file named `test/.env` +in which you will store the GitLab user credentials and +the DTaaS application URL for the website. The credentials will be +used by playwright to simulate real user interactions during the E2E tests. + +A template for `test/.env` for running the DTaaS client application +on the developer computer, i.e., `localhost` is given here: + +```env +REACT_APP_TEST_USERNAME=your_username +REACT_APP_TEST_PASSWORD=your_password +REACT_APP_URL='http://localhost:4000' +``` + +Replace _your_username_ and _your_password_ with the actual username and password +of your on-premise GitLab account (`gitlab.foo.com`) or the testing account that +you intend to use. + +Here's an example `test/.env` for test setup on the developer machine and +and the DTaaS client application running on a remote integration server: -```ini +```env REACT_APP_TEST_USERNAME=TestUsername REACT_APP_TEST_PASSWORD=TestPassword123 REACT_APP_URL='https://foo.com' ``` -Please note that the username and password are the user credentials on `gitlab.foo.com`. +Here `https://foo.com` is the URL of the application. +Remember to replace _foo.com_ with the URL of your application. -**NOTE:** The tests from developer computer to the integration server only -work with null basename. The test fails if a basename (say `au`) is specified. -This might be due to a complex interaction of developer computer, traefik -gateway and the client website hosted behind traefik. +## Run Tests -## Running the Tests +### Localhost -Once you've properly set up your .env file, you can run the end-to-end tests as follows: +You can run the end-to-end tests as follows: ```bash +yarn install +yarn build +yarn config:test yarn test:e2e ``` -Or with manual website launch: +The `yarn test:e2e` command launches the test runner, the DTaaS client application +and execute all end-to-end tests. +The client application is terminated at the end of end-to-end tests. + +## Testing on the integration server + +In this test setup, the DTaaS application is running at `https://foo.com` and +the GitLab instance is running at `https://gitlab.foo.com`. The E2E test shall +be run from the developer computer. The codebase commit should be the same on +both the developer computer and integration server. + +Points to note: + +1. In order to run the tests on the integration server, you need to disable the + HTTPS authorization (if setup in the first place) on the Traefik server and + let the website be accessible without any authenticaiton done by + [Traefik forward auth](../../docs/admin/servers/auth.md) service. +1. The tests from developer computer to the integration server only + work with null basename. The tests fail if a basename (say `au`) is specified. + This might be due to a complex interaction of developer computer, traefik + gateway and the client website hosted behind traefik. + +You can run the end-to-end tests as follows: ```bash +yarn install yarn test:e2e:ext ``` - -These commands launch the test runner and execute all end-to-end tests. The first -command also runs the `yarn start` command to start the client website -and terminates it after testing. - -Make sure you have an active internet connection while running these tests, -as they simulate real user interactions with your GitLab account. diff --git a/deploy/docker/SERVER.md b/deploy/docker/SERVER.md index df70a649a..12bee0a1f 100644 --- a/deploy/docker/SERVER.md +++ b/deploy/docker/SERVER.md @@ -269,7 +269,7 @@ docker compose -f compose.server.secure.yml --env-file .env.server up -d --force ## Use The application will be accessible at: - from web browser. +`http(s)://foo.com` from web browser. Sign in using your account linked to either _gitlab.com_ or your local gitlab instance. diff --git a/deploy/services/README.md b/deploy/services/README.md index 26981eba4..358d0f997 100644 --- a/deploy/services/README.md +++ b/deploy/services/README.md @@ -9,6 +9,7 @@ The installation scripts in this directory install: * **Grafana** visualization and dashboard service * **RabbitMQ** AMQP broker and its' management interface * Eclipse Mosquitto **MQTT** broker +* **MongoDB** database server ## Configure and Install @@ -35,7 +36,7 @@ at the following ports / URLs. | RabbitMQ Broker | services.foo.com:5672 | | RabbitMQ Broker Management Website | services.foo.com:15672 | | MQTT Broker | services.foo.com:1883 | -|| +| MongoDB database | services.foo.com:27017 | The firewall and network access settings of corporate / cloud network need to be configured to allow external access to the services. Otherwise the users of DTaaS diff --git a/docker/README.md b/docker/README.md index 2dca93849..5201125f7 100644 --- a/docker/README.md +++ b/docker/README.md @@ -66,7 +66,7 @@ The configuration files to be updated are: 1. docker/conf.dev please see [server docs](../docs/admin/servers/auth.md) for help with updating this config file) -1. client/config/dev.js +1. client/config/local.js please see [client config](../docs/admin/client/config.md) for help with updating this config file) diff --git a/docs/admin/client/config.md b/docs/admin/client/config.md index 2712256bb..54f973478 100644 --- a/docs/admin/client/config.md +++ b/docs/admin/client/config.md @@ -49,7 +49,7 @@ This page describes various configuration options for react website. if (typeof window !== 'undefined') { window.env = { REACT_APP_ENVIRONMENT: "dev", - REACT_APP_URL: 'https://foo.com/', + REACT_APP_URL: 'http://localhost:4000/', REACT_APP_URL_BASENAME: 'bar', REACT_APP_URL_DTLINK: '/lab', REACT_APP_URL_LIBLINK: '', @@ -59,8 +59,8 @@ This page describes various configuration options for react website. REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '', REACT_APP_CLIENT_ID: '1be55736756190b3ace4c2c4fb19bde386d1dcc748d20b47ea8cfb5935b8446c', REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/', - REACT_APP_REDIRECT_URI: 'https://foo.com/bar/Library', - REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/bar', + REACT_APP_REDIRECT_URI: 'http://localhost:4000/bar/Library', + REACT_APP_LOGOUT_REDIRECT_URI: 'http://localhost:4000/bar', REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', }; }; diff --git a/docs/developer/index.md b/docs/developer/index.md index 65a31f808..3341797e8 100644 --- a/docs/developer/index.md +++ b/docs/developer/index.md @@ -1,4 +1,4 @@ -# Developers Guide +# Developer Guide This guide is for DTaaS platform developers. It helps development team members get familiar with diff --git a/docs/user/examples/incubator-NuRV-fmu-monitor-service/README.md b/docs/user/examples/incubator-NuRV-fmu-monitor-service/README.md new file mode 100644 index 000000000..9cfde8f27 --- /dev/null +++ b/docs/user/examples/incubator-NuRV-fmu-monitor-service/README.md @@ -0,0 +1,166 @@ +# Incubator Digital Twin with NuRV FMU Monitoring Service + +## Overview + +This example demonstrates how an FMU can be used as a runtime monitoring +service (in this example NuRV[1]) and connected with the +[Incubator digital twin](../incubator/README.md) to verify +runtime behavior of the Incubator. + +## Simulated scenario + +This example simulates a scenario where the lid of the Incubator is +removed and later put back on. The Incubator is equipped with +anomaly detection capabilities, which can detect anomalous behavior +(i.e. the removal of the lid). When an anomaly is detected, +the Incubator triggers an energy saving mode where the heater is turned off. + +From a monitoring perspective, we wish to verify that within 3 messages of +an anomaly detection, the energy saving mode is turned on. +To verify this behavior, we construct the property: + +$G(anomaly \rightarrow (F_{[0,3]}\space energy\_saving))$. + +The monitor will output the _unknown_ state as long as the property is +satisfied and will transition to the _false_ state once +a violation is detected. + +The simulated scenario progresses as follows: + +- _Initialization_: The services are initialized and the Kalman filter + in the Incubator is given 2 minutes to stabilize. Sometimes, + the anomaly detection algorithm will detect an anomaly at startup + even though the lid is still on. It will disappear after approx 15 seconds. +- _After 2 minutes_: The lid is lifted and an anomaly is detected. + The energy saver is turned on shortly after. +- _After another 30 seconds_: The energy saver is manually disabled + producing a _false_ verdict. +- _After another 30 seconds_: The lid is put back on and + the anomaly detection is given time to detect that the lid is back on. + The monitor is then reset producing an Unknown verdict again. + The simulation then ends. + +## Example structure + +A diagram depicting the logical software structure of +the example can be seen below. + +![DT structure](./figures/dt-structure-nurv-fmu.png) + +The _execute_ script is responsible for starting the NuRV service and +running the Python script that controls the scenario (_execute.py_). + +The _execute.py_ script starts the Incubator services and runs +the example scenario. Once the Incubator DT is started, a RabbitMQ client +is created that subscribes to changes in the _anomaly_ and +_energy_saving_ states of the DT, as well as the verdicts produced +by the NuRV service. +Each time an update is received, the full state and verdict is +printed to the console. + +## Digital Twin configuration + +Before running the example, please configure the _simulation.conf_ file with +your RabbitMQ credentials. + +The example uses the following assets: + +| Asset Type | Names of Assets | Visibility | Reuse in other Examples | +| :------------ | :----------------------------- | :--------- | :---------------------- | +| Tools | common/tool/NuRV/NuRV | Common | Yes | +| Other | common/fmi2_headers | Common | Yes | +| DT | common/digital_twins/incubator | Common | Yes | +| Specification | safe-operation.smv | Private | No | +| Script | execute.py | Private | No | + +The _safe-operation.smv_ file contains the default monitored specification +as described in the [Simulated scenario section](#simulated-scenario). +These can be configured as desired. + +## Lifecycle phases + +The lifecycle phases for this example include: + +| Lifecycle phase | Completed tasks | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| create | Downloads the necessary tools and creates a virtual python environment with the necessary dependencies | +| execute | Runs a python script that starts up the necessary services as well as the Incubator simulation. Various status messages are printed to the console, including the monitored system states and monitor verdict. | + +If required, change the execute permissions of lifecycle scripts you +need to execute. This can be done using the following command. + +```bash +chmod +x lifecycle/{script} +``` + +where {script} is the name of the script, e.g. _create_, _execute_ etc. + +## Running the example + +To run the example, first run the following command in a terminal: + +```bash +cd /workspace/examples/digital_twins/incubator-NuRV-fmu-monitor-service/ +``` + +Then, first execute the _create_ script followed by the _execute_ script +using the following command: + +```bash +lifecycle/{script} +``` + +The _execute_ script will then start outputting system states and +the monitor verdict approx every 3 seconds. The output is printed +as follows. + +"__State: {anomaly state} & {energy_saving state}__" + +where "_anomaly_" indicates that an anomaly is detected and "!anomaly" +indicates that an anomaly is not currently detected. The same format is +used for the energy_saving state. +NuRV verdicts are printed as follows + +"__Verdict from NuRV: {verdict}__". + +The monitor verdict can be false or unknown, where the latter indicates +that the monitor does not yet have sufficient information to determine +the satisfaction of the property. The monitor will never produce +a true verdict as the entire trace must be verified to ensure satisfaction +due to the G operator. Thus the unknown state can be viewed as +a tentative true verdict. + +An example output trace is provided below: + +````log +.... +Using LIFECYCLE_PATH: /workspace/examples/digital_twins/incubator-NuRV-fmu-monitor-service/lifecycle +Using INCUBATOR_PATH: /workspace/examples/digital_twins/incubator-NuRV-fmu-monitor-service/lifecycle/../../../common/digital_twins/incubator +Starting NuRV FMU Monitor Service, see output at /tmp/nurv-fmu-service.log +NuRVService.py PID: 13496 +Starting incubator +Connected to rabbitmq server. +Running scenario with initial state: lid closed and energy saver on +Setting energy saver mode: enable +Setting G_box to: 0.5763498 +State: !anomaly & !energy_saving +State: !anomaly & !energy_saving +Verdict from NuRV: unknown +State: !anomaly & !energy_saving +State: !anomaly & !energy_saving +Verdict from NuRV: unknown +State: !anomaly & !energy_saving +State: !anomaly & !energy_saving +Verdict from NuRV: unknown +State: !anomaly & !energy_saving +State: !anomaly & !energy_saving +Verdict from NuRV: unknown +State: !anomaly & !energy_saving +State: !anomaly & !energy_saving +Verdict from NuRV: unknown +```` + +## References + +1. Information on the NuRV monitor can be found on + [FBK website](https://es-static.fbk.eu/tools/nurv/). diff --git a/docs/user/examples/incubator-NuRV-fmu-monitor-service/figures/dt-structure-nurv-fmu.png b/docs/user/examples/incubator-NuRV-fmu-monitor-service/figures/dt-structure-nurv-fmu.png new file mode 100644 index 000000000..9c2f3b695 Binary files /dev/null and b/docs/user/examples/incubator-NuRV-fmu-monitor-service/figures/dt-structure-nurv-fmu.png differ diff --git a/docs/user/examples/incubator-NuRV-monitor-validation/README.md b/docs/user/examples/incubator-NuRV-monitor-validation/README.md index bdc74bc9d..1c45d8988 100644 --- a/docs/user/examples/incubator-NuRV-monitor-validation/README.md +++ b/docs/user/examples/incubator-NuRV-monitor-validation/README.md @@ -1,4 +1,4 @@ -# Incubator Digital Twin validation with NuRV Monitor +# Incubator Co-Simulation Digital Twin validation with NuRV Monitor ## Overview @@ -10,6 +10,9 @@ FMU monitors (in this example, the monitors are generated with NuRV[1]). This example validates some components of the [Incubator digital twin](../incubator/README.md), by performing a simulation in which the commponents are wrapped inside FMUs, and are then inspected at runtime by some a FMU monitor generated by NuRV. +Please note that the link to [Incubator digital twin](../incubator/README.md) +is only provided to know the details of the incubator physical twin. +The digital twin (DT) presented here is a co-simulation DT of the Incubator. The input data for the simulation is generated by a purpose-built FMU component named _source_, which supplies testing data to the _anomaly detector_, diff --git a/docs/user/examples/incubator/README.md b/docs/user/examples/incubator/README.md index 230472235..39d06f46f 100644 --- a/docs/user/examples/incubator/README.md +++ b/docs/user/examples/incubator/README.md @@ -59,11 +59,60 @@ This example uses a plethora of Python scripts to run the digital twin. By default it is configured to run with a mock physical twin. Furthermore, it depends on a RabbitMQ and an InfluxDB instances. -There are two configuration files. One is is DT has a single configuration files. -First is `incubator/log.log`; it controls the verbosity of terminal log level -during DT execution. -Second is `simulation.conf` which provides the control and -connection parameters to the DT. +There is one configuration file: `simulation.conf`. +The RabbitMQ and InfluxDB configuration parameters need to be updated. + +## Lifecycle Phases + +The lifecycles that are covered include: + +| Lifecycle Phase | Completed Tasks | +| --------- | ------- | +| Create | Potentially updates the system and installs Python dependencies | +| Execute | Executes the Incubator digital twin and produces output in the terminal and in _incubator/log.log_. | +| Clean | Removes the log file. | + +## Run the example + +To run the example, change your present directory. + +```bash +cd /workspace/examples/digital_twins/incubator +``` + +If required, change the execute permission of lifecycle scripts +you need to execute, for example: + +```bash +chmod +x lifecycle/create +``` + +Now, run the following scripts: + +### Create + +Potentially updates the system and installs Python dependencies. + +```bash +lifecycle/create +``` + +### Execute + +Executes the Incubator digital twin with a mock physical twin. +Pushes the results in the terminal, _incubator/log.log_, and in InfluxDB. + +```bash +lifecycle/execute +``` + +### Clean + +Removes the output log file. + +```bash +lifecycle/clean +``` ## Examining the results diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md index 644c19b09..34575169c 100644 --- a/docs/user/examples/index.md +++ b/docs/user/examples/index.md @@ -1,14 +1,24 @@ # DTaaS Examples There are some example digital twins created for the DTaaS software. -Use these examples and follow the steps given in the **Examples** section +You can peruse these examples and follow the steps given in +this **Examples** section to experience features of the DTaaS software platform and understand best practices for managing digital twins within the platform. - -You can also see a -[short video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/cpsens.mp4) -on the use of DTaaS for creating a digital shadow. This video is recorded using -DTaaS v0.2.0. +Please see these +[slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/20240917-Examples.pdf) +and +[video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/20240917-Examples-Recorded-web.mp4) +to get an overview of these examples. + +There are two demo vides available: +CP-SENS project +([slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/20240917-CPSENS-demo.pdf) +and +[video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/20240917-CPSENS-demo-Recorded-web.mp4)) +and Incubator +([video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/Incubator-demo-web.mp4)). +These two videos have been recorded using DTaaS v0.5.0. ## Copy Examples @@ -36,9 +46,10 @@ to use the examples in the following order. 1. [Flex Cell with Two Industrial Robots](./flex-cell/README.md) 1. [Incubator](./incubator/README.md) 1. [Firefighters in Emergency Environments](./o5g/README.md) -1. [Mass Spring Damper with NuRV Runtime Monitor](./mass-spring-damper-monitor/README.md) -1. [Incubator with NuRV Runtime Monitor](./incubator-NuRV-monitor-validation/README.md) -1. [Incubator with NuRV Runtime Monitor Service](./incubator-NuRV-monitor-service/README.md) -1. [Water Tank Fault Injection with NuRV Runtime Monitor](./water_tank_FI_monitor/README.md) +1. [Mass Spring Damper with NuRV Runtime Monitor FMU](./mass-spring-damper-monitor/README.md) +1. [Water Tank Fault Injection with NuRV Runtime Monitor FMU](./water_tank_FI_monitor/README.md) +1. [Incubator Co-Simulation with NuRV Runtime Monitor FMU](./incubator-NuRV-monitor-validation/README.md) +1. [Incubator with NuRV Runtime Monitor as Service](./incubator-NuRV-monitor-service/README.md) +1. [Incubator with NuRV Runtime Monitor FMU as Service](./incubator-NuRV-fmu-monitor-service/README.md) :material-download: [DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples) diff --git a/docs/user/motivation.md b/docs/user/motivation.md index 95f309f12..996409653 100644 --- a/docs/user/motivation.md +++ b/docs/user/motivation.md @@ -1,4 +1,19 @@ -# Motivation +# DTaaS for Users + +## User Guide + +This guide is for users of the DTaaS platform. +Please make sure that you have access to a live installation of +the DTaaS platform. The easiest is +[localhost](../admin/localhost.md) installation scenario. + +Please see user-specific +[Slides](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/20240917-Users.pdf) +and +[Video](https://odin.cps.digit.au.dk/into-cps/dtaas/assets/videos/20240917-Users-Recorded-web.mp4) +to get the conceptual framework behind composable digital twins in the DTaaS platform. + +## Motivation How can DT software platforms enable users collaborate to: diff --git a/mkdocs-github.yml b/mkdocs-github.yml index d7b949cae..8fd7aa931 100644 --- a/mkdocs-github.yml +++ b/mkdocs-github.yml @@ -39,9 +39,10 @@ nav: - Incubator: user/examples/incubator/README.md - Firefighters: user/examples/o5g/README.md - Mass Spring Damper with NuRV: user/examples/mass-spring-damper-monitor/README.md - - Incubator with NuRV: user/examples/incubator-NuRV-monitor-validation/README.md - - Incubator with NuRV Service: user/examples/incubator-NuRV-monitor-service/README.md - Water Tank Fault Injection with NuRV: user/examples/water_tank_FI_monitor/README.md + - Incubator Co-Sim with NuRV: user/examples/incubator-NuRV-monitor-validation/README.md + - Incubator with NuRV Service: user/examples/incubator-NuRV-monitor-service/README.md + - Incubator with NuRV FMU Service: user/examples/incubator-NuRV-fmu-monitor-service/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - Admin: - Install: diff --git a/mkdocs.yml b/mkdocs.yml index 00af96ebb..785bccd67 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,9 +39,10 @@ nav: - Incubator: user/examples/incubator/README.md - Firefighters: user/examples/o5g/README.md - Mass Spring Damper with NuRV: user/examples/mass-spring-damper-monitor/README.md - - Incubator with NuRV: user/examples/incubator-NuRV-monitor-validation/README.md - - Incubator with NuRV Service: user/examples/incubator-NuRV-monitor-service/README.md - Water Tank Fault Injection with NuRV: user/examples/water_tank_FI_monitor/README.md + - Incubator Co-Sim with NuRV: user/examples/incubator-NuRV-monitor-validation/README.md + - Incubator with NuRV Service: user/examples/incubator-NuRV-monitor-service/README.md + - Incubator with NuRV FMU Service: user/examples/incubator-NuRV-fmu-monitor-service/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - Admin: - Install: diff --git a/servers/lib/DEVELOPER.md b/servers/lib/DEVELOPER.md index 497eeee53..6baa47c21 100644 --- a/servers/lib/DEVELOPER.md +++ b/servers/lib/DEVELOPER.md @@ -57,7 +57,7 @@ need to be done with the following `LOCAL_PATH` values. | OS | Absolute Path | Relative Path | | ------- | ----------------------------- | ------------- | | Windows | C:\DTaaS\files | ..\..\files | -| Linux | /Users//DTaaS/files | ../../files | +| Linux | /Users/\/DTaaS/files | ../../files | ### PM2