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 tutorial 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.
You can run this tutorial on Linux or Windows. The shell commands in this tutorial follow the Linux convention for path separators '/', if you're following along on Windows be sure to swap these separators for '\'.
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 SDK for C# GitHub repository. Open a command prompt in a folder of your choice. Run the following command to clone the Microsoft Azure IoT SDK for .NET GitHub repository:
git clone https://github.com/Azure/azure-iot-sdk-csharp.git
Build the device code
You can now build the device sample and run it. Run the following commands to build the sample:
cd azure-iot-sdk-csharp/iothub/device/samples/solutions/PnpDeviceSamples/Thermostat
dotnet build
Run the device sample
To run the sample, run the following command:
dotnet run
The device is now ready to receive commands and property updates, and has started sending telemetry data to the hub. Keep the sample 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:
- IOTHUB_CONNECTION_STRING: the IoT hub connection string you made a note of previously.
- IOTHUB_DEVICE_ID:
"my-pnp-device".
In this tutorial, you use a sample IoT solution written in C# to interact with the sample device you just set up and ran.
In another terminal window, navigate to the azure-iot-sdk-csharp/iothub/service/samples/solutions/PnpServiceSamples/Thermostat folder.
Run the following command to build the service sample:
dotnet buildRun the following command to run the service sample:
dotnet run
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 tutorial 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.
You can run this tutorial on Linux or Windows. The shell commands in this tutorial follow the Linux convention for path separators '/', if you're following along on Windows be sure to swap these separators for '\'.
To complete this tutorial, install the following software in your local development 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
Navigate to the root folder of the thermostat sample in the cloned Java SDK repository and build it:
cd azure-iot-sdk-java/device/iot-device-samples/pnp-device-sample/thermostat-device-sample
mvn clean package
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.
From the /device/iot-device-samples/pnp-device-sample/thermostat-device-sample folder, run the application:
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 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:
- IOTHUB_CONNECTION_STRING: the IoT hub connection string you made a note of previously.
- IOTHUB_DEVICE_ID:
"my-pnp-device".
In this tutorial, 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.
Open another terminal window to use as your service terminal.
In the cloned Java SDK repository, navigate to the service/iot-service-samples/pnp-service-sample/thermostat-service-sample folder.
To build and run the sample service application, run the following commands:
mvn clean package mvn 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 tutorial 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 tutorial, 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 tutorial, you use a sample thermostat device that's written in Node.js as the IoT Plug and Play device. To run the sample device:
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.
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/javascript folder. Install all the dependencies by running the following command:
npm installRun the sample thermostat device with the following command:
node pnp_simple_thermostat.jsYou 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:
- IOTHUB_CONNECTION_STRING: the IoT hub connection string you made a note of previously.
- IOTHUB_DEVICE_ID:
"my-pnp-device".
In this tutorial, you use a sample Node.js IoT solution to interact with the sample device you just set up and ran.
Open another terminal window to use as your service terminal.
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
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...Go to the service terminal and use the following command to run the sample for reading device information:
node twin.jsIn 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": {} }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
Open the file twin.js in a code editor.
Review the sample code, it shows you two ways to update the device twin. To use the first way, modify the
twinPatchvariable as follows:var twinPatch = { tags: { city: "Redmond" }, properties: { desired: { targetTemperature: 42 } } };The
targetTemperatureproperty is defined as a writable property in the Thermostat device model.In the service terminal, use the following command to run the sample for updating the property:
node twin.jsIn 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 propertyIn your service terminal, run the following command to confirm the property is updated:
node twin.jsIn the service terminal output, in the
reportedproperties 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
Open the file device_method.js and review the code.
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.jsOutput 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" } }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 tutorial 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 tutorial, you need Python installed on your development machine. Check the Azure IoT Python SDK for current Python version requirements. You can check your Python version with the following command:
python --version
You can download the latest recommended version for multiple platforms from python.org.
In your local Python environment, install the azure-iot-device 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 tutorial, you use a sample thermostat device, written in Python, as the IoT Plug and Play device. To run the sample device:
Open a terminal window in a folder of your choice. Run the following command to clone the Azure IoT Device Python SDK GitHub repository into this location:
git clone --branch v2 https://github.com/Azure/azure-iot-sdk-pythonThis terminal window is used as your device terminal. Go to the folder of your cloned repository, and navigate to the azure-iot-sdk-python/samples/pnp folder.
Run the sample thermostat device with the following command:
python simple_thermostat.pyYou 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 tutorial, you use a sample IoT solution in Python to interact with the sample device you just set up.
Open another terminal window to use as your service terminal. Run the following command to clone the Azure IoT Hub Python SDK GitHub repository into this location:
git clone https://github.com/Azure/azure-iot-hub-pythonInstall the
Navigate to the /azure-iot-hub-python/samples folder of the cloned Python SDK repository.
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:
- 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: