教學課程：連線 在 Linux 或 Windows 上執行的多個元件裝置應用程式 IoT 隨插即用，以 IoT 中樞

  • 發行項

本教學課程說明如何使用元件建置範例 IoT 隨插即用 裝置應用程式、將其連線至IoT中樞，以及使用 Azure IoT 總管工具來檢視傳送至中樞的資訊。 範例應用程式是以 C 撰寫，並包含在適用於 C 的 Azure IoT 裝置 SDK 中。解決方案建置者可以使用 Azure IoT 總管工具來瞭解 IoT 隨插即用 裝置的功能，而不需要檢視任何裝置程式代碼。

瀏覽程式碼

在本教學課程中，您已：

  • 下載範例程序代碼。
  • 建置範例程序代碼。
  • 執行範例裝置應用程式，並驗證它是否連線到您的IoT中樞。
  • 檢閱原始碼。

必要條件

繼續之前，請確定您已 設定環境，包括IoT中樞。

您可以在 Linux 或 Windows 上完成本教學課程。 本教學課程中的殼層命令會遵循路徑分隔符 『/』的 Linux 慣例，如果您遵循 Windows 上的命令，請務必將這些分隔符交換為 『\』。

必要條件與作業系統不同：

Linux

本教學課程假設您使用UbuntuLinux。 本教學課程中的步驟已使用Ubuntu18.04進行測試。

若要在Linux上完成本教學課程，請在本機Linux環境中安裝下列軟體：

使用 命令安裝 GCC、 Git、 cmake 和所有必要的相依 apt-get 性：

sudo apt-get update
sudo apt-get install -y git cmake build-essential curl libcurl4-openssl-dev libssl-dev uuid-dev

確認的版本cmake高於 2.8.12，且 GCC 的版本高於 4.4.7。

cmake --version
gcc --version

Windows

若要在 Windows 上完成本教學課程，請在本機 Windows 環境中安裝下列軟體：

下載程式碼

如果您已完成教學課程：連線 在 Linux 或 Windows 上執行的範例 IoT 隨插即用 裝置應用程式，以下載程式代碼 IoT 中樞 （C）。

在本教學課程中，您會準備可用來複製和建置 Azure IoT 中樞 裝置 C SDK 的開發環境。

在您選擇的資料夾開啟命令提示字元。 執行下列命令， 將 Azure IoT C SDK 和連結庫 GitHub 存放庫 複製到此位置：

git clone https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

預期此作業需要幾分鐘的時間才能完成。

建置並執行程序代碼

您可以使用 Visual Studio 或在 cmake 命令行建置和執行程式碼。

使用 Visual Studio

  1. 開啟複製存放庫的根資料夾。 在幾秒鐘之後， Visual Studio 中的 CMake 支援會建立執行和偵錯專案所需的所有專案。

  2. 當 Visual Studio 就緒時，在 方案總管 中，流覽至範例 iothub_client/samples/pnp/pnp_temperature_controller/。

  3. 以滑鼠右鍵按兩下 pnp_temperature_controller.c 檔案，然後選取 [ 新增偵錯組態]。 選取 [預設值]。

  4. Visual Studio 會 開啟launch.vs.json 檔案。 編輯此檔案，如下列代碼段所示，以設定必要的環境變數。 當您完成為 IoT 隨插即用 快速入門和教學課程設定環境時，請記下範圍標識元和註冊主鍵：

    {
  "version": "0.2.1",
  "defaults": {},
  "configurations": [
    {
      "type": "default",
      "project": "iothub_client\\samples\\pnp\\pnp_temperature_controller\\pnp_temperature_controller.c",
      "projectTarget": "",
      "name": "pnp_temperature_controller.c",
      "env": {
        "IOTHUB_DEVICE_SECURITY_TYPE": "DPS",
        "IOTHUB_DEVICE_DPS_ID_SCOPE": "<Your ID scope>",
        "IOTHUB_DEVICE_DPS_DEVICE_ID": "my-pnp-device",
        "IOTHUB_DEVICE_DPS_DEVICE_KEY": "<Your enrollment primary key>"
      }
    }
  ]
}

  5. 以滑鼠右鍵按兩下 pnp_temperature_controller.c 檔案，然後選取 [ 設定為啟始專案]。

  6. 若要追蹤 Visual Studio 中的程式碼執行，請將斷點新增至 main pnp_temperature_controller.c 檔案中的 函式。

  7. 您現在可以從 [ 偵 錯] 功能表執行和偵錯範例。

裝置現在已準備好接收命令和屬性更新，並開始將遙測數據傳送至中樞。 當您完成後續步驟時，請讓範例保持執行。

在命令行使用cmake

若要建置範例：

  1. 在複製裝置 SDK 的根資料夾中建立 cmake 子資料夾，並瀏覽至該資料夾：

    cd azure-iot-sdk-c
mkdir cmake
cd cmake

  2. 執行下列命令來產生及建置 SDK 和範例的項目檔：

    cmake ..
cmake --build .

在 [設定您的環境] 中，您已建立四個環境變數來設定範例，以使用裝置布建服務 （DPS） 連線到 IoT 中樞：

  • 具有 值的IOTHUB_DEVICE_SECURITY_TYPEDPS
  • 具有 DPS 識別碼範圍的IOTHUB_DEVICE_DPS_ID_SCOPE 。
  • IOTHUB_DEVICE_DPS_DEVICE_ID 值 my-pnp-device。
  • 使用註冊主鍵IOTHUB_DEVICE_DPS_DEVICE_KEY。
  • IOTHUB_DEVICE_DPS_ENDPOINT 值 global.azure-devices-provisioning.net。

若要深入瞭解範例組態，請參閱 範例自述檔。

若要執行範例：

  1. 從 cmake 資料夾，瀏覽至包含可執行檔案的資料夾，然後執行它：

    # Bash
cd iothub_client/samples/pnp/pnp_temperature_controller
./pnp_temperature_controller

    REM Windows
cd iothub_client\samples\pnp\pnp_temperature_controller\Debug
pnp_temperature_controller.exe

裝置現在已準備好接收命令和屬性更新，並開始將遙測數據傳送至中樞。 當您完成後續步驟時，請讓範例保持執行。

使用 Azure IoT 總管來驗證程式代碼

裝置用戶端範例啟動之後，請使用 Azure IoT 總管工具來確認其運作正常。

  1. 開啟 Azure IoT 總管。

  2. 在 [ IoT 中樞] 頁面上，如果您尚未將連線新增至 IoT 中樞，請選取 [+ 新增連線]。 輸入您先前建立的IoT中樞 連接字串，然後選取 [儲存]。

  3. 在 [IoT 隨插即用 設定] 頁面上，選取 [+ 新增>本機] 資料夾，然後選取您儲存模型檔案的本機 models 資料夾。

  4. 在 [ IoT 中樞] 頁面上，按下您要使用中樞的名稱。 您會看到已註冊至IoT中樞的裝置清單。

  5. 按兩下 您先前建立之裝置的 [裝置 標識符]。

  6. 左側功能表會顯示適用於裝置的不同信息類型。

  7. 選取 IoT 隨插即用元件，以檢視裝置的模型資訊。

  8. 您可以檢視裝置的不同元件。 默認元件和任何額外的元件。 選取要使用的元件。

  9. 選取 [ 遙測 ] 頁面，然後選取 [ 開始 ] 以檢視裝置為此元件傳送的遙測數據。

  10. 選取 [ 屬性] [只讀] 頁面，以檢視針對此元件報告的只讀屬性。

  11. 選取 [ 屬性] 頁面，以檢視您可以為此元件更新的可寫入 屬性。

  12. 依其 名稱選取屬性、輸入新值，然後選取 [ 更新所需的值]。

  13. 若要查看新的值，請選取 [ 重新 整理] 按鈕。

  14. 選取 [ 命令] 頁面以檢視此元件的所有命令。

  15. 選取您想要測試的命令，如果有的話，請設定 參數。 選取 [ 傳送] 命令 以呼叫裝置上的命令。 您可以在執行範例程式代碼的命令提示字元視窗中看到您的裝置回應命令。

檢閱程式碼

此範例會實作 IoT 隨插即用 溫度控制器裝置。 此範例會實作具有 多個元件的模型。 溫度裝置的數字對應項定義語言 （DTDL） V2 模型檔案會定義裝置所實作的遙測、屬性和命令。

IoT 隨插即用 協助程式函式

在這裡範例中，程式代碼會使用 /common 資料夾中的一些協助程式函式：

pnp_device_client_ll包含 IoT 隨插即用 的 connect 方法，並model-id隨附為 參數：PnP_CreateDeviceClientLLHandle。

pnp_protocol：包含 IoT 隨插即用 協助程式函式：

  • PnP_CreateReportedProperty
  • PnP_CreateReportedPropertyWithStatus
  • PnP_ParseCommandName
  • PnP_CreateTelemetryMessageHandle
  • PnP_ProcessTwinData
  • PnP_CopyPayloadToString
  • PnP_CreateDeviceClientLLHandle_ViaDps

這些協助程式函式很泛型，足以在您自己的專案中使用。 此範例會在對應至模型中每個元件的三個檔案中使用它們：

  • pnp_deviceinfo_component
  • pnp_temperature_controller
  • pnp_thermostat_component

例如，在pnp_deviceinfo_component檔案中，函SendReportedPropertyForDeviceInformation式會使用兩個協助程式函式：

if ((jsonToSend = PnP_CreateReportedProperty(componentName, propertyName, propertyValue)) == NULL)
{
    LogError("Unable to build reported property response for propertyName=%s, propertyValue=%s", propertyName, propertyValue);
}
else
{
    const char* jsonToSendStr = STRING_c_str(jsonToSend);
    size_t jsonToSendStrLen = strlen(jsonToSendStr);

    if ((iothubClientResult = IoTHubDeviceClient_LL_SendReportedState(deviceClientLL, (const unsigned char*)jsonToSendStr, jsonToSendStrLen, NULL, NULL)) != IOTHUB_CLIENT_OK)
    {
        LogError("Unable to send reported state for property=%s, error=%d", propertyName, iothubClientResult);
    }
    else
    {
        LogInfo("Sending device information property to IoTHub.  propertyName=%s, propertyValue=%s", propertyName, propertyValue);
    }
}

範例中的每個元件都遵循此模式。

程序代碼流程

函 main 式會初始化連接，並傳送模型識別碼：

deviceClient = CreateDeviceClientAndAllocateComponents();

程式代碼會使用 PnP_CreateDeviceClientLLHandle 連線到IoT中樞、設定 modelId 為選項，以及設定直接方法和裝置對應項更新的裝置方法和裝置對應項回呼處理程式：

g_pnpDeviceConfiguration.deviceMethodCallback = PnP_TempControlComponent_DeviceMethodCallback;
g_pnpDeviceConfiguration.deviceTwinCallback = PnP_TempControlComponent_DeviceTwinCallback;
g_pnpDeviceConfiguration.modelId = g_temperatureControllerModelId;
...

deviceClient = PnP_CreateDeviceClientLLHandle(&g_pnpDeviceConfiguration);

&g_pnpDeviceConfiguration 也包含連接資訊。 環境變數IOTHUB_DEVICE_SECURITY_TYPE會決定範例使用 連接字串 或裝置布建服務來連線到IoT中樞。

當裝置傳送模型標識碼時，它就會變成 IoT 隨插即用 裝置。

在回呼處理程式就緒后，裝置會響應對應項更新和直接方法呼叫：

  • 針對裝置對應項回呼，會 PnP_TempControlComponent_DeviceTwinCallback 呼叫 PnP_ProcessTwinData 函式來處理數據。 PnP_ProcessTwinData會使用訪客模式來剖析 JSON，然後造訪每個屬性，並在每個元素上呼叫 PnP_TempControlComponent_ApplicationPropertyCallback 。

  • 針對命令回呼，函 PnP_TempControlComponent_DeviceMethodCallback 式會使用協助程式函式來剖析命令和元件名稱：

    PnP_ParseCommandName(methodName, &componentName, &componentNameSize, &pnpCommandName);

    函式 PnP_TempControlComponent_DeviceMethodCallback 接著會在元件上呼叫 命令：

    LogInfo("Received PnP command for component=%.*s, command=%s", (int)componentNameSize, componentName, pnpCommandName);
if (strncmp((const char*)componentName, g_thermostatComponent1Name, g_thermostatComponent1Size) == 0)
{
    result = PnP_ThermostatComponent_ProcessCommand(g_thermostatHandle1, pnpCommandName, rootValue, response, responseSize);
}
else if (strncmp((const char*)componentName, g_thermostatComponent2Name, g_thermostatComponent2Size) == 0)
{
    result = PnP_ThermostatComponent_ProcessCommand(g_thermostatHandle2, pnpCommandName, rootValue, response, responseSize);
}
else
{
    LogError("PnP component=%.*s is not supported by TemperatureController", (int)componentNameSize, componentName);
    result = PNP_STATUS_NOT_FOUND;
}

函 main 式會初始化傳送至 IoT 中樞的唯讀屬性：

PnP_TempControlComponent_ReportSerialNumber_Property(deviceClient);
PnP_DeviceInfoComponent_Report_All_Properties(g_deviceInfoComponentName, deviceClient);
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle1, deviceClient);
PnP_TempControlComponent_Report_MaxTempSinceLastReboot_Property(g_thermostatHandle2, deviceClient);

函 main 式會輸入循環來更新每個元件的事件和遙測資料：

while (true)
{
    PnP_TempControlComponent_SendWorkingSet(deviceClient);
    PnP_ThermostatComponent_SendTelemetry(g_thermostatHandle1, deviceClient);
    PnP_ThermostatComponent_SendTelemetry(g_thermostatHandle2, deviceClient);
}

函 PnP_ThermostatComponent_SendTelemetry 式會示範如何使用 PNP_THERMOSTAT_COMPONENT 結構。 此範例會使用此結構，將兩個控溫器的相關信息儲存在溫度控制器中。 程式代碼會使用 PnP_CreateTelemetryMessageHandle 函式來準備訊息並傳送：

messageHandle = PnP_CreateTelemetryMessageHandle(pnpThermostatComponent->componentName, temperatureStringBuffer);
...
iothubResult = IoTHubDeviceClient_LL_SendEventAsync(deviceClientLL, messageHandle, NULL, NULL);

函 main 式最後會終結不同的元件，並關閉與中樞的連線。

本教學課程說明如何使用元件建置範例 IoT 隨插即用 裝置應用程式、將其連線至IoT中樞，以及使用 Azure IoT 總管工具來檢視傳送至中樞的資訊。 範例應用程式是以 C# 撰寫，並包含在適用於 C# 的 Azure IoT 裝置 SDK 中。 解決方案產生器可以使用 Azure IoT 總管工具來瞭解 IoT 隨插即用 裝置的功能，而不需要檢視任何裝置程式代碼。

瀏覽程式碼

在本教學課程中，您已：

  • 下載範例程序代碼。
  • 建置範例程序代碼。
  • 執行範例裝置應用程式，並驗證它是否連線到您的IoT中樞。
  • 檢閱原始碼。

必要條件

繼續之前，請確定您已 設定環境，包括IoT中樞。

您可以在 Linux 或 Windows 上執行本教學課程。 本教學課程中的殼層命令會遵循路徑分隔符 『/』的 Linux 慣例，如果您遵循 Windows 上的命令，請務必將這些分隔符交換為 『\』。

使用範例程式代碼複製 SDK 存放庫

如果您已完成教學課程：連線 在 Windows 上執行的範例 IoT 隨插即用 裝置應用程式，以 IoT 中樞 （C#），則您已經複製存放庫。

從適用於 C# 的 Azure IoT 範例 GitHub 存放庫複製範例。 在您選擇的資料夾開啟命令提示字元。 執行下列命令以複製 Microsoft Azure IoT SDK for .NET GitHub 存放庫：

git clone https://github.com/Azure/azure-iot-sdk-csharp.git

建置程式碼

您現在可以建置範例並加以執行。 執行下列命令來建置範例：

cd azure-iot-sdk-csharp/iothub/device/samples/solutions/PnpDeviceSamples/TemperatureController
dotnet build

執行裝置範例

若要執行範例，請執行下列命令：

dotnet run

裝置現在已準備好接收命令和屬性更新，並開始將遙測數據傳送至中樞。 當您完成後續步驟時，請讓範例保持執行。

使用 Azure IoT 總管來驗證程式代碼

裝置用戶端範例啟動之後，請使用 Azure IoT 總管工具來確認其運作正常。

  1. 開啟 Azure IoT 總管。

  2. 在 [ IoT 中樞] 頁面上，如果您尚未將連線新增至 IoT 中樞，請選取 [+ 新增連線]。 輸入您先前建立的IoT中樞 連接字串，然後選取 [儲存]。

  3. 在 [IoT 隨插即用 設定] 頁面上，選取 [+ 新增>本機] 資料夾，然後選取您儲存模型檔案的本機 models 資料夾。

  4. 在 [ IoT 中樞] 頁面上，按下您要使用中樞的名稱。 您會看到已註冊至IoT中樞的裝置清單。

  5. 按兩下 您先前建立之裝置的 [裝置 標識符]。

  6. 左側功能表會顯示適用於裝置的不同信息類型。

  7. 選取 [IoT 隨插即用元件] 以檢視裝置的模型資訊。

  8. 您可以檢視裝置的不同元件。 默認元件和任何額外的元件。 選取要使用的元件。

  9. 選取 [ 遙測 ] 頁面，然後選取 [ 開始 ] 以檢視裝置為此元件傳送的遙測數據。

  10. 選取 [ 屬性] [只讀] 頁面，以檢視針對此元件報告的只讀屬性。

  11. 選取 [ 屬性] 頁面，以檢視您可以為此元件更新的可寫入 屬性。

  12. 依其 名稱選取屬性、輸入新值，然後選取 [ 更新所需的值]。

  13. 若要查看新的值，請選取 [ 重新 整理] 按鈕。

  14. 選取 [ 命令] 頁面以檢視此元件的所有命令。

  15. 選取您想要測試的命令，如果有的話，請設定 參數。 選取 [ 傳送] 命令 以呼叫裝置上的命令。 您可以在執行範例程式代碼的命令提示字元視窗中看到您的裝置回應命令。

檢閱程式碼

此範例會實作 IoT 隨插即用 溫度控制器裝置。 此範例實作的模型會使用 多個元件。 溫度裝置的數字對應項定義語言 （DTDL） V2 模型檔案會定義裝置所實作的遙測、屬性和命令。

裝置程式代碼會使用標準 CreateFromConnectionString 方法連線到IoT中樞。 裝置會傳送它在連線要求中實作之 DTDL 模型的模型標識碼。 傳送模型標識碼的裝置是 IoT 隨插即用 裝置：

private static DeviceClient InitializeDeviceClient(string hostname, IAuthenticationMethod authenticationMethod)
{
    var options = new ClientOptions
    {
        ModelId = ModelId,
    };

    var deviceClient = DeviceClient.Create(hostname, authenticationMethod, TransportType.Mqtt, options);
    deviceClient.SetConnectionStatusChangesHandler((status, reason) =>
    {
        s_logger.LogDebug($"Connection status change registered - status={status}, reason={reason}.");
    });

    return deviceClient;
}

模型標識符會儲存在程序代碼中，如下列代碼段所示：

private const string ModelId = "dtmi:com:example:TemperatureController;1";

裝置連線到IoT中樞之後，程式代碼會註冊命令處理程式。 命令 reboot 定義於預設元件中。 getMaxMinReport命令定義於兩個控溫器元件中：

await _deviceClient.SetMethodHandlerAsync("reboot", HandleRebootCommandAsync, _deviceClient, cancellationToken);
await _deviceClient.SetMethodHandlerAsync("thermostat1*getMaxMinReport", HandleMaxMinReportCommandAsync, Thermostat1, cancellationToken);
await _deviceClient.SetMethodHandlerAsync("thermostat2*getMaxMinReport", HandleMaxMinReportCommandAsync, Thermostat2, cancellationToken);

兩個控溫器元件上所需屬性更新有個別的處理程式：

_desiredPropertyUpdateCallbacks.Add(Thermostat1, TargetTemperatureUpdateCallbackAsync);
_desiredPropertyUpdateCallbacks.Add(Thermostat2, TargetTemperatureUpdateCallbackAsync);

範例程式代碼會從每個控溫器元件傳送遙測：

await SendTemperatureAsync(Thermostat1, cancellationToken);
await SendTemperatureAsync(Thermostat2, cancellationToken);

方法 SendTemperatureTelemetryAsync 會 PnpHhelper 使用 類別來建立每個元件的訊息：

using Message msg = PnpHelper.CreateIothubMessageUtf8(telemetryName, JsonConvert.SerializeObject(currentTemperature), componentName);

類別 PnpHelper 包含您可以搭配多個元件模型使用的其他範例方法。

使用 Azure IoT 總管工具來檢視來自兩個控溫器元件的遙測和屬性：

Azure IoT 總管中的多個元件裝置

您也可以使用 Azure IoT 總管工具，在兩個控溫器元件或預設元件中呼叫命令。

本教學課程說明如何使用元件建置範例 IoT 隨插即用 裝置應用程式、將其連線至IoT中樞，以及使用 Azure IoT 總管工具來檢視傳送至中樞的資訊。 範例應用程式是以 Java 撰寫，並包含在適用於 Java 的 Azure IoT 裝置 SDK 中。 解決方案建置者可以使用 Azure IoT 總管工具來瞭解 IoT 隨插即用 裝置的功能，而不需要檢視任何裝置程式代碼。

瀏覽程式碼

在本教學課程中，您已：

  • 下載範例程序代碼。
  • 建置範例程序代碼。
  • 執行範例裝置應用程式，並驗證它是否連線到您的IoT中樞。
  • 檢閱原始碼。

必要條件

繼續之前，請確定您已 設定環境，包括IoT中樞。

您可以在 Linux 或 Windows 上執行本教學課程。 本教學課程中的殼層命令會遵循路徑分隔符 『/』的 Linux 慣例，如果您遵循 Windows 上的命令，請務必將這些分隔符交換為 『\』。

若要完成本教學課程，請在本機開發環境中安裝下列軟體：

下載程式碼

如果您已完成教學課程：連線 範例 IoT 隨插即用 裝置應用程式來 IoT 中樞 （Java），則您已經複製存放庫。

在您選擇的目錄中開啟命令提示字元。 執行下列命令，將 Azure IoT Java SDK 和連結庫 GitHub 存放庫 複製到此位置：

git clone https://github.com/Azure/azure-iot-sdk-java.git

預期此作業需要幾分鐘的時間才能完成。

建置程式碼

瀏覽至複製 Java SDK 存放庫中溫度控制器範例的根資料夾，並加以建置：

cd azure-iot-sdk-java/device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample
mvn clean package

執行裝置範例

在 [設定您的環境] 中，您已建立四個環境變數來設定範例，以使用裝置布建服務 （DPS） 連線到 IoT 中樞：

  • 具有 值的IOTHUB_DEVICE_SECURITY_TYPEDPS
  • 具有 DPS 識別碼範圍的IOTHUB_DEVICE_DPS_ID_SCOPE 。
  • IOTHUB_DEVICE_DPS_DEVICE_ID 值 my-pnp-device。
  • 使用註冊主鍵IOTHUB_DEVICE_DPS_DEVICE_KEY。
  • IOTHUB_DEVICE_DPS_ENDPOINT 值 global.azure-devices-provisioning.net。

若要執行範例應用程式，請流覽至 /device/iot-device-samples/pnp-device-sample/temperature-controller-device-sample 資料夾，然後執行下列命令：

mvn exec:java -Dexec.mainClass="samples.com.microsoft.azure.sdk.iot.device.TemperatureController"

裝置現在已準備好接收命令和屬性更新，並開始將遙測數據傳送至中樞。 當您完成後續步驟時，請讓範例保持執行。

使用 Azure IoT 總管來驗證程式代碼

裝置用戶端範例啟動之後，請使用 Azure IoT 總管工具來確認其運作正常。

  1. 開啟 Azure IoT 總管。

  2. 在 [ IoT 中樞] 頁面上，如果您尚未將連線新增至 IoT 中樞，請選取 [+ 新增連線]。 輸入您先前建立的IoT中樞 連接字串，然後選取 [儲存]。

  3. 在 [IoT 隨插即用 設定] 頁面上，選取 [+ 新增>本機] 資料夾，然後選取您儲存模型檔案的本機 models 資料夾。

  4. 在 [ IoT 中樞] 頁面上，按下您要使用中樞的名稱。 您會看到已註冊至IoT中樞的裝置清單。

  5. 按兩下 您先前建立之裝置的 [裝置 標識符]。

  6. 左側功能表會顯示適用於裝置的不同信息類型。

  7. 選取 [IoT 隨插即用元件] 以檢視裝置的模型資訊。

  8. 您可以檢視裝置的不同元件。 默認元件和任何額外的元件。 選取要使用的元件。

  9. 選取 [ 遙測 ] 頁面，然後選取 [ 開始 ] 以檢視裝置為此元件傳送的遙測數據。

  10. 選取 [ 屬性] [只讀] 頁面，以檢視針對此元件報告的只讀屬性。

  11. 選取 [ 屬性] 頁面，以檢視您可以為此元件更新的可寫入 屬性。

  12. 依其 名稱選取屬性、輸入新值，然後選取 [ 更新所需的值]。

  13. 若要查看新的值，請選取 [ 重新 整理] 按鈕。

  14. 選取 [ 命令] 頁面以檢視此元件的所有命令。

  15. 選取您想要測試的命令，如果有的話，請設定 參數。 選取 [ 傳送] 命令 以呼叫裝置上的命令。 您可以在執行範例程式代碼的命令提示字元視窗中看到您的裝置回應命令。

檢閱程式碼

此範例會實作 IoT 隨插即用 溫度控制器裝置。 此範例實作的模型會使用 多個元件。 溫度裝置的數字對應項定義語言 （DTDL） V2 模型檔案會定義裝置所實作的遙測、屬性和命令。

裝置程式代碼會使用標準 DeviceClient 類別來連線到IoT中樞。 裝置會傳送它在連線要求中實作之 DTDL 模型的模型標識碼。 傳送模型標識碼的裝置是 IoT 隨插即用 裝置：

private static void initializeDeviceClient() throws URISyntaxException, IOException {
    ClientOptions options = new ClientOptions();
    options.setModelId(MODEL_ID);
    deviceClient = new DeviceClient(deviceConnectionString, protocol, options);

    deviceClient.registerConnectionStatusChangeCallback((status, statusChangeReason, throwable, callbackContext) -> {
        log.debug("Connection status change registered: status={}, reason={}", status, statusChangeReason);

        if (throwable != null) {
            log.debug("The connection status change was caused by the following Throwable: {}", throwable.getMessage());
            throwable.printStackTrace();
        }
    }, deviceClient);

    deviceClient.open();
}

模型標識符會儲存在程序代碼中，如下列代碼段所示：

private static final String MODEL_ID = "dtmi:com:example:Thermostat;1";

裝置連線到IoT中樞之後，程式代碼會註冊命令處理程式。

deviceClient.subscribeToDeviceMethod(new MethodCallback(), null, new MethodIotHubEventCallback(), null);

兩個控溫器元件上所需屬性更新有個別的處理程式：

deviceClient.startDeviceTwin(new TwinIotHubEventCallback(), null, new GenericPropertyUpdateCallback(), null);
Map<Property, Pair<TwinPropertyCallBack, Object>> desiredPropertyUpdateCallback = Stream.of(
        new AbstractMap.SimpleEntry<Property, Pair<TwinPropertyCallBack, Object>>(
                new Property(THERMOSTAT_1, null),
                new Pair<>(new TargetTemperatureUpdateCallback(), THERMOSTAT_1)),
        new AbstractMap.SimpleEntry<Property, Pair<TwinPropertyCallBack, Object>>(
                new Property(THERMOSTAT_2, null),
                new Pair<>(new TargetTemperatureUpdateCallback(), THERMOSTAT_2))
).collect(Collectors.toMap(AbstractMap.SimpleEntry::getKey, AbstractMap.SimpleEntry::getValue));

deviceClient.subscribeToTwinDesiredProperties(desiredPropertyUpdateCallback);

範例程式代碼會從每個控溫器元件傳送遙測：

sendTemperatureReading(THERMOSTAT_1);
sendTemperatureReading(THERMOSTAT_2);

方法 sendTemperatureReading 會 PnpHhelper 使用 類別來建立每個元件的訊息：

Message message = PnpHelper.createIotHubMessageUtf8(telemetryName, currentTemperature, componentName);

類別 PnpHelper 包含您可以搭配多個元件模型使用的其他範例方法。

使用 Azure IoT 總管工具來檢視來自兩個控溫器元件的遙測和屬性：

Azure IoT 總管中的多個元件裝置

您也可以使用 Azure IoT 總管工具，在兩個控溫器元件或預設元件中呼叫命令。

本教學課程說明如何使用元件建置範例 IoT 隨插即用 裝置應用程式、將其連線到IoT中樞，以及使用 Azure IoT 總管工具來檢視傳送至中樞的資訊。 範例應用程式會針對 Node.js 撰寫，並包含在適用於 Node.js的 Azure IoT 中樞 Device SDK 中。 解決方案建置者可以使用 Azure IoT 總管工具來瞭解 IoT 隨插即用 裝置的功能，而不需要檢視任何裝置程式代碼。

瀏覽程式碼

在本教學課程中，您已：

  • 下載範例程序代碼。
  • 執行範例裝置應用程式，並驗證它是否連線到您的IoT中樞。
  • 檢閱原始碼。

必要條件

繼續之前，請確定您已 設定環境，包括IoT中樞。

若要完成本教學課程，您需要在開發計算機上Node.js。 您可以從 nodejs.org 下載多個平臺的最新建議版本。

您可以使用下列命令，在開發電腦上驗證目前版本的Node.js：

node --version

下載程式碼

如果您已完成教學課程：連線 在 Windows 上執行的範例 IoT 隨插即用 裝置應用程式，以 IoT 中樞 （Node），則您已經複製存放庫。

在您選擇的目錄中開啟命令提示字元。 執行下列命令，將適用於 Node.js GitHub 存放庫的 Microsoft Azure IoT SDK 複製到此位置：

git clone https://github.com/Azure/azure-iot-sdk-node

安裝必要的連結庫

您可以使用裝置 SDK 來建置包含的範例程式代碼。 您建置的應用程式會模擬具有多個連線到 IoT 中樞的多個元件 隨插即用 裝置。 應用程式會傳送遙測和屬性，並接收命令。

  1. 在本機終端機視窗中，移至您複製存放庫的資料夾，並流覽至 /azure-iot-sdk-node/device/samples/javascript 資料夾。 然後執行下列命令以安裝必要的連結庫：
npm install

此命令會安裝執行資料夾中範例所需的相關 npm 檔案。

檢閱程式碼

流覽至 azure-iot-sdk-node/device/samples/javascript 資料夾。

azure-iot-sdk-node/device/samples/javascript 資料夾包含 IoT 隨插即用 溫度控制器裝置的範例程序代碼。

pnp_temperature_controller.js檔案中的程式代碼會實作 IoT 隨插即用 溫度控制器裝置。 此範例實作的模型會使用 多個元件。 溫度裝置的數字對應項定義語言 （DTDL） V2 模型檔案會定義裝置所實作的遙測、屬性和命令。

在 您選擇的程式代碼編輯器中開啟pnp_temperature_controller.js 檔案。 範例程式代碼示範如何：

  • modelId定義您要實作之裝置的 DTMI。 此 DTMI 是使用者定義的，必須符合溫度控制器 DTDL 模型的 DTMI。

  • 實作溫度控制器 DTDL 模型中定義的元件。 實際溫度控制器中的元件應該實作這兩個介面。 這兩個介面已在中央存放庫中發佈。 在此範例中，兩個介面為：

    • 控溫器
    • Azure 開發的裝置資訊

  • 定義元件名稱。 此範例有兩個控溫器和一個裝置資訊元件。

  • 定義裝置回應之命令的命令名稱。

  • serialNumber定義常數。 已 serialNumber 修正任何指定的裝置。

  • 定義命令處理程式。

  • 定義要傳送命令回應的函式。

  • 定義協助程式函式來記錄命令要求。

  • 定義協助程式函式以建立屬性。

  • 定義屬性更新的接聽程式。

  • 定義函式以從此裝置傳送遙測。 控溫器和預設元件都會傳送遙測。 此函式會以參數的形式接收元件名稱。

  • 定義可 main ：

    • 使用裝置 SDK 來建立裝置用戶端，並連線到 IoT 中樞。 裝置會modelId提供 ，讓 IoT 中樞 可以將裝置識別為 IoT 隨插即用 裝置。

    • 使用 onDeviceMethod 函式開始接聽命令要求。 函式會設定來自服務的命令要求的接聽程式：

      • 裝置 DTDL 會 reboot 定義和 getMaxMinReport 命令。
      • 函 commandHandler 式會定義裝置如何回應命令。

    • 使用和 sendTelemetry開始傳送遙測setInterval。

    • 使用函式 helperCreateReportedPropertiesPatch 來建立屬性和 updateComponentReportedProperties 來更新屬性。

    • 使用 desiredPropertyPatchListener 來接聽屬性更新。

    • 停用所有接聽程式和工作，並在按下 Q 或 q 時結束迴圈。

在 [設定您的環境] 中，您已建立四個環境變數來設定範例，以使用裝置布建服務 （DPS） 連線到 IoT 中樞：

  • 具有 值的IOTHUB_DEVICE_SECURITY_TYPEDPS
  • 具有 DPS 識別碼範圍的IOTHUB_DEVICE_DPS_ID_SCOPE 。
  • IOTHUB_DEVICE_DPS_DEVICE_ID 值 my-pnp-device。
  • 使用註冊主鍵IOTHUB_DEVICE_DPS_DEVICE_KEY。
  • IOTHUB_DEVICE_DPS_ENDPOINT 值 global.azure-devices-provisioning.net。

若要深入瞭解範例組態，請參閱 範例自述檔。

既然您已看到程式代碼，請使用下列命令來執行範例：

node pnp_temperature_controller.js

您會看到下列輸出，指出裝置已開始將遙測數據傳送至中樞，現在已準備好接收命令和屬性更新。

裝置確認訊息

當您完成後續步驟時，請讓範例保持執行。

使用 Azure IoT 總管來驗證程式代碼

裝置用戶端範例啟動之後，請使用 Azure IoT 總管工具來確認其運作正常。

  1. 開啟 Azure IoT 總管。

  2. 在 [ IoT 中樞] 頁面上，如果您尚未將連線新增至 IoT 中樞，請選取 [+ 新增連線]。 輸入您先前建立的IoT中樞 連接字串，然後選取 [儲存]。

  3. 在 [IoT 隨插即用 設定] 頁面上，選取 [+ 新增>本機] 資料夾，然後選取您儲存模型檔案的本機 models 資料夾。

  4. 在 [ IoT 中樞] 頁面上，按下您要使用中樞的名稱。 您會看到已註冊至IoT中樞的裝置清單。

  5. 按兩下 您先前建立之裝置的 [裝置 標識符]。

  6. 左側功能表會顯示適用於裝置的不同信息類型。

  7. 選取 IoT 隨插即用元件，以檢視裝置的模型資訊。

  8. 您可以檢視裝置的不同元件。 默認元件和任何額外的元件。 選取要使用的元件。

  9. 選取 [ 遙測 ] 頁面，然後選取 [ 開始 ] 以檢視裝置為此元件傳送的遙測數據。

  10. 選取 [ 屬性] [只讀] 頁面，以檢視針對此元件報告的只讀屬性。

  11. 選取 [ 屬性] 頁面，以檢視您可以為此元件更新的可寫入 屬性。

  12. 依其 名稱選取屬性、輸入新值，然後選取 [ 更新所需的值]。

  13. 若要查看新的值，請選取 [ 重新 整理] 按鈕。

  14. 選取 [ 命令] 頁面以檢視此元件的所有命令。

  15. 選取您想要測試的命令，如果有的話，請設定 參數。 選取 [ 傳送] 命令 以呼叫裝置上的命令。 您可以在執行範例程式代碼的命令提示字元視窗中看到您的裝置回應命令。

本教學課程說明如何使用元件建置範例 IoT 隨插即用 裝置應用程式、將其連線到IoT中樞，以及使用 Azure IoT 總管工具來檢視傳送至中樞的資訊。 範例應用程式是以 Python 撰寫，並包含在適用於 Python 的 Azure IoT 裝置 SDK 中。 解決方案產生器可以使用 Azure IoT 總管工具來瞭解 IoT 隨插即用 裝置的功能，而不需要檢視任何裝置程式代碼。

瀏覽程式碼

在本教學課程中，您已：

  • 下載範例程序代碼。
  • 執行範例裝置應用程式，並驗證它是否連線到您的IoT中樞。
  • 檢閱原始碼。

必要條件

繼續之前，請確定您已 設定環境，包括IoT中樞。

您可以在 Linux 或 Windows 上執行本教學課程。 本教學課程中的殼層命令會遵循路徑分隔符 『/』的 Linux 慣例，如果您遵循 Windows 上的命令，請務必將這些分隔符交換為 『\』。

若要完成本教學課程，您需要在開發計算機上安裝 Python。 請查看 Azure IoT Python SDK 以取得目前的 Python 版本需求。 您可以使用下列命令來檢查 Python 版本：

python --version

您可以從 python.org 下載多個平臺的最新建議版本。

下載程式碼

azure-iot-device 套件會發佈為 PIP。

在您的本機 Python 環境中，安裝套件，如下所示：

pip install azure-iot-device

如果您已完成教學課程：連線 在 Windows 上執行的範例 IoT 隨插即用 裝置應用程式來 IoT 中樞 （Python），則您已經複製存放庫。

複製 Python SDK IoT 存放庫：

git clone --branch v2 https://github.com/Azure/azure-iot-sdk-python

檢閱程式碼

此範例會實作 IoT 隨插即用 溫度控制器裝置。 此範例實作的模型會使用 多個元件。 溫度裝置的數字對應項定義語言 （DTDL） V2 模型檔案會定義裝置所實作的遙測、屬性和命令。

azure-iot-sdk-python/samples/pnp 資料夾包含 IoT 隨插即用 裝置的範例程序代碼。 溫度控制器範例的檔案如下：

  • temp_controller_with_thermostats.py
  • pnp_helper.py

溫度控制器有多個元件和預設元件，以溫度控制器 DTDL 模型為基礎。

在 您選擇的編輯器中開啟temp_controller_with_thermostats.py 檔案。 此檔案中的程式代碼：

  1. pnp_helper.py匯入 以取得協助程式方法的存取權。

  2. 定義兩個數字對應項模型標識碼 （DTMIs），以唯一表示 DTDL 模型中定義的兩個不同的介面。 實際溫度控制器中的元件應該實作這兩個介面。 這兩個介面已在中央存放庫中發佈。 用戶必須知道這些 DTMIs，並視裝置實作的案例而有所不同。 針對目前的範例，這兩個介面代表：

    • 控溫器
    • Azure 開發的裝置資訊。

  3. 定義所實作之裝置的 DTMI model_id 。 DTMI 是使用者定義的，必須符合 DTDL 模型檔案中的 DTMI。

  4. 定義 DTDL 檔案中元件指定的名稱。 DTDL 和一個裝置資訊元件中有兩個控溫器。 呼叫的常數 serial_number 也會定義於預設元件中。 serial_number無法變更裝置。

  5. 定義命令處理程序實作。 這些處理程式會定義裝置在收到命令要求時執行的動作。

  6. 定義函式以建立命令回應。 這些函式會定義裝置如何回應命令要求。 如果命令需要將自定義回應傳回IoT中樞，您可以建立命令回應函式。 如果未提供命令的回應函式，則會傳送泛型回應。 在此範例中 ，只有 getMaxMinReport 命令具有自定義回應。

  7. 定義從此裝置傳送遙測的函式。 控溫器和預設元件都會傳送遙測。 此函式具有選擇性的元件名稱參數，可讓它識別傳送遙測的元件。

  8. 定義命令要求的接聽程式。

  9. 定義所需屬性更新的接聽程式。

  10. 具有一個 main 函式，其為：

    • 使用裝置 SDK 來建立裝置用戶端，並連線到 IoT 中樞。 裝置會傳送 ，model_id讓IoT中樞可以將裝置識別為 IoT 隨插即用裝置。

    • 使用協助程式檔案中的函 create_reported_properties 式來建立屬性。 將元件名稱和屬性當做索引鍵值組傳遞至此函式。

    • 更新 其元件的可讀取屬性，方法是呼叫 patch_twin_reported_properties。

    • 使用 execute_command_listener 函式開始接聽命令要求。 函式會設定來自服務的命令要求的接聽程式。 當您設定接聽程式時，您會提供 method_name、 user_command_handler和選擇性 create_user_response_handler 做為參數。

      • method_name會定義命令要求。 在此範例中，模型會定義命令重新啟動，並取得MaxMinReport。
      • 函 user_command_handler 式會定義裝置在收到命令時應該執行的動作。
      • 函 create_user_response_handler 式會在命令成功執行時，建立要傳送至IoT中樞的回應。 您可以在入口網站中檢視此回應。 如果未提供此函式，則會將一般回應傳送至服務。

    • 使用 execute_property_listener 來接聽屬性更新。

    • 使用 開始傳送遙測 send_telemetry。 範例程式代碼會使用 迴圈來呼叫三個遙測傳送函式。 每8秒呼叫一次

    • 停用所有接聽程式和工作，並在按下 Q 或 q 時結束迴圈。

在 [設定您的環境] 中，您已建立四個環境變數來設定範例，以使用裝置布建服務 （DPS） 連線到 IoT 中樞：

  • 具有 值的IOTHUB_DEVICE_SECURITY_TYPEDPS
  • 具有 DPS 識別碼範圍的IOTHUB_DEVICE_DPS_ID_SCOPE 。
  • IOTHUB_DEVICE_DPS_DEVICE_ID 值 my-pnp-device。
  • 使用註冊主鍵IOTHUB_DEVICE_DPS_DEVICE_KEY。
  • IOTHUB_DEVICE_DPS_ENDPOINT 值 global.azure-devices-provisioning.net。

若要深入瞭解範例組態，請參閱 範例自述檔。

使用下列命令來執行範例：

python temp_controller_with_thermostats.py

範例裝置每隔幾秒鐘就會將遙測訊息傳送至IoT中樞。

您會看到下列輸出，指出裝置正在將遙測數據傳送至中樞，且現在已準備好接收命令和屬性更新。

裝置確認訊息

當您完成後續步驟時，請讓範例保持執行。

使用 Azure IoT 總管來驗證程式代碼

裝置用戶端範例啟動之後，請使用 Azure IoT 總管工具來確認其運作正常。

  1. 開啟 Azure IoT 總管。

  2. 在 [ IoT 中樞] 頁面上，如果您尚未將連線新增至 IoT 中樞，請選取 [+ 新增連線]。 輸入您先前建立的IoT中樞 連接字串，然後選取 [儲存]。

  3. 在 [IoT 隨插即用 設定] 頁面上，選取 [+ 新增>本機] 資料夾，然後選取您儲存模型檔案的本機 models 資料夾。

  4. 在 [ IoT 中樞] 頁面上，按下您要使用中樞的名稱。 您會看到已註冊至IoT中樞的裝置清單。

  5. 按兩下 您先前建立之裝置的 [裝置 標識符]。

  6. 左側功能表會顯示適用於裝置的不同信息類型。

  7. 選取 IoT 隨插即用元件，以檢視裝置的模型資訊。

  8. 您可以檢視裝置的不同元件。 默認元件和任何額外的元件。 選取要使用的元件。

  9. 選取 [ 遙測 ] 頁面，然後選取 [ 開始 ] 以檢視裝置為此元件傳送的遙測數據。

  10. 選取 [ 屬性] [只讀] 頁面，以檢視針對此元件報告的只讀屬性。

  11. 選取 [ 屬性] 頁面，以檢視您可以為此元件更新的可寫入 屬性。

  12. 依其 名稱選取屬性、輸入新值，然後選取 [ 更新所需的值]。

  13. 若要查看新的值，請選取 [ 重新 整理] 按鈕。

  14. 選取 [ 命令] 頁面以檢視此元件的所有命令。

  15. 選取您想要測試的命令，如果有的話，請設定 參數。 選取 [ 傳送] 命令 以呼叫裝置上的命令。 您可以在執行範例程式代碼的命令提示字元視窗中看到您的裝置回應命令。

清除資源

如果您打算繼續進行更多裝置開發人員文章，您可以保留並重複使用本文中使用的資源。 否則，您可以刪除本文中建立的資源，以避免產生更多費用。

您可以使用下列 Azure CLI 命令刪除整個資源群組，同時刪除中樞和已註冊的裝置。 如果這些資源與您想要保留的其他資源分享資源群組，請勿使用此命令。

az group delete --name <YourResourceGroupName>

若要只刪除IoT中樞，請使用 Azure CLI 執行下列命令：

az iot hub delete --name <YourIoTHubName>

若要只刪除您向IoT中樞註冊的裝置身分識別，請使用 Azure CLI 執行下列命令：

az iot hub device-identity delete --hub-name <YourIoTHubName> --device-id <YourDeviceID>

您也可以從開發計算機中移除複製的範例檔案。

下一步

在本教學課程中，您已瞭解如何將 IoT 隨插即用 裝置與元件連線到 IoT 中樞。 若要深入瞭解 IoT 隨插即用 裝置型號，請參閱：

IoT 隨插即用 模型化開發人員指南