通过

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

教程：使用 Eclipse ThreadX 将 MXCHIP AZ3166 Devkit 连接到 IoT 中心

  • 项目

浏览代码

在本教程中，你使用 Eclipse ThreadX 将 MXCHIP AZ3166 IoT DevKit（后称 MXCHIP DevKit）连接到 Azure IoT。

你将完成以下任务：

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

先决条件

  • 运行 Windows 10 或 Windows 11 的电脑

  • 一个有效的 Azure 订阅。 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

  • 用于克隆存储库的 Git

  • Azure CLI。 在本教程中，有两个选项可用于运行 Azure CLI 命令：

    • 使用 Azure Cloud Shell，这是一个交互式 Shell，可在浏览器中运行 CLI 命令。 建议使用此选项，因为无需安装任何插件。 如果是首次使用 Cloud Shell，请登录到 Azure 门户。 按照 Cloud Shell 快速入门中的步骤启动 Cloud Shell 并选择 Bash 环境。
    • （可选）在本地计算机上运行 Azure CLI。 如果已安装 Azure CLI，请运行 az upgrade 以将 CLI 和扩展升级到当前版本。 要安装 Azure CLI，请参阅安装 Azure CLI。

  • 硬件

准备开发环境

要设置开发环境，首先要克隆 GitHub 存储库，其中包含本教程所需的所有资产。 然后安装一组编程工具。

克隆存储库

克隆以下存储库以下载所有示例设备代码、安装脚本和文档的脱机版本。 如果以前在另一个教程中克隆过这个存储库，则不需要再次执行此操作。

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

git clone --recursive https://github.com/eclipse-threadx/getting-started.git

安装工具

克隆的存储库包含用于安装和配置所需工具的安装脚本。 如果在另一篇嵌入式设备教程中安装了这些工具，则无需再次执行此操作。

注意

安装脚本将安装以下工具：

若要安装工具：

  1. 导航到存储库中的以下路径，并运行名为 get-toolchain.bat 的安装脚本：

    getting-started\tools\get-toolchain.bat

  2. 打开一个新的控制台窗口来识别安装脚本所做的配置更改。 使用这个控制台完成本教程中的其余编程任务。 可以使用 Windows CMD、PowerShell 或 Git Bash for Windows。

  3. 运行以下代码，确认已安装 CMake 版本3.14 或更高版本。

    cmake --version

创建云组件

创建 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

准备设备

若要将 MXCHIP DevKit 连接到 Azure，需要修改 Wi-Fi 和 Azure IoT 设置的配置文件，重新生成映像，并将映像刷写到设备。

添加配置

  1. 在文本编辑器中打开以下文件：

    getting-started\MXChip\AZ3166\app\azure_config.h

  2. 如下所示，注释掉文件顶部附近的以下行：

    // #define ENABLE_DPS

  3. 在本地环境中，将 Wi-Fi 常量设置为以下值。

    常量名称 值
    WIFI_SSID {Wi-Fi SSID}
    WIFI_PASSWORD {Wi-Fi 密码}
    WIFI_MODE {文件中枚举的 Wi-Fi 模式值之一}

  4. 将 Azure IoT 设备信息常量设置为在创建 Azure 资源后保存的值。

    常量名称 值
    IOT_HUB_HOSTNAME {你的主机名值}
    IOT_HUB_DEVICE_ID {设备 ID 值}
    IOT_DEVICE_SAS_KEY {主密钥值}

  5. 保存并关闭该文件。

生成映像

  1. 在控制台或文件资源管理器中，在以下路径中运行脚本 rebuild.bat 以生成映像：

    getting-started\MXChip\AZ3166\tools\rebuild.bat

  2. 生成完成后，请确认已在以下路径中创建了二进制文件：

    getting-started\MXChip\AZ3166\build\app\mxchip_azure_iot.bin

刷写映像

  1. 在 MXCHIP DevKit 上，找到“重置”按钮和 Micro USB 端口。 可在以下步骤中使用这两个组件。 下图突出显示了这两个组件：

    在 MXChip devkit 板上查找关键组件

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

  3. 在文件资源管理器中，找到在上一节中创建的二进制文件。

  4. 复制二进制文件 mxchip_azure_iot.bin。

  5. 在文件资源管理器中，找到连接到你的计算机的 MXCHIP DevKit 设备。 设备在系统中显示为驱动器，驱动器标签为 AZ3166。

  6. 将二进制文件粘贴到 MXCHIP Devkit 的根文件夹中。 刷写会自动启动，并在几秒钟内完成。

    注意

    在刷写过程中，MXCHIP DevKit 上的绿色 LED 闪烁。

确认设备连接详细信息

