Didacticiel : Interaction avec Device Shadow à l'aide de l'exemple d'application et du client de test MQTT - AWS IoT Core
Étape 1 : Mettre à jour les valeurs souhaitées et signalées àshadow.pyExemple d'applicationÉtape 2 : Afficher les messages provenant dushadow.pyExemple d'application dans le client de test MQTTÉtape 3 : Dépannage des erreurs liées aux interactions Device ShadowÉtape 4 : Passez en revue les résultats et les prochaines étapes

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 : Interaction avec Device Shadow à l'aide de l'exemple d'application et du client de test MQTT

Pour interagir avec l'shadow.pyexemple d'application, entrez une valeur dans le terminal pour l'applicationdesiredValeur . Par exemple, vous pouvez spécifier des couleurs qui ressemblent aux feux de signalisation etAWS IoTrépond à la demande et met à jour les valeurs signalées.

Dans ce didacticiel, vous allez apprendre à :

  • Utilisation de l'shadow.pyexemple d'application pour spécifier les états souhaités et mettre à jour l'état actuel de l'ombre.

  • Modifiez le document Shadow pour observer les événements delta et comment leshadow.pyl'exemple d'application y répond.

  • Utilisez le client de test MQTT pour vous abonner à des rubriques instantanées et observer les mises à jour lorsque vous exécutez l'exemple de programme.

Avant de lancer ce didacticiel, vous devez disposer des éléments suivants :

Configurer votreCompte AWS, a configuré votre appareil Raspberry Pi et créé unAWS IoTchose et politique. Vous devez également avoir installé le logiciel requis, le kit SDK de périphérique, les fichiers de certificats et exécuter l'exemple de programme dans le terminal. Pour plus d'informations, consultez les didacticiels précédentsDidacticiel : Préparation de votre Raspberry Pi pour exécuter l'application shadowetÉtape 1 : Exécutez l'exemple d'application shadow.py. Si vous ne l'avez pas déjà fait, vous devez suivre ces didacticiels.

Ce didacticiel vous prendra environ 45 minutes.

Étape 1 : Mettre à jour les valeurs souhaitées et signalées àshadow.pyExemple d'application

Dans le didacticiel précédentÉtape 1 : Exécutez l'exemple d'application shadow.py, vous avez appris comment observer un message publié dans le document Shadow dans leAWS IoTlorsque vous entrez la valeur souhaitée, comme décrit dans la sectionDidacticiel : Installation du kit SDK de périphériques et exécution de l'exemple d'application pour Device Shadows.

Dans l'exemple précédent, nous définissons la couleur souhaitée suryellow. Une fois que vous avez entré chaque valeur, le terminal vous invite à saisir une autre valeur.desiredValeur . Si vous entrez à nouveau la même valeur (yellow), l'application reconnaît cela et vous invite à entrer un nouveaudesiredValeur .

Enter desired value:
yellow
Local value is already 'yellow'.
Enter desired value:

Maintenant, disons que vous entrez la couleurgreen.AWS IoTrépond à la demande et met à jour lereportedvaleurgreen. C'est ainsi que la mise à jour se produit lorsque ledesiredest différent dureportedétat, provoquant un delta.

Procédureshadow.pyexemple d'application simule les interactions Device Shadow :

  1. Saisissez unedesiredvaleur (disons)yellow) dans le terminal pour publier l'état souhaité.

  2. Comme ledesiredest différent dureportedétat (dites la couleur)green), un delta se produit et l'application abonnée au delta reçoit ce message.

  3. L'application répond au message et met à jour son état sur ledesiredvaleur,yellow.

  4. L'application publie ensuite un message de mise à jour avec la nouvelle valeur signalée de l'état de l'appareil,yellow.

Vous trouverez ci-dessous les messages affichés dans le terminal qui indiquent comment la demande de mise à jour est publiée.

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

DansAWS IoT, le document Shadow reflète la valeur mise à jour versgreenpour les deuxreportedetdesiredet le numéro de version est incrémenté de 1. Par exemple, si le numéro de version précédente était affiché sur 10, le numéro de version actuel s'affiche sous la forme 11.

Note

La suppression d'une ombre ne réinitialise pas le numéro de version à 0. Vous verrez que la version de l'ombre est incrémentée de 1 lorsque vous publiez une demande de mise à jour ou que vous créez une autre ombre portant le même nom.

Modifier le document Shadow pour observer les événements Delta

