教學課程：建立支持即時功能的應用程式

發行項
03/27/2024

此教學課程示範如何在 Azure 球體裝置上建立即時核心的範例應用程式。如需即時支援應用程式的基本資訊，請參閱 Azure 球體應用程式概觀。

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

下載範例應用程式
安裝 GNU Arm 工具鏈
設定硬體以顯示輸出
啟用開發與偵錯
啟動終端模擬器以檢視輸出
建置、執行和偵錯支援即時的應用程式

重要

這些指示假設您使用的硬體遵循 MT3620 參考面板設計 (RDB) 硬體，例如來自 Seeed Studio 的 MT3620 Dev Kit。如果您使用不同的 Azure 球體硬體，請參閱製造商的檔，以瞭解 UART 是否公開以及如何存取。您可能需要設定硬體以不同方式顯示輸出，並更新範例程式代碼和app_manifest.json檔案的 Uart 功能 變數，以使用不同的 UART。

先決條件

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

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

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

下載範例應用程式

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

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

安裝 GNU Arm Embedded Toolchain

您可以從 Arm 開發人員網站下載並安裝 GNU Arm Embedded Toolchain。或者，您可以使用 vcpkg 成品來自動安裝和設定開發環境。

手動下載 GNU Arm Embedded Toolchain
使用 vcpkg 安裝

Visual Studio 2022：如果您使用的是 Visual Studio 2022，請從 Arm 開發人員網站安裝 GNU Arm Embedded Toolchain (arm-none-eabi) 。
Visual Studio 2019：工具鏈會自動與 Visual Studio 2019 上的 Visual Studio azure 球形延伸模組一起安裝。如果您使用的是 Visual Studio 2019，請繼續設定硬體以顯示輸出。不過，如果您手動安裝 GNU Arm Embedded Toolchain，Visual Studio 會使用您安裝的版本。

若要安裝工具鏈，請在 Arm 開發人員網站上尋找 GNU Arm Embedded Toolchain (arm-none-eabi) ，其中包含 ARM Cortex-M4 處理器的編譯程式。依照該處的指示下載並安裝操作系統平臺的編譯程式。

根據預設，Visual Studio Code 搜尋工具鏈，應該會找到您安裝的版本。如果您遇到與工具鏈相關的組建問題，請輸入路徑，如下所示：

選 取 [檔案>喜好設定>] 設定>擴充功能>Azure 球體。
在 Azure 球體中輸入 GNU Arm Embedded Toolchain 安裝路徑 ：Arm Gnu 路徑 設定。

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

注意

支援自動啟用 vcpkg，從 Visual Studio 2022 版本 17.4 Preview 2 開始。確定已安裝 vcpkg，且您使用的是版本 17.4 Preview 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 Dev Kit，則查看 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 Friend 配接器。
啟動終端模擬器程式，並開啟轉接器所使用的 115200-8-N-1 終端機至 COM 埠。請參閱終端模擬器的檔，瞭解如何指定埠和速度。

設定硬體以顯示輸出

將 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 Friend 配接器。
在 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

啟動終端模擬器程式，並開啟轉接器所使用的 115200-8-N-1 終端機至 COM 埠。請參閱終端模擬器的檔，瞭解如何指定埠和速度。

啟用開發與偵錯

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

若要偵錯即時核心，請使用 az 球體裝置啟用開發 命令。此命令會將裝置設定為接受來自計算機的應用程式進行偵錯，並將裝置指派給「開發裝置」群組，而此群組不允許雲端應用程式更新。在應用程式開發和偵錯期間，您應將裝置留在此群組中，讓雲端應用程式更新不會覆寫開發中的應用程式。

在 Windows 上，您必須新增 --enable-rt-core-debugging 參數，將偵錯伺服器和每種核心類型的必要驅動程式載入裝置上。

窗戶
Linux

如果您尚未登入 Azure 球體，請登入：
```
az login
```
使用 PowerShell 或具有系統管理員許可權的 Windows 命令提示字元開啟命令行介面。參數 --enable-rt-core-debugging 需要系統管理員許可權，因為它會安裝偵錯程式的USB驅動程式。

輸入下列命令：

az sphere device enable-development --enable-rt-core-debugging  --catalog <CatalogName>  --resource-group <ResourceGroupName>

由於不再需要系統管理員許可權，所以在命令完成後關閉視窗。最佳作法是一律使用能完成工作的最低許可權。

如果您尚未登入 Azure 球體，請登入：
```
az login
```

輸入下列命令：

az sphere device enable-development --enable-rt-core-debugging  --catalog <CatalogName> --resource-group <ResourceGroupName>

如果 az 球體裝置啟用開發 命令失敗，請參閱 Azure 球體問題的疑難解答以取得協助。

使用 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 球體輸出視窗應該會顯示「正在部署影像...」後面接著 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 從零變更為一。
像往常一樣逐步執行程序代碼。

建立範例

使用 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) 可用於可讀性，但並非必要。
下列範例顯示 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 -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
```
在專案目錄的命令提示字元中，載入忍者建立的影像套件：
```
az sphere device sideload deploy --image-package <path-to-imagepackage>
```
應用程式載入之後很快就會開始執行。下列將顯示在連接的終端機模擬器上：
```
Tick

Tock

Tick
.
.
.
```

取得影像的元件識別碼：

az sphere image-package show --image-package <path-to-imagepackage>

命令會傳回圖像套件的所有元數據。應用程式的元件識別碼會出現在應用程式圖像類型的 [身分識別] 區段中。例如：

...
  "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 資料夾。 Sysroots 會安裝在 Azure 球體 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 上執行，請將「目標 io0」取代為「目標 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 檔案和 start 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 球體裝置時，Azure 球體部署工具預設會刪除所有現有的應用程式。若要避免在您開發彼此通訊的應用程式時發生這種情況，您必須將應用程式標示為 合作夥伴。當您部署其中一個應用程式時，不會刪除其合作夥伴。如需詳細資訊，請參閱將應用程式標示為合作夥伴。

教學課程：建立支持即時功能的應用程式

先決條件

下載範例應用程式

安裝 GNU Arm Embedded Toolchain

Visual Studio 2019 和 2022

設定硬體以顯示輸出

設定硬體以顯示輸出

啟用開發與偵錯

使用 Visual Studio 建置和執行 HelloWorld RTApp 應用程式

使用 Visual Studio Code 建立並執行 HelloWorld RTApp 應用程式

故障排除

建立範例

執行範例

偵錯樣本

使用合作夥伴應用程式

後續步驟

其他資源