Didacticiel : Installation du kit SDK de périphériques et exécution de l'exemple d'application pour Device Shadows - AWS IoT Core

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Didacticiel : Installation du kit SDK de périphériques et exécution de l'exemple d'application pour Device Shadows

Cette section explique comment installer le logiciel requis et leAWS IoTKit SDK des appareils pour Python et exécutez l'shadow.pyexemple d'application pour modifier le document Shadow et contrôler l'état de l'ombre.

Dans ce didacticiel, vous allez apprendre à :
  • Utilisez le logiciel installé etAWS IoTKit SDK pour appareil Python pour exécuter l'exemple d'application.

  • Découvrez comment la saisie d'une valeur à l'aide de l'exemple d'application publie la valeur souhaitée dans leAWS IoTconsole

  • Vérifiez la rubriqueshadow.pyexemple d'application et comment il utilise le protocole MQTT pour mettre à jour l'état de l'ombre.

Avant de lancer ce didacticiel :

Vous avez dû configurer votreCompte AWS, a configuré votre appareil Raspberry Pi et créé unAWS IoTobjet et stratégie qui donnent à l'appareil les autorisations de publier et de s'abonner aux rubriques réservées MQTT du service Device Shadow. Pour plus d'informations, consultez Didacticiel : Préparation de votre Raspberry Pi pour exécuter l'application shadow.

Vous devez également avoir installé Git, Python et leAWS IoTKit SDK des appareils pour Python. Ce didacticiel s'appuie sur les concepts présentés dans le didacticielConnectez un Raspberry Pi ou un autre appareil. Si vous n'avez pas essayé ce didacticiel, nous vous recommandons de suivre les étapes décrites dans ce didacticiel pour installer les fichiers de certificats et le kit SDK de périphérique, puis de revenir à ce didacticiel pour exécuter leshadow.pyExemple d'application.

Ce didacticiel vous prendra environ 20 minutes.

Étape 1 : Exécutez l'exemple d'application shadow.py

Avant de lancer leshadow.pyexemple d'application, vous aurez besoin des informations suivantes en plus des noms et de l'emplacement des fichiers de certificats que vous avez installés.

Valeurs des paramètres d'application

Paramètre

Où trouver la valeur

your-iot-thing-Name

Nom duAWS IoTchose que vous avez créée précédemment dansÉtape 2 : Créez une ressource objet et attachez la stratégie à l'objet.

Pour trouver cette valeur, dans leAWS IoTconsole, choisissezGérer, puis choisissezObjets.

your-iot-endpoint

Leyour-iot-endpointLa valeur a un format de :endpoint_id-ats.iot.region.amazonaws.com, par exemple,a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com. Pour trouver cette valeur, procédez comme suit

  1. DansAWS IoTconsole, choisissezGérer, puis choisissezObjets.

  2. Choisissez l'objet IoT que vous avez créé pour votre appareil,My_Light_Bulb, que vous avez utilisé précédemment, puis choisissezInteragir. Sur la page de détails de l'objet, votre point de terminaison s'affiche dans leHTTPSSection.

Installez et exécutez l'exemple d'application
  1. Accédez au répertoire d'exemples d'applications.

    cd ~/aws-iot-device-sdk-python-v2/samples
  2. Dans la fenêtre de ligne de commande, remplacezyour-iot-endpointetyour-iot-thing-Namecomme indiqué et exécutez cette commande.

    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
  3. Notez que l'exemple d'application :

    1. Se connecte àAWSService IoT pour votre compte.

    2. S'abonne àDeltaévénements etUpdateetGetRéponses.

    3. Vous invite à entrer la valeur souhaitée dans le terminal.

    4. Affiche une sortie semblable à ce qui suit :

    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:
Note

Si vous rencontrez des problèmes dans l'exécution dushadow.pyExemple d'application, révisionÉtape 3 : Résolution des problèmes liés à lashadow.pyExemple d'application. Pour obtenir des informations supplémentaires susceptibles de vous aider à corriger le problème, ajoutez le--verbosity debugde la ligne de commande afin que l'exemple d'application affiche des messages détaillés sur ce qu'il fait.