Leshadow.pyUn exemple d'application est également abonné àdeltaet répond en cas de modification de ladesiredValeur . Par exemple, vous pouvez modifier ledesiredvaleur de la couleurred. Pour ce faire, dans l'AWS IoT, modifiez le document Shadow en cliquant surModifierpuis définissez le paramètredesiredvaleurreddans le JSON, tout en conservant lereportedvaleurgreen. Avant d'enregistrer les modifications, gardez le terminal sur le Raspberry Pi ouvert car les messages s'affichent dans le terminal lorsque la modification se produit.

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

Une fois que vous avez enregistré la nouvelle valeur, le paramètreshadow.pyl'exemple d'application répond à cette modification et affiche des messages dans le terminal indiquant le delta. Vous devriez alors voir les messages suivants apparaître sous l'invite de saisie dudesiredValeur .

Enter desired value:
Received shadow delta event.
Delta reports that desired value is 'red'. Changing local value...
Changed local shadow value to 'red'.
Updating reported shadow value to 'red'...
Finished updating reported shadow value to 'red'.
Enter desired value:
Update request published.
Finished updating reported shadow value to 'red'.

Étape 2 : Afficher les messages provenant dushadow.pyExemple d'application dans le client de test MQTT

Vous pouvez utiliser le pluginClient de test MQTTdans leAWS IoTconsolepour surveiller les messages MQTT transmis dans votreCompte AWS. En vous abonnant aux rubriques MQTT réservées utilisées par le service Device Shadow, vous pouvez observer les messages reçus par les rubriques lors de l'exécution de l'exemple d'application.

Si vous n'avez pas déjà utilisé le client de test MQTT, vous pouvez consulterAfficher les MQTT messages à l'aide du AWS IoT MQTTclient. Cela vous apprendra à utiliser l'Client de test MQTTdans leAWS IoTconsolepour afficher les messages MQTT lorsqu'ils passent par le courtier de messages.

  1. Ouvrez le client de test MQTT

    Ouverture d'Test client MQTT dans leAWS IoTconsoledans une nouvelle fenêtre afin que vous puissiez observer les messages reçus par les rubriques MQTT sans perdre la configuration de votre client de test MQTT. Le client de test MQTT ne conserve aucun abonnement ou journal de messages si vous le laissez accéder à une autre page de la console. Pour cette section du didacticiel, vous pouvez avoir le document Shadow de votreAWS IoTet le client de test MQTT s'ouvrent dans des fenêtres distinctes pour observer plus facilement l'interaction avec Device Shadows.

  2. Abonnez-vous aux rubriques Shadow réservées MQTT

    Vous pouvez utiliser le client de test MQTT pour entrer les noms des rubriques réservées MQTT de Device Shadow et vous y abonner pour recevoir des mises à jour lors de l'exécution dushadow.pyExemple d'application. Pour vous abonner aux sujets suivants :

    1. DansClient de test MQTTdans leAWS IoTconsole, choisissezS'abonner à une rubrique.

    2. DansFiltre de rubriques, saisissez :$aws/things/thingName/shadow/update/ #. Ici,thingnameest le nom de la ressource objet que vous avez créée plus tôt (par exemple,My_light_bulb).

    3. Conservez les valeurs par défaut des paramètres de configuration supplémentaires, puis choisissezS'abonner.

    En utilisant le#dans l'abonnement à la rubrique, vous pouvez vous abonner à plusieurs rubriques MQTT en même temps et observer tous les messages échangés entre l'appareil et son ombre dans une seule fenêtre. Pour plus d'informations sur les caractères génériques et leur utilisation, consultezRubriques MQTT.

  3. Run (Exécuter Lambda)shadow.pyexemple de programme et d'observation des messages

    Dans la fenêtre de ligne de commande du Raspberry Pi, si vous avez déconnecté le programme, exécutez à nouveau l'exemple d'application et regardez les messages dans leClient de test MQTTdans leAWS IoTconsole.

    1. Exécutez la commande suivante pour redémarrer l'exemple de programme. Remplacezyour-iot-thing-Nameetyour-iot-endpointavec les noms duAWS IoTobjet que vous avez créé précédemment (par exemple,My_light_bulb), et le point de terminaison pour interagir avec l'appareil. 

      cd ~/aws-iot-device-sdk-python-v2/samples
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

      Leshadow.pyl'exemple d'application s'exécute ensuite et récupère l'état de l'ombre actuel. Si vous avez supprimé l'ombre ou effacé les états actuels, le programme définit la valeur actuelle suroffpuis vous invite à entrer undesiredValeur .

      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 document lacks 'color' property. Setting defaults...
