Workshop: How to develop on Platform with Ontologies, Spring Boot Client Library, Digital Twins and Dashboards?

Owned by DevPortal Editor (Unlicensed)
13/09/21
12 min read

Introduction

You can find the sources of these examples in the workshop attached files

The goal in this workshop is to know onesait Platform's main tools to integrate IoT solutions.
To do this, we will model a case to integrate a connected sensor, which reports atmospheric values to the platform. Starting in the data model and device's connection, data will be remotely inserted in the platform. After these steps, exploitation tools will be used on this data, to transform it, visualize it or share it with other systems. For this workshop we will use the environment: https://lab.onesaitplatform.com/controlpanel

First of all, you have to create a user.

Defining an ontology in the Platform

Onesait Platform is a data-centric platform, inasmuch all the entities in the platform refer to the agreed data model to model the elements in a solution. When we talk about an ontology, we refer to that data model chosen to exchange information between involved devices and systems. Through the ontology, we can model and define what data, and in what format, the platform accepts for my device.
There are several ways to create ontologies in the Platform:

For this workshop, we will create an ontology step by step. An example could be the following ontology:

The platform does not allow to create several ontologies with the same name, so to avoid problems, we will use the following nomenclature to create our ontology: atmSensor_<my-user>

Among the provided templates, in the creation wizard's left side, we can start with Empty Base, under the General category, that starts with an empty schema. When the sensor fields are added, it will look like this:

For every field in the ontology, we can select the type of the data to be stored, whether it is required by the platform in the message exchange or not, and whether we want to encrypt the information on it. At the end, if we click on the Update Schema button, we will see the JSON Schema that's appropriate for the defined categories. Besides, if we click on Generate Instance, we will see an instance of the defined ontology:

If everything is OK, when we click New, the ontology is created. Just after that, the platform guides us and suggests several choices to continue defining our solution. Following this example's flow line, we will click on: 'Create new Digital Client for this ontology'.

Creating an Digital Client in the Platform

The Digital Client entity is a record in the platform used as an interface with the different ontologies to which it can access. In a typical case, an Digital Client is defined for a device type that will insert or consume a subset of ontologies.
We can define the Digital Client by filling in the required fields and by selecting the involved ontologies. For this workshop, we will select the ontology we have just created in the previous step.

And, once we click on New, it is created.

Digital Broker – Practical example using Client4SpringBoot library

Client4SpringBoot is a Java library designed to work on Spring Boot and that simplifies access to DigitalBroker by wrapping the queries with a Repository interface that allows you invoke the DigitalBroker using Java methods.

For this workshop, we will create a Java application that will work as a data simulator, will periodically insert data into the ontology that we have created previously.

Create Maven project

Before starting, if you don't have the Platform's Development Environment, we recommend you install it. You can see how to do it in this tutorial: How to run the platform in my Windows PC with OP-SDK (specifically in Step 1: Download and install Development Environment in Windows).
Once you have your environment configured with Java, Maven and Eclipse, you can go on.

Start Eclipse and select the option Create a Maven project, in the pop-up window select the option Create a Simple project and configure it like this:

Configuring communication with the platform

Once your project has been successfully created, you have to add the Client4SpringBoot library, for this you have to add both the dependency of the library and the repository of where we are going to download it. We put all this in the pom.xml:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.2.4.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>com.minsait.onesait.platform</groupId> <artifactId>workshop</artifactId> <version>0.0.1-SNAPSHOT</version> <name>workshop</name> <description>IoT Workshop</description> <properties> <java.version>1.8</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>com.minsait.onesait.platform</groupId> <artifactId>onesaitplatform-iotclient4springboot</artifactId> <version>1.3.7</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.16.16</version> </dependency> </dependencies> <repositories> <repository> <id>onesait platform releases</id> <url>https://nexus.onesaitplatform.com/nexus/content/repositories/releases/</url> </repository> <repository> <id>maven central</id> <url>http://central.maven.org/maven2/</url> </repository> </repositories> </project>

The next thing is to configure the connection to the platform. To do this we will open the file application.yml:

