Introdução aos dispositivos gêmeos (Python)

Artigo
03/19/2023

Dispositivos gêmeos são documentos JSON que armazenam informações do estado do dispositivo, incluindo metadados, configurações e condições. O Hub IoT persiste um dispositivo gêmeo para cada dispositivo que você conecta a ele.

Observação

Os recursos descritos neste artigo estão disponíveis apenas na camada padrão do Hub IoT. Para obter mais informações sobre as camadas básica e padrão/gratuita do Hub IoT, confira Escolher a camada certa do Hub IoT para a sua solução.

Use os dispositivos gêmeos para:

Armazene os metadados de dispositivo de seu back-end da solução.
Relate informações de estado atual, como funcionalidades disponíveis e condições (por exemplo, o método conectividade usado) do aplicativo do dispositivo.
Sincronize o estado dos fluxos de trabalho de longa duração (como atualizações de firmware e de configuração) entre um aplicativo de dispositivo e um aplicativo de back-end.
Consultar os metadados, a configuração ou o estado do seu dispositivo.

Dispositivos gêmeos são projetados para sincronização e para consultar condições e configurações de dispositivos. Para obter mais informações sobre dispositivos gêmeos e quando usá-los, confira Noções básicas sobre dispositivos gêmeos.

Os hubs IoT armazenam dispositivos gêmeos, que contêm os seguintes elementos:

Marcas. Metadados do dispositivo acessíveis apenas por meio do back-end da solução.
Propriedades desejadas. Objetos JSON modificáveis pelo back-end da solução e observáveis pelo aplicativo de dispositivo.
Propriedades reportadas. Objetos JSON modificáveis pelo aplicativo de dispositivo e legíveis pelo back-end da solução.

Marcas e propriedades não podem conter matrizes, mas podem conter objetos aninhados.

A ilustração a seguir mostra a organização de um dispositivo gêmeo:

Captura de tela de um diagrama de conceito de dispositivo gêmeo.

Além disso, o back-end da solução pode consultar dispositivos gêmeos com base em todos os dados acima. Para obter mais informações sobre dispositivos gêmeos, consulte Noções básicas de dispositivos gêmeos. Para obter mais informações sobre a consulta, consulte Linguagem de consulta do Hub IoT.

Este artigo mostra como:

Use um aplicativo de dispositivo simulado para relatar seu canal de conectividade como uma propriedade relatada no dispositivo gêmeo.
Consulte dispositivos por meio do aplicativo de back-end usando filtros nas marcações e propriedades criadas anteriormente.

Neste artigo, você cria dois aplicativos de console do Python:

AddTagsAndQuery.py: um aplicativo de back-end que adiciona marcas e consultas aos dispositivos gêmeos.
ReportConnectivity.py: um aplicativo de dispositivo simulado que se conecta ao hub IoT e relata a própria condição de conectividade.

Observação

Para obter mais informações sobre as ferramentas do SDK disponíveis para compilar os dispositivos e os aplicativos de back-end, consulte SDKs de Internet das Coisas do Azure.

Pré-requisitos

Uma conta ativa do Azure. (Se você não tiver uma conta, poderá criar uma conta gratuita em apenas alguns minutos.)
Um hub IoT. Crie um com a CLI ou o portal do Azure.
Um dispositivo registrado. Registre um no portal do Azure.
O Python versão 3.7 ou posterior é recomendado. Certifique-se de usar a instalação de 32 bits ou 64 bits conforme exigido pelo seu programa de instalação. Quando solicitado durante a instalação, certifique-se de adicionar Python à variável de ambiente específica da plataforma.
Verifique se a porta 8883 está aberta no firewall. O exemplo de dispositivo deste artigo usa o protocolo MQTT, que se comunica pela porta 8883. Essa porta poderá ser bloqueada em alguns ambientes de rede corporativos e educacionais. Para obter mais informações e maneiras de resolver esse problema, confira Como se conectar ao Hub IoT (MQTT).

Obter a cadeia de conexão do hub IoT

Neste artigo, você cria um serviço de back-end que adiciona as propriedades desejadas a um dispositivo gêmeo e, em seguida, consulta o registro de identidade para localizar todos os dispositivos com as propriedades relatadas que foram atualizadas de acordo. O seu serviço precisa da permissão conexão de serviço para modificar as propriedades desejadas de um dispositivo gêmeo e precisa da permissão leitura do registro para consultar o registro de identidade. Não há nenhuma política de acesso compartilhado padrão que contenha apenas essas duas permissões, portanto, você precisa criar uma.

Para criar uma política de acesso compartilhado que conceda as permissões conexão de serviço e leitura de registro e obter uma cadeia de conexão para essa política, siga estas etapas:

No portal do Azure, selecione Grupos de recursos. Selecione o grupo de recursos em que o Hub está localizado e, em seguida, selecione o seu hub na lista de recursos.
No painel do lado esquerdo do hub, selecione Políticas de acesso compartilhado.
No menu superior acima da lista de políticas, selecione Adicionar política de acesso compartilhado.
No painel Adicionar política de acesso compartilhado à direita, insira um nome descritivo para a política, como serviceAndRegistryRead. Em Permissões, selecione Leitura de Registro e Conexão de Serviço e selecione Adicionar.
Selecione a sua nova política na lista de políticas.
Selecione o ícone de cópia da Cadeia de conexão primária e salve o valor.

