你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

教程：与已连接到解决方案的 IoT 即插即用设备交互

项目
02/06/2024

IoT 即插即用简化了 IoT 的使用，使你无需了解底层设备实现，就能与某个设备的功能交互。本教程介绍如何使用 C# 来连接和控制已与解决方案连接的 IoT 即插即用设备。

先决条件

请确保设置环境（包括 IoT 中心）后再继续。

可以在 Linux 或 Windows 上运行本教程。本教程中的 shell 命令遵循适用于路径分隔符“/”的 Linux 约定，如果你是在 Windows 上操作，请务必将这些分隔符替换为“\”。

针对你的平台的最新 .NET SDK。
Git。

使用示例代码克隆 SDK 存储库

如果你完成了教程：将 Windows 上运行的示例 IoT 即插即用设备应用程序连接到 IoT 中心 (C#)，则已经克隆了该存储库。

为 C# GitHub 存储库克隆 Azure IoT SDK 中的示例。在所选文件夹中打开命令提示符。运行以下命令，以克隆适用于 .NET 的 Microsoft Azure IoT SDK GitHub 存储库：

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

生成设备代码

现在可以生成设备示例并运行它。运行以下命令生成示例：

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

运行设备示例

若要运行示例，请运行以下命令：

dotnet run

设备现在可以接收命令和属性更新，并已开始向中心发送遥测数据。在执行后续步骤时，保持示例处于运行状态。

运行示例解决方案

在针对 IoT 即插即用快速入门和教程设置环境中，已创建了两个环境变量以将示例配置为连接到 IoT 中心：

IOTHUB_CONNECTION_STRING：之前记下的 IoT 中心连接字符串。
IOTHUB_DEVICE_ID："my-pnp-device"。

在本教程中，你将使用以 C# 编写的示例 IoT 解决方案与刚设置并运行的示例设备进行交互。

在另一个终端窗口中，导航到 azure-iot-sdk-csharp/iothub/service/samples/solutions/PnpServiceSamples/Thermostat 文件夹。
运行以下命令以生成服务示例：
```
dotnet build
```
运行以下命令以运行服务示例：
```
dotnet run
```

获取设备孪生

以下代码片段演示了服务应用程序如何检索设备孪生：

// Get a Twin and retrieves model Id set by Device client
Twin twin = await s_registryManager.GetTwinAsync(s_deviceId);
s_logger.LogDebug($"Model Id of this Twin is: {twin.ModelId}");

注意

此示例使用 IoT 中心服务客户端中的 Microsoft.Azure.Devices.Client 命名空间。若要了解有关 API（包括数字孪生 API）的详细信息，请参阅服务开发人员指南。

此代码生成以下输出：

[09/21/2020 11:26:04]dbug: Thermostat.Program[0]
      Model Id of this Twin is: dtmi:com:example:Thermostat;1

以下代码片段演示了如何使用补丁通过设备孪生来更新属性：

// Update the twin
var twinPatch = new Twin();
twinPatch.Properties.Desired[PropertyName] = PropertyValue;
await s_registryManager.UpdateTwinAsync(s_deviceId, twinPatch, twin.ETag);

当服务更新 targetTemperature 属性时，此代码将从设备生成以下输出：

[09/21/2020 11:26:05]dbug: Thermostat.ThermostatSample[0]
      Property: Received - { "targetTemperature": 60°C }.
[09/21/2020 11:26:05]dbug: Thermostat.ThermostatSample[0]
      Property: Update - {"targetTemperature": 60°C } is InProgress.

...

[09/21/2020 11:26:17]dbug: Thermostat.ThermostatSample[0]
      Property: Update - {"targetTemperature": 60°C } is Completed.

调用命令

下面的代码片段演示如何调用命令：

private static async Task InvokeCommandAsync()
{
    var commandInvocation = new CloudToDeviceMethod(CommandName) { ResponseTimeout = TimeSpan.FromSeconds(30) };

    // Set command payload
    string componentCommandPayload = JsonConvert.SerializeObject(s_dateTime);
    commandInvocation.SetPayloadJson(componentCommandPayload);

    CloudToDeviceMethodResult result = await s_serviceClient.InvokeDeviceMethodAsync(s_deviceId, commandInvocation);

    if (result == null)
    {
        throw new Exception($"Command {CommandName} invocation returned null");
    }

    s_logger.LogDebug($"Command {CommandName} invocation result status is: {result.Status}");
}

当服务调用 getMaxMinReport 命令时，此代码将从设备生成以下输出：

[09/21/2020 11:26:05]dbug: Thermostat.ThermostatSample[0]
      Command: Received - Generating max, min and avg temperature report since 21/09/2020 11:25:58.
[09/21/2020 11:26:05]dbug: Thermostat.ThermostatSample[0]
      Command: MaxMinReport since 21/09/2020 11:25:58: maxTemp=32, minTemp=32, avgTemp=32, startTime=21/09/2020 11:25:59, endTime=21/09/2020 11:26:04

IoT 即插即用简化了 IoT 的使用，使你无需了解底层设备实现，就能与某个设备的功能交互。本教程介绍如何使用 Java 来连接和控制已与解决方案连接的 IoT 即插即用设备。

先决条件

请确保设置环境（包括 IoT 中心）后再继续。

若要完成本教程，需在本地开发环境中安装以下软件：

使用示例代码克隆 SDK 存储库

如果你完成了教程：将 Windows 上运行的示例 IoT 即插即用设备应用程序连接到 IoT 中心 (Java)，则已经克隆了该存储库。

在所选目录中打开命令提示符。执行以下命令，将用于 Java 的 Microsoft Azure IoT 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/thermostat-device-sample
mvn clean package

设置环境部分创建了四个环境变量来配置示例，以使用设备预配服务 (DPS) 连接到 IoT 中心：

具有值的 IOTHUB_DEVICE_SECURITY_TYPE
包含 DPS ID 范围的 IOTHUB_DEVICE_DPS_ID_SCOPE。
包含值的 IOTHUB_DEVICE_DPS_DEVICE_ID。
包含注册主密钥的 IOTHUB_DEVICE_DPS_DEVICE_KEY。
包含值的 IOTHUB_DEVICE_DPS_ENDPOINT。

若要详细了解示例配置，请参阅示例自述文件。

从 /device/iot-device-samples/pnp-device-sample/thermostat-device-sample 文件夹中，运行应用程序：

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

设备现在可以接收命令和属性更新，并已开始向中心发送遥测数据。在执行后续步骤时，保持示例处于运行状态。

运行示例解决方案

在针对 IoT 即插即用快速入门和教程设置环境中，已创建了两个环境变量以将示例配置为连接到 IoT 中心：

IOTHUB_CONNECTION_STRING：之前记下的 IoT 中心连接字符串。
IOTHUB_DEVICE_ID："my-pnp-device"。

在本教程中，你将使用以 Java 编写的示例 IoT 解决方案与刚设置的示例设备进行交互。

注意

此示例使用来自 IoT 中心服务客户端的“com.microsoft.azure.sdk.iot.service”命名空间。若要了解有关 API（包括数字孪生 API）的详细信息，请参阅服务开发人员指南。

打开另一个终端窗口用作服务终端。
在克隆的 Java SDK 存储库中，导航到 service/iot-service-samples/pnp-service-sample/thermostat-service-sample 文件夹。

要生成并运行示例服务应用程序，请运行以下命令：

mvn clean package
mvn exec:java -Dexec.mainClass="samples.com.microsoft.azure.sdk.iot.service.Thermostat"

获取设备孪生

以下代码片段演示了如何在服务中检索设备孪生：

 // Get the twin and retrieve model Id set by Device client.
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
twinClient.getTwin(twin);
System.out.println("Model Id of this Twin is: " + twin.getModelId());

更新设备孪生

以下代码片段演示了如何使用补丁通过设备孪生来更新属性：

String propertyName = "targetTemperature";
double propertyValue = 60.2;
twin.setDesiredProperties(Collections.singleton(new Pair(propertyName, propertyValue)));
twinClient.updateTwin(twin);

设备输出将显示设备如何响应此属性更新。

调用命令

以下代码片段演示了如何在设备上调用命令：

// The method to invoke for a device without components should be "methodName" as defined in the DTDL.
String methodToInvoke = "getMaxMinReport";
System.out.println("Invoking method: " + methodToInvoke);

Long responseTimeout = TimeUnit.SECONDS.toSeconds(200);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

// Invoke the command.
String commandInput = ZonedDateTime.now(ZoneOffset.UTC).minusMinutes(5).format(DateTimeFormatter.ISO_DATE_TIME);
MethodResult result = methodClient.invoke(deviceId, methodToInvoke, responseTimeout, connectTimeout, commandInput);
if(result == null)
{
    throw new IOException("Method result is null");
}

System.out.println("Method result status is: " + result.getStatus());

设备输出将显示设备如何响应此命令。

IoT 即插即用简化了 IoT 的使用，使你无需了解底层设备实现，就能与某个设备的功能交互。本教程介绍如何使用 Node.js 来连接和控制已与解决方案连接的 IoT 即插即用设备。

先决条件

请确保设置环境（包括 IoT 中心）后再继续。

若要完成本教程，需要在开发计算机上使用 Node.js。可以从 nodejs.org 下载适用于多个平台的最新推荐版本。

可以使用以下命令验证开发计算机上 Node.js 当前的版本：

node --version

使用示例代码克隆 SDK 存储库

从 Node SDK 存储库克隆示例。在所选文件夹中打开一个终端窗口。运行以下命令，以克隆用于 Node.js 的 Microsoft Azure IoT SDK GitHub 存储库：

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

运行示例设备

设置环境部分创建了四个环境变量来配置示例，以使用设备预配服务 (DPS) 连接到 IoT 中心：

具有值的 IOTHUB_DEVICE_SECURITY_TYPE
包含 DPS ID 范围的 IOTHUB_DEVICE_DPS_ID_SCOPE。
包含值的 IOTHUB_DEVICE_DPS_DEVICE_ID。
包含注册主密钥的 IOTHUB_DEVICE_DPS_DEVICE_KEY。
包含值的 IOTHUB_DEVICE_DPS_ENDPOINT。

若要详细了解示例配置，请参阅示例自述文件。

在本教程中，使用一个以 Node.js 编写的示例恒温器设备作为 IoT 即插即用设备。运行示例设备：

打开终端窗口，然后导航到包含从 GitHub 克隆的适用于 Node.js 的 Microsoft Azure IoT SDK 存储库的本地文件夹。
此终端窗口将用作设备终端。前往克隆的存储库的文件夹，然后导航到 /azure-iot-sdk-node/device/samples/javascript 文件夹。运行以下命令安装所有依赖项：
```
npm install
```
使用以下命令运行示例恒温器设备：
```
node pnp_simple_thermostat.js
```
你会看到一些消息，指出设备已发送部分信息并报告其自身处于联机状态。这些消息表明设备已开始向中心发送遥测数据，现在可以接收命令和属性更新。请不要关闭此终端，需要在其中确认服务示例是否在正常运行。

运行示例解决方案

在针对 IoT 即插即用快速入门和教程设置环境中，已创建了两个环境变量以将示例配置为连接到 IoT 中心：

IOTHUB_CONNECTION_STRING：之前记下的 IoT 中心连接字符串。
IOTHUB_DEVICE_ID："my-pnp-device"。

在本教程中，你使用示例 Node.js IoT 解决方案与刚设置并运行的示例设备进行交互。

打开另一个终端窗口用作服务终端。
在克隆的 Node SDK 存储库中，导航到 azure-iot-sdk-node/service/samples/javascript 文件夹。运行以下命令安装所有依赖项：
```
npm install
```

读取属性

在设备终端运行示例恒温器设备时，你会看到以下消息，指示其已联机：
```
properties have been reported for component
sending telemetry message 0...
```
转到服务终端，并使用以下命令来运行用于读取设备信息的示例：
```
node twin.js
```

在服务终端输出中，请注意设备孪生的响应。你会看到所报告的设备的模型 ID 以及相关属性：

Model Id: dtmi:com:example:Thermostat;1
{
  "deviceId": "my-pnp-device",
  "etag": "AAAAAAAAAAE=",
  "deviceEtag": "Njc3MDMxNDcy",
  "status": "enabled",
  "statusUpdateTime": "0001-01-01T00:00:00Z",
  "connectionState": "Connected",
  "lastActivityTime": "0001-01-01T00:00:00Z",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  },
  "modelId": "dtmi:com:example:Thermostat;1",
  "version": 4,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2020-10-05T11:35:19.4574755Z"
      },
      "$version": 1
    },
    "reported": {
      "maxTempSinceLastReboot": 31.343640523762232,
      "serialNumber": "123abc",
      "$metadata": {
        "$lastUpdated": "2020-10-05T11:35:23.7339042Z",
        "maxTempSinceLastReboot": {
          "$lastUpdated": "2020-10-05T11:35:23.7339042Z"
        },
        "serialNumber": {
          "$lastUpdated": "2020-10-05T11:35:23.7339042Z"
        }
      },
      "$version": 3
    }
  },
  "capabilities": {
    "iotEdge": false
  },
  "tags": {}
}

以下代码片段显示了 twin.js 中检索设备孪生的模型 ID 的代码：

var registry = Registry.fromConnectionString(connectionString);
registry.getTwin(deviceId, function(err, twin) {
  if (err) {
    console.error(err.message);
  } else {
    console.log('Model Id: ' + twin.modelId);
    //...
  }
  //...
}

在本方案中，此代码输出 Model Id: dtmi:com:example:Thermostat;1。

注意

这些服务示例使用来自 IoT 中心服务客户端的 Registry 类。若要了解有关 API（包括数字孪生 API）的详细信息，请参阅服务开发人员指南。

更新可写属性

在代码编辑器中打开文件 twin.js。
查看示例代码，它演示了更新设备孪生的两种方法。若要使用第一种方法，请按如下所示修改 twinPatch 变量：
```
var twinPatch = {
  tags: {
    city: "Redmond"
  },
  properties: {
    desired: {
      targetTemperature: 42
    }
  }
};
```
targetTemperature 属性被定义为恒温器设备模型中的可写属性。
在服务终端中，使用以下命令来运行用于更新属性的示例：
```
node twin.js
```

在设备终端中，将看到设备已接收更新：

The following properties will be updated for the default component:
{
  targetTemperature: {
    value: 42,
    ac: 200,
    ad: 'Successfully executed patch for targetTemperature',
    av: 2
  }
}
updated the property

在服务终端中，运行以下命令以确认属性已更新：
```
node twin.js
```
在服务终端输出的属性部分，你会看到报告的已更新的目标温度。设备可能需要花费一段时间来完成更新。请重复此步骤，直到设备已处理属性更新为止：
```
"reported": {
  //...
  "targetTemperature": {
    "value": 42,
    "ac": 200,
    "ad": "Successfully executed patch for targetTemperature",
    "av": 4
  },
  //...
}
```

调用命令

打开文件 device_method.js，并查看代码。

转到服务终端。使用以下命令来运行用于调用该命令的示例：

set IOTHUB_METHOD_NAME=getMaxMinReport
set IOTHUB_METHOD_PAYLOAD=commandpayload
node device_method.js

服务终端中的输出显示以下确认消息：

getMaxMinReport on my-pnp-device:
{
  "status": 200,
  "payload": {
    "maxTemp": 23.460596940801928,
    "minTemp": 23.460596940801928,
    "avgTemp": 23.460596940801928,
    "endTime": "2020-10-05T12:48:08.562Z",
    "startTime": "2020-10-05T12:47:54.450Z"
  }
}

在设备终端中，将看到命令已确认：

MaxMinReport commandpayload
Response to method 'getMaxMinReport' sent successfully.

IoT 即插即用简化了 IoT 的使用，使你无需了解底层设备实现，就能与某个设备的模型交互。本教程介绍如何使用 Python 来连接和控制已与解决方案连接的 IoT 即插即用设备。

先决条件

请确保设置环境（包括 IoT 中心）后再继续。

若要完成本教程，需要在开发计算机上安装 Python。查看 Azure IoT Python SDK 以了解当前的 Python 版本要求。可以使用以下命令检查 Python 版本：

python --version

可以从 python.org 下载适用于多个平台的最新推荐版本。

在本地 Python 环境中安装 azure-iot-device 包，如下所示：

pip install azure-iot-device

运行以下命令安装 azure-iot-hub 包：

pip install azure-iot-hub

运行示例设备

设置环境部分创建了四个环境变量来配置示例，以使用设备预配服务 (DPS) 连接到 IoT 中心：

具有值的 IOTHUB_DEVICE_SECURITY_TYPE
包含 DPS ID 范围的 IOTHUB_DEVICE_DPS_ID_SCOPE。
包含值的 IOTHUB_DEVICE_DPS_DEVICE_ID。
包含注册主密钥的 IOTHUB_DEVICE_DPS_DEVICE_KEY。
包含值的 IOTHUB_DEVICE_DPS_ENDPOINT。

若要详细了解示例配置，请参阅示例自述文件。

在本教程中，你将使用一个以 Python 编写的示例调温器作为 IoT 即插即用设备。运行示例设备：

在所选文件夹中打开一个终端窗口。运行以下命令，将 Azure IoT Device Python SDK GitHub 存储库克隆到此位置：
```
git clone --branch v2 https://github.com/Azure/azure-iot-sdk-python
```
此终端窗口将用作设备终端。前往克隆的存储库的文件夹，然后导航到 azure-iot-sdk-python/samples/pnp 文件夹。
使用以下命令运行示例恒温器设备：
```
python simple_thermostat.py
```
你会看到一些消息，指出设备已发送部分信息并报告其自身处于联机状态。这些消息表明设备已开始向中心发送遥测数据，现在可以接收命令和属性更新。请不要关闭此终端，需要在其中确认服务示例是否在正常运行。

运行示例解决方案

在本教程中，你将使用以 Python 编写的示例 IoT 解决方案与你刚刚设置的示例设备进行交互。

打开另一个终端窗口用作服务终端。运行以下命令，将 Azure IoT Hub Python SDK GitHub 存储库克隆到此位置：
```
git clone https://github.com/Azure/azure-iot-hub-python
```
安装
导航到克隆的 Python SDK 存储库的 /azure-iot-hub-python/samples 文件夹。
打开 registry_manager_pnp_sample.py 文件并查看代码。此示例演示如何使用 IoTHubRegistryManager 类与 IoT 即插即用设备进行交互。

注意

这些服务示例使用来自 IoT 中心服务客户端的 IoTHubRegistryManager 类。若要了解有关 API（包括数字孪生 API）的详细信息，请参阅服务开发人员指南。

获取设备孪生

在针对 IoT 即插即用快速入门和教程设置环境中，已创建了两个环境变量以将示例配置为连接到 IoT 中心：

IOTHUB_CONNECTION_STRING：之前记下的 IoT 中心连接字符串。
IOTHUB_DEVICE_ID："my-pnp-device"。

在服务终端中使用以下命令运行此示例：

set IOTHUB_METHOD_NAME="getMaxMinReport"
set IOTHUB_METHOD_PAYLOAD="hello world"
python registry_manager_pnp_sample.py

注意

如果是在 Linux 上运行此示例，请使用 export 代替 set。

输出将显示设备孪生，并打印其模型 ID：

The Model ID for this device is:
dtmi:com:example:Thermostat;1

以下代码片段显示了 registry_manager_pnp_sample.py 中的示例代码：

    # Create IoTHubRegistryManager
    iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)

    # Get device twin
    twin = iothub_registry_manager.get_twin(device_id)
    print("The device twin is: ")
    print("")
    print(twin)
    print("")

    # Print the device's model ID
    additional_props = twin.additional_properties
    if "modelId" in additional_props:
        print("The Model ID for this device is:")
        print(additional_props["modelId"])
        print("")

