diff --git a/README.md b/README.md index 0e139eb..f6c95cf 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@
Read the Docs +Helm
diff --git a/docs/docs/examples/ball-example.md b/docs/docs/examples/ball-example.md index 0c851cf..2164366 100644 --- a/docs/docs/examples/ball-example.md +++ b/docs/docs/examples/ball-example.md @@ -1,5 +1,2 @@ ---- -sidebar_position: 2 ---- # Bouncing ball example \ No newline at end of file diff --git a/docs/docs/examples/raspberry-example/_category_.json b/docs/docs/examples/raspberry-example/_category_.json new file mode 100644 index 0000000..e4f243b --- /dev/null +++ b/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." + } +} \ No newline at end of file diff --git a/docs/docs/examples/string-example.md b/docs/docs/examples/string-example.md index 4d073b8..6a65d8c 100644 --- a/docs/docs/examples/string-example.md +++ b/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). diff --git a/docs/docs/guides/add-3d-visualization.md b/docs/docs/guides/add-3d-visualization.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/docs/guides/connect-dt-with-real-devices.md b/docs/docs/guides/connect-dt-with-real-devices.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/docs/guides/create-dt-scheme.md b/docs/docs/guides/create-dt-scheme.md deleted file mode 100644 index 115c9ba..0000000 --- a/docs/docs/guides/create-dt-scheme.md +++ /dev/null @@ -1 +0,0 @@ -# Create Digital Twin scheme \ No newline at end of file diff --git a/docs/docs/guides/dt-creation.mdx b/docs/docs/guides/dt-creation.mdx new file mode 100644 index 0000000..7aab3ef --- /dev/null +++ b/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 + + +``` + +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/img/attributes.png b/docs/docs/guides/img/attributes.png new file mode 100644 index 0000000..bd4fced Binary files /dev/null and b/docs/docs/guides/img/attributes.png differ diff --git a/docs/docs/guides/img/createTwinButton.png b/docs/docs/guides/img/createTwinButton.png new file mode 100644 index 0000000..eadc327 Binary files /dev/null and b/docs/docs/guides/img/createTwinButton.png differ diff --git a/docs/docs/guides/img/createTypeButton.png b/docs/docs/guides/img/createTypeButton.png new file mode 100644 index 0000000..9314456 Binary files /dev/null and b/docs/docs/guides/img/createTypeButton.png differ diff --git a/docs/docs/guides/img/typefeatures.png b/docs/docs/guides/img/typefeatures.png new file mode 100644 index 0000000..1fab082 Binary files /dev/null and b/docs/docs/guides/img/typefeatures.png differ diff --git a/docs/docs/guides/img/typeidentification.png b/docs/docs/guides/img/typeidentification.png new file mode 100644 index 0000000..edd24b2 Binary files /dev/null and b/docs/docs/guides/img/typeidentification.png differ diff --git a/docs/docs/guides/img/typeinformation.png b/docs/docs/guides/img/typeinformation.png new file mode 100644 index 0000000..89a18f5 Binary files /dev/null and b/docs/docs/guides/img/typeinformation.png differ diff --git a/docs/docs/guides/type-creation.mdx b/docs/docs/guides/type-creation.mdx new file mode 100644 index 0000000..5760e2f --- /dev/null +++ b/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 + + +``` +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 + + + +``` +# Creation using HTTP requests + +```mdx-code-block + + + +``` \ No newline at end of file diff --git a/docs/old/examples/_category_.json b/docs/old/examples/_category_.json new file mode 100644 index 0000000..52773df --- /dev/null +++ b/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." + } +} diff --git a/docs/old/examples/ball-example.md b/docs/old/examples/ball-example.md new file mode 100644 index 0000000..2164366 --- /dev/null +++ b/docs/old/examples/ball-example.md @@ -0,0 +1,2 @@ + +# Bouncing ball example \ No newline at end of file diff --git a/docs/old/examples/raspberry-example/Untitled.png b/docs/old/examples/raspberry-example/Untitled.png new file mode 100644 index 0000000..2b5828e Binary files /dev/null and b/docs/old/examples/raspberry-example/Untitled.png differ diff --git a/docs/old/examples/raspberry-example/raspberry-example.mdx b/docs/old/examples/raspberry-example/raspberry-example.mdx new file mode 100644 index 0000000..8fd8863 --- /dev/null +++ b/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 +``` + + + + +```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": [] + } +``` + + + + +```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": [] + } +``` + + + + +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. \ No newline at end of file diff --git a/docs/old/examples/raspberry-example/sending-data.mdx b/docs/old/examples/raspberry-example/sending-data.mdx new file mode 100644 index 0000000..774157f --- /dev/null +++ b/docs/old/examples/raspberry-example/sending-data.mdx @@ -0,0 +1,232 @@ +--- +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Sending data to Ditto +In this case we will use a Raspberry Pi 3B with Raspbian buster OS connected to a DHT22 temperature and humidity sensor. + +## Setting up the Raspberry Pi +In the following image the pins of the Raspberry used are shown. + +We will use pins 2, 6, 23 and 24. + +## Obtaining sensor data +To get the data from the sensor it is necessary to install its library. + +```bash +sudo pip3 install Adafruit_DHT +``` +We can test the operation of the sensor by creating a .py file with the following code (in our case it is called dht_code.py and I have placed it on the desktop). + + +```python +import Adafruit_DHT +import time + +SENSOR_DHT = Adafruit_DHT.DHT22 +PIN_DHT = 24 + +while True: + humedad, temperatura = Adafruit_DHT.read(SENSOR_DHT, PIN_DHT) + if humedad is not None and temperatura is not None: + print("Temp={0:0.1f}C Hum={1:0.1f}%".format(temperatura, humedad)) + else: + print("Lecture fails, chech connection"); + time.sleep(3); +``` +And we run it as follows: + +```bash +cd Desktop/ +python3 dht_code.py +``` + +## Installing Mosquitto on Raspberry + +To send the data to DITTO we will use MQTT with the *Mosquitto* broker. + +```bash +sudo wget http://repo.mosquitto.org/debian/mosquitto-repo.gpg.key +sudo apt-key add mosquitto-repo.gpg.key +cd /etc/apt/sources.list.d/ +sudo wget http://repo.mosquitto.org/debian/mosquitto-buster.list +sudo -i +apt-get update +apt-get install mosquitto +apt-get install mosquitto-clients +``` +With this we would already have Mosquitto installed on our Raspberry. To test it we can open two terminals, subscribe to a *topic* with one and publish to that *topic* with another. + +```bash +mosquitto_sub -h localhost -t casa/comedor/temperatura +``` + +```bash +mosquitto_pub -h localhost -t casa/comedor/temperatura -m "Temperatura: 25ºC" +``` +## Configuring Mosquitto on raspberry + +If we wanted to try to send and receive messages by MQTT between the raspberry and another device, we would have to configure the following. + +1. From the main route of the Raspberry edit the Mosquitto configuration file. + +```bash +sudo nano /etc/mosquitto/mosquitto.conf +``` +1. Write these three lines at the end of the file to enable connections with any IP through port 1883 and configure authentication. + +``` +listener 1883 0.0.0.0 + +password_file /etc/mosquitto/passwd +allow_anonymous true +``` +So that mosquito.conf would look like this: + +``` +# Place your local configuration in /etc/mosquitto/conf.d/ +# +# A full description of the configuration file is at +# /usr/share/doc/mosquitto/examples/mosquitto.conf.gz + +pid_file /run/mosquitto/mosquitto.pid + +persistence true +persistence_location /var/lib/mosquitto/ + +log_dest file /var/log/mosquitto/mosquitto.log +log_type all +log_timestamp true + +include_dir /etc/mosquitto/conf.d + +listener 1883 0.0.0.0 + +password_file /etc/mosquitto/passwd +allow_anonymous true +``` +1. Save the file with Ctrl-O, Enter and Ctrl-X. +2. Create a user with password using the following command. Replace USERNAME with the username you want. When you run it, it will ask you to enter a password, which will not be visible while you type it. + +```bash +sudo mosquitto_passwd -c /etc/mosquitto/passwd USERNAME +``` +1. Restart Mosquitto with the following command: + +```bash +sudo systemctl restart mosquitto +``` +Finally, we would have Mosquitto configured to receive and send from other IPs. To do this you have to add -u "USERNAME" and -P "PASSWORD" (including quotes) to the respective command. + +For example (in this case being *user* both the user and the password): + +```bash +mosquitto_sub -h 192.168.0.27 -u "usuario" -P "usuario" -t "/Raspberry/Sensores/DHT22" +``` + +## Sending data to MQTT from Raspberry + +To work with MQTT in python we will need to make use of Eclipse Paho. + +```bash +sudo pip3 install paho-mqtt +``` +Now, we will create a .py file that publishes the sensor data in the corresponding topic of MQTT. For this we have adapted the code example exposed in the following link to the DHT22 sensor with the Adafruit_DHT library and the requirements of MQTT. + +[How to use MQTT in Python (Paho)](https://www.emqx.com/en/blog/how-to-use-mqtt-in-python) + +In addition, the message sent by MQTT regarding the Ditto Protocol has been made following both the documentation and an example of use. + +[Things - Create-Or-Modify protocol specification](https://www.eclipse.org/ditto/protocol-specification-things-create-or-modify.html) + +- Code to send sensor data to MQTT and Eclipse Ditto + + ```python + from paho.mqtt import client as mqtt_client + import time + import random + import Adafruit_DHT + import json + + #Constants to connect to MQTT + broker = "IP OF MQTT" + port = POR OF MQTT + topic = "telemetry" + client_id = f'python-mqtt-{random.randint(0, 1000)}' + username = "raspberry_DHT22_1@ditto" + password = "password" + + #Constantes para obtener información del sensor + SENSOR_DHT = Adafruit_DHT.DHT22 + PIN_DHT = 24 + + #Constantes para crear el mensaje de Eclipse Ditto + DITTO_NAMESPACE = "raspberry"; + DITTO_THING_ID = "DHT22_1"; + + def connect_mqtt(): + def on_connect(client, userdata, flags, rc): + if rc == 0: + print("Connected to MQTT Broker!") + else: + print("Failed to connect, return code %d\n", rc) + # Set Connecting Client ID + client = mqtt_client.Client(client_id) + client.username_pw_set(username, password) + client.on_connect = on_connect + client.connect(broker, port) + return client + + def publish(client): + while True: + time.sleep(1) + msg = getValues(); + if msg is not None: + result = client.publish(topic, msg) + status = result[0] + if status == 0: + print(f"Send '{msg}' to topic '{topic}'") + else: + print(f"Failed to send message to topic {topic}") + + def getValues(): + humedad, temperatura = Adafruit_DHT.read(SENSOR_DHT, PIN_DHT) + if humedad is not None and temperatura is not None: + temp = "{0:0.1f}".format(temperatura) + hum = "{0:0.1f}".format(humedad) + output = "{\"topic\": \"" + output += DITTO_NAMESPACE + output += "/" + output += DITTO_THING_ID + output += "/things/twin/commands/modify\",\"headers\":{\"response-required\":false, \"content-type\":\"application/vnd.eclipse.ditto+json\"}," + output += "\"path\": \"/features\", \"value\":{" + output += sensorString("temperature", temp) + output += "," + output += sensorString("humidity", hum) + output += "}}" + return output + else: + print("Failed on lecture, check circuit") + return None + + def sensorString(name, value): + return "\"" + name + "\": { \"properties\": { \"value\": " + value + "}}"; + + def run(): + client = connect_mqtt() + client.loop_start() + publish(client) + + if __name__ == '__main__': + run() + ``` + +This code has been saved in a .py file with the name of *dht22publisher.py* and have saved it on the desktop. To execute it we use: + +```bash +cd Desktop/ +python3 dht22publisher.py +``` \ No newline at end of file diff --git a/docs/old/examples/string-example.md b/docs/old/examples/string-example.md new file mode 100644 index 0000000..4d073b8 --- /dev/null +++ b/docs/old/examples/string-example.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- + +# String and number example diff --git a/files_for_manual_deploy/pivot-simulation-deployment.yaml b/files_for_manual_deploy/pivot-simulation-deployment.yaml index 6626a8d..e9bd5d2 100644 --- a/files_for_manual_deploy/pivot-simulation-deployment.yaml +++ b/files_for_manual_deploy/pivot-simulation-deployment.yaml @@ -16,7 +16,7 @@ spec: name: pivot-rest-deploy spec: containers: - - image: ertis-rest-api-pivot + - image: ertis/ertis-rest-api-pivot name: pivot-rest-deploy env: - name: KUBE_TOKEN @@ -24,11 +24,11 @@ spec: - name: KUBE_HOST value: - name: IMAGE_NAME - value: + value: ertis/ertis-pivot-runner - name: DEPLOYMENT_NAME - value: + value: pivot-rest-deploy - name: NAMESPACE - value: digitaltwins + value: ports: - containerPort: 8001 - imagePullPolicy: Always \ No newline at end of file + imagePullPolicy: Always diff --git a/files_for_manual_deploy/pivot-telegraf.yaml b/files_for_manual_deploy/pivot-telegraf.yaml new file mode 100644 index 0000000..f2e7956 --- /dev/null +++ b/files_for_manual_deploy/pivot-telegraf.yaml @@ -0,0 +1,44 @@ +replicaCount: 1 +service: + enabled: false +config: + agent: + debug: true + processors: + - rename: + replace: + - tag: "value_idSimulationRun_properties_value" + dest: "idSimulationRun" + - starlark: + source: | + def apply(metric): + topic = metric.tags["topic"] + if topic != None and topic != "": + thId = topic.split('/') + if len(thId) > 1: metric.tags["thingId"] = thId[0]+":"+thId[1] + return metric + else: + return None + outputs: + - influxdb_v2: + urls: + - "http://{IP_INFLUX}:30716" + token: "Hjh3ysMQ6evK=qqpFSYqn-s3JGovJLfHxyCDM=eNNZkdM-uuro93dNtJcodejLYYob2geKQ/29z3Kxui=y6FlL?dZeU9EFRxrYn284V/kZG5==jxLVAMJrYOv?LF79ahwIbhvstMN6gmfQ3DH7/IzUB7VlBZK-cd8aN7YqiFrYRLkBUv7H0QkbqPxgf2dMgCMCwZaLMk9RUeMaBfx2lQ=Mq1EEJJw-Jp!BmpCDnhlc!6D22PaE=Y3sgWWNhRv8oP" + organization: "opentwins" + bucket: "default" + timeout: "120s" + inputs: + - kafka_consumer: + brokers: + - "{KAFKA_IP}:{KAFKA_PORT}" + topics: + - "riego" + tags: + parent: "pivot:irrigation_simulation" + tag_keys: + - "value_idSimulationRun_properties_value" + - "topic" + data_format: "json" +metrics: + internal: + enabled: false \ No newline at end of file