spring: ## General Config application.name: Example IoT Client4SpringBoot onesaitplatform: iotclient: urlRestIoTBroker: https://lab.onesaitplatform.com/iot-broker sslverify: true token: 4a456739a56646419634136607f6c2a9 deviceTemplate: IoTSensorClient device: IoTSensorClient_instance connectTimeoutInSec: 10 writeTimeoutInSec: 30 readTimeoutInSec: 30 ## LOGGING CONF logging: path: ./target/ file: ${spring.application.name} level: org.springframework: INFO com.minsait: INFO

In these entries, you must specify the information you previously registered from the ControlPanel:

  • onesaitplatform.iotclient.token=4a456739a56646419634136607f6c2a9

  • onesaitplatform.iotclient.deviceTemplate=IoTSensorClient

  • onesaitplatform.iotclient.device=IoTSensorClient_instance

Creating the Java class representing your ontology

The next step is creating the Java class representing your ontology.

  • In the folder src/main/java create the package com.minsait.onesait.platform.workshop.ontology and create two classes inside of it: AtmSensorOntology and AtmSensor

  • The first thing to do is adding the @Data annotation to both classes. This Lombok annotation automatically generates the get and set of each attribute and the methods hashCode and toString()

  • Now edit the AtmSensorOntology class to add this:

package com.minsait.onesait.platform.workshop.ontology; import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.databind.JsonNode; import com.minsait.onesait.platform.client.springboot.fromjson.ContextData; import lombok.Data; @Data @JsonInclude(JsonInclude.Include.NON_NULL) public class AtmSensorOntology { private JsonNode _id; private ContextData contextData; @JsonProperty("atmSensor_rbarrio") private AtmSensor atmSensor; }

Let's see what each element means:

  1. The @JsonInclude(JsonInclude.Include.NON_NULL) annotation. It prevents the attributes to be returned if they are null.

  2. The _id field represents the internal identification in the database where the element was inserted, in this case MongoDB. If you don't need it, you may decide not to include it, but we have done it here.

  3. The contextData field represents the insertion context automatically provided by the Platform. It includes user and insertion date and time. You may decide not to include it if you are not going to use it.

  4. The atmSensor field really represents the ontology instance, the one we were seeing before. It is mapped with the AtmSensor property name (Same as in the JSON).

  • The next step is creating the attributes making up your ontology. Let's remember them:

    • temperature: Number required.

    • humidity: Number required.

    • pressure: Number required.

So, you have to add this properties to the class AtmSensor like this:

Creating the basic Repository to connect with the Platform

Once you have configured connection with the platform in the application.yml file and the class representing the ontology, you can create a Repository. Let's see how:

  • Create the package com.minsait.onesait.platform.workshop.repository and create the interface AtmSensorRepository and add the annotation @IoTBrokerRepository(“atmSensor_rbarrio“) to specify the ontology on which the Repository works.

  • Now, add the methods that your Repository uses. In this workshop we are going to create the basics operations:

 

  1. The @IoTBrokerQuery annotation is used for queries, such as recovering all the instances with getAllAtmSensor or counting them, etc. You can also pass it parameters, as you can see in the getByTemperatureAtmSensor method.

  2. The @IoTBrokerInsert annotation can be used to insert one AtmSensor, or a list of them. As a result, it returns a String with its ID.

  3. The @IotBrokerUpdate annotation allows you to update a AtmSensor by sending, as the parameters, its id (from the database) and instance.

  4. The @IoTBrokerDelete annotation allows you to delete a AtmSensor by its ID.

Communication with the Platform

You have everything ready to communicate with the platform through the communicating class:

  1. Create the package com.minsait.onesait.platform.workshop.controller and inside of it the AtmSensorController class and annotate it with the @Component annotation so it is a Spring Bean, and with the @Slf4j annotation, that instantiates a SL4J log (configured with logback in platform).

  2. Add the injection to your repository:

The next step is to create a @PostConstruct method (so that it is automatically invoked once the Spring Boot context is loaded). In this method we are going to insert an instance in the ontology using our repository:

 

Create the class WorkshopApp inside the package com.minsait.onesait.platform.workshop and add the annotations SpringBootApplication, EnableAutoConfig and ComponentScan:

 

From Eclipse, you can now launch your Eclipse project simply by hovering on the Application class, and select Debug As > Java Application. If everything ir OK, you should see the following logs:

 

Finally, click on Apply and Run.

Digital Twin - Practical Example

