Tutorial: Interact with an IoT Plug and Play device that's connected to your solution

IoT Plug and Play simplifies IoT by enabling you to interact with a device's capabilities without knowledge of the underlying device implementation. This quickstart shows you how to use C# to connect to and control an IoT Plug and Play device that's connected to your solution.

Prerequisites

Before you continue, make sure you've set up your environment, including your IoT hub.

To complete this quickstart on Windows, you need the following software installed on your development machine:

Clone the SDK repository with the sample code

If you completed Tutorial: Connect a sample IoT Plug and Play device application running on Windows to IoT Hub (C#), you've already cloned the repository.

Clone the samples from the Azure IoT Samples for C# GitHub repository. Open a command prompt in a folder of your choice. Run the following command to clone the Microsoft Azure IoT Samples for .NET GitHub repository:

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

Run the sample device

In this quickstart, you use a sample thermostat device that's written in C# as the IoT Plug and Play device. To run the sample device:

  1. Open the azure-iot-samples-csharp\iot-hub\Samples\device\PnpDeviceSamples\Thermostat\Thermostat.csproj project file in Visual Studio 2019.

  2. In Visual Studio, navigate to Project > Thermostat Properties > Debug. Then add the following environment variables to the project:

    Name Value
    IOTHUB_DEVICE_SECURITY_TYPE DPS
    IOTHUB_DEVICE_DPS_ENDPOINT global.azure-devices-provisioning.net
    IOTHUB_DEVICE_DPS_ID_SCOPE The value you made a note of when you completed Set up your environment
    IOTHUB_DEVICE_DPS_DEVICE_ID my-pnp-device
    IOTHUB_DEVICE_DPS_DEVICE_KEY The value you made a note of when you completed Set up your environment
  3. You can now build the sample in Visual Studio and run it in debug mode.

  4. You see messages saying that the device has sent some information and reported itself online. These messages indicate that the device has begun sending telemetry data to the hub, and is now ready to receive commands and property updates. Don't close this instance of Visual Studio, you need it to confirm the service sample is working.

Run the sample solution

In Set up your environment for the IoT Plug and Play quickstarts and tutorials you created two environment variables to configure the sample to connect to your IoT hub and device:

  • IOTHUB_CONNECTION_STRING: the IoT hub connection string you made a note of previously.
  • IOTHUB_DEVICE_ID: "my-pnp-device".

In this quickstart, you use a sample IoT solution in C# to interact with the sample device you just set up.

  1. In another instance of Visual Studio, open the azure-iot-samples-csharp\iot-hub\Samples\service\PnpServiceSamples\Thermostat\Thermostat.csproj project.

  2. In Visual Studio, navigate to Project > Thermostat Properties > Debug. Then add the following environment variables to the project:

    Name Value
    IOTHUB_DEVICE_ID my-pnp-device
    IOTHUB_CONNECTION_STRING The value you made a note of when you completed Set up your environment
  3. You can now build the sample in Visual Studio and run it in debug mode.

Get device twin

The following code snippet shows how the service application retrieves the device twin:

// 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}");

Note

This sample uses the Microsoft.Azure.Devices.Client namespace from the IoT Hub service client. To learn more about the APIs, including the digital twins API, see the service developer guide.

This code generates the following output:

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

The following code snippet shows how to use a patch to update properties through the device twin:

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

This code generates the following output from the device when the service updates the targetTemperature property:

[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.

Invoke a command

The following code snippet shows how to call a command:

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}");
}

This code generates the following output from the device when the service calls the getMaxMinReport command:

