| author | ms.author | ms.service | ms.topic | ms.date |
|---|---|---|---|---|
dominicbetts |
dobett |
iot-pnp |
include |
10/20/2020 |
The following resources are also available:
This section shows Python examples using the IoT Hub service client and the IoTHubRegistryManager and CloudToDeviceMethod classes. You use the IoTHubRegistryManager class to interact with the device state using device twins. You can also use the IoTHubRegistryManager class to query device registrations in your IoT Hub. You use the CloudToDeviceMethod class to call commands on the device. The DTDL model for the device defines the properties and commands the device implements. In the code snippets, the device_id variable holds the device ID of the IoT Plug and Play device registered with your IoT hub.
To get the device twin and model ID of the IoT Plug and Play device that connected to your IoT hub:
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties
iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)
# ...
twin = iothub_registry_manager.get_twin(device_id)
print("The device twin is: ")
print("")
print(twin)
print("")
additional_props = twin.additional_properties
if "modelId" in additional_props:
print("The Model ID for this device is:")
print(additional_props["modelId"])
print("")The following code snippet shows how to update the targetTemperature property on a device. The sample shows how you need to get the twin's etag before you update it. The property is defined in the default component of the device:
iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)
twin = iothub_registry_manager.get_twin(device_id)
twin_patch = Twin()
twin_patch.properties = TwinProperties(
desired={"targetTemperature": 42}
)
updated_twin = iothub_registry_manager.update_twin(device_id, twin_patch, twin.etag)The following snippet shows how to update the targetTemperature property on a component. The sample shows how you need to get the twin's ETag before you update it. The property is defined in the thermostat1 component:
iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)
twin = iothub_registry_manager.get_twin(device_id)
twin_patch = Twin()
twin_patch.properties = TwinProperties(
desired={ "thermostat1": {
"__t": "c",
"targetTemperature": 42}
}
)
updated_twin = iothub_registry_manager.update_twin(device_id, twin_patch, twin.etag)For a property in a component, the property patch looks like the following example:
{
"thermostat1":
{
"__t": "c",
"targetTemperature": 20
}
}The following snippet shows how to invoke the getMaxMinReport command defined in a default component:
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod
# ...
iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)
method_payload = datetime.datetime.now() - datetime.timedelta(minutes=2)
device_method = CloudToDeviceMethod(method_name="getMaxMinReport", payload=method_payload)
result = iothub_registry_manager.invoke_device_method(device_id, device_method)
print(result.payload)The following snippet shows how to call the getMaxMinReport command on a component. The command is defined in the thermostat1 component:
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod
# ...
iothub_registry_manager = IoTHubRegistryManager(iothub_connection_str)
method_payload = datetime.datetime.now() - datetime.timedelta(minutes=2)
device_method = CloudToDeviceMethod(method_name="thermostat1*getMaxMinReport", payload=method_payload)
result = iothub_registry_manager.invoke_device_method(device_id, device_method)
print(result.payload)You use the DigitalTwinClient class to interact with the device state using digital twins. The DTDL model for the device defines the properties and commands the device implements.
The device_id variable holds the device ID of the IoT Plug and Play device registered with your IoT hub.
To get the digital twin and model ID of the IoT Plug and Play device that connected to your IoT hub:
from azure.iot.hub import DigitalTwinClient
digital_twin_client = DigitalTwinClient(iothub_connection_str)
digital_twin = digital_twin_client.get_digital_twin(device_id)
if digital_twin:
print(digital_twin)
print("Model Id: " + digital_twin["$metadata"]["$model"])
else:
print("No digital_twin found")The following code snippet shows how to update the targetTemperature property on a device. The property is defined in the default component of the device:
from azure.iot.hub import DigitalTwinClient
digital_twin_client = DigitalTwinClient(iothub_connection_str)
patch = [{"op": "add", "path": "/targetTemperature", "value": 42}]
digital_twin_client.update_digital_twin(device_id, patch)The following snippet shows how to update the targetTemperature property on a component. The property is defined in the thermostat1 component:
from azure.iot.hub import DigitalTwinClient
digital_twin_client = DigitalTwinClient(iothub_connection_str)
patch = [{"op": "add", "path": "/targetTemperature", "value": 42}]
digital_twin_client.update_digital_twin(device_id, patch)The following snippet shows how to invoke the getMaxMinReport command defined in a default component:
from azure.iot.hub import DigitalTwinClient
payload = datetime.datetime.now() - datetime.timedelta(minutes=2)
connect_timeout_in_seconds = 3
response_timeout_in_seconds = 7
digital_twin_client = DigitalTwinClient(iothub_connection_str)
invoke_command_result = digital_twin_client.invoke_command(
device_id, "getMaxMinReport", payload, connect_timeout_in_seconds, response_timeout_in_seconds
)
if invoke_command_result:
print(invoke_command_result)
else:
print("No invoke_command_result found")The following snippet shows how to call the getMaxMinReport command on a component. The command is defined in the thermostat1 component:
from azure.iot.hub import DigitalTwinClient
payload = datetime.datetime.now() - datetime.timedelta(minutes=2)
connect_timeout_in_seconds = 3
response_timeout_in_seconds = 7
digital_twin_client = DigitalTwinClient(iothub_connection_str)
invoke_command_result = digital_twin_client.invoke_component_command(
device_id, "thermostat1", "getMaxMinReport", payload, connect_timeout_in_seconds, response_timeout_in_seconds
)
if invoke_command_result:
print(invoke_command_result)
else:
print("No invoke_command_result found")IoT Plug and Play devices send the telemetry defined in the DTDL model to IoT Hub. By default, IoT Hub routes the telemetry to an Event Hubs endpoint where you can consume it. To learn more, see Use IoT Hub message routing to send device-to-cloud messages to different endpoints.
The following code snippet shows how to read the telemetry from the default Event Hubs endpoint. The code in this snippet is taken from the IoT Hub quickstart Send telemetry from a device to an IoT hub and read it with a back-end application:
import asyncio
from azure.eventhub import TransportType
from azure.eventhub.aio import EventHubConsumerClient
# Define callbacks to process events
async def on_event_batch(partition_context, events):
for event in events:
print("Received event from partition: {}.".format(partition_context.partition_id))
print("Telemetry received: ", event.body_as_str())
print("Properties (set by device): ", event.properties)
print("System properties (set by IoT Hub): ", event.system_properties)
print()
await partition_context.update_checkpoint()
async def on_error(partition_context, error):
# ...
loop = asyncio.get_event_loop()
client = EventHubConsumerClient.from_connection_string(
conn_str=CONNECTION_STR,
consumer_group="$default",
)
try:
loop.run_until_complete(client.receive_batch(on_event_batch=on_event_batch, on_error=on_error))
except KeyboardInterrupt:
print("Receiving has stopped.")
finally:
loop.run_until_complete(client.close())
loop.stop()The following output from the previous code shows the temperature telemetry sent by the no-component Thermostat IoT Plug and Play device that only has the default component. The dt-dataschema system property shows the model ID:
Received event from partition: 1.
Telemetry received: {"temperature": 12}
Properties (set by device): None
System properties (set by IoT Hub): {b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-connection-auth-method': b'{"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}', b'iothub-connection-auth-generation-id': b'637388855582764406', b'iothub-enqueuedtime': 1603288810715, b'iothub-message-source': b'Telemetry', b'dt-dataschema': b'dtmi:com:example:Thermostat;1', b'x-opt-sequence-number': 13280, b'x-opt-offset': b'12890070640', b'x-opt-enqueued-time': 1603288810824}
The following output from the previous code shows the temperature telemetry sent by the multi-component TemperatureController IoT Plug and Play device. The dt-subject system property shows the name of the component that sent the telemetry. In this example, the two components are thermostat1 and thermostat2 as defined in the DTDL model. The dt-dataschema system property shows the model ID:
Received event from partition: 1.
Telemetry received: {"temperature": 45}
Properties (set by device): None
System properties (set by IoT Hub): {b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-connection-auth-method': b'{"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}', b'iothub-connection-auth-generation-id': b'637388858939631652', b'iothub-enqueuedtime': 1603289127844, b'iothub-message-source': b'Telemetry', b'dt-subject': b'thermostat1', b'dt-dataschema': b'dtmi:com:example:TemperatureController;1', b'x-opt-sequence-number': 13328, b'x-opt-offset': b'12890095440', b'x-opt-enqueued-time': 1603289128001}
Received event from partition: 1.
Telemetry received: {"temperature": 49}
Properties (set by device): None
System properties (set by IoT Hub): {b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-connection-auth-method': b'{"scope":"device","type":"sas","issuer":"iothub","acceptingIpFilterRule":null}', b'iothub-connection-auth-generation-id': b'637388858939631652', b'iothub-enqueuedtime': 1603289133017, b'iothub-message-source': b'Telemetry', b'dt-subject': b'thermostat2', b'dt-dataschema': b'dtmi:com:example:TemperatureController;1', b'x-opt-sequence-number': 13329, b'x-opt-offset': b'12890095928', b'x-opt-enqueued-time': 1603289133173}
You can configure IoT Hub to generate device twin change notifications to route to a supported endpoint. To learn more, see Use IoT Hub message routing to send device-to-cloud messages to different endpoints > Non-telemetry events.
The code shown in the previous Python code snippet generates the following output when IoT Hub generates device twin change notifications for a no-component thermostat device. The application properties iothub-message-schema and opType give you information about the type of change notification:
Received event from partition: 1.
Telemetry received: {"version":3,"properties":{"reported":{"maxTempSinceLastReboot":10.96,"$metadata":{"$lastUpdated":"2020-10-21T14:10:42.4171263Z","maxTempSinceLastReboot":{"$lastUpdated":"2020-10-21T14:10:42.4171263Z"}},"$version":2}}}
Properties (set by device): {b'hubName': b'my-pnp-hub', b'deviceId': b'my-pnp-device', b'operationTimestamp': b'2020-10-21T14:10:42.4171263+00:00', b'iothub-message-schema': b'twinChangeNotification', b'opType': b'updateTwin'}
System properties (set by IoT Hub): {b'user-id': b'my-pnp-hub\x81\x0e\xa4\x7f', b'correlation-id': b'12104ced5402', b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-enqueuedtime': 1603289442519, b'iothub-message-source': b'twinChangeEvents', b'x-opt-sequence-number': 13332, b'x-opt-offset': b'12890097392', b'x-opt-enqueued-time': 1603289442738}
The code shown in the previous Python code snippet generates the following output when IoT Hub generates device twin change notifications for a device with components. This example shows the output when a temperature sensor device with a thermostat component generates notifications. The application properties iothub-message-schema and opType give you information about the type of change notification:
Received event from partition: 1.
Telemetry received: {"version":4,"properties":{"reported":{"thermostat1":{"maxTempSinceLastReboot":98.34,"__t":"c"},"$metadata":{"$lastUpdated":"2020-10-21T14:13:39.36491Z","thermostat1":{"$lastUpdated":"2020-10-21T14:13:39.36491Z","maxTempSinceLastReboot":{"$lastUpdated":"2020-10-21T14:13:39.36491Z"},"__t":{"$lastUpdated":"2020-10-21T14:13:39.36491Z"}}},"$version":3}}}
Properties (set by device): {b'hubName': b'my-pnp-hub', b'deviceId': b'my-pnp-device', b'operationTimestamp': b'2020-10-21T14:13:39.3649100+00:00', b'iothub-message-schema': b'twinChangeNotification', b'opType': b'updateTwin'}
System properties (set by IoT Hub): {b'user-id': b'my-pnp-hub', b'correlation-id': b'1210b664ab83', b'content-type': b'application/json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-enqueuedtime': 1603289619481, b'iothub-message-source': b'twinChangeEvents', b'x-opt-sequence-number': 13341, b'x-opt-offset': b'12890102216', b'x-opt-enqueued-time': 1603289619668}
You can configure IoT Hub to generate digital twin change notifications to route to a supported endpoint. To learn more, see Use IoT Hub message routing to send device-to-cloud messages to different endpoints > Non-telemetry events.
The code shown in the previous Python code snippet generates the following output when IoT Hub generates digital twin change notifications for a no-component thermostat device. The application properties iothub-message-schema and opType give you information about the type of change notification:
Received event from partition: 1.
Telemetry received: [{"op":"add","path":"/$metadata/maxTempSinceLastReboot","value":{"lastUpdateTime":"2020-10-21T14:10:42.4171263Z"}},{"op":"add","path":"/maxTempSinceLastReboot","value":10.96}]
Properties (set by device): {b'hubName': b'my-pnp-hub', b'deviceId': b'my-pnp-device', b'operationTimestamp': b'2020-10-21T14:10:42.4171263+00:00', b'iothub-message-schema': b'digitalTwinChangeNotification', b'opType': b'updateTwin'}
System properties (set by IoT Hub): {b'user-id': b'my-pnp-hub\x81\x0e\xa4\x7f', b'correlation-id': b'12104ced5402', b'content-type': b'application/json-patch+json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-enqueuedtime': 1603289442519, b'iothub-message-source': b'digitalTwinChangeEvents', b'x-opt-sequence-number': 13333, b'x-opt-offset': b'12890098024', b'x-opt-enqueued-time': 1603289442738}
The code shown in the previous Python code snippet generates the following output when IoT Hub generates digital twin change notifications for a device with components. This example shows the output when a temperature sensor device with a thermostat component generates notifications. The application properties iothub-message-schema and opType give you information about the type of change notification:
Received event from partition: 1.
Telemetry received: [{"op":"add","path":"/thermostat1","value":{"$metadata":{"maxTempSinceLastReboot":{"lastUpdateTime":"2020-10-21T14:13:39.36491Z"}},"maxTempSinceLastReboot":98.34}}]
Properties (set by device): {b'hubName': b'my-pnp-hub', b'deviceId': b'my-pnp-device', b'operationTimestamp': b'2020-10-21T14:13:39.3649100+00:00', b'iothub-message-schema': b'digitalTwinChangeNotification', b'opType': b'updateTwin'}
System properties (set by IoT Hub): {b'user-id': b'my-pnp-hub', b'correlation-id': b'1210b664ab83', b'content-type': b'application/json-patch+json', b'content-encoding': b'utf-8', b'iothub-connection-device-id': b'my-pnp-device', b'iothub-enqueuedtime': 1603289619481, b'iothub-message-source': b'digitalTwinChangeEvents', b'x-opt-sequence-number': 13342, b'x-opt-offset': b'12890102984', b'x-opt-enqueued-time': 1603289619668}