Uso de sombras en dispositivos

En esta sección se describen las comunicaciones de los dispositivos con las sombras mediante MQTT mensajes, el método preferido para que los dispositivos se comuniquen con el servicio AWS IoT Device Shadow.

Las comunicaciones ocultas emulan un modelo de solicitud/respuesta utilizando el modelo de comunicación de publicación/suscripción de. MQTT Cada acción de sombra consta de un tema de solicitud, un tema de respuesta correcta (accepted) y un tema de respuesta de error (rejected).

Si desea que las aplicaciones y servicios puedan determinar si un dispositivo está conectado, consulte Detección de un dispositivo conectado.

importante

Como MQTT utiliza un modelo de comunicación de publicación/suscripción, debe suscribirse a los temas de respuesta antes de publicar un tema de solicitud. Si no lo hace, es posible que no reciba la respuesta a la solicitud que publique.

Si utiliza un servicio SDK para dispositivos con AWS IoTpara llamar al servicio Device ShadowAPIs, se gestionará por usted.

Los ejemplos de esta sección utilizan una forma abreviada del tema en el que ShadowTopicPrefix puede hacer referencia a una sombra con nombre o sin nombre, tal y como se describe en esta tabla.

Las sombras pueden ser con nombre o sin nombre (clásico). Los temas utilizados por cada uno solo difieren en el prefijo del tema. Esta tabla muestra el prefijo de tema utilizado por cada tipo de sombra.

ShadowTopicPrefix valor	Tipo de sombra
$aws/things/thingName/shadow	Sombra sin nombre (clásica)
$aws/things/thingName/shadow/name/shadowName	Sombra con nombre

importante

Asegúrese de que el uso de las sombras por parte de la aplicación o servicio sea coherente y compatible con las implementaciones correspondientes en los dispositivos. Por ejemplo, tenga en cuenta cómo se crean, actualizan y eliminan las sombras. Tenga en cuenta también cómo se tratan las actualizaciones en el dispositivo y en las aplicaciones o servicios que acceden al dispositivo a través de una sombra. El diseño debe ser claro respecto a cómo se actualiza y notifica el estado del dispositivo y cómo interactúan las aplicaciones y los servicios con el dispositivo y sus sombras.

Para crear un tema completo, seleccione el ShadowTopicPrefix para el tipo de sombra al que desea hacer referencia, reemplace thingName y shadowName si procede, con sus valores correspondientes y, a continuación, anexe el código auxiliar del tema como se muestra en la tabla siguiente. Recuerde que los temas distinguen entre mayúsculas y minúsculas.

Consulte Temas de sombra para obtener más información acerca de los temas reservados para las sombras.

Inicializar el dispositivo en la primera conexión a AWS IoT

Una vez que un dispositivo se registre en él AWS IoT, debería suscribirse a estos MQTT mensajes para las sombras que admite.

Tema	Significado	Acción que debe realizar un dispositivo cuando se recibe este tema
ShadowTopicPrefix/delete/accepted	Se aceptó la delete solicitud y AWS IoT se eliminó la sombra.	Las acciones necesarias para incorporar la sombra eliminada, como detener la publicación de actualizaciones.
ShadowTopicPrefix/delete/rejected	La delete solicitud fue rechazada por AWS IoT y la sombra no se eliminó. El cuerpo del mensaje contiene la información de error.	Responda al mensaje de error en el cuerpo del mensaje.
ShadowTopicPrefix/get/accepted	La get solicitud fue aceptada por AWS IoT y el cuerpo del mensaje contiene el documento alternativo actual.	Las acciones necesarias para procesar el documento de estado en el cuerpo del mensaje.
ShadowTopicPrefix/get/rejected	La get solicitud fue rechazada por AWS IoT y el cuerpo del mensaje contiene la información del error.	Responda al mensaje de error en el cuerpo del mensaje.
ShadowTopicPrefix/update/accepted	La update solicitud fue aceptada por AWS IoT y el cuerpo del mensaje contiene el documento alternativo actual.	Confirme que los datos actualizados en el cuerpo del mensaje coinciden con el estado del dispositivo.
ShadowTopicPrefix/update/rejected	La update solicitud fue rechazada por AWS IoT y el cuerpo del mensaje contiene la información del error.	Responda al mensaje de error en el cuerpo del mensaje.
ShadowTopicPrefix/update/delta	El documento alternativo se actualizó mediante una solicitud dirigida a AWS IoT, y el cuerpo del mensaje contiene los cambios solicitados.	Actualice el estado del dispositivo para que coincida con el estado deseado en el cuerpo del mensaje.
ShadowTopicPrefix/update/documents	Recientemente se completó una actualización de la sombra y el cuerpo del mensaje contiene el documento de sombra actual.	Confirme que el estado actualizado en el cuerpo del mensaje coincide con el estado del dispositivo.

Después de suscribirse a los mensajes de la tabla anterior para cada sombra, el dispositivo debe probar si las sombras que admite ya se han creado publicando un tema /get en cada sombra. Si se recibe un mensaje /get/accepted, el cuerpo del mensaje contiene el documento de sombra, que el dispositivo puede utilizar para inicializar su estado. Si se recibe un mensaje /get/rejected, la sombra debe crearse publicando un mensaje /update con el estado actual del dispositivo.

Por ejemplo, supongamos que tiene un objeto My_IoT_Thing sin sombras, ni clásicas ni con nombre. Si ahora publica una solicitud /get en el tema reservado $aws/things/My_IoT_Thing/shadow/get, se devolverá un error sobre el tema $aws/things/My_IoT_Thing/shadow/get/rejected, ya que el objeto no tiene sombras. Para resolver este error, publique primero un mensaje /update utilizando el tema $aws/things/My_IoT_Thing/shadow/update con el estado actual del dispositivo, como la siguiente carga.

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

Ahora se creará una sombra clásica para el objeto y el mensaje se publicará en el tema $aws/things/My_IoT_Thing/shadow/update/accepted. Si publica en el tema $aws/things/My_IoT_Thing/shadow/get, se devuelve una respuesta al tema $aws/things/My_IoT_Thing/shadow/get/accepted con el estado del dispositivo.

En el caso de las sombras con nombre, debe crear primero la sombra con nombre o publicar una actualización con el nombre de la sombra antes de utilizar la solicitud get. Por ejemplo, para crear una sombra con nombre namedShadow1, publique primero la información del estado del dispositivo en el tema $aws/things/My_IoT_Thing/shadow/name/namedShadow1/update. Para recuperar la información de estado, use la solicitud /get para la sombra con nombre ($aws/things/My_IoT_Thing/shadow/name/namedShadow1/get).

Procesar los mensajes mientras el dispositivo está conectado a AWS IoT

Mientras un dispositivo está conectado AWS IoT, puede recibir mensajes /update/delta y debe mantener el estado del dispositivo adaptado a los cambios que se producen en sus sombras de la siguiente manera:

1. Leer todos los mensajes /update/delta recibidos y sincronizar el estado del dispositivo para que coincida.

2. Publicando un mensaje /update con un cuerpo de mensaje reported que tenga el estado actual del dispositivo, siempre que cambie el estado del dispositivo.

Mientras un dispositivo está conectado, debe publicar estos mensajes cuando se indique.

Indicación	Tema	Carga
El estado del dispositivo ha cambiado.	ShadowTopicPrefix/update	Un documento de sombra con la propiedad reported.
Es posible que el dispositivo no esté sincronizado con la sombra.	ShadowTopicPrefix/get	(empty)
Una acción en el dispositivo indica que el dispositivo ya no admite una sombra; por ejemplo, cuando se quita o se reemplaza el dispositivo.	ShadowTopicPrefix/delete	(empty)

Procesar los mensajes cuando el dispositivo se vuelve a conectar a AWS IoT

Cuando se conecta un dispositivo con una o más sombras AWS IoT, debe sincronizar su estado con el de todas las sombras que admite de la siguiente manera:

1. Leer todos los mensajes /update/delta recibidos y sincronizar el estado del dispositivo para que coincida.

2. Publicando un mensaje /update con un cuerpo de mensaje reported que tenga el estado actual del dispositivo.