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

项目
08/09/2023

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

本教程介绍如何：

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

重要

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

先决条件

安装适用于 Windows 或 Linux 的 CMake 和 Ninja。

安装适用于 Windows 或 Linux 的 Visual Studio Code。
安装适用于 Windows 或 Linux 的 CMake 和 Ninja。

安装 Visual Studio 和 Azure Sphere 扩展。

安装适用于 Windows 或 Linux 的 Azure Sphere SDK。
选择目录并声明设备。
配置网络并更新设备 OS。

安装 GNU Arm 嵌入式工具链

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

若要在 Arm 开发人员网站上安装工具链，请找到包含 ARM Cortex-M4 处理器编译器的 gnu Arm Embedded Toolchain (arm-none-eabi) 。按照此处的说明下载并安装适用于 OS 平台的编译器。

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

设置硬件以显示输出

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

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

若要设置硬件以显示来自 RTApp 的输出，请执行以下步骤。你需要参考硬件制造商的文档来确定引脚位置。如果你使用遵循 MT3620 参考板设计 (RDB) 硬件的硬件（如 Seeed Studio 中的 MT3620 开发工具包），则查看 RDB 接口标头可以帮助你确定引脚位置。

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

将 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

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

启用开发和调试

在 Azure Sphere 设备上生成示例应用程序或为其开发新应用程序之前，必须启用开发和调试。默认情况下，Azure Sphere 设备处于“锁定”状态;也就是说，它们不允许从电脑加载正在开发的应用程序，并且不允许调试应用程序。准备设备进行调试会消除此限制，并加载调试和解锁设备功能所需的软件。

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

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

窗户
Linux

登录到 Azure Sphere（如果尚未登录）：
```
az login
```
使用 PowerShell 或 Windows 命令提示符打开具有管理员权限的命令行界面。参数 --enable-rt-core-debugging 需要管理员权限，因为它为调试器安装 USB 驱动程序。

输入以下命令：

az sphere device enable-development --enable-rt-core-debugging  --catalog <CatalogName>  --resource-group <ResourceGroupName>

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

登录到 Azure Sphere（如果尚未登录）：
```
az login
```

输入以下命令：

az sphere device enable-development --enable-rt-core-debugging  --catalog <CatalogName> --resource-group <ResourceGroupName>

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

下载示例应用程序

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

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

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

启动 Visual Studio。选择“打开本地文件夹”，并导航到在其中提取 IntercoreComms 应用程序的文件夹。

重要

如果使用 Visual Studio 2022 版本 17.1 或更高版本，并在 22.02 Azure Sphere 版本之前提取了 IntercoreComms 示例，则必须将 CMakeWorkspaceSettings.json 文件添加到顶级项目文件夹。
如果不使用 MT3620 RDB，请更新应用程序的app_manifest.json文件和硬件定义文件，并为高级应用程序更新CMakeLists.txt 文件，以匹配硬件。
如果 CMake 生成未自动启动，请选择 CMakeLists.txt 文件。
在 Visual Studio 中，查看>输出>显示来自的输出： CMake 输出应显示消息 CMake generation started 和 CMake generation finished。
选择“全部生成>”。如果该菜单不存在，请打开解决方案资源管理器，右键单击 CMakeLists.txt 文件，然后选择“生成”。 IntercoreComms_HL & IntercoreComms RT 应用程序的输出位置将显示在 “输出 ”窗口中。
选择 “选择启动项>IntercoreComms” () 的所有核心 。
选择“ 调试>调试” 或按 F5 部署和调试应用程序。

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

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

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

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

使用调试器可以设置断点、检查变量，并尝试执行其他调试任务。

在 Visual Studio Code中，打开在其中提取 IntercoreComms 应用程序的文件夹。 Visual Studio Code检测 intercore.code-workspace 文件，并询问是否要打开工作区。选择“打开工作区”可同时打开实时应用程序和高级应用程序。
如果不使用 MT3620 RDB，请更新应用程序的app_manifest.json文件和硬件定义文件，并为高级应用程序更新CMakeLists.txt 文件，以匹配硬件。
按 F5 启动调试器。如果之前尚未生成项目，或者文件已更改并需要重新生成，Visual Studio Code将在调试开始之前生成项目。
Azure Sphere 输出窗口应显示“正在部署映像...”后跟 SDK 和编译器的路径。

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

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

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

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

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

故障排除

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

在应用程序入口点 RTCoreMain 的开头插入以下代码。这将导致应用程序进入并保留在循环中， while 直到变量 f 设置为 true。
```
static _Noreturn void RTCoreMain(void)
{
  .
  .
  .
 volatile bool f = false;
 while (!f) {
    // empty.
 }
  .
  .
  .
}
```
按 F5 启动调试应用，然后中断执行。
在 “局部变量 调试”窗格中，将的值 f 从零更改为 1。
像往常一样单步执行代码。

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

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

导航到提取 IntercoreComms 应用程序的文件夹，然后选择 IntercoreComms/IntercoreComms_RTApp_MT3620_BareMetal 文件夹。
打开 app_manifest.json 文件并验证高级应用的组件 ID 是否显示在 AllowedApplicationConnections 功能中。
使用 PowerShell、Windows 命令提示符或 Linux 命令行界面打开命令行界面。导航到项目生成目录。
在命令提示符下，在项目生成目录中，使用以下参数运行 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 命令：
- 窗户
- Linux
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"
```
```
 cmake \
--preset "ARM-Debug" \
 ./AzSphere/azure-sphere-samples/Samples/IntercoreComms/IntercoreComms_RTApp_MT3620_BareMetal
```
在命令提示符下，从项目生成目录运行 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 命令进行任何更改后，请删除整个生成，然后重试。
删除已部署到设备的任何应用程序：
```
az sphere device sideload delete
```
在命令提示符下，从项目生成目录加载 ninja 创建的映像包：
```
az sphere device sideload deploy --image-package <path-to-imagepackage>
```
应用程序将在加载后不久开始运行。

获取映像的组件 ID：

az sphere image-package show --image-package <path-to-imagepackage>

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

...
  "Identity": {
    "ComponentId": "<component-id>",
    "ImageId": "<image-id>",
    "ImageType": "Application"
  },
...

生成和部署高级应用程序

导航到提取 IntercoreComms 应用程序的文件夹，然后选择 IntercoreComms/IntercoreComms_HighLevelApp 文件夹。
打开 app_manifest.json 文件，并验证 RTApp 的组件 ID 是否显示在 AllowedApplicationConnections 功能中。
使用 PowerShell、Windows 命令提示符或 Linux 命令行界面打开命令行界面。导航到项目生成目录。
在命令提示符下，在项目生成目录中，使用以下参数运行 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 命令。
- 窗户
- Linux
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"
```
```
 cmake \
 --preset "ARM-Debug" \
 ./AzSphere/azure-sphere-samples/Samples/IntercoreComms/IntercoreComms_HighLevelApp
```
在命令提示符下，从项目生成目录运行 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 命令进行任何更改后，请删除整个生成，然后重试。
在命令提示符下，从项目生成目录加载 ninja 创建的映像包：
```
az sphere device sideload deploy --image-package <package-name>
```
应用程序将在加载后不久开始运行。

获取映像的组件 ID：

az sphere image-package show --image-package <path-to-imagepackage>

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

...
  "Identity": {
    "ComponentId": "<component-id>",
    "ImageId": "<image-id>",
    "ImageType": "Application"
  },
...

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

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

az sphere device app stop --component-id <component id>

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

az sphere device app start -- --debug-mode true --component-id <component id>

此命令返回运行应用程序的核心。

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

导航到生成应用程序的 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。

如以下示例所示运行 openocd 。该示例假定应用在核心 0 上运行。如果应用在核心 1 上运行，请将“targets io0”替换为“targets io1”。

窗户
Linux

   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"

   ./usr/bin/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"

(Windows Azure Sphere 经典 CLI) 、标准命令提示符或 PowerShell (Windows Azure CLI) 打开新的 Azure Sphere 命令提示符，或者 (Linux) 终端窗口。
导航到包含支持实时的应用程序 .out 文件的文件夹，然后启动 arm-none-eabi-gdb，它是 GNU Arm 嵌入式工具链的一部分：
- 窗户
- Linux
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
```
/opt/gnu-arm-toolchain/arm-none-eabi-gdb IntercoreComms_RTApp_MT3620_BareMetal.out
OpenOCD 服务器在：4444 上提供 GDB 服务器接口。设置调试目标。

target remote :4444
现在可以对支持实时的应用程序运行 gdb 命令。在函数 HandleSendTimerDeferred 中添加断点：
```
break HandleSendTimerDeferred
```
连接的终端模拟器应显示支持实时的应用程序的输出。
(Windows Azure Sphere 经典 CLI) 、标准命令提示符或 PowerShell (Windows Azure CLI) 打开新的 Azure Sphere 命令提示符，或者 (Linux) 终端窗口。
导航到包含高级应用程序 .imagepackage 文件的文件夹。
如果高级应用程序正在运行，请停止该应用程序。
```
az sphere device app stop --component-id <component id>
```

通过调试重新启动高级应用程序。

az sphere device app start --debug-mode true --component-id <component id> --debug-mode

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

使用以下命令启动 gdb：

窗户
Linux

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

/opt/azurespheresdk/Sysroots/*sysroot*/tools/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-musleabi/arm-poky-linux-musleabi-gdb IntercoreComms_HighLevelApp.out

注意

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

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

target remote 192.168.35.2:2345
在函数 SendMessageToRTApp 中添加断点：

break SendMessageToRTApp
键入 c 以继续，观察 Telnet/TCP 终端中的输出，然后切换到包含实时应用程序调试会话的命令提示符或终端窗口。
键入 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 。

后续步骤

浏览高级和实时支持应用程序的其他示例
详细了解 Azure Sphere 应用程序
详细了解 Azure Sphere 开发环境