AWS IoTAplicación de demostración de sombra de dispositivos - FreeRTOS
IntroducciónFuncionalidadConexión al agente MQTT de AWS IoTEliminación del documento de sombraSuscripción a temas de sombraEnvío de actualizaciones de sombraGestión de los mensajes delta de sombra y los mensajes de actualización de sombra

AWS IoTAplicación de demostración de sombra de dispositivos

importante

Esta demostración está alojada en el repositorio de Amazon-FreeRTOS, que está en desuso. Recomendamos empezar por aquí 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.

Introducción

Esta demostración muestra cómo utilizar la biblioteca de sombra de dispositivo de AWS IoT para conectarse al servicio de sombra de dispositivo de AWS. Utiliza Biblioteca coreMQTT para establecer una conexión MQTT con TLS (autenticación mutua) al agente de AWS IoT MQTT y al analizador de la biblioteca coreJSON para analizar los documentos sombra recibidos del servicio de sombra de 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.

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. Esta demostración también utiliza una conexión MQTT segura con el agente de AWS IoT MQTT y supone que hay un estado powerOn en la sombra de dispositivo.

La demostración lleva a cabo las siguientes operaciones:

  1. Establece una conexión MQTT mediante las funciones auxiliares de shadow_demo_helpers.c.

  2. 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.

  3. Publica en el tema MQTT utilizado para eliminar una sombra de dispositivo para eliminar cualquier sombra de dispositivo existente.

  4. Se suscribe a temas de MQTT correspondientes a /update/delta, /update/accepted y /update/rejected utilizando las funciones auxiliares de shadow_demo_helpers.c.

  5. 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.

  6. Gestiona los mensajes MQTT entrantes en prvEventCallback y determina si el mensaje está relacionado con la sombra de dispositivo mediante una función definida en la biblioteca de sombra de dispositivo de AWS IoT (Shadow_MatchTopic). 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.

salida de terminal de demostración de sombra

La demostración se encuentra en el archivo freertos/demos/device_shadow_for_aws/shadow_demo_main.c o en GitHub.

En la siguiente captura de pantalla se muestra la salida esperada si la demostración se realiza correctamente.

salida de terminal de demostración de sombra correcta

Conexión al agente MQTT de AWS IoT

Para conectarse al agente AWS IoT MQTT, utilizamos el mismo método que MQTT_Connect() en Demostración de la autenticación mutua de coreMQTT.

Eliminación del documento de sombra

Para eliminar el documento de sombra, llame a xPublishToTopic con un mensaje vacío y utilice las macros definidas por la biblioteca de sombra de dispositivo de AWS IoT. 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 sombra de dispositivo para recibir notificaciones del agente de AWS IoT sobre cambios de 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 mediante la función MQTT_Init, nos notificará sobre un evento de paquete entrante. Consulte la función de devolución de llamada prvEventCallback en 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 de sombra de tipo ShadowMessageTypeUpdateDelta, llamamos a prvUpdateDeltaHandler 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 de sombra de tipo ShadowMessageTypeUpdateAccepted, llamamos a prvUpdateAcceptedHandler para que gestione este mensaje. El controlador prvUpdateAcceptedHandler analiza el mensaje mediante la biblioteca coreJSON para obtener el clientTokendel 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.