adafruit_azureiot

Microsoft Azure IoT for CircuitPython

  • Author(s): Jim Bennett, Elena Horton

Implementation Notes

Software and Dependencies:

class adafruit_azureiot.IoTCentralDevice(socket, iface, id_scope: str, device_id: str, key: str, token_expires: int = 21600, logger: sphinx.ext.autodoc.mock.adafruit_logging.__qualname__ = None)

A device client for the Azure IoT Central service

connect() None

Connects to Azure IoT Central :raises DeviceRegistrationError: if the device cannot be registered successfully :raises RuntimeError: if the internet connection is not responding or is unable to connect

connection_status_change(connected: bool) None

Called when the connection status changes :param bool connected: True if the device is connected, otherwise false

device_twin_desired_updated(desired_property_name: str, desired_property_value, desired_version: int) None

Called when the device twin desired properties are updated :param str desired_property_name: The name of the desired property that was updated :param desired_property_value: The value of the desired property that was updated :param int desired_version: The version of the desired property that was updated

device_twin_reported_updated(reported_property_name: str, reported_property_value, reported_version: int) None

Called when the device twin reported values are updated :param str reported_property_name: The name of the reported property that was updated :param reported_property_value: The value of the reported property that was updated :param int reported_version: The version of the reported property that was updated

direct_method_called(method_name: str, payload: str) adafruit_azureiot.iot_mqtt.IoTResponse

Called when a direct method is invoked :param str method_name: The name of the method that was invoked :param str payload: The payload with the message :returns: A response with a code and status to show if the method was correctly handled :rtype: IoTResponse

disconnect() None

Disconnects from the MQTT broker :raises IoTError: if there is no open connection to the MQTT broker

is_connected() bool

Gets if there is an open connection to the MQTT broker :returns: True if there is an open connection, False if not :rtype: bool

loop() None

Listens for MQTT messages :raises IoTError: if there is no open connection to the MQTT broker

on_command_executed

A callback method that is called when a command is executed on the device. This method should have the following signature: def connection_status_changed(method_name: str, payload: str) -> IoTResponse:

This method returns an IoTResponse containing a status code and message from the command call. Set this appropriately depending on if the command was successfully handled or not. For example, if the command was handled successfully, set the code to 200 and message to “OK”:

return IoTResponse(200, “OK”)

on_connection_status_changed

A callback method that is called when the connection status is changed. This method should have the following signature: def connection_status_changed(connected: bool) -> None

on_property_changed

A callback method that is called when property values are updated. This method should have the following signature: def property_changed(_property_name: str, property_value, version: int) -> None

reconnect() None

Reconnects to the MQTT broker

send_property(property_name: str, value) None

Updates the value of a writable property :param str property_name: The name of the property to write to :param value: The value to set on the property :raises IoTError: if there is no open connection to the MQTT broker

send_telemetry(data) None

Sends telemetry to the IoT Central app :param data: The telemetry data to send :raises IoTError: if there is no open connection to the MQTT broker

exception adafruit_azureiot.IoTError(message: str)

An error from the IoT service

class adafruit_azureiot.IoTHubDevice(socket, iface, device_connection_string: str, token_expires: int = 21600, logger: sphinx.ext.autodoc.mock.adafruit_logging.__qualname__ = None)

A device client for the Azure IoT Hub service

cloud_to_device_message_received(body: str, properties: dict) None

Called when a cloud to device message is received :param str body: The body of the message :param dict properties: The propreties sent with the mesage

connect() None

Connects to Azure IoT Hub :raises RuntimeError: if the internet connection is not responding or is unable to connect

connection_status_change(connected: bool) None

Called when the connection status changes :param bool connected: True if the device is connected, otherwise false

device_twin_desired_updated(desired_property_name: str, desired_property_value: Any, desired_version: int) None

Called when the device twin desired properties are updated :param str desired_property_name: The name of the desired property that was updated :param desired_property_value: The value of the desired property that was updated :param int desired_version: The version of the desired property that was updated

device_twin_reported_updated(reported_property_name: str, reported_property_value: Any, reported_version: int) None

Called when the device twin reported values are updated :param str reported_property_name: The name of the reported property that was updated :param reported_property_value: The value of the reported property that was updated :param int reported_version: The version of the reported property that was updated

direct_method_invoked(method_name: str, payload: str) adafruit_azureiot.iot_mqtt.IoTResponse

Called when a direct method is invoked :param str method_name: The name of the method that was invoked :param str payload: The payload with the message :returns: A response with a code and status to show if the method was correctly handled :rtype: IoTResponse

disconnect() None

Disconnects from the MQTT broker :raises IoTError: if there is no open connection to the MQTT broker

is_connected() bool

Gets if there is an open connection to the MQTT broker :returns: True if there is an open connection, False if not :rtype: bool

loop() None

Listens for MQTT messages :raises IoTError: if there is no open connection to the MQTT broker

property on_cloud_to_device_message_received: Callable

A callback method that is called when a cloud to device message is received. This method should have the following signature: def cloud_to_device_message_received(body: str, properties: dict) -> None:

property on_connection_status_changed: Callable

A callback method that is called when the connection status is changed. This method should have the following signature: def connection_status_changed(connected: bool) -> None

property on_device_twin_desired_updated: Callable

A callback method that is called when the desired properties of the devices device twin are updated. This method should have the following signature: def device_twin_desired_updated(desired_property_name: str, desired_property_value, desired_version: int) -> None:

property on_device_twin_reported_updated: Callable

A callback method that is called when the reported properties of the devices device twin are updated. This method should have the following signature: def device_twin_reported_updated(reported_property_name: str, reported_property_value, reported_version: int) -> None:

property on_direct_method_invoked: Callable

A callback method that is called when a direct method is invoked. This method should have the following signature: def direct_method_invoked(method_name: str, payload: str) -> IoTResponse:

This method returns an IoTResponse containing a status code and message from the method invocation. Set this appropriately depending on if the method was successfully handled or not. For example, if the method was handled successfully, set the code to 200 and message to “OK”:

return IoTResponse(200, “OK”)

reconnect() None

Reconnects to the MQTT broker

send_device_to_cloud_message(message: Union[str, dict], system_properties: Optional[dict] = None) None

Send a device to cloud message from this device to Azure IoT Hub :param message: The message data as a JSON string or a dictionary :param system_properties: System properties to send with the message :raises: ValueError if the message is not a string or dictionary :raises RuntimeError: if the internet connection is not responding or is unable to connect

update_twin(patch: Union[str, dict]) None

Updates the reported properties in the devices device twin :param patch: The JSON patch to apply to the device twin reported properties

class adafruit_azureiot.IoTResponse(code: int, message: str)

A response from a direct method call