AWS IoT-Device Shadow – Demo-Anwendung

Wichtig

Diese Demo wird im Amazon-FreeRTOS-Repository gehostet, das veraltet ist. Wir empfehlen, dass Sie hier beginnen, wenn Sie ein neues Projekt in nutzen. Wenn Sie bereits über ein bestehendes FreeRTOS-Projekt verfügen, das auf dem inzwischen veralteten Amazon-FreeRTOS-Repository basiert, lesen Sie dieLeitfaden zur Migration des Amazon-FreerTOS Github-Repositorys.

Einführung

Diese Demo zeigt, wie Sie dieAWS IoT Device Shadow-Bibliothek verwenden, um eine Verbindung zum AWSDevice Shadow-Dienst herzustellen. Es verwendet den,CoreMQTT-Bibliothek um eine MQTT-Verbindung mit TLS (Mutual Authentication) zumAWS IoT MQTT-Broker herzustellen, und den CoreJSON-Bibliotheksparser, um vom Shadow-Dienst empfangeneAWS Shadow-Dokumente zu parsen. Die Demo zeigt grundlegende Schattenoperationen, z. B. das Aktualisieren eines Schattendokuments und das Löschen eines Schattendokuments. Die Demo zeigt auch, wie eine Callback-Funktion bei der CoreMQTT-Bibliothek registriert wird, um Nachrichten wie den Shadow/update und/update/delta Nachrichten, die vomAWS IoT Device Shadow-Dienst gesendet werden, zu verarbeiten.

Diese Demo ist nur als Lernübung gedacht, da die Anfrage zur Aktualisierung des Shadow-Dokuments (Status) und die Aktualisierungsantwort von derselben Anwendung ausgeführt werden. In einem realistischen Produktionsszenario würde eine externe Anwendung aus der Ferne eine Aktualisierung des Gerätestatus anfordern, auch wenn das Gerät derzeit nicht angeschlossen ist. Das Gerät bestätigt die Aktualisierungsanfrage, wenn es angeschlossen ist.

Anmerkung

Um die FreeRTOS-Demos einzurichten und auszuführen, folgen Sie den Schritten unterErste Schritte mit FreeRTOS.

Funktionalität

In der Demo wird eine einzelne Anwendungsaufgabe erstellt, die eine Reihe von Beispielen durchläuft, in denen Shadow/update und/update/delta Callbacks demonstriert werden, mit denen der Status eines Remote-Geräts simuliert wird. Es sendet ein Shadow-Update mit dem neuendesired Status und wartet darauf, dass das Gerät seinenreported Status als Reaktion auf den neuendesired Status ändert. Zusätzlich wird ein/update Shadow-Callback verwendet, um die sich ändernden Schattenzustände zu drucken. Diese Demo verwendet auch eine sichere MQTT-Verbindung zumAWS IoT MQTT-Broker und geht davon aus, dass im Geräteshadow einpowerOn Status vorliegt.

Die Demo führt die folgenden Operationen aus:

1. Stellen Sie eine MQTT-Verbindung her, indem Sie die Hilfsfunktionen in verwendenshadow_demo_helpers.c.

2. Stellen Sie MQTT-Themenzeichenketten für Device-Shadow-Operationen zusammen, indem Sie Makros verwenden, die in derAWS IoT Device Shadow-Bibliothek definiert sind.

3. Veröffentlichen Sie in dem MQTT-Thema, das für das Löschen eines Geräteschadens verwendet wird, um einen vorhandenen Geräteschatten zu löschen.

4. Abonnieren Sie die MQTT-Themen für/update/delta/update/accepted und zur/update/rejected Verwendung von Hilfsfunktionen inshadow_demo_helpers.c.

5. Veröffentlichen Sie den gewünschten Status derpowerOn Verwendung von Hilfsfunktionen inshadow_demo_helpers.c. Dadurch wird eine/update/delta Nachricht an das Gerät gesendet.

6. Verarbeiten Sie eingehende MQTT-Nachrichten in und stellen Sie festprvEventCallback, ob die Nachricht mit dem Geräteshadow in Verbindung steht, indem Sie eine Funktion verwenden, die in derAWS IoT Device Shadow-Bibliothek (Shadow_MatchTopic) definiert ist. Wenn es sich bei der Nachricht um eine/update/delta Geräte-Shadow-Nachricht handelt, veröffentlicht die Haupt-Demo-Funktion eine zweite Nachricht, auf die der gemeldete Status aktualisiert wirdpowerOn. Wenn eine/update/accepted Nachricht empfangen wird, stellen Sie sicher, dass sie mit der zuvor veröffentlichten Nachricht in der Aktualisierungsnachricht übereinstimmt.clientToken Das wird das Ende der Demo markieren.