Changed local shadow value to 'off'.
Updating reported shadow value to 'off'...
Update request published.
Finished updating reported shadow value to 'off'...
Enter desired value:

      Par contre, si le programme était en cours d'exécution et que vous l'avez redémarré, vous verrez la dernière valeur de couleur signalée dans le terminal. Dans le client de test MQTT, vous verrez une mise à jour des rubriques.$aws/things/thingName/ombre/obteniret$aws/things/thingName/shadow/get/accepted.

      Supposons que la dernière couleur signalée soitgreen. Voici le contenu de l'$aws/things/thingName/shadow/get/acceptedJSON.

      {
"state": {
  "desired": {
    "welcome": "aws-iot",
    "color": "green"
  },
  "reported": {
    "welcome": "aws-iot",
    "color": "green"
  }
},
"metadata": {
  "desired": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620161643
    }
  },
  "reported": {
    "welcome": {
      "timestamp": 1620156892
    },
    "color": {
      "timestamp": 1620161643
    }
  }
},
"version": 10,
"timestamp": 1620173908
}

    2. Saisissez unedesiredvaleur dans le terminal, telle queyellow. Leshadow.pyl'exemple d'application répond et affiche les messages suivants dans le terminal qui indiquent la modification dans lereportedvaleuryellow.

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

      DansClient de test MQTTdans leAWS IoTconsole, sousSubscriptions, vous constatez que les rubriques suivantes ont reçu un message :

      • $aws/things/thingName/ombre/mise à jour: montre que les deuxdesiredetupdatedles valeurs changent en couleuryellow.

      • $aws/things/thingName/shadow/update/accepted: affiche les valeurs actuelles dudesiredetreportedétats et leurs métadonnées et informations de version.

      • $aws/things/thingName/shadow/update/documents: affiche les valeurs précédentes et actuelles dudesiredetreportedétats et leurs métadonnées et informations de version.

      Comme document$aws/things/thingName/shadow/update/documentscontient également des informations contenues dans les deux autres rubriques, nous pouvons les consulter pour voir les informations d'état. L'état précédent affiche la valeur signalée définie surgreen, ses métadonnées et ses informations de version, ainsi que l'état actuel qui affiche la valeur signalée mise à jour versyellow.

      {
"previous": {
  "state": {
    "desired": {
      "welcome": "aws-iot",
      "color": "green"
    },
    "reported": {
      "welcome": "aws-iot",
      "color": "green"
    }
  },
  "metadata": {
    "desired": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297898
      }
    },
    "reported": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297898
      }
    }
  },
  "version": 10
},
"current": {
  "state": {
    "desired": {
      "welcome": "aws-iot",
      "color": "yellow"
    },
    "reported": {
      "welcome": "aws-iot",
      "color": "yellow"
    }
  },
  "metadata": {
    "desired": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297904
      }
    },
    "reported": {
      "welcome": {
        "timestamp": 1617297888
      },
      "color": {
        "timestamp": 1617297904
      }
    }
  },
  "version": 11
},
"timestamp": 1617297904
}

    3. Maintenant, si vous entrez un autredesired, vous verrez d'autres modifications apportées à lareportedles valeurs et les mises à jour des messages reçues par ces rubriques. Le numéro de version est également incrémenté de 1. Par exemple, si vous entrez la valeurgreen, l'état précédent indique la valeuryellowet l'état actuel indique la valeurgreen.

  4. Modifier le document Shadow pour observer les événements Delta

    Pour observer les modifications apportées à la rubrique delta, modifiez le document Shadow dans leAWS IoTconsole Par exemple, vous pouvez modifier ledesiredvaleur de la couleurred. Pour ce faire, dans l'AWS IoTChoisissez, choisissezModifierpuis définissez le paramètredesiredvaleur rouge dans le JSON, tout en conservant la valeurreportedDéfinit la valeurgreen. Avant d'enregistrer la modification, gardez le terminal ouvert car vous verrez le message Delta signalé dans le terminal.

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

    Leshadow.pyl'exemple d'application répond à cette modification et affiche des messages dans le terminal indiquant le delta. Dans le client de test MQTT, leupdateles rubriques auront reçu un message indiquant les modifications apportées audesiredetreportedvaleurs.

    Vous voyez aussi que le sujet$aws/things/thingName/shadow/update/deltaa reçu un message. Pour voir le message, choisissez cette rubrique, répertoriée sousSubscriptions.

    {
"version": 13,
"timestamp": 1617318480,
"state": {
  "color": "red"
},
"metadata": {
  "color": {
    "timestamp": 1617318480
  }
}
}

