生成和部署合作伙伴应用程序

项目
08/09/2023

本部分介绍如何生成、打包和部署 Azure Sphere 合作伙伴应用程序。

这些说明使用 IntercoreComms 示例应用程序作为示例。

先决条件

将 Azure Sphere 设备连接到计算机
安装 Azure Sphere
如果使用 Visual Studio Code 或 CLI，请安装 GNU Arm Embedded 工具链。
设置硬件以显示来自专用 UART 的输出（如果尚未这样做）

启用开发和调试

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

启用开发和调试

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

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

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

输入以下命令：

az sphere device enable-development --enable-rt-core-debugging

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

如果 az sphere device enable-development 命令失败并显示以下错误消息，请参阅排查 Azure Sphere 问题以获取帮助。

error: The device did not accept the device capability configuration. Please check the Azure Sphere OS on your device is up-to-date using 'az sphere device show-deployment-status'.

使用 Visual Studio 生成合作伙伴应用

确保设备通过 USB 连接到电脑。在 “设置启动项 ”菜单中，选择“ Azure Sphere 应用 (所有核心) 其中 Azure Sphere 应用 是顶级项目的名称，或按 F5。
如果系统提示生成项目，请选择“ 是”。 Visual Studio 编译合作伙伴应用程序，创建映像包， 将其旁加载 到开发板上，并在调试模式下启动它们。 旁加载 意味着应用程序通过有线连接直接从电脑交付，而不是通过云传递。

请注意“ 查看>输出>”“显示输出来源：生成输出”中的路径，该路径指示输出映像包在电脑上的位置。准备好创建部署时，需要知道映像包的路径。
默认情况下，“ 输出 ”窗口显示 设备输出的输出。若要查看来自调试器的消息，请从“显示输出来源：”下拉菜单中选择“调试”。还可以通过 “调试>Windows ”菜单检查程序反汇编、寄存器或内存。

使用 Visual Studio Code 生成合作伙伴应用

打开包含合作伙伴应用程序的文件夹。 Visual Studio Code检测工作区文件并询问是否要打开工作区。选择“打开工作区”可同时打开实时应用程序和高级应用程序。
右键单击两个 CMakeLists.txt 文件之一，然后选择“ 生成所有项目”。
单击Visual Studio Code活动栏中的“运行”图标。
在屏幕左侧窗口顶部显示的下拉菜单上，选择“ 启动 Azure Sphere 应用 (gdb) (工作区) ”。
按 F5 生成和调试项目。如果之前尚未生成项目，或者文件已更改且需要重新生成，Visual Studio Code将在调试开始之前生成项目。
等待几秒钟，让Visual Studio Code生成应用程序、创建映像包、将其部署到开发板，并在调试模式下启动它们。在此过程中，你将在“ 输出 ”窗格中看到状态更新。

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

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

编译并生成应用程序

若要使用 CLI 生成应用程序，需要在计算机上找到正确的编译工具、标头和库（统称为 sysroot）。 Azure Sphere SDK 附带多个 sysroot，以便应用程序可以面向不同的 API 集，如应用程序运行时版本、sysroots 和 Beta API 中所述。 sysroot 安装在 Sysroots 下的 Azure Sphere SDK 安装文件夹中。

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

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

导航到包含支持实时的应用程序的文件夹。
打开 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"
  },
...

生成和部署高级应用程序

导航到包含高级应用程序的文件夹。
打开 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 显示在应用程序映像类型的“标识”部分中。例如：

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

通过

生成和部署合作伙伴应用程序

先决条件

启用开发和调试

启用开发和调试

使用 Visual Studio 生成合作伙伴应用

使用 Visual Studio Code 生成合作伙伴应用

编译并生成应用程序

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

生成和部署高级应用程序

反馈

其他资源