Compartir a través de

Información de Digital Twins de IoT Plug and Play

Un dispositivo IoT Plug and Play implementa un modelo descrito por el esquema del Lenguaje de Definición de Digital Twins (DTDL). Un modelo describe el conjunto de componentes, propiedades, comandos y mensajes de telemetría que puede tener un dispositivo determinado.

Nota:

DTDL no es exclusivo de IoT Plug and Play. Otros servicios de IoT, como Azure Digital Twins, lo usan para representar entornos completos, como edificios y redes energéticas.

Los SDK de servicio IoT de Azure incluyen API que permiten que un servicio interactúe con el gemelo digital de un dispositivo. Por ejemplo, un servicio puede leer las propiedades del dispositivo del gemelo digital o usar el gemelo digital para llamar a un comando en un dispositivo. Para más información, consulte Ejemplos de gemelos digitales de IoT Hub.

El dispositivo IoT Plug and Play de ejemplo de este artículo implementa un modelo de controlador de temperatura que tiene componentes thermostat .

Gemelos de dispositivos y gemelos digitales

Junto con un gemelo digital, Azure IoT Hub también mantiene un dispositivo gemelo para cada dispositivo conectado. Un dispositivo gemelo es similar a un gemelo digital en que es una representación de las propiedades de un dispositivo. Un centro de IoT inicializa un gemelo digital y un dispositivo gemelo la primera vez que se aprovisiona un dispositivo IoT Plug and Play. Los SDK de servicio IoT de Azure incluyen API para interactuar con dispositivos gemelos.

Los dispositivos gemelos son documentos JSON que almacenan información de estado del dispositivo, incluidos metadatos, configuraciones y condiciones. Para más información, consulte Ejemplos de cliente de servicio de IoT Hub. Los generadores de dispositivos y soluciones pueden usar el mismo conjunto de API y SDK de dispositivos gemelos para implementar dispositivos y soluciones mediante convenciones de IoT Plug and Play. En un dispositivo gemelo, el estado de una propiedad grabable se divide en las secciones propiedades deseadas y propiedades notificadas . Todas las propiedades de solo lectura están disponibles en la sección de propiedades notificadas.

Las APIs de gemelo digital operan sobre construcciones DTDL de alto nivel, como componentes, propiedades y comandos, y facilitan a los desarrolladores de soluciones crear soluciones de IoT Plug and Play. En un gemelo digital, hay una vista unificada del estado actual y deseado de la propiedad. El estado de sincronización de una propiedad determinada se almacena en la sección del componente $metadata predeterminado correspondiente.

Ejemplo de dispositivo gemelo JSON

En el fragmento de código siguiente se muestra un dispositivo gemelo IoT Plug and Play con formato de objeto JSON:

{
  "deviceId": "sample-device",
  "modelId": "dtmi:com:example:TemperatureController;1",
  "version": 15,
  "properties": {
    "desired": {
      "thermostat1": {
        "__t": "c",
        "targetTemperature": 21.8
      },
      "$metadata": {...},
      "$version": 4
    },
    "reported": {
      "serialNumber": "alwinexlepaho8329",
      "thermostat1": {
        "maxTempSinceLastReboot": 25.3,
        "__t": "c",
        "targetTemperature": {
          "value": 21.8,
          "ac": 200,
          "ad": "Successfully executed patch",
        }
      },
      "$metadata": {...},
      "$version": 11
    }
  }
}

Ejemplo de gemelo digital

En el fragmento de código siguiente se muestra el gemelo digital con formato de objeto JSON:

{
  "$dtId": "sample-device",
  "serialNumber": "alwinexlepaho8329",
  "thermostat1": {
    "maxTempSinceLastReboot": 25.3,
    "targetTemperature": 21.8,
    "$metadata": {
      "targetTemperature": {
        "desiredValue": 21.8,
        "desiredVersion": 4,
        "ackVersion": 4,
        "ackCode": 200,
        "ackDescription": "Successfully executed patch",
        "lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
      },
      "maxTempSinceLastReboot": {
         "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
      }
    }
  },
  "$metadata": {
    "$model": "dtmi:com:example:TemperatureController;1",
    "serialNumber": {
      "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
    }
  }
}

En la tabla siguiente se describen los campos del objeto JSON del gemelo digital:

Nombre del campo Description
$dtId Cadena proporcionada por el usuario que representa el identificador del gemelo digital del dispositivo.
{propertyName} Valor de una propiedad en JSON.
$metadata.$model [Opcional] Identificador de la interfaz del modelo que caracteriza al gemelo digital.
$metadata.{propertyName}.desiredValue [Solo para propiedades grabables] Valor deseado de la propiedad especificada.
$metadata.{propertyName}.desiredVersion [Solo para propiedades grabables] Versión del valor deseado mantenido por IoT Hub.
$metadata.{propertyName}.ackVersion [Obligatorio, solo para propiedades grabables] La versión reconocida por el dispositivo que implementa el gemelo digital, debe ser mayor o igual a la versión deseada.
$metadata.{propertyName}.ackCode [Obligatorio, solo para propiedades grabables] Código ack devuelto por la aplicación del dispositivo que implementa el gemelo digital.
$metadata.{propertyName}.ackDescription [Opcional, solo para propiedades grabables] Descripción ack devuelta por la aplicación del dispositivo que implementa el gemelo digital.
$metadata.{propertyName}.lastUpdateTime IoT Hub conserva la marca de tiempo de la última actualización de la propiedad por parte del dispositivo. Las marcas de tiempo están en UTC y codificadas según el formato ISO8601 YYYY-MM-DDTHH:MM:SS.mmmZ.
{componentName} Objeto JSON que contiene los metadatos y los valores de propiedad del componente.
{componentName}.{propertyName} Valor de la propiedad del componente en JSON.
{componentName}.$metadata La información de metadatos del componente.

Propiedades

Las propiedades son campos de datos que representan el estado de una entidad igual que las propiedades de muchos lenguajes de programación orientados a objetos.

Propiedad de solo lectura

Esquema DTDL:

{
    "@type": "Property",
    "name": "serialNumber",
    "displayName": "Serial Number",
    "description": "Serial number of the device.",
    "schema": "string"
}

En este ejemplo, alwinexlepaho8329 es el valor actual de la serialNumber propiedad de solo lectura notificada por el dispositivo.

Los fragmentos de código siguientes muestran la representación JSON en paralelo de la serialNumber propiedad :

Dispositivo gemelo

"properties": {
"reported": {
"serialNumber": "alwinexlepaho8329"
}
}

Gemelo digital

"serialNumber": "alwinexlepaho8329"

Propiedad escribible

En los ejemplos siguientes se muestra una propiedad grabable en el componente predeterminado.

DTDL:

{
  "@type": "Property",
  "name": "fanSpeed",
  "displayName": "Fan Speed",
  "writable": true,
  "schema": "double"
}

Dispositivo gemelo

{
"properties": {
"desired": {
"fanSpeed": 2.0,
},
"reported": {
"fanSpeed": {
"value": 3.0,
"ac": 200,
"av": 1,
"ad": "Successfully executed patch version 1"
}
}
},
}

Gemelo digital

