通过

教程：生成和调试合作伙伴应用程序

  • 项目

重要

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

本教程介绍如何生成和调试包含高级应用程序和支持实时的应用程序的示例项目，其中两个应用在高级 A7 核心和实时 M4 核心之间通信。 有关高级应用程序和支持实时的应用程序的基本信息，请参阅 Azure Sphere 应用程序的 概述。

本教程介绍如何执行下列操作：

  • 安装 GNU Arm 工具链
  • 设置硬件以显示输出
  • 启用开发和调试
  • 克隆 Azure Sphere 示例存储库
  • 启动终端模拟器以查看输出
  • 生成、运行和调试一对合作伙伴应用程序

重要

这些说明假设你使用的是遵循 MT3620 参考板设计 (RDB) 硬件的硬件，例如来自 Seeed Studios 的 MT3620 开发工具包。 如果使用的是其他 Azure Sphere 硬件，请查阅制造商的文档以了解 UART 是否公开以及如何访问它。 可能需要以不同方式设置硬件来显示输出，并更新示例代码和 app_manifest.json 文件的“Uarts”字段以使用不同的 UART。

先决条件

安装 GNU Arm 嵌入式工具链

  • Visual Studio 2022：如果使用的是 Visual Studio 2022，请从 Arm 开发人员网站安装 GNU Arm Embedded Toolchain（arm-none-eabi）。
  • Visual Studio 2019：工具链随 Visual Studio 2019 上的 Visual Studio 的 Azure Sphere 扩展一起自动安装。 如果使用 Visual Studio 2019，请继续设置 硬件以显示输出。 但是，如果手动安装了 GNU Arm Embedded 工具链，Visual Studio 将使用已安装的版本。

若要在 Arm 开发人员网站上安装工具链，请查找 GNU Arm Embedded Toolchain （arm-none-eabi），其中包括 ARM Cortex-M4 处理器的编译器。 按照此处的说明下载并安装 OS 平台的编译器。

默认情况下，Visual Studio Code 搜索工具链，应找到已安装的版本。 如果遇到与工具链相关的生成问题，请检查首选项>设置>扩展>AzureSphere 以确保“Azure Sphere： Arm Gnu Path”标识 GNU Arm Embedded Toolchain 安装目录。

设置硬件以显示输出

目前，每个实时核心都支持仅 TX 的 UART。 RTApp 可以使用此 UART 从设备发送日志输出。 在应用程序开发和调试过程中，通常需要一种方法来读取和显示输出。 HelloWorld_RTApp_MT3620_BareMetal 示例演示应用程序如何写入 UART。

使用 USB 转串行适配器（如 FTDI Friend）将实时核心上的 UART 连接到计算机上的 USB 端口。 还需要一个 终端模拟器 来建立与 115200-8-N-1 终端设置（115200 bps、8 位、无奇偶校验位、一个停止位）的串行连接以显示输出。

要将硬件设置为显示 RTApp 的输出，请执行以下步骤。 需要参考硬件制造商提供的文档来确定引脚位置。 如果你使用的硬件属于 MT3620 参考板设计 (RDB) 硬件（例如 Seeed Studios 的 MT3620 开发工具包），那么查看 RDB 接口接头可能有助于确定引脚位置。

  1. 将 USB 转串行适配器上的 GND 连接到开发工具包上的 GND。 在 MT3620 RDB 硬件上，GND 的位置为接头 3，引脚 2。

  2. 将 USB 转串行适配器上的 RX 连接到开发工具包上的 IOM4-0 TX。 在 MT3620 RDB 硬件上，IOM4-0 TX 的位置为接头 3，引脚 6。

  3. 将 USB 到串行适配器连接到开发计算机上的免费 USB 端口，并确定串行设备连接到哪个端口。

    • 在 Windows 上，开始设备管理器，按容器选择“查看>设备”，然后查找“USB UART”。 例如，FT232R USB UART 指示 FTDI 友元适配器。

    • 在 Linux 上，键入以下命令：

      dmesg | grep ttyUSB

      端口应命名为 ttyUSBn，其中 n 表示端口号。 dmesg如果命令列出了多个 USB 端口，则连接到通常报告为附加的最后一个端口。 例如，在以下示例中，将使用 ttyUSB4：

    ~$ dmesg | grep ttyUSB
[  144.564350] usb 1-1.1.2: FTDI USB Serial Device converter now attached to ttyUSB0
[  144.564768] usb 1-1.1.2: FTDI USB Serial Device converter now attached to ttyUSB1
[  144.565118] usb 1-1.1.2: FTDI USB Serial Device converter now attached to ttyUSB2
[  144.565593] usb 1-1.1.2: FTDI USB Serial Device converter now attached to ttyUSB3
[  144.570429] usb 1-1.1.3: FTDI USB Serial Device converter now attached to ttyUSB4
[  254.171871] ftdi_sio ttyUSB1: FTDI USB Serial Device converter now disconnected from ttyUSB1

  4. 启动终端模拟器程序，并将 115200-8-N-1 终端打开适配器使用的 COM 端口。 请参阅终端模拟器的文档，了解如何指定端口和速度。

启用开发和调试

在 Azure Sphere 设备上生成示例应用程序或为其开发新应用程序前，必须启用开发和调试。 默认情况下，Azure Sphere 设备处于“锁定”状态；也就是说，这些设备不允许从电脑加载开发中的应用程序，并且不允许调试应用程序。 对设备进行调试准备可消除此限制、加载调试所需的软件，以及解锁设备功能，如设备功能和通信中所述。

若要在实时核心上进行调试，请使用 azsphere device enable-development 命令。 此命令将设备配置为接受来自电脑的应用程序进行调试，并将设备分配给开发设备组，而开发设备不允许云应用程序更新。 在应用程序开发和调试期间，应将设备保留在该组中，以便云应用程序更新不会覆盖开发中的应用程序。

在 Windows 上，必须添加参数 --enable-rt-core-debugging ，该参数将调试服务器和每种核心类型所需的驱动程序加载到设备上。

  1. 如果尚未登录 Azure Sphere，请执行以下操作：

    azsphere login

  2. 使用 PowerShell 或具有管理员权限的 Windows 命令提示符打开命令行界面。 该 --enable-rt-core-debugging 参数需要管理员权限，因为它为调试器安装 USB 驱动程序。

  3. 输入以下命令：

    azsphere device enable-development --enable-rt-core-debugging

  4. 命令完成后关闭窗口，因为不再需要管理员权限。 作为最佳做法，应始终使用可以完成任务的最低权限。

如果 azsphere device enable-development 命令失败，请参阅排查 Azure Sphere 问题以获取帮助。

下载示例应用程序

可以按如下所示下载 InterCore 通信应用程序：

  1. 将浏览器指向 Microsoft示例浏览器。
  2. 在搜索框中键入“Azure Sphere”。
  3. 从搜索结果中选择 “Azure Sphere - 核心间通信 ”。
  4. 选择“ 下载 ZIP”。
  5. 打开下载的文件并解压缩到本地目录。

生成并运行合作伙伴应用程序

  1. 启动 Visual Studio。 选择“打开本地文件夹”，然后导航到提取 IntercoreComms 应用程序的文件夹。

    重要

    如果使用 Visual Studio 2022 版本 17.1 或更高版本，并且提取了 22.02 Azure Sphere 版本之前的 IntercoreComms 示例，则必须 将CMakeWorkspaceSettings.json文件添加到顶级项目文件夹中。

  2. 如果不使用 MT3620 RDB，请更新应用程序和硬件定义文件的app_manifest.json文件，并为高级应用程序CMakeLists.txt文件以匹配硬件。

  3. 如果 CMake 生成未自动启动，请选择 CMakeLists.txt 文件。

  4. 在 Visual Studio 中，查看>输出>显示输出来源：CMake 输出应显示消息CMake generation started和 。CMake generation finished

  5. 选择“全部生成>”。 如果菜单不存在，请打开解决方案资源管理器，右键单击CMakeLists.txt文件，然后选择“生成”。 IntercoreComms_HL和 IntercoreComms RT 应用程序的输出位置将显示在 “输出 ”窗口中。

  6. 选择“启动项>IntercoreComms”（所有核心）。

  7. 选择“调试>调试”或按 F5 部署和调试应用程序。

  8. 在 “输出 ”窗口中， 从菜单中选择“输出 ”，然后选择“ 设备输出”。 “ 输出 ”窗口应显示高级应用程序输出：

    Remote debugging from host 192.168.35.1, port 58817
High-level intercore comms application
Sends data to, and receives data from a real-time capable application.
Received 19 bytes: rt-app-to-hl-app-07
Sending: hl-app-to-rt-app-00
Sending: hl-app-to-rt-app-01

  9. 连接的终端模拟器应显示支持实时的程序的输出：

    Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
Message size: 19 bytes:
Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30
Text: hl-app-to-rt-app-00
Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
Message size: 19 bytes:
Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:31
Text: hl-app-to-rt-app-01

  10. 使用调试程序设置断点、检查变量并尝试其他调试任务。

  1. 在 Visual Studio Code 中，打开提取 IntercoreComms 应用程序的文件夹。 Visual Studio Code 会检测 intercore.code-workspace 文件，并询问是否要打开工作区。 选择“打开工作区”可同时打开实时应用程序和高级应用程序。

  2. 如果不使用 MT3620 RDB，请更新应用程序和硬件定义文件的app_manifest.json文件，并为高级应用程序CMakeLists.txt文件以匹配硬件。

  3. 按 F5 启动调试器。 如果以前未生成项目，或者文件已更改且需要重新生成，则 Visual Studio Code 会在调试开始之前生成项目。

  4. Azure Sphere 输出窗口应显示“正在部署图像…”，后跟 SDK 和编译器的路径。

  5. 输出窗口应显示高级应用程序输出：

    Remote debugging from host 192.168.35.1, port 58817
High-level intercore comms application
Sends data to, and receives data from a real-time capable application.
Received 19 bytes: rt-app-to-hl-app-07
Sending: hl-app-to-rt-app-00
Sending: hl-app-to-rt-app-01

  6. 连接的终端模拟器应显示支持实时的程序的输出：

    Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
Message size: 19 bytes:
Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30
Text: hl-app-to-rt-app-00
Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
Message size: 19 bytes:
Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:31
Text: hl-app-to-rt-app-01

  7. 使用 Visual Studio Code 调试功能来设置断点、检查变量并尝试其他调试任务。

故障排除

应用程序可能在 OpenOCD 建立连接之前就已开始执行。 因此，在代码早期设置的断点可能会丢失。 此问题的一个简单的解决方法是在 OpenOCD 连接之前延迟应用程序的启动。

  1. 在应用程序入口点 RTCoreMain 的开头插入以下代码。 此操作将导致应用程序进入并保持在 while 循环中，直到变量 f 设置为 true。

    static _Noreturn void RTCoreMain(void)
{
  .
  .
  .
 volatile bool f = false;
 while (!f) {
    // empty.
 }
  .
  .
  .
}

  2. 按 F5 通过调试启动应用，然后中断执行。

  3. 在“ 局部变量 调试”窗格中，将值 f 从零更改为 1。

  4. 像往常一样单步执行代码。

使用 CLI 生成时，首先生成并部署支持实时的应用程序，然后生成和部署高级应用程序。

生成和部署支持实时的应用程序

  1. 导航到提取 IntercoreComms 应用程序的文件夹，然后选择 IntercoreComms/IntercoreComms_RTApp_MT3620_BareMetal 文件夹。

  2. 打开app_manifest.json文件，并验证高级应用的组件 ID 是否显示在 AllowedApplicationConnections 功能中。

  3. 使用 PowerShell、Windows 命令提示符或 Linux 命令行界面打开命令行界面。 导航到项目生成目录。

  4. 在命令提示符下，从项目生成目录中，使用以下参数运行 CMake：

    cmake --preset <preset-name> <source-path>

    • --preset <preset-name>

      CMakePresets.json中定义的生成配置预设名称。

    • --build <cmake-path>

      包含 CMake 缓存的二进制目录。 例如，如果在 Azure Sphere 示例中运行 CMake，则生成命令将是 cmake --build out/ARM-Debug。

    • <source-path>

      包含示例应用程序的源文件的目录的路径。 在此示例中，Azure Sphere 示例存储库已下载到名为 AzSphere 的目录。

      这些 CMake 参数以空格分隔。 行延续字符（^ for Windows 命令行、\for Linux 命令行或“for PowerShell”）可用于可读性，但不是必需的。

    以下示例显示了 IntercoreComms RTApp 的 CMake 命令：

    Windows 命令提示符

     cmake ^
--preset "ARM-Debug" ^
 "C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_RTApp_MT3620_BareMetal"

    Windows PowerShell

     cmake `
--preset "ARM-Debug" `
 "C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_RTApp_MT3620_BareMetal"

  5. 在项目生成目录中，在命令提示符处，运行 Ninja 以生成应用程序并创建映像包文件。

    ninja -C out/ARM-Debug

    Ninja 将生成的应用程序和 .imagepackage 文件放置在指定的目录中。

    还可以使用以下命令通过 CMake 调用 Ninja：

    cmake --build out/<binary-dir>

    设置为 <binary-dir> 包含 CMake 缓存的二进制目录。 例如，如果在 Azure Sphere 示例中运行 CMake，则生成命令将是 cmake --build out/ARM-Debug。

    排除故障时，尤其是在对 CMake 命令进行任何更改后，请删除整个生成并重试。

  6. 删除已部署到设备的所有应用程序：

    azsphere device sideload delete

  7. 在命令提示符下，从项目生成目录中加载 ninja 创建的映像包：

    azsphere device sideload deploy --image-package <path-to-imagepackage>

    加载应用程序后不久将开始运行。

  8. 获取映像的组件 ID：

    azsphere image-package show --image-package <path-to-imagepackage>

    该命令返回映像包的所有元数据。 应用程序的组件 ID 显示在应用程序映像类型的“标识”部分中。 例如：

    Image package metadata:
Section: Identity
Image Type:           Application
Component ID:         <component id>
Image ID:             <image id>

生成和部署高级应用程序

  1. 导航到提取 IntercoreComms 应用程序的文件夹，然后选择 IntercoreComms/IntercoreComms_HighLevelApp 文件夹。

  2. 打开app_manifest.json文件，并验证 RTApp 的组件 ID 是否显示在 AllowedApplicationConnections 功能中。

  3. 使用 PowerShell、Windows 命令提示符或 Linux 命令行界面打开命令行界面。 导航到项目生成目录。

  4. 在命令提示符下，从项目生成目录中，使用以下参数运行 CMake：

    cmake --preset <preset-name> <source-path>

    • --preset <preset-name>

      CMakePresets.json中定义的生成配置预设名称。

    • --build <cmake-path>

      包含 CMake 缓存的二进制目录。 例如，如果在 Azure Sphere 示例中运行 CMake，则生成命令将是 cmake --build out/ARM-Debug。

    • <source-path>

      包含示例应用程序的源文件的目录的路径。 在此示例中，Azure Sphere 示例存储库已下载到名为 AzSphere 的目录。

      这些 CMake 参数以空格分隔。 行延续字符（^ for Windows 命令行、\for Linux 命令行或“for PowerShell”）可用于可读性，但不是必需的。

    以下示例显示了 IntercoreComms 高级应用程序的 CMake 命令。

    Windows 命令提示符

     cmake ^
 --preset "ARM-Debug" ^
 "C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_HighLevelApp"

    Windows PowerShell

     cmake `
 --preset "ARM-Debug" `
 "C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_HighLevelApp"

  5. 在项目生成目录中，在命令提示符处，运行 Ninja 以生成应用程序并创建映像包文件。

    ninja -C out/ARM-Debug

    Ninja 将生成的应用程序和 .imagepackage 文件放置在指定的目录中。

    还可以使用以下命令通过 CMake 调用 Ninja：

    cmake --build out/<binary-dir>

    设置为 <binary-dir> 包含 CMake 缓存的二进制目录。 例如，如果在 Azure Sphere 示例中运行 CMake，则生成命令将是 cmake --build out/ARM-Debug。

    排除故障时，尤其是在对 CMake 命令进行任何更改后，请删除整个生成并重试。

  6. 在命令提示符下，从项目生成目录中加载 ninja 创建的映像包：

    azsphere device sideload deploy --image-package <package-name>

    加载应用程序后不久将开始运行。

  7. 获取映像的组件 ID：

    azsphere image-package show --image-package <path-to-imagepackage>

    该命令返回映像包的所有元数据。 应用程序的组件 ID 显示在应用程序映像类型的“标识”部分中。 例如：

    Image package metadata:
  Section: Identity
    Image Type:           Application
    Component ID:         <component id>
    Image ID:             <image id>

运行启用了调试的合作伙伴应用程序

  1. 如果正在运行，请停止实时应用程序。

    azsphere device app stop --component-id <component id>

  2. 重新启动应用程序进行调试。

    azsphere device app start --component-id <component id>

    此命令返回应用程序正在其上运行的内核。

      <component id>
  App state: running
  Core        : Real-time 0

  3. 导航到生成应用程序所用的 sysroot 的 Openocd 文件夹。 sysroot 安装在 Azure Sphere SDK 安装文件夹中。 例如，在 Windows 上，该文件夹默认安装在 C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\openocd，而在 Linux 上安装在 /opt/azurespheresdk/Sysroots/*sysroot*/tools/sysroots/x86_64-pokysdk-linux。

  4. 如下面的示例所示，运行 openocd。 该示例假定应用在内核 0 上运行。 如果应用在内核 1 上运行，请将“目标 io0”替换为“目标 io1”。

       openocd -f mt3620-rdb-ftdi.cfg -f mt3620-io0.cfg -c "gdb_memory_map disable" -c "gdb_breakpoint_override hard" -c init -c "targets io0" -c halt -c "targets"

  5. 打开新的 Azure Sphere 命令提示符（Windows Azure Sphere 经典 CLI）、标准命令提示符或 PowerShell（Windows Azure Sphere CLI）或终端窗口（Linux）。

  6. 导航到包含支持实时的应用程序 .out 文件的文件夹并启动 arm-none-eabi-gdb，这是 GNU Arm Embedded 工具链的一部分：

    Windows 命令提示符

    "C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update\bin\arm-none-eabi-gdb" IntercoreComms_RTApp_MT3620_BareMetal.out

    Windows PowerShell

     & "C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update\bin\arm-none-eabi-gdb" IntercoreComms_RTApp_MT3620_BareMetal.out

  7. OpenOCD 服务器在 :4444 上提供 GDB 服务器接口。 设置目标进行调试。

    target remote :4444

  8. 现在可以将 gdb 命令运行到支持实时的应用程序。 在函数 HandleSendTimerDeferred 中添加断点：

    break HandleSendTimerDeferred

  9. 连接的终端模拟器应显示支持实时的应用程序的输出。

  10. 打开新的 Azure Sphere 命令提示符（Windows Azure Sphere 经典 CLI）、标准命令提示符或 PowerShell（Windows Azure Sphere CLI）或终端窗口（Linux）。

  11. 导航到包含高级应用程序 .imagepackage 文件的文件夹。

  12. 如果应用程序正在运行，请停止高级应用程序。

    azsphere device app stop --component-id <component id>

  13. 使用调试重新启动高级应用程序。

    azsphere device app start --component-id <component id> --debug-mode

  14. 打开终端模拟器，并在端口 2342 上建立到 192.168.35.2 的 Telnet 或 TCP 连接，以查看高级应用的输出。

  15. 使用以下命令启动 gdb：

    Windows 命令提示符

    "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb.exe" IntercoreComms_HighLevelApp.out

    Windows PowerShell

    & "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb.exe" IntercoreComms_HighLevelApp.out

    注意

    Azure Sphere SDK 附带了多个 sysroot，以便应用程序可以面向不同的 API 集，如应用程序运行时版本、sysroot 和 Beta API 中所述。 sysroot 安装在 Sysroots 下的 Azure Sphere SDK 安装文件夹中。

  16. 将远程调试目标设置为端口 2345 上的 IP 地址 192.168.35.2：

    target remote 192.168.35.2:2345

  17. 在函数 SendMessageToRTApp 中添加断点：

    break SendMessageToRTApp

  18. 键入 c 继续，观察 Telnet/TCP 终端中的输出，然后切换到包含实时应用程序调试会话的命令提示符或终端窗口。

  19. 键入 c 以继续并观察连接的串行会话中的输出。

可以在调试会话之间来回工作，在支持实时的应用程序与高级应用程序之间进行切换。 应在两个输出窗口中看到类似于以下内容的输出：

Starting debugger....
                     Process /mnt/apps/25025d2c-66da-4448-bae1-ac26fcdd3627/bin/app created; pid = 40
                     Listening on port 2345
                                           Remote debugging from host 192.168.35.1, port 56522
              High-level intercore comms application
                                                    Sends data to, and receives data from a real-time capable application.
                                          Sending: hl-app-to-rt-app-00
                                                                      Sending: hl-app-to-rt-app-01

IntercoreComms_RTApp_MT3620_BareMetal
App built on: Nov 17 2020, 09:25:19
Sender: 25025d2c-66da-4448-bae1-ac26fcdd3627
Message size: 19 bytes:
Hex: 68:6c:2d:61:70:70:2d:74:6f:2d:72:74:2d:61:70:70:2d:30:30
Text: hl-app-to-rt-app-00

若要结束每个调试会话，请在 gdb 提示符处键入 q 。

后续步骤