教學課程：將ESPRESSIF ESP32-Azure IoT 套件連線至 IoT 中樞

發行項
06/13/2024

在本教學課程中，您會使用適用於FreeRTOS的 Azure IoT 中間件，將ESPRESSIF ESP32-Azure IoT 套件（從現在起，ESP32 DevKit）連線到 Azure IoT。

您要完成下列工作：

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

必要條件

執行 Windows 10 或 Windows 11 的電腦
用於複製存放庫的 Git
硬體
- ESPRESSIF ESP32-Azure IoT 套件
- USB 2.0 A 型公插頭對 Micro USB 公插頭纜缐
- Wi-Fi 2.4 GHz
啟用中的 Azure 訂用帳戶。如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。

準備開發環境

安裝工具

若要設定開發環境，請先安裝 ESPRESSIF ESP-IDF 組建環境。安裝程式包含複製、建置、快閃及監視裝置所需的所有工具。

若要安裝 ESP-IDF 工具：

下載並啟動 ESP-IDF v5.0 Offline-installer。
當安裝程式列出要安裝的元件時，請選取所有元件並完成安裝。

複製存放庫

複製下列存放庫，以下載所有範例裝置程式碼、設定指令碼和 SDK 文件。如果您先前複製過此存放庫，就不需要再複製一次。

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

git clone --recursive  https://github.com/Azure-Samples/iot-middleware-freertos-samples.git

若是 Windows 10 和 11，請確定已啟用完整路徑。

若要啟用完整路徑，請參閱在 Windows 10 中啟用完整路徑。
在 git 中，在具有管理員權限的終端中執行下列命令：
```
git config --system core.longpaths true
```

建立雲端元件

建立 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

準備裝置

若要將 ESP32 DevKit 連線至 Azure，請修改組態設定、建置映像，並將該映像更新至裝置。

設定環境

若要啟動 ESP-IDF 環境：

選取 [Windows 開始]，尋找 ESP-IDF 5.0 CMD，然後加以執行。
在 ESP-IDF 5.0 CMD 中，瀏覽至您先前複製的 iot-middleware-freertos-samples 目錄。
瀏覽至 ESP32-Azure IoT 套件專案目錄 demos\projects\ESPRESSIF\aziotkit。
執行下列命令以啟動設定功能表：
```
idf.py menuconfig
```

新增設定

若要新增無線網路設定：

在 ESP-IDF 5.0 CMD 中，選取 [FreeRTOS 範例設定的 Azure IoT 中介軟體 --->]，然後按 Enter。
使用本機無線網路認證，以進行下列設定。

設定值

WiFi SSID {Wi-Fi SSID}

WiFi 密碼 {Wi-Fi 密碼}
選取 Esc 以返回上一個功能表。

設定	值
WiFi SSID	{Wi-Fi SSID}
WiFi 密碼	{Wi-Fi 密碼}

若要新增設定以連線至 Azure IoT 中樞：

選取 [FreeRTOS 主要工作設定的 Azure IoT 中介軟體 --->]，然後按 Enter。
將下列 Azure IoT 設定設為您在建立 Azure 資源後儲存的值。

設定值

Azure IoT 中樞 FQDN {主機名稱}

Azure IoT 裝置 ID {裝置識別碼}

Azure IoT 裝置對稱金鑰 {主要金鑰}

注意

在 [Azure IoT 驗證方法] 設定中，確認已選取 [對稱金鑰] 的預設值。
選取 Esc 以返回上一個功能表。

設定	值
Azure IoT 中樞 FQDN	{主機名稱}
Azure IoT 裝置 ID	{裝置識別碼}
Azure IoT 裝置對稱金鑰	{主要金鑰}

若要儲存設定：

選取 Shift+S 以開啟儲存選項。此功能表可讓您將設定儲存至目前 .\aziotkit 目錄中名為 skconfig 的檔案。
選取 Enter，即可儲存設定。
選取 Enter 即可關閉通知訊息。
選取 Q 以結束設定功能表。

建置並更新映像

您會在本節中使用 ESP-IDF 工具，以建置、快閃及監視 ESP32 DevKit，因為其會連線至 Azure IoT。

注意

在本節中的下列命令中，使用根目錄附近的簡短組建輸出路徑。在每個需要 -B 參數的命令中，於該參數後指定組建路徑。簡短路徑有助於避免 ESPRESSIF ESP-IDF 工具中目前的問題，即可能導致組建路徑名稱很長的錯誤。下列命令使用本機路徑 C：\espbuild 作為範例。

若要建置映像：

在 iot-middleware-freertos-samples\demos\projects\ESPRESSIF\aziotkit 目錄的 ESP-IDF 5.0 CMD 中，執行下列命令以建置映像。
```
idf.py --no-ccache -B "C:\espbuild" build 
```
建置完成之後，請確認已在您先前指定的組建路徑中建立二進位映像檔。

C:\espbuild\azure_iot_freertos_esp32.bin

若要快閃映像：

如下圖所示，在 ESP32 DevKit 上找出反白顯示的 Micro USB 連接埠：
將 Micro USB 纜線連接至 ESP32 DevKit 上的 Micro USB 連接埠，然後將其連線至電腦。
開啟 Windows 設備管理員，並檢視連接埠以找出 ESP32 DevKit 所連線的 COM 連接埠。
在 ESP-IDF 5.0 CMD 中執行下列命令，將 <Your-COM-port> 預留位置和括弧取代為上一步中的正確 COM 連接埠。例如，將預留位置取代為 COM3。
```
idf.py --no-ccache -B "C:\espbuild" -p <Your-COM-port> flash
```

確認輸出完成時會出現以下文字，表示快閃成功：

Hash of data verified

Leaving...
Hard resetting via RTS pin...
Done

若要確認裝置連線至 Azure IoT Central：

在 ESP-IDF 5.0 CMD 中，執行下列命令以啟動監視工具。如同您在上一個命令中的操作，請將 <Your-COM-port> 預留位置和括號取代為該裝置所連線的 COM 連接埠。
```
idf.py -B "C:\espbuild" -p <Your-COM-port> monitor
```

檢查是否有類似下列範例的重複輸出區塊。此輸出會確認裝置連線至 Azure IoT 並傳送遙測。

I (50807) AZ IOT: Successfully sent telemetry message
I (50807) AZ IOT: Attempt to receive publish message from IoT Hub.

I (51057) MQTT: Packet received. ReceivedBytes=2.
I (51057) MQTT: Ack packet deserialized with result: MQTTSuccess.
I (51057) MQTT: State record updated. New state=MQTTPublishDone.
I (51067) AZ IOT: Puback received for packet id: 0x00000008
I (53067) AZ IOT: Keeping Connection Idle...

檢視裝置屬性

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

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

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

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

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

定位字元	類型	姓名	描述
介面	介面	`Espressif ESP32 Azure IoT Kit`	ESP32 DevKit 的範例裝置模型
屬性 (可寫入)	屬性	`telemetryFrequencySecs`	裝置傳送遙測的間隔
命令	Command	`ToggleLed1`	開啟或關閉 LED
命令	Command	`ToggleLed2`	開啟或關閉 LED
命令	Command	`DisplayText`	在裝置畫面上顯示已傳送的文字

若要使用 Azure IoT 總管檢視和編輯裝置屬性：

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

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

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

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

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

提示

您也可以使用 Azure IoT 總管以檢視裝置屬性。在左側導覽中，選取 [裝置對應項]。

檢視遙測

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

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

從 IoT 總管中裝置的 [IoT 隨插即用元件] (預設元件) 窗格中，選取 [遙測] 索引標籤。確認使用內建事件中樞設定為是。
選取 [開始]。
當裝置將訊息傳送至雲端時，檢視遙測。
選取 [顯示模型化事件] 核取方塊，以裝置模型指定的資料格式檢視事件。
選取 [停止]，以結束接收事件。

若要使用 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:azureiot:devkit:freertos:Esp32AzureIotKit;1",
        "component": "",
        "payload": "{\"temperature\":28.6,\"humidity\":25.1,\"light\":116.66,\"pressure\":-33.69,\"altitude\":8764.9,\"magnetometerX\":1627,\"magnetometerY\":28373,\"magnetometerZ\":4232,\"pitch\":6,\"roll\":0,\"accelerometerX\":-1,\"accelerometerY\":0,\"accelerometerZ\":9}"
    }
}

選取 CTRL+C 來結束監視。

在裝置上呼叫直接方法

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

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

從 IoT 總管中裝置的 [IoT 隨插即用元件] (預設元件) 窗格中，選取 [命令] 索引標籤。
針對 ToggleLed1 命令，選取 [傳送] 命令。 ESP32 DevKit 上的 LED 會開啟或關閉。您也應該會在 IoT 總管中看到通知。
針對 DisplayText 命令，在 [內容] 欄位中輸入一些文字。
選取 [傳送命令]。此文字會顯示在 ESP32 DevKit 畫面上。

若要使用 Azure CLI 呼叫方法：

執行 az iot hub invoke-device-method 命令，並指定方法名稱和承載。針對此方法，將 method-payload 設為 true 表示 LED 會切換至與其目前狀態相反的狀態。
```
az iot hub invoke-device-method --device-id mydevice --method-name ToggleLed2 --method-payload true --hub-name {YourIoTHubName}
```
CLI 主控台會顯示裝置上方法呼叫的狀態，其中 200 表示成功。
```
{
  "payload": {},
  "status": 200
} 
```
請檢查裝置以確認 LED 狀態。

疑難排解和偵錯

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

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

清除資源

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

重要

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

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

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

下一步

在本教學課程中，您已建置自定義映像，其中包含適用於FreeRTOS的 Azure IoT 中間件範例程式代碼，然後將映像刷新至 ESP32 DevKit 裝置。您已將 ESP32 DevKit 連線至 Azure IoT 中樞，並執行在裝置上檢視遙測和呼叫方法等工作。

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

深入了解如何使用 C SDK 和內嵌 C SDK 連線內嵌裝置

共用方式為