Skip to content

Latest commit

 

History

History
177 lines (129 loc) · 8.13 KB

iot-hub-python-python-module-twin-getstarted.md

File metadata and controls

177 lines (129 loc) · 8.13 KB
title description author manager ms.service services ms.devlang ms.topic ms.date ms.author
Get started with Azure IoT Hub module identity and module twin (Python) | Microsoft Docs
Learn how to create module identity and update module twin using IoT SDKs for Python.
chrissie926
iot-hub
iot-hub
python
conceptual
04/26/2018
menchi

Get started with IoT Hub module identity and module twin using Python back end and Python device

Note

Module identities and module twins are similar to Azure IoT Hub device identity and device twin, but provide finer granularity. While Azure IoT Hub device identity and device twin enable the back-end application to configure a device and provides visibility on the device’s conditions, a module identity and module twin provide these capabilities for individual components of a device. On capable devices with multiple components, such as operating system based devices or firmware devices, it allows for isolated configuration and conditions for each component.

At the end of this tutorial, you have two Python apps:

  • CreateIdentities, which creates a device identity, a module identity and associated security key to connect your device and module clients.
  • UpdateModuleTwinReportedProperties, which sends updated module twin reported properties to your IoT Hub.

Note

For information about the Azure IoT SDKs that you can use to build both applications to run on devices, and your solution back end, see Azure IoT SDKs.

To complete this tutorial, you need the following:

  • An active Azure account. (If you don't have an account, you can create a free account in just a couple of minutes.)
  • An IoT Hub.
  • Install the latest Python SDK.

You have now created your IoT hub, and you have the host name and IoT Hub connection string that you need to complete the rest of this tutorial.

Create a device identity and a module identity in IoT Hub

In this section, you create a Python app that creates a device identity and a module identity in the identity registry in your IoT hub. A device or module cannot connect to IoT hub unless it has an entry in the identity registry. For more information, see the "Identity registry" section of the IoT Hub developer guide. When you run this console app, it generates a unique ID and key for both device and module. Your device and module use these values to identify itself when it sends device-to-cloud messages to IoT Hub. The IDs are case-sensitive.

Add the following code to your Python file:

import sys
import iothub_service_client
from iothub_service_client import IoTHubRegistryManager, IoTHubRegistryManagerAuthMethod, IoTHubError

CONNECTION_STRING = "YourConnString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    # CreateDevice
    primary_key = ""
    secondary_key = ""
    auth_method = IoTHubRegistryManagerAuthMethod.SHARED_PRIVATE_KEY
    new_device = iothub_registry_manager.create_device(DEVICE_ID, primary_key, secondary_key, auth_method)
    print("new_device <" + DEVICE_ID + "> has primary key = " + new_device.primaryKey)

    # CreateModule
    new_module = iothub_registry_manager.create_module(DEVICE_ID, primary_key, secondary_key, MODULE_ID, auth_method)
    print("device/new_module <" + DEVICE_ID + "/" + MODULE_ID + "> has primary key = " + new_module.primaryKey)

except IoTHubError as iothub_error:
    print ( "Unexpected error {0}".format(iothub_error) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

This app creates a device identity with ID myFirstDevice and a module identity with ID myFirstModule under device myFirstDevice. (If that module ID already exists in the identity registry, the code simply retrieves the existing module information.) The app then displays the primary key for that identity. You use this key in the simulated module app to connect to your IoT hub.

Note

The IoT Hub identity registry only stores device and module identities to enable secure access to the IoT hub. The identity registry stores device IDs and keys to use as security credentials. The identity registry also stores an enabled/disabled flag for each device that you can use to disable access for that device. If your application needs to store other device-specific metadata, it should use an application-specific store. There is no enabled/disabled flag for module identities. For more information, see IoT Hub developer guide.

Update the module twin using Python device SDK

In this section, you create a Python app on your simulated device that updates the module twin reported properties.

  1. Get your module connection string -- now if you login to Azure portal. Navigate to your IoT Hub and click IoT Devices. Find myFirstDevice, open it and you see myFirstModule was successfuly created. Copy the module connection string. It is needed in the next step.

Azure portal module detail

  1. Create UpdateModuleTwinReportedProperties app Add the following using statements at the top of the Program.cs file:

    import sys
import iothub_service_client
from iothub_service_client import IoTHubRegistryManager, IoTHubRegistryManagerAuthMethod, IoTHubDeviceTwin, IoTHubError

CONNECTION_STRING = "FILL IN CONNECTION STRING"
DEVICE_ID = "MyFirstDevice"
MODULE_ID = "MyFirstModule"

UPDATE_JSON = "{\"properties\":{\"desired\":{\"telemetryInterval\":122}}}"

try:
    iothub_twin = IoTHubDeviceTwin(CONNECTION_STRING)

    twin_info = iothub_twin.get_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Twin before update    :" )
    print ( "{0}".format(twin_info) )

    twin_info_updated = iothub_twin.update_twin(DEVICE_ID, MODULE_ID, UPDATE_JSON)
    print ( "" )
    print ( "Twin after update     :" )
    print ( "{0}".format(twin_info_updated) )

except IoTHubError as iothub_error:
    print ( "Unexpected error {0}".format(iothub_error) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

This code sample shows you how to retrieve the module twin and update reported properties with AMQP protocol.

Get updates on the device side

In addition to the above code, you can add below code block to get the twin update message on your device.

import random
import time
import sys
import iothub_client
from iothub_client import IoTHubModuleClient, IoTHubClientError, IoTHubTransportProvider, IoTHubClientResult

PROTOCOL = IoTHubTransportProvider.AMQP
CONNECTION_STRING = ""

def module_twin_callback(update_state, payload, user_context):
    print ("")
    print ("Twin callback called with:")
    print ("updateStatus: %s" % update_state )
    print ("context: %s" % user_context )
    print ("payload: %s" % payload )

try:
    module_client = IoTHubModuleClient(CONNECTION_STRING, PROTOCOL)
    module_client.set_module_twin_callback(module_twin_callback, 1234)

    print ("Waiting for incoming twin messages.  Hit Control-C to exit.")
    while True:

        time.sleep(1000000)

except IoTHubError as iothub_error:
    print ( "Unexpected error {0}".format(iothub_error) )
except KeyboardInterrupt:
    print ( "module client sample stopped" )

Next steps

To continue getting started with IoT Hub and to explore other IoT scenarios, see: