Examen de la configuración de dispositivos mediante dispositivos gemelos en Azure IoT Hub

  • 6 minutos

La capacidad de configurar dispositivos desde el servicio back-end es un componente principal de la mayoría de las soluciones de administración de dispositivos.

Para sincronizar la información de estado entre un dispositivo y un centro de IoT, use dispositivos gemelos. Un dispositivo gemelo es un documento JSON asociado a un dispositivo específico y almacenado por IoT Hub en la nube donde puede consultarlo. Un dispositivo gemelo contiene la siguiente información:

  • Una propiedad deseada se establece mediante una aplicación back-end y se lee mediante un dispositivo.
  • Una propiedad notificada la establece un dispositivo y la lee una aplicación back-end.
  • Una etiqueta que se establece mediante una aplicación back-end y nunca se envía al dispositivo. Use etiquetas para organizar los dispositivos. Por ejemplo, una etiqueta puede contener una ubicación o categoría del dispositivo. Puede asignar más de una etiqueta por dispositivo.

Diagram that shows the device twin properties used to synchronize state information between a device and an IoT hub.

Propiedades del dispositivo gemelo

Tenga en cuenta la siguiente sección properties de un documento de dispositivo gemelo:

  "properties": {
      "desired": {
          "telemetryConfig": {
              "sendFrequency": "5m"
          },
          "$metadata" : {...},
          "$version": 1
      },
      "reported": {
          "telemetryConfig": {
              "sendFrequency": "5m",
              "status": "success"
          },
          "$metadata" : {...},
          "$version": 4
      }
  }

En este ejemplo, el back-end de la solución y la aplicación del dispositivo usan las propiedades deseadas y notificadas del dispositivo gemelo telemetryConfig para sincronizar la configuración de telemetría de este dispositivo. Se podría implementar una actualización de la configuración del dispositivo de la siguiente manera:

  1. El back-end de la solución establece la propiedad desired con el valor de configuración deseado.
  2. La aplicación de dispositivo recibe una notificación del cambio inmediatamente si está conectado, o en cuanto vuelva a conectarse. Después, la aplicación de dispositivo notifica la configuración actualizada (o una condición de error mediante la propiedad status.
  3. El back-end de la solución puede realizar un seguimiento de los resultados de la operación de configuración en varios dispositivos; para ello, consulta los dispositivos gemelos.

Operaciones de back-end

Para trabajar en el back-end de la solución, el dispositivo gemelo usa las siguientes operaciones atómicas expuestas mediante HTTPS:

  • Recuperación del dispositivo gemelo por el identificador. Esta operación devuelve el documento del dispositivo gemelo, incluidas las etiquetas y las propiedades del sistema, deseadas y notificadas.

  • Actualización parcial de los dispositivos gemelos. Esta operación permite que el back-end de la solución actualice parcialmente las etiquetas o las propiedades deseadas del dispositivo gemelo. La actualización parcial se expresa como un documento JSON que agrega o actualiza cualquier propiedad. Las propiedades establecidas en null se quitan. El ejemplo siguiente crea una nueva propiedad deseada con el valor {"newProperty": "newValue"}, sobrescribe el valor existente de existingProperty con "otherNewValue", y quita otherOldProperty. No se realiza ningún cambio en otras etiquetas o propiedades deseadas existentes:

      {
    "properties": {
        "desired": {
            "newProperty": {
                "nestedProperty": "newValue"
            },
            "existingProperty": "otherNewValue",
            "otherOldProperty": null
        }
    }
  }

  • Reemplazar propiedades deseadas. Esta operación permite que el back-end de la solución sobrescriba completamente todas las propiedades deseadas y sustituya un nuevo documento JSON para properties/desired.

  • Reemplazar etiquetas. Esta operación permite que el back-end de la solución sobrescriba completamente todas las etiquetas y sustituya un nuevo documento JSON para tags.

  • Recibir notificaciones gemelas. Esta operación permite que el back-end de la solución reciba una notificación cuando se modifique la gemela. Para ello, la solución de IoT debe crear una ruta y establecer el origen de datos igual a twinChangeEvents. De manera predeterminada, no existe tal ruta, por tanto, no se envían notificaciones gemelas. Si la tasa de cambio es demasiado alta, o por otras razones, como errores internos, IoT Hub podría enviar una sola notificación que contiene todos los cambios. Por lo tanto, si la aplicación necesita registro y auditoría confiables de todos los estados intermedios, debe usar mensajes del dispositivo a la nube. El mensaje de notificaciones gemelas incluye propiedades y el cuerpo.

    • Propiedades. Las propiedades de un mensaje de notificación de gemelo se muestran en la tabla siguiente. Las propiedades del sistema de mensajes tienen como prefijo el símbolo $.

      Nombre

      Valor

      $content-type

      application/json

      $iothub-enqueuedtime

      Fecha y hora en que se envió la notificación.

      $iothub-message-source

      twinChangeEvents

      $content-encoding

      utf-8

      deviceId

      Identificador del dispositivo.

      hubName

      Nombre del IoT Hub que generó el evento.

      operationTimestamp

      Marca de tiempo ISO8601 de la operación.

      iothub-message-schema

      Esquema de mensaje asociado a la categoría de evento; por ejemplo, deviceLifecycleNotification.

      moduleId

      Id. de módulo. Esta propiedad solo se genera para el ciclo de vida del módulo y eventos de cambio de gemelo.

      opType

      "replaceTwin" o "updateTwin"

    • Cuerpo. Esta sección de un mensaje de notificación de gemelo incluye todos los cambios en el gemelo en formato JSON. Usa el mismo formato que una revisión, con la diferencia de que puede contener todas las secciones gemelas: tags, properties.reported, properties.desired y contiene los elementos $metadata.

Además de estas operaciones, el back-end de soluciones puede hacer lo siguiente:

  • Consultar los dispositivos gemelos mediante el lenguaje de consultas de IoT Hub del tipo SQL.
  • Realizar operaciones en conjuntos grandes de dispositivos gemelos usando trabajos.

Operaciones de dispositivo

La aplicación de dispositivo aplica las siguientes operaciones atómicas en el dispositivo gemelo:

  • Recuperación del dispositivo gemelo. Esta operación devuelve el documento del dispositivo gemelo (incluidas las propiedades del sistema deseadas y notificadas) para el dispositivo conectado actualmente.

    Nota:

    Las etiquetas no son visibles para las aplicaciones de dispositivo.

  • Actualizar parcialmente propiedades notificadas. Esta operación permite la actualización parcial de las propiedades notificadas del dispositivo conectado actualmente. Esta operación usa el mismo formato de actualización JSON que el back-end de la solución usa para una actualización parcial de propiedades deseadas.
  • Observar las propiedades deseadas. El dispositivo conectado actualmente puede elegir recibir notificaciones de las actualizaciones de las propiedades deseadas cuando se produzcan. El dispositivo recibe la misma forma de actualización (sustitución parcial o completa) ejecutada por el back-end de la solución.

Todas las operaciones anteriores requieren el permiso de DeviceConnect.

Los SDK de dispositivo de Azure IoT Hub facilitan el uso de las operaciones anteriores de muchos lenguajes y plataformas.

Metadatos de dispositivo gemelo

IoT Hub conserva la marca de tiempo de la última actualización para cada objeto JSON en las propiedades deseadas y notificadas del dispositivo gemelo. Las marcas de tiempo están en formato UTC y se codifican con el formato ISO8601YYYY-MM-DDTHH:MM:SS.mmmZ.

Por ejemplo:

  "properties": {
      "desired": {
          "telemetryConfig": {
              "sendFrequency": "5m"
          },
          "$metadata": {
              "telemetryConfig": {
                  "sendFrequency": {
                      "$lastUpdated": "2019-08-30T16:24:48.789Z"
                  },
                  "$lastUpdated": "2019-08-30T16:24:48.789Z"
              },
              "$lastUpdated": "2019-08-30T16:24:48.789Z"
          },
          "$version": 23
      },
      "reported": {
          "telemetryConfig": {
              "sendFrequency": "5m",
              "status": "success"
          },
          "batteryLevel": "55%",
          "$metadata": {
              "telemetryConfig": {
                  "sendFrequency": "5m",
                  "status": {
                      "$lastUpdated": "2019-08-31T16:35:48.789Z"
                  },
                  "$lastUpdated": "2019-08-31T16:35:48.789Z"
              },
              "$lastUpdated": "2019-08-31T16:35:48.789Z"
          },
          "$version": 123
      }
  }

Esta información se conserva en todo los niveles (no solo en las hojas de la estructura JSON) para conservar las actualizaciones que quitan las claves de objeto.

Simultaneidad optimista

Tanto las etiquetas como las propiedades deseadas y notificadas admiten la simultaneidad optimista. Las etiquetas tienen una ETag, según la norma RFC7232, que es la representación JSON de la etiqueta. Puede usar ETags en operaciones de actualización condicional desde el back-end de la solución para garantizar la coherencia.

Las propiedades deseadas y notificadas del dispositivo gemelo no tienen etiquetas de entidad, pero tienen un valor $version que se garantiza que sea incremental. De forma similar a una ETag, la parte que realiza la actualización puede usar la versión para garantizar la coherencia de las actualizaciones. Por ejemplo, una aplicación de dispositivo para una propiedad notificada o la solución de back-end para una propiedad deseada.

Las versiones también son útiles cuando un agente de observación (por ejemplo, la aplicación de dispositivo que observa las propiedades deseadas) tiene que conciliar las carreras entre el resultado de una operación de recuperación y una notificación de actualización.

Flujo de reconexión de dispositivos

IoT Hub no conserva las notificaciones de actualización de las propiedades deseadas para los dispositivos desconectados. Se supone que un dispositivo que se está conectando debe recuperar el documento con todas las propiedades deseadas, además de suscribirse a las notificaciones de actualización. Dada la posibilidad de carreras entre las notificaciones de actualización y la recuperación completa, se debe asegurar el flujo siguiente:

  • La aplicación de dispositivo se conecta a un centro de IoT.
  • La aplicación de dispositivo se suscribe a las notificaciones de actualización de las propiedades deseadas.
  • La aplicación de dispositivo recupera el documento completo de las propiedades deseadas.

La aplicación de dispositivo puede pasar por alto todas las notificaciones cuyo valor de $version sea anterior o igual a la versión del documento completo recuperado. Este enfoque es posible porque IoT Hub garantiza que las versiones siempre se incrementan.

Nota:

Esta lógica ya está implementada en los SDK de dispositivo de Azure IoT Hub. Esta descripción es útil solo si la aplicación del dispositivo no puede usar ninguno de los SDK de dispositivos de IoT de Azure y debe programar directamente la interfaz MQTT.