Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# AWS IoT Aplicación de demostración Device Shadow
**importante**
Esta demostración está alojada en el repositorio de Amazon-FreeRTOS, que está en desuso. Recomendamos [empezar por aquí](freertos-getting-started-modular.md) al crear un nuevo proyecto. Si ya tiene un proyecto FreeRTOS existente basado en el repositorio Amazon FreeRTOS, ahora obsoleto, consulte [Guía de migración del repositorio Github de Amazon-FreeRTOS](github-repo-migration.md).
## Introducción
Esta demostración muestra cómo utilizar la biblioteca AWS IoT Device Shadow para conectarse al [servicio AWS Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html). La utiliza [Biblioteca coreMQTT](coremqtt.md) para establecer una conexión MQTT con TLS (autenticación mutua) con el AWS IoT MQTT Broker y el analizador de la biblioteca CoreJson para analizar los documentos paralelos recibidos del servicio Shadow. AWS La demostración muestra las operaciones de sombra básicas, por ejemplo, cómo actualizar un documento de sombra y cómo eliminarlo. La demostración también muestra cómo registrar una función de devolución de llamada en la biblioteca coreMQTT para gestionar mensajes como los mensajes de sombra `/update` y `/update/delta` que se envían desde el servicio de sombra de dispositivo de AWS IoT .
Esta demostración solo pretende ser un ejercicio de aprendizaje, ya que la solicitud de actualización del documento de sombra (estado) y la respuesta a la actualización las realiza la misma aplicación. En un escenario de producción realista, una aplicación externa solicitaría una actualización del estado del dispositivo de forma remota, incluso si el dispositivo no está conectado actualmente. El dispositivo confirmará la solicitud de actualización cuando esté conectado.
**nota**
Para configurar y ejecutar las demostraciones de FreeRTOS, siga los pasos que se indican en [Introducción a FreeRTOS](freertos-getting-started.md).
## Funcionalidad
La demostración crea una tarea de aplicación única que incluye una serie de ejemplos en los que se muestran las devoluciones de llamada `/update` y `/update/delta` de sombra para simular el cambio de estado de un dispositivo remoto. Envía una actualización de sombra con el nuevo estado `desired` y espera a que el dispositivo cambie su estado `reported` en respuesta al nuevo estado `desired`. Además, se utiliza una devolución de llamada `/update` de sombra para imprimir los estados de sombra que cambian. En esta demostración también se utiliza una conexión MQTT segura con el AWS IoT MQTT Broker y se supone que existe un estado oculto en el dispositivo. `powerOn`
La demostración lleva a cabo las siguientes operaciones:
1. Establece una conexión MQTT mediante las funciones auxiliares de `shadow_demo_helpers.c`.
1. Reúne cadenas de temas de MQTT para las operaciones de sombra de dispositivo mediante las macros definidas por la biblioteca de sombra de dispositivo de AWS IoT .
1. Publica en el tema MQTT utilizado para eliminar una sombra de dispositivo para eliminar cualquier sombra de dispositivo existente.
1. Se suscribe a temas de MQTT correspondientes a `/update/delta`, `/update/accepted` y `/update/rejected` utilizando las funciones auxiliares de `shadow_demo_helpers.c`.
1. Publica el estado deseado de `powerOn` utilizando las funciones auxiliares de `shadow_demo_helpers.c`. Esto provocará que se envíe un mensaje `/update/delta` al dispositivo.
1. Gestione los mensajes MQTT entrantes y determine si el mensaje está relacionado con la sombra del dispositivo mediante una función definida en la biblioteca AWS IoT Device Shadow (`Shadow_MatchTopic`). `prvEventCallback` Si se trata de un mensaje `/update/delta` de sombra de dispositivo, la función de demostración principal publicará un segundo mensaje para actualizar el estado notificado a `powerOn`. Si recibe un mensaje `/update/accepted`, compruebe que es el mismo `clientToken` que el publicado anteriormente en el mensaje de actualización. Esto marcará el final de la demostración.
La demostración se encuentra en el archivo `{{freertos}}/demos/device_shadow_for_aws/shadow_demo_main.c` o en [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c).
En la siguiente captura de pantalla se muestra la salida esperada si la demostración se realiza correctamente.
## Conéctese al bróker AWS IoT MQTT
Para conectarnos al bróker AWS IoT MQTT, utilizamos el mismo método que `MQTT_Connect()` en el. [Demostración de la autenticación mutua de coreMQTT](mqtt-demo-ma.md)
## Eliminación del documento de sombra
Para eliminar el documento oculto, llame `xPublishToTopic` con un mensaje vacío y utilice las macros definidas por la biblioteca AWS IoT Device Shadow. Utiliza `MQTT_Publish` para publicar en el tema `/delete`. En la siguiente sección de código se muestra cómo se realiza en la función `prvShadowDemoTask`.
```
/* First of all, try to delete any Shadow document in the cloud. */
returnStatus = PublishToTopic( SHADOW_TOPIC_STRING_DELETE( THING_NAME ),
SHADOW_TOPIC_LENGTH_DELETE( THING_NAME_LENGTH ),
pcUpdateDocument,
0U );
```
## Suscripción a temas de sombra
Suscríbase a los temas de Device Shadow para recibir notificaciones del AWS IoT corredor sobre cambios en la sombra. Los temas de sombra de dispositivo se agrupan mediante macros definidas en la biblioteca de sombra de dispositivo. En la siguiente sección de código se muestra cómo se realiza en la función `prvShadowDemoTask`.
```
/* Then try to subscribe shadow topics. */
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_DELTA( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_DELTA( THING_NAME_LENGTH ) );
}
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_ACCEPTED( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_ACCEPTED( THING_NAME_LENGTH ) );
}
if( returnStatus == EXIT_SUCCESS )
{
returnStatus = SubscribeToTopic(
SHADOW_TOPIC_STRING_UPDATE_REJECTED( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE_REJECTED( THING_NAME_LENGTH ) );
}
```
## Envío de actualizaciones de sombra
Para enviar una actualización de sombra, la demostración llama a `xPublishToTopic` con un mensaje en formato JSON, utilizando las macros definidas por la biblioteca de sombra de dispositivo. Utiliza `MQTT_Publish` para publicar en el tema `/delete`. En la siguiente sección de código se muestra cómo se realiza en la función `prvShadowDemoTask`.
```
#define SHADOW_REPORTED_JSON \
"{" \
"\"state\":{" \
"\"reported\":{" \
"\"powerOn\":%01d" \
"}" \
"}," \
"\"clientToken\":\"%06lu\"" \
"}"
snprintf( pcUpdateDocument,
SHADOW_REPORTED_JSON_LENGTH + 1,
SHADOW_REPORTED_JSON,
( int ) ulCurrentPowerOnState,
( long unsigned ) ulClientToken );
xPublishToTopic( SHADOW_TOPIC_STRING_UPDATE( THING_NAME ),
SHADOW_TOPIC_LENGTH_UPDATE( THING_NAME_LENGTH ),
pcUpdateDocument,
( SHADOW_DESIRED_JSON_LENGTH + 1 ) );
```
## Gestión de los mensajes delta de sombra y los mensajes de actualización de sombra
La función de devolución de llamada del usuario, que se registró en la [biblioteca de clientes de coreMQTT](https://www.freertos.org/iot-device-shadow/device-shadow-demo.html#handle-shadow-messages) mediante la función `MQTT_Init`, nos notificará sobre un evento de paquete entrante. Activa la función [ prvEventCallback](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L671-L753)de devolución de llamada. GitHub
La función de devolución de llamada confirma que el paquete entrante es de tipo `MQTT_PACKET_TYPE_PUBLISH` y utiliza la API de la biblioteca de sombra de dispositivo `Shadow_MatchTopic` para confirmar que el mensaje entrante es un mensaje de sombra.
Si el mensaje entrante es un mensaje oculto del tipo`ShadowMessageTypeUpdateDelta`, entonces llamamos a [ prvUpdateDeltaHandler](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L464-L580) para que gestione este mensaje. El controlador `prvUpdateDeltaHandler` usa la biblioteca coreJSON para analizar el mensaje y obtener el valor delta del estado `powerOn` y lo compara con el estado actual del dispositivo mantenido localmente. Si son diferentes, el estado del dispositivo local se actualiza para reflejar el nuevo valor del estado `powerOn` del documento de sombra.
Si el mensaje entrante es un mensaje oculto de tipo`ShadowMessageTypeUpdateAccepted`, entonces llamamos a [ prvUpdateAcceptedHandler](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L584-L667) para que gestione este mensaje. El controlador `prvUpdateAcceptedHandler` analiza el mensaje mediante la biblioteca coreJSON para obtener el `clientToken`del mensaje. Esta función de controlador comprueba que el token de cliente del mensaje JSON coincide con el token de cliente utilizado por la aplicación. Si no coincide, la función registra un mensaje de advertencia.