将 IoT DevKit AZ3166 连接到 Azure IoT 中心

可以使用 MXChip IoT DevKit 开发物联网 (IoT) 解决方案和构建其原型,以利用 Azure 服务。 该工具包包含一个具有大量外围设备和传感器的 Arduino 兼容的板、一个开源板包和一个丰富的示例库

学习内容

  • 如何创建 IoT 中心以及注册 MXChip IoT DevKit 的设备。
  • 如何将 IoT DevKit 连接到 Wi-Fi 并配置 IoT 中心连接字符串。
  • 如何将 DevKit 传感器遥测数据发送到 IoT 中心。
  • 如何准备开发环境并为 IoT DevKit 开发应用程序。

还没有 DevKit? 请尝试 DevKit 模拟器购买 DevKit

可以在代码示例库中找到所有 DevKit 教程的源代码。

所需条件

可以使用本地 Azure CLI。

  • 如果需要,请安装 Azure CLI 来运行 CLI 参考命令。

  • 本地 Azure CLI,请了解如何安装 Azure CLI。 如果在 Windows 或 macOS 上运行,请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息,请参阅如何在 Docker 容器中运行 Azure CLI

    • 通过使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程,请遵循终端中显示的步骤。 有关其他登录选项,请参阅使用 Azure CLI 登录

    • 出现提示时,请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息,请参阅使用 Azure CLI 的扩展

    • 运行 az version 以查找安装的版本和依赖库。 若要升级到最新版本,请运行 az upgrade

准备开发环境

遵循以下步骤准备 DevKit 的开发环境:

安装包含 Azure IoT Tools 扩展包的 Visual Studio Code

  1. 安装 Arduino IDE。 此 IDE 提供必要的工具链用于编译和上传 Arduino 代码。

    • Windows:使用 Windows Installer 版本。 不要从应用商店安装。
    • macOS:将解压缩的 Arduino.app 拖放到 /Applications 文件夹中。
    • Ubuntu:解压缩到某个文件夹中,例如 $HOME/Downloads/arduino-1.8.8
  2. 安装 Visual Studio Code,这是一个跨平台的源代码编辑器,具有强大的智能、代码自动填写和调试支持,以及可从市场安装的丰富扩展。

  3. 启动 VS Code,在扩展市场中找到 Arduino 并安装它。 此扩展提供在 Arduino 平台上进行开发的增强体验。 Install Arduino

  4. 在扩展市场中找到 Azure IoT Tools 并安装它。 Install Azure IoT Tools

    或者将此 URL 复制并粘贴到浏览器窗口中:vscode:extension/vsciot-vscode.azure-iot-tools

    注意

    Azure IoT Tools 扩展包包含 Azure IoT 设备工作台,用于在各种 IoT devkit 设备上进行开发和调试。 同样随附在 Azure IoT Tools 扩展包中的 Azure IoT 中心扩展用于管理 Azure IoT 中心并与之交互。

  5. 为 VS Code 配置 Arduino 设置。

    在 Visual Studio Code 中,单击“文件”>“首选项”>“设置”(在 MacOS 上,单击“代码”>“首选项”>“设置”)。 然后单击“设置”页右上角的“打开设置(JSON)”图标。

    Install Azure IoT Tools

    必须在 VS Code 中配置正确的 Arduino 安装路径。 添加以下行,以根据平台和 Arduino IDE 的安装目录路径来配置 Arduino:

    • Windows

      "arduino.path": "C:\\Program Files (x86)\\Arduino",
      "arduino.additionalUrls": "https://raw.githubusercontent.com/VSChina/azureiotdevkit_tools/master/package_azureboard_index.json"
      
    • macOS

      "arduino.path": "/Applications",
      "arduino.additionalUrls": "https://raw.githubusercontent.com/VSChina/azureiotdevkit_tools/master/package_azureboard_index.json"
      
    • Ubuntu

      将下面的 {username} 占位符替换为你的用户名。

      "arduino.path": "/home/{username}/Downloads/arduino-1.8.13",
      "arduino.additionalUrls": "https://raw.githubusercontent.com/VSChina/azureiotdevkit_tools/master/package_azureboard_index.json"
      
  6. 单击 F1 以打开命令面板,键入并选择 Arduino:Board Manager。 搜索 AZ3166 并安装最新版本。 Install DevKit SDK

