Merge branch 'main' of https://github.com/ertis-research/OpenTwins

README.md

@@ -9,6 +9,7 @@
 
 </br>
 <a href='https://ertis-research.github.io/opentwins' target="_blank"><img alt='Read the Docs' src='https://img.shields.io/badge/Docs-100000?style=for-the-badge&logo=Read the Docs&logoColor=000000&labelColor=33d9b2&color=40407a'/></a>
+<a href='https://github.com/ertis-research/Helm-charts/tree/main/OpenTwins' target="_blank"><img alt='Helm' src='https://img.shields.io/badge/Helm-100000?style=for-the-badge&logo=Helm&logoColor=000000&labelColor=33d9b2&color=40407a'/></a>
 </div>
 
 </br>

docs/docs/examples/ball-example.md

@@ -1,5 +1,2 @@
----
-sidebar_position: 2
----
 
 # Bouncing ball example

docs/docs/examples/raspberry-example/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Raspberry Pi example",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "This section will explain how to reproduce Raspberry pi example."
+  }
+}

docs/docs/examples/string-example.md

@@ -3,3 +3,6 @@ sidebar_position: 1
 ---
 
 # String and number example
+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).

docs/docs/guides/dt-creation.mdx

@@ -0,0 +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
+<Tabs className="unique-tabs"
+    defaultValue="ui"
+    values={[
+        {label: 'Using Grafana interface', value: 'ui'},
+        {label: 'Using http methods', value: 'http'},
+    ]}>
+<TabItem value="ui">
+```
+
+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
+</TabItem>
+
+<TabItem value="http">This is an orange</TabItem>
+</Tabs>
+```

docs/docs/guides/type-creation.mdx

@@ -0,0 +1,99 @@
+---
+sidebar_position: 1
+---
+
+# Creation of the schema of the digital twin 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.
+
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+```mdx-code-block
+<Tabs className="unique-tabs"
+    defaultValue="ui"
+    values={[
+        {label: 'Using Grafana interface', value: 'ui'},
+        {label: 'Using http methods', value: 'http'},
+    ]}>
+<TabItem value="ui">
+```
+As explained in TWINS WIP, OpenTwins has two types of DT schemas. One for creating a single DT and other for creating a type to create multiple instances of a DT.
+
+
+To create a new DT type using OpenTwins plugin in Grafana, just select "Create new type in" button in "Types" tab.
+![CreateType](./img/createTypeButton.png)
+
+A new window with a form that will define the DT and a viewer of the produced JSON schema will have appeared.
+
+The first required information is the identification of the twin. There are two required field.
+- Namespace: Is the name of the context to which the type belongs.
+- ID: This must be unique within the scope of the type. The name of the type will precede it automatically.
+
+![Identification](./img/typeidentification.png)
+
+Next is type information. This basic static information about the type for description. There are several fields, but just one is required:
+- Policy* : We must select a policy.
+- Name.
+- Description.
+- Image: You can paste a image url to show in the type information.
+
+![Information](./img/typeinformation.png)
+
+In addition to the above information, new custom attributes can be defined, normally used as static information. By simply filling in the attribute name and its value, click on the "add" button to add a new attribute.
+
+![Attributes](./img/attributes.png)
+
+Finally, the features section is used to create the variables to be collected by the DT. Simply type the name and click on the "add" button. This will add a new variable to the twin schema.
+
+![Features](./img/typefeatures.png)
+
+An example of a schema of a DT of an abstract vehicle can be seen in the following JSON:
+
+```JSON
+{
+    "thingId": "benchmark:vehicle",
+    "policyId": "default:basic_policy",
+    "attributes": {
+        "name": "Vehicle",
+        "description": "Vehicle type for generating new vehicles.",
+        "image": "ImageLink",
+        "Brand": "EMPTY",
+        "Subtype": "EMPTY"
+    },
+    "features": {
+        "wheels": {
+            "properties": {
+                "value": null
+            }
+        },
+        "power": {
+            "properties": {
+                "value": null
+            }
+        },
+        "capacity": {
+            "properties": {
+                "value": null
+            }
+        }
+    }
+}
+
+```
+
+
+```mdx-code-block
+</TabItem>
+
+<TabItem value="http">
+```
+# Creation using HTTP requests
+
+```mdx-code-block
+</TabItem>
+</Tabs>
+
+```

docs/old/examples/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Examples",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "There are two ways of creating digital twins, the first is using the Eclipse Ditto API and the second is using our Grafana plugin(WIP). \n It is recommended using Postman to make all requests but youy can use your own method."
+  }
+}

docs/old/examples/ball-example.md

@@ -0,0 +1,2 @@
+
+# Bouncing ball example

docs/old/examples/raspberry-example/raspberry-example.mdx

@@ -0,0 +1,193 @@
+---
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Raspberry example
+
+## Requirements
+The only requisites are:
+- Collect `IP` address of Ditto.
+- Collect `USER` and `PASSWORD`
+
+## First step. Creating the twin
+First of all, you need to understand how twins work:
+A twin has two main components:
+- **attributes**. It contains the basic information of the twin, such as the name, location, etc.
+- **features**. It contains the variables of the twin. Imagine a twin of a sensor that measures humidity and temperature. You will have two features: humidity and temperature. 
+Each feature must contain a field called `properties` that contains, as its name says, every property of the feature, for example, the value of the temperature and the time the value has been measured.
+
+
+Once we know wich data will store our twin, it is time to create it.
+To create a twin, we need to make HTTP requests, we recommend you to use Postman. We need to create a `PUT` request to the Ditto url with the next pattern and a specific payload.
+
+```bash
+PUT http://{DITTO_IP}:{PORT}/api/2/things/{nameOfThing}
+```
+
+The payload has the attributes and features of the twin mentioned above. As attributes we have the location, in this case "Spain".
+
+As features we have temperature and humidity. In this case both features has the same properties, value and timestamp, but they dont have to fit.
+```json
+{
+    "attributes": {
+        "location": "Spain"
+    },
+    "features": {
+        "temperature": {
+            "properties": {
+                "value": null,
+                "timestamp": null
+            }
+        },
+        "humidity": {
+            "properties": {
+                "value": null,
+                "timestamp": null
+            }
+        }
+    }
+}
+```
+
+Once we have checked that all the data is correct, just click send. You should recieve a 200 code of a correct execution.
+
+To check if the twin has been created properly, just send a `GET` request to the same url.
+
+```bash
+GET http://{DITTO_IP}:{PORT}/api/2/things/{nameOfThing}
+```
+
+You should be granted with the schema of the new twin.
+
+
+## Second step. Recieving the data
+A digital twin is a copy of a real object or process, but we just have a schema, so we need to feed it with data. To achieve this we can use both the Kafka or MQTT broker that are installed with the platform.
+
+Ditto needs to recieve the data in a specific format called [`Ditto Protocol`](https://www.eclipse.org/ditto/protocol-overview.html), so we need the data to be sent in that format. But don't worry if you recieve the data on other format, Ditto gives us the chance to create a mapping with Javascript to change the format when the data arrives to Ditto(We will always recommend you to send the data on Ditto protocol).
+
+Asuming that we recieve that data in Ditto protocol we can configure the connection with one of the two brokers, Kafka or MQTT. To create a connection you can proceed with the same steps as creating the twins, make a `POST` request to the url and a payload that contains the connection information.
+
+```bash
+POST http://{DITTO_IP}:{PORT}/api/2/connections
+```
+
+<Tabs>
+<TabItem value="kafka" label="Kafka">
+
+```json
+  {
+    "name": "{NAME OF THE CONNECTION}",
+    "connectionType": "kafka",
+    "connectionStatus": "open",
+    "uri": "tcp://KAFKA_BROKER_IP",
+    "sources": [
+      {
+        "addresses": [
+            {"list Of topics to read"}
+        ],
+        "consumerCount": 1,
+        "qos": 1,
+        "authorizationContext": [
+            "nginx:ditto"
+        ],
+        "headerMapping": {
+            "correlation-id": "{{header:correlation-id}}",
+            "namespace": "{{ entity:namespace }}",
+            "content-type": "{{header:content-type}}",
+            "connection": "{{ connection:id }}",
+            "id": "{{ entity:id }}",
+            "reply-to": "{{header:reply-to}}"
+        },
+        "replyTarget": {
+            "address": "{{header:reply-to}}",
+            "headerMapping": {
+                "content-type": "{{header:content-type}}",
+                "correlation-id": "{{header:correlation-id}}"
+            },
+            "expectedResponseTypes": [
+                "response",
+                "error"
+            ],
+            "enabled": true
+        }
+      }
+    ],
+    "targets": [],
+    "clientCount": 5,
+    "failoverEnabled": true,
+    "validateCertificates": true,
+    "processorPoolSize": 1,
+    "specificConfig": {
+        "saslMechanism": "plain",
+        "bootstrapServers": "KAFKA_BROKER_IP"
+    },
+    "tags": []
+  }
+```
+
+</TabItem>
+<TabItem value="mqtt" label="MQTT">
+
+```json
+  {
+    "name": "{NAME OF THE CONNECTION}",
+    "connectionType": "mqtt-5",
+    "connectionStatus": "open",
+    "uri": "tcp://MQTT_BROKER_IP",
+    "sources": [
+      {
+        "addresses": [
+            {"list Of topics to read"}
+        ],
+        "consumerCount": 1,
+        "qos": 1,
+        "authorizationContext": [
+            "nginx:ditto"
+        ],
+        "headerMapping": {
+            "correlation-id": "{{header:correlation-id}}",
+            "namespace": "{{ entity:namespace }}",
+            "content-type": "{{header:content-type}}",
+            "connection": "{{ connection:id }}",
+            "id": "{{ entity:id }}",
+            "reply-to": "{{header:reply-to}}"
+        },
+        "replyTarget": {
+            "address": "{{header:reply-to}}",
+            "headerMapping": {
+                "content-type": "{{header:content-type}}",
+                "correlation-id": "{{header:correlation-id}}"
+            },
+            "expectedResponseTypes": [
+                "response",
+                "error"
+            ],
+            "enabled": true
+        }
+      }
+    ],
+    "targets": [],
+    "clientCount": 1,
+    "failoverEnabled": true,
+    "validateCertificates": true,
+    "processorPoolSize": 1,
+    "tags": []
+  }
+```
+
+</TabItem>
+</Tabs>
+
+Once we have checked that all the data is correct, just click send. You should recieve a 200 code of a correct execution.
+
+To check if the twin has been created properly, just send a `GET` request to the same url adding the if of the new connection
+
+```bash
+GET http://{DITTO_IP}:{PORT}/api/2/connections/{connectionID}
+```
+You should be granted with the information of the connection.
+
+With all this setup, the configuration should be already done, and Ditto should be recieving the data from the broker. If you want to create an example script to send the data, just click on the next link.