Información de Digital Twins de IoT Plug and Play

  • Artículo

Un dispositivo IoT Plug and Play implementa un modelo descrito por el esquema de Lenguaje de definición de Digital Twins (DTDL). Un modelo describe el conjunto de componentes, las propiedades, los comandos y los 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 servicios 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 obtener 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 con componentes de termostato.

Dispositivo gemelos 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, ya 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 un dispositivo IoT Plug and Play se aprovisiona. Los SDK de servicios IoT de Azure incluyen API para interactuar con dispositivos gemelos.

Los dispositivos gemelos son documentos JSON que almacenan información acerca del estado del dispositivo, incluidos metadatos, configuraciones y condiciones. Para obtener 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 dispositivo gemelo para implementar dispositivos y soluciones con las convenciones de IoT Plug and Play. En un dispositivo gemelo, el estado de una propiedad grabable se divide entre las secciones propiedades deseadas y propiedades notificadas. Todas las propiedades de solo lectura están disponibles en la sección de propiedades notificadas.

Las API de gemelos digitales funcionan en construcciones DTDL de alto nivel, como componentes, propiedades y comandos, y facilitan a los generadores de soluciones la creación de soluciones 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 $metadata del componente predeterminado.

Ejemplo de JSON de dispositivo gemelo

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 un 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 siguiente tabla se describen los campos del objeto JSON del gemelo digital:

Nombre del campo Descripción
$dtId Cadena proporcionada por el usuario que representa el identificador del gemelo digital.
{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 que IoT Hub mantiene.
$metadata.{propertyName}.ackVersion [Obligatorio, solo para propiedades grabables] Versión confirmada por el dispositivo que implementa el gemelo digital, debe ser mayor o igual que 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 formato UTC y se codifican con el formato ISO8601 AAAA-MM-DDTHH:MM:SS.mmmZ.
{componentName} Objeto JSON que contiene los valores de propiedad y los metadatos del componente.
{componentName}.{propertyName} Valor de la propiedad del componente en formato JSON.
{componentName}.$metadata Información de metadatos del componente.

Propiedades

Las propiedades son campos de datos que representan el estado de una entidad (como 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 propiedad de solo lectura serialNumber que el dispositivo indica.

En los fragmentos de código siguientes se muestra la representación JSON en paralelo de la propiedad serialNumber:

Dispositivo gemelo

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

Gemelo digital

"serialNumber": "alwinexlepaho8329"

Propiedad grabable

En los siguientes ejemplos 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 propiedad fanSpeed que el dispositivo indica. 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 está en línea, puede aplicar esta actualización e informar del valor actualizado.

Componentes

Los componentes permiten compilar una interfaz del modelo como un ensamblado de otras interfaces. Por ejemplo, la interfaz de termostato puede incorporarse como componentes thermostat1 y thermostat2 en el modelo de controlador de temperatura.

En un dispositivo gemelo, un componente se identifica mediante el marcador { "__t": "c"}. 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 ha sincronizado correctamente. El valor deseado y el estado de sincronización de estas propiedades se encuentran en el elemento $metadata del componente.

En los fragmentos de código siguientes se muestra la representación JSON en paralelo del componente thermostat1:

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 Obtener gemelo digital, Actualizar gemelo digital, Invocar comando de componente e Invocar comando para administrar un gemelo digital. Puede usar las API rest directamente o a través de uno 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 información sobre cómo habilitar el enrutamiento para eventos de dispositivo digital y de gemelo digital, consulte Uso del enrutamiento de mensajes de IoT Hub para enviar mensajes del dispositivo a la nube a distintos puntos de conexión. Para comprender el formato de los mensajes, consulte Creación y lectura de mensajes de IoT Hub.

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

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.

Pasos siguientes

Ahora que ha aprendido acerca de los gemelos digitales, estos son algunos recursos adicionales: