Usar sombras em dispositivos

Esta seção descreve as comunicações de dispositivos com sombras usando mensagens MQTT, o método preferido para dispositivos se comunicarem com o serviço AWS IoT Device Shadow.

As comunicações de sombra emulam um modelo de solicitação/resposta usando o modelo de comunicação de publicação/assinatura do MQTT. Cada ação de sombra consiste em um tópico de solicitação, um tópico de resposta bem-sucedido (accepted) e um tópico de resposta de erro (rejected).

Para que os aplicativos e serviços possam determinar se um dispositivo está conectado, consulte Detectar se um dispositivo está conectado.

Importante

Como o MQTT usa um modelo de comunicação de publicação/assinatura, você pode assinar os tópicos de resposta antes de você publicar um tópico de solicitação. Caso contrário, você não deve receber a resposta à solicitação que publicar.

Se você usar um AWS IoT Device SDK para chamar as APIs do serviço Sombra do Dispositivo, isso será feito para você.

Os exemplos desta seção usam uma forma abreviada do tópico em que ShadowTopicPrefixpodem se referir a uma sombra nomeada ou não nomeada, conforme descrito nesta tabela.

As sombras podem ser nomeadas ou sem nome (clássica). Os tópicos usados por cada uma diferem apenas no prefixo do tópico. Esta tabela mostra o prefixo do tópico usado em cada tipo de sombra.

ShadowTopicPrefix value	Tipo de sombra
$aws/things/thingName/shadow	Sombra sem nome (clássica)
$aws/things/thingName/shadow/name/shadowName	Sombra nomeada

Importante

Verifique se o uso de sombras por seu aplicativo ou serviço é consistente e compatível com as implementações correspondentes em seus dispositivos. Por exemplo, considere como as sombras são criadas, atualizadas e excluídas. Considere também como as atualizações são processadas no dispositivo e nos aplicativos ou serviços que acessam o dispositivo por meio de uma sombra. Seu design deve ser claro sobre como o estado do dispositivo é atualizado e relatado e como seus aplicativos e serviços interagem com o dispositivo e suas sombras.

Para criar um tópico completo, selecione o ShadowTopicPrefix do tipo de sombra ao qual você quer fazer referência, substitua thingName, e shadowName, se aplicável, por seus valores correspondentes e acrescente isso ao stub de tópico, conforme mostrado na seguinte tabela. Lembre-se de que os tópicos diferenciam maiúsculas de minúsculas.

Consulte Tópicos de sombra para obter mais informações sobre os tópicos reservados para sombras.

Inicializando o dispositivo na primeira conexão com AWS IoT

Depois que um dispositivo se registra AWS IoT, ele deve assinar essas mensagens MQTT para as sombras que ele suporta.

Tópico	Significado	Ação que um dispositivo deve executar quando este tópico é recebido
ShadowTopicPrefix/delete/accepted	A delete solicitação foi aceita e a sombra foi AWS IoT excluída.	As ações necessárias para acomodar a sombra excluída, como interromper a publicação de atualizações.
ShadowTopicPrefix/delete/rejected	A delete solicitação foi rejeitada AWS IoT e a sombra não foi excluída. O corpo da mensagem contém as informações do erro.	Responda à mensagem de erro no corpo da mensagem.
ShadowTopicPrefix/get/accepted	A get solicitação foi aceita por AWS IoT, e o corpo da mensagem contém o documento paralelo atual.	As ações necessárias para processar o documento de estado no corpo da mensagem.
ShadowTopicPrefix/get/rejected	A get solicitação foi rejeitada por AWS IoT, e o corpo da mensagem contém as informações do erro.	Responda à mensagem de erro no corpo da mensagem.
ShadowTopicPrefix/update/accepted	A update solicitação foi aceita por AWS IoT, e o corpo da mensagem contém o documento paralelo atual.	Confirme se os dados atualizados no corpo da mensagem correspondem ao estado do dispositivo.
ShadowTopicPrefix/update/rejected	A update solicitação foi rejeitada por AWS IoT, e o corpo da mensagem contém as informações do erro.	Responda à mensagem de erro no corpo da mensagem.
ShadowTopicPrefix/update/delta	O documento paralelo foi atualizado por meio de uma solicitação para AWS IoT, e o corpo da mensagem contém as alterações solicitadas.	Atualize o estado do dispositivo para que corresponda ao estado desejado no corpo da mensagem.
ShadowTopicPrefix/update/documents	Uma atualização na sombra foi concluída recentemente e o corpo da mensagem contém o documento de sombra atual.	Confirme se o estado atualizado no corpo da mensagem corresponde ao estado do dispositivo.

Depois de assinar as mensagens na tabela anterior para cada sombra, o dispositivo deve testar para ver se as sombras às quais oferece suporte já foram criadas pela publicação de um tópico /get para cada sombra. Se uma mensagem /get/accepted for recebida, o corpo da mensagem conterá o documento de sombra que o dispositivo pode usar para inicializar seu estado. Se uma mensagem /get/rejected for recebida, a sombra deverá ser criada publicando uma mensagem /update com o estado do dispositivo atual.

Por exemplo, suponha que você tenha uma My_IoT_Thing objeto que não tenha sombras clássicas ou nomeadas. Se você publicar agora uma solicitação /get no tópico $aws/things/My_IoT_Thing/shadow/get reservado, será retornado um erro no tópico $aws/things/My_IoT_Thing/shadow/get/rejected porque o objeto não tem sombras. Para resolver esse erro, primeiro publique uma mensagem /update usando o tópico $aws/things/My_IoT_Thing/shadow/update com o estado atual do dispositivo, como a carga útil a seguir.

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

Uma sombra clássica agora é criada para o objeto e a mensagem é publicada no tópico $aws/things/My_IoT_Thing/shadow/update/accepted. Se você publicar no tópico $aws/things/My_IoT_Thing/shadow/get, ele retornará uma resposta ao tópico $aws/things/My_IoT_Thing/shadow/get/accepted com o estado do dispositivo.

Para sombras nomeadas, você deve primeiro criar a sombra nomeada ou publicar uma atualização com o nome da sombra antes de usar a solicitação get. Por exemplo, para criar uma sombra nomeada namedShadow1, primeiro publique as informações do estado do dispositivo no tópico $aws/things/My_IoT_Thing/shadow/name/namedShadow1/update. Para recuperar as informações do estado, use a solicitação /get para a sombra nomeada, $aws/things/My_IoT_Thing/shadow/name/namedShadow1/get.

Processando mensagens enquanto o dispositivo está conectado ao AWS IoT

Enquanto um dispositivo está conectado AWS IoT, ele pode receber mensagens /update/delta e deve manter o estado do dispositivo compatível com as mudanças em suas sombras da seguinte forma:

1. Lendo todas as mensagens /update/delta recebidas e sincronizando o estado do dispositivo para que corresponda.

2. Publicando uma mensagem /update com um corpo de mensagem reported que tenha o estado atual do dispositivo, sempre que o estado do dispositivo for alterado.

Enquanto um dispositivo está conectado, ele deve publicar essas mensagens quando indicado.

Indicação	Tópico	Carga útil
O estado do dispositivo foi alterado.	ShadowTopicPrefix/update	Um documento de sombra com a propriedade reported.
O dispositivo pode não estar sincronizado com a sombra.	ShadowTopicPrefix/get	(empty)
Uma ação no dispositivo indica que uma sombra não será mais compatível com o dispositivo, como quando o dispositivo é removido ou substituído.	ShadowTopicPrefix/delete	(empty)

Processando mensagens quando o dispositivo se reconecta ao AWS IoT

Quando um dispositivo com uma ou mais sombras se conecta AWS IoT, ele deve sincronizar seu estado com o de todas as sombras que ele suporta por meio de:

1. Lendo todas as mensagens /update/delta recebidas e sincronizando o estado do dispositivo para que corresponda.

2. Publicando uma mensagem /update com um corpo de mensagem reported que tenha o estado atual do dispositivo.