可以使用 Termite 应用来监视通信，并确认设备已正确设置。

  1. 启动 Termite。

    提示

    如果无法将 Termite 连接到 devkit，请安装 ST-LINK 驱动程序，然后重试。 有关其他步骤，请参阅故障排除。

  2. 选择“设置”。

  3. 在“串行端口设置”对话框中，检查以下设置并根据需要进行更新：

    • 波特率：115,200
    • 端口：你的 MXCHIP DevKit 连接到的端口。 如果下拉列表中有多个端口选项，则可以找到要使用的正确端口。 打开 Windows 设备管理器，查看“端口”以确定要使用的端口。

    Termite 应用中串行端口设置的屏幕截图

  4. 选择“确定”。

  5. 按设备上的“复位”按钮。 该按钮在设备上进行了标记，位于 Micro USB 连接器附近。

  6. 在 Termite 应用中，检查以下检查点值，以确认设备已初始化并连接到 Azure IoT。

     Starting Azure thread


 Initializing WiFi
     MAC address: ******************
 SUCCESS: WiFi initialized

 Connecting WiFi
     Connecting to SSID 'iot'
     Attempt 1...
 SUCCESS: WiFi connected

 Initializing DHCP
     IP address: 192.168.0.49
     Mask: 255.255.255.0
     Gateway: 192.168.0.1
 SUCCESS: DHCP initialized

 Initializing DNS client
     DNS address: 192.168.0.1
 SUCCESS: DNS client initialized

 Initializing SNTP time sync
     SNTP server 0.pool.ntp.org
     SNTP time update: Jan 4, 2023 22:57:32.658 UTC
 SUCCESS: SNTP initialized

 Initializing Azure IoT Hub client
     Hub hostname: ***.azure-devices.net
     Device id: mydevice
     Model id: dtmi:eclipsethreadx:devkit:gsgmxchip;2
 SUCCESS: Connected to IoT Hub

 Receive properties: {"desired":{"$version":1},"reported":{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128},"ledState":false,"telemetryInterval":{"ac":200,"av":1,"value":10},"$version":4}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=3{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=5{"ledState":false}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=7{"telemetryInterval":{"ac":200,"av":1,"value":10}}

 Starting Main loop
 Telemetry message sent: {"humidity":31.01,"temperature":25.62,"pressure":927.3}.
 Telemetry message sent: {"magnetometerX":177,"magnetometerY":-36,"magnetometerZ":-346.5}.
 Telemetry message sent: {"accelerometerX":-22.5,"accelerometerY":0.54,"accelerometerZ":1049.01}.
 Telemetry message sent: {"gyroscopeX":0,"gyroscopeY":0,"gyroscopeZ":0}.

在以下步骤中，保持 Termite 处于打开状态以监视设备输出。

查看设备属性

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

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

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

  2. 选择你的设备。

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

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

    IoT Explorer 中 MXCHIP DevKit 默认组件的屏幕截图

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

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

    Tab 类型 名称 说明
    Interface 接口 MXCHIP Getting Started Guide MXCHIP DevKit 的示例模型
    属性（只读） 属性 ledState LED 的当前状态
    属性（可写） 属性 telemetryInterval 设备发送遥测数据的间隔
    命令 命令 setLedState 打开或关闭 LED

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

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

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

    在 IoT Explorer 中设置 MXCHIP DevKit 上遥测间隔的屏幕截图

  3. IoT Explorer 使用通知进行响应。 还可以在 Termite 中观察更新情况。

  4. 将遥测间隔设置回 10。

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

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

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

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

查看遥测数据

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

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

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

  2. 选择“开始”。

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

    IoT Explorer 中设备遥测数据的屏幕截图

    注意

    还可以使用 Termite 应用从设备监视遥测数据。

  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:eclipsethreadx:devkit:gsgmxchip;1",
         "component": "",
         "payload": "{\"humidity\":41.21,\"temperature\":31.37,\"pressure\":1005.18}"
     }
 }

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

在设备上调用直接方法

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

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

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

  2. 对于“setLedState”命令，将“状态”设置为 “true”。

  3. 选择“发送命令”。 此时应在 IoT Explorer 中看到一条通知，设备上的黄色用户 LED 灯应打开。

    屏幕截图显示如何在 IoT Explorer 中调用 setLedState 方法

  4. 将“状态”设置为“false”，然后选择“发送命令”。 黄色用户 LED 灯应关闭。

  5. （可选）可以在 Termite 中查看输出，以监视这些方法的状态。

若要使用 Azure CLI 调用方法：

  1. 运行 az iot hub invoke-device-method 命令，并指定方法名称和有效负载。 对于此方法，将 method-payload 设置为 true 将打开 LED，设置为 false 将关闭它。

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

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

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

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

  3. 查看 Termite 终端以确认输出消息：

     Receive direct method: setLedState
     Payload: true
 LED is turned ON
 Device twin property sent: {"ledState":true}

故障排除和调试

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

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

清理资源

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

重要

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

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

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

    az group delete --name MyResourceGroup

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

    az group list

后续步骤

在本教程中，你生成了一个包含 Eclipse ThreadX 示例代码的自定义映像，并随后将该映像刷入 MXCHIP DevKit 设备。 还使用 Azure CLI 和/或 IoT Explorer 创建了 Azure 资源，将 MXCHIP DevKit 安全地连接到 Azure，查看遥测数据以及发送消息。

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

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

Eclipse ThreadX 为 OEM 提供了一些组件，通过这些组件可以保护通信以及使用底层 MCU/MPU 硬件保护机制创建代码和数据隔离。 但是，每个 OEM 最终负责确保其设备满足不断变化的安全要求。