Aplicativo de demonstração do Device Shadow da AWS IoT

Importante

Essa demonstração está hospedada no repositório Amazon-FreeRTOS, que está preterido. Recomendamos começar aqui ao criar um novo projeto. Se você já tem um projeto FreeRTOS existente baseado no repositório Amazon-FreeRTOS que está preterido, consulte o Guia de migração do repositório Github do Amazon FreeRTOS.

Introdução

Esta demonstração mostra como usar a biblioteca do AWS IoT Device Shadow para se conectar ao serviço do AWS Device Shadow. Ela usa o Biblioteca coreMQTT para estabelecer uma conexão MQTT com TLS (autenticação mútua) com o agente MQTT do AWS IoT e o analisador da biblioteca coreJSON para analisar documentos paralelos recebidos do serviço de Sombra da AWS. A demonstração mostra operações básicas de sombra, como atualizar um documento de sombra e como excluir um documento de sombra. A demonstração também mostra como registrar uma função de retorno de chamada na biblioteca coreMQTT para lidar com mensagens como a /update de sombra e as mensagens de /update/delta enviadas do serviço do AWS IoT Device Shadow.

Esta demonstração serve apenas como um exercício de aprendizado porque a solicitação para atualizar o documento de sombra (estado) e a resposta de atualização são feitas pelo mesmo aplicativo. Em um cenário de produção realista, um aplicativo externo solicitaria uma atualização do estado do dispositivo remotamente, mesmo que o dispositivo não estivesse conectado no momento. O dispositivo reconhecerá a solicitação de atualização quando estiver conectado.

nota

Para configurar e executar as demonstrações do FreeRTOS, siga as etapas em Conceitos básicos do FreeRTOS.

Funcionalidade

A demonstração cria uma tarefa de aplicativo única que faz loop por um conjunto de exemplos que demonstram /update de sombras e /update/delta de retornos de chamada para simular a alternância do estado de um dispositivo remoto. Ela envia uma atualização de sombra com o novo estado desired e espera o dispositivo mudar o estado reported em resposta ao novo estado desired. Além disso, um retorno de chamada de /update de sombra é usado para exibir as mudanças dos estados de sombra. Essa demonstração também usa uma conexão MQTT segura com o agente MQTT do AWS IoT e considera que há um estado powerOn na sombra do dispositivo.

A demonstração realiza as seguintes operações:

1. Estabelece uma conexão MQTT usando as funções auxiliares em shadow_demo_helpers.c.

2. Monta strings de tópicos MQTT para operações de sombra do dispositivo, usando macros definidas pela biblioteca do AWS IoT Device Shadow.

3. Publica no tópico MQTT usado para excluir uma sombra do dispositivo para excluir toda sombra do dispositivo existente.

4. Assina os tópicos MQTT para /update/delta, /update/accepted e /update/rejected usando funções auxiliares em shadow_demo_helpers.c.

5. Publica um estado desejado de powerOn usando funções auxiliares em shadow_demo_helpers.c. Isso fará com que uma mensagem de /update/delta seja enviada ao dispositivo.

6. Gerencie as mensagens MQTT recebidas em prvEventCallback e determine se a mensagem está relacionada à sombra do dispositivo usando uma função definida pela biblioteca do AWS IoT Device Shadow (Shadow_MatchTopic). Se a mensagem for uma mensagem de /update/delta da sombra do dispositivo, a função de demonstração principal publicará uma segunda mensagem para atualizar o estado relatado como powerOn. Se uma mensagem de /update/accepted for recebida, verifique se ela tem o mesmo clientToken publicado anteriormente na mensagem de atualização. Isso marcará o fim da demonstração.

A demonstração pode ser encontrada no arquivo freertos/demos/device_shadow_for_aws/shadow_demo_main.c ou no GitHub.

A captura de tela a seguir mostra a saída esperada quando a demonstração é bem-sucedida.

Conecte-se ao agente MQTT da AWS IoT

Para nos conectarmos ao agente MQTT do AWS IoT, usamos o mesmo método que MQTT_Connect() na Demonstração de autenticação mútua da coreMQTT.

Exclusão de documento de sombra

Para excluir o documento de sombra, chame xPublishToTopic com uma mensagem vazia, usando macros definidas pela biblioteca do AWS IoT Device Shadow. Isso usa MQTT_Publish para publicar no tópico /delete. A seção de código a seguir mostra como isso é feito na função 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 );

Assinatura em tópicos de sombra

Assine os tópicos do Device Shadow para receber notificações do agente do AWS IoT sobre mudanças nas sombras. Os tópicos do Device Shadow são montados por macros definidas na biblioteca do Device Shadow. A seção de código a seguir mostra como isso é feito na função 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 ) );
} 

Envio de atualizações de sombras

Para enviar uma atualização de sombra, a demonstração chama xPublishToTopic com uma mensagem no formato JSON, usando macros definidas pela biblioteca do Device Shadow. Isso usa MQTT_Publish para publicar no tópico /delete. A seção de código a seguir mostra como isso é feito na função 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 ) );

Lidar com mensagens delta de sombra e mensagens de atualização de sombra

A função de retorno de chamada do usuário, que foi registrada na biblioteca de clientes coreMQTT usando a função MQTT_Init, notificará sobre um evento de pacote de entrada. Veja a função de retorno de chamada prvEventCallback no GitHub.

A função de retorno de chamada confirma que o pacote de entrada é do tipo MQTT_PACKET_TYPE_PUBLISH e usa a API Shadow_MatchTopic da biblioteca do Device Shadow para confirmar se a mensagem recebida é uma mensagem de sombra.

Se a mensagem recebida for uma mensagem de sombra com tipo ShadowMessageTypeUpdateDelta, chamaremos prvUpdateDeltaHandler para lidar com essa mensagem. O manipulador prvUpdateDeltaHandler usa a biblioteca coreJSON para analisar a mensagem e obter o valor delta do estado powerOn e o compara com o estado atual do dispositivo mantido localmente. Se forem diferentes, o estado do dispositivo local será atualizado para refletir o novo valor do estado powerOn do documento de sombra.

Se a mensagem recebida for uma mensagem de sombra com tipo ShadowMessageTypeUpdateAccepted, chamaremos prvUpdateAcceptedHandler para lidar com essa mensagem. O manipulador prvUpdateAcceptedHandler analisa a mensagem usando a biblioteca coreJSON para obter o clientToken da mensagem. Essa função de manipulador verifica se o token do cliente da mensagem JSON corresponde ao token do cliente usado pelo aplicativo. Se não corresponder, a função registrará uma mensagem de aviso.