iot-hub-howto-cloud-to-device-messaging-python.md

author	SoniaLopezBravo
ms.author	sonialopez
ms.service	azure-iot-hub
ms.devlang	python
ms.topic	include
ms.date	12/19/2024
ms.custom	mqtt devx-track-python py-fresh-zinc sfi-ropc-nochange

Create a device application

This section describes how to receive cloud-to-device messages.

The IoTHubDeviceClient class includes methods to create a synchronous connection from a device to an Azure IoT Hub and receive messages from IoT Hub.

The azure-iot-device library must be installed to create device applications.

pip install azure-iot-device

For a Python-based device application to receive cloud-to-device messages, it must connect to IoT Hub and then set up a callback message handler to process incoming messages from IoT Hub.

Device import statement

Add this code to import the IoTHubDeviceClient functions from the azure.iot.device SDK.

from azure.iot.device import IoTHubDeviceClient

Connect a device to IoT Hub

A device app can authenticate with IoT Hub using the following methods:

• Shared access key
• X.509 certificate

[!INCLUDE iot-authentication-device-connection-string.md]

Authenticate using a shared access key

To connect a device to IoT Hub:

1. Call create_from_connection_string to add the device primary connection string.
2. Call connect to connect the device client.

For example:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Authenticate using an X.509 certificate

[!INCLUDE iot-hub-howto-auth-device-cert-python]

Handle reconnection

IoTHubDeviceClient will by default attempt to reestablish a dropped connection. Reconnection behavior is governed by the IoTHubDeviceClient connection_retry and connection_retry_interval parameters.

Create a message handler

Create a message handler function to process incoming messages to the device. This will be assigned by on_message_received (next step) as the callback message handler.

In this example, message_handler is called when a message is received. The message properties (.items) are printed to the console using a loop.

def message_handler(message):
    global RECEIVED_MESSAGES
    RECEIVED_MESSAGES += 1
    print("")
    print("Message received:")

    # print data from both system and application (custom) properties
    for property in vars(message).items():
        print ("    {}".format(property))

    print("Total calls received: {}".format(RECEIVED_MESSAGES))

Assign the message handler

Use the on_message_received method to assign the message handler method.

In this example, a message handler method named message_handler is attached to the IoTHubDeviceClient client object. The client object waits to receive a cloud-to-device message from an IoT Hub. This code waits up to 300 seconds (5 minutes) for a message, or exits if a keyboard key is pressed.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

SDK receive message sample

Receive Message - Receive Cloud-to-Device (C2D) messages sent from the Azure IoT Hub to a device.

Create a backend application

This section describes how to send a cloud-to-device message. A solution backend application connects to an IoT Hub and messages are sent to IoT Hub encoded with a destination device. IoT Hub stores incoming messages to its message queue, and messages are delivered from the IoT Hub message queue to the target device.

The IoTHubRegistryManager class exposes all methods required to create a backend application to interact with cloud-to-device messages from the service. The azure-iot-hub library must be installed to create backend service applications.

pip install azure-iot-hub

Import the IoTHubRegistryManager object

Add the following import statement. IoTHubRegistryManager includes APIs for IoT Hub Registry Manager operations.

from azure.iot.hub import IoTHubRegistryManager

Connect to IoT hub

You can connect a backend service to IoT Hub using the following methods:

• Shared access policy
• Microsoft Entra

[!INCLUDE iot-authentication-service-connection-string.md]

Connect using a shared access policy

Connect to IoT hub using from_connection_string.

For example:

IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

Connect using Microsoft Entra

[!INCLUDE iot-hub-howto-connect-service-iothub-entra-python]

Build and send a message

Use send_c2d_message to send a message through the cloud (IoT Hub) to the device.

send_c2d_message uses these parameters:

• deviceID - The string identifier of the target device.
• message - The cloud-to-device message. The message is of type str (string).
• properties - An optional collection of properties of type dict. Properties can contain application properties and system properties. The default value is {}.

This example sends a test message to the target device.

# define the device ID
deviceID = "Device-1"

# define the message
message = "{\"c2d test message\"}"

# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)

# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)

SDK send message sample

The Azure IoT SDK for Python provides a working sample of a service app that demonstrates how to send a cloud-to-device message. For more information, see send_message.py demonstrates how to send a cloud-to-device message.