Introducción a los dispositivos gemelos (Python)

Artículo
03/18/2023

Los dispositivos gemelos son documentos JSON que almacenan información acerca del estado del dispositivo, incluidos metadatos, configuraciones y condiciones. IoT Hub conserva un dispositivo gemelo por cada dispositivo que se conecta a él.

Nota

Las características descritas en este artículo solo están disponibles en el nivel estándar de IoT Hub. Para obtener más información sobre los niveles Básico y Estándar o Gratis de IoT Hub, consulte Elección del nivel adecuado de IoT Hub para la solución.

Use los dispositivos gemelos para:

Almacenar metadatos del dispositivo desde el back-end de la solución.
Notificar la información sobre el estado actual, como las funcionalidades y las condiciones disponibles (por ejemplo, el método de conectividad usado) de la aplicación del dispositivo.
Sincronizar el estado de flujos de trabajo de larga duración (como las actualizaciones del firmware y de la configuración) entre la aplicación del dispositivo y la del back-end.
Consultar los metadatos, la configuración o el estado del dispositivo.

Los dispositivos gemelos están diseñados para la sincronización y para consultar las condiciones y configuraciones del dispositivo. Para obtener más información sobre los dispositivos gemelos, incluyendo cuándo usarlos, consulte Comprenda los dispositivos gemelos.

Los centros de IoT almacenan dispositivos gemelos, que contienen los siguientes elementos:

Etiquetas. Metadatos de dispositivo a los que solo puede acceder el back-end de la solución.
Propiedades deseadas. Objetos JSON que puede modificar el back-end de la solución y puede observar la aplicación del dispositivo.
Propiedades notificadas. Objetos JSON que puede modificar la aplicación del dispositivo y que puede leer el back-end de la solución.

Las etiquetas y las propiedades no pueden contener matrices, pero pueden contener objetos anidados.

En la ilustración siguiente se muestra la organización del dispositivo gemelo:

Captura de pantalla de un diagrama de concepto de dispositivo gemelo.

Además, el back-end de la solución puede consultar los dispositivos gemelos en función de todos los datos descritos anteriormente. Para obtener más información acerca de los dispositivos gemelos, consulte Introducción a los dispositivos gemelos. Para más información sobre la consulta, consulte Lenguaje de consulta de IoT Hub.

En este artículo aprenderá a:

Use una aplicación de dispositivo simulado para notificar su canal de conectividad como propiedad notificada en el dispositivo gemelo.
Consultar dispositivos desde la aplicación de back-end mediante filtros en las etiquetas y propiedades que se han creado anteriormente.

En este artículo, creará dos aplicaciones de consola de Python:

AddTagsAndQuery.py: una aplicación de back-end que agrega etiquetas y consulta dispositivos gemelos.
ReportConnectivity.py: una aplicación de dispositivo simulado que se conecta al centro de IoT y notifica su condición de conectividad.

Nota

Para más información sobre las herramientas de SDK disponibles para compilar aplicaciones de dispositivo y back-end, consulte SDK de Azure IoT.

Requisitos previos

Una cuenta de Azure activa. (En caso de no tener ninguna, puede crear una cuenta gratuita en tan solo unos minutos).
Una instancia de IoT Hub. Cree uno con la CLI o el Azure Portal.
Dispositivo registrado. Registre uno en el Azure Portal.
Se recomienda usar Python versión 3.7 o posterior. Asegúrese de usar la instalación de 32 bits o 64 bits en función del programa de instalación. Cuando se le solicite durante la instalación, asegúrese de agregar Python a la variable de entorno específica de la plataforma.
Asegúrese de que el puerto 8883 está abierto en el firewall. En el ejemplo de dispositivo de este artículo se usa el protocolo MQTT, que se comunica mediante el puerto 8883. Este puerto puede estar bloqueado en algunos entornos de red corporativos y educativos. Para más información y para saber cómo solucionar este problema, consulte el artículo sobre la conexión a IoT Hub (MQTT).

Obtención de la cadena de conexión de IoT Hub

En este artículo, se crea un servicio back-end que agrega propiedades deseadas a un dispositivo gemelo y luego consulta el registro de identidades para buscar todos los dispositivos con propiedades notificadas que se han actualizado en consecuencia. El servicio necesita el permiso Conectar al servicio para modificar las propiedades deseadas de un dispositivo gemelo y el permiso Lectura del Registro para consultar el registro de identidades. No hay ninguna directiva de acceso compartido predeterminada que contenga solo estos dos permisos, por lo que tendrá que crearla.

Para crear una directiva de acceso compartido que conceda los permisos Conexión del servicio y Lectura del Registro, y obtenga una cadena de conexión para esta directiva, siga estos pasos:

En Azure Portal, seleccione Grupos de recursos. Seleccione el grupo de recursos donde se encuentra el centro y, a continuación, seleccione el centro en la lista de recursos.
En el panel de la izquierda del centro, seleccione Directivas de acceso compartido.
En el menú superior situado encima de la lista de directivas, seleccione Agregar una directiva de acceso compartida.
En el panelAgregar una directiva de acceso compartida de la derecha, escriba un nombre descriptivo para la directiva, por ejemplo serviceAndRegistryRead. En Permisos, seleccione Lectura del Registro y Conexión del servicio, y después seleccione Agregar.
Seleccione la directiva nueva en la lista de directivas.
Seleccione el icono de copia para Cadena de conexión principal y guarde el valor.

Para obtener más información sobre las directivas de acceso compartido y los permisos de IoT Hub, consulte Permisos y control del acceso.

Creación de una aplicación de servicio que actualiza las propiedades deseadas y consulta gemelos

En esta sección, creará una aplicación de consola de Python que agrega metadatos de ubicación al dispositivo gemelo asociado con {Device ID}. La aplicación consulta el centro de IoT para los dispositivos que se encuentran en Estados Unidos y, después, consulta los dispositivos que notifican una conexión de red de telefonía móvil.

En el directorio de trabajo, abra un símbolo del sistema e instale el SDK del servicio Azure IoT Hub para Python.
```
pip install azure-iot-hub
```
Con un editor de texto, cree un nuevo archivo AddTagsAndQuery.py.

Agregue el código siguiente para importar los módulos necesarios desde el SDK del servicio:

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

Agregue el código siguiente: Reemplace [IoTHub Connection String] por la cadena de conexión de IoT Hub que copió en Obtención de la cadena de conexión de IoT Hub. Reemplace [Device Id] por el identificador de dispositivo (el nombre) del dispositivo registrado en IoT Hub.
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

Agregue el código siguiente al archivo AddTagsAndQuery.py:

def iothub_service_sample_run():
    try:
        iothub_registry_manager = IoTHubRegistryManager(IOTHUB_CONNECTION_STRING)

        new_tags = {
                'location' : {
                    'region' : 'US',
                    'plant' : 'Redmond43'
                }
            }

        twin = iothub_registry_manager.get_twin(DEVICE_ID)
        twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
        twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

        # Add a delay to account for any latency before executing the query
        sleep(1)

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

        print()

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

    except Exception as ex:
        print("Unexpected error {0}".format(ex))
        return
    except KeyboardInterrupt:
        print("IoT Hub Device Twin service sample stopped")

El objeto IoTHubRegistryManager expone todos los métodos necesarios para interactuar con dispositivos gemelos del servicio. En primer lugar, el código inicializa el objeto IoTHubRegistryManager y, después, actualiza el dispositivo gemelo para DEVICE_ID que, por último, ejecuta dos consultas. La primera selecciona solo los dispositivos gemelos de los dispositivos que se encuentran en la planta Redmond43 y la segunda mejora la consulta para seleccionar solo los dispositivos que están también conectados a través de la red de telefonía móvil.

Agregue el código siguiente al final del archivo AddTagsAndQuery.py para implementar la función iothub_service_sample_run:

if __name__ == '__main__':
    print("Starting the Python IoT Hub Device Twin service sample...")
    print()

    iothub_service_sample_run()

Ejecute la aplicación con:
```
python AddTagsAndQuery.py
```
Debería ver un dispositivo en los resultados de la consulta que pregunta por todos los dispositivos que se encuentran en Redmond43 y ninguno para la consulta que restringe los resultados a los dispositivos que utilizan una red de telefonía móvil. En la sección siguiente, creará una aplicación de dispositivo que usará una red de telefonía móvil y volverá a ejecutar esta consulta para ver cómo cambia.

Creación de una aplicación de dispositivo que actualiza las propiedades notificadas

En esta sección, creará una aplicación de consola de Python que se conecta al centro como el {id. de dispositivo} y, luego, actualiza las propiedades notificadas de su dispositivo gemelo para confirmar que está conectada mediante una red de telefonía móvil.

En un símbolo del sistema del directorio de trabajo, instale el SDK del dispositivo de Azure IoT Hub para Python:
```
pip install azure-iot-device
```
Con un editor de texto, cree un nuevo archivo ReportConnectivity.py.
Agregue el código siguiente para importar los módulos necesarios desde el SDK del dispositivo:
```
import time
from azure.iot.device import IoTHubModuleClient
```
Agregue el código siguiente: Reemplace el valor del marcador de posición [IoTHub Device Connection String] por la cadena de conexión de dispositivo que vio cuando registró un dispositivo en IoT Hub:
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

Agregue el código siguiente al archivo ReportConnectivity.py para crear una instancia de un cliente e implementar la funcionalidad de dispositivos gemelos:

def create_client():
    # Instantiate client
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

    try:
        # Set handlers on the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler
    except:
        # Clean up in the event of failure
        client.shutdown()

    return client

Agregue el código siguiente al final del archivo ReportConnectivity.py para ejecutar la aplicación:

def main():
    print ( "Starting the Python IoT Hub Device Twin device sample..." )
    client = create_client()
    print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )

    try:
        # Update reported properties with cellular information
        print ( "Sending data as reported property..." )
        reported_patch = {"connectivity": "cellular"}
        client.patch_twin_reported_properties(reported_patch)
        print ( "Reported properties updated" )

        # Wait for program exit
        while True:
            time.sleep(1000000)
    except KeyboardInterrupt:
        print ("IoT Hub Device Twin device sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Ejecute la aplicación del dispositivo:
```
python ReportConnectivity.py
```
Debería ver la confirmación de que se actualizaron las propiedades notificadas de los dispositivos gemelos.
Ahora que el dispositivo ha informado sobre su información de conectividad, debe aparecer en ambas consultas. Vuelva atrás y ejecute las consultas de nuevo:
```
python AddTagsAndQuery.py
```
Esta vez {Device Id} debe aparecer en los resultados de ambas consultas.

En la aplicación del dispositivo, verá una confirmación de la recepción de la revisión de las propiedades gemelas deseadas enviadas por la aplicación de servicio.

En este artículo:

Ha agregado metadatos de dispositivo como etiquetas desde una aplicación de back-end.
Ha notificado la información de conectividad del dispositivo en el dispositivo gemelo.
Ha consultado la información del dispositivo gemelo mediante el lenguaje de consulta de IoT Hub.

Pasos siguientes

Para saber cómo:

Enviar datos de telemetría desde dispositivos, consulte el artículo Inicio rápido: Envío de telemetría desde un dispositivo IoT Plug and Play a Azure IoT Hub.
Configurar dispositivos mediante las propiedades deseadas del dispositivo gemelo, consulte Tutorial: Configuración de dispositivos desde un servicio back-end.
Controlar los dispositivos de forma interactiva, por ejemplo, encender un ventilador desde una aplicación controlada por el usuario, consulte Inicio rápido: Control de un dispositivo conectado a IoT Hub.