AzureIoTHubClient 1.10.0

AzureIoTHubClient 1.10.0

×

由 Jeremy Bobotek、Ewerton Scaboro Da Silva、Jelani Brandon、Rajeev Massand 和 Dane Walton 维护。

 
依赖
AzureMacroUtils= 1.4.0
AzureuMockC= 1.4.0
AzureIoTUtility= 1.10.0
AzureIoTuAmqp= 1.10.0
AzureIoTuMqtt= 1.10.0
 

AzureIoTHubClient 1.10.0

  • 由
  • Microsoft
此库已弃用。

Azure IoT C SDKs and Libraries

Build Status

此存储库包含以下内容

  • Azure IoT Hub Device C SDK 用于连接运行 C 代码的设备到 Azure IoT Hub。
  • Azure IoT Hub Device Provisioning Service Client SDK 用于将设备注册到 Azure IoT Device Provisioning Services 并管理注册列表。
  • Azure IoT Hub Service C SDK 用于从服务器端 C 应用程序与 Azure IoT Hub 服务实例接口。
  • C 的序列化库 帮助在您的设备上序列化和反序列化数据。

目录

软件包和库

开始使用 Azure IoT SDK 的最简单方法是使用以下软件包和库

示例

以下是一组简单的示例，可以帮助您开始使用

编译 SDK

当您的平台没有提供软件包或库，或者您想修改 SDK 代码，或者将 SDK 移植到新平台时，您可以使用存储库中提供的构建环境。

SDK API 参考文档

C SDK 的 API 参考文档可以在这里找到：这里。

其他 Azure IoT SDK

要寻找其他语言的 Azure IoT SDK，请参阅 azure-iot-sdks 存储库。

关于受限制设备的说明： 嵌入式C SDK 是受限制设备的替代方案，它支持 BYO（自行携带）网络方法：物联网开发者可以选择他们自己的 MQTT 客户端、TLS 和 Socket 来创建设备解决方案。有关嵌入式 C SDK 的更多信息，请参阅此处。

开发 Azure 物联网应用程序

要了解更多关于构建 Azure 物联网应用程序的信息，您可以访问Azure 物联网开发者中心。

关键功能和路线图

设备客户端 SDK

✔️功能可用✖️功能计划但尚未支持➖未计划支持

功能 mqtt mqtt-ws amqp amqp-ws https 描述
身份验证 ✔️ ✔️* ✔️ ✔️* ✔️* 使用受支持的认证方式（包括私钥、SASToken、X-509 自签名的证书和证书颁发机构（CA）签名的证书）安全地将设备连接到 IoT 中心。*IoT 中心目前只支持通过 AMQP 和 MQTT 使用 X-509 CA 签名的证书。
发送设备到云的消息 ✔️* ✔️* ✔️* ✔️* ✔️* 以添加自定义属性的方式向 IoT 中心发送设备到云的消息（最大 256KB）。IoT 中心目前只支持在 AMQP 和 HTTPS 上进行批处理发送。此 SDK 支持通过 HTTP 进行批处理发送。*正在对通过 AMQP 和 AMQP-WS 进行批处理发送，并在 D2C 消息上添加系统属性进行中。
接收云到设备的消息 ✔️* ✔️* ✔️ ✔️ ✔️ 接收云到设备消息，并从 IoT 中心读取相关的自定义和系统属性，有选项完成/拒绝/放弃 C2D 消息。*IoT 中心目前仅支持通过 HTTPS 和 AMQP 完成选项/拒绝/放弃 C2D 消息。
设备孪生 ✔️* ✔️* ✔️* ✔️* ➖ IoT 中心为连接到 IoT 中心的每个设备持久化设备孪生。设备可以执行获取双重标签、订阅所需属性等操作。*正在对发送报告属性版本和所需属性版本进行中。
直接方法 ✔️ ✔️ ✔️ ✔️ ➖ IoT 中心让您能够从云调用设备上的直接方法。SDK 支持 method specific 和 generic 操作的处理程序。
上传文件到 Blob ➖ ➖ ➖ ➖ ✔️ 设备可以启动文件上传，并在上传完成后通知 IoT 中心。文件上传需要 HTTPS 连接，但可以通过客户端使用任何协议进行其他操作。
连接状态和错误报告 ✔️* ✔️* ✔️* ✔️* ✖️ 针对物联网网关支持的错误代码进行错误报告。*本SDK支持认证和设备未找到的错误报告。
重试策略 ✔️* ✔️* ✔️* ✔️* ✖️ 对于未成功发送设备到云的消息的重试策略有两个选项：不尝试，默认使用带有抖动的指数退避。
单连接中的设备多路复用 ➖ ➖ ✔️ ✔️ ✔️
连接池 - 指定连接数 ➖ ➖ ✖️ ✖️ ✖️

此SDK还包含您可以设置的平台特定功能。您可以在本文档中找到详细信息列表。

服务客户端SDK

✔️功能可用✖️功能计划但尚未支持➖未计划支持

功能 C 描述
身份注册（CRUD） ✔️* 使用您的后端应用程序对单个设备或批量设备执行CRUD操作。本SDK仅支持使用ID/密钥对创建单个设备的CRUD操作。
云到设备消息 ✔️ 使用您的后端应用程序以AMQP和AMQP-WS发送云到设备消息，并设置云到设备消息接收器。
直接方法操作 ✔️ 使用您的后端应用程序在设备上调用直接方法。
设备双操作 ✔️* 使用您的后端应用程序执行设备双操作。*双操作属性更新回调和替换双操作正在进行中。
查询 ✖️ 使用您的后端应用程序进行信息查询。
作业 ✖️ 使用您的后端应用程序执行作业操作。
文件上传 ✖️ 设置您的后端应用程序以发送文件上传通知接收器。

设备配置客户端SDK

本存储库包含设备配置客户端SDK，适用于设备配置服务。

✔️功能可用✖️功能计划但尚未支持➖未计划支持

功能 mqtt mqtt-ws amqp amqp-ws https 描述
TPM单个注册 ➖ ➖ ✔️ ✔️ ✔️ 本SDK支持通过使用单个注册将您的设备连接到设备配置服务，并通过可信平台模块。本快速入门演示了如何使用TPM创建单个注册的模拟设备。当前，设备配置服务不支持通过MQTT进行TPM注册。
X.509单个注册 ✔️ ✔️ ✔️ ✔️ ✔️ 本SDK支持通过使用单个注册将您的设备连接到设备配置服务，并通过X.509叶证书。本快速入门演示了如何使用X.509创建单个注册的模拟设备。
X.509注册组 ✔️ ✔️ ✔️ ✔️ ✔️ 本SDK支持通过使用注册组将您的设备连接到设备配置服务，并通过X.509根证书。

资源分配服务 SDK

此存储库包含用于设备资源分配服务的 资源分配服务客户端 SDK，以编程方式注册设备。

功能 支持 描述
使用 TPM 单个注册的 CRUD 操作 ✔️ 使用服务 SDK 使用 TPM 以编程方式管理设备注册。请访问 示例文件夹 以了解更多有关此功能的信息。
使用 TPM 单个注册的批量 CRUD 操作 ✔️ 使用服务 SDK 以编程方式批量管理使用 TPM 的设备注册。请访问 示例文件夹 以了解更多有关此功能的信息。
使用 X.509 单个注册的 CRUD 操作 ✔️ 使用服务 SDK 使用 X.509 单个注册以编程方式管理设备注册。请访问 示例文件夹 以了解更多有关此功能的信息。
使用 X.509 组注册的 CRUD 操作 ✔️ 使用服务 SDK 使用 X.509 组注册以编程方式管理设备注册。请访问 示例文件夹 以了解更多有关此功能的信息。
查询注册 ✔️ 使用服务 SDK 以编程方式查询注册状态。请访问 示例文件夹 以了解更多有关此功能的信息。

操作系统平台和硬件兼容性

C 意图平台设备 SDK 可与广泛的操作系统平台和设备一起使用。

最低要求为设备平台能够支持以下情况

  • 能建立 IP 连接：只有具备 IP 功能的设备可以直接与 Azure IoT Hub 通信。
  • 支持 TLS：需要与 Azure IoT Hub 建立安全通信通道。
  • 支持 SHA-256 (可选)：在服务中对设备进行认证时生成安全令牌所必需的。不同的认证方法都可用，并非所有方法都要求 SHA-256。
  • 有实时时钟或实现代码以连接到 NTP 服务器：建立 TLS 连接和生成用于认证的安全令牌所必需的。
  • 至少有 64KB 的 RAM：SDK 的内存占用取决于使用的 SDK 和协议以及目标平台。最小占用是在针对微控制器进行时实现的。
  • 为 incoming SSL 最大内容长度缓冲区设置至少 4KB 的 RAM：对于一些 TLS 库，这可能是一个可配置的选项，默认可能已设置为 4KB 以适应内存占用较低的设备。在 TLS 握手过程中，IoT Hub 服务将发送包含 IoT Hub 服务器端证书的 Server Hello，作为 Server Hello 有效负载的一部分。在 IoT Hub 服务器端证书的 更新 过程中，IoT Hub 服务端将进行检查，以防止 Server Hello 超过 4KB 的限制，以确保已设置 4KB 限制的现有设备在证书更新后仍能像以前一样继续工作。

平台支持详细信息可以在这篇文档中找到。您可以在Azure Certified for IoT 设备目录中找到各种 SDK 测试过的所有操作系统平台的详尽列表。请注意，您可能仍然能够在不在该页面上列出的操作系统和硬件平台上使用 SDK：所有 SDK 都是开源的，并设计为可移植。如果您有任何建议、反馈或问题要报告，请参阅下方的贡献和支持部分。

将 Azure IoT 设备客户端 SDK for C 迁移到新设备

