diff --git a/docs/docs/examples/ball-example.md b/docs/docs/examples/ball-example.md index 2164366..ee46eaa 100644 --- a/docs/docs/examples/ball-example.md +++ b/docs/docs/examples/ball-example.md @@ -1,2 +1,2 @@ -# Bouncing ball example \ No newline at end of file +# Bouncing ball \ No newline at end of file diff --git a/docs/docs/examples/raspberry-example/_category_.json b/docs/docs/examples/raspberry-example/_category_.json index e4f243b..becd17e 100644 --- a/docs/docs/examples/raspberry-example/_category_.json +++ b/docs/docs/examples/raspberry-example/_category_.json @@ -1,5 +1,5 @@ { - "label": "Raspberry Pi example", + "label": "Raspberry Pi", "position": 2, "link": { "type": "generated-index", diff --git a/docs/docs/examples/raspberry-example/raspberry-example.mdx b/docs/docs/examples/raspberry-example/raspberry-example.mdx index 8fd8863..e0674cf 100644 --- a/docs/docs/examples/raspberry-example/raspberry-example.mdx +++ b/docs/docs/examples/raspberry-example/raspberry-example.mdx @@ -5,7 +5,7 @@ sidebar_position: 1 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Raspberry example +# Raspberry ## Requirements The only requisites are: diff --git a/docs/docs/examples/string-example.md b/docs/docs/examples/string-example.md index 6a65d8c..b097f15 100644 --- a/docs/docs/examples/string-example.md +++ b/docs/docs/examples/string-example.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# String and number example +# String and number This is a very simple example of creating a ONE way digital twin for monitoring a device. In this case, the stored information will be a string and a number, both of them have a timestamp asociated. To create a digital twin, we must first know the schema used by [Eclipse Ditto](https://eclipse.dev/ditto/index.html) called [Ditto Protocol](https://eclipse.dev/ditto/protocol-overview.html). diff --git a/docs/docs/guides/dt-creation.mdx b/docs/docs/guides/dt-schema-creation.mdx similarity index 92% rename from docs/docs/guides/dt-creation.mdx rename to docs/docs/guides/dt-schema-creation.mdx index 7aab3ef..79ef6f1 100644 --- a/docs/docs/guides/dt-creation.mdx +++ b/docs/docs/guides/dt-schema-creation.mdx @@ -1,35 +1,35 @@ ---- -sidebar_position: 2 ---- - -# Creation of the schema of the digital twin - -The way to interact with [Eclipse Ditto](https://eclipse.dev/ditto/index.html) and therefore create not only digital twins, but connections, etc. is through http requests and methods. -Although the graphical interface of OpenTwins makes it unnecessary to go so low level, the option to communicate directly with Eclipse Ditto is still available. - - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -```mdx-code-block - - -``` - -To create a new digital twin schema using OpenTwins plugin in Grafana just select "Create new twin" button in Twins tab. -![CreateTwin](./img/createTwinButton.png) - - - - -```mdx-code-block - - -This is an orange - -``` +--- +sidebar_position: 2 +--- + +# Create a digital twin + +The way to interact with [Eclipse Ditto](https://eclipse.dev/ditto/index.html) and therefore create not only digital twins, but connections, etc. is through http requests and methods. +Although the graphical interface of OpenTwins makes it unnecessary to go so low level, the option to communicate directly with Eclipse Ditto is still available. + + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +```mdx-code-block + + +``` + +To create a new digital twin schema using OpenTwins plugin in Grafana just select "Create new twin" button in Twins tab. +![CreateTwin](./img/createTwinButton.png) + + + + +```mdx-code-block + + +This is an orange + +``` diff --git a/docs/docs/guides/type-creation.mdx b/docs/docs/guides/type-creation.mdx index 5760e2f..6f26071 100644 --- a/docs/docs/guides/type-creation.mdx +++ b/docs/docs/guides/type-creation.mdx @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# Creation of the schema of the digital twin type +# Create a type The way to interact with [Eclipse Ditto](https://eclipse.dev/ditto/index.html) and therefore create not only digital twins, but connections, etc. is through http requests and methods. Although the graphical interface of OpenTwins makes it unnecessary to go so low level, the option to communicate directly with Eclipse Ditto is still available. diff --git a/docs/docs/img/children-car.png b/docs/docs/img/children-car.png new file mode 100644 index 0000000..8916246 Binary files /dev/null and b/docs/docs/img/children-car.png differ diff --git a/docs/docs/img/create-digital-twins.png b/docs/docs/img/create-digital-twins.png new file mode 100644 index 0000000..a8e6ad4 Binary files /dev/null and b/docs/docs/img/create-digital-twins.png differ diff --git a/docs/docs/img/create-twin-car.png b/docs/docs/img/create-twin-car.png new file mode 100644 index 0000000..f73b707 Binary files /dev/null and b/docs/docs/img/create-twin-car.png differ diff --git a/docs/docs/img/create-type-1.png b/docs/docs/img/create-type-1.png new file mode 100644 index 0000000..56906f6 Binary files /dev/null and b/docs/docs/img/create-type-1.png differ diff --git a/docs/docs/img/create-type-2.png b/docs/docs/img/create-type-2.png new file mode 100644 index 0000000..fd7d6ac Binary files /dev/null and b/docs/docs/img/create-type-2.png differ diff --git a/docs/docs/img/create-type-car-1.png b/docs/docs/img/create-type-car-1.png new file mode 100644 index 0000000..6981321 Binary files /dev/null and b/docs/docs/img/create-type-car-1.png differ diff --git a/docs/docs/img/create-type-car-2.png b/docs/docs/img/create-type-car-2.png new file mode 100644 index 0000000..ae487a4 Binary files /dev/null and b/docs/docs/img/create-type-car-2.png differ diff --git a/docs/docs/img/create-type-wheel-1.png b/docs/docs/img/create-type-wheel-1.png new file mode 100644 index 0000000..24bba53 Binary files /dev/null and b/docs/docs/img/create-type-wheel-1.png differ diff --git a/docs/docs/img/create-type-wheel-2.png b/docs/docs/img/create-type-wheel-2.png new file mode 100644 index 0000000..d381832 Binary files /dev/null and b/docs/docs/img/create-type-wheel-2.png differ diff --git a/docs/docs/img/model-car-example.jpg b/docs/docs/img/model-car-example.jpg new file mode 100644 index 0000000..d1c29fc Binary files /dev/null and b/docs/docs/img/model-car-example.jpg differ diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md deleted file mode 100644 index 5cf0fb5..0000000 --- a/docs/docs/quickstart.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Quickstart - -Welcome to OpenTwins, a flexible platform adapted to your needs! Although OpenTwins offers extensive customization options, we understand the importance of simplicity for beginners. Therefore, let's embark on a short journey together, showing you the quickest route to deploy the platform and develop a simple, functional digital twin. - -## Prerequisites -Please be sure you have the following utilities installed on your host machine: - -- [Docker](https://www.docker.com/) -- [Kubernetes](https://kubernetes.io/releases/download/) -- [Helm](https://helm.sh/docs/intro/install/) v3 - -If you don't have a Kubernetes cluster, you can set one up on local using [minikube](https://minikube.sigs.k8s.io/docs/). For a smooth deployment experience, we suggest you use the following minimum configuration values. - -```bash -minikube start --cpus 4 --disk-size 40gb --memory 8192 -``` -```bash -kubectl config use-context minikube -``` - -## Installation -The quickest way to deploy OpenTwins is [using Helm](https://helm.sh/docs/intro/using_helm/). - -The following command adds the ERTIS repository where the OpenTwins helm chart is located. - -```bash -helm repo add ertis https://ertis-research.github.io/Helm-charts/ -``` - -To deploy the platform with recommended functionality, use the command below: - -```bash -helm upgrade --install opentwins ertis/OpenTwins -n opentwins --wait --dependency-update -``` - -To modify the components to be deployed and connected during the installation, you can check the [installation via Helm](./installation/using-helm.md). - - -## Define your first digital twin - -A digital twin is composed of static and dynamic data. - -**Static data.** Information relevant to the digital twin that is expected to remain constant, such as the model, the date of acquisition or the location of the machine we are replicating. - -**Dynamic data.** Data that changes over time and that we will record in time series, such as the position of a mobile robot or the values measured by a sensor. - -For example, consider a DHT22 temperature and humidity sensor. Its digital twin, represented in JSON format following the schema provided by Eclipse Ditto, would look like this: - -## Link the digital twin to a data input - -## Visualize twin data \ No newline at end of file diff --git a/docs/docs/quickstart.mdx b/docs/docs/quickstart.mdx new file mode 100644 index 0000000..bf6364c --- /dev/null +++ b/docs/docs/quickstart.mdx @@ -0,0 +1,227 @@ +--- +sidebar_position: 1 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +# Quickstart + +Welcome to OpenTwins, a flexible platform adapted to your needs! Although OpenTwins offers extensive customization options, we understand the importance of simplicity for beginners. Therefore, let's embark on a short journey together, showing you the quickest route to deploy the platform and develop a functional digital twin. + +## Installation + +### Prerequisites +Please be sure you have the following utilities installed on your host machine: + +- [Docker](https://www.docker.com/) +- [Kubernetes](https://kubernetes.io/releases/download/) +- [Helm](https://helm.sh/docs/intro/install/) v3 + +If you don't have a Kubernetes cluster, you can set one up on local using [minikube](https://minikube.sigs.k8s.io/docs/). For a smooth deployment experience, we suggest you use the following minimum configuration values. + +```bash +minikube start --cpus 4 --disk-size 40gb --memory 8192 +``` +```bash +kubectl config use-context minikube +``` + +### Deploy +The quickest way to deploy OpenTwins is [using Helm](https://helm.sh/docs/intro/using_helm/). + +The following command adds the ERTIS repository where the OpenTwins helm chart is located. + +```bash +helm repo add ertis https://ertis-research.github.io/Helm-charts/ +``` + +To deploy the platform with recommended functionality, use the command below: + +```bash +helm upgrade --install opentwins ertis/OpenTwins -n opentwins --wait --dependency-update +``` + +To modify the components to be deployed and connected during the installation, you can check the [installation via Helm](./installation/using-helm.md). + + +## Create your first digital twin + +
+Create digital twins +
+ +**A digital twin must be at least a synchronized replica of a real system or object**. To create it, the first step involves understanding the purpose of the digital twin, designing its structure and defining its most relevant characteristics. Next, it is necessary to define this information in OpenTwins and then connect the data sources that will feed the model. Finally, it is necessary to represent the data in a way that is understandable to any user. + +Optionally, other useful functionalities can be added to the digital twin. In OpenTwins, we offer the integration of AI/ML models, the addition of 3D models and the execution of FMI or containerized simulations. However, this tutorial will not cover these extra functionalities, so we recommend consulting their respective guides for more information. + +Following these steps, we will use OpenTwins to develop the **digital twin of a car**. In this case, for simplicity, we will focus only on the speed and direction of the car's four wheels. In addition, we will record the GPS location of the vehicle for tracking. + + +### Design + +Taking advantage of the platform's functionalities, we will create a [composite digital twin](./overview/concepts.md#digital-twins-composition). +For this purpose, we will define [types](./overview/concepts.md#digital-twin-type) "t_car" and "t_wheel", which will abstract information about the car and the wheel, respectively. +These types will be linked by a composition relation, which means that a car comprises four wheels. Once all this is set up, instantiating the car as a digital twin will automatically generate twins for all four wheels. +In this way, we can independently access the data for each wheel and easily add digital twins for other cars or other contexts. + +
+Create digital twins +
+ +:::info +The creation of **types is not essential** to create a digital twin, but **it is recommended** to facilitate future work. You can create digital twins directly without defining a type, just select the *from scratch* option in the twin creation form. +::: + +### Definition + +#### Create Car type + +First, we will create the car type. To do so, we navigate to the _Types_ section in the interface and click on the blue _Create new type_ button. In this form, we must fill in the [digital twin information](./overview/concepts.md#digital-twin-content) that will be common for all instances. This includes the name, description and image of the twin, along with the values it will store, in this case **gps**. +We will define this type within a namespace and assign it a name. +The combination of the namespace and the name will be referred to as the [thingId](https://eclipse.dev/ditto/3.3/basic-thing.html#thing-id). + +
+ Screenshots of the filled form +
+
+ Create type - Identification and type information + Create type - attributes and features +
+
+
+ +The JSON generated in [Ditto Thing](https://eclipse.dev/ditto/3.3/basic-thing.html#model-specification) model is shown to the right of the form, which in this case corresponds to the following JSON: + +```json +{ + "thingId": "example:t_car", + "policyId": "default:basic_policy", + "attributes": { + "name": "Car", + "description": "Digital twin example for quickstart", + "image": "https://images.pexels.com/photos/119435/pexels-photo-119435.jpeg" + }, + "features": { + "gps": { + "properties": { + "value": null + } + } + } +} +``` + +Click on the blue _Create type_ button to create the type. A message should appear indicating that the type has been successfully created. You can close this message and return to the main screen. + +:::info + +If you have installed OpenTwins with Helm, you should have a basic policy. Currently, we do not take into account the restriction of access to digital twins by [policy](https://eclipse.dev/ditto/3.3/basic-policy.html), so we always use the same one. Still, using this functionality is possible with OpenTwins, although you must interact directly with Eclipse Ditto. + +For more details see the [Eclipse Ditto documentation](https://eclipse.dev/ditto/3.3/http-api-doc.html#/Policies). + +::: + +#### Create Wheel type + +Next we will create the type for the wheels. +In the list of types, we will access the type of the car we have just created to see its information. +Here we select the **children tab** and click on the **create new type** button. +This form is almost identical to the previous one, with the difference that we can directly specify the number of instances of this new type to be created when a *t_car* type is instantiated. +In our example we will have to indicate a 4 in this section and fill in the rest of the form as before. +This type, in addition to its identification and basic information, will have as features the **velocity** and **direction** of the wheel. + +
+ Screenshots of the filled form +
+
+ Create type - Identification and type information + Create type - attributes and features +
+
+
+ +In this case the JSON of the generated Ditto Thing is the following: + +```json +{ + "thingId": "example:t_wheel", + "policyId": "default:basic_policy", + "attributes": { + "name": "Wheel", + "description": "Digital twin example for quickstart", + "image": "https://images.pexels.com/photos/111766/pexels-photo-111766.jpeg" + }, + "features": { + "velocity": { + "properties": { + "value": null + } + }, + "direction": { + "properties": { + "value": null + } + } + } +} +``` + + +After clicking the **Create type** button, a confirmation message will appear. +If we now navigate to the children tab of the *t_car* type, it will show that the *t_wheel* type is one of its children and will be instantiated four times. + +
+Children of car type +
+ +#### Create the digital twins + + +All that remains is to instantiate the car type so that all the twins are created. +To do this, navigate to the *Twins* section and click on **Create a new twin**. +In the form, specify the identification of the twin and select the *t_car* type. +All data will be filled in automatically, though you can modify it if desired by activating the customization switch. + +
+ Screenshots of the filled form +
+
+ Create twin form +
+
+
+ +After clicking on create twin, the 5 digital twins will be generated automatically. A successfull message will appear when the process is finished. +If we check the list of twins, we will see our twin example: car. +By clicking on it and accessing the children tab, we will find four twins corresponding to its wheels, each with the features specified in their respective type. + +### Connection + +### Visualization \ No newline at end of file diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index ac12c11..09b4b53 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -26,7 +26,6 @@ const config = { defaultLocale: 'en', locales: ['en'], }, - presets: [ [ 'classic', @@ -79,7 +78,7 @@ const config = { }, footer: { style: 'dark', - copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, + copyright: `Copyright © ${new Date().getFullYear()} OpenTwins. Built with Docusaurus. Icons from Flaticon.`, }, prism: { theme: lightCodeTheme, diff --git a/docs/static/img/model-raspberry-example.png b/docs/static/img/model-raspberry-example.png new file mode 100644 index 0000000..42a8904 Binary files /dev/null and b/docs/static/img/model-raspberry-example.png differ diff --git a/docs/static/img/model-raspberry-example_dark.png b/docs/static/img/model-raspberry-example_dark.png new file mode 100644 index 0000000..99bf9e2 Binary files /dev/null and b/docs/static/img/model-raspberry-example_dark.png differ