Die Demo finden Sie in der Dateifreertos/demos/device_shadow_for_aws/shadow_demo_main.c oder auf GitHub.

Der folgende Screenshot zeigt die erwartete Ausgabe, wenn die Demo erfolgreich ist.

Connect zumAWS IoT MQTT-Broker her

Um eine Verbindung zumAWS IoT MQTT-Broker herzustellen, verwenden wir dieselbe Methode wieMQTT_Connect() in derCoreMQTT-Demo zur gegenseitigen Authentifizierung.

Löschen Sie das Schattendokument

Um das Shadow-Dokument zu löschen, rufen Sie esxPublishToTopic mit einer leeren Nachricht auf und verwenden Sie Makros, die in derAWS IoT Device Shadow-Bibliothek definiert sind. Dies wird verwendetMQTT_Publish, um zum/delete Thema zu veröffentlichen. Der folgende Codeabschnitt zeigt, wie dies in der Funktion geschiehtprvShadowDemoTask.

/* 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 );

Schattenthemen abonnieren

Abonnieren Sie die Device Shadow-Themen, um vomAWS IoT Broker Benachrichtigungen über Shadow-Änderungen zu erhalten. Die Device Shadow-Themen werden anhand von Makros zusammengestellt, die in der Device Shadow-Bibliothek definiert sind. Der folgende Codeabschnitt zeigt, wie dies in derprvShadowDemoTask Funktion geschieht.

/* 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 ) );
} 

Shadow-Updates senden

Um ein Shadow-Update zu senden, ruft die DemoxPublishToTopic mit einer Nachricht im JSON-Format auf und verwendet Makros, die von der Device Shadow-Bibliothek definiert sind. Dies wird verwendetMQTT_Publish, um zum/delete Thema zu veröffentlichen. Der folgende Codeabschnitt zeigt, wie dies in derprvShadowDemoTask Funktion geschieht.

#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 ) );

Umgang mit Shadow-Delta-Nachrichten und Shadow-Update-Nachrichten

Die Benutzer-Callback-Funktion, die mithilfe derMQTT_Init Funktion in der CoreMQTT-Clientbibliothek registriert wurde, benachrichtigt uns über ein eingehendes Paketereignis. Sehen Sie sich die Callback-Funktion prvEventCallbackan GitHub.

Die Callback-Funktion bestätigt, dass das eingehende Paket vom Typ istMQTT_PACKET_TYPE_PUBLISH, und verwendet die Device Shadow Library API,Shadow_MatchTopic um zu bestätigen, dass es sich bei der eingehenden Nachricht um eine Shadow-Nachricht handelt.

Wenn es sich bei der eingehenden Nachricht um eine Shadow-Nachricht vom Typ handeltShadowMessageTypeUpdateDelta, rufen wir prvUpdateDeltaHandler auf, um diese Nachricht zu bearbeiten. Der HandlerprvUpdateDeltaHandler verwendet die CoreJSON-Bibliothek, um die Nachricht zu analysieren, um den Delta-Wert für denpowerOn Status zu erhalten, und vergleicht diesen mit dem aktuellen, lokal verwalteten Gerätestatus. Wenn diese unterschiedlich sind, wird der lokale Gerätestatus aktualisiert, sodass er den neuen Wert despowerOn Status aus dem Shadow-Dokument wiedergibt.

Wenn es sich bei der eingehenden Nachricht um eine Shadow-Nachricht vom Typ handeltShadowMessageTypeUpdateAccepted, rufen wir prvUpdateAcceptedHandler auf, um diese Nachricht zu bearbeiten. Der HandlerprvUpdateAcceptedHandler analysiert die Nachricht mithilfe der CoreJSON-Bibliothek, um sieclientToken aus der Nachricht abzurufen. Diese Handlerfunktion überprüft, ob das Client-Token aus der JSON-Nachricht mit dem von der Anwendung verwendeten Client-Token übereinstimmt. Wenn es nicht übereinstimmt, protokolliert die Funktion eine Warnmeldung.