使用 shadow.py 示例应用程序及 MQTT 测试客户端与 Device Shadow 交互 - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

使用 shadow.py 示例应用程序及 MQTT 测试客户端与 Device Shadow 交互

若要与 shadow.py 示例应用程序交互,请在终端中为 desired 值输入一个值。例如,您可以向请求指定类似于红绿灯的颜色和 Amazon IoT 响应,并更新报告的值。

在本教程中,您将学习如何:

  • 使用 shadow.py 示例应用程序来指定所需的状态并更新影子的当前状态。

  • 编辑影子文档以观察增量事件以及 shadow.py 示例应用程序如何响应。

  • 使用 MQTT 测试客户端订阅影子主题并在运行示例程序时观察更新。

运行本教程之前,您必须具有:

设置您的 Amazon Web Services 账户 ,配置您的 Raspberry Pi 设备,并创建 Amazon IoT 事物和策略。您还必须安装了所需的软件、设备软件开发工具包、证书文件,并在终端中运行示例程序。有关更多信息,请参阅教程 创建 Amazon IoT 资源和连接 Raspberry Pi 运行影子应用程序。如果您尚未完成这些教程,请先予完成。

完成本教程需要大约 45 分钟。

使用 shadow.py 示例应用程序更新所需值和报告值

在前面的教程 中,您学习了在按照部分 安装设备开发工具包并运行 shadow.py Device Shadow 示例应用程序 中所述输入必要数值后,如何在 Amazon IoT 控制台中观察发布到影子文档的消息。

在前面的示例中,我们将所需的颜色设置为 yellow。输入每个值后,终端将提示您输入另一个 desired 值。如果您再次输入相同的值 (yellow),应用程序会识别这一点,并提示您输入一个新的 desired 值。

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

现在,假设nin 输入了颜色 green。Amazon IoT 响应请求,并将 reported 值更新为 green。这就是当 desired 状态不同于 reported 状态时产生更新的方式,从而导致增量。

shadow.py 示例应用程序模拟 Device Shadow 交互:

  1. 在终端输入 desired 值(例如 yellow)来发布所需的状态。

  2. 由于 desired 状态不同于 reported 状态(比如说颜色 green),则会产生增量,并且订阅增量的应用程序会收到此消息。

  3. 应用程序响应消息并将其状态更新为 desired 值,yellow

  4. 然后,应用程序会发布一条更新消息,其中包含设备状态的新报告值,yellow

下面显示了终端中显示的消息,其展示了更新申请是如何发布的。

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

在 Amazon IoT 控制台中,影子文档将 reporteddesired 字段更新后的值反映到 green,然后版本号会增加 1。例如,如果以前的版本号显示为 10,则当前版本号将显示为 11。

注意

删除影子不会将版本号重置为 0。当您发布更新请求或创建另一个具有相同名称的影子时,您将看到影子版本递增 1。

编辑影子文档以观察增量事件

shadow.py 示例应用程序也订阅 delta 事件,并在 desired 值出现更改时予以响应。例如,您可以将 desired 值更改为颜色 red。为此,请在 Amazon IoT 控制台中,单击 Edit(编辑)以编辑 Shadow 文档,然后在 JSON 中将 desired 设置为 red,同时将 reported 值保留为 green。保存更改之前,请保持 Raspberry Pi 上的终端打开状态,因为当出现更改时,您会看到终端中显示的消息。

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

保存新值后,shadow.py 示例应用程序响应此更改,并在终端中显示指示增量的消息。然后,您应该看到以下消息出现在输入 desired 值的提示下方。

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

查看来自 shadow.py 中 MQTT 测试客户端中示例应用程序的消息

您可以使用 Amazon IoT 控制台中的 MQTT 测试客户端来监控传递在 Amazon Web Services 账户 中的 MQTT 消息。通过订阅 Device Shadow 服务使用的保留 MQTT 主题,您可以观察在运行示例应用程序时主题收到的消息。

