安装设备开发工具包并运行 shadow.py Device Shadow 示例应用程序 - Amazon IoT Core
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

安装设备开发工具包并运行 shadow.py Device Shadow 示例应用程序

本部分介绍如何安装所需的软件和适用于 Python 的 Amazon IoT 设备软件开发工具包,并运行 shadow.py 示例应用程序来编辑影子文档并控制影子的状态。

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

  • 使用已安装的软件和适用于 Python 的 Amazon IoT 设备软件开发工具包以运行示应用程序。

  • 了解使用示例应用程序输入值如何在 Amazon IoT 控制台发布预期的值。

  • 查看 shadow.py 示例应用程序以及它如何使用 MQTT 协议来更新影子的状态。

在运行本教程之前:

您必须已设置好您的 Amazon Web Services 账户 ,配置好您的 Raspberry Pi 设备,并已创建 Amazon IoT 事物和策略,授予设备发布和订阅 MQTT 预留的 Device Shadow 服务主题的权限。有关更多信息,请参阅 创建 Amazon IoT 资源和连接 Raspberry Pi 运行影子应用程序

您必须还安装了 Git、Python 和适用于 Python 的 Amazon IoT 设备软件开发工具包。本教程基于教程 连接 Raspberry Pi 或其他设备 中介绍的概念执行。如果您尚未尝试该教程,我们建议您按照该教程中描述的步骤安装证书文件和设备软件开发工具包,然后返回本教程运行 shadow.py 示例应用程序。

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

运行 shadow.py 示例应用程序

在运行 shadow.py 示例应用程序前,除了安装的证书文件的名称和位置之外,还需要以下信息。

应用程序参数值

参数

在何处查找值

your-iot-thing-name

您之前在 创建事物资源并将策略附加到事物 中创建的 Amazon IoT 事物的名称。

要查找此值,请在 Amazon IoT 控制台中,选择 Manage(管理),然后选择 Things(事物)。

your-iot-endpoint

your-iot-endpoint 值的格式为:endpoint_id-ats.iot.region.amazonaws.com,例如,a3qj468EXAMPLE-ats.iot.us-west-2.amazonaws.com。要查找此值:

  1. Amazon IoT 控制台中,选择 Manage(管理),然后选择 Things(事物)。

  2. 选择您为您的设备创建的 IoT 事物,您在之前使用过的 My_light_bulb,然后选择 Interact(交互)。您的端点会显示在事物详细信息页面的 HTTPS 部分中。

安装并运行示例应用程序

  1. 导航到示例应用程序目录。

    cd ~/aws-iot-device-sdk-python-v2/samples
  2. 在命令行窗口中,按照指示替换 your-iot-endpointyour-iot-thing-name 的值并运行此命令。

    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
  3. 观察示例应用程序:

    1. 为您的账户连接到 Amazon IoT 服务。

    2. 订阅 Delta 事件和 UpdateGet 响应。

    3. 提示您在终端中输入所需的值。

    4. 输出类似于以下内容:

    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:
注意

如果您在运行 shadow.py 示例应用程序时遇到问题,请查看 借助 shadow.py 示例应用程序排查问题。若要获取可能帮助您更正此问题的其他信息,请将 --verbosity debug 参数添加到命令行,以便示例应用程序显示有关其正在执行的操作的详细消息。

在影子文档中输入值并观察更新

您可以在终端中输入值来指定 desired 值,该值还会更新 reported 值。假设您在终端中输入颜色 yellowreported 值也会更新为颜色 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 将为事物资源创建一个默认的经典影子。您可以在 Amazon IoT 控制台中观察您发布到 reporteddesired 中的值,方法是查看您创建的事物资源的影子文档(例如 My_light_bulb)。要查看影子文档中的更新:

  1. 在 Amazon IoT 控制台中,选择 Manage(管理),然后选择 Things(事物)。

  2. 在显示的事物列表中,选择您创建的事物,选择 Shadows(影子),然后选择 Classic Shadow(经典影子)。

影子文档应类似于以下内容,显示为颜色 yellow 设置的 reporteddesired 值。您可以在文档的 Shadow state(影子状态)部分看到这些值。

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

您还可以看到 Metadata(元数据)部分,其中包含请求的时间戳信息和版本号。

您可以使用状态文档版本来确保正在更新的设备影子文档为最新版本。如果您发送另一个更新请求,则版本号将增加 1。当您为更新请求提供版本时,如果状态文档的当前版本与提供的版本不符,该服务将显示 HTTP 409 冲突响应代码并拒绝请求。

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

要了解有关影子文档的详细信息并观察状态信息的更改,请继续阅读下一教程 使用 shadow.py 示例应用程序及 MQTT 测试客户端与 Device Shadow 交互,如本教程的 查看结果和后续步骤 部分所述。或者,您也可以在下一部分中了解 shadow.py 示例代码以及它如何使用 MQTT 协议。

查看 shadow.py 设备软件开发工具包示例应用

本部分将回顾本教程中适用的来自适用于 Python 的 Amazon IoT 设备软件开发工具包 v2中的 shadow.py 示例应用程序。在这里,我们将回顾它如何使用 MQTT 和采用 WSS 协议的 MQTT 来连接到 Amazon IoT Core 。Amazon 公共运行时 (Amazon-CRT) 库提供低级通信协议支持,并包含在适用于 Python 的 Amazon IoT 设备软件开发工具包 v2 中。

虽然本教程使用 MQTT 和 采用 WSS 的 MQTT,Amazon IoT 支持发布 HTTPS 请求的设备。有关从设备发送 HTTP 消息的 Python 程序示例,请参阅使用 Python 的 requests 库的 HTTPS 代码示例

有关如何对设备通信使用何种协议作出明智决定的信息,请查看 为设备通信选择协议

MQTT

shadow.py 示例在 mqtt_connection_builder 中调用 mtls_from_path(此处显示)以使用 MQTT 协议建立与 Amazon IoT Core 的连接。mtls_from_path 使用 X.509 证书和 TLS v1.2 对设备进行身份验证。Amazon-CRT 库处理该连接的较低级别的详细信息。

mqtt_connection = mqtt_connection_builder.mtls_from_path( endpoint=args.endpoint, cert_filepath=args.cert, pri_key_filepath=args.key, ca_filepath=args.root_ca, 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 )
  • endpoint 是您从命令行传入的 Amazon IoT 端点,而 client_id 是在 Amazon Web Services 区域 中唯一标识此设备的 ID。

  • cert_filepathpri_key_filepathca_filepath 是指向设备证书和私钥文件以及根 CA 文件的路径。

  • client_bootstrap 是处理套接字通信活动的通用运行时对象,并在调用 mqtt_connection_builder.mtls_from_path 前实例化。

  • on_connection_interruptedon_connection_resumed 是在设备连接中断和恢复时调用的回调函数。

  • clean_session 表示是否启动新的持久会话,或者如果会话已存在,则重新连接到现有会话。keep_alive_secs 是保持活动状态的值(以秒为单位),以发送到 CONNECT 请求中。在此时间间隔内将自动发送 ping。如果服务器在此值的 1.5 倍之后没有收到 ping,则假定连接丢失。

shadow.py 示例还调用 mqtt_connection_builder 中的 websockets_with_default_aws_signing 以使用采用 WSS 的 MQTT 协议与 Amazon IoT Core 建立连接。采用 WSS 的 MQTT 也使用与 MQTT 相同的参数,并采用以下附加参数:

  • region 是 Signature V4 身份验证使用的Amazon区域,而 credentials_provider 是 Amazon 凭据,用于进行身份验证。区域是从命令行传递的,credentials_provider 对象在调用 mqtt_connection_builder.websockets_with_default_aws_signing 前进行实例化。

  • websocket_proxy_options 是 HTTP 代理选项(如果使用代理主机)。在 shadow.py 示例应用程序中,此值在调用 mqtt_connection_builder.websockets_with_default_aws_signing 前进行实例化。

订阅影子主题和活动

shadow.py 示例尝试建立连接并等待完全连接。如果未连接,命令将排队。连接后,示例将订阅增量事件并更新和获取消息,并发布服务质量 (QoS) 级别为 1 的消息 (mqtt.QoS.AT_LEAST_ONCE)。

当设备订阅 QoS 级别 1 的消息时,消息代理会保存该设备订阅的消息,直到这些消息可以发送到设备。消息代理会重新发送消息,直至收到设备发出的 PUBACK 响应。

有关 MQTT 协议的更多信息,请参阅 查看 MQTT 协议MQTT

有关本教程中如何使用 MQTT、采用 WSS 的 MQTT、持久性会话和 QoS 级别的详细信息,请参阅 查看 pubsub.py 设备软件开发工具包示例应用程序

借助 shadow.py 示例应用程序排查问题

当您运行 shadow.py 示例应用程序时,您应该看到终端中显示的一些消息以及输入 desired 值的提示。如果程序抛出错误,那么请调试以解决错误,您可以从检查系统是否运行了正确的命令开始。

在某些情况下,错误消息可能会指示连接问题,并且看起来类似于:Host name was invalid for dns resolution 或者 Connection was closed unexpectedly。在这种情况下,以下是您可以检查的几个事项:

  • 检查命令中的端点地址

    查看您在命令中输入用来运行示例应用程序的 endpoint 参数(例如 a3qEXAMPLEffp-ats.iot.us-west-2.amazonaws.com),然后在 Amazon IoT 控制台中检查此值。

    要检查是否使用了正确的值:

    1. Amazon IoT 控制台中,选择 Manage(管理),然后选择 Things(事物)。

    2. 选择您为示应用程序创建的事物(例如 My_light_bulb),然后选择 Interact(交互)。

    您的端点会显示在事物详细信息页面的 HTTPS 部分中。您还会看到一条消息,写着:This thing already appears to be connected.

  • 检查证书激活

    证书通过 Amazon IoT Core 对您的设备进行身份验证。

    要检查您的证书是否处于活动状态:

    1. Amazon IoT 控制台中,选择 Manage(管理),然后选择 Things(事物)。

    2. 选择您为示应用程序创建的事物(例如 My_light_bulb),然后选择 Security(安全)。

    3. 选择证书,然后从证书的详细信息页面中选择 Actions(操作)。

    如果在下拉列表中 Activate(激活)不可用,且您只能选择 Deactivate(停用),则表示您的证书处于活动状态。如果并非如此,请选择 Activate(激活)并重新运行示例程序。

    如果程序仍未运行,请检查 certs 文件夹中的证书文件名。

  • 检查附加到事物资源的策略

    当证书对您的设备进行身份验证时,Amazon IoT 策略允许设备执行 Amazon IoT 操作,例如订阅或发布 MQTT 预留主题。

    要检查是否附加了正确的策略:

    1. 查找如前所述的证书,然后选择 Policies(策略)。

    2. 选择显示的策略,并检查它是否描述 connectsubscribereceivepublish 操作,授予设备发布和订阅 MQTT 预留主题的权限。

      如需了解示例策略,请参阅 创建事物影子 Amazon IoT 策略

    如果您看到错误消息,指示与 Amazon IoT 的连接出现问题,这可能是由于您正在为策略使用的权限所导致的。如果是这种情况,建议您从向 Amazon IoT 资源提供完全访问权限的策略开始,然后重新运行示例程序。您可以编辑当前策略,也可以选择当前策略,选择 Detach(分离),然后创建另一个提供完全访问权限的策略并将其附加到您的事物资源。您可以稍后将策略限制为运行程序所需的操作和策略。

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:*" ], "Resource": "*" } ] }
  • 检查您的设备软件开发工具包安装

    如果程序仍未运行,您可以重新安装设备软件开发工具包以确保软件开发工具包安装完整且正确。

查看结果和后续步骤

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

  • 安装所需的软件、工具和适用于 Python 的 Amazon IoT 设备开发工具包。

  • 了解示例应用程序 shadow.py 如何使用 MQTT 协议检索和更新影子的当前状态。

  • 运行 Device Shadow 的示例应用程序,并在 Amazon IoT 控制台中观察和更新影子文档。您还学习了如何在运行程序时解决任何问题和修复错误。

后续步骤

您现在可以运行 shadow.py 示例应用程序,并使用 Device Shadow 控制状态。您可以在 Amazon IoT 控制台中观察并更新影子文档,并观察示例应用程序相应的增量事件。使用 MQTT 测试客户端,您可以订阅预留影子主题并在运行示例程序时观察主题收到的消息。有关如何使用该教程的更多信息,请参阅 使用 shadow.py 示例应用程序及 MQTT 测试客户端与 Device Shadow 交互