Introducción a la administración de dispositivos (Python)

Artículo
03/19/2023

Las aplicaciones de back-end pueden usar primitivos de Azure IoT Hub, como dispositivos gemelos y métodos directos, para iniciar y supervisar de forma remota las acciones de administración de dispositivos en los dispositivos. Este artículo muestra cómo una aplicación back-end y una aplicación para dispositivo pueden funcionar a la vez para iniciar y supervisar el reinicio remoto de un dispositivo mediante IoT Hub.

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 un método directo para iniciar acciones de administración de dispositivos (por ejemplo, reinicio, restablecimiento de fábrica y actualización de firmware) desde una aplicación back-end en la nube. El dispositivo es responsable de:

Controlar la solicitud del método enviada desde IoT Hub.
Iniciar la acción específica del dispositivo correspondiente en el dispositivo.
Proporcionar actualizaciones de estado mediante las propiedades notificadas a IoT Hub.

Puede usar una aplicación de back-end en la nube para ejecutar consultas de dispositivos gemelos para informar sobre el progreso de las acciones de administración de los dispositivos.

Este artículo muestra cómo crear:

dmpatterns_getstarted_device.py: una aplicación de dispositivo simulado con un método directo que reinicia el dispositivo e informa de la última hora de reinicio. Los métodos directos se invocan desde la nube.
dmpatterns_getstarted_service.py: una aplicación de consola de Python que llame al método directo en la aplicación de dispositivo simulado mediante el centro de IoT. Muestra la respuesta y las propiedades notificadas actualizadas.

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).

Registro de un nuevo dispositivo en el centro de IoT

En esta sección, se usa la CLI de Azure para crear una identidad del dispositivo para este artículo. Los identificadores de dispositivos distinguen mayúsculas de minúsculas.

Abra Azure Cloud Shell.
En Azure Cloud Shell, ejecute el comando siguiente para instalar la extensión IoT de Microsoft Azure para la CLI de Azure:
```
az extension add --name azure-iot
```
Cree una identidad del dispositivo denominada myDeviceId y recupere la cadena de conexión del dispositivo con estos comandos:
```
az iot hub device-identity create --device-id myDeviceId --hub-name {Your IoT Hub name} --resource-group {Resource group of the Hub}
az iot hub device-identity connection-string show --device-id myDeviceId --hub-name {Your IoT Hub name} --resource-group {Resource group of the Hub} -o table
```
Importante

El identificador del dispositivo puede estar visible en los registros recopilados para soporte técnico y solución de problemas del cliente, por tanto asegúrese de evitar cualquier información confidencial al darle el nombre.

Anote la cadena de conexión de dispositivo del resultado. La aplicación de dispositivo usa esta cadena de conexión de dispositivo para conectarse a su instancia de IoT Hub como un dispositivo.

Creación de una aplicación de dispositivo con un método directo

En esta sección:

Cree una aplicación de consola de Python que responda a un método directo que se llama desde la nube.
Simule el reinicio de un dispositivo.
Usará las propiedades notificadas para permitir consultas de dispositivo gemelo a fin de identificar los dispositivos y cuándo se reiniciaron por última vez.

En Azure Cloud Shell que usaste anteriormente o en cualquier otro entorno con Python, crea el código del dispositivo.

En el símbolo del sistema, ejecute el siguiente comando para instalar el paquete azure-iot-device:
```
pip install azure-iot-device
```
Con un editor de texto, cree un archivo denominado dmpatterns_getstarted_service.py en el directorio de trabajo.
Agregue las siguientes instrucciones import al comienzo del archivo dmpatterns_getstarted_device.py.
```
import time
import datetime
from azure.iot.device import IoTHubDeviceClient, MethodResponse
```
Agregue la variable CONNECTION_STRING. Reemplace el valor del marcador de posición {deviceConnectionString} por la cadena de conexión del dispositivo. Ha copiado esta cadena de conexión previamente en Registro de un nuevo dispositivo en el centro de IoT.
```
CONNECTION_STRING = "{deviceConnectionString}"
```

Agregue la siguiente función para crear una instancia de un cliente configurado para métodos directos en el dispositivo.

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

    # Define the handler for method requests
    def method_request_handler(method_request):
        if method_request.name == "rebootDevice":
            # Act on the method by rebooting the device
            print("Rebooting device")
            time.sleep(20)
            print("Device rebooted")

            # ...and patching the reported properties
            current_time = str(datetime.datetime.now())
            reported_props = {"rebootTime": current_time}
            client.patch_twin_reported_properties(reported_props)
            print( "Device twins updated with latest rebootTime")

            # Create a method response indicating the method request was resolved
            resp_status = 200
            resp_payload = {"Response": "This is the response from the device"}
            method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

        else:
            # Create a method response indicating the method request was for an unknown method
            resp_status = 404
            resp_payload = {"Response": "Unknown method"}
            method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

        # Send the method response
        client.send_method_response(method_response)

    try:
        # Attach the handler to the client
        client.on_method_request_received = method_request_handler
    except:
        # In the event of failure, clean up
        client.shutdown()

    return client

Inicie el ejemplo de método directo y espere.

def main():
    print ("Starting the IoT Hub Python sample...")
    client = create_client()

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Wait for program exit
        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubDeviceClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Guarde y cierre el archivo dmpatterns_getstarted_device.py.

Nota

Por simplificar, este tutorial no implementa ninguna directiva de reintentos. En el código de producción, deberá implementar directivas de reintentos (por ejemplo, retroceso exponencial), tal y como se sugiere en el artículo Control de errores transitorios.

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

En este artículo, creará un servicio back-end que invoca un método directo en un dispositivo. Para invocar un método directo en un dispositivo a través de IoT Hub, el servicio necesita el permiso Conexión del servicio. De forma predeterminada, todas las instancias de IoT Hub se crean con una directiva de acceso compartido denominada servicio que concede este permiso.

Para obtener la cadena de conexión de IoT Hub para la directiva service, 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 de IoT Hub, seleccione Directivas de acceso compartido.
En la lista de directivas, seleccione la directiva service.
Copie la 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 para desencadenar un reinicio

En esta sección, creará una aplicación de consola de Python que inicia un reinicio remoto en un dispositivo mediante un método directo. La aplicación usa las consultas gemelas de dispositivo para detectar la hora en que se reinició por última vez el dispositivo.

En Azure Cloud Shell o en cualquier otro entorno con Python, cree el código de la consola.

En el símbolo del sistema, ejecute el siguiente comando para instalar el paquete azure-iot-hub:
```
pip install azure-iot-hub
```
Con un editor de texto, cree un archivo denominado dmpatterns_getstarted_service.py en el directorio de trabajo.

Agregue las siguientes instrucciones import al comienzo del archivo dmpatterns_getstarted_service.py.

import sys, time

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult, Twin

Agregue las siguientes declaraciones de variable. Reemplace el valor del marcador de posición {IoTHubConnectionString} por la cadena de conexión del centro de IoT que copió anteriormente en Obtención de la cadena de conexión de IoT Hub. Reemplace el marcador de posición {deviceId} por el identificador de dispositivo que registró en Registro de un nuevo dispositivo en el centro de IoT.
```
CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10
```

Agregue la siguiente función para invocar el método de reinicio del dispositivo de destino, luego consulte los dispositivos gemelos y obtenga la hora del último reinicio.

def iothub_devicemethod_sample_run():
    try:
        # Create IoTHubRegistryManager
        registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

        print ( "" )
        print ( "Invoking device to reboot..." )

        # Call the direct method.
        deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
        response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

        print ( "" )
        print ( "Successfully invoked the device to reboot." )

        print ( "" )
        print ( response.payload )

        while True:
            print ( "" )
            print ( "IoTHubClient waiting for commands, press Ctrl-C to exit" )

            status_counter = 0
            while status_counter <= WAIT_COUNT:
                twin_info = registry_manager.get_twin(DEVICE_ID)

                if twin_info.properties.reported.get("rebootTime") != None :
                    print ("Last reboot time: " + twin_info.properties.reported.get("rebootTime"))
                else:
                    print ("Waiting for device to report last reboot time...")

                time.sleep(5)
                status_counter += 1

    except Exception as ex:
        print ( "" )
        print ( "Unexpected error {0}".format(ex) )
        return
    except KeyboardInterrupt:
        print ( "" )
        print ( "IoTHubDeviceMethod sample stopped" )

if __name__ == '__main__':
    print ( "Starting the IoT Hub Service Client DeviceManagement Python sample..." )
    print ( "    Connection string = {0}".format(CONNECTION_STRING) )
    print ( "    Device ID         = {0}".format(DEVICE_ID) )

    iothub_devicemethod_sample_run()

Guarde y cierre el archivo dmpatterns_getstarted_service.py.

Ejecución de las aplicaciones

Ya está listo para ejecutar el código de dispositivo y el código de servicio que inicia el reinicio de un dispositivo.

En el símbolo del sistema en el que creó el dispositivo, ejecute el siguiente comando para iniciar la escucha del método directo de reinicio.
```
python dmpatterns_getstarted_device.py
```
En el símbolo del sistema en el que creó el servicio, ejecute el siguiente comando para desencadenar el reinicio remoto y la consulta en el dispositivo gemelo para buscar la hora del último reinicio.
```
python dmpatterns_getstarted_service.py
```
Verá la respuesta del dispositivo al método directo en la consola.

A continuación, puede ver la respuesta del dispositivo al método directo de reinicio:

A continuación se muestra el servicio que llama al método directo de reinicio y sondea el estado del dispositivo gemelo:

Personalizar y ampliar el dispositivo las acciones de administración del dispositivo

Las soluciones de IoT pueden expandir el conjunto definido de patrones de administración de dispositivos o permitir modelos personalizados mediante el uso de los primitivos de método de nube a dispositivo y dispositivos gemelos. Otros ejemplos de acciones de administración de dispositivos son el restablecimiento de fábrica, la actualización de firmware, la actualización de software, la administración de energía, la administración de conectividad y red, y el cifrado de datos.

Ventanas de mantenimiento del dispositivo

Normalmente, puede dispositivos para llevar a cabo acciones a la vez que minimiza las interrupciones y el tiempo de inactividad. Las ventanas de mantenimiento dle dispositivo son un patrón que se utiliza habitualmente para definir la hora en la que un dispositivo debe actualizar su configuración. Las soluciones de back-end pueden utilizar las propiedades deseadas del dispositivo gemelo para definir y activar una directiva en el dispositivo que permita una ventana de mantenimiento. Cuando un dispositivo recibe la directiva de la ventana de mantenimiento, puede usar la propiedad notificada del dispositivo gemelo para informar del estado de la directiva. La aplicación de back-end puede usar luego consultas de dispositivos gemelos para dar testimonio de cumplimiento de dispositivos y cada directiva.

Pasos siguientes

En este artículo, ha usado un método directo para desencadenar un reinicio remoto en un dispositivo. Se usaron las propiedades notificadas para notificar la última hora de reinicio del dispositivo y se consultó el dispositivo gemelo para detectar la última hora de reinicio del dispositivo desde la nube.

Para continuar con la introducción a IoT Hub y los patrones de administración de dispositivos, como la actualización basada en imágenes de un extremo a otro, consulte el Artículo de Device Update para Azure IoT Hub con la imagen de referencia para Raspberry Pi 3 B+.

Para obtener información sobre cómo ampliar la solución IoT y programar llamadas a métodos en varios dispositivos, vea Programación de trabajos en varios dispositivos.

Introducción a la administración de dispositivos (Python)

Requisitos previos

Registro de un nuevo dispositivo en el centro de IoT

Creación de una aplicación de dispositivo con un método directo

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

Creación de una aplicación de servicio para desencadenar un reinicio

Ejecución de las aplicaciones

Personalizar y ampliar el dispositivo las acciones de administración del dispositivo

Ventanas de mantenimiento del dispositivo

Pasos siguientes

Recursos adicionales