通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

教程：将 ESPRESSIF ESP32-Azure IoT Kit 连接到 IoT 中心

  • 项目

在本教程中，用户将使用 Azure FreeRTOS 中间件将 ESPRESSIF ESP32-Azure IoT Kit（现统称为 ESP32 DevKit）连接到 Azure IoT。

你将完成以下任务：

  • 安装一组嵌入式开发工具，用于编写 ESP32 DevKit
  • 生成一个映像并将其刷写到 ESP32 DevKit
  • 使用 Azure CLI 创建和管理 ESP32 DevKit 连接到的 Azure IoT 中心
  • 使用 Azure IoT Explorer 向 IoT 中心注册设备，查看设备属性，查看设备遥测数据，并在设备上调用直接命令

先决条件

  • 运行 Windows 10 或 Windows 11 的电脑
  • 用于克隆存储库的 Git
  • 硬件
  • 一个有效的 Azure 订阅。 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

准备开发环境

安装工具

若要设置开发环境，请首先安装 ESPRESSIF ESP-IDF 生成环境。 安装程序包含克隆、生成、闪存和监视设备所需的所有工具。

安装 ESP-IDF 工具：

  1. 下载并启动 ESP-IDF v5.0 离线安装程序。
  2. 当安装程序列出了要安装的组件时，请选择所有组件并完成安装。

克隆存储库

克隆以下存储库以下载所有示例设备代码、安装脚本和 SDK 文档。 如果先前已克隆此存储库，则无需再次克隆。

要克隆存储库，请运行以下命令：

git clone --recursive  https://github.com/Azure-Samples/iot-middleware-freertos-samples.git

对于 Windows 10 和 11，确保启用了长路径。

  1. 若要启用长路径，请参阅在 Windows 10 中启用长路径。

  2. 在 git 中，在终端中使用管理员权限运行以下命令：

    git config --system core.longpaths true

创建云组件

创建 IoT 中心

可使用 Azure CLI 来创建 IoT 中心，用于处理设备的事件和消息。

若要创建 IoT 中心：

  1. 启动 CLI 应用。 若要在本快速入门的其余部分运行 CLI 命令，请复制命令语法，将其粘贴到 CLI 应用中，编辑变量值，然后按 Enter。

    • 如果使用 Cloud Shell，请右键单击 Cloud Shell 的链接，然后选择要在新选项卡中打开的选项。
    • 如果要在本地使用 Azure CLI，请启动 CLI 控制台应用程序并登录到 Azure CLI。

  2. 运行 az extension add，将“azure-iot”扩展安装或升级到当前版本。

    az extension add --upgrade --name azure-iot

  3. 运行 az group create 命令创建资源组。 以下命令在“centralus”区域创建名为“myResourceGroup”的资源组。

    注意

    可以选择设置备用 location。 若要查看可用位置，请运行 az account list-locations。

    az group create --name MyResourceGroup --location centralus

  4. 运行 az iot hub create 命令创建 IoT 中心。 创建 IoT 中心可能需要数分钟的时间。

    YourIotHubName。 将代码中的占位符替换为你为 IoT 中心选择的名称。 IoT 中心名称必须在 Azure 中全局唯一。 此占位符在本快速入门的其余部分中用于表示唯一的 IoT 中心名称。

    --sku F1 参数在免费层中创建 IoT 中心。 免费层中心具有有限的功能集，用于概念证明应用程序。 有关 IoT 中心层、功能和定价的详细信息，请参阅 Azure IoT 中心定价。

    az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName} --sku F1 --partition-count 2

  5. 创建 IoT 中心后，在控制台中查看 JSON 输出，并复制 hostName 值用于后面的步骤。 hostName 值如以下示例所示：

    {Your IoT hub name}.azure-devices.net

配置 IoT Explorer

在本快速入门的其余部分中，会使用 IoT Explorer 将设备注册到 IoT 中心，查看设备属性和遥测数据，并将命令发送到设备。 在本部分，我们将配置 IoT Explorer，以便连接到创建的 IoT 中心并从公共型号存储库中读取即插即用型号。

若要添加与 IoT 中心的连接：

  1. 安装 Azure IoT 资源管理器。 此工具是用于监视和管理 Azure IoT 资源的跨平台实用工具。

  2. 在 CLI 应用中，运行 az iot hub connection-string show 命令以获取用于 IoT 中心的连接字符串。

    az iot hub connection-string  show --hub-name {YourIoTHubName}

  3. 复制不带两旁引号字符的连接字符串。

  4. 在 Azure IoT Explorer 的左侧菜单中选择“IoT 中心”。

  5. 选择“+ 添加连接”。

  6. 将连接字符串粘贴到“连接字符串”框中。

  7. 选择“保存”。

    屏幕截图显示如何在 IoT Explorer 中添加连接。

如果连接成功，IoT Explorer 将切换到“设备”视图。

若要添加公共模型存储库：

  1. 在 IoT Explorer 中，选择“主页”以返回到主页视图。

  2. 在左侧菜单中，选择“IoT 即插即用设置”。

  3. 确认存在具有 https://devicemodels.azure.com 终结点的现有公共存储库条目。

    注意

    如果没有公共存储库条目，请选择“+添加”，从下拉菜单中选择“公共存储库”，指定 https://devicemodels.azure.com 终结点值，然后选择“保存”。

    已完成的公共存储库条目如以下屏幕截图所示：

    屏幕截图显示如何在 IoT Explorer 中添加公共型号存储库。

注册设备

在本部分中，将创建一个新设备实例，并将其注册到所创建的 IoT 中心。 在后面的部分中，会使用新注册的设备的连接信息安全连接物理设备。

若要注册设备：

  1. 从 IoT Explorer 的主页视图中，选择“IoT 中心”。

  2. 此时应出现之前添加的连接。 在“连接属性”下面选择“查看此中心的设备”。

  3. 选择“+ 新建”，然后输入设备的设备 ID，例如 mydevice。 将所有其它属性保持不变。

  4. 选择“创建” 。

    Azure IoT Explorer 设备标识的屏幕截图。

  5. 使用复制按钮复制“设备 ID”和“主键”字段。

在继续下一部分之前，请将从前面的步骤中检索到的以下每个值保存到安全位置。 在下一部分使用这些值来配置设备。

  • hostName
  • deviceId
  • primaryKey

准备设备

若要将 ESP32 DevKit 连接到 Azure，需要修改配置设置、生成映像，并将映像刷写到设备。

设置环境

若要启动 ESP-IDF 环境，请执行以下操作：

  1. 选择 Windows“开始”，找到“ESP-IDF 5.0 CMD”并运行它。

  2. 在 ESP-IDF 5.0 CMD 中，导航到此前克隆的 iot-middleware-freertos-samples 目录。

  3. 导航到 ESP32-Azure IoT Kit 项目目录 demos\projects\ESPRESSIF\aziotkit。

  4. 运行以下命令以启动配置菜单：

    idf.py menuconfig

添加配置

添加无线网络配置：

  1. 在“ESP-IDF 5.0 CMD”中，选择“FreeRTOS 示例配置的 Azure IoT 中间件 --->”，然后按 Enter。

  2. 使用本地无线网络凭据设置以下配置设置。

    设置 值
    WiFi SSID {Wi-Fi SSID}
    WiFi 密码 {Wi-Fi 密码}

  3. 按 Esc 返回上一菜单。

若要添加配置以连接到 Azure IoT 中心，请执行以下操作：

  1. 选择“FreeRTOS 主任务配置的 Azure IoT 中间件 --->”，然后按 Enter。

  2. 将以下 Azure IoT 配置设置设为创建 Azure 资源后保存的值。

    设置 值
    Azure IoT 中心 FQDN {你的主机名}
    Azure IoT 设备 ID {你的设备 ID}
    Azure IoT 注册设备对称密钥 {你的主密钥}

    注意

    在“Azure IoT 身份验证方法”设置中，确认已选择“对称密钥”默认值。

  3. 按 Esc 返回上一菜单。

保存配置：

  1. 按 Shift+S 打开保存选项。 在此菜单上，可将配置保存到当前 .\aziotkit 目录中名为 skconfig 的文件中。
  2. 按 Enter 保存配置。
  3. 按 Enter 关闭确认消息。
  4. 按 Q 退出配置菜单。

生成并刷写映像

在本部分，你将使用 ESP-IDF 工具生成、刷写和监视 ESP32 DevKit，因为它连接到 Azure IoT。

注意

在本部分的以下命令中，使用靠近根目录的短生成输出路径。 在每个需要 -B 参数的命令中，指定该参数后的生成路径。 短路径有助于避免当前在 ESPRESSIF ESP-IDF 工具中存在可能导致过长生成路径名称错误的问题。 以下命令使用本地路径 C：\espbuild\ 为例。

生成映像：

  1. 在“ESP-IDF 5.0 CMD”中，从 iot-middleware-freertos-samples\demos\projects\ESPRESSIF\aziotkit 目录运行以下命令以生成映像。

    idf.py --no-ccache -B "C:\espbuild" build

  2. 生成完成后，请确认在此前指定的生成路径中已创建二进制映像文件。

    C:\espbuild\azure_iot_freertos_esp32.bin

