Descripción de la cosa

La descripción de cosa (TD) (o descripción de cosa W3C WoT (TD) ) es un modelo de información abierto y libre de regalías con un formato de representación basado en JSON para la Internet de las cosas (IoT). Una TD proporciona una forma unificada de describir las capacidades de un dispositivo o servicio de IoT con su modelo de datos y funciones ofrecidos, uso de protocolo y otros metadatos. El uso de descripciones de cosas ayuda a reducir la complejidad de la integración de dispositivos de IoT y sus capacidades en aplicaciones de IoT. ^[1]

La TD se originó a partir de la iniciativa Web of Things (WoT) de la organización de estándares internacionales del W3C que tiene la intención de aumentar la interoperabilidad en el IoT. ^[2] Desde abril de 2020, la Descripción de cosa ^[3] es una recomendación del W3C (W3C WoT Thing Description 1.0).

En diciembre de 2023, el W3C publicó la versión 1.1 de la recomendación de descripción de cosas. ^[4]

El principio principal de la descripción de cosa es proporcionar una descripción de interfaz legible para humanos e interpretable por máquina de un dispositivo/cosa de IoT. En ese contexto, la descripción de cosa de WoT es para IoT lo que index.html es para un sitio web: puede considerarse como el punto de entrada de una cosa/dispositivo físico o virtual . ^[5] La descripción de cosa no se limita a un protocolo de comunicación específico, sino que proporciona un marco llamado plantilla de enlace de WoT. ^[6] Dicho enlace de protocolo define el mapeo de una capacidad de interacción a mensajes concretos de un protocolo de IoT específico como MQTT , HTTP , CoAP , Modbus u OPC UA .

La descripción de WoT Thing define 3 tipos de posibilidades de interacción, denominadas Propiedad, Acción y Evento:

Una capacidad de interacción que expone el estado de un dispositivo IoT. Este estado se puede recuperar (leer) y, opcionalmente, actualizar (escribir). Los dispositivos también pueden optar por hacer que las propiedades sean observables al enviar el nuevo estado después de un cambio.

Una capacidad de interacción que permite invocar una función de un dispositivo IoT, que manipula el estado (por ejemplo, encender o apagar una lámpara) o activa un proceso en el dispositivo (por ejemplo, atenuar una lámpara con el tiempo).

Una capacidad de interacción que describe una fuente de evento, que envía de forma asincrónica datos de evento a los suscriptores del evento (por ejemplo, alertas de sobrecalentamiento).

En general, la descripción de la cosa está diseñada para reutilizarse y confiar en los estándares establecidos de Internet y la Web, esto incluye:

• Serialización: La serialización JSON del modelo de información de TD está alineada con la sintaxis de JSON-LD 1.1. ^[7] JSON-LD abre la oportunidad de ampliar el contexto y enriquecer las instancias de Thing Description con semántica adicional (por ejemplo, específica del dominio) como la de Schema.org . Esto también respalda la extracción y la comprensión de información relevante, como en escenarios de descubrimiento en aplicaciones de IoT ^[8]
• Seguridad: La descripción de la cosa viene con un marco que permite proporcionar metadatos para seguir el esquema de seguridad existente, como OAuth2 o Digest Access Authentication. ^[9] Debido al concepto de extensión de contexto de la descripción de la cosa, se pueden importar esquemas de seguridad específicos.
• Enlaces: Las cosas pueden tener referencias a otras cosas o pueden querer enlazarse a información adicional. Para definir este tipo de relaciones, la descripción de la cosa se basa en el conocido concepto de enlaces web ^[10] .
• Interacciones: Los datos y/o funciones ofrecidos de una Cosa se asignan a las Propiedades, Acciones y Eventos de interacción correspondientes.
• Esquema de datos: para modelar los datos de la cosa que se pueden intercambiar, el concepto de esquema JSON ^[11] está integrado en la descripción de la cosa.
• Enlaces: Las plantillas de enlaces definen el protocolo específico y el método de serialización para las propiedades, acciones y eventos de la Cosa. Como método de identificación y direccionamiento del protocolo se utiliza el Identificador URI ^[12] . Para anunciar la codificación de serialización (por ejemplo, JSON , CBOR , XML , Efficient XML Interchange ) de la carga útil que se especifica mediante el esquema de datos, se aplica la asignación de Tipo de medio ^{[13] en la Descripción de la Cosa.}

A continuación se muestra un ejemplo de TD serializado en formato JSON-LD, que tiene una propiedad, una acción y un evento. El dispositivo IoT representado por este TD utiliza el protocolo HTTP, pero un TD puede representar cualquier protocolo con un esquema URI , como se muestra en el siguiente ejemplo.

{
    "@contexto" : "https://www.w3.org/2019/wot/td/v1" , 
    "id" : "urn:dev:ops:32473-WoTLamp-1234" , 
    "título" : "MiLámpara" , 
    "definicionesdeseguridad" : { 
        "basic_sc" : { "esquema" : "básico" , "en" : "encabezado" }   
    },
    "seguridad" : [ "basic_sc" ], 
    "propiedades" : { 
        "estado" : {  
            "tipo" : "cadena" , 
            "formas" : [{ 
                "href" : "https://milampara.ejemplo.com/estado" , 
                "htv:nombreMétodo" : "OBTENER"
            }]
        }
    },
    "acciones" : { 
        "alternar" : {  
            "formas" : [{ 
                "href" : "https://milampara.ejemplo.com/toggle" , 
                "htv:nombreMétodo" : "POST"
            }]
        }
    },
    "eventos" :{
        "sobrecalentamiento" :{
            "datos" : { "tipo" : "cadena" },  
            "formas" : [{ 
                "href" : "https://milampara.ejemplo.com/oh" , 
                "htv:nombreMétodo" : "OBTENER" ,
                "subprotocolo" : "longpoll" 
            }]
        }
    }
}

Este TD representa una lámpara conectada a Internet, que podría considerarse una versión simple de una lámpara Philips Hue .

A partir de este ejemplo de TD, un cliente sabe que existe una propiedad con el estado del título (líneas 10-16). Además, se proporciona información en las líneas 13-14 de que esta propiedad se puede leer con una solicitud HTTP GET a la URI https://mylamp.example.com/status y devolverá un valor de estado basado en cadena. De manera similar, se especifica una propiedad Action para alternar el estado del interruptor utilizando el método POST en el https://mylamp.example.com/togglerecurso. La propiedad Event permite un mecanismo para que un objeto envíe mensajes asincrónicos. Aquí, se puede obtener una suscripción para recibir una notificación sobre un posible evento de sobrecalentamiento de la lámpara utilizando HTTP con su subprotocolo de sondeo largo en https://mylamp.example.com/oh. El uso del método GET o POST se indica explícitamente, pero se puede omitir utilizando las suposiciones predeterminadas establecidas en la especificación de TD. Se puede ver que los métodos HTTP se definen utilizando los "htv:methodName"términos del vocabulario. Estos términos del vocabulario para HTTP se incluyen en el vocabulario de TD que se encuentra en el "@context"valor.

Este ejemplo también especifica el basicesquema de seguridad, que requiere un nombre de usuario y una contraseña para acceder. A un esquema de seguridad se le asigna primero un nombre y su esquema correspondiente en el securityDefinitionsy luego se activa especificando ese nombre en una securitysección. En combinación con el uso de HTTP, este ejemplo demuestra el uso de la autenticación de acceso básica .

A continuación se muestra la misma lámpara conectada pero utilizando el protocolo MQTT y sin seguridad.

{
    "@contexto" : [ 
        "https://www.w3.org/2019/wot/td/v1" ,
        { "mqv" : "http://www.example.org/mqtt-binding#" } 
    ],
    "id" : "urn:dev:ops:32473-WoTLamp-1234" , 
    "título" : "MiLámpara" , 
    "definicionesdeseguridad" : { 
        "nosec_sc" : { "esquema" : "nosec" }  
    },
    "seguridad" : [ "nosec_sc" ], 
    "propiedades" : { 
        "estado" : {  
            "tipo" : "cadena" , 
            "formas" : [{ 
                "href" : "mqtt://milampara.ejemplo.com/estado" , 
                "mqv:controlPacketValue" : "SUSCRÍBETE" 
            }]
        }
    },
    "acciones" : { 
        "alternar" : {  
            "formas" : [{ 
                "href" : "mqtt://milampara.ejemplo.com/toggle" , 
                "mqv:controlPacketValue" : "PUBLICAR" 
            }]
        }
    },
    "eventos" :{
        "sobrecalentamiento" :{
            "datos" : { "tipo" : "cadena" },  
            "formas" : [{ 
                "href" : "mqtt://milampara.ejemplo.com/oh" , 
                "mqv:controlPacketValue" : "SUSCRÍBETE" 
            }]
        }
    }
}

A diferencia del último TD, aquí los formularios incluyen el protocolo MQTT tal como se especifica en las plantillas de enlace de WoT. Más específicamente, las líneas 17, 25 y 34 describen qué tipos de mensajes se deben usar para usar las posibilidades. Por ejemplo, en lugar de HTTP GET y el subprotocolo longpoll para observar el evento de sobrecalentamiento, un cliente puede suscribirse a este evento utilizando el protocolo MQTT. Además, un dispositivo WoT con protocolo MQTT puede ser tanto un publicador como un suscriptor. Para las posibilidades de propiedad y evento, publicaría los valores, mientras que para las posibilidades de acción se suscribiría a los temas de acción que otros publicadores MQTT pueden activar al publicar en estos temas.

Herramientas de edición y validación de descripciones de cosas

• Eclipse edi{TD}or: ^[14] Una herramienta para diseñar de forma sencilla descripciones y modelos de cosas W3C
• TD Playground: ^[15] Área de juegos para la validación de instancias de descripción de cosas

Implementaciones que utilizan Thing Description

• Eclipse node-wot: ^[16] Una implementación de las tecnologías WoT de W3C en Node.js
• WoTify: ^[17] Una biblioteca de implementación de WoT que admite una descripción de cosa
• wot-py: ^[18] Una implementación de las tecnologías WoT del W3C en Python
• Node-RED node-gen: ^[19] Genera nodos basados ​​en una descripción de cosa en Node-RED
• SANE: ^[20] Una implementación de las tecnologías WoT del W3C en Java

• La red de las cosas
• Gemelo digital
• Especificación OpenAPI