Introduzione ai dispositivi gemelli (Python)

Articolo
03/17/2023

i dispositivi gemelli sono documenti JSON che archiviano informazioni sullo stato dei dispositivi, tra cui metadati, configurazioni e condizioni. L'hub IoT rende permanente un dispositivo gemello per ogni dispositivo che si connette.

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT basic e standard/gratuiti, vedere Scegliere il livello di hub IoT appropriato per la soluzione.

Usare i dispositivi gemelli per:

Archiviare i metadati dei dispositivi dal back-end della soluzione.
Segnalare informazioni sullo stato corrente, come funzionalità disponibili e condizioni (ad esempio, il metodo di connettività usato) dall'app per dispositivi.
Sincronizzare lo stato dei flussi di lavoro a esecuzione prolungata (come gli aggiornamenti del firmware e della configurazione) tra un'app per dispositivi e un'app di back-end.
Eseguire query sui metadati, la configurazione o lo stato dei dispositivi.

I dispositivi gemelli sono progettati per la sincronizzazione e per l'esecuzione di query sulle configurazioni e le condizioni dei dispositivi. Per altre informazioni sui dispositivi gemelli, tra cui quando usare dispositivi gemelli, vedere Informazioni sui dispositivi gemelli.

Gli hub IoT archiviano i dispositivi gemelli, che contengono gli elementi seguenti:

Tag. Metadati dei dispositivi accessibili solo dal back-end della soluzione.
Proprietà desiderate. Oggetti JSON modificabili dal back-end della soluzione e osservabili dall'app per dispositivi.
Proprietà segnalate. Oggetti JSON modificabili dall'app per dispositivi e leggibili dal back-end della soluzione.

I tag e le proprietà non possono contenere matrici, ma possono contenere oggetti annidati.

Nella figura seguente viene illustrata l'organizzazione di un dispositivo gemello:

Screenshot di un diagramma del concetto di dispositivo gemello.

Il back-end della soluzione può anche eseguire query sui dispositivi gemelli in base a tutti i dati sopra indicati. Per altre informazioni sui dispositivi gemelli, vedere Informazioni sui dispositivi gemelli. Per altre informazioni sulle query, vedere Linguaggio di query di hub IoT.

Questo articolo illustra come:

Usare un'app per dispositivo simulato per segnalare il canale di connettività come proprietà segnalata nel dispositivo gemello.
Eseguire query sui dispositivi dall'app back-end con filtri sui tag e sulle proprietà creati in precedenza.

In questo articolo vengono create due app console Python:

AddTagsAndQuery.py: un'app back-end che aggiunge tag ed esegue query sui dispositivi gemelli.
Report Connessione ivity.py: un'app per dispositivi simulata che si connette all'hub IoT e ne segnala la condizione di connettività.

Nota

Per altre informazioni sugli strumenti SDK disponibili per creare app per dispositivi e back-end, vedere Azure IoT SDK.

Prerequisiti

Un account Azure attivo. Se non si dispone di un account, è possibile crearne uno gratuito in pochi minuti.
Un hub IoT. Crearne uno con l'interfaccia della riga di comando o il portale di Azure.
Un dispositivo registrato. Registrarne uno nel portale di Azure.
È consigliabile usare Python versione 3.7 o successive. Assicurarsi di usare le installazioni a 32 bit o 64 bit, come richiesto dalla configurazione. Quando richiesto durante l'installazione, assicurarsi di aggiungere Python alla variabile di ambiente specifica per la piattaforma.
Assicurarsi che la porta 8883 sia aperta nel firewall. L'esempio di dispositivo di questo articolo usa il protocollo MQTT, che comunica tramite la porta 8883. Questa porta potrebbe essere bloccata in alcuni ambienti di rete aziendali e didattici. Per altre informazioni e soluzioni alternative per questo problema, vedere Connettersi all'hub IoT (MQTT).

Ottenere la stringa di connessione dell'hub IoT

In questo articolo viene creato un servizio back-end che aggiunge le proprietà desiderate a un dispositivo gemello e quindi esegue una query nel registro delle identità per trovare tutti i dispositivi con le proprietà segnalate che sono stati aggiornati di conseguenza. Il servizio richiede l’autorizzazione di connessione al servizio per modificare le proprietà desiderate di un dispositivo gemello ed è necessaria l’autorizzazione di lettura del registro di sistema per eseguire query sul registro delle identità. Non esistono criteri di accesso condiviso predefiniti che contengono solo queste due autorizzazioni, quindi è necessario crearne uno.

Per creare criteri di accesso condiviso che concedono le autorizzazioni di connessione al servizio e lettura del registro di sistema e ottenere una stringa di connessione per questo criterio, attenersi alla seguente procedura:

Nel portale di Azure fare clic su Gruppi di risorse. Selezionare il gruppo di risorse in cui si trova l'hub e quindi selezionare l'hub dall'elenco di risorse.
Nel riquadro sinistro dell'hub selezionare Criteri di accesso condiviso.
Nel menu in alto sopra l'elenco dei criteri selezionare Aggiungi criteri di accesso ai criteri condivisi.
Nel riquadro Aggiungi criteri di accesso condiviso a destra immettere un nome descrittivo per i criteri, ad esempio serviceAndRegistryRead. In Autorizzazioni selezionare Lettura e servizio del Registro di sistema Connessione e quindi selezionare Aggiungi.
Selezionare il nuovo criterio dall'elenco dei criteri.
Selezionare l'icona di copia per il stringa di connessione primario e salvare il valore.

Per altre informazioni sui criteri di accesso condiviso e sulle autorizzazioni dell'hub IoT, vedere Controllo dell'accesso e autorizzazioni.

Creare un'app di servizio che aggiorni le proprietà desiderate e le query dei dispositivi gemelli

In questa sezione viene creata un'app console Python che aggiunge i metadati della posizione al dispositivo gemello associato all '{ID dispositivo}. L'app esegue una query sull'hub IoT per i dispositivi che si trovano negli Stati Uniti e quindi esegue query sui dispositivi che segnalano una connessione di rete cellulare.

Nella directory di lavoro aprire un prompt dei comandi e installare hub IoT di Azure Service SDK per Python.
```
pip install azure-iot-hub
```
Usando un editor di testo, creare un nuovo file AddTagsAndQuery.py.

Aggiungere il codice seguente per importare i moduli necessari dall'SDK del servizio:

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

Aggiungi il seguente codice. Sostituire [IoTHub Connection String] con la stringa di connessione dell'hub IoT copiata in Ottenere la stringa di connessione dell'hub IoT. Sostituire [Device Id] con l'ID dispositivo (il nome) del dispositivo registrato nell'hub IoT.
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

Aggiungere il codice seguente al file 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")

L'oggetto IoTHubRegistryManager espone tutti i metodi necessari per interagire con i dispositivi gemelli dal servizio. Il codice inizializza prima l'oggetto IoTHubRegistryManager , quindi aggiorna il dispositivo gemello per DEVICE_ID e infine esegue due query. Il primo seleziona solo i dispositivi gemelli dei dispositivi che si trovano nell'impianto Redmond43 e la seconda affina la query per selezionare solo i dispositivi connessi anche tramite una rete cellulare.

Aggiungere il codice seguente alla fine di AddTagsAndQuery.py per implementare la funzione iothub_service_sample_run:

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

    iothub_service_sample_run()

Eseguire l'applicazione con:
```
python AddTagsAndQuery.py
```
Nei risultati si noterà un dispositivo per la query che cerca tutti i dispositivi situati in Redmond43 e nessuno per la query che limita i risultati ai dispositivi che usano una rete cellulare. Nella sezione successiva si creerà un'app per dispositivi che userà una rete cellulare e si eseguirà di nuovo questa query per vedere come cambia.

Creare un'app per dispositivi che aggiorna le proprietà segnalate

In questa sezione viene creata un'app console Python che si connette all'hub come {ID dispositivo} e quindi aggiorna le proprietà segnalate del dispositivo gemello per verificare che sia connessa tramite una rete cellulare.

Da un prompt dei comandi nella directory di lavoro installare l'SDK per dispositivi hub IoT di Azure per Python:
```
pip install azure-iot-device
```
Usando un editor di testo, creare un nuovo file ReportConnectivity.py.
Aggiungere il codice seguente per importare i moduli necessari dall'SDK per dispositivi:
```
import time
from azure.iot.device import IoTHubModuleClient
```
Aggiungi il seguente codice. Sostituire il [IoTHub Device Connection String] valore segnaposto con il dispositivo stringa di connessione visualizzato quando è stato registrato un dispositivo nel hub IoT:
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

Aggiungere il codice seguente al file Report Connessione ivity.py per creare un'istanza di un client e implementare la funzionalità dei dispositivi gemelli:

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

Aggiungere il codice seguente alla fine del report Connessione ivity.py per eseguire l'applicazione:

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

Eseguire l'app per dispositivo:
```
python ReportConnectivity.py
```
Verrà visualizzata la conferma dell'aggiornamento delle proprietà segnalate del dispositivo gemello.
Ora che il dispositivo ha segnalato le informazioni sulla connettività, verrà visualizzato in entrambe le query. Tornare indietro ed eseguire di nuovo le query:
```
python AddTagsAndQuery.py
```
Questa volta il tuo {ID dispositivo} dovrebbe essere visualizzato in entrambi i risultati della query.

Nell'app per dispositivi verrà visualizzato un messaggio di conferma della ricezione della patch del dispositivo gemello delle proprietà desiderate inviata dall'app del servizio.

In questo articolo si apprenderà come:

Aggiunta di metadati del dispositivo come tag da un'app back-end
Informazioni sulla connettività del dispositivo segnalate nel dispositivo gemello
Query sulle informazioni sul dispositivo gemello usando il linguaggio di query hub IoT

Passaggi successivi

Per scoprire come:

Inviare dati di telemetria dai dispositivi, vedere Avvio rapido: Inviare dati di telemetria da un dispositivo Plug and Play IoT a hub IoT di Azure articolo.
Configurare i dispositivi usando le proprietà desiderate del dispositivo gemello, vedere Esercitazione: Configurare i dispositivi da un servizio back-end.
Controllare i dispositivi in modo interattivo, ad esempio accendere una ventola da un'app controllata dall'utente, vedere Avvio rapido: Controllare un dispositivo connesso a un hub IoT.