Digital Twin can be defined as a virtual model of physic assets or industrial processes that continually learn, provide data and respond to changes made in their environment. The concept of Digital Twin originally was used in CAD and simulation environments but is now commonly used in IoT technologies. According to Gartner, Digital Twin technology will be one of the 10 top strategic and disruptive technologies in 2018.

As said before, a Digital Twin is the virtual representation of a system or a physical device. This representation is defined by three elements:

  • Status: value of each of its properties, representing in real time what the device is “doing”; e.g. an engine turning at 1800 rpm at an optimal work temperature.

  • Actions: external actions or commands that can be applied to the device or that the device can respond to; e.g. an engine can be turned off.

  • Events: notifications that can be sent a device by certain events; e.g. an engine can send an event of being turned off if its working temperature exceeds a threshold value.

Create Digital Twin Type

  • Go to onesait Platform Control Panel (https://lab.onesaitplatform.com/controlpanel/).

  • To create the Digital Twin Type go to the following menu Digital Twin ->My Digital Twin Definitions. Once there, you will be able to start creating your Digital Twin type by pressing the Create button.

  • Put a name and a description for your Digital Twin, and remember the nomenclature:

  • Add the properties of your turbine: represent the status of the Digital Twin. Those are the variables that will be ingested and processed in the platform as a device shadow.

  • Add the actions: notifications and actions that a Digital Twin receives from the platform.

  • Add the events: notifications and actions that the Digital Twin sends to the platform.

  • Add the logic: the platform allows defining what kind of logic will the Digital Twin execute. For this example, the logic is programmed in Javascript. By default, when creating a Digital Twin, Type the following functions are added:

    • Init: executed only when registering the Digital Twin in the platform.

    • Main: periodically executes the Digital Twin.

    • onActionXXX: a method will be created for each action defined in the Actions section, where we can define the logic that we want to execute when the Digital Twin receives an action from the platform.

 

Create Digital Twin

Once created the Digital Twin Type “Sensehat”, the next step is to create a concrete instance of the Digital Twin. To create an instance of the Digital Twin go the following menu: Digital Twin > My Digital Twins.

Where:

  • Digital Twin Type corresponds to the Digital Twin Type that has been created previously and therefore defines the Web Thing Description. In addition, when selecting the type of DigitalTwin we assign the logic defined for this type.

  • URL scheme, interface, port, ContextPath and IPV6: They provide the Digital Twin with the necessary information to infer its URL and that it be sent to the platform in the Registration message. Therefore, the platform can notify the actions. 

  • Broker endpoint is the URL where you have to notify the Digital Twin events on a platform. 

  • DigitalTwinKey is the key with which the Digital Twin can be authenticated against the platform.

Execute Digital Twin

Once you have defined our Digital Twin, the platform allows you to generate the corresponding code. In the current platform version, the code is generated in Java.

  • To see the Digital Twin's generated code, go again to Digital Twin -> My Digital Twin and select the already created Digital Twin instance.

  • To generate the code, you must select the following options:

Then click on Generate and the Maven project will be compiled (Java) and downloaded, ready to be executed.

Unzip the zip downloaded on the directory S:\sources and compile the maven project with the command:

If everything is OK, you should see something like this.

On the target directory, the JAR file should be created with the compilation. Execute it with the command:

You can see the following logs:

 

Dashboard - Practical example

We are going to create a simple dashboard using the data generated with my Digital Twin. It’s important to remember that, when you create a Digital Twin, an ontology is created with the name TwinProperties<my-digitaltwin-type-name>, in our case “TwinPropertiesTurbine_rbarrio“. So, we are going to use this ontology to create our dashboard.

Create Datasource

For this workshop we are going to create a dashboard to show the temperature evolution of the Digital Twin.

First of all, you have to create a datasource going to the menu VISUALIZATION > My Datasources and then click on “create” button. We use the following query to create the datasource:

Create Gadget

Go to the menu option VISUALIZATION > My Gadgets and click on “Create Gadget” button. First, you have to select the datasource that you create in the previus step.

Next, you can select the type of your gadget. In this workshop we are going to create a line gadget:

Then, you can configure your dashboard:

Create dashboard

The last step is to create the dashboard through the menu option VISUALIZATIONS > My Dashboards and by selecting the “New Dashboard” button.

Once you has created the dashboard, you’ll see something like this:

Click on the + button and select “Line chart”

Select your gadget and click “ADD GADGET“: