¿Qué son las plantillas de dispositivo?
Una plantilla de dispositivo en Azure IoT Central es un plano técnico que define las características y los comportamientos de un tipo de dispositivo que se conecta a la aplicación. Por ejemplo, la plantilla de dispositivo define la telemetría que un dispositivo envía para que IoT Central pueda crear visualizaciones que usen las unidades y los tipos de datos correctos.
Un generador de soluciones agrega plantillas de dispositivos a una aplicación de IoT Central. Un desarrollador de dispositivos escribe el código del dispositivo que implementa los comportamientos definidos en la plantilla de dispositivo. Para obtener más información sobre los datos que un dispositivo intercambia con IoT Central, consulte Cargas de telemetría, propiedades y comandos.
En una plantilla de dispositivo se incluyen las secciones siguientes:
- Un modelo de dispositivo. Esta parte de la plantilla de dispositivo define cómo interactúa el dispositivo con la aplicación. Cada modelo de dispositivo tiene un identificador único. Un desarrollador de dispositivos implementa los comportamientos definidos en el modelo.
- Componente raíz. Cada modelo de dispositivo tiene un componente raíz. La interfaz del componente raíz describe las funcionalidades que son específicas del modelo de dispositivo.
- Componentes. Un modelo de dispositivo puede incluir componentes además del componente raíz para describir las funcionalidades del dispositivo. Cada componente tiene una interfaz que describe las funcionalidades del componente. Las interfaces de los componentes se pueden reutilizar en otros modelos de dispositivo. Por ejemplo, varios modelos de dispositivos telefónicos podrían usar la misma interfaz de cámara.
- Interfaces heredadas. Un modelo de dispositivo contiene una o más interfaces que amplían las funcionalidades del componente raíz.
- Vistas. Esta parte de la plantilla de dispositivo permite que el desarrollador de soluciones defina visualizaciones para ver los datos del dispositivo y los formularios para administrar y controlar un dispositivo. Las vistas no afectan al código que escribe el desarrollador de dispositivos para implementar el modelo de dispositivo.
Asignación de un dispositivo a una plantilla de dispositivo
Para que un dispositivo interactúe con IoT Central, debe asignarse a una plantilla de dispositivo. Esta asignación se realiza de una de estas cuatro maneras:
- Al registrar un dispositivo en la página Dispositivos, puede identificar la plantilla que debe usar el dispositivo.
- Al importar en bloque una lista de dispositivos, puede elegir la plantilla de dispositivo que deben usar todos los dispositivos de la lista.
- Puede asignar manualmente un dispositivo sin asignar a una plantilla de dispositivo después de conectarse.
- Puede asignar automáticamente un dispositivo a una plantilla de dispositivo enviando un identificador de modelo cuando el dispositivo se conecte por primera vez a la aplicación.
Asignación automática
IoT Central puede asignar automáticamente un dispositivo a una plantilla de dispositivo cuando el dispositivo se conecta. Un dispositivo debe enviar un identificador de modelo cuando se conecta. IoT Central usa el identificador de modelo para identificar la plantilla de dispositivo para ese modelo de dispositivo específico. El proceso de detección funciona de la siguiente manera:
Si la plantilla de dispositivo ya está publicada en la aplicación IoT Central, el dispositivo se le asigna.
Si la plantilla de dispositivo aún no está publicada en la aplicación de IoT Central, éste busca el modelo de dispositivo en el repositorio de modelos de dispositivo público. Si IoT Central encuentra el modelo, lo utiliza para generar una plantilla de dispositivo básica.
Si IoT Central no encuentra el modelo en el repositorio de modelos público, el dispositivo se marca como Sin asignar. Un operador puede:
- Cree una plantilla de dispositivo para el dispositivo y a continuación, migre el dispositivo sin asignar a la nueva plantilla de dispositivo.
- Genere automáticamente una plantilla de dispositivo en función de los datos que envía el dispositivo.
En la captura de pantalla siguiente se muestra cómo ver el identificador de modelo de una plantilla de dispositivo en IoT Central. En una plantilla de dispositivo, seleccione un componente y luego Editar identidad:
Puede ver el modelo de thermostat en el repositorio de modelos públicos. La definición del identificador de modelo tiene este aspecto:
"@id": "dtmi:com:example:Thermostat;1"
Use la siguiente carga de DPS para asignar el dispositivo a una plantilla de dispositivo:
{
"modelId":"dtmi:com:example:TemperatureController;2"
}
Para más información sobre la carga de DPS, consulte el código de ejemplo usado en el Tutorial: Creación y conexión de una aplicación cliente a la aplicación de Azure IoT Central.
Modelos de dispositivos
Un modelo de dispositivo define cómo interactúa un dispositivo con la aplicación de IoT Central. El desarrollador de dispositivos debe asegurarse de que el dispositivo implementa los comportamientos definidos en el modelo de dispositivo para que IoT Central pueda supervisar y administrar el dispositivo. Un modelo de dispositivo se compone de una o varias interfaces, y cada interfaz puede definir una colección de tipos de telemetría, propiedades del dispositivo y comandos. Un desarrollador de soluciones puede:
- Importe un archivo JSON que defina un modelo de dispositivo completo o una interfaz individual en una plantilla de dispositivo.
- Use la interfaz de usuario web de IoT Central para crear o editar un modelo de dispositivo.
Nota:
IoT Central acepta cualquier carga JSON válida de un dispositivo, pero solo puede usar los datos para las visualizaciones si coincide con una definición en el modelo de dispositivo. Puede exportar datos que no coincidan con una definición; para ello, consulte Exportación de datos de IoT a destinos en la nube mediante Blob Storage.
Para más información sobre cómo editar un modelo de dispositivo, consulte Edición de una plantilla de dispositivo existente.
Un desarrollador de soluciones también puede exportar un archivo JSON desde la plantilla de dispositivo que contiene un modelo completo del dispositivo o una interfaz individual. Un desarrollador de dispositivos puede usar este documento JSON para comprender cómo debe comunicarse el dispositivo con la aplicación de IoT Central.
El archivo JSON que define el modelo de dispositivo usa el Lenguaje de definición de gemelos digitales (DTDL) V2. IoT Central espera que el archivo JSON contenga el modelo de dispositivo con las interfaces definidas insertadas, en lugar de en archivos independientes. Los modelos creados en IoT Central tienen el contexto dtmi:iotcentral:context;2 definido para indicar que el modelo se creó en IoT Central:
"@context": [
"dtmi:iotcentral:context;2",
"dtmi:dtdl:context;2"
]
Para más información sobre los modelos DTDL, consulte la guía de modelado IoT Plug and Play.
Nota:
IoT Central define algunas extensiones en el lenguaje DTDL v2. Para más información, consulte extensión de IoT Central.
Propiedades
De forma predeterminada, las propiedades son de solo lectura. Las propiedades de solo lectura significan que el dispositivo informa de las actualizaciones de valores de propiedad a la aplicación de IoT Central. La aplicación de IoT Central no puede establecer el valor de una propiedad de solo lectura.
Una propiedad también se puede marcar como grabable en una interfaz. Un dispositivo puede recibir una actualización de una propiedad grabable de la aplicación de IoT Central y notificar las actualizaciones de valor de propiedad de la aplicación.
No es preciso que los dispositivos estén conectados para establecer los valores de propiedad. Los valores actualizados se transfieren la siguiente vez que el dispositivo se conecta a la aplicación. Este comportamiento se aplica a tanto a las propiedades de solo lectura como a las grabables.
No use las propiedades para enviar datos de telemetría desde un dispositivo. Por ejemplo, una propiedad de solo lectura como mtemperatureSetting=80 debe significar que la temperatura del dispositivo se ha establecido en 80 y que el dispositivo está intentando llegar a esta temperatura o quedarse en ella.
En el caso de las propiedades de escritura, la aplicación de dispositivo devuelve un código de estado deseado, una versión y una descripción para indicar si ha recibido y aplicado el valor de propiedad.
Propiedades de la nube
También puede agregar propiedades en la nube al componente raíz del modelo. Las propiedades de la nube permiten especificar los metadatos del dispositivo que se van a almacenar en la aplicación de IoT Central. Los valores de propiedad en la nube se almacenan en la aplicación de IoT Central y nunca se sincronizan con un dispositivo. Las propiedades de la nube no afectan al código que escribe el desarrollador de dispositivos para implementar el modelo de dispositivo.
Un desarrollador de soluciones puede agregar propiedades de la nube a las vistas y los formularios del dispositivo, junto a las propiedades del dispositivo, para permitir que un operador administre los dispositivos conectados a la aplicación. Un desarrollador de soluciones también puede usar las propiedades de la nube como parte de una definición de regla para que un operador pueda editar un valor de umbral.
El siguiente fragmento de código DTDL muestra una definición de propiedad en la nube de ejemplo:
{
"@id": "dtmi:azureiot:Thermostat:CustomerName",
"@type": [
"Property",
"Cloud",
"StringValue"
],
"displayName": {
"en": "Customer Name"
},
"name": "CustomerName",
"schema": "string"
}
Telemetría
IoT Central le permite ver los datos de telemetría en vistas y gráficos de dispositivos, y usar reglas para desencadenar acciones cuando se alcanzan los umbrales. IoT Central usa la información del modelo de dispositivo, como los tipos de datos, las unidades y los nombres para mostrar, para determinar cómo se muestran los valores de telemetría. También puede mostrar los valores de telemetría en los paneles personales y de la aplicación.
Puede usar la característica de exportación de datos de IoT Central para transmitir la telemetría a otros destinos, como Storage o Event Hubs.
Comandos
Un comando debe ejecutarse en un plazo máximo de 30 segundos de manera predeterminada y el dispositivo debe estar conectado cuando llegue el comando. Si el dispositivo no responde a tiempo o no está conectado, se produce un error en el comando.
Los comandos pueden tener parámetros de solicitud y devolver una respuesta.
Comandos sin conexión
Puede elegir comandos de cola si un dispositivo está sin conexión; para ello, habilite la opción Queue if offline (Poner en cola si no está conectado) en un comando de la plantilla de dispositivo.
Los comandos sin conexión son notificaciones unidireccionales al dispositivo desde la solución. Los comandos sin conexión pueden tener parámetros de solicitud, pero no devuelven una respuesta.
Nota:
Los comandos sin conexión se marcan como durable si exporta el modelo como DTDL.
Los comandos sin conexión usan mensajes de la nube al dispositivo de IoT Hub para enviar el comando y la carga útil al dispositivo.
La carga del mensaje que recibe el dispositivo es el valor sin procesar del parámetro. Una propiedad personalizada denominada method-name almacena el nombre del comando de IoT Central. En la tabla siguiente se muestran algunas cargas de ejemplo:
| Esquema de solicitud de IoT Central | Carga de ejemplo que recibió el dispositivo |
|---|---|
| Sin parámetro de solicitud | @ |
| Doble | 1.23 |
| Cadena | sample string |
| Object | {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2} |
El siguiente fragmento de código de un modelo de dispositivo muestra la definición de un comando. El comando tiene un parámetro object con un campo datetime y una enumeración:
{
"@type": "Command",
"displayName": {
"en": "Generate Diagnostics"
},
"name": "GenerateDiagnostics",
"request": {
"@type": "CommandPayload",
"displayName": {
"en": "Payload"
},
"name": "Payload",
"schema": {
"@type": "Object",
"displayName": {
"en": "Object"
},
"fields": [
{
"displayName": {
"en": "StartTime"
},
"name": "StartTime",
"schema": "dateTime"
},
{
"displayName": {
"en": "Bank"
},
"name": "Bank",
"schema": {
"@type": "Enum",
"displayName": {
"en": "Enum"
},
"enumValues": [
{
"displayName": {
"en": "Bank 1"
},
"enumValue": 1,
"name": "Bank1"
},
{
"displayName": {
"en": "Bank2"
},
"enumValue": 2,
"name": "Bank2"
},
{
"displayName": {
"en": "Bank3"
},
"enumValue": 3,
"name": "Bank3"
}
],
"valueSchema": "integer"
}
}
]
}
}
}
Si habilita la opción Poner en cola si no hay conexión en la interfaz de usuario de la plantilla de dispositivo para el comando del fragmento de código anterior, el mensaje que recibe el dispositivo incluye las siguientes propiedades:
| Nombre de propiedad | Valor de ejemplo |
|---|---|
custom_properties |
{'method-name': 'GenerateDiagnostics'} |
data |
{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2} |
Vistas
Un desarrollador de soluciones crea vistas que permiten a los operadores supervisar y administrar los dispositivos conectados. Las vistas forman parte de la plantilla de dispositivo, por lo que una vista se asocia a un tipo de dispositivo específico. Una vista puede incluir:
- Gráficos para trazar la telemetría.
- Iconos para mostrar las propiedades de un dispositivo de solo lectura.
- Iconos para permitir que el operador edite las propiedades grabables del dispositivo.
- Iconos para permitir que el operador edite las propiedades de la nube.
- Iconos para permitir que el operador llame a comandos, incluidos los comandos que esperan una carga útil.
- Iconos para mostrar etiquetas, imágenes o texto de Markdown.
Pasos siguientes
Ahora que ha aprendido sobre las plantillas de dispositivo, un siguiente paso sugerido es leer Telemetría, propiedad y cargas de comandos para obtener más información sobre los datos que intercambia un dispositivo con IoT Central.