ST-Link/V2 是 IoT DevKit 用来与开发计算机通信的 USB 接口。 需要将它安装在 Windows 上才能将编译的设备代码刷写到 DevKit。 遵循 OS 特定的步骤,使计算机能够访问你的设备。

  • Windows:从 STMicroelectronics 网站下载并安装 USB 驱动程序。

  • macOS:macOS 无需驱动程序。

  • Ubuntu:在终端中运行以下命令,然后注销并登录,使组更改生效:

    # Copy the default rules. This grants permission to the group 'plugdev'
    sudo cp ~/.arduino15/packages/AZ3166/tools/openocd/0.10.0/linux/contrib/60-openocd.rules /etc/udev/rules.d/
    sudo udevadm control --reload-rules
    
    # Add yourself to the group 'plugdev'
    # Logout and log back in for the group to take effect
    sudo usermod -a -G plugdev $(whoami)
    

现已完成开发环境的准备和配置工作。

准备 Azure 资源

对于本文,需要创建一个 IoT 中心以及一个注册为使用该中心的设备。 以下子部分介绍如何使用 Azure CLI 创建资源。

也可以在 Visual Studio Code 中使用 Azure IoT Tools 扩展创建 IoT 中心并注册设备。 有关在 VS Code 中创建中心和设备的详细信息,请参阅使用适用于 VS Code 的 Azure IoT Tools

创建 IoT 中心

如果尚未创建 IoT 中心,请按照使用 Azure CLI 创建 IoT 中心中的步骤操作。

注册设备

必须先在 IoT 中心内为 IoT DevKit 注册设备,然后该设备才能进行连接。 在 Azure Cloud Shell 中使用以下步骤来注册新设备。

  1. 在 Azure Cloud Shell 中运行以下命令,以创建设备标识。

    YourIoTHubName:将下面的占位符替换为你为 IoT 中心选择的名称。

    AZ3166Device:要注册的设备的名称。 请按照本文中的示例所示使用 AZ3166Device。 如果为设备选择其他名称,则需要在本文中从头至尾使用该名称,并在运行示例应用程序之前在其中更新设备名称。

    az iot hub device-identity create --hub-name YourIoTHubName --device-id AZ3166Device
    

    注意

    如果在运行 device-identity 时遇到错误,请安装用于 Azure CLI 的 Azure IoT 扩展。 运行以下命令将用于 Azure CLI 的 Azure IoT 扩展添加到 Cloud Shell 实例。 IoT 扩展会将特定于 IoT 中心、IoT Edge 和 IoT 设备预配服务 (DPS) 的命令添加到 Azure CLI。

    az extension add --name azure-iot
    
  2. 在 Azure Cloud Shell 中运行以下命令,以获取刚注册设备的设备连接字符串

    YourIoTHubName:将下面的占位符替换为你为 IoT 中心选择的名称。

    az iot hub device-identity connection-string show --hub-name YourIoTHubName --device-id AZ3166Device --output table
    

    记下如下所示的设备连接字符串:

    HostName={YourIoTHubName}.azure-devices.net;DeviceId=AZ3166Device;SharedAccessKey={YourSharedAccessKey}

    稍后会用到此值。

准备硬件

将以下硬件挂接到计算机:

  • DevKit 板
  • Micro-USB 电缆

Required hardware

请按照以下步骤将 DevKit 连接到计算机:

  1. 将 USB 端连接到计算机。

  2. 将 Micro-USB 端连接到 DevKit。

  3. 电源的绿色 LED 灯确认连接。

    Hardware connections

更新固件

DevKit 入门固件 (devkit-getstarted-*.*.*.bin) 将连接到 IoT 中心内特定于设备的终结点,并发送温度和湿度遥测数据。

  1. 下载适用于 IoT DevKit 的最新版入门固件 (devkit-getstarted- . .*.bin)。 发布此项更新时,最新的文件名为 devkit-getstarted-2.0.0.bin。

  2. 确保 IoT DevKit 通过 USB 连接到计算机。 打开文件资源管理器,有一个称为 AZ3166 的 USB 大容量存储设备。

    Open Windows Explorer

  3. 将刚刚下载的固件拖放到大容量存储设备中,它将自动闪烁。

    Copy firmware

  4. 在 DevKit 上,按住 B 按钮不放。 按下然后松开“重置”按钮。 然后松开按钮 B。DevKit 随即进入 AP 模式。 若要进行确认,屏幕将显示 DevKit 的服务集标识符 (SSID) 和配置门户 IP 地址。

    Reset button, button B, and SSID

    Set AP Mode

  5. 在另一个启用了 Wi-Fi 的设备(计算机或手机)上使用 Web 浏览器连接到上一步骤中显示的 IoT DevKit SSID。 如果要求输入密码,则将其留空。

    Connect SSID

  6. 在浏览器中打开“192.168.0.1”。 选择 IoT DevKit 所要连接到的 Wi-Fi,键入 Wi-Fi 密码,然后粘贴前面记下的设备连接字符串。 然后单击“配置设备”。

    Configuration UI

    注意

    IoT DevKit 仅支持 2.4GHz 网络。 有关详细信息,请查阅 FAQ

  7. 在“结果”页,你会看到 WiFi 信息和设备连接字符串将存储到 IoT DevKit 中。

    Configuration result

    注意

    配置 Wi-Fi 后,即使拔下设备插头,该连接的凭据也会保留在设备上。

  8. IoT DevKit 在几秒钟后将重新启动。 在 DevKit 屏幕上,会看到 DevKit 的 IP 地址,后跟遥测数据,其中包括温度和湿度值以及发送到 Azure IoT 中心的消息计数。

    WiFi IP

    Sending data

  9. 若要验证发送到 Azure 的遥测数据,请在 Azure Cloud Shell 中运行以下命令:

    az iot hub monitor-events --hub-name YourIoTHubName --output table
    

    此命令将监视发送到 IoT 中心的设备到云 (D2C) 消息

生成第一个项目

IoT DevKit 包含丰富的示例库,可以使用这些示例来了解如何将 DevKit 连接到各种 Azure 服务。

  1. 确保 IoT DevKit 未连接到计算机。 先启动 VS Code,然后将 DevKit 连接到计算机。

  2. 单击 F1 打开命令面板,键入并选择“Azure IoT Device Workbench: 打开示例...”。然后选择“MXChip IoT DevKit”作为板 。

  3. 在 IoT Workbench 的“示例”页中,找到“入门”并单击“打开示例”。 然后,选择默认路径来下载示例代码。

    Open sample

查看代码

GetStarted.ino 是主要的 Arduino 草图文件。

D2C message

若要查看设备遥测数据如何发送到 Azure IoT 中心,请打开同一文件夹中的 utility.cpp 文件。 查看 API 参考,了解如何在 IoT DevKit 中使用传感器和外围设备。

使用的 DevKitMQTTClient适用于 C 的 Azure IoT SDK 和库中 iothub_client 的包装器,用于与 Azure IoT 中心交互。

配置并编译设备代码

  1. 在右下方的状态栏中,检查选定的开发板是否为 MXCHIP AZ3166,以及是否使用了带有 STMicroelectronics 的串行端口。

    Select board and COM

  2. 单击 F1 打开命令面板,键入并选择“Azure IoT Device Workbench: 配置设备设置...”,然后选择“配置设备连接字符串” 。 然后粘贴 IoT 设备的连接字符串。

  3. 在 DevKit 上,按住按钮 A 不放,按下再松开重置按钮,然后松开按钮 A。DevKit 将进入配置模式并保存连接字符串。

    Connection string

  4. 再次单击 F1,键入并选择“Azure IoT Device Workbench:上传设备代码”。 它启动编译,并将代码上传到 DevKit。

    Arduino upload

DevKit 将重新启动并开始运行代码。 DevKit 开始向中心发送遥测数据。

注意

如果出现了任何错误或中断,始终可以再次运行该命令予以恢复。

使用串行监视器