Étape 3 : Dépannage des erreurs liées aux interactions Device Shadow

Lorsque vous exécutez l'exemple d'application Shadow, vous risquez de rencontrer des problèmes lors de l'observation des interactions avec le service Device Shadow.

Si le programme s'exécute correctement et vous invite à entrer undesired, vous devriez pouvoir observer les interactions Device Shadow à l'aide du document Shadow et du client de test MQTT comme décrit précédemment. Toutefois, si vous ne parvenez pas à voir les interactions, voici quelques éléments que vous pouvez vérifier :

  • Vérifiez le nom de la chose et son ombre dans leAWS IoTconsole

    Si vous ne voyez pas les messages dans le document Shadow, passez en revue la commande et assurez-vous qu'elle correspond au nom de l'objet dans leAWS IoTconsole. Vous pouvez également vérifier si vous avez une ombre classique en choisissant la ressource de votre objet, puis en choisissantShadows. Ce tutoriel se concentre principalement sur les interactions avec l'ombre classique.

    Vous pouvez également vérifier que l'appareil que vous avez utilisé est connecté à Internet. DansAWS IoTconsole, choisissez l'objet que vous avez créé précédemment, puis choisissezInteragir. Sur la page de détails de l'objet, vous devez voir ici un message indiquant :This thing already appears to be connected.

  • Vérifiez les sujets réservés MQTT auxquels vous êtes abonné

    Si les messages ne s'affichent pas dans le client de test MQTT, vérifiez si les rubriques auxquelles vous vous êtes abonné sont correctement formatées. Les rubriques MQTT Device Shadow ont un format$aws/things/thingName/shadow/et pourrait avoirupdate,get, oudeletesuivant le suivant en fonction des actions que vous souhaitez effectuer sur l'ombre. Ce didacticiel utilise.$aws/things/thingName/ombre/ #assurez-vous donc de l'avoir correctement saisi lorsque vous vous abonnez au sujet dans leFiltre de rubriquessection du client de test.

    Lorsque vous entrez le nom du sujet, assurez-vous que lethingNameest le même que le nom duAWS IoTCe que vous avez créé précédemment. Vous pouvez également vous abonner à d'autres rubriques MQTT pour voir si une mise à jour a été effectuée avec succès. Par exemple, vous pouvez vous abonner au sujet$aws/things/thingName/shadow/update/acceptedpour recevoir un message chaque fois qu'une demande de mise à jour échoue afin que vous puissiez déboguer les problèmes de connexion. Pour plus d'informations sur les rubriques réservées, consultezRubriques de shadowetRubriques MQTT de Device Shadow.

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

Dans ce didacticiel, vous avez appris à :

  • Utilisation de l'shadow.pyexemple d'application pour spécifier les états souhaités et mettre à jour l'état actuel de l'ombre.

  • Modifiez le document Shadow pour observer les événements delta et comment leshadow.pyl'exemple d'application y répond.

  • Utilisez le client de test MQTT pour vous abonner à des rubriques instantanées et observer les mises à jour lorsque vous exécutez l'exemple de programme.

Étapes suivantes

Vous pouvez vous abonner à d'autres rubriques réservées MQTT pour observer les mises à jour de l'application Shadow. Par exemple, si vous vous abonnez uniquement au sujet$aws/things/thingName/shadow/update/accepted, vous ne verrez que les informations d'état actuel lorsqu'une mise à jour est exécutée avec succès.

Vous pouvez également vous abonner à d'autres rubriques d'ombre pour déboguer les problèmes ou en savoir plus sur les interactions Device Shadow et également déboguer tout problème lié aux interactions Device Shadow. Pour plus d'informations, consultez Rubriques de shadow et Rubriques MQTT de Device Shadow.

Vous pouvez également choisir d'étendre votre application en utilisant des ombres nommées ou en utilisant du matériel supplémentaire connecté au Raspberry Pi pour les LED et observer les changements d'état à l'aide des messages envoyés depuis le terminal.

Pour plus d'informations sur le service Device Shadow et l'utilisation du service dans les appareils, les applications et les services, reportez-vous à la sectionAWS IoT Service Device Shadow,Utilisation des shadows sur les appareils, etUtilisation des shadows dans les applications et les services.