通过

排查 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 警告。 应在 Web 浏览器窗口中看到类似于 的 {"uptime":56} 输出。

注意

还可以使用 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/devices从 PowerShell 执行此步骤。

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

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

首先，检查计算机检测到设备。

从终端：

  1. 运行 sudo lsusb。 验证 Future Technology Devices International， Ltd FT4232H Quad HS USB-UART/FIFO IC 是否出现在输出中。

使用 PowerShell 窗口：

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

如果前面的命令 未 返回预期的输出，则将设备连接到其他 USB 端口。 如果这仍然无法解决问题，检查设备已正确配置其跳线。 例如，Seeed MT3620 开发工具包在 J3 的引脚 2 和引脚 3 上带有一个跳线接头，用于从main电源为时钟供电。 检查标头是否未被移除或移除。

无法直接与设备通信，但 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. 运行命令 az sphere device rescan-attached

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

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

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

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

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

如果命令继续失败，或 az sphere device list-attached 具有类似于以下内容的输出：

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

运行 az sphere device recover

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

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

如果你有最新版本的 SDK，但问题仍未解决，请将问题发布到 Q&A 论坛。

连接断开或设备缺失

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

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

无法应用设备功能

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

az sphere device enable-development 或 az sphere 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 'az sphere device show-deployment-status'.

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

error: Could not apply device capability configuration to device.

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

无法创建四个 USB 串行转换器

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

注意

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

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

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

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

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

    卸载设备和删除驱动程序

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

  3. 从电脑中拔下开发板，然后重新插入。 “MSFT MT3620 Std 接口”应显示三角形警告图标，指示没有可用的驱动程序。

  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 网络访问管理器筛选器驱动程序 ”条目并清除该项。

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

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

  7. 通过打开命令提示符并输入 az sphere 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 (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 用户报告说，在使用 az sphere device enable-development --enable-rt-core-debugging 命令从主机电脑开发和调试 RTApps 后，他们无法再与其他附加的非 Azure Sphere FTDI 设备通信。

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

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

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

设备管理器两个 USB 设备

原因

出现此问题的原因是 az sphere 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 驱动程序。

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

  • 如果在还原驱动程序后再次运行 az sphere device enable-development --enable-rt-core-debugging 命令，则非 Azure Sphere FTDI 设备将再次更换其驱动程序，并且需要按照解决方案中的步骤还原官方 FTDI 驱动程序。 无论运行 az sphere 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 ---> 找不到 Tun tap 设备：不允许请求的注册表访问。”

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

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

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

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

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

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

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

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

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

    网络Connections的屏幕截图。

  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。

无法编译或调试 RTApps

如果 CMake 报告了查找工具链的错误，或者 openocd 当你尝试生成或调试 RTApp 时，请确保：

排查 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 警告。 应在 Web 浏览器窗口中看到类似于 的 {"uptime":56} 输出。

注意

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

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

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