VS Code 中的串行监视器可用于查看从代码发送的日志记录信息。 此日志记录信息是使用 LogInfo() API 生成的。 这些信息可帮助进行调试。

  1. 单击状态栏上的电源插头图标,打开串行监视器:

    Serial monitor

  2. 当看到以下结果时,示例应用程序已成功运行:

    • 串行监视器显示发送到 IoT 中心的消息。
    • MXChip IoT DevKit 上的 LED 灯闪烁。

    Serial monitor output

    注意

    在测试期间可能会遇到错误,表现为:LED 不闪烁,Azure 门户不显示来自设备的传入数据,而设备 OLED 屏幕则显示为“正在运行...”。若要解决此问题,请在 Azure 门户中转到 IoT 中心的设备,向设备发送一条消息。 如果在 VS Code 的串行监视器中看到以下响应,则表明可能在路由器级别阻止了与设备的直接通信。 请检查为正在连接的设备配置的防火墙和路由器规则。 另请确保出站端口 1833 处于打开状态。

    错误: mqtt_client.c (第 454 行):错误: 无法打开到终结点的连接
    信息:>>>连接状态:已断开连接
    错误: tlsio_mbedtls.c (第 604 行):基础 IO 打开失败
    错误: mqtt_client.c (第 1042 行):错误: io_open 失败
    错误: iothubtransport_mqtt_common.c (第 2283 行): 无法连接到以下地址: atcsliothub.azure-devices.net。
    信息:>>>请重新连接。
    信息:IoT 中心版本:1.3.6

  3. 在 DevKit 上,按住按钮 A,按下再松开“Reset”(重置)按钮,然后松开按钮 A。DevKit 随即停止发送遥测数据并进入配置模式 。 VS Code 的串行监视器输出窗口中显示了配置模式的完整命令列表。

    ************************************************
    ** MXChip - Microsoft IoT Developer Kit **
    ************************************************
    Configuration console:
     - help: Help document.
     - version: System version.
     - exit: Exit and reboot.
     - scan: Scan Wi-Fi AP.
     - set_wifissid: Set Wi-Fi SSID.
     - set_wifipwd: Set Wi-Fi password.
     - set_az_iothub: Set IoT Hub device connection string.
     - set_dps_uds: Set DPS Unique Device Secret (UDS) for X.509 certificates..
     - set_az_iotdps: Set DPS Symmetric Key. Format: "DPSEndpoint=global.azure-devices-provisioning.net;IdScope=XXX;DeviceId=XXX;SymmetricKey=XXX".
     - enable_secure: Enable secure channel between AZ3166 and secure chip.
    

    此模式支持用于更改所要使用的 IoT 中心设备连接字符串等命令。 可以通过按下 F1 并选择“Arduino: 将文本发送到串行端口”,在串行监视器中发送文本命令。

  4. 在 DevKit 上,按下再松开“Reset”(重置)按钮。 这会重新启动设备,使它可以再次开始发送遥测数据。

使用 VS Code 查看中心遥测数据

准备硬件部分结束时,你已使用 Azure CLI 监视了 IoT 中心内的设备到云 (D2C) 消息。 你也可以在 VS Code 中使用 Azure IoT Tools 来监视设备到云 (D2C) 消息。

  1. 登录 Azure 门户,并找到创建的 IoT 中心。

    Azure portal

  2. 在“共享访问策略”窗格中单击“iothubowner”策略,并复制 IoT 中心的连接字符串 。

    Azure IoT Hub connection string

  3. 在 VS Code 中,单击 F1,键入并选择“Azure IoT 中心:设置 IoT 中心连接字符串”。 将 IoT 中心连接字符串粘贴到字段中。

    Set Azure IoT Hub connection string

  4. 展开左侧的“AZURE IOT 中心”窗格,右键单击创建的设备名称,然后选择“开始监视内置事件终结点” 。

    Monitor D2C Message

    如果系统提示你指定内置终结点,请使用在 Azure 门户中单击你的 IoT 中心对应的“内置终结点”后显示的“与事件中心兼容的终结点” 。

  5. 在“输出”窗格中,可以看到传入 IoT 中心的 D2C 消息。

    确保通过选择“Azure IoT 中心”来正确筛选输出。 可以使用此筛选操作在中心监视与串行监视器输出之间切换。

    Screenshot that shows the incoming D2C messages to the IoT Hub.

问题和反馈

如果遇到问题,可在 IoT DevKit 常见问题解答中查看解决方法,或者通过 Gitter 联系我们。 还可在此页中留言,向我们提供反馈。

后续步骤

现已成功将 MXChip IoT DevKit 连接到 IoT 中心,并将捕获的传感器数据发送到了 IoT 中心。

若要继续了解 Azure IoT 中心入门知识并使用 IoT DevKit 探索其他 IoT 方案,请参阅: