Azure IoT Device SDK for Python

The sdklab directory contains a collection of command-line tools designed to exercise the Azure IoT SDK for Python through various testing methodologies, including end-to-end tests, stress tests, and long-haul tests.

Key characteristics of these tools:

• Purpose: They are used to validate library quality and prevent bit-rot, often by being integrated into CI/CD pipelines via run_gate_tests.py.
• Behavior: Most tools are designed to return a success value (0) 100% of the time. Tools that return a failure are specifically intended to expose known, currently unfixed issues.
• Usage Warning: While these tools demonstrate library usage, they should not be used as production samples. Some tools intentionally use undocumented knowledge, distort library behavior, or simulate extreme conditions to expose theoretical bugs or weaknesses.

The following samples demonstrate specific asynchronous and edge-specific communication patterns using the Azure IoT Hub Device SDK:

• receive_data.py: Demonstrates how to receive messages, twin patches, and method requests sent to an Edge module.
• send_message.py: Demonstrates how to send multiple telemetry messages in parallel from an Edge module to either the Azure IoT Hub or Azure IoT Edge.
• send_message_to_output.py: Demonstrates how to send multiple messages in parallel from an Edge module to a specific defined output.
• send_message_downstream.py: Demonstrates how to send messages from a downstream (or 'leaf') device to IoT Edge.

The repository contains several directories for advanced scenarios:

• async-hub-scenarios/: Complex asynchronous IoT Hub scenarios including:
  • Sending multiple telemetry messages.
  • Receiving Cloud-to-Device (C2D) messages.
  • Sending/receiving updates to device twins.
  • Receiving direct method invocations.
  • Uploading files to Azure storage.
• async-edge-scenarios/: Complex asynchronous IoT Edge scenarios including:
  • Module telemetry and input message handling.
  • Sending messages to Module Outputs.
  • Communicating from downstream/leaf devices to IoT Edge.
• sync-samples/: Samples using the synchronous client API.
• pnp/: Samples for Azure IoT Plug and Play.

The PnP samples demonstrate how devices following IoT Plug and Play conventions interact with IoT Hub or IoT Central to perform three main tasks:

1. Send telemetry
2. Update properties (both read-only and read-write)
3. Respond to command invocation

There are two primary model implementations provided in the samples:

• Thermostat Model: A single interface defining telemetry, read-only/read-write properties, and commands.
• Temperature Controller Model: A multi-component model. The top-level interface defines telemetry, a read-only property, and commands. It includes two Thermostat components and a device information component.

To use TLS 1.3 with Azure IoT Hub (currently in preview), you must use a specific connection string format. The standard connection string format (<hub name>.azure-devices.<dnsSuffix>) only supports TLS 1.0, 1.1, and 1.2.

To enable TLS 1.3 support, use the preview endpoints by modifying your connection string to include .device. or .service. as shown below:

• Device connection string: <hub name>.device.azure-devices.<dnsSuffix>
• Service connection string: <hub name>.service.azure-devices.<dnsSuffix>

The Python SDK automatically advertises support for both TLS 1.2 and TLS 1.3 in the 'Client Hello' message. When using the correct connection string, IoT Hub will negotiate and select TLS 1.3 for the connection.

# Example Device Connection String for TLS 1.3
<hub name>.device.azure-devices.<dnsSuffix>

In v2, use the Message class. Custom properties are now managed via the custom_properties dictionary rather than a properties() method. Sending is performed using the asynchronous await client.send_message(message) method.

from azure.iot.device import Message

message = Message("telemetry message")
message.message_id = "message id"
message.correlation_id = "correlation id"

# Set custom properties via dictionary
message.custom_properties["property"] = "property_value"

await client.send_message(message)

To test the receive_direct_method.py sample, use the Azure CLI to trigger a direct method request on your device.

az iot hub invoke-device-method --device-id <your device id> --hub-name <your IoT Hub name> --method-name <desired method>

If you are running aedes manually instead of via the mean time script or Docker, perform the following steps:

1. Install Node.js locally.
2. Navigate to the folder containing package.json and run npm install.
3. Generate the appropriate certificates using create_self.py.

In v2, message receiving is handled by assigning a callback function to the client.on_message_received property. The handler function receives a message object where data is accessed via .data and custom properties via .custom_properties.

# define behavior for receiving a message
def message_handler(message):
    print("the data in the message received was ")
    print(message.data)
    print("custom properties are")
    print(message.custom_properties)

# set the message handler on the client
client.on_message_received = message_handler