通过

排查 Azure Sphere 问题

  • 项目

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

下面是安装和安装过程中可能出现的问题的一些故障排除步骤。

设备通信问题

由于多种原因，无法从主机连接到设备，可能会触发多个错误消息中的任何一条，具体取决于遇到哪些工具或应用程序。 以下错误消息可能表明连接失败：

  • An error occurred. Please check your device is connected and your PC has been configured correctly, then retry.
  • Could not connect to the device. Check if your device is connected to the PC. The device may be unresponsive if it is applying an Azure Sphere operating system update; wait a few minutes and then retry. If this issue persists, try uninstalling and reinstalling the Azure Sphere SDK.
  • An unexpected issue occurred. Please try again; if the issue persists, please refer to aka.ms/azurespheresupport for troubleshooting suggestions and support.
  • Failed to retrieve device ID from attached device: 'Could not connect to the device; please ensure it is attached.'
  • Failed to establish communication with device after recovery.

有三个组件可能导致设备通信问题：（1） 命令行接口本身;（2） 促进与设备的通信的设备通信服务 （DCS）：和 （3） 设备。

若要隔离原因，请执行以下步骤：

  1. 验证是否可以直接与设备通信。 在 Web 浏览器中导航到 https://192.168.35.2/status 。 忽略并消除任何显示的 SSL 警告。 应会看到类似于： {"uptime":56} 在 Web 浏览器窗口中的输出。

注意

也可以使用命令行 curl https://192.168.35.2/status --insecure执行此步骤。

注意

还可以从 PowerShell 执行此步骤（v6 或更高版本）。 Invoke-WebRequest https://192.168.35.2/status -SkipCertificateCheck

  1. 确认设备通信服务已检测到设备。 在 Web 浏览器中导航到 http://localhost:48938/api/service/devices 并确认至少一台设备显示在 JSON 输出中。

警告

Linux DCS 仅包含在 SDK 版本 23.05 及更高版本中。 按照 SDK 版本 22.11 及更早版本的旧故障排除步骤进行操作。

注意

还可以通过 Invoke-WebRequest http://localhost:48938/api/service/devicesPowerShell 执行此步骤。

无法直接与设备通信，DCS 未检测到设备

如果无法与设备建立连接（步骤 1），并且 DCS 无法检测到设备（步骤 2），则物理设备配置可能存在问题。

首先，检查设备是否已由计算机检测到。

从终端：

  1. 运行 sudo lsusb。 验证未来技术设备国际有限公司FT4232H四号 HS USB-UART/FIFO IC 是否显示在输出中。

使用 PowerShell 窗口：

  1. 运行 Get-PnpDevice -PresentOnly |Where-Object { $_.InstanceId -match '^USB' }。 验证 MSFT MT3620 Std 接口是否显示在输出中。

如果前面的命令 未 返回预期的输出，请将设备连接到其他 USB 端口。 如果此问题仍然无法解决问题，请检查设备是否已正确配置其跳线。 例如，出厂的 Seeed MT3620 开发工具包在 J3 的引脚 2 和 3 之间有一个跳线接头，可以从主电源为时钟供电。 确保该接头未移出或移除。

无法直接与设备通信，但 DCS 检测到设备

如果无法与设备建立连接（步骤 1），但 DCS 检测到设备（步骤 2），则设备或设备通信服务可能处于错误状态。

如果刚刚将设备连接到 Internet，并且设备的操作系统已过期，则设备可能正在应用 OS 更新。 如果时间恰逢发布窗口，设备也会进行 OS 更新的可能性很小。 在操作系统更新期间，将无法与设备通信。

如果怀疑设备是最新的且/或设备未连接到 Internet，则下一个最佳选项是拔出设备并将其重新连接到电脑。 这应会导致 DCS 续订其与设备的连接，并且设备重置为初始状态。

如果无法拔出并重新连接设备，则下一个最佳选项是重启 DCS。 从终端：

  1. 运行 sudo azspheredctl restart。 验证命令是否成功完成。
    1. 如果命令失败，请运行 sudo systemctl restart azsphered。

如果无法拔出并重新连接设备，则下一个最佳选项是针对 DCS 发出重新扫描命令。 收到此命令后，DCS 将循环并重置用于与 MT3620 通信的 FTDI 接口芯片。 使用 PowerShell 窗口：

  1. 运行 azsphere device rescan-attached

现在重新运行最初尝试的命令。 如果问题仍未解决，则下一个最佳选择是尝试重启 DCS。 从管理员级别 Powershell 窗口：

  1. 运行 Restart-Service -Name AzureSphereDeviceCommunicationService。 验证命令是否成功完成。

或者，使用图形用户界面重启 DCS。

  1. 按“开始”并输入“服务”。 右键单击 Azure Sphere 设备通信服务 ，然后选择“ 重启”。

现在重新运行最初尝试的命令。

如果命令继续失败，或者 azsphere device list-attached 的输出类似于：

1 device attached:
--> Device ID: Cannot get device ID
  --> Is responsive: no
  --> IP address: 192.168.35.2
  --> Connection path: 213

运行 azsphere device recover

可以直接与设备通信，DCS 检测到设备

这可能表示 CLI 出现问题。 请确保拥有最新版本的 SDK。

如果你有最新版本的 SDK，并且问题仍未解决，请将问题发布到 问答论坛。

已删除连接或缺少设备

如果计算机可以连接到 Azure Sphere 设备，但经常断开连接，则 IP 子网中可能存在冲突。

Azure Sphere 使用子网 192.168.35.*。 如果有其他软件使用同一子网，请禁用该软件，或者限制其使用的 IP 地址的范围。 目前不能更改 Azure Sphere 使用的 IP 地址的范围。

无法应用设备功能

如果在尝试将设备功能应用到 Azure Sphere 设备时收到错误，问题可能是设备上的 OS 已过期。 如果设备长时间处于脱机状态，在此期间Microsoft更新其内部密钥，则可能会出现此问题。 以下错误是此问题的症状：

azsphere device enable-development 或 azsphere device enable-cloud-test 命令返回类似于以下内容的错误：

error: The device did not accept the device capability configuration. Please check the Azure Sphere OS on your device is up-to-date using 'azsphere device show-deployment-status'.

azsphere device capability update 命令返回类似于以下内容的错误：

error: Could not apply device capability configuration to device.

这是因为设备上的受信任密钥存储已过期。 若要解决此问题，请按照 此处的说明进行操作。

未能创建四个 USB 串行转换器

设置 MT3620 开发板后，应会在设备管理器中看到四个 USB 串行转换器。 如果看到少于 4 个，则 FTDI 驱动程序可能存在问题。

注意

如果此板以前用于 RTApp 开发，你可能会看到三个转换器，而不是四个转换器。 这是正常的，并不表示错误。

如果未正确安装 FTDI 驱动程序，转换器可能会出现在错误的位置，例如其他设备，或者可能根本不显示。

若要解决此问题，请执行以下操作:

  1. 若要打开设备管理器，请单击“开始”，然后输入设备管理器。

  2. 在“通用串行总线控制器”下，选择“USB 串行转换器 A”。右键单击名称，选择“卸载设备”，并在给定选项的情况下删除驱动程序：

    卸载设备并删除驱动程序

    通过 USB 串行转换器 D 对 USB 串行转换器 B 重复此步骤。

  3. 从电脑上拔下开发板，然后重新插回。 “MSFT MT3620 标准接口”应会显示并附带一个三角形警告图标，表示没有可用的驱动程序。

  4. 右键单击其中一个 MSFT MT3620 Std 接口设备，然后选择“ 更新驱动程序”。 选择 “自动搜索更新的驱动程序软件”。 更新一个应全部修复它们。 现在，应该会在“通用串行总线控制器”部分看到四个 USB 串行转换器。 如果未显示所有四个转换器，请为每个转换器重复此步骤。

安装 FTDI 驱动程序失败

首次将 Azure Sphere 设备插入电脑时，Windows 会自动下载并安装 FTDI 驱动程序。 如果驱动程序安装正确，你将看到四个 USB 串行转换器在 设备管理器 中的通用串行总线控制器下列出，如设置开发工具包中所述。

Windows 10 版本 2004 不搜索驱动程序。 在这种情况下，驱动程序不会自动下载并安装，你将看到设备管理器中列出的以下项：

设备管理器中列出的 MT3620 项

若要安装驱动程序，请从未来技术设备国际（FTDI）手动下载驱动程序。 选择与 Windows 安装（32 位或 64 位）相匹配的驱动程序。

有关 Windows 10 版本的可用性日期和内部版本号，请参阅 Windows 10 版本信息。 此信息可以帮助你确定你的 Windows 10 版本是早于版本 2004 还是更高版本。

TAP-Windows 适配器配置导致的连接问题

Azure Sphere 工具使用经 USB 连接的 IP 网络与连接的开发板通信。 这需要 OpenVPN Technologies 提供的 TAP-Windows 适配器。 可以通过 Azure Sphere SDK 安装过程在电脑上安装此适配器（如果尚未安装）。

TAP-Windows 适配器报告了两种不同类型的问题：

  • 如果已安装其他版本的 TAP-Windows 适配器，或者 Azure Sphere 设备未连接到 TAP-Windows 适配器的第一个实例，则 Azure Sphere 工具可能无法连接到设备。

  • 如果使用 Cisco AnyConnect 虚拟专用网络（VPN），TAP-Windows 适配器可能会显示为未连接，设备通信可能无法正常工作。 这是因为 VPN 可以从 TAP 适配器的 IP 地址重定向流量。

确保 Azure Sphere 设备已连接到相应的 TAP-Windows 适配器

为了确定问题是否与 TAP 适配器相关，请先确定有多少 TAP 适配器安装在电脑上，然后根据需要修改安装。

若要确定有多少 TAP 适配器安装在电脑上，请执行以下操作：

  1. 打开 Windows 设置并选择 “网络和 Internet ”组。

  2. 在“高级网络设置”下，选择“更改适配器”选项。 应只看到一个 TAP 适配器，如以下屏幕截图所示：

    一个 TAP 适配器

    如果看到多个 TAP 适配器，或者只看到一个 TAP 适配器，但其名称不是 Azure Sphere，请按照以下步骤卸载所有 TAP 适配器并重新安装 SDK。 如果看不到 TAP 适配器，请重新安装 SDK。

若要卸载 TAP 适配器，请执行以下操作：

  1. 单击“开始”，然后输入设备管理器。

  2. 在设备管理器中，打开网络适配器并选择 TAP-Windows 适配器：

    带 TAP 适配器的设备管理器

  3. 右键单击 TAP-Windows 适配器 并选择“ 卸载设备”。 在对话框中，选择“ 删除此设备的驱动程序软件”，然后单击“ 卸载”。

  4. 以管理员身份打开命令提示符，然后运行以下 Powershell 安装程序脚本：

     powershell -ExecutionPolicy RemoteSigned -File "%ProgramData%\Microsoft\Azure Sphere\TapDriverInstaller\TapDriverInstaller.ps1" Install

  5. 如果安装成功，请重启 Azure Sphere 设备通信服务：

    net stop AzureSphereDeviceCommunicationService

    net start AzureSphereDeviceCommunicationService

  6. 重新安装 Azure Sphere SDK。

使用 Cisco AnyConnect VPN 客户端时更正未拔出的状态

使用 Cisco AnyConnect VPN 客户端时，TAP-Windows 适配器可能会显示为未连接，设备通信可能无法正常工作。 可以按如下所示更正问题：

  1. 请确保计算机上具有管理员权限。

  2. 打开 Windows 设置并选择 “网络和 Internet ”组。

  3. 在“高级网络设置”下，选择“更改适配器”选项。

  4. 右键单击 Azure Sphere TAP-Windows 适配器 V9 并选择“ 属性”。

  5. 在 “网络 ”选项卡上，找到 Cisco AnyConnect 网络访问管理器筛选器驱动程序 条目并清除该项。

    TAP-Windows 适配器属性，其中显示了未选中的 Cisco AnyConnect 项

  6. 选择“确定”保存设置并退出属性。

  7. 通过打开命令提示符并输入 azsphere device show-attached 命令，检查与 Azure Sphere 设备的通信是否正常工作。

设备未响应

Azsphere 命令中出现的以下一个或多个错误可能表示 Azure Sphere 设备通信服务无法启动：

  • warn: Device is not responding. Could not perform version check.​
  • Device is not responding. Cannot get device ID.​
  • error: Could not connect to the Azure Sphere Device Communication Service. If this issue persists, try uninstalling and reinstalling the Azure Sphere SDK.​
  • error: The device is not responding. The device may be unresponsive if it is applying an Azure Sphere operating system update; please retry in a few minutes.

确保已执行 设备通信故障排除步骤。

如果问题仍未解决，并且计算机最近进行了 Windows 更新，则设备通信服务在 Windows 更新后可能无法启动，如果其中一个内部 JSON 设置文件或配置文件已损坏。

Windows 更新后失败

在电脑上更新 Windows 后，可能会发生这些错误。 有时 Windows 更新会卸载通信服务所需的 FTDI 驱动程序。

解决此问题：

  1. 将 USB 从 Azure Sphere 设备中拔下，并再次将其插入。 重新插入设备后，应重新安装正确的驱动程序。
  2. 如果拔出并重新插入设备无法解决问题，请卸载并重新安装 Azure Sphere SDK。

JSON 文件

如果最近没有更新 Windows，则发生此问题的原因可能在于该服务使用的 restore.json 文件。

若要解决此问题，请执行以下操作:

  1. 保存以下文件的副本：

    c:\windows\serviceprofiles\localservice\appdata\local\Azure Sphere Tools\restore.json

  2. 从其原始位置删除文件。

  3. 停止，然后重启 Azure Sphere 设备通信服务：

    net stop AzureSphereDeviceCommunicationService

    net start AzureSphereDeviceCommunicationService

损坏的配置文件

如果在尝试运行命令时报告了错误，损坏的配置文件可能会阻止设备正确运行。

若要解决此问题，请删除 Windows 上的 .azsphere\config 或 Linux 上的 ~/.azsphere/config 中损坏的配置文件。

插入或拔出设备时 Windows 崩溃

MT3620 开发板拥有未来技术设备国际（FTDI）FT4232HQ芯片，有助于设备和电脑之间的通信。 正式的 FTDI 驱动程序“组合驱动程序模型”（CMD）包含两个驱动程序：一个驱动程序通过 D2XX API 提供访问权限，另一个驱动程序为同一设备提供虚拟 Com 端口（VCP）。 如果 FTDI 芯片已启用 VCP 模式，则默认安装这两个驱动程序。 这可能导致芯片在电源循环时 Windows 崩溃。

若要解决此问题，可以禁用 FTDI 芯片的 VCP 模式。 需要使用FT_PROG工具来重新编程 FTDI 芯片的 EEPROM。

  1. 请参阅 FTDI FT_PROG编程工具 ，了解如何下载和安装此工具。

  2. 运行FT_PROG并查找附加设备，如 FT_PROG GUI 应用程序中所述。

  3. 在“设备树”视图中，展开“ 硬件特定 ”部分。 应会看到四个端口。

    FTProg 硬件特定四个端口

  4. 选择 端口 A 并选择 D2XX Direct 而不是虚拟 Com 端口。

    选择端口 A 和 D2XX 直接端口

  5. 对端口 C 和端口 D 重复上一步。端口 B 应已处于 D2XX 直接模式。

  6. 选择“程序设备”图标（类似于闪电）进入编程模式。

    单击程序设备

  7. 选择 程序 以对 EEPROM 进行编程，然后等待它完成。

    程序设备

  8. 从 USB 端口拔出设备，然后将其重新连接到电源循环设备，并导致更改生效。 在 Windows 设备管理器中，“端口”（COM 和 LPT）部分现在应显示三个更少的 COM 端口。 通用串行总线设备的数量应保持不变。

启用 RTApp 调试后，与非 Azure Sphere FTDI 设备的连接丢失

某些 Azure Sphere 用户报告说，在使用 azsphere device enable-development --enable-rt-core-debug 命令从主机电脑开发和调试 RTApps 后，他们无法再与其他附加的非 Azure Sphere FTDI 设备通信。

例如，如果同时安装了 Azure Sphere 设备和连接到电脑的其他 FTDI 设备，则运行命令之前，可能会在 Windows 设备管理器中看到两个名为 USB 串行转换器 B 设备的通用串行控制器。

具有两个串行转换器 B 的设备管理器

执行此命令后，USB 串行转换器 B 设备都从通用串行总线控制器部分消失，两个新设备显示在通用串行总线设备中显示的设备管理器中。

设备管理器两个 USB 设备

原因

出现此问题的原因是 azsphere device enable-development --enable-rt-core-debugging 命令在 MT3620 上安装 FTDI 芯片的端口 B 的新驱动程序;端口随后成为 MSFT MT3620 Std 接口。 但是，此驱动程序的安装无意中更改了其他非 Azure Sphere 设备的端口 B 的驱动程序。 由于基础库中存在限制，所有具有相同 VID（0x0403）和 PID（0x6011）的 FTDI 设备都将更换其端口 B 驱动程序。

解决方案

按照以下步骤将任何非 Azure Sphere 设备的驱动程序手动还原到其以前的版本：

  1. 在设备管理器中，选择非 Azure Sphere 设备（示例中的另一个 FTDI Quad GZ），然后右键单击并选择“更新驱动程序”。

  2. 在“更新驱动程序”中，选择“ 浏览我的计算机以获取驱动程序软件”。

    浏览我的计算机以获取驱动程序

  3. 选择“ 让我从计算机上的可用驱动程序列表中选择”。

    让我选择

  4. 从列表中选择 USB 串行转换器 B 驱动程序，然后单击“下一步”。

    usb 串行转换器 b

  5. 在确认窗口中单击“ 关闭 ”。

  6. 设备管理器应将其他 FTDI 设备的端口 B 显示为 USB 串行转换器 B，指示它使用官方 FTDI 驱动程序。 MT3620 的驱动程序仍然是 MSFT MT3620 Std 接口。

    端口 B 已还原

其他信息

  • 如果在运行 azsphere device enable-development --enable-rt-core-debugging 命令后插入另一个新的非 Azure Sphere FTDI 设备，则会以相同的方式为该设备分配 Azure Sphere MT3620 的驱动程序。 重复上述步骤，将设备还原为官方 FTDI 驱动程序。

  • 如果在将设备返回到官方 FTDI 驱动程序后拔出并重新插入非 Azure Sphere FTDI 设备，该设备将保留官方 FTDI 驱动程序。

  • 如果在还原驱动程序后再次运行 azsphere device enable-development --enable-rt-core-debugging 命令，则非 Azure Sphere FTDI 设备将再次更换其驱动程序，并且需要按照解决方案中的步骤还原到官方 FTDI 驱动程序。 无论运行 azsphere device enable-development --enable-rt-core-debugging 命令时，是否将非 Azure Sphere FTDI 设备附加到电脑，都会发生这种情况。

未能识别命令

如果在输入 azsphere 命令时看到以下错误，请确保在 Windows 上使用 PowerShell 或标准命令提示符。

'azsphere' is not recognized as an internal or external command, operable program or batch file.

安装程序挂起 60%

安装程序挂起 60%，你被告知设备通信服务无法启动。 这通常发生在 TAP 驱动程序安装以奇怪的方式失败时，使系统处于不确定状态。

确认问题是否为 TAP 驱动程序

  1. 打开 Windows 事件查看器以检查日志。

  2. 查看应用程序日志和 Azure Sphere 设备通信服务日志，了解以下错误消息：

    “SerialSlipToTun.TunInterfaceSetupException：访问优化注册表设置时出错，---> System.Collections.Generic.KeyNotFoundException ---> ：不允许在 System.Security.SecurityException：不允许访问请求的注册表访问。”

    Windows 事件查看器的屏幕截图。

  3. 检查应用程序日志时，筛选日志以避免看到许多不相关的消息。 在 “操作 ”选项卡上，选择“ 筛选当前日志”。

  4. 选择 “错误”，然后选择 “AzureSphereDeviceCommunicationService ”，仅列出来自 Azure Sphere 设备通信服务的错误消息。

    “筛选当前日志”对话框的屏幕截图。

  5. 如果在应用程序日志或 Azure Sphere 设备通信服务日志中找不到错误，则可能不是 TAP 驱动程序问题。