Para obter mais informações sobre permissões e políticas de acesso compartilhado do Hub IoT, consulte Controle de acesso e permissões.

Criar um aplicativo de serviço que atualiza as propriedades desejadas e consulta gêmeos

Nesta seção, você cria um aplicativo de console do Python que adiciona metadados de local ao dispositivo gêmeo associado à {Device ID} . O aplicativo consulta no hub IoT se há dispositivos localizados nos EUA e, em seguida, consulta dispositivos que relatam a uma conexão de rede de celular.

Em seu diretório de trabalho, abra um prompt de comando e instale o SDK de Serviço do Hub IoT para Python.
```
pip install azure-iot-hub
```
Usando um editor de texto, crie um novo arquivo AddTagsAndQuery.py.

Adicione o código a seguir para importar os módulos necessários do SDK de serviço:

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

Adicione o código seguinte: Substitua [IoTHub Connection String] pela cadeia de conexão do hub IoT que você copiou em Obter a cadeia de conexão do hub IoT. Substitua [Device Id] pela identificação do dispositivo registrado (o nome) no hub IoT.
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

Adicione o seguinte código ao arquivo 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")

O objeto IoTHubRegistryManager expõe todos os métodos necessários para interagir com gêmeos de dispositivo do serviço. O código primeiro inicializa o objeto IoTHubRegistryManager, atualiza o dispositivo gêmeo para DEVICE_ID e, por fim, executa duas consultas. A primeira seleciona somente os dispositivos gêmeos de dispositivos localizados na fábrica de Redmond43, enquanto a segunda refina a consulta para selecionar somente os dispositivos que também estão conectados por meio de uma rede de celular.

Adicione o seguinte código ao final de AddTagsAndQuery.py para implementar a função iothub_service_sample_run:

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

    iothub_service_sample_run()

Execute o aplicativo com:
```
python AddTagsAndQuery.py
```
Você deve ver um dispositivo nos resultados da consulta que pergunta sobre todos os dispositivos localizados em Redmond43, e nenhum para a consulta que restringe os resultados para dispositivos que usam uma rede de celular. Na próxima seção, você criará um aplicativo de dispositivo que usará uma rede celular e executará novamente essa consulta para ver como ela muda.

Criar um aplicativo de dispositivo que atualiza as propriedades relatadas

Nesta seção, você cria um aplicativo de console do Python que se conecta ao seu hub como {Device ID} e depois atualiza as propriedades relatadas do dispositivo gêmeo dele para confirmar que ele está conectado usando uma rede celular.

De um prompt de comando em seu diretório de trabalho, instale o SDK de Dispositivo do Hub IoT do Azure para Python:
```
pip install azure-iot-device
```
Usando um editor de texto, crie um novo arquivo ReportConnectivity.py.
Adicione o seguinte código para importar os módulos necessários do SDK do dispositivo:
```
import time
from azure.iot.device import IoTHubModuleClient
```
Adicione o código seguinte: Substitua o valor do espaço reservado [IoTHub Device Connection String] pela cadeia de conexão de dispositivo que você viu quando registrou um dispositivo no Hub IoT:
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

Adicione o seguinte código ao arquivo ReportConnectivity.py para instanciar uma cliente ou implementar a funcionalidade de dispositivo gêmeo:

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

Adicione o seguinte código ao final de ReportConnectivity.py para executar o aplicativo:

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

Execute o aplicativo do dispositivo:
```
python ReportConnectivity.py
```
Você verá a confirmação de que as propriedades relatadas do dispositivo gêmeo foram atualizadas.
Agora que o dispositivo divulgou suas informações de conectividade, ele deve aparecer em ambas as consultas. Volte e execute as consultas novamente:
```
python AddTagsAndQuery.py
```
Desta vez, {Device ID} deve aparecer em ambos os resultados da consulta.

No aplicativo do dispositivo, você verá a confirmação de que o patch gêmeo de propriedades desejadas enviado pelo aplicativo de serviço foi recebido.

Neste artigo você:

Adicionou metadados do dispositivo como marcas de um aplicativo de back-end
Relatou informações de conectividade do dispositivo no dispositivo gêmeo
Consultou as informações do dispositivo gêmeo usando a linguagem de consulta do Hub IoT

Próximas etapas

Para saber como:

Enviar telemetria de dispositivos, confira o artigo Início Rápido: enviar telemetria de um dispositivo IoT Plug and Play para o Hub IoT do Azure.
Configurar dispositivos usando as propriedades desejadas do dispositivo gêmeo, consulte Tutorial: Configurar seus dispositivos de um serviço de back-end.
Controlar dispositivos interativamente, como ativar um ventilador de um aplicativo controlado pelo usuário, consulte Início Rápido: controlar um dispositivo conectado a um hub IoT.

Share via