Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
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 kostenlosen RTOS Github-Repositorys von Amazon.
Einführung
Diese Demo zeigt, wie Sie dieAWS IoT Device Shadow-Bibliothek verwenden, um eine Verbindung zum AWSDevice Shadow-Dienst herzustellen. Es verwendet den,MQTTKernbibliothek 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 unterJetzt kostenlos durchstarten RTOS.
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:
-
Stellen Sie eine MQTT-Verbindung her, indem Sie die Hilfsfunktionen in verwenden
shadow_demo_helpers.c
. -
Stellen Sie MQTT-Themenzeichenketten für Device-Shadow-Operationen zusammen, indem Sie Makros verwenden, die in derAWS IoT Device Shadow-Bibliothek definiert sind.
-
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.
-
Abonnieren Sie die MQTT-Themen für
/update/delta
/update/accepted
und zur/update/rejected
Verwendung von Hilfsfunktionen inshadow_demo_helpers.c
. -
Veröffentlichen Sie den gewünschten Status der
powerOn
Verwendung von Hilfsfunktionen inshadow_demo_helpers.c
. Dadurch wird eine/update/delta
Nachricht an das Gerät gesendet. -
Verarbeiten Sie eingehende MQTT-Nachrichten in und stellen Sie fest
prvEventCallback
, 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 Datei
oder auf GitHubfreertos
/demos/device_shadow_for_aws/shadow_demo_main.c
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
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 prvUpdateDeltaHandlerprvUpdateDeltaHandler
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 prvUpdateAcceptedHandlerprvUpdateAcceptedHandler
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.