adafruit_azureiot

Microsoft Azure IoT for CircuitPython

  • Author(s): Jim Bennett, Elena Horton

Implementation Notes

Software and Dependencies:

With ESP32 Airlift Networking

With Native Networking

class adafruit_azureiot.IoTCentralDevice(socket, iface, id_scope: str, device_id: str, device_sas_key: str, token_expires: int = 21600, logger: adafruit_logging.Logger = 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

  • 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

Parameters:

connected (bool) – 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

Parameters:
  • desired_property_name (str) – The name of the desired property that was updated

  • desired_property_value – The value of the desired property that was updated

  • desired_version (int) – 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

Parameters:
  • reported_property_name (str) – The name of the reported property that was updated

  • reported_property_value – The value of the reported property that was updated

  • reported_version (int) – The version of the reported property that was updated

direct_method_called(method_name: str, payload: str) IoTResponse

Called when a direct method is invoked

Parameters:
  • method_name (str) – The name of the method that was invoked

  • payload (str) – The payload with the message

Returns:

A response with a code and status to show if the method was correctly handled

Return type:

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

Return type:

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

Parameters:
  • property_name (str) – The name of the property to write to

  • 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

Parameters:

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: adafruit_logging.Logger = 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

Parameters:
  • body (str) – The body of the message

  • properties (dict) – 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

Parameters:

connected (bool) – 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

Parameters:
  • desired_property_name (str) – The name of the desired property that was updated

  • desired_property_value – The value of the desired property that was updated

  • desired_version (int) – 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

Parameters:
  • reported_property_name (str) – The name of the reported property that was updated

  • reported_property_value – The value of the reported property that was updated

  • reported_version (int) – The version of the reported property that was updated

direct_method_invoked(method_name: str, payload: str) IoTResponse

Called when a direct method is invoked

Parameters:
  • method_name (str) – The name of the method that was invoked

  • payload (str) – The payload with the message

Returns:

A response with a code and status to show if the method was correctly handled

Return type:

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

Return type:

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: str | dict, system_properties: dict = None) None

Send a device to cloud message from this device to Azure IoT Hub

Parameters:
  • message – The message data as a JSON string or a dictionary

  • 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: str | dict) None

Updates the reported properties in the devices device twin

Parameters:

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