IoTHubModuleClient class

Definition

A synchronous module client that connects to an Azure IoT Hub or Azure IoT Edge instance.

Intended for usage with Python 2.7 or compatibility scenarios for Python 3.5.3+.

IoTHubModuleClient(iothub_pipeline, edge_pipeline=None)
Inheritance
azure.iot.device.iothub.abstract_clients.AbstractIoTHubClient
azure.iot.device.iothub.sync_clients.GenericIoTHubClient
IoTHubModuleClient
azure.iot.device.iothub.abstract_clients.AbstractIoTHubClient
azure.iot.device.iothub.abstract_clients.AbstractIoTHubModuleClient
IoTHubModuleClient

Methods

connect()

Connects the client to an Azure IoT Hub or Azure IoT Edge Hub instance.

The destination is chosen based on the credentials passed via the auth_provider parameter that was provided when this object was initialized.

This is a synchronous call, meaning that this function will not return until the connection to the service has been completely established.

create_from_connection_string(connection_string, ca_cert=None)

Instantiate the client from a IoTHub device or module connection string.

connection string with a GatewayHostName parameter.

create_from_edge_environment()

Instantiate the client from the IoT Edge environment.

This method can only be run from inside an IoT Edge container, or in a debugging environment configured for Edge development (e.g. Visual Studio, Visual Studio Code)

create_from_shared_access_signature(sas_token)

Instantiate the client from a Shared Access Signature (SAS) token.

This method of instantiation is not recommended for general usage.

create_from_x509_certificate(x509, hostname, device_id, module_id)

Instantiate a client which using X509 certificate authentication. :param hostname: Host running the IotHub. Can be found in the Azure portal in the Overview tab as the string hostname. :param x509: The complete x509 certificate object, To use the certificate the enrollment object needs to contain cert (either the root certificate or one of the intermediate CA certificates). If the cert comes from a CER file, it needs to be base64 encoded. :type x509: X509 :param device_id: The ID is used to uniquely identify a device in the IoTHub :param module_id : The ID of the module to uniquely identify a module on a device on the IoTHub. :return: A IoTHubClient which can use X509 authentication.

disconnect()

Disconnect the client from the Azure IoT Hub or Azure IoT Edge Hub instance.

This is a synchronous call, meaning that this function will not return until the connection to the service has been completely closed.

get_twin()

Gets the device or module twin from the Azure IoT Hub or Azure IoT Edge Hub service.

This is a synchronous call, meaning that this function will not return until the twin has been retrieved from the service.

patch_twin_reported_properties(reported_properties_patch)

Update reported properties with the Azure IoT Hub or Azure IoT Edge Hub service.

This is a synchronous call, meaning that this function will not return until the patch has been sent to the service and acknowledged.

If the service returns an error on the patch operation, this function will raise the appropriate error.

receive_message_on_input(input_name, block=True, timeout=None)

Receive an input message that has been sent from another Module to a specific input.

Default True. :param int timeout: Optionally provide a number of seconds until blocking times out.

receive_method_request(method_name=None, block=True, timeout=None)

Receive a method request via the Azure IoT Hub or Azure IoT Edge Hub.

If this parameter is not given, all methods not already being specifically targeted by a different request to receive_method will be received. :param bool block: Indicates if the operation should block until a request is received. Default True. :param int timeout: Optionally provide a number of seconds until blocking times out.

receive_twin_desired_properties_patch(block=True, timeout=None)

Receive a desired property patch via the Azure IoT Hub or Azure IoT Edge Hub.

This is a synchronous call, which means the following:

  1. If block=True, this function will block until one of the following happens:

    • a desired proprety patch is received from the Azure IoT Hub or Azure IoT Edge Hub.

    • the timeout period, if provided, elapses. If a timeout happens, this function will raise a InboxEmpty exception

  2. If block=False, this function will return any desired property patches which may have been received by the pipeline, but not yet returned to the application. If no desired property patches have been received by the pipeline, this function will raise an InboxEmpty exception

send_message(message)

Sends a message to the default events endpoint on the Azure IoT Hub or Azure IoT Edge Hub instance.

This is a synchronous event, meaning that this function will not return until the event has been sent to the service and the service has acknowledged receipt of the event.

If the connection to the service has not previously been opened by a call to connect, this function will open the connection before sending the event.

Message class will be converted to Message object.

send_message_to_output(message, output_name)

Sends an event/message to the given module output.

These are outgoing events and are meant to be "output events".

This is a synchronous event, meaning that this function will not return until the event has been sent to the service and the service has acknowledged receipt of the event.

If the connection to the service has not previously been opened by a call to connect, this function will open the connection before sending the event.

Message class will be converted to Message object. :param output_name: Name of the output to send the event to.

send_method_response(method_response)

Send a response to a method request via the Azure IoT Hub or Azure IoT Edge Hub.

This is a synchronous event, meaning that this function will not return until the event has been sent to the service and the service has acknowledged receipt of the event.

If the connection to the service has not previously been opened by a call to connect, this function will open the connection before sending the event.

connect()

Connects the client to an Azure IoT Hub or Azure IoT Edge Hub instance.

The destination is chosen based on the credentials passed via the auth_provider parameter that was provided when this object was initialized.

This is a synchronous call, meaning that this function will not return until the connection to the service has been completely established.

connect()

create_from_connection_string(connection_string, ca_cert=None)

Instantiate the client from a IoTHub device or module connection string.

connection string with a GatewayHostName parameter.

create_from_connection_string(connection_string, ca_cert=None)

Parameters

cls
connection_string
ca_cert
default value: None

create_from_edge_environment()

Instantiate the client from the IoT Edge environment.

This method can only be run from inside an IoT Edge container, or in a debugging environment configured for Edge development (e.g. Visual Studio, Visual Studio Code)

create_from_edge_environment()

Parameters

cls

create_from_shared_access_signature(sas_token)

Instantiate the client from a Shared Access Signature (SAS) token.

This method of instantiation is not recommended for general usage.

create_from_shared_access_signature(sas_token)

Parameters

sas_token
str

The string representation of a SAS token.

sas_token

create_from_x509_certificate(x509, hostname, device_id, module_id)

Instantiate a client which using X509 certificate authentication. :param hostname: Host running the IotHub. Can be found in the Azure portal in the Overview tab as the string hostname. :param x509: The complete x509 certificate object, To use the certificate the enrollment object needs to contain cert (either the root certificate or one of the intermediate CA certificates). If the cert comes from a CER file, it needs to be base64 encoded. :type x509: X509 :param device_id: The ID is used to uniquely identify a device in the IoTHub :param module_id : The ID of the module to uniquely identify a module on a device on the IoTHub. :return: A IoTHubClient which can use X509 authentication.

create_from_x509_certificate(x509, hostname, device_id, module_id)

Parameters

cls
x509
hostname
device_id
module_id

disconnect()

Disconnect the client from the Azure IoT Hub or Azure IoT Edge Hub instance.

This is a synchronous call, meaning that this function will not return until the connection to the service has been completely closed.

disconnect()

get_twin()

Gets the device or module twin from the Azure IoT Hub or Azure IoT Edge Hub service.

This is a synchronous call, meaning that this function will not return until the twin has been retrieved from the service.

get_twin()

Returns

Twin object which was retrieved from the hub

patch_twin_reported_properties(reported_properties_patch)

Update reported properties with the Azure IoT Hub or Azure IoT Edge Hub service.

This is a synchronous call, meaning that this function will not return until the patch has been sent to the service and acknowledged.

If the service returns an error on the patch operation, this function will raise the appropriate error.

patch_twin_reported_properties(reported_properties_patch)

Parameters

reported_properties_patch
dict or str or int or float or bool or or None (JSON compatible values)

receive_message_on_input(input_name, block=True, timeout=None)

Receive an input message that has been sent from another Module to a specific input.

Default True. :param int timeout: Optionally provide a number of seconds until blocking times out.

receive_message_on_input(input_name, block=True, timeout=None)

Parameters

input_name
block
default value: True
timeout
default value: None

Returns

Message that was sent to the specified input.

receive_method_request(method_name=None, block=True, timeout=None)

Receive a method request via the Azure IoT Hub or Azure IoT Edge Hub.

If this parameter is not given, all methods not already being specifically targeted by a different request to receive_method will be received. :param bool block: Indicates if the operation should block until a request is received. Default True. :param int timeout: Optionally provide a number of seconds until blocking times out.

receive_method_request(method_name=None, block=True, timeout=None)

Parameters

method_name
default value: None
block
default value: True
timeout
default value: None

Returns

MethodRequest object representing the received method request.

receive_twin_desired_properties_patch(block=True, timeout=None)

Receive a desired property patch via the Azure IoT Hub or Azure IoT Edge Hub.

This is a synchronous call, which means the following:

  1. If block=True, this function will block until one of the following happens:

    • a desired proprety patch is received from the Azure IoT Hub or Azure IoT Edge Hub.

    • the timeout period, if provided, elapses. If a timeout happens, this function will raise a InboxEmpty exception

  2. If block=False, this function will return any desired property patches which may have been received by the pipeline, but not yet returned to the application. If no desired property patches have been received by the pipeline, this function will raise an InboxEmpty exception

receive_twin_desired_properties_patch(block=True, timeout=None)

Parameters

block
bool

Indicates if the operation should block until a request is received. Default True.

default value: True
timeout
int

Optionally provide a number of seconds until blocking times out.

default value: None

Returns

desired property patch. This can be dict, str, int, float, bool, or None (JSON compatible values)

send_message(message)

Sends a message to the default events endpoint on the Azure IoT Hub or Azure IoT Edge Hub instance.

This is a synchronous event, meaning that this function will not return until the event has been sent to the service and the service has acknowledged receipt of the event.

If the connection to the service has not previously been opened by a call to connect, this function will open the connection before sending the event.

Message class will be converted to Message object.

send_message(message)

Parameters

message

The actual message to send. Anything passed that is not an instance of the

send_message_to_output(message, output_name)

Sends an event/message to the given module output.

These are outgoing events and are meant to be "output events".

This is a synchronous event, meaning that this function will not return until the event has been sent to the service and the service has acknowledged receipt of the event.

If the connection to the service has not previously been opened by a call to connect, this function will open the connection before sending the event.

Message class will be converted to Message object. :param output_name: Name of the output to send the event to.

send_message_to_output(message, output_name)

Parameters

message

message to send to the given output. Anything passed that is not an instance of the

output_name

send_method_response(method_response)

Send a response to a method request via the Azure IoT Hub or Azure IoT Edge Hub.

This is a synchronous event, meaning that this function will not return until the event has been sent to the service and the service has acknowledged receipt of the event.

If the connection to the service has not previously been opened by a call to connect, this function will open the connection before sending the event.

send_method_response(method_response)

Parameters

method_response
MethodResponse

The MethodResponse to send.