¿Cómo desarrollar sobre la Plataforma con Entidades, Spring Boot, Digital Twins y Dashboards?
Introducción
Puedes encontrar las fuentes de estos ejemplos en los archivos adjuntos del taller
El objetivo de este taller es conocer las principales herramientas de onesait Platform para integrar soluciones IoT.
Para ello, modelaremos un caso para integrar un sensor conectado, que reporta valores atmosféricos a la plataforma. Partiendo del modelo de datos y de la conexión del dispositivo, se insertarán los datos de forma remota en la plataforma. Tras estos pasos, se utilizarán herramientas de explotación sobre estos datos, para transformarlos, visualizarlos o compartirlos con otros sistemas. Para este taller utilizaremos el entorno: https://lab.onesaitplatform.com/controlpanel
Lo primero, tienes que crear un usuario.
Definir una ontología en la Plataforma
Onesait Platform es una plataforma centrada en los datos, ya que todas las entidades de la plataforma hacen referencia al modelo de datos acordado para modelar los elementos de una solución. Cuando hablamos de una ontología, nos referimos a ese modelo de datos elegido para intercambiar información entre los dispositivos y sistemas involucrados. A través de la ontología, podemos modelar y definir qué datos, y en qué formato, acepta la plataforma para mi dispositivo.
Hay varias formas de crear ontologías en la Plataforma:
Para este taller, crearemos una ontología paso a paso. Un ejemplo podría ser la siguiente ontología:
La plataforma no permite crear varias ontologías con el mismo nombre, así que para evitar problemas, utilizaremos la siguiente nomenclatura para crear nuestra ontología: atmSensor_<mi-usuario>
Entre las plantillas proporcionadas, en la parte izquierda del asistente de creación, podemos empezar con Empty Base, bajo la categoría General, que empieza con un esquema vacío. Cuando se añadan los campos del sensor, se verá así:
Para cada campo de la ontología, podemos seleccionar el tipo de dato a almacenar, si es requerido por la plataforma en el intercambio de mensajes o no, y si queremos encriptar la información del mismo. Al final, si hacemos clic en el botón Actualizar esquema, veremos el esquema JSON adecuado para las categorías definidas. Además, si pulsamos en Generar Instancia, veremos una instancia de la ontología definida:
Si todo va bien, al hacer clic en Nuevo, se crea la ontología. Inmediatamente después, la plataforma nos guía y nos sugiere varias opciones para seguir definiendo nuestra solución. Siguiendo la línea de flujo de este ejemplo, haremos clic en: 'Crear nuevo Cliente Digital para esta ontología'.
Creación de un Cliente Digital en la Plataforma
La entidad Cliente Digital es un registro en la plataforma que sirve de interfaz con las diferentes ontologías a las que puede acceder. En un caso típico, se define un Cliente Digital para un tipo de dispositivo que insertará o consumirá un subconjunto de ontologías.
Podemos definir el Cliente Digital rellenando los campos requeridos y seleccionando las ontologías implicadas. Para este taller, seleccionaremos la ontología que acabamos de crear en el paso anterior.
Y, una vez que hagamos clic en Nuevo, se creará.
Digital Broker - Ejemplo práctico con la librería Client4SpringBoot
Client4SpringBoot es una librería Java diseñada para trabajar sobre Spring Boot y que simplifica el acceso a DigitalBroker envolviendo las consultas con una interfaz de Repositorio que te permite invocar al DigitalBroker mediante métodos Java.
Para este taller, crearemos una aplicación Java que funcionará como simulador de datos, e insertará periódicamente datos en la ontología que hemos creado previamente.
Crear proyecto Maven
Antes de empezar, si no tienes el Entorno de Desarrollo de la Plataforma, te recomendamos que lo instales. Puedes ver cómo hacerlo en este tutorial: (Desarrollar) ¿Cómo ejecutar la plataforma en mi PC con Windows con OP-SDK? (concretamente en el Paso 1: Descargar e instalar el Entorno de Desarrollo en Windows).
Una vez que tengas tu entorno configurado con Java, Maven y Eclipse, puedes continuar.
Inicia Eclipse y selecciona la opción Crear un proyecto Maven, en la ventana emergente selecciona la opción Crear un proyecto simple y configúralo así:
Configurar la comunicación con la plataforma
Una vez creado el proyecto con éxito, hay que añadir la librería Client4SpringBoot. Para ello hay que añadir tanto la dependencia de la librería como el repositorio de donde la vamos a descargar. Todo esto lo ponemos en el 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>Lo siguiente es configurar la conexión con la plataforma. Para ello, abre el archivo 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: INFOEn estas entradas, debes especificar la información que registraste previamente desde el Panel de Control:
onesaitplatform.iotclient.token=4a456739a56646419634136607f6c2a9
onesaitplatform.iotclient.deviceTemplate=IoTSensorClient
onesaitplatform.iotclient.device=IoTSensorClient_instance
Creación de la clase Java que representa tu ontología
El siguiente paso es crear la clase Java que representa tu ontología.
En la carpeta src/main/java crea el paquete com.minsait.onesait.platform.workshop.ontology y crea dos clases dentro de él: AtmSensorOntology y AtmSensor
Lo primero que hay que hacer es añadir la anotación @Data a ambas clases. Esta anotación de Lombok genera automáticamente el get y el set de cada atributo y los métodos hashCode y toString()
Ahora edita la clase AtmSensorOntology para añadir esto:
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;
}Veamos qué significa cada elemento:
La anotación @JsonInclude(JsonInclude.Include.NON_NULL) evita que se devuelvan los atributos si son nulos.
El campo _id representa la identificación interna en la base de datos donde se insertó el elemento, en este caso MongoDB. Si no lo necesitas, puedes decidir no incluirlo, pero nosotros lo hemos hecho aquí.
El campo contextData representa el contexto de inserción proporcionado automáticamente por la Plataforma. Incluye el usuario y la fecha y hora de inserción. Puedes decidir no incluirlo si no lo vas a utilizar.
El campo atmSensor representa realmente la instancia de la ontología, la que veíamos antes. Se mapea con el nombre de la propiedad AtmSensor (Igual que en el JSON)
El siguiente paso es crear los atributos que componen tu ontología. Vamos a recordarlos:
temperature: Número requerido.
humidity: Número requerido.
pressure: Número requerido.
Así que ahora tienes que añadir estas propiedades a la clase AtmSensor de la siguiente manera:
Creación del Repositorio básico para conectar con la Plataforma
Una vez configurada la conexión con la plataforma en el fichero application.yml y la clase que representa la ontología, puedes crear un Repositorio. Veamos cómo:
Crea el paquete com.minsait.onesait.platform.workshop.repository y crea la interfaz AtmSensorRepository y añade la anotación @IoTBrokerRepository("atmSensor_rbarrio") para especificar la ontología sobre la que trabaja el Repositorio.
Ahora, añade los métodos que utiliza tu Repositorio. En este taller vamos a crear las operaciones básicas:
La anotación @IoTBrokerQuery se utiliza para realizar consultas, como recuperar todas las instancias con getAllAtmSensor o contarlas, etc. También se le pueden pasar parámetros, como se puede ver en el método getByTemperatureAtmSensor.
La anotación @IoTBrokerInsert se puede utilizar para insertar un AtmSensor, o una lista de ellos. Como resultado, devuelve un String con su ID.
La anotación @IotBrokerUpdate permite actualizar un AtmSensor enviando, como parámetros, su id (de la base de datos) y su instancia.
La anotación @IoTBrokerDelete permite borrar un AtmSensor por su ID.
Comunicación con la plataforma
Ya tienes todo listo para comunicarte con la plataforma a través de la clase comunicadora:
Crea el paquete com.minsait.onesait.platform.workshop.controller y dentro de él la clase AtmSensorController y anótala con la anotación @Component para que sea un Spring Bean, y con la anotación @Slf4j, que instancia un log SL4J (configurado con logback en la plataforma).
Añade la inyección a tu repositorio:
El siguiente paso es crear un método @PostConstruct (para que se invoque automáticamente una vez cargado el contexto de Spring Boot). En este método vamos a insertar una instancia en la ontología utilizando nuestro repositorio:
Crea la clase WorkshopApp dentro del paquete com.minsait.onesait.platform.workshop y añade las anotaciones SpringBootApplication, EnableAutoConfig y ComponentScan:
Desde Eclipse, ahora puedes lanzar tu proyecto Eclipse simplemente pasando el ratón sobre la clase Application, y seleccionando Debug As > Java Application. Si todo va bien, deberías ver los siguientes registros:
Por último, haz clic en Apply y Run.
Digital Twin - Ejemplo práctico
Un Gemelo Digital, o Digital Twin, puede definirse como un modelo virtual de activos físicos o procesos industriales que aprenden continuamente, proporcionan datos y responden a los cambios realizados en su entorno. El concepto de Digital Twin se utilizó originalmente en entornos de CAD y simulación, pero ahora se utiliza comúnmente en las tecnologías de IoT. Según Gartner, la tecnología Digital Twin será una de las 10 principales tecnologías estratégicas y disruptivas en 2018.
Como se ha dicho antes, un Digital Twin es la representación virtual de un sistema o dispositivo físico. Esta representación está definida por tres elementos
Status (Estado): valor de cada una de sus propiedades, que representa en tiempo real lo que el dispositivo está "haciendo"; por ejemplo, un motor girando a 1800 rpm a una temperatura óptima de trabajo.
Actions (Acciones): acciones u órdenes externas que pueden aplicarse al dispositivo o a las que éste puede responder; por ejemplo, un motor puede apagarse.
Events (Eventos): notificaciones que puede enviar un dispositivo por determinados eventos; por ejemplo, un motor puede enviar un evento de apagado si su temperatura de trabajo supera un valor umbral.
Crear Tipo Gmelo Digital
Ve al Panel de Control de onesait Platform (https://lab.onesaitplatform.com/controlpanel/).
Para crear el Tipo Digital Twin, ve al siguiente menú: Digital Twin ->My Digital Twin Definitions. Una vez allí, podrás empezar a crear tu Tipo Digital Twin pulsando el botón Create.
Da un nombre y una descripción para tu Digital Twin, y recuerda la nomenclatura:
Añade las propiedades de tu turbina: representan el estado del Digital Twin. Son las variables que serán ingeridas y procesadas en la plataforma como una “sombra” del dispositivo.
Añade las acciones: notificaciones y acciones que un Digital Twin recibe de la plataforma.
Añade los eventos: notificaciones y acciones que el Digital Twin envía a la plataforma.
Añade la lógica: la plataforma permite definir qué tipo de lógica ejecutará el Digital Twin. En este ejemplo, la lógica está programada en Javascript. Por defecto, al crear un Digital Twin, se añaden las siguientes funciones:
Init: se ejecuta sólo al registrar el Digital Twin en la plataforma.
Main: ejecuta periódicamente el Digital Twin.
onActionXXX: se creará un método para cada acción definida en la sección Actions, donde podremos definir la lógica que queremos ejecutar cuando el Digital Twin reciba una acción de la plataforma.
Crear un Digital Twin
Una vez creado el Digital Twin Tipo "Sensehat", el siguiente paso es crear una instancia concreta del Digital Twin. Para crear una instancia del Digital Twin, ve al siguiente menú: Digital Twin > My Digital Twins.
Donde:
Digital Twin Type se corresponde con el Tipo de Gemelo Digital que se ha creado previamente y por tanto define la Descripción de la Web Thing. Además, al seleccionar el tipo de Digital Twin, asignamos la lógica definida para este tipo.
URL scheme, interface, port, ContextPath e IPV6: Proporcionan al Digital Twin la información necesaria para inferir su URL y que ésta sea enviada a la plataforma en el mensaje de Registro. Así, la plataforma puede notificar las acciones.
Broker endpoint es la URL donde hay que notificar los eventos de Digital Twin en una plataforma.
DigitalTwinKey es la clave con la que el Digital Twin puede autenticarse frente a la plataforma.
Ejecutar Digital Twin
Una vez que has definido nuestro Digital Twin, la plataforma te permite generar el código correspondiente. En la versión actual de la plataforma, el código se genera en Java.
Para ver el código generado del Digital Twin, ve de nuevo a Digital Twin -> My Digital Twin y selecciona la instancia de Digital Twin ya creada.
Para generar el código, debes seleccionar las siguientes opciones:
Entonces, haz clic en Generate y el proyecto Maven se compilará (Java) y se descargará, listo para ser ejecutado.
Descomprime el zip descargado en el directorio S:\sources y compila el proyecto maven con el comando:
Si todo está bien, deberías ver algo así.
En el directorio target, debería crearse el archivo JAR con la compilación. Ejecútalo con el comando:
Verás los siguientes registros:
Dashboard - Ejemplo práctico
Vamos a crear un sencillo cuadro de mando o dashboard utilizando los datos generados con mi Digital Twin. Es importante recordar que, al crear un Digital Twin, se crea una ontología con el nombre TwinProperties<nombre-tipo-de-mi-digitaltwin>, en nuestro caso "TwinPropertiesTurbine_rbarrio". Por lo tanto, vamos a utilizar esta ontología para crear nuestro dashboard.
Crear la fuente de datos
Para este taller vamos a crear un cuadro de mando que muestre la evolución de la temperatura del Gemelo Digital.
Antes que nada, hay que crear una fuente de datos yendo al menú VISUALIZATION > My Datasources y pulsando el botón "create". Utilizamos la siguiente consulta para crear la fuente de datos:
Crear Gadget
Ve a la opción de menú VISUALIZATION > My Gadgets y haz clic en el botón "Crear Gadget". En primer lugar, debes seleccionar la fuente de datos que has creado en el paso anterior.
Después, puedes seleccionar el tipo de tu gadget. En este taller vamos a crear un gadget de línea:
Ahora puedes configurar tu panel de control:
Crear panel de control
El último paso es crear el cuadro de mando a través de la opción de menú VISUALIZATIONS > My Dashboards y seleccionando el botón "New Dashboard".
Una vez hayas creado el cuadro de mando, verás algo así:
Haz clic en el botón + y selecciona "Line chart".
Selecciona tu gadget y haz clic en "ADD GADGET":