{
"fanSpeed": 3.0,
"$metadata": {
"fanSpeed": {
"desiredValue": 2.0,
"desiredVersion": 2,
"ackVersion": 1,
"ackCode": 200,
"ackDescription": "Successfully executed patch version 1",
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

En este ejemplo, 3.0 es el valor actual de la fanSpeed propiedad notificada por el dispositivo. 2.0 es el valor deseado establecido por la solución. El valor deseado y el estado de sincronización de una propiedad de nivel raíz se establecen dentro del elemento $metadata de nivel de raíz para un gemelo digital. Cuando el dispositivo se conecta, puede aplicar esta actualización e informar sobre el valor actualizado.

Componentes

Los componentes permiten crear una interfaz de modelo como un ensamblado de otras interfaces. Por ejemplo, la interfaz Thermostat se puede incorporar como componentes thermostat1 y thermostat2 en el modelo de controlador de temperatura.

En un dispositivo gemelo, el { "__t": "c"} marcador identifica un componente. En un gemelo digital, la presencia de $metadata marca un componente.

En este ejemplo, thermostat1 es un componente con dos propiedades:

  • maxTempSinceLastReboot es una propiedad de solo lectura.
  • targetTemperature es una propiedad grabable que el dispositivo sincronizó correctamente. El valor deseado y el estado de sincronización de estas propiedades se encuentran en el componente $metadata.

Los fragmentos de código siguientes muestran la representación JSON en paralelo del thermostat1 componente:

Dispositivo gemelo

"properties": {
"desired": {
"thermostat1": {
"__t": "c",
"targetTemperature": 21.8
},
"$metadata": {
},
"$version": 4
},
"reported": {
"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"__t": "c",
"targetTemperature": {
"value": 21.8,
"ac": 200,
"ad": "Successfully executed patch",
"av": 4
}
},
"$metadata": {
},
"$version": 11
}
}

Gemelo digital

"thermostat1": {
"maxTempSinceLastReboot": 25.3,
"targetTemperature": 21.8,
"$metadata": {
"targetTemperature": {
"desiredValue": 21.8,
"desiredVersion": 4,
"ackVersion": 4,
"ackCode": 200,
"ackDescription": "Successfully executed patch",
"lastUpdateTime": "2020-07-17T06:11:04.9309159Z"
},
"maxTempSinceLastReboot": {
"lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
}
}
}

API de gemelo digital

Las API de gemelo digital incluyen las operaciones Get Digital Twin, Update Digital Twin, Invoke Component Command e Invoke Command para administrar un gemelo digital. Puede usar las API REST directamente o bien a través de alguno de los SDK de servicio.

Eventos de cambio de gemelo digital

Cuando se habilitan los eventos de cambio de gemelo digital, se desencadena un evento cada vez que cambia el valor actual o el deseado del componente o propiedad. Los eventos de cambio de gemelo digital se generan en formato de revisión de JSON. Los eventos correspondientes se generan en el formato del dispositivo gemelo si se habilitan los eventos de cambio de gemelo.

Para aprender cómo habilitar el enrutamiento para eventos de dispositivos y gemelos digitales, consulte Uso del enrutamiento de mensajes de IoT Hub para enviar mensajes de dispositivo a la nube a diferentes puntos de conexión. Para comprender el formato de mensaje, consulte Creación y lectura de mensajes de IoT Hub.

Por ejemplo, el siguiente evento de cambio de gemelo digital se desencadena cuando la solución establece un valor de targetTemperature:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:04 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d463fa034
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature",
    "value": {
      "desiredValue": 21.8,
      "desiredVersion": 4
    }
  }
]

Se desencadena el evento de cambio de gemelo digital siguiente cuando el dispositivo informa de que se ha aplicado el cambio deseado anterior:

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/17/2020 6:11:05 AM
iothub-message-source:digitalTwinChangeEvents
correlation-id:275d464a2c80
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackCode",
    "value": 200
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackDescription",
    "value": "Successfully executed patch"
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/ackVersion",
    "value": 4
  },
  {
    "op": "add",
    "path": "/thermostat1/$metadata/targetTemperature/lastUpdateTime",
    "value": "2020-07-17T06:11:04.9309159Z"
  },
  {
    "op": "add",
    "path": "/thermostat1/targetTemperature",
    "value": 21.8
  }
]

Nota:

Los mensajes de notificación de cambios de gemelo se duplican cuando se activan en la notificación de cambio de dispositivo y de gemelo digital.

  • Last updated on