[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 Plug and Play simplifies IoT by enabling you to interact with a device's capabilities without knowledge of the underlying device implementation. This quickstart shows you how to use Java to connect to and control an IoT Plug and Play device that's connected to your solution.

Prerequisites

Before you continue, make sure you've set up your environment, including your IoT hub.

To complete this quickstart on Windows, install the following software on your local Windows environment:

Clone the SDK repository with the sample code

If you completed Tutorial: Connect a sample IoT Plug and Play device application running on Windows to IoT Hub (Java), you've already cloned the repository.

Open a command prompt in the directory of your choice. Execute the following command to clone the Microsoft Azure IoT SDKs for Java GitHub repository into this location:

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

Build and run the sample device

In Set up your environment, you created four environment variables to configure the sample to use the Device Provisioning Service (DPS) to connect to your IoT hub:

  • IOTHUB_DEVICE_SECURITY_TYPE with the value DPS
  • IOTHUB_DEVICE_DPS_ID_SCOPE with the DPS ID scope.
  • IOTHUB_DEVICE_DPS_DEVICE_ID with the value my-pnp-device.
  • IOTHUB_DEVICE_DPS_DEVICE_KEY with the enrollment primary key.
  • IOTHUB_DEVICE_DPS_ENDPOINT with the value global.azure-devices-provisioning.net.

To learn more about the sample configuration, see the sample readme.

In this quickstart, you use a sample thermostat device that's written in Java as the IoT Plug and Play device. To run the sample device:

  1. Open a terminal window and navigate to the local folder that contains the Microsoft Azure IoT SDK for Java repository you cloned from GitHub.

  2. This terminal window is used as your device terminal. Go to the root folder of your cloned repository. Install all the dependencies by running the following command:

  3. Run the following command to build the sample device application:

    mvn install -T 2C -DskipTests
    
  4. To run the sample device application, navigate to the device\iot-device-samples\pnp-device-sample\thermostat-device-sample folder and run the following command:

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

The device is now ready to receive commands and property updates, and has started sending telemetry data to the hub. Keep the sample device running as you complete the next steps.

Run the sample solution

In Set up your environment for the IoT Plug and Play quickstarts and tutorials you created two environment variables to configure the sample to connect to your IoT hub and device:

  • IOTHUB_CONNECTION_STRING: the IoT hub connection string you made a note of previously.
  • IOTHUB_DEVICE_ID: "my-pnp-device".

In this quickstart, you use a sample IoT solution written in Java to interact with the sample device you just set up.

Note

This sample uses the com.microsoft.azure.sdk.iot.service namespace from the IoT Hub service client. To learn more about the APIs, including the digital twins API, see the service developer guide.

  1. Open another terminal window to use as your service terminal.

  2. In the cloned Java SDK repository, navigate to the service\iot-service-samples\pnp-service-sample\thermostat-service-sample folder.

  3. To run the sample service application, run the following command:

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

Get device twin

The following code snippet shows how to retrieve the device twin in the service:

 // 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());

Update a device twin

The following code snippet shows you how to use a patch to update properties through the device twin:

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

The device output shows how the device responds to this property update.

Invoke a command

The following code snippet shows you call a command on the device:

// 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());

The device output shows how the device responds to this command.

IoT Plug and Play simplifies IoT by enabling you to interact with a device's capabilities without knowledge of the underlying device implementation. This quickstart shows you how to use Node.js to connect to and control an IoT Plug and Play device that's connected to your solution.

Prerequisites

Before you continue, make sure you've set up your environment, including your IoT hub.

To complete this quickstart, you need Node.js on your development machine. You can download the latest recommended version for multiple platforms from nodejs.org.

You can verify the current version of Node.js on your development machine using the following command:

node --version

Clone the SDK repository with the sample code

Clone the samples from a the Node SDK repository. Open a terminal window in a folder of your choice. Run the following command to clone the Microsoft Azure IoT SDK for Node.js GitHub repository:

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

Run the sample device

In Set up your environment, you created four environment variables to configure the sample to use the Device Provisioning Service (DPS) to connect to your IoT hub:

  • IOTHUB_DEVICE_SECURITY_TYPE with the value DPS
  • IOTHUB_DEVICE_DPS_ID_SCOPE with the DPS ID scope.
  • IOTHUB_DEVICE_DPS_DEVICE_ID with the value my-pnp-device.
  • IOTHUB_DEVICE_DPS_DEVICE_KEY with the enrollment primary key.
  • IOTHUB_DEVICE_DPS_ENDPOINT with the value global.azure-devices-provisioning.net.

To learn more about the sample configuration, see the sample readme.

In this quickstart, you use a sample thermostat device that's written in Node.js as the IoT Plug and Play device. To run the sample device:

  1. Open a terminal window and navigate to the local folder that contains the Microsoft Azure IoT SDK for Node.js repository you cloned from GitHub.

  2. This terminal window is used as your device terminal. Go to the folder of your cloned repository, and navigate to the /azure-iot-sdk-node/device/samples/pnp folder. Install all the dependencies by running the following command:

    npm install
    
  3. Run the sample thermostat device with the following command:

    node simple_thermostat.js
    
  4. You see messages saying that the device has sent some information and reported itself online. These messages indicate that the device has begun sending telemetry data to the hub, and is now ready to receive commands and property updates. Don't close this terminal, you need it to confirm the service sample is working.

Run the sample solution

In Set up your environment for the IoT Plug and Play quickstarts and tutorials you created two environment variables to configure the sample to connect to your IoT hub and device:

  • IOTHUB_CONNECTION_STRING: the IoT hub connection string you made a note of previously.
  • IOTHUB_DEVICE_ID: "my-pnp-device".

In this quickstart, you use a sample IoT solution in Node.js to interact with the sample device you just set up.

  1. Open another terminal window to use as your service terminal.

  2. In the cloned Node SDK repository, navigate to the /azure-iot-sdk-node/service/samples/javascript folder. Install all the dependencies by running the following command:

    npm install
    

Read a property

  1. When you ran the sample thermostat device in the device terminal, you saw the following messages indicating its online status:

    properties have been reported for component
    sending telemetry message 0...
    
  2. Go to the service terminal and use the following command to run the sample for reading device information:

    node twin.js
    
  3. In the service terminal output, notice the response of the device twin. You see the device's model ID and associated properties reported:

    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. The following snippet shows the code in twin.js that retrieves the device twin's model 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);
        //...
      }
      //...
    }
    

In this scenario, it outputs Model Id: dtmi:com:example:Thermostat;1.

Note

