教學課程：建立高階應用程式

發行項
04/03/2024

高階應用程式會在 Azure 球體 OS 上執行、使用 Azure 球體應用程式庫，並可與因特網和雲端服務通訊。如需高層級應用程式的基本資訊，請參閱 Azure 球體應用程式概觀。

在此教學課程中，您將瞭解如何：

準備您的裝置以進行開發和偵錯

建立、執行和偵錯高階應用程式

先決條件

安裝適用於 Windows 或 Linux 的 CMake 和 Ninja。

安裝適用於 Windows 或 Linux 的 Visual Studio Code。
安裝適用於 Windows 或 Linux 的 CMake 和 Ninja。

安裝 Visual Studio 和 Azure 球體擴充功能。

準備您的裝置以進行開發和偵錯

您必須先啟用開發及側載，才能在 Azure 球體裝置上建立範例應用程式或開發新的應用程式。根據預設，Azure 球體裝置會被「鎖定」;也就是說，他們不允許從計算機載入開發中的應用程式，也不允許偵錯應用程式。準備裝置以進行側載會移除此限制。

az 球形裝置啟用開發命令會將裝置設定為接受偵錯應用程式、將偵錯伺服器載入裝置，並將裝置指派給不允許雲端應用程式更新的裝置群組。在應用程式開發和偵錯期間，您應將裝置留在此群組中，讓雲端應用程式更新不會覆寫開發中的應用程式。

確定您的 Azure 球體裝置已連接到您的電腦，且您的電腦已連線到因特網。
使用 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 球體裝置啟用開發 命令失敗，請參閱 Azure 球體問題的疑難解答以取得協助。

使用 Visual Studio Code 建置及執行高階應用程式

此教學課程使用 Azure 球體閃爍範本，此範本是 Visual Studio Code Azure 球體擴充功能的一部分。 [閃爍] 範本會閃爍 LED，讓您可以確認已正確安裝並設定 Azure 球體裝置和工具。

開始 Visual Studio Code。選 取 [檢視>命令調色盤]，然後輸入「Azure 球體：產生新專案」。
從 [範本] 功能表選取 [閃爍 ]。

Visual Studio Code 然後顯示 檔案總管 視窗。瀏覽至您要放置 [閃爍] 應用程式的資料夾。 Visual Studio Code 會在您選取的位置建立 [閃爍] 資料夾，併產生 [閃爍] 應用程式的組建檔案。您應該會看到來自 CMake 的郵件。
開啟 CMakeLists.txt 檔案並變更TARGET_DIRECTORY設定，以指定包含所使用硬體定義的資料夾。根據預設，TARGET_DIRECTORY會指定符合 Seeed Azure 球體 MT3620 開發工具包的 HardwareDefinitions/mt3620_rbd：
```
azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
```
範本隨附數個硬體定義。例如，如果您使用的是 SEEED MT3620 Mini Dev Board，請改為指定 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 球體的 Visual Studio Code 偵錯功能。

使用 Visual Studio 建置和執行高階應用程式

此教學課程使用 Azure 球體閃爍範本，這是 Visual Studio Azure 球體擴充功能的一部分。 [閃爍] 範本會閃爍 LED，讓您可以確認已正確安裝並設定 Azure 球體裝置和工具。

如果您是 Visual Studio 的新使用者，請考慮使用快速入門或引導式導覽來瞭解如何流覽和使用。
開啟 Visual Studio，然後選取 [建立新專案]。在 [搜尋] 方塊中，輸入「azure 球體」以取得 Azure 球體範本清單。從清單中選擇 [Azure 球體閃爍 ]。
輸入項目的名稱和位置，然後選取 [ 建立]。
開啟 CMakeLists.txt 檔案並變更TARGET_DIRECTORY設定，以指定包含所使用硬體定義的資料夾。根據預設，TARGET_DIRECTORY會指定符合 Seeed Azure 球體 MT3620 開發工具包的 HardwareDefinitions/mt3620_rbd：
```
azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
```
範本隨附數個硬體定義。例如，如果您使用的是 SEEED MT3620 Mini Dev Board，請改為指定 HardwareDefinitions/seeed_mt3620_mdb。
在 Visual Studio 中，選 取 [檢視>輸出 ] 以顯示 [輸出] 窗格。
確定您的裝置已透過 USB 連接到電腦。在 [設定啟動專案] 功能表中，按 F5 或選取 [Azure 球體應用程式 (HLCore) * 其中 Azure 球體應用程式是您目前高層級應用程式的名稱。
如果系統提示您建立專案，請選取 [ 是]。 Visual Studio 會編譯應用程式、建立影像套件、側載至白板，然後以偵錯模式啟動。側載表示應用程式是透過有線連線直接從電腦傳遞，而不是透過雲端傳遞。

提示

記下影像套件的位置，如建立部署時所需。您應該會在 [檢視>輸出>顯示來自：組建的輸出] 中的輸出中看到「輸出檔案在：<路徑>」等訊息，其中<path>是閃爍應用程式組建資料夾的完整路徑，通常結尾為「out/ARM-Debug」。
根據預設，[ 輸出 ] 窗格會顯示 [裝置輸出] 的輸出。若要查看來自調試程式的郵件，請從 [顯示輸出來源：] 下拉功能表中選取 [偵錯]。您也可以透過 [ 偵錯>Windows ] 功能表，對程序進行拆解、註冊或記憶體檢查。
當您執行程式時，應該會看到LED閃爍。

下載範例應用程式

您可以下載 HelloWorld 應用程式，如下所示：

將瀏覽器指向 Microsoft 範例瀏覽器。
在搜尋方塊中輸入「Azure 球體」。。
從搜尋結果中選取 [Azure 球體 - Hello World]。
選取 [下載 ZIP]。
開啟下載的檔案，然後解壓縮到本機目錄。

建立範例

若要建立HelloWorld_HighLevelApp範例應用程式的組建和 .imagepackage 檔案，請遵循下列步驟。

如有需要，請更新範例以鎖定您的硬體。根據預設，遵循 MT3620 參考面板設計 (RDB) 的範例目標硬體，例如來自 Seeed Studio 的 MT3620 開發工具包。範例應用程式的其他目標硬體定義可在 Azure 球體範例回收的 HardwareDefinitions 目錄中取得。例如，Avnet MT3620 Starter Kit 的硬體定義檔案位於 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 球體樣本上執行 CMake，則組建命令會是 cmake --build out/ARM-Debug。
- <source-path>
  
  包含範例應用程式之來源檔案的目錄路徑。在範例中，Azure 球體樣本存放庫已下載到名為 AzSphere 的目錄。
  
  CMake 參數會以空格分隔。 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 -C out/ARM-Debug
```
忍者會將產生的應用程式和 .imagepackage 檔案放在指定的目錄中。

您也可以使用下列命令透過 CMake 叫用忍者：
```
cmake --build out/<binary-dir>
```
設定 <binary-dir> 為包含 CMake 快取的二進位目錄。例如，如果您在 Azure 球體樣本上執行 CMake，則組建命令會是 cmake --build out/ARM-Debug。

進行疑難解答時，尤其是對 CMake 命令進行任何變更之後，請刪除整個組建，然後再試一次。

執行範例

如果您的裝置已經在執行應用程式，請刪除應用程式：
```
az sphere device sideload delete
```
變更包含先前建立之組建和 .imagepackage 檔案的目錄。
執行 az 球形裝置側載部署 命令並指定影像套件，將圖像套件載入到您的裝置上。例如：
```
az sphere device sideload deploy --image-package HelloWorld_HighLevelApp.imagepackage
```
這個命令會載入圖像套件並啟動應用程式。您應該會看到LED閃爍。

提示

請注意圖像套件的路徑。您稍後將在部署快速入門中使用圖像套件。

偵錯樣本

變更包含先前建立之組建和 .imagepackage 檔案的目錄。

如果您還沒有元件識別碼，請取得：

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 或 RAW 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 球體 SDK 會隨附多個 sysroots ，讓應用程式可以按照應用程式運行時間版本、sysroots 和 Beta API 中所述，以不同的 API 集為目標。 Sysroots 會安裝在 Sysroots 下的 Azure 球體 SDK 安裝資料夾中。

將遠端偵錯目標設定為埠 2345 上的 IP 位址 192.168.35.2：

target remote 192.168.35.2:2345
執行您選擇的任何其他 gdb 命令。例如，下列命令會在進入主 () 時設定斷點，然後分別在斷點之後繼續執行。
```
break main
```
```
c
```
如需有關使用 gdb 進行偵錯的詳細資訊，請參閱 GDB：GNU 專案調試程式或主題上的其他眾多來源之一。

後續步驟

您已建置高階應用程式，可在 Azure 球體裝置上執行。您可能想要立即修改。硬體定義說明如何編輯硬體定義 JSON 檔案，並重新產生相關聯的頁首檔案。

接下來，瞭解如何從雲端部署您的高階應用程式。

教學課程：建立雲端部署

另請參閱

造訪 Azure 球體圖庫，這是一個集合，其中包含一個令人振奮、未實現且可重複使用的 Azure 球體腳本、公用程式和函數。