STMCU-管管
发布时间：2025-12-4 16:08
|
2025年10月29日上午8:30 引言 本文介绍了 ST AIoT Craft IoT API，它是为 ST AIoT Craft 平台中的物联网功能提供支持的云后端组件。 ST AIoT Craft IoT API 为构成 IoT 系统的实体提供 CRUD（创建-读取-更新-删除）接口，即：设备 ，网关 及相关遥测 ，命令， 和特性 。
1. 物联网系统组成实体的定义 一个设备 是距离被测量数据源更近的任何物理实体。这些设备配备了传感器和执行器，处理能力有限，并且本身不连接到任何互联网。在 ST AIoT Craft 的背景下，支持的设备示例包括：SensorTile.box PRO 和STWIN.box 板。互联网连接以及其他高级功能，则由……提供。网关。 一个网关 是一个充当连接设备和云/互联网之间中介的组件。它提供了一座桥梁，使数据能够在本地环境和云端/互联网之间有效、安全地流动。许多现代网关还具有强大的处理能力，允许在靠近数据源的位置执行复杂的逻辑，然后再将相关数据发送到云端。 遥测技术 是设备和网关提供的实际数据。遥测数据可以是数据源的原始测量值，例如加速度计的输出，也可以是设备或网关上运行的算法的结果。 命令 是设备和网关在收到请求时可以执行的操作。例如，命令允许用户开始和停止记录来自设备的日志数据，该设备正在监控特定系统的惯性测量。 最后，特性 定义描述设备或网关状态的数据。例如，设备的序列号、固件版本、恒温器所需的温度设置、当前运行模式（“开”、“关”、“待机”）或电池电量。 与房产密切相关，活动 发出组件属性集发生变化的信号。在 ST AIoT Craft IoT API 的上下文中，一个示例事件是当设备或网关连接或断开与互联网的连接时触发的 isConnected 属性的变化。 我们可以用下图概括由 ST AIoT Craft IoT API 管理的物联网系统实体：
图 1 ：物联网系统实体 2. 从实体到云端 现在您已经了解了 ST AIoT Craft IoT API 管理的实体，接下来让我们转向云端，物联网 API 和相关组件都托管在云端。 物联网API的高级架构可以用下图概括：
图 2 ：ST AIoT Craft 物联网 API 架构 如图所示，API 为 IoT 系统实体提供 REST 接口，ST AIoT Craft Web 门户使用该接口来提供 IoT 功能。图中描绘了多个组件，除 AWS Cognito 身份提供程序外，所有组件均在 ST 为 ST AIoT Craft 用户提供的 Azure 环境中运行。 ST AIoT Craft IoT API 作为 Azure 函数运行，这是一种无服务器计算服务，可执行代码，从而无需服务器管理。它会自动扩展规模，并且只按执行时间收费。它利用了 Azure 的三项主要云原生服务：Azure 设备预配服务 (DPS) ，Azure IoT 中心 ， 和Azure CosmosDB 。 这Azure DPS 实现物联网设备的自动化配置和部署，并与……协同工作Azure IoT 中心 进而，在已配置的设备和云之间提供强大的双向通信。回顾上一节，我们描述了物联网系统的组成部分，遥测数据、命令和属性以消息的形式从设备路由到云端。Azure 物联网中心 。ST AIoT Craft API 利用的第三个 Azure 原生组件是Azure CosmosDB 它提供了一个 SQL 数据库，用于存储来自连接设备的遥测数据和事件：当新的遥测数据或事件到达时，它会将数据存储在该数据库中。Azure IoT 中心 它会自动路由到Azure CosmosDB 该服务会将传入的数据存储到数据库的相应表中。 ST AIoT Craft IoT API 的最后一个组件是AWS Cognito 这是一个 AWS 原生组件，提供用户身份验证和访问控制的托管服务。它的主要作用是与 IoT API 交互，以验证和授权来自 ST AIoT Craft 网络门户的 REST 调用。 ST 为所有 ST AIoT Craft 用户提供此云基础设施。用户无需费力设置所需组件，即可直接体验该平台的物联网功能。对于高级用例，用户还可以设置自己的 Azure 云基础架构，并利用提供的 Terraform 脚本将其连接到 ST AIoT Craft。 3. ST AIoT Craft IoT API 接口 在对物联网系统实体和参考架构有了清晰的了解之后，我们现在可以探索 ST AIoT Craft 物联网 API 接口，如下图所示：
图 3 ：ST AIoT Craft IoT API 规范 3.1 示例：智能恒温器 在这个例子中，我们考虑一个非常简单的场景，即一个连接到云端的智能恒温器，并利用 ST AIoT Craft API 对其进行配置，以及观察其事件和遥测数据。 我们使用的智能恒温器是一个模拟设备，它是 Azure IoT SDK 的一部分，支持多种编程语言。我们使用的是 Python 实现，可以在以下位置找到：Azure IoT Python SDK GitHub 仓库。 让我们更详细地了解一下智能恒温器的功能，其正式描述可在以下位置找到：Azure IoT GitHub 仓库。它遵循 DTDL（数字孪生定义语言）语法，DTDL 是一种用于对现实世界设备进行建模的开放标准语言。它使他们能够通过以下方式定义自己的能力特性 ，遥测技术， 和命令 本文开头提出的概念。 从智能恒温器 DTDL 模型中，我们可以看到它定义了：
掌握了这些知识后，我们现在可以使用 ST AIoT Craft IoT API 来配置设备并与之交互。 将设备连接到云环境的第一步是注册设备，因此让我们调用 API 的专用端点： POST https://staiotcraft-iot-api-dev-efd9cxewbwbnfvgt.westeurope-01.azurewebsites.net/v1/devices 授权：Bearer ACCESS_TOKEN { "name": "示例智能恒温器", "部署": "example_deployment", "isIoTEdgeCapable": false } 根据上述请求，我们将创建一个名为“智能恒温器示例 “，它分别属于名为“的项目和部署”的项目和部署。示例项目 “ 和 ”示例部署 “。” 项目和部署是组织概念，有助于构建设备的配置：一个项目由一个或多个部署组成，而部署又可以由一个或多个设备组成。这 ”isIoTEdgeCapable ：错误的 该标志表明智能恒温器不具备网关功能，而只是一个简单的联网设备。 执行上述 API 调用后，我们得到以下响应： { “id”: “c8dc6706-a327-4f99-ab21-80010f667860” "idScope": "0ne00D47E07", "provisioningStatus": "已启用", 芯片 "name": "example smart thermostat", "project": "example_project", "deployment": "example_deployment", "f5c5a7a8-44fb-4b16-bcef-df8dc08fae8f" }, "isIoTEdgeCapable": false, "connectionState": "已断开连接", SigFox凭证 "type": "symmetricKey", "symmetricKey": { "primaryKey": "UHuGlQXGmClq6ts02WNaoMOQOXQRTfJpHXCgwnn2Xc26yjbQ Jvxo9Zrpfz96 juy5Je5mo68sCeAIoT2Oh9tg==", "secondaryKey": "xUzWWl4BcQldim1W/ISk3c9iV8mQJv6eaesXrBdkJR/ 1N9wZWzEdAZox8kWSeGTy63Js4HXmooJAIoT9la9QQ==" }, 录音性能 }, "lastActivityTime": null, “modelId”：null， “模块”：null } 回复中包含大量信息，因此我们只关注最重要的信息。 id 字段提供我们设备的唯一 ID，我们将使用它在与 IoT API 交互时以及将智能恒温器连接到云端时识别设备。 idScope 提供我们云应用程序的唯一 ID，我们将在下一阶段将设备连接到云环境时使用它。 标签字段包含有关我们设备的元数据，例如设备名称、所属项目和部署。 最后，证书 该字段包含安全密钥，云环境使用这些密钥来验证我们的智能恒温器。 3.1.1 智能恒温器与云应用程序的连接 并不是说我们创造了一个新的设备，而是现在需要将智能恒温器连接到云应用程序。 要配置示例恒温器应用程序以连接到云环境，只需在启动示例 Python 代码时导出以下 BASH 变量： IOTHUB_DEVICE_SECURITY_TYPE="DPS" IOTHUB_DEVICE_DPS_ID_SCOPE="0ne00D47E07" IOTHUB_DEVICE_DPS_DEVICE_ID="c8dc6706-a327-4f99-ab21-80010f667860" IOTHUB_DEVICE_DPS_DEVICE_KEY="UHuGlQXGmClq6ts02WNaoMOQOXQRTfJpHXCgwnn2Xc26yjbQ Jvxo9Zrpfz96 juy5Je5mo68sCeAIoT2Oh9tg=" 如果配置正确，智能恒温器应用程序将启动，并提供如下启动消息： 起始时间：2025-08-13T13:03:40.079720 00:00 设备已分配 staiotcraft-iothub-dev.azure-devices.net c8dc6706-a327-4f99-ab21-80010f667860 监听命令请求和属性更新 按 Q 退出 发送温度遥测数据 已发送消息 如消息日志所示，连接成功后，恒温器开始向云端发送遥测数据。让我们使用 ST AIoT Craft IoT API 来检索它们。 要获取设备遥测数据，我们可以使用以下 API 调用来访问遥测端点： Authorization: Bearer ACCESS_TOKEN 上述 API 调用检索属于名为“项目”的所有设备的全部遥测数据。示例项目 并部署到名为示例部署 。由于我们只创建了一个设备，因此我们只能获得智能恒温器设备传输的遥测数据，这些数据由 API 响应提供给我们： [ { "deviceID": "c8dc6706-a327-4f99-ab21-80010f667860", "timestamp": "2025-08-13T13:12:29.6760000Z", 温度：35 }, { "deviceID": "c8dc6706-a327-4f99-ab21-80010f667860", "timestamp": "2025-08-13T13:12:19.5040000Z", "body": { 温度：13 }, { "deviceID": "c8dc6706-a327-4f99-ab21-80010f667860", "timestamp": "2025-08-13T13:12:09.3320000Z", "body": { 温度：16 } ] 如上所示，API 返回一个遥测数据数组：该数组中的每个条目都是由我们的智能恒温器设备发送的遥测数据，并提供以下信息：
获取设备的遥测数据并不是 ST AIoT Craft IoT API 提供的唯一功能，我们还可以做更多的事情。当我们的设备连接到云环境时，连接状态事件 已生成，表明设备连接成功。让我们通过以下物联网 API 调用来获取它： Authorization: Bearer ACCESS_TOKEN 事件端点使用与先前 API 相同的参数，返回属于名为“项目”的所有设备的所有事件。示例项目 并部署到名为示例部署 。同样，由于我们只有一个设备，所以我们可以获取智能恒温器的所有事件： [{ "eventType": "connection_state_event", "deviceID": "c8dc6706-a327-4f99-ab21-80010f667860", "timestamp": "2025-08-13T13:04:28.0370000Z", "body": { "sequenceNumber": "000000000000000001DB26E3F31EC1C400000044000000000000000000000105", "state": "deviceConnected" }] 正如我们所预期的，我们得到了一个连接状态事件 与我们设备的状态相关，表明与云端的连接已成功完成。 3.1.2 如何与设备的属性进行交互 现在让我们来看一个如何与设备属性进行交互的例子。我们的智能恒温器提供了一个专用属性，用于设置房间的目标温度。目标温度 我们可以使用*设备*/{{deviceID}} 设置它的端点： 授权：Bearer {{accessToken}} { "properties": { 目标温度：22.5 } API 调用执行后，所需值会被传输到我们的智能恒温器，智能恒温器在接收到所需值后会打印以下输出： 所需属性补丁中的数据为：{'$version': 2, 'targetTemperature': 22.5} 智能恒温器还提供了一个名为“只读属性”的属性自上次重启以来的最高温度 指定自上次设备重启以来的最高温度，让我们使用 IoT API 读取其值。为此，我们可以利用之前用过的同一个事件端点： Authorization: Bearer ACCESS_TOKEN 因为 API 响应将提供智能恒温器迄今为止发出的所有事件。结果数组中可能会出现多个条目，但稍加查找即可找到以下条目： { "eventType": "change_event", "deviceID": "c8dc6706-a327-4f99-ab21-80010f667860", "timestamp": "2025-08-13T13:46:49.1280000Z", "body": { "properties": { 报告错误 "maxTempSinceLastReboot": 10.96, "$metadata": { "$lastUpdated": "2025-08-13T13:46:49.0139609Z", "上次重启后的最大温度": { "$lastUpdated": "2025-08-13T13:46:49.0139609Z" } }, "$version": 13765 } } } 提供了报告值自上次重启以来的最高温度 我们智能恒温器的属性（检查该值）*设备*ID 字段），以及时间戳字段中属性更改发生的时间戳。 设置和读取属性使我们能够与设备进行交互，但这通常还不够。许多设备提供命令，从而可以进行更复杂的交互。这适用于我们的智能恒温器，因为它提供了一个 getMaxMinReport 命令，该命令会返回设备记录的最高温度、最低温度和平均温度。 让我们使用 ST AIoT Craft IoT API 来请求执行这样的命令。为此，我们可以利用*设备*/{{deviceID}}/ 方法 终点： Authorization: Bearer ACCESS_TOKEN { "name": "getMaxMinReport" } 当我们执行上述 API 调用时，命令执行请求会到达我们的智能恒温器，智能恒温器收到请求后会打印以下输出： 已收到带有有效载荷的命令请求。 有效载荷为空。 生成完成 {"avgTemp": 34.6, "endTime": "2025-08-13T16:39:54.062918", "maxTemp": 49, "minTemp": 10, "startTime": "2025-08-13T16:38:34.062890"} 这些行告诉我们，设备已成功接收并执行了我们请求的命令。随后，它将结果传回，我们通过 API 的响应负载获取到该结果： { "avgTemp": 34.6, "endTime": "2025-08-13T16:39:54.062918", “maxTemp”：49， "minTemp": 10, "startTime": "2025-08-13T16:38:34.062890" } 现在我们已经探索了智能恒温器的所有功能，可以通过在运行恒温器的终端窗口中按下 q 键来将其关闭： Sent message Sent message Q 辞职…… 设备关机时，与云环境的连接也会关闭。正如我们所预期的，通过调用活动 再次检查端点，我们通过搜索确认智能恒温器设备已离线。设备已断开连接 从 API 响应中获取的 events 数组中的事件： { "eventType": "connection_state_event", "deviceID": "c8dc6706-a327-4f99-ab21-80010f667860", "timestamp": "2025-08-13T14:57:27.4580000Z", "body": { "sequenceNumber": "000000000000000001DB26E3F31EC1C40000004400000000000000000000010D", "state": "deviceDisconnected" } } 总结 在本文中，我们了解了如何利用 ST AIoT Craft IoT API 来注册和连接新设备。此外，还可以与设备交互，设置和读取设备的属性，获取相关的遥测数据，并调用设备的命令。立即试用 ST AIoT Craft IoT API 的功能远不止本文中的示例；它还提供与网关设备及其软件模块的交互。 |
微信公众号
手机版