These service samples use the Registry class from the IoT Hub service client. To learn more about the APIs, including the digital twins API, see the service developer guide.

Update a writable property

  1. Open the file twin.js in a code editor.

  2. Review the sample code, it shows you two ways to update the device twin. To use the first way, modify the twinPatch variable as follows:

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

    The targetTemperature property is defined as a writable property in the Thermostat device model.

  3. In the service terminal, use the following command to run the sample for updating the property:

    node twin.js
    
  4. In your device terminal, you see the device has received the update:

    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. In your service terminal, run the following command to confirm the property is updated:

    node twin.js
    
  6. In the service terminal output, in the reported properties section, you see the updated target temperature reported. It might take a while for the device to finish the update. Repeat this step until the device has processed the property update:

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

Invoke a command

  1. Open the file device_method.js and review the code.

  2. Go to the service terminal. Use the following command to run the sample for invoking the command:

    set IOTHUB_METHOD_NAME=getMaxMinReport
    set IOTHUB_METHOD_PAYLOAD=commandpayload
    node device_method.js
    
  3. Output in the service terminal shows the following confirmation:

    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. In the device terminal, you see the command is acknowledged:

    MaxMinReport commandpayload
    Response to method 'getMaxMinReport' sent successfully.
    

IoT Plug and Play simplifies IoT by enabling you to interact with a device's model without knowledge of the underlying device implementation. This quickstart shows you how to use Python to connect to and control an IoT Plug and Play device that's connected to your solution.

Prerequisites

Before you continue, make sure you've set up your environment, including your IoT hub.

To complete this quickstart, you need Python 3.7 on your development machine. You can download the latest recommended version for multiple platforms from python.org. You can check your Python version with the following command:

python --version

The azure-iot-device package is published as a PIP.

In your local python environment install the package as follows:

pip install azure-iot-device

Install the azure-iot-hub package by running the following command:

pip install azure-iot-hub

Run the sample device

In Set up your environment, you created four environment variables to configure the sample to use the Device Provisioning Service (DPS) to connect to your IoT hub:

  • IOTHUB_DEVICE_SECURITY_TYPE with the value DPS
  • IOTHUB_DEVICE_DPS_ID_SCOPE with the DPS ID scope.
  • IOTHUB_DEVICE_DPS_DEVICE_ID with the value my-pnp-device.
  • IOTHUB_DEVICE_DPS_DEVICE_KEY with the enrollment primary key.
  • IOTHUB_DEVICE_DPS_ENDPOINT with the value global.azure-devices-provisioning.net.

To learn more about the sample configuration, see the sample readme.

In this quickstart, you use a sample thermostat device, written in Python, as the IoT Plug and Play device. To run the sample device:

  1. Open a terminal window in a folder of your choice. Run the following command to clone the Azure IoT Python SDK GitHub repository into this location:

    git clone https://github.com/Azure/azure-iot-sdk-python
    
  2. This terminal window is used as your device terminal. Go to the folder of your cloned repository, and navigate to the /azure-iot-sdk-python/azure-iot-device/samples/pnp folder.

  3. Run the sample thermostat device with the following command:

    python simple_thermostat.py
    
  4. You see messages saying that the device has sent some information and reported itself online. These messages indicate that the device has begun sending telemetry data to the hub, and is now ready to receive commands and property updates. Don't close this terminal, you need it to confirm the service sample is working.

Run the sample solution

In this quickstart, you use a sample IoT solution in Python to interact with the sample device you just set up.

  1. Open another terminal window to use as your service terminal.

  2. Navigate to the /azure-iot-sdk-python/azure-iot-hub/samples folder of the cloned Python SDK repository.

  3. Open the registry_manager_pnp_sample.py file and review the code. This sample shows how to use the IoTHubRegistryManager class to interact with your IoT Plug and Play device.

Note

These service samples use the IoTHubRegistryManager class from the IoT Hub service client. To learn more about the APIs, including the digital twins API, see the service developer guide.

Get the device twin

In Set up your environment for the IoT Plug and Play quickstarts and tutorials you created two environment variables to configure the sample to connect to your IoT hub and device:

  • IOTHUB_CONNECTION_STRING: the IoT hub connection string you made a note of previously.
  • IOTHUB_DEVICE_ID: "my-pnp-device".

Use the following command in the service terminal to run this sample:

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

Note

If you're running this sample on Linux, use export in place of set.

The output shows the device twin and prints its model ID:

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

The following snippet shows the sample code from 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("")

Update a device twin

This sample shows you how to update the targetTemperature writable property in the device:

    # 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("")

You can verify that the update is applied in the device terminal that shows the following output:

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

The service terminal confirms that the patch was successful:

The twin patch has been successfully applied

Invoke a command

The sample then invokes a command:

The service terminal shows a confirmation message from the device:

The device method has been successfully invoked

In the device terminal, you see the device receives the command:

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"}}

Clean up resources

If you've finished with the quickstarts and tutorials, see Clean up resources.

Next steps

In this tutorial, you learned how to connect an IoT Plug and Play device to a IoT solution. To learn more about IoT Plug and Play device models, see: