教程：生成支持实时的应用程序

项目
08/09/2023

本教程介绍如何在 Azure Sphere 设备上为实时核心生成示例应用程序。有关支持实时的应用程序的基本信息，请参阅 Azure Sphere 应用程序概述。

本教程介绍如何：

下载示例应用程序
安装 GNU Arm 工具链
设置硬件以显示输出
启用开发和调试
启动终端模拟器以查看输出
生成、运行和调试支持实时的应用程序

重要

这些说明假设你使用的是遵循 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。

下载示例应用程序

可按如下所示下载 HelloWorld 应用程序：

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

安装 GNU Arm 嵌入式工具链

可以从 Arm 开发人员网站下载并安装 GNU Arm 嵌入式工具链。或者，可以使用 vcpkg 项目自动安装和配置开发环境。

手动下载 GNU Arm Embedded 工具链
使用 vcpkg 进行安装

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搜索工具链，并应找到已安装的版本。如果遇到与工具链相关的生成问题，请输入路径，如下所示：

选择“文件>首选项>设置扩展>>Azure Sphere”。
在 Azure Sphere： Arm Gnu Path 设置中输入 GNU Arm Embedded Toolchain 安装路径。

Visual Studio 2019 和 2022

确保 Visual Studio 是最新的。选择“帮助>检查汇报...”。
打开开发人员命令提示符。
导航到示例项目文件夹：

> cd <path to local directory>\HelloWorld_RTApp_MT3620_BareMetal
验证项目文件夹是否包含名为 vcpkg-configuration.json 的文件。
如果打开了 Windows 命令提示符，请切换到 Powershell 命令提示符。

> Powershell
下载 vcpkg。

> iex (iwr -useb https://aka.ms/vcpkg-init.ps1)
激活 vcpkg。

> vcpkg activate

注意

从 Visual Studio 2022 版本 17.4 预览版 2 开始，支持 vcpkg 的自动激活。确保已安装 vcpkg，并且使用的是版本 17.4 预览版 2 或更高版本。在 Visual Studio 中打开项目或从模板创建新项目时，将自动激活 vcpkg。

窗户
Linux

打开命令提示符
导航到示例项目文件夹。

> cd <path to local directory>\HelloWorld_RTApp_MT3620_BareMetal
验证项目文件夹是否包含名为 vcpkg-configuration.json 的文件。
如果打开了 Windows 命令行界面，请切换到 Powershell 命令提示符。

> Powershell
下载 vcpkg。

> iex (iwr -useb https://aka.ms/vcpkg-init.ps1)
激活 vcpkg。

> vcpkg activate

设置硬件以显示输出

目前，每个实时核心都支持仅限 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 友元适配器。
启动终端模拟器程序，并打开适配器使用的 COM 端口的 115200-8-N-1 终端。请参阅终端模拟器的文档，了解如何指定端口和速度。

设置硬件以显示输出

将 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 问题以获取帮助。

使用 Visual Studio 生成并运行 HelloWorld RTApp 应用程序

启动 Visual Studio。选择“ 打开本地文件夹”，导航到提取下载 Azure_Sphere___Hello_World.zip 文件的文件夹，然后选择HelloWorld_RTApp_MT3620_Baremetal文件夹。
如果不使用 MT3620 RDB，请更新 app_manifest.json 文件和示例代码以指定正确的 UART，例如 ISU1。
如果 CMake 生成未自动启动，请选择 CMakeLists.txt 文件。
在 Visual Studio 输出 窗口中，CMake 输出应显示消息 CMake generation started. 和 CMake generation finished.。
选择“全部生成>”。如果该菜单不存在，请打开解决方案资源管理器，右键单击 CMakeLists.txt 文件，然后选择“生成”。 HelloWorld_RTApp_MT3620_Baremetal应用程序的输出位置将显示在 “输出 ”窗口中。
在 “选择启动项 ”菜单上，选择 HelloWorld_RTApp_MT3620_Baremetal (RTCore) 。
按 F5 部署应用程序。
连接的终端模拟器应显示来自HelloWorld_RTApp_MT3620_Baremetal程序的输出。程序每隔一秒发送以下单词：

Tick

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

使用 Visual Studio Code 生成并运行 HelloWorld RTApp 应用程序

在 Visual Studio Code中，打开解压缩下载的 Azure_Sphere___Hello_World.zip 文件的文件夹中的 HelloWorld_RTApp_MT3620_BareMetal 文件夹。如果系统提示你选择工具包，请选择“ 不使用工具包”。
如果不使用 MT3620 RDB 硬件，请更新 app_manifest.json 文件和示例代码以指定正确的 UART，例如 ISU1。
按 F5 启动调试器。如果之前尚未生成项目，或者文件已更改并需要重新生成，Visual Studio Code将在调试开始之前生成项目。
Azure Sphere 输出窗口应显示“正在部署映像...”后跟 SDK 和编译器的路径。
连接的终端模拟器应显示来自HelloWorld_RTApp_MT3620_Baremetal程序的输出。程序每隔一秒发送以下单词：

Tick

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

故障排除

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

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

生成示例

使用 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) 可用于提高可读性，但不是必需的。
以下示例显示了 RTApp 的 CMake 命令。如果指示，请将文件路径>替换为<系统上 GNU Arm Embedded Toolchain 的安装路径。
- 窗户
- Linux
Windows 命令提示符
```
cmake ^
--preset "ARM-Debug" ^
"C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_RTApp_MT3620_BareMetal"
```
Windows PowerShell
```
cmake `
--preset "ARM-Debug" `
"C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_RTApp_MT3620_BareMetal"
```
```
cmake \
--preset "ARM-Debug" \
./AzSphere/azure-sphere-samples/Samples/HelloWorld/HelloWorld_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>
```
应用程序将在加载后不久开始运行。连接的终端仿真器上将显示以下内容：
```
Tick

Tock

Tick
.
.
.
```

获取映像的组件 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 --component-id <component id>

az sphere device app show-status --component-id <component id>

调试示例

如果应用程序正在运行，请停止该应用程序。
```
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"

导航到包含应用程序 .out 文件的文件夹，并启动 arm-none-eabi-gdb，这是 GNU Arm Embedded Toolchain 的一部分：

窗户
Linux

Windows 命令提示符

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

Windows PowerShell

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

  /opt/gcc-arm-none-eabi-9-2020-q2-update/bin/arm-none-eabi-gdb HelloWorld_RTApp_MT3620_BareMetal.out

OpenOCD 服务器在：4444 上提供 GDB 服务器接口。设置调试目标。

target remote :4444
现在可以运行 gdb 命令。
连接的终端模拟器应显示来自应用程序的输出。

使用合作伙伴应用

将应用程序加载到 Azure Sphere 设备时，Azure Sphere 部署工具默认会删除所有现有应用程序。若要防止在开发相互通信的应用程序时发生这种情况，需要将应用程序标记为 合作伙伴。部署其中一个应用程序时，不会删除其伙伴。有关详细信息，请参阅将应用程序标记为合作伙伴。

教程：生成支持实时的应用程序

先决条件

下载示例应用程序

安装 GNU Arm 嵌入式工具链

Visual Studio 2019 和 2022

设置硬件以显示输出

设置硬件以显示输出

启用开发和调试

使用 Visual Studio 生成并运行 HelloWorld RTApp 应用程序

使用 Visual Studio Code 生成并运行 HelloWorld RTApp 应用程序

故障排除

生成示例

运行示例

调试示例

使用合作伙伴应用

后续步骤

其他资源

教程：生成支持实时的应用程序

先决条件

下载示例应用程序

安装 GNU Arm 嵌入式工具链

设置硬件以显示输出

设置硬件以显示输出

启用开发和调试

使用 Visual Studio 生成并运行 HelloWorld RTApp 应用程序

使用 Visual Studio Code 生成并运行 HelloWorld RTApp 应用程序

故障 排除

生成示例

运行示例

调试示例

使用合作伙伴应用

后续步骤

其他资源

故障排除