如果尚未使用 MQTT 测试客户端,您可以查看 使用 Amazon IoT MQTT 客户端查看 MQTT 消息。它可以帮助您了解如何使用 Amazon IoT 控制台中的 MQTT 测试客户端来查看通过消息代理时的 MQTT 消息。

  1. 打开 MQTT 测试客户端

    打开 Amazon IoT 控制台中的 MQTT 测试客户端,以便您可以观察 MQTT 主题收到的消息,而不会丢失 MQTT 测试客户端的配置。如果您让 MQTT 测试客户端进入控制台中的其他页面,则 MQTT 测试客户端不会保留任何订阅或消息日志。对于本教程的这一部分,您可以在单独的窗口中打开 Amazon IoT 事物的影子文档和 MQTT 测试客户端,以便更轻松地观察与 Device Shadow 的交互。

  2. 订阅 MQTT 预留的影子主题

    您可以使用 MQTT 测试客户端输入 Device Shadow 的 MQTT 预留主题的名称,并在运行 shadow.py 示例应用程序时订阅它们以接收更新。要订阅主题:

    1. Amazon IoT 控制台中的 MQTT 测试客户端中,选择 Subscribe to a topic(订阅主题)。

    2. Topic filter(主题筛选条件)部分,输入:$aws/things/thingname/shadow/update/#。在这里,thingname 是您之前创建的事物资源的名称(例如,My_light_bulb)。

    3. 保留附加配置设置的默认值,然后选择 Subscribe(订阅)。

    通过使用 # 通配符,您可以同时订阅多个 MQTT 主题,并在单个窗口中观察设备与其影子之间交换的所有消息。有关通配符及其用法的更多信息,请参阅 MQTT 主题

  3. 运行 shadow.py 示例程序和观察消息

    在 Raspberry Pi 的命令行窗口中,如果您已经断开程序的连接,请再次运行示例应用程序,并在 Amazon IoT 控制台中的 MQTT 测试客户端观察消息。

    1. 运行以下命令以重新启动示程序。将 your-iot-thing-nameyour-iot-endpoint 替换为您早前创建的 Amazon IoT 事物名称(例如,My_light_bulb)以及与设备交互的端点名称。

      cd ~/aws-iot-device-sdk-python-v2/samples python3 shadow.py --root-ca ~/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

      shadow.py 示例应用程序随后会开始运行并检索当前影子状态。如果已删除影子或清除当前状态,程序会将当前值设置为 off,然后提示您输入 desired 值。

      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:

      另一方面,如果程序正在运行,并且您将程序重新启动,您将看到终端中报告的最新颜色值。在 MQTT 测试客户端中,您将看到主题 $aws/things/thingname/shadow/get$aws/things/thingname/shadow/get/accepted 的更新。

      假设报告的最新颜色为 green。下面显示的是 $aws/things/thingname/shadow/get/accepted JSON 文件的内容。

      { "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. 在终端中输入 desired 值,例如 yellowshadow.py 示例应用程序响应并在终端中显示以下消息,这些消息显示了 reported 值变更为 yellow 的情况。

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

      Amazon IoT 控制台中的 MQTT 测试客户端中,在 Subscriptions 下,您会看到以下主题收到一条消息:

      • $aws/things/thingname/shadow/update:显示两个 desiredupdated 值更改为颜色 yellow

      • $aws/things/thingname/shadow/update/accepted:显示 desiredreported状态当前的值及其元数据和版本信息。

      • $aws/things/thingname/shadow/update/documents:显示 desiredreported 状态之前以及当前的值,及其元数据和版本信息。

      由于文档 $aws/things/thingname/shadow/update/documents 还包含其他两个主题中包含的信息,我们可以查看该文档以查看状态信息。上一个状态显示报告的值设置为 green、其元数据和版本信息,而当前的状态显示报告的值更新为 yellow

      { "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. 现在,如果您输入另一个 desired 值,您可以看到 reported 值的进一步更改和这些主题收到的消息更新。版本号也会增加 1。例如,如果您输入值 green,之前的状态会报告值 yellow,而当前状态报告值 green

  4. 编辑影子文档以观察增量事件

    要观察对增量主题的更改,请在 Amazon IoT 控制台编辑影子文档。例如,您可以将 desired 值更改为颜色 red。为此,请在 Amazon IoT 控制台中,选择 Edit(编辑),然后在 JSON 中将 desired 值设置为红色,同时保持 reported 设置为 green。在保存更改之前,请保持终端处于开启状态,因为您将看到终端中报告的增量消息。

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

    shadow.py 示例应用程序响应此更改,并在终端中显示指示增量的消息。在 MQTT 测试客户端中,update 主题将收到一条消息,显示对 desiredreported 值的更改。

    您还可以看到主题 $aws/things/thingname/shadow/update/delta 收到一条消息。要查看消息,请选择该主题,其列于 Subscriptions(订阅)下方。

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

排除 Device Shadow 交互中的错误

运行影子示例应用程序时,在观察与 Device Shadow 服务的交互过程中可能会遇到问题。

如果程序运行成功并提示您输入 desired 值,您应该能够通过使用前述影子文档和 MQTT 测试客户端来观察 Device Shadow 交互。但是,如果您无法查看交互,可以检查以下事项:

  • 在 Amazon IoT 控制台中检查事物名称及其影子

    如果您在影子文档中没有看到这些消息,请查看该命令,并确保它与 Amazon IoT 控制台 中的事物名称相符。您还可以通过选择事物资源,然后选择 Shadows(影子)来查看您是否拥有经典影子。本教程主要侧重于与经典影子的交互。

    您还可以确认您使用的设备已连接到互联网。在 Amazon IoT控制台,选择您之前创建的事物,然后选择 Interact(交互)。在事物详细信息页面上,您应该会在此处看到一条消息:This thing already appears to be connected.

  • 检查您订阅的 MQTT 预留主题

    如果在 MQTT 测试客户端中看不到消息,请检查您订阅的主题是否格式正确。MQTT Device Shadow 主题具有格式$aws/things/thingname/shadow/并且可能有 updateget 或者 delete 跟随其后,具体取决于要对影子执行的操作。本教程使用主题 $aws/things/thingname/shadow/#,因此请确保您在测试客户端的 Topic filter(主题筛选条件)部分订阅主题时正确输入。

    输入主题名称时,请确保 thingname 的名称与您之前创建的 Amazon IoT 事物的名称相同。您还可以订阅其他 MQTT 主题,以查看是否已成功执行更新。例如,您可以订阅主题 $aws/things/thingname/shadow/update/rejected 以在更新请求失败时收到一条消息,让您能够调试连接问题。有关预留主题的更多信息,请参阅 影子主题Device Shadow MQTT 主题

查看结果和后续步骤

在本教程中,您学习了如何:

  • 使用 shadow.py 示例应用程序来指定所需的状态并更新影子的当前状态。

  • 编辑影子文档以观察增量事件以及 shadow.py 示例应用程序如何响应。

  • 使用 MQTT 测试客户端订阅影子主题并在运行示例程序时观察更新。

后续步骤

您可以订阅其他 MQTT 预留主题,以观察影子应用程序的更新。例如,如果您只订阅主题 $aws/things/thingname/shadow/update/accepted,则在成功执行更新时只能看到当前状态信息。

您还可以订阅其他影子主题以调试问题或了解有关 Device Shadow 交互的详细信息,还可以调试与 Device Shadow 交互有关的任何问题。有关更多信息,请参阅 影子主题Device Shadow MQTT 主题

您还可以选择通过使用命名影子或使用为 LED 而连接到 Raspberry Pi 的附加硬件来扩展您的应用程序,并使用从终端发送的消息观察其状态的变化。

有关 Device Shadow 服务以及在设备、应用程序和服务中使用该服务的详细信息,请参阅 Amazon IoT Device Shadow 服务在设备中使用影子在应用程序和服务中使用影子