Entrez des valeurs et observez les mises à jour dans le document Shadow

Vous pouvez entrer des valeurs dans le terminal pour spécifier le paramètredesired, qui met également à jour la valeurreportedValeur . Supposons que vous saisissez la couleuryellowdans le terminal. Lereportedest également mise à jour vers la couleuryellow. Les messages affichés dans le terminal sont les suivants :

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'.

Lorsque vous publiez cette demande de mise à jour,AWS IoTcrée une ombre classique par défaut pour la ressource objet. Vous pouvez observer la demande de mise à jour que vous avez publiée sur lereportedetdesiredvaleurs dans l'AWS IoTen regardant le document Shadow correspondant à la ressource objet que vous avez créée (par exemple,My_light_bulb). Pour voir la mise à jour dans le document Shadow :

  1. DansAWS IoTChoisissez, choisissezGérerpuis choisissezObjets.

  2. Dans la liste des objets affichés, sélectionnez l'objet que vous avez créé, choisissezShadows, puis choisissezShadow Classique.

Le document Shadow doit se présenter comme suit, montrant l'reportedetdesiredvaleurs définies sur la couleuryellow. Vous voyez ces valeurs dans leÉtat de l'ombresection du document.

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

Vous voyez également unMétadonnéesqui contient les informations d'horodatage et le numéro de version de la demande.

Vous pouvez utiliser la version du document d'état pour vous assurer que vous mettez à jour la version la plus récente du document Shadow d'appareil. Si vous envoyez une autre demande de mise à jour, le numéro de version augmente de 1. Lorsque vous fournissez une version dans une demande de mise à jour, le service rejette la demande avec un code de réponse de conflit HTTP 409 si la version actuelle du document d'état ne correspond pas à la version fournie.

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

Pour en savoir plus sur le document Shadow et observer les modifications apportées aux informations d'état, passez au didacticiel suivantDidacticiel : Interaction avec Device Shadow à l'aide de l'exemple d'application et du client de test MQTTcomme cela est décrit dans laÉtape 4 : Passez en revue les résultats et les prochaines étapessection de ce didacticiel. Le cas échéant, vous pouvez également découvrir l'shadow.pyexemple de code et comment il utilise le protocole MQTT dans la section suivante.

Étape 2 : Consultez l'exemple d'application shadow.py Device SDK

Cette section passe en revue leshadow.pyExemple d'application de l'AWS IoTKit SDK des appareils v2 pour Pythonutilisé dans ce didacticiel. Ici, nous allons examiner comment il se connecte àAWS IoT Coreen utilisant le protocole MQTT et MQTT sur WSS. LeAWSRuntime commun (AWS-CRT)fournit la prise en charge du protocole de communication de bas niveau et est incluse dans leAWS IoTKit SDK des appareils v2 pour Python.

Bien que ce tutoriel utilise MQTT et MQTT sur WSS,AWS IoTprend en charge les appareils qui publient des requêtes HTTPS. Pour obtenir un exemple de programme Python qui envoie un message HTTP depuis un appareil, consultez leExemple de code HTTPSUtilisation de Pythonrequestsbibliothèque.

Pour plus d'informations sur la façon dont vous pouvez prendre une décision éclairée quant au protocole à utiliser pour les communications de votre appareil, consultez leChoix d'un protocole pour la communication de votre appareil.

MQTT

Leshadow.pyExemples d'appelmtls_from_path(illustré ici) dans lemqtt_connection_builderpour établir une connexion avecAWS IoT Coreen utilisant le protocole MQTT.mtls_from_pathutilise les certificats X.509 et TLS v1.2 pour authentifier l'appareil. LeAWS-La bibliothèque CRT gère les détails de niveau inférieur de cette connexion.

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 )
  • endpointest votreAWS IoTpoint de terminaison que vous avez transmis depuis la ligne de commande etclient_idest l'ID qui identifie de manière unique cet appareil dans le champRégion AWS.

  • cert_filepath,pri_key_filepath, etca_filepathsont les chemins d'accès au certificat et aux fichiers de clé privée de l'appareil, ainsi que le fichier d'autorité de certification racine.

  • client_bootstrapest l'objet d'exécution courant qui gère les activités de communication de socket et est instancié avant l'appel àmqtt_connection_builder.mtls_from_path.

  • on_connection_interruptedeton_connection_resumedsont des fonctions de rappel à appeler lorsque la connexion de l'appareil est interrompue et reprend.

  • clean_sessionindique s'il faut démarrer une nouvelle session persistante ou, s'il y en a une, se reconnecter à une session existante.keep_alive_secsest la valeur Keep Alive, en quelques secondes, à envoyer leCONNECTde la demande. Un ping sera automatiquement envoyé à cet intervalle. Le serveur suppose que la connexion est perdue s'il ne reçoit pas de ping après 1,5 fois cette valeur.

Leshadow.pyl'échantillon appelle égalementwebsockets_with_default_aws_signingdans lemqtt_connection_builderpour établir une connexion avecAWS IoT Coreen utilisant le protocole MQTT sur WSS. MQTT over WSS utilise également les mêmes paramètres que MQTT et prend les paramètres supplémentaires suivants :

  • regionest leAWSrégion de signature utilisée par l'authentification Signature V4, etcredentials_providerest leAWSinformations d'identification fournies à utiliser pour l'authentification. La région est transmise à partir de la ligne de commande, et lecredentials_providerest instancié juste avant l'appel àmqtt_connection_builder.websockets_with_default_aws_signing.

  • websocket_proxy_optionsest les options proxy HTTP, si vous utilisez un hôte proxy. Dansshadow.pyexemple d'application, cette valeur est instanciée juste avant l'appel àmqtt_connection_builder.websockets_with_default_aws_signing.

Abonnez-vous aux sujets et événements Shadow

Leshadow.pyexemple tente d'établir une connexion et attend d'être entièrement connecté. S'il n'est pas connecté, les commandes sont mises en file d'attente. Une fois connecté, l'exemple s'abonne aux événements delta, met à jour et reçoit des messages, et publie des messages avec un niveau de qualité de service (QoS) de 1 (mqtt.QoS.AT_LEAST_ONCE).

Lorsqu'un appareil s'abonne à un message avec QoS niveau 1, le courtier de messages enregistre les messages auxquels l'appareil est abonné jusqu'à ce qu'ils puissent être envoyés à l'appareil. Le courtier de messages renvoie les messages jusqu'à ce qu'il reçoive unPUBACKréponse de l'appareil.

Pour plus d'informations sur le protocole MQTT, consultezVérifier le protocole MSONetMQTT.

Pour plus d'informations sur la façon dont MQTT, MQTT over WSS, les sessions persistantes et les niveaux de QoS utilisés dans ce didacticiel, voirConsultez l'exemple d'application pubsub.py Device SDK.

Étape 3 : Résolution des problèmes liés à lashadow.pyExemple d'application

Lorsque vous exécutez leshadow.pyexemple d'application, vous devriez voir certains messages s'afficher dans le terminal et une invite à entrer undesiredValeur . Si le programme génère une erreur, alors pour déboguer l'erreur, vous pouvez commencer par vérifier si vous avez exécuté la commande correcte pour votre système.

Dans certains cas, le message d'erreur peut indiquer des problèmes de connexion et ressembler à :Host name was invalid for dns resolutionouConnection was closed unexpectedly. Dans ce cas, voici quelques éléments que vous pouvez vérifier :

  • Vérifiez l'adresse du point de terminaison dans la commande

    Vérifiez la rubriqueendpointdans la commande que vous avez entrée pour exécuter l'exemple d'application (par exemple,a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com) et vérifiez cette valeur dans le champAWS IoTconsole.

    Pour vérifier si vous avez utilisé la bonne valeur, procédez comme suit :

    1. DansAWS IoTconsole, choisissezGérerpuis choisissezObjets.

    2. Choisissez l'objet que vous avez créé pour votre exemple d'application (par exemple,My_Light_Bulb) puis choisissezInteragir.

    Sur la page de détails de l'objet, votre point de terminaison s'affiche dans leHTTPSSection. Vous devez également voir un message indiquant :This thing already appears to be connected.

  • Vérifier l'activation du certificat

    Les certificats authentifient votre appareil avecAWS IoT Core.

    Pour vérifier si votre certificat est actif, procédez comme suit :

    1. DansAWS IoTconsole, choisissezGérerpuis choisissezObjets.

    2. Choisissez l'objet que vous avez créé pour votre exemple d'application (par exemple,My_Light_Bulb) puis choisissezSécurité.

    3. Sélectionnez le certificat, puis, dans la page des détails du certificat, choisissez Sélectionner le certificat, puis, dans la page de détails du certificat, choisissezActions.

    Si vous êtes dans la liste déroulanteActivaten'est pas disponible et vous pouvez uniquement choisirDeactivate, votre certificat est actif. Sinon, choisissezActivateet réexécutez l'exemple de programme.

    Si le programme ne s'exécute toujours pas, vérifiez les noms des fichiers de certificats dans le champcertsfolder.

  • Vérifiez la stratégie attachée à la ressource objet

    Pendant que les certificats authentifient votre appareil,AWS IoTles stratégies permettent à l'appareil d'exécuterAWS IoTopérations, telles que l'abonnement ou la publication à des rubriques réservées MQTT.

    Pour vérifier si la stratégie appropriée est attachée :

    1. Recherchez le certificat comme décrit précédemment, puis choisissezStratégies.

    2. Choisissez la stratégie affichée et vérifiez si elle décrit laconnect,subscribe,receive, etpublishactions qui donnent à l'appareil l'autorisation de publier et de s'abonner aux rubriques réservées MQTT.

      Pour obtenir un exemple de stratégie, consultezÉtape 1 : Création d'unAWS IoTstratégie Device Shadow.

    Si des messages d'erreur indiquent un problème de connexion àAWS IoT, cela peut être dû aux autorisations que vous utilisez pour la stratégie. Si tel est le cas, nous vous recommandons de commencer par une stratégie qui offre un accès complet àAWS IoTressources, puis réexécutez l'exemple de programme. Vous pouvez soit modifier la stratégie actuelle, soit choisir la stratégie actuelle, choisissezDetach, puis créez une autre stratégie qui fournit un accès complet et l'attache à votre ressource objet. Vous pouvez ensuite limiter la stratégie aux actions et aux stratégies dont vous avez besoin pour exécuter le programme.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:*" ], "Resource": "*" } ] }
  • Vérifiez l'installation du SDK de votre appareil

    Si le programme ne s'exécute toujours pas, vous pouvez réinstaller le kit SDK pour vous assurer que l'installation de votre SDK est terminée et correcte.

Étape 4 : Passez en revue les résultats et les prochaines étapes

Dans ce didacticiel, vous avez appris à :
  • Installer le logiciel requis, les outils et l'AWS IoTKit SDK des appareils pour Python.

  • Comprendre comment l'exemple d'application,shadow.py, utilise le protocole MQTT pour récupérer et mettre à jour l'état actuel de l'ombre.

  • Exécutez l'exemple d'application pour Device Shadows et observez la mise à jour du document Shadow dans leAWS IoTconsole Vous avez également appris à résoudre les problèmes et à corriger les erreurs lors de l'exécution du programme.

Étapes suivantes

Vous pouvez désormais exécuter l'shadow.pyexemple d'application et utilisez Device Shadows pour contrôler l'état. Vous pouvez observer les mises à jour du document Shadow dans leAWS IoTConsole et observez les événements delta auxquels l'exemple d'application répond. À l'aide du client de test MQTT, vous pouvez vous abonner aux rubriques d'ombre réservées et observer les messages reçus par les rubriques lors de l'exécution de l'exemple de programme. Pour plus d'informations sur l'exécution de ce didacticiel, consultezDidacticiel : Interaction avec Device Shadow à l'aide de l'exemple d'application et du client de test MQTT.