教程：生成高级应用程序

项目
08/09/2023

高级应用程序在 Azure Sphere OS 上运行，使用 Azure Sphere 应用程序库，并且可以与 Internet 和基于云的服务进行通信。有关高级应用程序的基本信息，请参阅 Azure Sphere 应用程序概述。

本教程介绍如何：

准备设备进行开发和调试

生成、运行和调试高级应用程序

先决条件

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

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

安装 Visual Studio 和 Azure Sphere 扩展。

准备设备进行开发和调试

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

az sphere device enable-development 命令将设备配置为接受要调试的应用程序，将调试服务器加载到设备上，并将设备分配给不允许云应用程序更新的设备组。在应用程序开发和调试期间，应将设备保留在此组中，以便云应用程序更新不会覆盖正在开发的应用程序。

确保 Azure Sphere 设备已连接到计算机，并且计算机已连接到 Internet。
使用 PowerShell、Windows 命令提示符或 Linux 命令行界面打开命令行界面。

输入以下命令：

az sphere device enable-development --resource-group <ResourceGroupName> --catalog <CatalogName> --device <DeviceIdValue>

应会看到类似于以下内容的输出：

Getting device capability configuration for application development.
Downloading device capability configuration for device ID '<device ID>'.
Successfully downloaded device capability configuration.
Successfully wrote device capability configuration file 'C:\Users\user\AppData\Local\Temp\tmpD732.tmp'.
Setting device group ID 'a6df7013-c7c2-4764-8424-00cbacb431e5' for device with ID '<device ID>'.
Successfully disabled over-the-air updates.
Enabling application development capability on attached device.
Applying device capability configuration to device.
Successfully applied device capability configuration to device.
The device is rebooting.
Installing debugging server to device.
Deploying 'C:\Program Files (x86)\Microsoft Azure Sphere SDK\DebugTools\gdbserver.imagepackage' to the attached device.
Image package 'C:\Program Files (x86)\Microsoft Azure Sphere SDK\DebugTools\gdbserver.imagepackage' has been deployed to the attached device.
Application development capability enabled.
Successfully set up device '<device ID>' for application development, and disabled over-the-air updates.
Command completed successfully in 00:00:38.3299276.

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

使用 Visual Studio Code 生成并运行高级应用程序

本教程使用 Azure Sphere Blink 模板，该模板是适用于 Visual Studio Code的 Azure Sphere 扩展的一部分。 Blink 模板会闪烁 LED，以便你可以验证 Azure Sphere 设备和工具是否已正确安装和设置。

启动Visual Studio Code。选择“ 查看>命令”面板，然后键入“Azure Sphere：生成新项目”。
从“模板”菜单中选择“ 闪烁 ”。

Visual Studio Code然后显示文件资源管理器窗口。导航到要放置 Blink 应用程序的文件夹。 Visual Studio Code在所选位置创建 Blink 文件夹并为 Blink 应用程序生成生成文件。应会看到来自 CMake 的消息。
打开 CMakeLists.txt 文件并更改TARGET_DIRECTORY设置，以指定包含正在使用的硬件定义的文件夹。默认情况下，TARGET_DIRECTORY指定 HardwareDefinitions/mt3620_rbd，它与 Seeed Azure Sphere MT3620 开发工具包匹配：
```
azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
```
模板提供了多个硬件定义。例如，如果使用 SEEED MT3620 微型开发板，请改为指定 HardwareDefinitions/seeed_mt3620_mdb。
按 F5 生成和调试项目。如果之前尚未生成项目，或者文件已更改且需要重新生成，Visual Studio Code将在调试开始之前生成项目。
等待几秒钟，让Visual Studio Code生成应用程序、创建映像包、将其部署到开发板，并在调试模式下启动它。在此过程中，你将在“ 输出 ”窗格中看到状态更新。

首先，CMake 确定是否需要生成应用程序。如果是这样，焦点将转移到输出窗格，其中显示来自 CMake/Build 的输出。

接下来，输出窗格会在将映像包部署到设备时显示输出。最后，调试控制台接收焦点并显示 gdb 输出。

提示

记下映像包的位置，因为创建部署时需要它。应在“输出”窗口中看到一条消息，如“生成文件写入路径<>”，其中 <path> 是 Blink 应用程序的生成文件夹的完整路径，通常以“out\ARM-Debug”或“out/ARM-Debug”结尾。
短暂延迟后，应会看到 LED 闪烁。
在 main.c 中的某个位置设置断点并单步执行应用程序，以便浏览 Azure Sphere 的Visual Studio Code调试功能。

使用 Visual Studio 生成并运行高级应用程序

本教程使用 Azure Sphere Blink 模板，该模板是适用于 Visual Studio 的 Azure Sphere 扩展的一部分。 Blink 模板会闪烁 LED，以便你可以验证 Azure Sphere 设备和工具是否已正确安装和设置。

如果不熟悉 Visual Studio，请考虑使用快速入门或指南来了解如何导航和使用它。
打开 Visual Studio，然后选择“ 创建新项目”。在“搜索”框中，键入“azure sphere”以获取 Azure Sphere 模板的列表。从列表中选择 “Azure Sphere Blink ”。
输入项目的名称和位置，然后选择“ 创建”。
打开 CMakeLists.txt 文件并更改TARGET_DIRECTORY设置，以指定包含正在使用的硬件定义的文件夹。默认情况下，TARGET_DIRECTORY指定 HardwareDefinitions/mt3620_rbd，它与 Seeed Azure Sphere MT3620 开发工具包匹配：
```
azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
```
模板提供了多个硬件定义。例如，如果使用 SEEED MT3620 微型开发板，请改为指定 HardwareDefinitions/seeed_mt3620_mdb。
在 Visual Studio 中，选择“ 查看>输出 ”以显示“ 输出 ”窗格。
确保设备通过 USB 连接到电脑。在 “设置启动项 ”菜单中，按 F5 或选择“ Azure Sphere 应用 (HLCore) *，其中 Azure Sphere 应用 是当前高级应用程序的名称。
如果系统提示生成项目，请选择“ 是”。 Visual Studio 编译应用程序，创建映像包， 将其旁加载 到开发板上，并在调试模式下启动它。 旁加载 意味着应用程序通过有线连接直接从电脑交付，而不是通过云传递。

提示

记下映像包的位置，因为创建部署时需要它。在“查看>输出显示输出来源：生成”中的输出中，应看到一条消息，如“输出>文件位于：<path>”，其中 <path> 是 Blink 应用程序的生成文件夹的完整路径，通常以“out/ARM-Debug”结尾。
默认情况下，“ 输出 ”窗格显示 设备输出的输出。若要查看来自调试器的消息，请从“显示输出来源：”下拉菜单中选择“调试”。还可以通过 “调试>Windows ”菜单检查程序反汇编、寄存器或内存。
运行程序时，应会看到 LED 闪烁。

下载示例应用程序

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

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

生成示例

若要为 HelloWorld_HighLevelApp 示例应用程序创建生成文件和 .imagepackage 文件，请执行以下步骤。

如有必要，请更新示例以面向硬件。默认情况下，遵循 MT3620 参考板设计的示例目标硬件 (RDB) ，例如 Seeed Studios 的 MT3620 开发工具包。 Azure Sphere 示例存储库的 HardwareDefinitions 目录中提供了示例应用程序的其他目标硬件定义。例如，Avnet MT3620 初学者工具包的硬件定义文件位于 HardwareDefinitions/avnet_mt3620_sk 子目录中。
- 打开 CMakeLists.txt 并更新 azure_target_hardware_definition 函数中的 TARGET_DIRECTORY 参数，使其指向硬件的子目录。例如：
```
azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "../../../HardwareDefinitions/avnet_mt3620_sk" TARGET_DEFINITION "sample_appliance.json")
```
使用 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) 可用于提高可读性，但不是必需的。
以下示例显示了Hello World高级应用的 CMake 命令：
- 窗户
- Linux
Windows 命令提示符
```
 cmake ^
 --preset "ARM-Debug" ^
 "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp"
```
Windows PowerShell
```
 cmake `
 --preset "ARM-Debug" `
 "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp"
```
```
cmake \
 --preset "ARM-Debug" \
 ./AzSphere/azure-sphere-samples/Samples/HelloWorld/HelloWorld_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 命令进行任何更改后，请删除整个生成，然后重试。

运行示例

如果设备已在运行应用程序，请删除该应用程序：
```
az sphere device sideload delete
```
更改为包含以前创建的生成文件和 .imagepackage 文件的目录。
通过运行 az sphere device sideload deploy 命令并指定映像包，将映像包加载到设备上。例如：
```
az sphere device sideload deploy --image-package HelloWorld_HighLevelApp.imagepackage
```
此命令加载映像包并启动应用程序。应会看到 LED 闪烁。

提示

记下映像包的路径。稍后将在部署快速入门中使用映像包。

调试示例

更改为包含以前创建的生成文件和 .imagepackage 文件的目录。

获取组件 ID（如果还没有）：

az sphere image-package show --image-package HelloWorld_HighLevelApp.imagepackage

如果应用程序正在运行，请停止它，然后使用选项重启它 --debug-mode ：

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

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

应会看到：

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

使用终端客户端建立 Telnet 或原始 TCP 连接，以从进程读取输出流。指定 192.168.35.2 作为 IP 地址，将 2342 指定为端口。

在 Windows 上使用 PowerShell 或标准命令提示符打开命令行接口，或在 Linux 上使用命令行界面，并将生成中的 .out 应用二进制文件作为参数传递。这将启用完整的源代码调试。

窗户
Linux

Windows 命令提示符

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

Windows PowerShell

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

 /opt/azurespheresdk/Sysroots/*sysroot*/tools/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-musleabi/arm-poky-linux-musleabi-gdb HelloWorld_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
运行你选择的任何其他 gdb 命令。例如，以下命令在条目时将断点设置为main () 然后在断点之后分别继续执行。
```
break main
```
```
c
```
有关使用 gdb 进行调试的详细信息，请参阅 GDB：GNU 项目调试器或有关该主题的其他众多源之一。

后续步骤

你已生成一个高级应用程序，可在 Azure Sphere 设备上运行。建议立即对其进行修改。硬件定义介绍如何编辑硬件定义 JSON 文件并重新生成关联的头文件。

接下来，了解如何从云部署高级应用程序。

教程：创建云部署

另请参阅

访问 Azure Sphere 库，这是一个鼓舞人心、未经管理和可重用的 Azure Sphere 脚本、实用工具和函数的集合。

通过