Schritt 1: Führen Sie die Beispiel-App shadow.py aus Schritt 2: Überprüfen Sie die Beispiel-App des shadow.py Device SDK Schritt 3: Beheben Sie Probleme mit dershadow.pyBeispiel-App Schritt 4: Überprüfen Sie die Ergebnisse und nächsten Schritte

Tutorial: Installieren des Device SDK und Ausführen der Beispielanwendung für Device Shadows

In diesem Abschnitt wird gezeigt, wie Sie die erforderliche Software installieren können undAWS IoTDevice SDK für Python und führen Sie dieshadow.pyBeispielanwendung, um das Shadow-Dokument zu bearbeiten und den Status des Schattens zu steuern.

In diesem Tutorial erfahren Sie Folgendes:

Verwenden Sie die installierte Software undAWS IoTGeräte-SDK für Python zum Ausführen der Beispiel-App.
Erfahren Sie, wie die Eingabe eines Wertes mit der Beispiel-App den gewünschten Wert imAWS IoTconsole.
Prüfen Sie dieshadow.pyBeispiel-App und wie sie das MQTT-Protokoll verwendet, um den Status des Shadows zu aktualisieren.

Bevor Sie dieses Tutorial ausführen:

Sie müssen Ihre eingerichtet habenAWS-Konto, hat Ihr Raspberry Pi-Gerät konfiguriert und einAWS IoTSache und Richtlinie, die dem Gerät Berechtigungen zum Veröffentlichen und Abonnieren der reservierten MQTT-Themen des Device Shadow Shadow-Dienstes erteilt. Weitere Informationen finden Sie unter Tutorial: Vorbereiten Ihres Raspberry Pi zum Ausführen der Shadow-Anwendung.

Sie müssen auch Git, Python und das installiert habenAWS IoTDevice SDK für Python. Dieses Tutorial baut auf den im Tutorial vorgestellten Konzepten aufVerbinden eines Raspberry Pi oder eines anderes Gerätesaus. Wenn Sie dieses Tutorial noch nicht ausprobiert haben, empfehlen wir Ihnen, die in diesem Tutorial beschriebenen Schritte auszuführen, um die Zertifikatsdateien und das Device SDK zu installieren und dann zu diesem Tutorial zurückzukehren, um dieshadow.pyBeispiel-App.

In diesem Tutorial werden Sie:

Schritt 1: Führen Sie die Beispiel-App shadow.py aus
Schritt 2: Überprüfen Sie die Beispiel-App des shadow.py Device SDK
Schritt 3: Beheben Sie Probleme mit dershadow.pyBeispiel-App
Schritt 4: Überprüfen Sie die Ergebnisse und nächsten Schritte

Für dieses Tutorial brauchen Sie ungefähr 20 Minuten.

Schritt 1: Führen Sie die Beispiel-App shadow.py aus

Bevor du dieshadow.pyBeispiel-App benötigen Sie zusätzlich zu den Namen und dem Speicherort der von Ihnen installierten Zertifikatsdateien die folgenden Informationen.

Werte für Anwendungsparameter
Parameter	Wo finden Sie den Wert
`your-iot-thing-Name`	Name desAWS IoTSache, die Sie vorher erstellt habenSchritt 2: Erstellen Sie eine Sache Ressource und fügen Sie die Richtlinie an das Ding anaus. Um diesen Wert zu finden, finden Sie imAWS IoTKonsole, wählenVerwaltenKlicken Sie auf und danach aufElementeaus.
`your-iot-endpoint`	Die`your-iot-endpoint`value hat ein Format von:`endpoint_id-ats.iot.region.amazonaws.com`zum Beispiel`a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com`aus. So finden Sie diesen Wert: In derAWS IoTKonsole, wählenVerwaltenKlicken Sie auf und danach aufElementeaus. Wählen Sie das IoT-Ding aus, das Sie für Ihr Gerät erstellt haben,my_light_Bulb, die Sie vorher benutzt haben, und wählen Sie dannInteragierenaus. Auf der Seite mit den Thing-Details wird Ihr Endpunkt im FeldHTTPSAbschnitts erstellt.

Installieren und führen Sie die Beispielanwendung aus

