AWS IoT Device Shadow 库 - FreeRTOS
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS IoT Device Shadow 库

概述

FreeRTOS Device Shadow API 定义了创建、更新和删除 AWS IoT Device Shadow 的函数。有关 AWS IoT Device Shadow 的更多信息,请参阅 AWS IoT 的 Device Shadow 服务。使用 MQTT 协议访问 Device Shadow 服务。FreeRTOS Device Shadow API 与 MQTT API 配合使用来处理有关使用 MQTT 协议的详细信息。

依赖项和要求

要将 AWS IoT Device Shadow 与 FreeRTOS 结合使用,您需要将设备注册为 AWS IoT 事物。您的事物必须有一个证书和一个允许访问 Device Shadow 的策略。有关更多信息,请参阅 AWS IoT 入门。有关 FreeRTOS 的策略示例,请参阅 AWS IoT Device Shadow 演示应用程序

例如,客户端凭证标头文件位于 freertos/demos/include/aws_clientcredential.h。确保在该标头文件中设置以下常量的值:

clientcredentialMQTT_BROKER_ENDPOINT

您的 AWS IoT 终端节点。

clientcredentialIOT_THING_NAME

IoT 事物的名称。

clientcredentialWIFI_SSID

Wi-Fi 网络的 SSID。

clientcredentialWIFI_PASSWORD

Wi-Fi 密码。

clientcredentialWIFI_SECURITY

网络所使用的 Wi-Fi 安全类型。

keyCLIENT_CERTIFICATE_PEM

与 IoT 事物关联的证书 PEM。

keyCLIENT_PRIVATE_KEY_PEM

与 IoT 事物关联的私有密钥 PEM。

此文件包含在 aws_shadow_lightbulb_on_off.cDevice Shadow 演示应用程序)中。

如果您将开发自己的应用程序,则需要将 aws_client_credentials.h 标头文件包含在应用程序中,然后将凭证作为 MQTTAgentConnectParams 传递到 SHADOW_ClientConnect 以通过 MQTT 连接到 AWS IoT。确保为 MQTTAgentConnectParamspucClientId 字段指定设备的已注册 AWS IoT 事物名称,否则 Device Shadow 客户端将无法连接。

在运行应用程序之前,请确保您的设备上已安装 FreeRTOS MQTT 库。有关更多信息,请参阅 MQTT 库

另请确保 MQTT 缓冲区足够大,能够包含影子 JSON 文件。Device Shadow 文档的最大大小为 8 KB。Device Shadow API 的所有默认设置均可在 aws_shadow_config_defaults.h 文件中进行设置。您可以在 freertos/vendors/vendor/boards/board/aws_demos/config_files/aws_shadow_config.h 文件中修改这些设置中的任意设置。

重要

为 Device Shadow 任务定义的 JSON 格式必须包含 clientToken 字段。clientToken 可以采用任何唯一值。例如,aws_shadow_lightbulb_on_off.c 演示应用程序使用 token-%d,其中 %d 是生成 JSON 文档时的 RTOS 滴答计数。

如果 JSON 格式不包含 clientToken 字段,则对 SHADOW_Delete()、SHADOW_Get() 和 SHADOW_Update() 的调用将超时。

API 参考

对于完整 API 参考,请参阅 Device Shadow C 开发工具包 API 参考

示例用法

  1. 使用 SHADOW_ClientCreate API 创建影子客户端。对于大部分应用程序,唯一可填充的字段为 xCreateParams.xMQTTClientType = eDedicatedMQTTClient

  2. 通过调用 SHADOW_ClientConnect API,并传递 SHADOW_ClientCreate 返回的客户端句柄,来建立 MQTT 连接。

  3. 调用 SHADOW_RegisterCallbacks API 来配置回调,以更新、获取和删除影子。

建立连接后,可以通过以下 API 使用 Device Shadow:

SHADOW_Delete

删除 Device Shadow。

SHADOW_Get

获取当前的 Device Shadow。

SHADOW_Update

更新 Device Shadow。

注意

使用完 Device Shadow 后,调用 SHADOW_ClientDisconnect 断开影子客户端的连接,释放系统资源。