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-Demoanwendung
**Wichtig**
Diese Demo wird im Amazon-FreeRTOS-Repository gehostet, das veraltet ist. Wir empfehlen, dass Sie [hier beginnen](freertos-getting-started-modular.md), wenn Sie ein neues Projekt erstellen. Wenn Sie bereits ein vorhandenes FreeRTOS-Projekt haben, das auf dem inzwischen veralteten Amazon-FreeRTOS-Repository basiert, finden Sie weitere Informationen unter. [Leitfaden zur Migration des Amazon-FreerTOS Github-Repositorys](github-repo-migration.md)
## Einführung
Diese Demo zeigt, wie Sie die AWS IoT Device Shadow-Bibliothek verwenden, um eine Verbindung zum [AWS Device Shadow-Dienst](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) herzustellen. Es verwendet den[CoreMQTT-Bibliothek](coremqtt.md), um eine MQTT-Verbindung mit TLS (Mutual Authentication) zum AWS IoT MQTT-Broker herzustellen, und den CoreJSON-Bibliotheksparser, um vom Shadow-Dienst empfangene Shadow-Dokumente zu analysieren. AWS Die Demo zeigt grundlegende Shadow-Operationen, z. B. wie man ein Shadow-Dokument aktualisiert und wie man ein Shadow-Dokument löscht. Die Demo zeigt auch, wie man eine Callback-Funktion in der CoreMQTT-Bibliothek registriert, um Nachrichten wie den Shadow `/update` und `/update/delta` Nachrichten, die vom AWS 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 per Fernzugriff eine Aktualisierung des Gerätestatus anfordern, auch wenn das Gerät derzeit nicht verbunden ist. Das Gerät bestätigt die Aktualisierungsanforderung, sobald es verbunden ist.
**Anmerkung**
Folgen Sie den Schritten unter, um die FreeRTOS-Demos einzurichten und auszuführen. [Erste Schritte mit FreeRTOS](freertos-getting-started.md)
## Funktionalität
Die Demo erstellt eine einzelne Anwendungsaufgabe, die eine Reihe von Beispielen durchläuft, die Shadow `/update` und `/update/delta` Callbacks demonstrieren, um das Umschalten des Status eines Remote-Geräts zu simulieren. Es sendet ein Shadow-Update mit dem neuen `desired` Status und wartet darauf, dass das Gerät seinen `reported` Status als Reaktion auf den neuen Status ändert. `desired` Darüber hinaus wird ein `/update` Shadow-Callback verwendet, um die sich ändernden Shadow-Zustände zu drucken. Diese Demo verwendet auch eine sichere MQTT-Verbindung zum AWS IoT MQTT-Broker und geht davon aus, dass im Geräteshadow ein `powerOn` Status vorliegt.
Die Demo führt die folgenden Operationen aus:
1. Stellen Sie mithilfe der Hilfsfunktionen in `shadow_demo_helpers.c` eine MQTT-Verbindung her.
1. Stellen Sie MQTT-Themenzeichenfolgen für Device Shadow-Operationen zusammen, indem Sie Makros verwenden, die von der AWS IoT Device Shadow-Bibliothek definiert sind.
1. Veröffentlichen Sie das MQTT-Thema, das zum Löschen eines Device-Shadows verwendet wurde, um alle vorhandenen Device-Shadow zu löschen.
1. Abonnieren Sie die MQTT-Themen für `/update/delta` `/update/accepted` und zur `/update/rejected` Verwendung von Hilfsfunktionen in. `shadow_demo_helpers.c`
1. Veröffentlichen Sie den gewünschten Status der `powerOn` Verwendung von Hilfsfunktionen in`shadow_demo_helpers.c`. Dadurch wird eine `/update/delta` Nachricht an das Gerät gesendet.
1. Verarbeiten Sie eingehende MQTT-Nachrichten und ermitteln Sie mithilfe einer in `prvEventCallback` der Device Shadow-Bibliothek (`Shadow_MatchTopic`) definierten Funktion, ob die Nachricht mit dem AWS IoT Device Shadow verknüpft ist. Wenn es sich bei der Nachricht um eine `/update/delta` Device-Shadow-Nachricht handelt, veröffentlicht die Haupt-Demofunktion eine zweite Nachricht, auf die der gemeldete Status aktualisiert wird. `powerOn` Wenn eine `/update/accepted` Nachricht empfangen wird, stellen Sie sicher, dass sie dieselbe `clientToken` Nachricht enthält, die zuvor in der Aktualisierungsnachricht veröffentlicht wurde. Das wird das Ende der Demo bedeuten.
![\[Ausgang des Shadow-Demo-Terminals\]](http://docs.aws.amazon.com/de_de/freertos/latest/userguide/images/shadow-demo-output.png)
Die Demo finden Sie in der Datei `freertos/demos/device_shadow_for_aws/shadow_demo_main.c` oder auf [ GitHub](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c).
Der folgende Screenshot zeigt die erwartete Ausgabe, wenn die Demo erfolgreich ist.
![\[Die Ausgabe des Shadow-Demo-Terminals zeigt Erfolg\]](http://docs.aws.amazon.com/de_de/freertos/latest/userguide/images/shadow-demo-screenshot.png)
## Connect zum AWS IoT MQTT-Broker her
Um eine Verbindung zum AWS IoT MQTT-Broker herzustellen, verwenden wir dieselbe Methode wie `MQTT_Connect()` in der. [Demo zur gegenseitigen CoreMQTT-Authentifizierung](mqtt-demo-ma.md)
## Löschen Sie das Schattendokument
Um das Shadow-Dokument zu löschen, rufen Sie `xPublishToTopic` mit einer leeren Nachricht auf und verwenden Sie dabei Makros, die in der AWS IoT Device Shadow-Bibliothek definiert sind. Dies wird verwendet`MQTT_Publish`, um zum `/delete` Thema zu veröffentlichen. Der folgende Codeabschnitt zeigt, wie dies in der Funktion gemacht wird`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 );
```
## Abonnieren Sie Schattenthemen
Abonnieren Sie die Device Shadow-Themen, um Benachrichtigungen vom AWS IoT Broker ü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 der `prvShadowDemoTask` Funktion erfolgt.
```
/* 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 Demo `xPublishToTopic` mit einer Nachricht im JSON-Format auf und verwendet Makros, die von der Device Shadow-Bibliothek definiert wurden. Dies wird verwendet`MQTT_Publish`, um zum `/delete` Thema zu veröffentlichen. Der folgende Codeabschnitt zeigt, wie dies in der `prvShadowDemoTask` Funktion gemacht wird.
```
#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 ) );
```
## Verarbeiten Sie Shadow-Delta-Nachrichten und Shadow-Update-Nachrichten
Die Benutzer-Callback-Funktion, die mithilfe der `MQTT_Init` Funktion in der [CoreMQTT-Clientbibliothek](https://www.freertos.org/iot-device-shadow/device-shadow-demo.html#handle-shadow-messages) registriert wurde, benachrichtigt uns über ein eingehendes Paketereignis. Sehen Sie sich die Callback-Funktion an. [ prvEventCallback](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L671-L753) GitHub
Die Callback-Funktion bestätigt, dass das eingehende Paket vom Typ ist`MQTT_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 handelt`ShadowMessageTypeUpdateDelta`, rufen wir [ prvUpdateDeltaHandler](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L464-L580) auf, um diese Nachricht zu verarbeiten. Der Handler `prvUpdateDeltaHandler` verwendet die CoreJSON-Bibliothek, um die Nachricht zu analysieren, um den Deltawert für den `powerOn` Status zu ermitteln, und vergleicht diesen mit dem aktuellen Gerätestatus, der lokal verwaltet wird. Wenn diese unterschiedlich sind, wird der lokale Gerätestatus aktualisiert, um den neuen Wert des `powerOn` Status aus dem Schattendokument widerzuspiegeln.
Wenn es sich bei der eingehenden Nachricht um eine Shadow-Nachricht mit Typ handelt`ShadowMessageTypeUpdateAccepted`, rufen wir [ prvUpdateAcceptedHandler](https://github.com/aws/amazon-freertos/blob/main/demos/device_shadow_for_aws/shadow_demo_main.c#L584-L667) auf, um diese Nachricht zu bearbeiten. Der Handler `prvUpdateAcceptedHandler` analysiert die Nachricht mithilfe der CoreJSON-Bibliothek, um sie `clientToken` 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.