更新设备孪生

此示例演示如何更新设备中的 targetTemperature 可写属性：

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(
        desired={"targetTemperature": 42}
    )  # this is relevant for the thermostat device sample
    updated_twin = iothub_registry_manager.update_twin(device_id, twin_patch, twin.etag)
    print("The twin patch has been successfully applied")
    print("")

你可以在显示以下输出的设备终端中验证是否已应用更新：

the data in the desired properties patch was: {'targetTemperature': 42, '$version': 2}

服务终端确认修补程序已成功：

The twin patch has been successfully applied

调用命令

然后，该示例会调用命令：

服务终端显示来自设备的确认消息：

The device method has been successfully invoked

在设备终端中，将显示设备收到以下命令：

Command request received with payload
hello world
Will return the max, min and average temperature from the specified time hello to the current time
Done generating
{"tempReport": {"avgTemp": 34.2, "endTime": "09/07/2020 09:58:11", "maxTemp": 49, "minTemp": 10, "startTime": "09/07/2020 09:56:51"}}

清理资源

如果已完成快速入门和教程，请参阅清理资源。

后续步骤

本教程已介绍如何将 IoT 即插即用设备连接到 IoT 解决方案。若要详细了解 IoT 即插即用设备模型，请参阅：

IoT 即插即用建模开发人员指南

教程：与已连接到解决方案的 IoT 即插即用设备交互

先决条件

使用示例代码克隆 SDK 存储库

生成设备代码

运行设备示例

运行示例解决方案

获取设备孪生

调用命令

先决条件

使用示例代码克隆 SDK 存储库

生成并运行示例设备

运行示例解决方案

获取设备孪生

更新设备孪生

调用命令

先决条件

使用示例代码克隆 SDK 存储库

运行示例设备

运行示例解决方案

读取属性

更新可写属性

调用命令

先决条件

运行示例设备

运行示例解决方案

获取设备孪生

更新设备孪生

调用命令

清理资源

后续步骤

其他资源