若要解决 TAP 驱动程序问题，请执行以下步骤：

  1. 转到“网络和共享中心”，然后选择“ 更改适配器设置”。

    网络共享中心的屏幕截图。

  2. 在 Azure Sphere 下的网络连接中，选择 TAP-WIndows 适配器 V9 并打开其属性。

    网络连接的屏幕截图。

  3. 在 Azure Sphere 属性中，选择 Internet 协议版本 4（TCP/IPv4），然后选择“属性”以查看协议设置。

    Azure Sphere 属性的屏幕截图。

  4. 确保 IP 地址设置为 192.168.35.1，子网掩码设置为 255.255.255.0。

  5. 再次尝试安装程序。 如果仍然挂起，请尝试重置网络连接。 若要进行重置，请转到“设置>网络和 Internet>状态”，然后选择页面底部附近的网络重置。

    重要

    重置网络将重置所有网络设置。

停止 Azure Sphere 设备通信服务

如果安装程序挂起，可以使用 taskkill 命令停止 Azure Sphere 设备通信服务。

执行以下步骤：

  1. 复制 AzureSphereDeviceCommunicationService 的 PID。

    • 转到 “任务管理器>服务 ”选项卡，记下 AzureSphereDeviceCommunicationService 服务的 PID，或
    • 在命令行中，键入 tasklist /fi "SERVICES eq AzureSphereDeviceCommunicationService*" 并复制输出中的 PID。

  2. 在命令行中键入以下内容以结束服务。 taskkill 命令结束与进程 ID 号相对应的进程。 该 /f 选项用于强制结束该过程。

    taskkill /PID <DCS_PID> /f

  3. 再次尝试安装程序。

无法停止 Azure Sphere 设备通信服务

升级现有的 Azure Sphere SDK 时，可能会看到一条消息，指出“服务'Azure Sphere 设备通信服务'（AzureSphereDeviceCommunicationService）无法停止。 验证是否有足够的权限来停止系统服务。如果收到此消息，请重新启动并再次运行安装程序。

使用拆分隧道时设备通信中断

当开发计算机连接到公司 VPN 并且 VPN 配置禁用拆分隧道时，开发计算机可能无法与 Azure Sphere 设备通信。

若要解决此问题，请执行下列操作之一：

  • 断开与企业 VPN 的连接，然后再次尝试连接到 Azure Sphere 设备。
  • 更改 VPN 配置以允许拆分隧道。

通信问题也可能由 TAP-Windows 适配器配置引起。 请参阅 TAP-Windows 适配器配置故障排除部分导致的连接问题。

无法在 Windows 11 上安装或卸载 Azure Sphere SDK

升级到 Windows 11 后，用户无法安装或卸载 Azure Sphere SDK。 若要解决此问题，请安装最新版本的适用于 Windows 的 Azure Sphere SDK。 安装 21.07 Update 2 或更高版本后，你将能够卸载 SDK。

无法编译或调试 RTApp

如果 CMake 在尝试生成或调试 RTApp 时报告查找工具链或 openocd 时出错，请确保：

排查 23.05 之前的设备通信问题

警告

这些步骤适用于 SDK 版本 22.11 或更高版本的用户。 通过运行 azsphere show-version 验证已安装的 SDK 版本为 22.11 或更早版本。

在运行 SDK 版本 22.11 或更早版本的 Linux 系统上，每次插入设备或拔出或重新拔出脚本时， 都需要运行azsphere_connect.sh 脚本。 该脚本会刷新设备连接，并生成一个内核驱动程序，用于将网络流量映射到设备。

如果遇到通信问题，请从以下基本步骤开始：

  1. 确保已通过 USB 连接设备。

  2. 运行azsphere_connect.sh脚本（如果尚未这样做）。

  3. 验证是否可以直接与设备通信。 在 Web 浏览器中导航到 https://192.168.35.2/status 。 忽略并消除任何显示的 SSL 警告。 应会看到类似于： {"uptime":56} 在 Web 浏览器窗口中的输出。

注意

也可以使用命令行 curl https://192.168.35.2/status --insecure执行此步骤。

  1. 如果错误仍然存在，请从 USB 端口拔出设备，再次插入设备，并等待重启。 然后运行 azsphere_connect.sh 脚本。

  2. 如果错误仍然存在，请确保没有子网与其他网络工具冲突。