刷写映像：

  1. 在 ESP32 DevKit 上，找到 Micro USB 端口，该端口在下图中突出显示：

    ESP32-Azure IoT 工具包板的图片。

  2. 将 Micro USB 电缆连接到 ESP32 DevKit 上的 Micro USB 端口，然后将电缆连接到计算机。

  3. 打开 Windows 设备管理器，查看“端口”以确定 ESP32 DevKit 所连接的是哪一个 COM 端口。

    Windows 设备管理器的屏幕截图，显示已连接设备的 COM 端口。

  4. 在“ESP-IDF 5.0 CMD”中运行以下命令（请将其中的 <Your-COM-port\> 占位符和括号替换为上一步骤中看到的正确 COM 端口。 例如，将占位符替换为 COM3。

    idf.py --no-ccache -B "C:\espbuild" -p <Your-COM-port> flash

  5. 确认输出完成并包含以下文本，以便成功刷写：

    Hash of data verified

Leaving...
Hard resetting via RTS pin...
Done

确认设备连接到 Azure IoT Central：

  1. 在“ESP-IDF 5.0 CMD”中，运行以下命令以启动监视工具。 与在上一命令中所做的一样，将 <Your-COM-port> 占位符和括号替换为设备连接到的 COM 端口。

    idf.py -B "C:\espbuild" -p <Your-COM-port> monitor

  2. 检查是否重复输出块，如以下示例所示。 此输出确认设备连接到 Azure IoT 并发送遥测数据。

    I (50807) AZ IOT: Successfully sent telemetry message
I (50807) AZ IOT: Attempt to receive publish message from IoT Hub.

I (51057) MQTT: Packet received. ReceivedBytes=2.
I (51057) MQTT: Ack packet deserialized with result: MQTTSuccess.
I (51057) MQTT: State record updated. New state=MQTTPublishDone.
I (51067) AZ IOT: Puback received for packet id: 0x00000008
I (53067) AZ IOT: Keeping Connection Idle...

查看设备属性

可使用 Azure IoT Explorer 查看和管理设备的属性。 在以下部分，你将使用 IoT Explorer 中显示的即插即用功能来管理 ESP32 DevKit 并与之交互。 这些功能依赖于为公共型号存储库中的 ESP32 DevKit 发布的设备型号。 在本教程的前面部分，已将 IoT Explorer 配置为在此存储库中搜索设备模型。 在很多情况下，可以通过选择 IoT Explorer 菜单选项来执行相同的操作，无需使用即插即用。 但是，使用即插即用功能通常可以提供更好的体验。 IoT Explorer 可以读取即插即用设备指定的设备型号，并显示特定于该设备的信息。

若要在 IoT Explorer 中访问设备的 IoT 即插即用组件：

  1. 从 IoT Explorer 的主页视图中，选择“IoT 中心”，然后选择“查看此中心的设备”。

  2. 选择你的设备。

  3. 选择“IoT 即插即用组件”。

  4. 选择“默认组件”。 IoT Explorer 显示设备上实施的 IoT 即插即用组件。

    屏幕截图显示 IoT Explorer 中的设备默认组件。

  5. 在“接口”选项卡上，查看设备模型“说明”中的 JSON 内容。 JSON 包含设备模型中每个 IoT 即插即用组件的配置详细信息。

    IoT Explorer 中的每个选项卡都与设备模型中的一个 IoT 即插即用组件相对应。

    Tab 类型 名称 说明
    Interface 接口 Espressif ESP32 Azure IoT Kit ESP32 DevKit 的示例设备型号
    属性（可写） 属性 telemetryFrequencySecs 设备发送遥测数据的间隔
    命令 命令 ToggleLed1 打开或关闭 LED
    命令 命令 ToggleLed2 打开或关闭 LED
    命令 命令 DisplayText 在设备屏幕上显示发送的文本

若要使用 Azure IoT 资源管理器查看和编辑设备属性，请执行以下操作：

  1. 选择“属性（可写）”选项卡。将显示发送遥测数据的间隔。

  2. 将 telemetryFrequencySecs 值更改为 5，然后选择“更新所需值”。 设备现在用此间隔发送遥测数据。

    屏幕截图显示如何在 IoT Explorer 中的设备上设置遥测间隔。

  3. IoT Explorer 使用通知进行响应。

若要使用 Azure CLI 查看设备属性：

  1. 运行 az iot hub device-twin show 命令。

    az iot hub device-twin show --device-id mydevice --hub-name {YourIoTHubName}

  2. 在控制台输出中检查设备的属性。

提示

还可以使用 Azure IoT 资源管理器查看设备属性。 在左侧导航栏中，选择“设备孪生”。

查看遥测数据

通过 Azure IoT Explorer，可以查看从设备到云的遥测数据流。 （可选）可以使用 Azure CLI 执行同一任务。

若要在 Azure IoT Explorer 中查看遥测数据：

  1. 从 IoT Explorer 中设备的“IoT 即插即用组件”（默认组件）窗格中，选择“遥测”选项卡。确认“使用内置事件中心”设置为“是”。

  2. 选择“开始”。

  3. 查看设备向云发送消息的遥测数据。

    屏幕截图显示 IoT Explorer 中的设备遥测。

  4. 选中“显示建模事件”复选框，查看设备模型指定的数据格式的事件。

    屏幕截图显示 IoT Explorer 中建模的遥测事件。

  5. 选择“停止”以结束接收事件。

若要使用 Azure CLI 查看设备遥测数据：

  1. 运行 az iot hub monitor-events 命令。 使用之前在 Azure IoT 中为设备和 IoT 中心创建的名称。

    az iot hub monitor-events --device-id mydevice --hub-name {YourIoTHubName}

  2. 在控制台中查看 JSON 输出。

    {
    "event": {
        "origin": "mydevice",
        "module": "",
        "interface": "dtmi:azureiot:devkit:freertos:Esp32AzureIotKit;1",
        "component": "",
        "payload": "{\"temperature\":28.6,\"humidity\":25.1,\"light\":116.66,\"pressure\":-33.69,\"altitude\":8764.9,\"magnetometerX\":1627,\"magnetometerY\":28373,\"magnetometerZ\":4232,\"pitch\":6,\"roll\":0,\"accelerometerX\":-1,\"accelerometerY\":0,\"accelerometerZ\":9}"
    }
}

  3. 选择 CTRL+C 结束监视。

在设备上调用直接方法

还可以使用 Azure IoT Explorer 来调用已在设备上实现的直接方法。 直接方法有一个名称，可以选择包含 JSON 有效负载、可配置的连接和方法超时。 在本部分中，将调用一个方法用于打开或关闭 LED。 （可选）可以使用 Azure CLI 执行同一任务。

若要在 Azure IoT Explorer 中调用方法：

  1. 从 IoT Explorer 中设备的“IoT 即插即用组件”（默认组件）窗格中，选择“命令”选项卡。

  2. 对于“ToggleLed1”命令，请选择“发送命令”。 ESP32 DevKit 上的 LED 会点亮或熄灭。 你还应该会在 IoT 资源管理器中看到通知。

    在 IoT 资源管理器中调用方法的屏幕截图。

  3. 对于“DisplayText”命令，请在“内容”字段中输入一些文本。

  4. 选择“发送命令”。 该文本将显示在 ESP32 DevKit 屏幕上。

若要使用 Azure CLI 调用方法：

  1. 运行 az iot hub invoke-device-method 命令，并指定方法名称和有效负载。 对于此方法，将 method-payload 设置为 true 意味着 LED 会切换为与其当前状态相反的状态。

    az iot hub invoke-device-method --device-id mydevice --method-name ToggleLed2 --method-payload true --hub-name {YourIoTHubName}

    CLI 控制台在设备上显示方法调用的状态，其中 200 指示成功。

    {
  "payload": {},
  "status": 200
}

  2. 检查设备以确认 LED 状态。

故障排除和调试

如果在生成设备代码、刷写设备或进行连接时遇到问题，请参阅故障排除。

要调试应用程序，请参阅使用 Visual Studio Code 进行调试。

清理资源

如果不再需要本快速入门中创建的 Azure 资源，可以使用 Azure CLI 删除资源组及其所有资源。

重要

删除资源组的操作不可逆。 资源组以及包含在其中的所有资源将被永久删除。 请确保不会意外删除错误的资源组或资源。

若要按名称删除资源组，请执行以下操作：

  1. 运行 az group delete 命令。 此命令将删除创建的资源组、IoT 中心和设备注册。

    az group delete --name MyResourceGroup

  2. 运行 az group list 命令，确认资源组是否已删除。

    az group list

后续步骤

在本教程中，用户将生成一个包含 FreeRTOS 示例代码的 Azure IoT 中间件的自定义映像，然后将该映像刷写到 ESP32 DevKit 设备。 你已将 ESP32 DevKit 连接到 Azure IoT 中心，并在设备上执行了查看遥测数据和调用方法等任务。

接下来，请浏览以下这些文章，以详细了解嵌入式开发选项。

详细了解如何使用 C SDK 和嵌入式 C SDK 连接嵌入式设备