教學課程：使用 Eclipse ThreadX 將 MXCHIP AZ3166 devkit 連線至 IoT 中樞

發行項
11/11/2024

在本教學課程中，您會使用 Eclipse ThreadX 將 MXCHIP AZ3166 IoT DevKit 連線至 Azure IoT。

您要完成下列工作：

安裝內嵌開發工具，以在 C 中對 MXChip DevKit 進行程式設計
建置映像並將其刷新至 MXCHIP DevKit
使用 Azure CLI 建立和管理 MXCHIP DevKit 安全地連線到的 Azure IoT 中樞
使用 Azure IoT Explorer 向 IoT 中樞註冊裝置、檢視裝置屬性、檢視裝置遙測，以及在裝置上呼叫直接命令

必要條件

執行 Windows 10 或 Windows 11 的電腦
啟用中的 Azure 訂用帳戶。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
用於複製存放庫的 Git (英文)
Azure CLI。在本教學課程中，您有兩個選項可用來執行 Azure CLI 命令：
- 使用 Azure Cloud Shell，這是一種在瀏覽器中執行 CLI 命令的互動式 shell。建議使用此選項，因為您不需要安裝任何項目。如果您是第一次使用 Cloud Shell，請登入 Azure 入口網站。請遵循 Cloud Shell 快速入門中的步驟，以啟動 Cloud Shell並選取 Bash 環境。
- 或者，在本機電腦上執行 Azure CLI。如果已安裝 Azure CLI，請執行 az upgrade 以將 CLI 和擴充功能更新為目前的版本。若要安裝 Azure CLI，請參閱安裝 Azure CLI。
硬體
- The MXCHIP AZ3166 IoT DevKit (MXCHIP DevKit)
- Wi-Fi 2.4 GHz
- USB 2.0 A 型公頭至 Micro USB 公頭纜缐

準備開發環境

若要設定開發環境，請先複製 GitHub 存放庫，其中包含教學課程所需的所有資產。然後，您會安裝一組程式設計工具。

複製存放庫

複製下列存放庫，以下載所有範例裝置程式碼、設定指令碼和文件的離線版本。如果您先前在另一個教學課程中複製此存放庫，就不需要再執行此存放庫。

若要複製存放庫，請執行下列命令：

git clone --recursive https://github.com/eclipse-threadx/getting-started.git

安裝工具

複製的存放庫包含安裝指令碼，其會安裝及設定所需的工具。如果您在另一個內嵌裝置教學課程中安裝這些工具，則不需要再次執行。

注意

安裝指令碼會安裝下列工具：

CMake (英文)：組建
ARM GCC：編譯
Termite：監視連線裝置資源的序列埠輸出

若要安裝工具：

瀏覽至存放庫中的下列路徑，然後執行名為 get-toolchain.bat 的安裝腳稿：

getting-started\tools\get-toolchain.bat
開啟新的主控台視窗，以辨識安裝腳本所做的組態變更。使用此主控台來完成教學課程中的其餘程式設計工作。您可以使用 Windows CMD、PowerShell 或 Git Bash for Windows。
執行下列程式碼來確認已安裝 CMake 3.14 版或更新版本。
```
cmake --version
```

建立雲端元件

建立 IoT 中樞

您可以使用 Azure CLI 來建立 IoT 中樞，其會為您的裝置處理事件和傳訊。

若要建立 IoT 中樞：

啟動 CLI 應用程式。若要在此快速入門的其餘部分執行 CLI 命令，請複製命令語法、將其貼入 CLI 應用程式、編輯變數值，然後按 Enter 鍵。
- 如果您使用的是 Cloud Shell，請以滑鼠右鍵按一下 Cloud Shell 的連結，然後選取要在新索引標籤中開啟的選項。
- 如果您要在本機使用 Azure CLI，則請啟動 CLI 主控台應用程式，並登入 Azure CLI。
執行 az extension add 以將 azure-iot 延伸模組安裝或升級至目前版本。
```
az extension add --upgrade --name azure-iot
```
執行 az group create 命令以建立資源群組。下列命令會在 centralus 區域建立名為 MyResourceGroup 的資源群組。

注意

您可以選擇性地設定替代 location。若要查看可用的位置，請執行 az account list-locations (部分機器翻譯)。
```
az group create --name MyResourceGroup --location centralus
```
使用 az iot hub create 命令建立 IoT 中樞。建立 IoT 中樞可能需要幾分鐘的時間。

YourIotHubName。將程式碼中的這個預留位置取代為您為 IoT 中樞選擇的名稱。 IoT 中樞名稱在 Azure 中必須是全域唯一的。此預留位置用於本快速入門的其餘部分，以代表您的唯一 IoT 中樞名稱。

--sku F1 參數會在免費層中建立 IoT 中樞。免費層中樞具有一個有限的功能集，並用於概念證明應用程式。如需 IoT 中樞層、功能和定價的詳細資訊，請參閱 Azure IoT 中樞定價。
```
az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName} --sku F1 --partition-count 2
```
在建立 IoT 中樞之後，請在主控台中檢視 JSON 輸出，並複製要在稍後步驟中使用的 hostName 值。 hostName 值看起來像下列範例：

{Your IoT hub name}.azure-devices.net

設定 IoT 總管

在本快速入門的其餘部分，您會使用 IoT 總管，將裝置註冊至 IoT 中樞、檢視裝置屬性和遙測，以及將命令傳送至您的裝置。在本節中，您會將 IoT 總管設定為連線至所建立的 IoT 中樞，以及從公用模型存放庫讀取隨插即用模型。

若要新增 IoT 中樞的連線：

安裝 Azure IoT 總管 (英文)。此工具是一種跨平台公用程式，用來監視和管理 Azure IoT 資源。
在您的 CLI 應用程式中，執行 az iot hub connection-string show (部分機器翻譯) 命令，為您的 IoT 中樞取得連接字串。
```
az iot hub connection-string  show --hub-name {YourIoTHubName}
```
複製連接字串，不含括住其的引號字元。
在 Azure IoT 總管中，選取左側功能表上的 [IoT 中樞]。
選取 [+ Add connection] \(+ 新增連線\)。
將連接字串貼入 [連接字串] 方塊中。
選取 [儲存]。

如果連線成功，IoT 總管會切換至 [裝置] 檢視。

若要新增公用模型存放庫：

在 IoT 總管中，選取 [首頁] 以返回首頁檢視。
在左側功能表上，選取 [IoT 隨插即用設定]。
確認現有的 公用存放庫 專案具有的端點 https://devicemodels.azure.com。

注意

如果沒有公用存放庫的專案，請選取 [+新增]，從下拉功能表中選取 [公用存放庫 ]，指定 https://devicemodels.azure.com 端點值，然後選取 [ 儲存]。

公用存放庫已完成的項目看起來像下列螢幕快照：

註冊裝置

在本節中，您會建立新的裝置執行個體，並向您建立的 IoT 中樞註冊此裝置執行個體。在稍後的章節中，您會使用新註冊裝置的連線資訊，安全地連線您的實體裝置。

若要註冊裝置：

從 IoT 總管的首頁檢視中，選取 [IoT 中樞]。
您先前新增的連線應該會出現。在連線屬性下方選取 [檢視此中樞內的裝置]。
選取 [+ 新增]，然後輸入您裝置的裝置識別碼；例如 mydevice。所有其他屬性保持不變。
選取建立。
使用複製按鈕來複製 [裝置識別碼] 和 [主要金鑰] 欄位。

在繼續下一節之前，請將從先前步驟擷取的下列每個值儲存到安全的位置。您會在下一節中使用這些值來設定您的裝置。

hostName
deviceId
primaryKey

準備裝置

若要將 MXCHIP DevKit 連線至 Azure，您可以修改 Wi-Fi 和 Azure IoT 設定的組態檔、重建映像，並將映像排清至裝置。

新增設定

在文字編輯器開啟下列檔案：

getting-started\MXChip\AZ3166\app\azure_config.h
將下列行註解化到檔案頂端附近，如下所示：
```
// #define ENABLE_DPS
```
將 Wi-Fi 常數設定為來自本機環境的下列值。

固定名稱值

WIFI_SSID {您的 Wi-Fi SSID}

WIFI_PASSWORD {您的 Wi-Fi 密碼}

WIFI_MODE {檔案中的其中一個列舉 Wi-Fi 模式值}
將 Azure IoT 裝置資訊常數設定為您在建立 Azure 資源之後儲存的值。

固定名稱值

IOT_HUB_HOSTNAME {您的主機名稱值}

IOT_HUB_DEVICE_ID {您的裝置識別碼值}

IOT_DEVICE_SAS_KEY {您的主要金鑰值}
儲存並關閉檔案。

固定名稱	值
`WIFI_SSID`	{您的 Wi-Fi SSID}
`WIFI_PASSWORD`	{您的 Wi-Fi 密碼}
`WIFI_MODE`	{檔案中的其中一個列舉 Wi-Fi 模式值}

固定名稱	值
`IOT_HUB_HOSTNAME`	{您的主機名稱值}
`IOT_HUB_DEVICE_ID`	{您的裝置識別碼值}
`IOT_DEVICE_SAS_KEY`	{您的主要金鑰值}

建置映像

在主控台或檔案總管中，執行下列路徑的指令碼 rebuild.bat 來建置映像：

getting-started\MXChip\AZ3166\tools\rebuild.bat
建置完成之後，請確認二進位檔案已在下列路徑中建立：

getting-started\MXChip\AZ3166\build\app\mxchip_azure_iot.bin

排清映像

在 MXCHIP DevKit 上，找出 [重設] 按鈕和 Micro USB 連接埠。您可以在下列步驟中使用這些元件。兩者均在下列圖片中反白顯示：
將 Micro USB 傳輸線連接到 MXCHIP DevKit 上的 Micro USB 連接埠，然後將其連線到您的電腦。
在檔案總管中，尋找您在上一節中建立的二進位檔案。
複製二進位檔案 mxchip_azure_iot.bin。
在檔案總管中，尋找連線到您電腦的 MXCHIP DevKit 裝置。裝置會顯示為系統上具有磁碟標籤 AZ3166 的磁碟機。
將二進位檔案貼到 MXCHIP Devkit 的根資料夾中。閃爍會在幾秒鐘內自動啟動並完成。

注意

在閃爍流程中，MXCHIP DevKit 上的綠色 LED 會切換。

確認裝置連線詳細資料

您可以使用 Termite 應用程式來監視通訊，並確認您的裝置已正確設定。

啟動 Termite。

提示

如果您無法將 Termite 連線到 devkit，請安裝 ST-LINK 驅動程式 (英文)，然後再試一次。如需其他步驟，請參閱疑難排解 (部分機器翻譯)。
選取設定。
在 [序列埠設定] 對話方塊中，檢查下列設定，並視需要更新：
- 傳輸速率：115200
- 連接埠：MXCHIP DevKit 所連線的連接埠。如果下拉式清單中有多個連接埠選項，您可以找到要使用的正確連接埠。開啟 Windows 裝置管理員，並檢視連接埠，以識別要使用的連接埠。
選取 [確定]。
按裝置上的 [重設] 按鈕。按鈕會在裝置上加上標籤，並位於 Micro USB 連接器附近。

在 Termite 應用程式中，檢查下列檢查點值，以確認裝置已初始化並連線至 Azure IoT。

 Starting Azure thread


 Initializing WiFi
     MAC address: ******************
 SUCCESS: WiFi initialized

 Connecting WiFi
     Connecting to SSID 'iot'
     Attempt 1...
 SUCCESS: WiFi connected

 Initializing DHCP
     IP address: 192.168.0.49
     Mask: 255.255.255.0
     Gateway: 192.168.0.1
 SUCCESS: DHCP initialized

 Initializing DNS client
     DNS address: 192.168.0.1
 SUCCESS: DNS client initialized

 Initializing SNTP time sync
     SNTP server 0.pool.ntp.org
     SNTP time update: Jan 4, 2023 22:57:32.658 UTC
 SUCCESS: SNTP initialized

 Initializing Azure IoT Hub client
     Hub hostname: ***.azure-devices.net
     Device id: mydevice
     Model id: dtmi:eclipsethreadx:devkit:gsgmxchip;2
 SUCCESS: Connected to IoT Hub

 Receive properties: {"desired":{"$version":1},"reported":{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128},"ledState":false,"telemetryInterval":{"ac":200,"av":1,"value":10},"$version":4}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=3{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=5{"ledState":false}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=7{"telemetryInterval":{"ac":200,"av":1,"value":10}}

 Starting Main loop
 Telemetry message sent: {"humidity":31.01,"temperature":25.62,"pressure":927.3}.
 Telemetry message sent: {"magnetometerX":177,"magnetometerY":-36,"magnetometerZ":-346.5}.
 Telemetry message sent: {"accelerometerX":-22.5,"accelerometerY":0.54,"accelerometerZ":1049.01}.
 Telemetry message sent: {"gyroscopeX":0,"gyroscopeY":0,"gyroscopeZ":0}.

讓 Termite 保持開啟狀態，以在下列步驟中監視裝置輸出。

檢視裝置屬性

您可以使用 Azure IoT 總管來檢視和管理裝置的屬性。在本節和下列各節內容中，您會使用 IoT Explorer 中顯示的隨插即用功能來管理 MXCHIP DevKit 並與其互動。這些功能會依賴公用模型存放庫中針對 MXCHIP DevKit 發佈的裝置模型。您已將 IoT Explorer 設定為在本教學課程稍早搜尋此存放庫的裝置模型。您可以從 IoT Explorer 中裝置窗格的左側功能表中選取動作，而不需使用隨插即用來執行許多動作。不過，使用隨插即用通常會提供增強的體驗。 IoT 總管可以讀取隨插即用裝置所指定的裝置型號，並顯示該裝置特定的資訊。

若要在 IoT 總管中存取裝置的 IoT 隨插即用元件：

從 IoT 總管的首頁檢視中，選取 [IoT 中樞]，然後選取 [檢視此中樞內的裝置]。
選取您的裝置。
選取 [IoT 隨插即用元件]。
選取 [預設元件]。 IoT 總管會顯示在裝置上實作的 IoT 隨插即用元件。

在 [介面]索引標籤上，檢視裝置模型 [描述]中的 JSON 內容。 JSON 包含裝置型號中每個 IoT 隨插即用元件設定詳細資料。

IoT 總管中的每個索引標籤都會對應至裝置型號中的其中一個 IoT 隨插即用元件。

定位字元	類型	姓名	描述
介面	介面	`MXCHIP Getting Started Guide`	MXCHIP DevKit 的範例模型
屬性 (唯讀)	屬性	`ledState`	LED 的目前狀態
屬性 (可寫入)	屬性	`telemetryInterval`	裝置傳送遙測的間隔
命令	Command	`setLedState`	開啟或關閉 LED

若要使用 Azure IoT Explorer 檢視裝置屬性：

選取 [屬性 (可寫入)] 索引標籤。其會顯示傳送遙測的間隔。
將 telemetryInterval 變更為 5，然後選取 [更新所需的值]。您的裝置現在會使用此間隔來傳送遙測。
IoT 總管會以通知回應。您也可以在 Termite 中觀察更新。
將遙測間隔設定回 10。

若要使用 Azure CLI 檢視裝置屬性：

執行 az iot hub device-twin show (部分機器翻譯) 命令。

az iot hub device-twin show --device-id mydevice --hub-name {YourIoTHubName}

在主控台輸出中檢查裝置的屬性。

檢視遙測

使用 Azure IoT 總管，您可以檢視從裝置到雲端的遙測流程。您可以選擇性地使用 Azure CLI 來執行相同的工作。

若要在 Azure IoT 總管中檢視遙測：

從 IoT 總管中裝置的 [IoT 隨插即用元件] (預設元件) 窗格中，選取 [遙測] 索引標籤。確認使用內建事件中樞設定為是。
選取 [開始]。
當裝置將訊息傳送至雲端時，檢視遙測。

注意

您也可以使用 Termite 應用程式來監視來自裝置的遙測。
選取 [顯示模型化事件] 核取方塊，以裝置模型指定的資料格式檢視事件。
選取 [停止]，以結束接收事件。

若要使用 Azure CLI 檢視裝置遙測：

執行 az iot hub monitor-events (部分機器翻譯) 命令。使用您先前在 Azure IoT 中為您的裝置和 IoT 中樞建立的名稱。
```
 az iot hub monitor-events --device-id mydevice --hub-name {YourIoTHubName}
```

在控制台中檢視 JSON 輸出。

 {
     "event": {
         "origin": "mydevice",
         "module": "",
         "interface": "dtmi:eclipsethreadx:devkit:gsgmxchip;1",
         "component": "",
         "payload": "{\"humidity\":41.21,\"temperature\":31.37,\"pressure\":1005.18}"
     }
 }

選取 CTRL+C 來結束監視。

在裝置上呼叫直接方法

您也可以使用 Azure IoT Explorer 呼叫您在裝置上實作的直接方法。直接方法具有名稱，而且可以選擇性地擁有 JSON 承載、可設定的連線和方法逾時。在本節中，您會呼叫開啟或關閉 LED 的方法。您可以選擇性地使用 Azure CLI 來執行相同的工作。

若要在 Azure IoT 總管中呼叫方法：

從 IoT 總管中裝置的 [IoT 隨插即用元件] (預設元件) 窗格中，選取 [命令] 索引標籤。
針對 setLedState 命令，請將 [狀態] 設定為 [true]。
選取 [傳送命令]。您應該會在 IoT 總管中看到通知，且裝置上的黃色的使用者 LED 燈應該會開啟。
將狀態設定為 false，然後選取 [傳送命令]。黃色的使用者 LED 應該關閉。
您可以選擇性地檢視 Termite 中的輸出，以監視方法的狀態。

若要使用 Azure CLI 呼叫方法：

執行 az iot hub invoke-device-method (部分機器翻譯) 命令，並指定方法名稱和承載。針對此方法，將 method-payload 設定為 true 以開啟 LED，並將其設定為 false 以將其關閉。
```
az iot hub invoke-device-method --device-id mydevice --method-name setLedState --method-payload true --hub-name {YourIoTHubName}
```
CLI 主控台會顯示裝置上方法呼叫的狀態，其中 204 表示成功。
```
{
  "payload": {},
  "status": 200
}
```
檢查您的裝置以確認 LED 狀態。

檢視 Termite 終端機以確認輸出訊息：

 Receive direct method: setLedState
     Payload: true
 LED is turned ON
 Device twin property sent: {"ledState":true}

疑難排解和偵錯

如果您在建置裝置程式碼、刷新裝置或連線時遇到問題，請參閱疑難排解 (部分機器翻譯)。

如需對應用程式進行偵錯，請參閱使用 Visual Studio Code 進行偵錯 (英文)。

清除資源

如果您不再需要在本快速入門中建立的 Azure 資源，則可以使用 Azure CLI，刪除資源群組及其所有資源。

重要

刪除資源群組是無法回復的動作。資源群組和其中包含的所有資源都將永久刪除。請確定您不會不小心刪除錯誤的資源群組或資源。

若要依名稱刪除資源群組：

執行 az group delete 命令。此命令會移除資源群組、IoT 中樞，和您建立的裝置註冊。
```
az group delete --name MyResourceGroup
```
執行 az group list 命令，以確認資源群組已刪除。
```
az group list
```

下一步

在本教學課程中，您已建置包含 Eclipse ThreadX 範例程式代碼的自定義映像，然後將映像刷新至 MXCHIP DevKit 裝置。您也已使用 Azure CLI 和/或 IoT Explorer 建立了 Azure 資源、安全地將 MXCHIP DevKit 連線至 Azure、檢視遙測資料，以及傳送訊息。

在下一個步驟中，探索下列文章，以深入瞭解內嵌開發選項。

深入了解如何使用 C SDK 和內嵌 C SDK 連線內嵌裝置 (部分機器翻譯)

Eclipse ThreadX 為 OEM 提供元件來保護通訊，並使用基礎 MCU/MPU 硬體保護機制建立程式碼和數據隔離。不過，每個 OEM 最終都會負責確保其裝置符合不斷演進的安全性需求。

共用方式為