As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Tutorial: instalando o Device SDK e executando o aplicativo de amostra para Sombras do Dispositivo

Esta seção mostra como você pode instalar o software necessário e o SDK de dispositivo AWS IoT para Python e executar o aplicativo de exemplo shadow.py para editar o documento Shadow e controlar o estado do shadow.

Antes de executar este tutorial:

Você deve ter configurado seu Conta da AWS, configurado o seu dispositivo Raspberry Pi e criado um objeto AWS IoT e uma política que conceda ao dispositivo permissões para publicar e assinar os tópicos reservados MQTT do serviço Sombra do Dispositivo. Para obter mais informações, consulte Tutorial: preparando seu Raspberry Pi para executar o aplicativo de sombra.

Você também deve ter instalado o Git, o Python e o SDK de dispositivo AWS IoT para Python. Este tutorial se baseia nos conceitos apresentados no tutorial Conectar um Raspberry Pi ou outro dispositivo. Se você ainda não experimentou esse tutorial, recomendamos que siga as etapas descritas nesse tutorial para instalar os arquivos de certificado e o SDK do dispositivo e, em seguida, volte a este tutorial para executar o aplicativo de amostra shadow.py.

A conclusão deste tutorial requer cerca de 20 minutos.

Etapa 1: execute o aplicativo de exemplo shadow.py

Antes de executar o aplicativo de amostra shadow.py, você precisará das informações a seguir, além dos nomes e do local dos arquivos de certificado instalados.

Insira valores e observe as atualizações no documento de sombra

Você pode inserir valores no terminal para especificar o valor desired, o que também atualiza o valor reported. Digamos que você insira a cor yellow no terminal. O valor reported também é atualizado para a cor yellow. O seguinte mostra as mensagens exibidas no terminal:

Enter desired value:
yellow
Changed local shadow value to 'yellow'.
Updating reported shadow value to 'yellow'...
Update request published.
Finished updating reported shadow value to 'yellow'.

Ao publicar essa solicitação de atualização, AWS IoT cria uma sombra clássica padrão para o recurso do objeto. É possível observar a solicitação de atualização publicada nos valores reported e desired no console AWS IoT examinando o documento de sombra do recurso de objeto que você criou (por exemplo, My_light_bulb). Para ver a atualização no documento de sombra:

O documento de sombra deve ser semelhante ao seguinte, mostrando os valores reported e desired definidos para a cor yellow. Você vê esses valores na seção Estado da sombra do documento.

{
"desired": {
  "welcome": "aws-iot",
  "color": "yellow"
},
"reported": {
  "welcome": "aws-iot",
  "color": "yellow"
}
}

Você também vê uma seção de Metadados que contém as informações de data e hora e o número da versão da solicitação.

Você pode usar a versão do documento de estado para garantir que está atualizando a versão mais recente de um documento de sombra do dispositivo. Se você enviar outra solicitação de atualização, o número da versão será incrementado em 1. Ao fornecer uma versão com uma solicitação de atualização, o serviço rejeitará a solicitação com um código de resposta de conflito HTTP 409 se a versão atual do documento de estado não corresponder à versão fornecida.

{
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  }
},
"version": 10
}        

Para saber mais sobre o documento de sombra e observar as alterações nas informações de estado, vá para o próximo tutorial Tutorial: interagindo com a Sombra do Dispositivo usando o aplicativo de amostra e o cliente de teste MQTT conforme descrito na seção Etapa 4: revisar os resultados e as próximas etapas deste tutorial. Opcionalmente, você também pode aprender sobre o código de amostra shadow.py e como ele usa o protocolo MQTT na seção a seguir.

Etapa 2: revise o aplicativo de amostra do SDK do dispositivo shadow.py

Esta seção analisa o aplicativo de amostra shadow.py do AWS IoT Device SDK v2 para Python usado neste tutorial. Aqui, veremos como ele se conecta em AWS IoT Core usando o protocolo MQTT e MQTT sobre WSS. A biblioteca AWS common runtime (AWS-CRT) fornece suporte ao protocolo de comunicação de baixo nível e está incluída no Device SDK v2 AWS IoT para Python.

Embora este tutorial use MQTT e MQTT sobre WSS, o AWS IoT oferece suporte a dispositivos que publicam solicitações HTTPS. Para ver um exemplo de um programa em Python que envia uma mensagem HTTP de um dispositivo, consulte o exemplo de código HTTPS usando a biblioteca do Python requests.

Para obter informações sobre como você pode tomar uma decisão informada sobre qual protocolo usar para as comunicações do seu dispositivo, consulte Escolher um protocolo para a comunicação do seu dispositivo.

MQTT

As chamadas shadow.py de amostra mtls_from_path (mostradas aqui) em mqtt_connection_builder para estabelecer uma conexão com AWS IoT Core usando o protocolo MQTT. O mtls_from_path usa certificados X.509 e TLS v1.2 para autenticar o dispositivo. A biblioteca AWS-CRT manipula os detalhes de nível inferior dessa conexão.

mqtt_connection = mqtt_connection_builder.mtls_from_path(
  endpoint=args.endpoint,
  cert_filepath=args.cert,
  pri_key_filepath=args.key,
  ca_filepath=args.ca_file,
  client_bootstrap=client_bootstrap,
  on_connection_interrupted=on_connection_interrupted,
  on_connection_resumed=on_connection_resumed,
  client_id=args.client_id,
  clean_session=False,
  keep_alive_secs=6
)

A amostra shadow.py também chama websockets_with_default_aws_signing no mqtt_connection_builder para estabelecer uma conexão com AWS IoT Core usando o protocolo MQTT sobre WSS. MQTT sobre WSS também usa os mesmos parâmetros que MQTT e usa estes parâmetros adicionais:

Inscreva-se em tópicos e eventos de sombra

A amostra shadow.py tenta estabelecer uma conexão e espera ser totalmente conectada. Se não estiver conectado, os comandos serão colocados na fila. Uma vez conectado, o exemplo assina eventos delta e atualiza e obtém mensagens, e publica mensagens com um nível de Qualidade de Serviço (QoS) de 1 (mqtt.QoS.AT_LEAST_ONCE).

Quando um dispositivo assina uma mensagem com QoS nível 1, o agente de mensagens salva as mensagens nas quais o dispositivo está inscrito até que elas possam ser enviadas ao dispositivo. O agente de mensagens reenvia as mensagens até receber uma resposta PUBACK do dispositivo.

Para obter mais informações sobre o protocolo MQTT, consulte Revisar o protocolo MQTT e MQTT.

Para obter mais informações sobre como MQTT, MQTT sobre WSS, sessões persistentes e níveis de QoS são usados neste tutorial, consulte. Revise o aplicativo de amostra do SDK do dispositivo pubsub.py

Etapa 3: solucionar problemas com o aplicativo de amostra shadow.py

Ao executar o aplicativo de amostra shadow.py, você deve ver algumas mensagens exibidas no terminal e uma solicitação para inserir um valor desired. Se o programa gerar um erro, para depurar o erro, você pode começar verificando se executou o comando correto para o seu sistema.

Em alguns casos, a mensagem de erro pode indicar problemas de conexão e ser semelhante a: Host name was invalid for dns resolution ou Connection was closed unexpectedly. Nesses casos, aqui estão algumas objetos que você pode verificar:

Etapa 4: revisar os resultados e as próximas etapas

Próximas etapas

Agora você pode executar o aplicativo de amostra shadow.py e usar as Sombras do Dispositivo para controlar o estado. Você pode observar as atualizações no documento Shadow no console AWS IoT e observar os eventos delta aos quais o aplicativo de amostra responde. Usando o cliente de teste MQTT, é possível assinar os tópicos de sombra reservados e observar as mensagens recebidas pelos tópicos ao executar o programa de amostra. Para obter mais informações sobre como executar este tutorial, consulte Tutorial: interagindo com a Sombra do Dispositivo usando o aplicativo de amostra e o cliente de teste MQTT.