AWS IoT Device Shadow 操作演示

• 本页内容：
  • 简介
  • 源代码组织
  • 配置演示项目
  • 配置 AWS IoT MQTT 代理连接
  • 构建演示项目
  • 功能
    • 连接到 AWS IoT MQTT 代理
    • 删除 Shadow 文档
    • 订阅 Shadow 主题
    • 发送 Shadow 更新
    • 处理 Shadow 增量消息和 Shadow 更新消息

简介

本演示说明如何使用 AWS IoT Device Shadow 库来连接 AWS 设备 Shadow 服务。它使用 coreMQTT 库 与 AWS IoT MQTT 代理 和 coreJSON 解析器建立一个带有 TLS（相互身份验证）的 MQTT 连接来解析 它从 AWS Shadow 服务收到的 Shadow 文档。该演示展示了一些基本 Shadow 操作，例如如何更新 Shadow 文档以及如何删除 Shadow 文档。演示还展示了如何 在 MQTT 库中注册一个回调函数，以处理 shadow /update 和 /update/delta 消息等从 AWS 设备 Shadow 服务中发送的消息。

本演示仅用于学习练习，因为请求更新 Shadow 文档（状态）和更新 响应是由同一应用程序完成的。 在实际生产场景中，外部应用程序（例如， 在用户的手机上运行的应用程序）会请求远程更新设备状态，即使该设备当前 未连接。连接后，设备将确认更新请求。

此演示项目使用 FreeRTOS Windows 端口，因此您可以在 Windows 上使用免费社区版本 Visual Studio 来构建和评估它，而无需任何 MCU 硬件。

源代码组织

演示项目名为 shadow_device_operations_demo.sln，可在 GitHub 上的 FreeRTOS 存储库中找到， 所在目录为：

FreeRTOS-Plus\Demo\AWS\Device_Shadow_Windows_Simulator\Device_Shadow_Demo

配置演示项目

此演示使用 FreeRTOS-Plus-TCP TCP/IP 堆栈，因此请按照 为 TCP/IP 入门 项目提供的说明执行以下操作：

1. 安装必备 组件（例如 WinPCap）。
2. 设置一个静态 或动态 IP 地址、网关地址和网络掩码（可选）。
3. 设置一个 MAC 地址（可选）。
4. 在您的主机上选择 以太网网络接口。
5. （重要！） 请先测试您的网络连接，然后再尝试运行 Shadow 演示。

所有这些设置都应在 Shadow 演示项目中设置。

配置 AWS IoT MQTT 代理连接

在本演示中，您将使用 MQTT 连接到 AWS IoT MQTT 代理。此连接的配置方式与 MQTT 相互 身份验证演示相同。

构建演示项目

此演示项目使用 Visual Studio 的社区免费版。要构建演示，请执行如下操作：

1. 从 Visual Studio IDE 中打开 Visual Studio 解决方案文件 FreeRTOS-Plus\Demo\AWS\Device_Shadow_Windows_Simulator\Device_Shadow_Demo\shadow_main_demo.sln 。
2. 在 IDE 的 “build” 菜单中选择 “build solution”。

功能

该演示创建了一个单个应用程序任务，该任务通过一系列示例循环，演示 shadow /update 和 /update/delta 回调，以模拟切换远程 IoT 设备的状态。该任务发送具有 新的 desired 状态的 shadow 更新，并等待 IoT 设备更改其 reported 状态，以响应 这一新的 desired 状态。此外，还使用 Shadow /update 回调打印不断变化的 Shadow 状态。 此演示还使用安全的 MQTT 连接到 AWS IoT MQTT 代理，并假设设备 shadow 处于 powerOn 状态 。默认情况下，演示使用经典的未命名 Shadow。可以选择通过定义 democonfigSHADOW_NAME 来选择一个命名的 Shadow。

演示执行以下操作：

1. 使用 shadow_demo_helpers.c 中的辅助函数建立 MQTT 连接。
2. 使用 Device Shadow 库定义的宏，为 IoT 设备 shadow 操作汇编 MQTT 主题字符串。
3. 发布到用于删除设备 Shadow 的 MQTT 主题，以删除任何现有设备 Shadow。
4. 为 /update/delta 、/update/accepted 和 /update/rejected 订阅 MQTT 主题——使用 shadow_demo_helpers.c 中的辅助函数。
5. 使用 shadow_demo_helpers.c 中的辅助函数发布所需的 powerOn 状态。这将 把 /update/delta 消息发送到设备。
6. 在 prvEventCallback 中处理传入 MQTT 消息， 并通过使用由设备 Shadow 库定义的函数 (Shadow_MatchTopicString) 确定消息是否和设备 Shadow 相关。如果 消息是设备 shadow/update/delta消息，则主演示函数将发布第二条 消息以更新报告状态为 powerOn。如果收到 /update/accepted 消息， 请验证其是否具有与先前在更新消息中发布的客户端令牌相同的客户端令牌。这将标志着 演示的结束。

演示的结构体 可在 GitHub 上的 ShadowDemoMainExample.c 中 找到。

此屏幕截图显示演示正确执行时的预期输出：

点击放大

连接到 AWS IoT MQTT 代理

为了连接到 AWS IoT MQTT 代理，我们使用与 MQTTConnect() （ MQTT 相互 身份验证演示中所用）相同的方法。

删除 Shadow 文档

要删除 Shadow 文档，请使用设备 Shadow 库定义的宏以空消息调用 xPublishToTopic 。这会使用 MQTT_Publish 发布到 /delete 主题。演示 如何在 prvShadowDemoTask 中完成此操作的示例， 可在 GitHub 上的 ShadowDemoMainExample.c 中找到。

订阅 Shadow 主题

订阅设备 Shadow 主题以接收来自 AWS IoT 代理有关 Shadow 更改的通知。设备 Shadow 主题由设备 Shadow 库中定义的宏汇编。演示 如何在 prvShadowDemoTask 中完成此操作的示例， 可在 GitHub 上的 ShadowDemoMainExample.c 中找到。

发送 Shadow 更新

为发送 shadow 更新，该演示使用设备 Shadow 库定义的宏，通过 JSON 格式的消息调用 xPublishToTopic 。这会使用 MQTT_Publish 发布到 /delete 主题。演示 如何在 prvShadowDemoTask 中完成此操作的示例 可在 GitHub 上的 ShadowDemoMainExample.c 中找到。

处理 Shadow 增量消息和 Shadow 更新消息

已注册到 coreMQTT 客户端库的用户回调函数 （使用函数 MQTT_Init()），将通知我们传入的数据包事件。示例回调函数的代码 可在 GitHub 上的 ShadowDemoMainExample.c 中找到。

回调函数确认传入数据包的类型为 MQTT_PACKET_TYPE_PUBLISH，并使用 Device Shadow 库 API Shadow_MatchTopic 确认传入的消息为 shadow 消息。

如果传入消息是类型为 ShadowMessageTypeUpdateDelta 的 shadow 消息，则 调用 prvUpdateDeltaHandler 来处理此消息。处理程序 prvUpdateDeltaHandler 使 用 CORE JSON 库来解析消息， 以获取 powerOn 状态的增量值， 并将其与本地维护的当前设备状态进行比较。如果这些值不同，则会更新本地设备状态， 以反映 shadow 文档中的 powerOn 状态。prvUpdateDeltaHandler 的 代码 可在 GitHub 上的 ShadowDemoMainExample.c 中找到。

如果传入消息是类型为 ShadowMessageTypeUpdateAccepted 的 shadow 消息，则 调用 prvUpdateAcceptedHandler 来处理此消息。处理程序 prvUpdateAcceptedHandler 使 用 coreJSON 库从消息中获取 clientToken。此处理程序函数 会检查 JSON 消息中的客户端令牌是否与应用程序使用的客户端令牌匹配。如果不匹配， 该函数将记录一条警告消息。prvUpdateAcceptedHandler 的代码 可在 GitHub 上的 ShadowDemoMainExample.c 中找到。