Navigieren Sie zum Beispiel-App-Verzeichnis.
```
cd ~/aws-iot-device-sdk-python-v2/samples
```

Ersetzen Sie im Befehlszeilen-Fensteryour-iot-endpointundyour-iot-thing-Namewie angegeben und führen Sie diesen Befehl aus.


python3 shadow.py --ca_file ~/certs/Amazon-root-CA-1.pem --cert ~/certs/device.pem.crt --key ~/certs/private.pem.key --endpoint your-iot-endpoint --thing_name your-iot-thing-name

Beachten Sie, dass die Beispielanwendung:

Stellt eine Verbindung mitAWSIoT-Dienst für Ihr Konto.
Abonniert fürDeltaEreignisse undUpdateundGetAntworten.
Fordert Sie auf, einen gewünschten Wert im Terminal einzugeben.
Zeigt eine Ausgabe ähnlich der folgenden an:


Connecting to a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com with client ID 'test-0c8ae2ff-cc87-49d2-a82a-ae7ba1d0ca5a'...
Connected!
Subscribing to Delta events...
Subscribing to Update responses...
Subscribing to Get responses...
Requesting current shadow state...
Launching thread to read user input...
Finished getting initial shadow state.
Shadow contains reported value 'off'.
Enter desired value:

Anmerkung

Wenn Probleme beim Ausführen desshadow.pyBeispiel-App, überprüfenSchritt 3: Beheben Sie Probleme mit dershadow.pyBeispiel-Appaus. Um zusätzliche Informationen zu erhalten, die Ihnen bei der Behebung des Problems helfen könnten, fügen Sie die--verbosity debugParameter auf die Befehlszeile, damit die Beispiel-App detaillierte Nachrichten darüber anzeigt, was sie tut.

Geben Sie Werte ein und beobachten Sie die Updates im Shadow-Dokument

Sie können Werte im Terminal eingeben, um diedesiredWert, der auch denreportedWert. Sag, du gibst die Farbe einyellowim Terminal. DiereportedWert wird auch auf die Farbe aktualisiertyellowaus. Im Folgenden werden die im Terminal angezeigten Nachrichten angezeigt:


Enter desired value:
yellow
Changed local shadow value to 'yellow'.
Updating reported shadow value to 'yellow'...
Update request published.
Finished updating reported shadow value to 'yellow'.

Wenn Sie diese Aktualisierungsanfrage veröffentlichen,AWS IoTerstellt einen standardmäßigen, klassischen Schatten für die Ding-Ressource. Sie können die Aktualisierungsanfrage beobachten, die Sie in derreportedunddesired-Werte imAWS IoTkonsolen, indem Sie sich das Shadow-Dokument für die von Ihnen erstellte Dingressource ansehen (z.My_light_bulb) enthalten. So sehen Sie das Update im Shadow-Dokument:

In derAWS IoT-Konsole, Wählen SieVerwaltenKlicken Sie auf und danach aufElementeaus.
Wählen Sie in der Liste der angezeigten Dinge das Objekt aus, das Sie erstellt haben, und wählen SieShadowsKlicken Sie auf und danach aufKlassischer Schattenaus.

Das Shadow-Dokument sollte in etwa folgendermaßen aussehen und zeigt diereportedunddesiredWerte, die auf die Farbe eingestellt sindyellowaus. Diese Werte sehen Sie imSchatten-StatusAbschnitt des Dokuments.


{
"desired": {
  "welcome": "aws-iot",
  "color": "yellow"
},
"reported": {
  "welcome": "aws-iot",
  "color": "yellow"
}
}

Sie sehen auch einMetadataAbschnitt, der die Zeitstempelinformationen und die Versionsnummer der Anforderung enthält.

Sie können die Version des Statusdokuments verwenden, um sicherzustellen, dass Sie die neueste Version des Shadow-Dokuments eines Geräts aktualisieren. Wenn Sie eine weitere Aktualisierungsanfrage senden, erhöht sich die Versionsnummer um 1. Geben Sie bei einer Aktualisierungsanfrage eine Version an, lehnt der Service die Anfrage mit einem Konflikt-Antwortcode HTTP 409 ab, wenn die aktuelle Version des Statusdokuments nicht der angegebenen Version entspricht.


{
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620156893
    }
  }
},
"version": 10
}

Um mehr über das Shadow-Dokument zu erfahren und Änderungen an den Statusinformationen zu beobachten, fahren Sie mit dem nächsten Tutorial fortTutorial: Interaktion mit Device Shadow über die Beispiel-App und den MQTT-Testclientwie im beschriebenSchritt 4: Überprüfen Sie die Ergebnisse und nächsten SchritteAbschnitt dieses Tutorials. Optional können Sie auch mehr über dieshadow.pyBeispielcode und wie er das MQTT-Protokoll im folgenden Abschnitt verwendet.

Schritt 2: Überprüfen Sie die Beispiel-App des shadow.py Device SDK

In diesem Abschnitt wird dieshadow.pySample App ausAWS IoTDevice SDK v2 für PythonWird in diesem Tutorial verwendet. Hier werden wir überprüfen, wie es sich mit verbindetAWS IoT Coredurch Verwendung des MQTT- und MQTT-over-WSS-Protokolls. DieAWSgemeinsame Laufzeit (AWS-CRT)-Bibliothek bietet die Unterstützung des Low-Level-Kommunikationsprotokolls und ist imAWS IoTDevice SDK v2 für Python.

Während dieses Tutorial MQTT und MQTT über WSS verwendet,AWS IoTunterstützt Geräte, die HTTPS-Anfragen veröffentlichen. Ein Beispiel für ein Python-Programm, das eine HTTP-Nachricht von einem Gerät sendet, finden Sie imBeispiel für HTTPS-CodeVerwenden von Pythonsrequestsaufgelistet werden können.

Informationen darüber, wie Sie eine fundierte Entscheidung darüber treffen können, welches Protokoll Sie für Ihre Gerätekommunikation verwenden möchten, finden Sie in derWählen Sie ein Anwendungsprotokoll für Ihre Gerätekommunikationaus.

MQTT

Dieshadow.pyBeispielaufrufemtls_from_path(hier gezeigt) immqtt_connection_builderSo stellen Sie eine Verbindung mitAWS IoT CoreVerwendung des MQTT-Protokolls.mtls_from_pathverwendet X.509-Zertifikate und TLS v1.2, um das Gerät zu authentifizieren. DieAWS-CRT-Bibliothek verarbeitet die Details dieser Verbindung auf niedrigerer Ebene.


mqtt_connection = mqtt_connection_builder.mtls_from_path(
  endpoint=args.endpoint,
  cert_filepath=args.cert,
  pri_key_filepath=args.key,
  ca_filepath=args.ca_file,
  client_bootstrap=client_bootstrap,
  on_connection_interrupted=on_connection_interrupted,
  on_connection_resumed=on_connection_resumed,
  client_id=args.client_id,
  clean_session=False,
  keep_alive_secs=6
)

endpointist IhreAWS IoTEndpunkt, den Sie von der Befehlszeile aus übergeben haben undclient_idist die ID, die dieses Gerät eindeutig imAWS-Regionaus.
cert_filepath,pri_key_filepath, undca_filepathsind die Pfade zu den Zertifikats- und privaten Schlüsseldateien des Geräts sowie zur Root-CA-Datei.
client_bootstrapist das gemeinsame Laufzeitobjekt, das Socket-Kommunikationsaktivitäten verarbeitet und vor dem Aufruf vonmqtt_connection_builder.mtls_from_pathaus.
on_connection_interruptedundon_connection_resumedsind Callback-Funktionen, die aufgerufen werden sollen, wenn die Verbindung des Geräts unterbrochen und wieder aufgenommen wird.
clean_sessionist, ob eine neue, dauerhafte Sitzung gestartet werden soll oder ob eine vorhanden ist, eine erneute Verbindung zu einer bestehenden Sitzung herstellen soll.keep_alive_secsist der Keep Alive Wert in Sekunden, um dieCONNECTrequest. In diesem Intervall wird automatisch ein Ping gesendet. Der Server geht davon aus, dass die Verbindung verloren geht, wenn sie nach dem 1,5-fachen dieses Wertes keinen Ping erhält.

Dieshadow.pyBeispiel auch Anrufewebsockets_with_default_aws_signingimmqtt_connection_builderSo stellen Sie eine Verbindung mitAWS IoT CoreVerwenden des MQTT-Protokolls über WSS. MQTT over WSS verwendet auch die gleichen Parameter wie MQTT und nimmt diese zusätzlichen Parameter an:

regionist derAWSsignierende Region, die von Signature V4-Authentifizierung verwendet wird,credentials_providerist derAWSAnmeldeinformationen, die zur Authentifizierung verwendet werden sollen. Die Region wird von der Befehlszeile übergeben und diecredentials_providerobject wird kurz vor dem Aufruf vonmqtt_connection_builder.websockets_with_default_aws_signingaus.
websocket_proxy_optionssind die HTTP-Proxy-Optionen, wenn ein Proxy-Host verwendet wird. In dershadow.pyBeispiel-App, dieser Wert wird kurz vor dem Aufruf vonmqtt_connection_builder.websockets_with_default_aws_signingaus.

Abonnieren Sie Shadow Themen und Ereignisse

Dieshadow.pyProbe versucht, eine Verbindung herzustellen, und wartet darauf, vollständig verbunden zu sein. Wenn es nicht verbunden ist, werden Befehle in die Warteschlange gestellt. Nach der Verbindung abonniert das Beispiel Delta-Ereignisse und aktualisiert und erhält Nachrichten und veröffentlicht Nachrichten mit einer Quality of Service (QoS) -Level von 1 (mqtt.QoS.AT_LEAST_ONCE) enthalten.

Wenn ein Gerät eine Nachricht mit QoS Level 1 abonniert, speichert der Nachrichtenbroker die Nachrichten, die das Gerät abonniert hat, bis sie an das Gerät gesendet werden können. Der Nachrichtenbroker sendet die Nachrichten erneut, bis er einePUBACKAntwort vom Gerät.

Weitere Informationen zum MQTT-Protokoll finden Sie unterÜberprüfen des MQTT-ProtokollsundMQTTaus.

Weitere Informationen darüber, wie MQTT, MQTT über WSS, persistente Sitzungen und QoS-Ebenen, die in diesem Tutorial verwendet werden, finden Sie unterSehen Sie sich die pubsub.py Device SDK-Beispiel-App anaus.

Schritt 3: Beheben Sie Probleme mit der`shadow.py`Beispiel-App

Wenn du dieshadow.pyBeispiel-App, Sie sollten einige Nachrichten im Terminal angezeigt werden und eine Aufforderung zur Eingabe einesdesiredWert. Wenn das Programm einen Fehler auslöst, können Sie zum Debuggen des Fehlers zunächst prüfen, ob Sie den richtigen Befehl für Ihr System ausgeführt haben.

In einigen Fällen kann die Fehlermeldung auf Verbindungsprobleme hinweisen und ähnlich aussehen wie:Host name was invalid for dns resolutionoderConnection was closed unexpectedlyaus. In solchen Fällen können Sie einige Dinge überprüfen:

Überprüfen Sie die Endpunktadresse im Befehl

Prüfen Sie dieendpointArgument in dem Befehl, den Sie zum Ausführen der Beispiel-App eingegeben haben (z.a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com) und überprüfen Sie diesen Wert imAWS IoTKonsoleaus.

So prüfen Sie, ob Sie den richtigen Wert verwendet haben:
1. In derAWS IoTKonsole, wählenVerwaltenKlicken Sie auf und danach aufElementeaus.
2. Wählen Sie das -Objekt aus, das Sie für Ihre Beispiel-App erstellt haben (z. B.my_light_Bulb) und danach aufInteragierenaus.
Auf der Seite mit den Thing-Details wird Ihr Endpunkt im FeldHTTPSAbschnitts erstellt. Es sollte auch eine Meldung angezeigt werden, die besagt:This thing already appears to be connected.
Überprüfen der Zertifikataktivierung

Zertifikate authentifizieren Ihr Gerät mitAWS IoT Coreaus.

So prüfen Sie, ob Ihr Zertifikat aktiv ist:
1. In derAWS IoTKonsole, wählenVerwaltenKlicken Sie auf und danach aufElementeaus.
2. Wählen Sie das -Objekt aus, das Sie für Ihre Beispiel-App erstellt haben (z. B.my_light_Bulb) und danach aufSicherheitaus.
3. Wählen Sie das Zertifikat aus und wählen Sie dann auf der Detailseite des Zertifikats das Zertifikat auswählen aus und wählen Sie dann auf der Detailseite des ZertifikatsAktionenaus.
Wenn in der Dropdown-ListeActivateist nicht verfügbar und Sie können nur wählenDeaktivieren, Ihr Zertifikat ist aktiv. Wenn nicht, wählen SieActivateund führen Sie das Beispielprogramm erneut aus.

Wenn das Programm immer noch nicht ausgeführt wird, überprüfen Sie die Namen der Zertifikatdateien imcertsfolder.
Überprüfen Sie die Richtlinie, die mit der Ding-Ressource verbunden ist

Während Zertifikate Ihr Gerät authentifizieren,AWS IoTRichtlinien erlauben dem Gerät die AusführungAWS IoTOperationen, wie das Abonnieren oder Veröffentlichen von reservierten MQTT-Themen.

So prüfen Sie, ob die richtige Richtlinie angehängt ist:
1. Suchen Sie das Zertifikat wie zuvor beschrieben und wählen Sie dannRichtlinienaus.
2. Wählen Sie die angezeigte Richtlinie aus und prüfen Sie, ob sie dieconnect,subscribe,receive, undpublishAktionen, die dem Gerät die Berechtigung geben, die reservierten MQTT-Themen zu veröffentlichen und zu abonnieren.
  
  Eine Beispielrichtlinie finden Sie unterSchritt 1: Erstellen einesAWS IoT-Richtlinie für Device Shadowaus.
Wenn Fehlermeldungen angezeigt werden, die auf Probleme beim Verbinden mit hinweisenAWS IoT, könnte es an den Berechtigungen liegen, die Sie für die Richtlinie verwenden. In diesem Fall empfehlen wir, dass Sie mit einer Richtlinie beginnen, die vollen Zugriff aufAWS IoT-Ressourcen und führen Sie dann das Beispielprogramm erneut aus. Sie können entweder die aktuelle Richtlinie bearbeiten oder die aktuelle Richtlinie auswählen undAufhebung der Verknüpfungund erstellen Sie dann eine weitere Richtlinie, die vollen Zugriff bietet, und fügen Sie sie an Ihre Ding-Ressource an. Sie können die Richtlinie später nur auf die Aktionen und Richtlinien beschränken, die Sie zum Ausführen des Programms benötigen.
```
{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Action": [
              "iot:*"
          ],
          "Resource": "*"
      }
  ]
}         
```
Überprüfen Sie Ihre Device SDK-Installation

Wenn das Programm immer noch nicht ausgeführt wird, können Sie das Device SDK neu installieren, um sicherzustellen, dass Ihre SDK-Installation abgeschlossen und korrekt ist.

Schritt 4: Überprüfen Sie die Ergebnisse und nächsten Schritte

In diesem Tutorial haben Sie Folgendes gelernt:

Installieren Sie die erforderliche Software, Tools und dieAWS IoTDevice SDK für Python.
So verstehen Sie, wie die Beispielanwendungshadow.pyverwendet das MQTT-Protokoll zum Abrufen und Aktualisieren des aktuellen Status des Shadows.
Führen Sie die Beispiel-App für Device Shadows aus und beobachten Sie das Update des Shadow-Dokuments imAWS IoTconsole. Sie haben auch gelernt, Probleme zu beheben und Fehler beim Ausführen des Programms zu beheben.

Nächste Schritte

Sie können jetzt denshadow.pyBeispielanwendung und verwenden Sie Device Shadows, um den Status zu steuern. Sie können die Aktualisierungen des Shadow-Dokuments imAWS IoTKonsolen und beobachten Sie Delta-Ereignisse, auf die die Beispiel-App reagiert. Mit dem MQTT-Testclient können Sie die reservierten Schattenthemen abonnieren und Nachrichten beobachten, die die Themen beim Ausführen des Beispielprogramms erhalten haben. Weitere Informationen zum Ausführen dieses Tutorials finden Sie unterTutorial: Interaktion mit Device Shadow über die Beispiel-App und den MQTT-Testclientaus.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Bereitstellen Ihres Geräts inAWS IoT

Interaktion mit Device Shadow über die Beispiel-App und den MQTT-Testclient