教程：生成高级应用程序

重要

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

高级应用程序在 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 扩展。

• 安装适用于 Windows 或 Linux 的 SDK
• 选择租户并声明设备
• 配置网络并更新设备 OS

准备设备以进行开发和调试

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

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

1. 确保 Azure Sphere 设备已连接到计算机，并且计算机已连接到 Internet。

2. 使用 PowerShell、Windows 命令提示符或 Linux 命令行界面打开命令行界面。

3. 输入以下命令：

   azsphere device enable-development
   

   应该会看到与下面类似的输出：

   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.
   

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

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

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

1. 启动 Visual Studio Code。 选择“查看>命令”面板，然后键入 Azure Sphere：生成新项目。

   

2. 从“模板”菜单中选择“Blink”。

   

3. 然后，Visual Studio Code 会显示文件资源管理器窗口。 导航到要放置 Blink 应用程序的文件夹。 Visual Studio Code 会在所选位置创建 Blink 文件夹，并为 Blink 应用程序生成生成文件。 你应可看到来自 CMake 的消息。

4. 打开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。

5. 按 F5 生成和调试项目。 如果项目以前尚未生成，或者文件已更改并重新生成，Visual Studio Code 将在调试开始之前生成项目。

6. 等待几秒钟，Visual Studio Code 生成应用程序、创建映像包、将其部署到开发板，并在调试模式下启动它。 在此过程中， 你将在“输出 ”窗格中看到状态更新。

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

   接下来，输出窗格显示 Azure Sphere 的输出，因为它将映像包部署到设备。 最后，调试控制台接收焦点并显示 gdb 输出。

   提示

   记下映像包的位置，因为创建部署时需要它。 应在“输出”窗口中看到一条消息，例如“生成写入<路径>的文件”，其中<路径是 Blink 应用程序的生成文件夹的完整路径>，通常以“out\ARM-Debug”或“out/ARM-Debug”结尾。

7. 短暂延迟后，应看到 LED 闪烁。

8. 在 main.c 中的某个位置设置断点并单步执行应用程序，以便探索 Azure Sphere 的 Visual Studio Code 调试功能。

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

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

1. 如果不熟悉 Visual Studio，请考虑使用快速入门或指导教程了解如何在其中导航以及如何使用它。

2. 打开 Visual Studio 并选择“创建新项目” 。 在“搜索”框中，键入“azure sphere”以获取 Azure Sphere 模板的列表。 从列表中选择 Azure Sphere Blink。

3. 输入项目的名称和位置，然后选择“ 创建”。

4. 打开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。

5. 在 Visual Studio 中，选择“查看>输出”以显示“输出”窗格。

6. 确保通过 USB 将设备连接到电脑。 在“设置启动项”菜单中，选择 Azure Sphere 应用（HLCore），其中 Azure Sphere 应用是当前高级应用程序的名称或按 F5。

   

7. 如果系统提示你生成项目，请选择“是”。 Visual Studio 编译应用程序，创建映像包，并将其旁加载到开发板上，然后以调试模式启动该应用程序。 “旁加载”意味着应用程序通过有线连接直接从电脑传送，而不是通过云传送。

   提示

   记下映像包的位置，因为创建部署时需要它。 在“查看>输出>显示输出来源：生成”的输出中，应会看到一条消息，例如“输出文件位于：<path>”，其中<路径是 Blink 应用程序的生成文件夹的完整路径>，通常以“out/ARM-Debug”结尾。

8. 默认情况下，“输出”窗格显示设备输出的输出。 若要查看调试程序中的消息，请从“显示输出来源:”下拉菜单中选择“调试”。 也可通过“调试”>“Windows”菜单检查程序反汇编、寄存器或内存。

9. 当运行该程序时，应看到 LED 闪烁一次。

下载示例应用程序

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

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

生成示例

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

1. 如有必要，请更新示例，使之针对你的硬件。 默认情况下，示例目标硬件遵循 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")
     

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

3. 在命令提示符下，从项目生成目录中，使用以下参数运行 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 命令：

   Windows

   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"
   

   Linux

   cmake \
    --preset "ARM-Debug" \
    ./AzSphere/azure-sphere-samples/Samples/HelloWorld/HelloWorld_HighLevelApp
   

4. 运行 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 命令进行任何更改后，请删除整个生成并重试。

运行示例

1. 如果设备已在运行某个应用程序，请删除该应用程序：

   azsphere device sideload delete
   

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

3. 通过运行 azsphere device sideload deploy 命令并指定映像包，将映像包加载到设备上。 例如：

   Azure Sphere CLI

   azsphere device sideload deploy --image-package HelloWorld_HighLevelApp.imagepackage
   

   Azure Sphere 经典 CLI

   azsphere device sideload deploy --imagepackage HelloWorld_HighLevelApp.imagepackage
   

   注意

   Azure Sphere 经典 CLI 即将停用。 建议使用 Azure Sphere（集成）。

   此命令加载映像包并启动应用程序。 应会看到 LED 闪烁。

   提示

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

调试示例

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

2. 如果还没有组件 ID，请获取它：

   Azure Sphere CLI

   azsphere image-package show --image-package HelloWorld_HighLevelApp.imagepackage
   

   Azure Sphere 经典 CLI

   azsphere image-package show --filepath HelloWorld_HighLevelApp.imagepackage
   

   注意

   Azure Sphere 经典 CLI 即将停用。 建议使用 Azure Sphere（集成）。

---

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

   Azure Sphere CLI

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

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

   Azure Sphere 经典 CLI

   azsphere device app stop --componentid <ComponentId>
   

   azsphere device app start --debug --componentid <ComponentId>
   

   注意

   Azure Sphere 经典 CLI 即将停用。 建议使用 Azure Sphere（集成）。

---

应会看到：

 <ComponentId>
 App state   : debugging
 GDB port    : 2345
 Output port : 2342
 Core        : High-level

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

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

   Windows

   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
   

   Linux

    /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 集，如应用程序运行时版本、sysroot 和 Beta API 中所述。 sysroot 安装在 Sysroots 下的 Azure Sphere SDK 安装文件夹中。

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

   target remote 192.168.35.2:2345

4. 运行选择的任何其他 gdb 命令。 例如，以下命令在进入 main（）时设置断点，然后在断点后继续执行。

   break main
   

   c
   

   有关使用 gdb 进行调试的详细信息，请参阅 GDB：GNU 项目调试器 或主题上的其他许多源之一。

后续步骤

你已生成一个高级应用程序，用于在 Azure Sphere 设备上运行。 现在可能需要修改它。 硬件定义 描述如何编辑硬件定义 JSON 文件并重新生成关联的头文件。

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

教程：创建云部署

另请参阅

访问 Azure Sphere 库，这是一系列鼓舞人心、未经保护且可重用的 Azure Sphere 脚本、实用工具和函数。