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

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

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

先决条件

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

若要在 Windows 上完成本快速入门,需要在开发计算机上安装以下软件:

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

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

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

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

运行示例设备

在本快速入门中,你将使用一个以 C# 编写的示例恒温器设备作为 IoT 即插即用设备。 运行示例设备:

  1. 在 Visual Studio 2019 中打开“azure-iot-samples-csharp\iot-hub\Samples\device\PnpDeviceSamples\Thermostat\Thermostat.csproj”项目文件。

  2. 在 Visual Studio 中,导航到“项目”>“恒温器属性”>“调试”。 然后,将以下环境变量添加到项目:

    名称
    IOTHUB_DEVICE_SECURITY_TYPE DPS
    IOTHUB_DEVICE_DPS_ENDPOINT global.azure-devices-provisioning.net
    IOTHUB_DEVICE_DPS_ID_SCOPE 在完成设置环境时记下的值
    IOTHUB_DEVICE_DPS_DEVICE_ID my-pnp-device
    IOTHUB_DEVICE_DPS_DEVICE_KEY 在完成设置环境时记下的值
  3. 现在可以在 Visual Studio 中生成示例,并在调试模式下运行它。

  4. 你会看到一些消息,指出设备已发送部分信息并报告其自身处于联机状态。 这些消息表明设备已开始向中心发送遥测数据,现在可以接收命令和属性更新。 请勿关闭此 Visual Studio 实例,你需要使用它确认服务示例正常工作。

运行示例解决方案

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

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

在本快速入门中,你将使用以 C# 编写的示例 IoT 解决方案与刚设置的示例设备进行交互。

  1. 在 Visual Studio 的另一个实例中,打开“azure-iot-samples-csharp\iot-hub\Samples\service\PnpServiceSamples\Thermostat\Thermostat.csproj”项目。

  2. 在 Visual Studio 中,导航到“项目”>“恒温器属性”>“调试”。 然后,将以下环境变量添加到项目:

    名称
    IOTHUB_DEVICE_ID my-pnp-device
    IOTHUB_CONNECTION_STRING 在完成设置环境时记下的值
  3. 现在可以在 Visual Studio 中生成示例,并在调试模式下运行它。

获取设备孪生

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

// 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 中心)后再继续。

要完成本快速入门,需在本地 Windows 环境上安装以下软件:

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

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

在所选目录中打开命令提示符。 执行以下命令,将用于 Java 的 Microsoft Azure IoT SDK GitHub 存储库克隆到此位置:

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

生成并运行示例设备

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

  • 具有值 DPS 的 IOTHUB_DEVICE_SECURITY_TYPE
  • 包含 DPS ID 范围的 IOTHUB_DEVICE_DPS_ID_SCOPE。
  • 包含值 my-pnp-device 的 IOTHUB_DEVICE_DPS_DEVICE_ID。
  • 包含注册主密钥的 IOTHUB_DEVICE_DPS_DEVICE_KEY。
  • 包含值 global.azure-devices-provisioning.net 的 IOTHUB_DEVICE_DPS_ENDPOINT。

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

在本快速入门中,你将使用一个以 Java 编写的示例恒温器设备作为 IoT 即插即用设备。 运行示例设备:

  1. 打开终端窗口,然后导航到包含从 GitHub 克隆的用于 Java 的 Microsoft Azure IoT SDK 存储库的本地文件夹。

  2. 此终端窗口将用作设备终端。 转到克隆存储库的根文件夹。 运行以下命令安装所有依赖项:

  3. 运行以下命令以生成示例设备应用程序:

    mvn install -T 2C -DskipTests
    
  4. 若要运行示例设备应用程序,请导航到“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)的详细信息,请参阅服务开发人员指南

  1. 打开另一个终端窗口用作服务终端。

  2. 在克隆的 Java SDK 存储库中,导航到“service\iot-service-samples\pnp-service-sample\thermostat-service-sample”文件夹。

  3. 要运行示例服务应用程序,请运行以下命令:

    mvm 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 中心:

  • 具有值 DPS 的 IOTHUB_DEVICE_SECURITY_TYPE
  • 包含 DPS ID 范围的 IOTHUB_DEVICE_DPS_ID_SCOPE。
  • 包含值 my-pnp-device 的 IOTHUB_DEVICE_DPS_DEVICE_ID。
  • 包含注册主密钥的 IOTHUB_DEVICE_DPS_DEVICE_KEY。
  • 包含值 global.azure-devices-provisioning.net 的 IOTHUB_DEVICE_DPS_ENDPOINT。

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

在本快速入门中,使用一个以 Node.js 编写的示例恒温器设备作为 IoT 即插即用设备。 运行示例设备:

  1. 打开终端窗口,然后导航到包含从 GitHub 克隆的适用于 Node.js 的 Microsoft Azure IoT SDK 存储库的本地文件夹。

  2. 此终端窗口将用作设备终端。 前往克隆的存储库的文件夹,然后导航到 /azure-iot-sdk-node/device/samples/pnp 文件夹。 运行以下命令安装所有依赖项:

    npm install
    
  3. 使用以下命令运行示例恒温器设备:

    node simple_thermostat.js
    
  4. 你会看到一些消息,指出设备已发送部分信息并报告其自身处于联机状态。 这些消息表明设备已开始向中心发送遥测数据,现在可以接收命令和属性更新。 请不要关闭此终端,需要在其中确认服务示例是否在正常运行。

运行示例解决方案

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

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

在本快速入门中,你将使用以 Node.js 编写的示例 IoT 解决方案与你刚刚设置的示例设备进行交互。

  1. 打开另一个终端窗口用作服务终端。

  2. 在克隆的 Node SDK 存储库中,导航到“/azure-iot-sdk-node/service/samples/javascript”文件夹。 运行以下命令安装所有依赖项:

    npm install
    

读取属性

  1. 在设备终端运行示例恒温器设备时,你会看到以下消息,指示其已联机:

    properties have been reported for component
    sending telemetry message 0...
    
  2. 转到 服务 终端,并使用以下命令来运行用于读取设备信息的示例:

    node twin.js
    
  3. 在服务终端输出中,请注意设备孪生的响应。 你会看到所报告的设备的模型 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": {}
    }
    
  4. 以下代码片段显示了 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)的详细信息,请参阅服务开发人员指南

更新可写属性

  1. 在代码编辑器中打开文件 twin.js。

  2. 查看示例代码,它演示了更新设备孪生的两种方法。 若要使用第一种方法,请按如下所示修改 twinPatch 变量:

    var twinPatch = {
      tags: {
        city: "Redmond"
      },
      properties: {
        desired: {
          targetTemperature: 42
        }
      }
    };
    

    targetTemperature 属性被定义为恒温器设备模型中的可写属性。

  3. 在服务终端中,使用以下命令来运行用于更新属性的示例:

    node twin.js
    
  4. 在设备终端中,将看到设备已接收更新:

    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
    
  5. 在服务终端中,运行以下命令以确认属性已更新:

    node twin.js
    
  6. 在服务终端输出的 reported 属性部分,你会看到报告的已更新的目标温度。 设备可能需要花费一段时间来完成更新。 请重复此步骤,直到设备已处理属性更新为止:

    "reported": {
      //...
      "targetTemperature": {
        "value": 42,
        "ac": 200,
        "ad": "Successfully executed patch for targetTemperature",
        "av": 4
      },
      //...
    }
    

调用命令

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

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

    set IOTHUB_METHOD_NAME=getMaxMinReport
    set IOTHUB_METHOD_PAYLOAD=commandpayload
    node device_method.js
    
  3. 服务终端中的输出显示以下确认消息:

    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"
      }
    }
    
  4. 在设备终端中,将看到命令已确认:

    MaxMinReport commandpayload
    Response to method 'getMaxMinReport' sent successfully.
    

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

先决条件

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

若要完成本快速入门,需要在开发计算机上使用 Python 3.7。 可以从 python.org 下载适用于多个平台的最新推荐版本。可以使用以下命令检查 Python 版本:

python --version

azure-iot-device 包将以 PIP 的形式发布。

在本地 python 环境中安装该包,如下所示:

pip install azure-iot-device

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

pip install azure-iot-hub

运行示例设备

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

  • 具有值 DPS 的 IOTHUB_DEVICE_SECURITY_TYPE
  • 包含 DPS ID 范围的 IOTHUB_DEVICE_DPS_ID_SCOPE。
  • 包含值 my-pnp-device 的 IOTHUB_DEVICE_DPS_DEVICE_ID。
  • 包含注册主密钥的 IOTHUB_DEVICE_DPS_DEVICE_KEY。
  • 包含值 global.azure-devices-provisioning.net 的 IOTHUB_DEVICE_DPS_ENDPOINT。

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

在本快速入门中,你将使用一个以 Python 编写的示例调温器作为 IoT 即插即用设备。 运行示例设备:

  1. 在所选文件夹中打开一个终端窗口。 运行以下命令,将 Azure IoT Python SDK GitHub 存储库克隆到此位置:

    git clone https://github.com/Azure/azure-iot-sdk-python
    
  2. 此终端窗口将用作设备终端。 前往克隆的存储库的文件夹,然后导航到 /azure-iot-sdk-python/azure-iot-device/samples/pnp 文件夹。

  3. 使用以下命令运行示例恒温器设备:

    python simple_thermostat.py
    
  4. 你会看到一些消息,指出设备已发送部分信息并报告其自身处于联机状态。 这些消息表明设备已开始向中心发送遥测数据,现在可以接收命令和属性更新。 请不要关闭此终端,需要在其中确认服务示例是否在正常运行。

运行示例解决方案

在本快速入门中,你将使用以 Python 编写的示例 IoT 解决方案与你刚刚设置的示例设备进行交互。

  1. 打开另一个终端窗口用作服务终端。

  2. 导航到克隆的 Python SDK 存储库的“/azure-iot-sdk-python/azure-iot-hub/samples”文件夹。

  3. 打开 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 即插即用设备模型,请参阅: