IoTHubDeviceClient Class

A synchronous device client that connects to an Azure IoT Hub instance.

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

Inheritance
azure.iot.device.iothub.sync_clients.GenericIoTHubClient
IoTHubDeviceClient
azure.iot.device.iothub.abstract_clients.AbstractIoTHubDeviceClient
IoTHubDeviceClient

Constructor

IoTHubDeviceClient(mqtt_pipeline, http_pipeline)

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

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

create_from_sastoken

Instantiate the client from a pre-created SAS Token string

create_from_symmetric_key

Instantiate a client using symmetric key authentication.

create_from_x509_certificate

Instantiate a client using X509 certificate authentication.

disconnect

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

It is recommended that you make sure to call this function when you are completely done with the your client instance.

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

get_storage_info_for_blob

Sends a POST request over HTTP to an IoTHub endpoint that will return information for uploading via the Azure Storage Account linked to the IoTHub your device is connected to.

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.

notify_blob_upload_status

When the upload is complete, the device sends a POST request to the IoT Hub endpoint with information on the status of an upload to blob attempt. This is used by IoT Hub to notify listening clients.

patch_twin_reported_properties

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

Receive a message that has been sent from the Azure IoT Hub.

Deprecated since version 2.3.0: We recommend that you use the .on_message_received property to set a handler instead

receive_method_request

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

Deprecated since version 2.3.0: We recommend that you use the .on_method_request_received property to set a handler instead

receive_twin_desired_properties_patch

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 property 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

Deprecated since version 2.3.0: We recommend that you use the .on_twin_desired_properties_patch_received property to set a handler instead

send_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.

send_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.

shutdown

Shut down the client for graceful exit.

Once this method is called, any attempts at further client calls will result in a ClientError being raised

update_sastoken

Update the client's SAS Token used for authentication, then reauthorizes the connection.

This API can only be used if the client was initially created with a SAS Token. Note also that this API may return before the reauthorization/reconnection is completed. This means that some errors that may occur as part of the reconnection could occur in the background, and will not be raised by this method.

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

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

create_from_connection_string(connection_string, **kwargs)

Parameters

connection_string
str
Required

The connection string for the IoTHub you wish to connect to.

server_verification_cert
str
Required

Configuration Option. The trusted certificate chain. Necessary when using connecting to an endpoint which has a non-standard root of trust, such as a protocol gateway.

websockets
bool
Required

Configuration Option. Default is False. Set to true if using MQTT over websockets.

cipher
str or list(str)
Required

Configuration Option. Cipher suite(s) for TLS/SSL, as a string in "OpenSSL cipher list format" or as a list of cipher suite strings.

product_info
str
Required

Configuration Option. Default is empty string. The string contains arbitrary product info which is appended to the user agent string.

proxy_options
ProxyOptions
Required

Options for sending traffic through proxy servers.

sastoken_ttl
int
Required

The time to live (in seconds) for the created SasToken used for authentication. Default is 3600 seconds (1 hour)

keep_alive
int
Required

Maximum period in seconds between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker. If not provided default value of 60 secs will be used.

auto_connect
bool
Required

Automatically connect the client to IoTHub when a method is invoked which requires a connection to be established. (Default: True)

connection_retry
bool
Required

Attempt to re-establish a dropped connection (Default: True)

connection_retry_interval
int
Required

Interval, in seconds, between attempts to re-establish a dropped connection (Default: 10)

Returns

An instance of an IoTHub client that uses a connection string for authentication.

create_from_sastoken

Instantiate the client from a pre-created SAS Token string

create_from_sastoken(sastoken, **kwargs)

Parameters

sastoken
str
Required

The SAS Token string

server_verification_cert
str
Required

Configuration Option. The trusted certificate chain. Necessary when using connecting to an endpoint which has a non-standard root of trust, such as a protocol gateway.

websockets
bool
Required

Configuration Option. Default is False. Set to true if using MQTT over websockets.

cipher
str or list(str)
Required

Configuration Option. Cipher suite(s) for TLS/SSL, as a string in "OpenSSL cipher list format" or as a list of cipher suite strings.

product_info
str
Required

Configuration Option. Default is empty string. The string contains arbitrary product info which is appended to the user agent string.

proxy_options
ProxyOptions
Required

Options for sending traffic through proxy servers.

keep_alive
int
Required

Maximum period in seconds between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker. If not provided default value of 60 secs will be used.

auto_connect
bool
Required

Automatically connect the client to IoTHub when a method is invoked which requires a connection to be established. (Default: True)

connection_retry
bool
Required

Attempt to re-establish a dropped connection (Default: True)

connection_retry_interval
int
Required

Interval, in seconds, between attempts to re-establish a dropped connection (Default: 10)

create_from_symmetric_key

Instantiate a client using symmetric key authentication.

create_from_symmetric_key(symmetric_key, hostname, device_id, **kwargs)

Parameters

symmetric_key
Required

The symmetric key.

hostname
str
Required

Host running the IotHub. Can be found in the Azure portal in the Overview tab as the string hostname.

device_id
Required

The device ID

server_verification_cert
str
Required

Configuration Option. The trusted certificate chain. Necessary when using connecting to an endpoint which has a non-standard root of trust, such as a protocol gateway.

websockets
bool
Required

Configuration Option. Default is False. Set to true if using MQTT over websockets.

cipher
str or list(str)
Required

Configuration Option. Cipher suite(s) for TLS/SSL, as a string in "OpenSSL cipher list format" or as a list of cipher suite strings.

product_info
str
Required

Configuration Option. Default is empty string. The string contains arbitrary product info which is appended to the user agent string.

proxy_options
ProxyOptions
Required

Options for sending traffic through proxy servers.

sastoken_ttl
int
Required

The time to live (in seconds) for the created SasToken used for authentication. Default is 3600 seconds (1 hour)

keep_alive
int
Required

Maximum period in seconds between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker. If not provided default value of 60 secs will be used.

auto_connect
bool
Required

Automatically connect the client to IoTHub when a method is invoked which requires a connection to be established. (Default: True)

connection_retry
bool
Required

Attempt to re-establish a dropped connection (Default: True)

connection_retry_interval
int
Required

Interval, in seconds, between attempts to re-establish a dropped connection (Default: 10)

Returns

An instance of an IoTHub client that uses a symmetric key for authentication.

create_from_x509_certificate

Instantiate a client using X509 certificate authentication.

create_from_x509_certificate(x509, hostname, device_id, **kwargs)

Parameters

hostname
str
Required

Host running the IotHub. Can be found in the Azure portal in the Overview tab as the string hostname.

x509
X509
Required

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.

device_id
str
Required

The ID used to uniquely identify a device in the IoTHub

server_verification_cert
str
Required

Configuration Option. The trusted certificate chain. Necessary when using connecting to an endpoint which has a non-standard root of trust, such as a protocol gateway.

websockets
bool
Required

Configuration Option. Default is False. Set to true if using MQTT over websockets.

cipher
str or list(str)
Required

Configuration Option. Cipher suite(s) for TLS/SSL, as a string in "OpenSSL cipher list format" or as a list of cipher suite strings.

product_info
str
Required

Configuration Option. Default is empty string. The string contains arbitrary product info which is appended to the user agent string.

proxy_options
ProxyOptions
Required

Options for sending traffic through proxy servers.

keep_alive
int
Required

Maximum period in seconds between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker. If not provided default value of 60 secs will be used.

auto_connect
bool
Required

Automatically connect the client to IoTHub when a method is invoked which requires a connection to be established. (Default: True)

connection_retry
bool
Required

Attempt to re-establish a dropped connection (Default: True)

connection_retry_interval
int
Required

Interval, in seconds, between attempts to re-establish a dropped connection (Default: 10)

Returns

An instance of an IoTHub client that uses an X509 certificate for authentication.

disconnect

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

It is recommended that you make sure to call this function when you are completely done with the your client 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_storage_info_for_blob

Sends a POST request over HTTP to an IoTHub endpoint that will return information for uploading via the Azure Storage Account linked to the IoTHub your device is connected to.

get_storage_info_for_blob(blob_name)

Parameters

blob_name
str
Required

The name in string format of the blob that will be uploaded using the storage API. This name will be used to generate the proper credentials for Storage, and needs to match what will be used with the Azure Storage SDK to perform the blob upload.

Returns

A JSON-like (dictionary) object from IoT Hub that will contain relevant information including: correlationId, hostName, containerName, blobName, sasToken.

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

Complete Twin as a JSON dict

Return type

notify_blob_upload_status

When the upload is complete, the device sends a POST request to the IoT Hub endpoint with information on the status of an upload to blob attempt. This is used by IoT Hub to notify listening clients.

notify_blob_upload_status(correlation_id, is_success, status_code, status_description)

Parameters

correlation_id
str
Required

Provided by IoT Hub on get_storage_info_for_blob request.

is_success
bool
Required

A boolean that indicates whether the file was uploaded successfully.

status_code
int
Required

A numeric status code that is the status for the upload of the fiel to storage.

status_description
str
Required

A description that corresponds to the status_code.

patch_twin_reported_properties

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
Required

Twin Reported Properties patch as a JSON dict

Exceptions

receive_message

Receive a message that has been sent from the Azure IoT Hub.

Deprecated since version 2.3.0: We recommend that you use the .on_message_received property to set a handler instead

receive_message(block=True, timeout=None)

Parameters

block
bool
Required

Indicates if the operation should block until a message is received.

timeout
int
Required

Optionally provide a number of seconds until blocking times out.

Returns

Message that was sent from the Azure IoT Hub, or None if no method request has been received by the end of the blocking period.

Return type

receive_method_request

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

Deprecated since version 2.3.0: We recommend that you use the .on_method_request_received property to set a handler instead

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

Parameters

method_name
str
default value: None

Optionally provide the name of the method to receive requests for. If this parameter is not given, all methods not already being specifically targeted by a different request to receive_method will be received.

block
bool
default value: True

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

timeout
int
default value: None

Optionally provide a number of seconds until blocking times out.

Returns

MethodRequest object representing the received method request, or None if no method request has been received by the end of the blocking period.

receive_twin_desired_properties_patch

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 property 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

Deprecated since version 2.3.0: We recommend that you use the .on_twin_desired_properties_patch_received property to set a handler instead

receive_twin_desired_properties_patch(block=True, timeout=None)

Parameters

block
bool
default value: True

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

timeout
int
default value: None

Optionally provide a number of seconds until blocking times out.

Returns

Twin Desired Properties patch as a JSON dict, or None if no patch has been received by the end of the blocking period

Return type

dict,

send_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.

send_message(message)

Parameters

message
Message or str
Required

The actual message to send. Anything passed that is not an instance of the Message class will be converted to Message object.

Exceptions

send_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
Required

The MethodResponse to send.

Exceptions

shutdown

Shut down the client for graceful exit.

Once this method is called, any attempts at further client calls will result in a ClientError being raised

shutdown()

update_sastoken

Update the client's SAS Token used for authentication, then reauthorizes the connection.

This API can only be used if the client was initially created with a SAS Token. Note also that this API may return before the reauthorization/reconnection is completed. This means that some errors that may occur as part of the reconnection could occur in the background, and will not be raised by this method.

update_sastoken(sastoken)

Parameters

sastoken
str
Required

The new SAS Token string for the client to use

Exceptions

Attributes

connected

Read-only property to indicate if the transport is connected or not.

on_message_received

The handler function that will be called when a message is received.

The function definition should take one positional argument (the Message object)

on_method_request_received

The handler function that will be called when a method request is received.

The function definition should take one positional argument (the MethodRequest object)

on_twin_desired_properties_patch_received

The handler function that will be called when a twin desired properties patch is received.

The function definition should take one positional argument (the twin patch in the form of a JSON dictionary object)