C SDKs 和库

  • 使用 ANSI C (C99) 编写，并避免使用编译器扩展，以最大化代码的可移植性和广泛平台兼容性。
  • 暴露一个平台抽象层，以隔离操作系统依赖项（线程和互斥机制、通信协议等，例如 HTTP）。有关我们抽象层的更多信息，请参阅我们的迁移指南。

在存储库中，您可以找到有关在 Linux、Windows 和微控制器平台上编译和运行设备客户端 SDK for C 的说明和构建工具（有关编译 C 设备客户端的更多信息，请参阅上面的链接）。

如果您正在考虑将设备客户端 SDK for C 迁移到新平台，请查看迁移指南文档。

贡献、反馈和问题

如果您遇到任何错误、有新功能的建议或想成为本项目的积极贡献者，请按照贡献指南提供的说明操作。

支持

  • 对 SDK 有功能请求吗？请到用户声音上发布，以帮助我们确定优先级。
  • 有技术问题？请在带有“azure-iot-hub”标签的 Stack Overflow 上提问。
  • 需要支持？每位有活跃 Azure 订阅的客户都可以获得带有保证响应时间的 支持。请提交工单，以便从微软支持团队获得帮助。
  • 发现了一个错误？请帮助我们通过详细记录它并在 GitHub 上提交问题来修复它（C, Java, .NET, Node.js, Python）。

阅读更多

SDK 文件夹结构

/c-utility, /uamqp, /umqtt, /parson

这些是与其他项目共享的代码，例如适配器和协议实现，作为 Git 子模块。请注意，其中一些包含嵌套子模块。

/blob

此文件夹包含用于访问 Azure blob 存储的客户端组件。

/dps_client

此文件夹包含设备预配服务的客户端库。

/certs

包含与Azure IoT Hub通信所需的证书。

/doc

该文件夹包含应用程序开发指南和设备设置说明。

/build_all

包含客户端库和依赖组件的平台特定构建脚本。

/iothub_client

包含提供库原始消息功能的Azure IoT Hub客户端组件。请参阅API文档和示例，了解如何使用它。

  • 构建：为每个平台（例如Windows、Linux、Mbed）有一个子文件夹。包含用于生成库二进制文件的makefiles、批处理文件和解决方案。
  • devdoc：包含要求、设计笔记、手册。
  • inc：公共包含文件。
  • src：客户端库源文件。
  • samples：包含简单示例。
  • tests：源代码的单元和端到端测试。

/serializer

包含在原始消息库之上提供建模和JSON序列化功能的库。这些库简化了结构化数据和命令控制的上传，以便与Azure IoT服务一起使用。请参阅API文档和示例，了解如何使用它。

  • 构建：为每个平台（例如Windows、Linux、Mbed）有一个子文件夹。包含用于生成库二进制文件的makefiles、批处理文件和解决方案。
  • devdoc：包含要求、设计笔记、手册。
  • inc：公共包含文件。
  • src：客户端库源文件。
  • samples：包含简单示例。
  • tests：源代码的单元测试和端到端测试。

/iothub_service_client

包含库，允许与物联网平台服务交互，执行发往设备的消息发送和设备标识注册管理等功能。

/testtools

包含当前用于测试客户端库的工具：Mocking 框架（micromock）、通用测试执行器（CTest）、单元测试项目模板等。

/tools

其他工具：compilembed、mbed_build、traceabilitytool（检查规范需求与代码实现的一致性）。

长期支持

该项目提供长期支持（LTS）版本，以便不使用最新特性的用户免受不必要更改的影响。

每6个月将创建一个新的LTS版本。当前LTS分支的寿命计划为一年。LTS分支将收到属于以下任意类别的所有错误修复：

  • 安全漏洞修复
  • 关键漏洞修复

LTS分支不会引入新功能。

LTS分支的名称为 lts_mm_yyyy，其中 mm 和 yyyy 是创建分支的月份和年份。此类分支的示例是 lts_07_2017。

时间表1

下表展示了LTS分支与发布软件包的映射关系

软件包 Github 分支 LTS 状态 长期支持版本开始日期 维护结束日期 移除日期
Vcpkg：2020-07-19
Xenial：0.2.0.0-27xenial
Trusty：0.2.0-27trusty
Bionic：0.2.0.0-20bionic
 lts_07_2020 活动状态 2020-07-19 2021-07-19 2021-07-19
Vcpkg：2020-02-07.1
Xenial：0.2.0.0-26xenial
Trusty：0.2.0-26trusty
Bionic：0.2.0.0-19bionic
 lts_02_2020 活动状态 2020-02-04 2021-02-04 2021-02-04
  • 1所有预定日期均可能由 Azure IoT SDK 团队进行更改。

计划发布时间表

本项目采用了 Microsoft 开源行为准则。更多信息请参阅 行为准则常见问题解答，或联系 [email protected] 解决任何额外的问题或意见。

Microsoft 收集性能和用法信息，这些信息可用于提供和改进 Microsoft 产品和服务，并提高您的体验。欲了解更多信息，请查看 隐私声明。