Copying in code from the external repo

Author: Jim Bennett

.gitignore

@@ -8,4 +8,5 @@ bundles
 *.DS_Store
 .eggs
 dist
-**/*.egg-info
+**/*.egg-info
+.vscode/settings.json

.pylintrc

@@ -217,7 +217,7 @@ indent-after-paren=4
 indent-string='    '
 
 # Maximum number of characters on a single line.
-max-line-length=100
+max-line-length=140
 
 # Maximum number of lines in a module
 max-module-lines=1000
@@ -395,7 +395,7 @@ valid-metaclass-classmethod-first-arg=mcs
 [DESIGN]
 
 # Maximum number of arguments for function / method
-max-args=5
+max-args=6
 
 # Maximum number of attributes for a class (see R0902).
 # max-attributes=7

adafruit_azureiot.py

@@ -0,0 +1,46 @@
+# The MIT License (MIT)
+#
+# Copyright (c) 2019 Jim Bennett
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+"""
+`adafruit_azureiot`
+================================================================================
+
+Microsoft Azure IoT for CircuitPython
+
+* Author(s): Jim Bennett, Elena Horton
+
+Implementation Notes
+--------------------
+
+**Software and Dependencies:**
+
+* Adafruit CircuitPython firmware for the supported boards:
+  https://github.com/adafruit/circuitpython/releases
+
+* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
+* Adafruit's ESP32SPI library: https://github.com/adafruit/Adafruit_CircuitPython_ESP32SPI
+* Community HMAC library: https://github.com/jimbobbennett/CircuitPython_HMAC
+* Community base64 library: https://github.com/jimbobbennett/CircuitPython_Base64
+* Community Parse library: https://github.com/jimbobbennett/CircuitPython_Parse
+"""
+
+__version__ = "0.0.0-auto.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_AzureIoT.git"

adafruit_azureiot/__init__.py

@@ -0,0 +1,6 @@
+"""This file is for maintaining constants that could be changed or added to over time for different scenarios
+"""
+
+DPS_API_VERSION = "2018-11-01"
+IOTC_API_VERSION = "2016-11-14"
+DPS_END_POINT = "global.azure-devices-provisioning.net"

adafruit_azureiot/constants.py

@@ -0,0 +1,225 @@
+"""
+Device Registration
+=====================
+
+Handles registration of IoT Central devices, and gets the hostname to use when connecting
+to IoT Central over MQTT
+"""
+
+import gc
+import json
+import time
+import circuitpython_base64 as base64
+import circuitpython_hmac as hmac
+import circuitpython_parse as parse
+from adafruit_esp32spi.adafruit_esp32spi_wifimanager import ESPSPI_WiFiManager
+import adafruit_logging as logging
+from adafruit_logging import Logger
+import adafruit_hashlib as hashlib
+from . import constants
+
+
+AZURE_HTTP_ERROR_CODES = [400, 401, 404, 403, 412, 429, 500]  # Azure HTTP Status Codes
+
+
+class DeviceRegistrationError(Exception):
+    """
+    An error from the device registration
+    """
+
+    def __init__(self, message):
+        super(DeviceRegistrationError, self).__init__(message)
+        self.message = message
+
+
+class DeviceRegistration:
+    """
+    Handles registration of IoT Central devices, and gets the hostname to use when connecting
+    to IoT Central over MQTT
+    """
+
+    _dps_endpoint = constants.DPS_END_POINT
+    _dps_api_version = constants.DPS_API_VERSION
+    _loop_interval = 2
+
+    @staticmethod
+    def _parse_http_status(status_code, status_reason):
+        """Parses status code, throws error based on Azure IoT Common Error Codes.
+        :param int status_code: HTTP status code.
+        :param str status_reason: Description of HTTP status.
+        """
+        for error in AZURE_HTTP_ERROR_CODES:
+            if error == status_code:
+                raise TypeError("Error {0}: {1}".format(status_code, status_reason))
+
+    def __init__(self, wifi_manager: ESPSPI_WiFiManager, id_scope: str, device_id: str, key: str, logger: Logger = None):
+        """Creates an instance of the device registration
+        :param wifi_manager: WiFiManager object from ESPSPI_WiFiManager.
+        :param str id_scope: The ID scope of the device to register
+        :param str device_id: The device ID of the device to register
+        :param str key: The primary or secondary key of the device to register
+        :param adafruit_logging.Logger key: The primary or secondary key of the device to register
+        """
+        wifi_type = str(type(wifi_manager))
+        if "ESPSPI_WiFiManager" not in wifi_type:
+            raise TypeError("This library requires a WiFiManager object.")
+
+        self._wifi_manager = wifi_manager
+        self._id_scope = id_scope
+        self._device_id = device_id
+        self._key = key
+        self._logger = logger if logger is not None else logging.getLogger("log")
+
+    @staticmethod
+    def compute_derived_symmetric_key(secret, reg_id):
+        """Computes a derived symmetric key from a secret and a message
+        """
+        secret = base64.b64decode(secret)
+        return base64.b64encode(hmac.new(secret, msg=reg_id.encode("utf8"), digestmod=hashlib.sha256).digest())
+
+    def _loop_assign(self, operation_id, headers) -> str:
+        uri = "https://%s/%s/registrations/%s/operations/%s?api-version=%s" % (
+            self._dps_endpoint,
+            self._id_scope,
+            self._device_id,
+            operation_id,
+            self._dps_api_version,
+        )
+        self._logger.info("- iotc :: _loop_assign :: " + uri)
+        target = parse.urlparse(uri)
+
+        response = self.__run_get_request_with_retry(target.geturl(), headers)
+
+        try:
+            data = response.json()
+        except Exception as error:
+            err = "ERROR: " + str(error) + " => " + str(response)
+            self._logger.error(err)
+            raise DeviceRegistrationError(err)
+
+        loop_try = 0
+
+        if data is not None and "status" in data:
+            if data["status"] == "assigning":
+                time.sleep(self._loop_interval)
+                if loop_try < 20:
+                    loop_try = loop_try + 1
+                    return self._loop_assign(operation_id, headers)
+
+                err = "ERROR: Unable to provision the device."
+                self._logger.error(err)
+                raise DeviceRegistrationError(err)
+
+            if data["status"] == "assigned":
+                state = data["registrationState"]
+                return state["assignedHub"]
+        else:
+            data = str(data)
+
+        err = "DPS L => " + str(data)
+        self._logger.error(err)
+        raise DeviceRegistrationError(err)
+
+    def __run_put_request_with_retry(self, url, body, headers):
+        retry = 0
+        response = None
+
+        while True:
+            gc.collect()
+            try:
+                self._logger.debug("Trying to send...")
+                response = self._wifi_manager.put(url, json=body, headers=headers)
+                self._logger.debug("Sent!")
+                break
+            except RuntimeError as runtime_error:
+                self._logger.info("Could not send data, retrying after 0.5 seconds: " + str(runtime_error))
+                retry = retry + 1
+
+                if retry >= 10:
+                    self._logger.error("Failed to send data")
+                    raise
+
+                time.sleep(0.5)
+                continue
+
+        gc.collect()
+        return response
+
+    def __run_get_request_with_retry(self, url, headers):
+        retry = 0
+        response = None
+
+        while True:
+            gc.collect()
+            try:
+                self._logger.debug("Trying to send...")
+                response = self._wifi_manager.get(url, headers=headers)
+                self._logger.debug("Sent!")
+                break
+            except RuntimeError as runtime_error:
+                self._logger.info("Could not send data, retrying after 0.5 seconds: " + str(runtime_error))
+                retry = retry + 1
+
+                if retry >= 10:
+                    self._logger.error("Failed to send data")
+                    raise
+
+                time.sleep(0.5)
+                continue
+
+        gc.collect()
+        return response
+
+    def register_device(self, expiry: int) -> str:
+        """
+        Registers the device with the IoT Central device registration service.
+        Returns the hostname of the IoT hub to use over MQTT
+        :param str expiry: The expiry time
+        """
+        # pylint: disable=c0103
+        sr = self._id_scope + "%2Fregistrations%2F" + self._device_id
+        sig_no_encode = DeviceRegistration.compute_derived_symmetric_key(self._key, sr + "\n" + str(expiry))
+        sig_encoded = parse.quote(sig_no_encode, "~()*!.'")
+        auth_string = "SharedAccessSignature sr=" + sr + "&sig=" + sig_encoded + "&se=" + str(expiry) + "&skn=registration"
+
+        headers = {
+            "content-type": "application/json; charset=utf-8",
+            "user-agent": "iot-central-client/1.0",
+            "Accept": "*/*",
+        }
+
+        if auth_string is not None:
+            headers["authorization"] = auth_string
+
+        body = {"registrationId": self._device_id}
+
+        uri = "https://%s/%s/registrations/%s/register?api-version=%s" % (
+            self._dps_endpoint,
+            self._id_scope,
+            self._device_id,
+            self._dps_api_version,
+        )
+        target = parse.urlparse(uri)
+
+        self._logger.info("Connecting...")
+        self._logger.info("URL: " + target.geturl())
+        self._logger.info("body: " + json.dumps(body))
+        print("headers: " + json.dumps(headers))
+
+        response = self.__run_put_request_with_retry(target.geturl(), body, headers)
+
+        data = None
+        try:
+            data = response.json()
+        except Exception as e:
+            err = "ERROR: non JSON is received from " + self._dps_endpoint + " => " + str(response) + " .. message : " + str(e)
+            self._logger.error(err)
+            raise DeviceRegistrationError(err)
+
+        if "errorCode" in data:
+            err = "DPS => " + str(data)
+            self._logger.error(err)
+            raise DeviceRegistrationError(err)
+
+        time.sleep(1)
+        return self._loop_assign(data["operationId"], headers)

adafruit_azureiot/device_registration.py

@@ -0,0 +1,13 @@
+"""
+An error from the IoT service
+"""
+
+
+class IoTError(Exception):
+    """
+    An error from the IoT service
+    """
+
+    def __init__(self, message):
+        super(IoTError, self).__init__(message)
+        self.message = message

adafruit_azureiot/iot_error.py

@@ -0,0 +1,123 @@
+"""Connectivity to Azure IoT Central
+"""
+
+import json
+import time
+from adafruit_esp32spi.adafruit_esp32spi_wifimanager import ESPSPI_WiFiManager
+from device_registration import DeviceRegistration
+from iot_error import IoTError
+from iot_mqtt import IoTMQTT, IoTMQTTCallback, IoTResponse
+import adafruit_logging as logging
+
+
+class IoTCentralDevice(IoTMQTTCallback):
+    """A device client for the Azure IoT Central service
+    """
+
+    def connection_status_change(self, connected: bool) -> None:
+        """Called when the connection status changes
+        """
+        if self.on_connection_status_changed is not None:
+            # pylint: disable=E1102
+            self.on_connection_status_changed(connected)
+
+    # pylint: disable=W0613, R0201
+    def direct_method_called(self, method_name: str, data) -> IoTResponse:
+        """Called when a direct method is invoked
+        """
+        if self.on_command_executed is not None:
+            # pylint: disable=E1102
+            return self.on_command_executed(method_name, data)
+
+        raise IoTError("on_command_executed not set")
+
+    def device_twin_desired_updated(self, desired_property_name: str, desired_property_value, desired_version: int) -> None:
+        """Called when the device twin is updated
+        """
+        if self.on_property_changed is not None:
+            # pylint: disable=E1102
+            self.on_property_changed(desired_property_name, desired_property_value, desired_version)
+
+        # when a desired property changes, update the reported to match to keep them in sync
+        self.send_property(desired_property_name, desired_property_value)
+
+    def device_twin_reported_updated(self, reported_property_name: str, reported_property_value, reported_version: int) -> None:
+        """Called when the device twin is updated
+        """
+        if self.on_property_changed is not None:
+            # pylint: disable=E1102
+            self.on_property_changed(reported_property_name, reported_property_value, reported_version)
+
+    # pylint: disable=R0913
+    def __init__(
+        self, wifi_manager: ESPSPI_WiFiManager, id_scope: str, device_id: str, key: str, token_expires: int = 21600, logger: logging = None
+    ):
+        super(IoTCentralDevice, self).__init__()
+        self._wifi_manager = wifi_manager
+        self._id_scope = id_scope
+        self._device_id = device_id
+        self._key = key
+        self._token_expires = token_expires
+        self._logger = logger
+        self._device_registration = None
+        self._mqtt = None
+
+        self.on_connection_status_changed = None
+        self.on_command_executed = None
+        self.on_property_changed = None
+
+    def connect(self):
+        """Connects to Azure IoT Central
+        """
+        self._device_registration = DeviceRegistration(self._wifi_manager, self._id_scope, self._device_id, self._key, self._logger)
+
+        token_expiry = int(time.time() + self._token_expires)
+        hostname = self._device_registration.register_device(token_expiry)
+        self._mqtt = IoTMQTT(self, hostname, self._device_id, self._key, self._token_expires, self._logger)
+
+        self._mqtt.connect()
+
+    def disconnect(self):
+        """Disconnects from the MQTT broker
+        """
+        if self._mqtt is None:
+            raise IoTError("You are not connected to IoT Central")
+
+        self._mqtt.disconnect()
+
+    def is_connected(self) -> bool:
+        """Gets if there is an open connection to the MQTT broker
+        """
+        if self._mqtt is not None:
+            return self._mqtt.is_connected()
+
+        return False
+
+    def loop(self):
+        """Listens for MQTT messages
+        """
+        if self._mqtt is None:
+            raise IoTError("You are not connected to IoT Central")
+
+        self._mqtt.loop()
+
+    def send_property(self, property_name, data):
+        """Updates the value of a writable property
+        """
+        if self._mqtt is None:
+            raise IoTError("You are not connected to IoT Central")
+
+        patch_json = {property_name: data}
+        patch = json.dumps(patch_json)
+        self._mqtt.send_twin_patch(patch)
+
+    def send_telemetry(self, data):
+        """Sends telemetry to the IoT Central app
+        """
+        if self._mqtt is None:
+            raise IoTError("You are not connected to IoT Central")
+
+        if isinstance(data, dict):
+            data = json.dumps(data)
+
+        self._mqtt.send_device_to_cloud_message(data)

adafruit_azureiot/iot_mqtt.py

@@ -0,0 +1,171 @@
+"""Connectivity to Azure IoT Hub
+"""
+
+import json
+from iot_error import IoTError
+from iot_mqtt import IoTMQTT, IoTMQTTCallback, IoTResponse
+import adafruit_logging as logging
+
+
+def _validate_keys(connection_string_parts):
+    """Raise ValueError if incorrect combination of keys
+    """
+    host_name = connection_string_parts.get(HOST_NAME)
+    shared_access_key_name = connection_string_parts.get(SHARED_ACCESS_KEY_NAME)
+    shared_access_key = connection_string_parts.get(SHARED_ACCESS_KEY)
+    device_id = connection_string_parts.get(DEVICE_ID)
+
+    if host_name and device_id and shared_access_key:
+        pass
+    elif host_name and shared_access_key and shared_access_key_name:
+        pass
+    else:
+        raise ValueError("Invalid Connection String - Incomplete")
+
+
+DELIMITER = ";"
+VALUE_SEPARATOR = "="
+
+HOST_NAME = "HostName"
+SHARED_ACCESS_KEY_NAME = "SharedAccessKeyName"
+SHARED_ACCESS_KEY = "SharedAccessKey"
+SHARED_ACCESS_SIGNATURE = "SharedAccessSignature"
+DEVICE_ID = "DeviceId"
+MODULE_ID = "ModuleId"
+GATEWAY_HOST_NAME = "GatewayHostName"
+
+VALID_KEYS = [
+    HOST_NAME,
+    SHARED_ACCESS_KEY_NAME,
+    SHARED_ACCESS_KEY,
+    SHARED_ACCESS_SIGNATURE,
+    DEVICE_ID,
+    MODULE_ID,
+    GATEWAY_HOST_NAME,
+]
+
+
+class IoTHubDevice(IoTMQTTCallback):
+    """A device client for the Azure IoT Hub service
+    """
+
+    def connection_status_change(self, connected: bool) -> None:
+        """Called when the connection status changes
+        """
+        if self.on_connection_status_changed is not None:
+            # pylint: disable=E1102
+            self.on_connection_status_changed(connected)
+
+    # pylint: disable=W0613, R0201
+    def direct_method_called(self, method_name: str, data) -> IoTResponse:
+        """Called when a direct method is invoked
+        """
+        if self.on_direct_method_called is not None:
+            # pylint: disable=E1102
+            return self.on_direct_method_called(method_name, data)
+
+        raise IoTError("on_direct_method_called not set")
+
+    # pylint: disable=C0103
+    def cloud_to_device_message_received(self, body: str, properties: dict):
+        """Called when a cloud to device message is received
+        """
+        if self.on_cloud_to_device_message_received is not None:
+            # pylint: disable=E1102
+            self.on_cloud_to_device_message_received(body, properties)
+
+    def device_twin_desired_updated(self, desired_property_name: str, desired_property_value, desired_version: int) -> None:
+        """Called when the device twin is updated
+        """
+        if self.on_device_twin_desired_updated is not None:
+            # pylint: disable=E1102
+            self.on_device_twin_desired_updated(desired_property_name, desired_property_value, desired_version)
+
+    def device_twin_reported_updated(self, reported_property_name: str, reported_property_value, reported_version: int) -> None:
+        """Called when the device twin is updated
+        """
+        if self.on_device_twin_reported_updated is not None:
+            # pylint: disable=E1102
+            self.on_device_twin_reported_updated(reported_property_name, reported_property_value, reported_version)
+
+    def __init__(self, device_connection_string: str, token_expires: int = 21600, logger: logging = None):
+        self._token_expires = token_expires
+        self._logger = logger if logger is not None else logging.getLogger("log")
+
+        connection_string_values = {}
+
+        try:
+            cs_args = device_connection_string.split(DELIMITER)
+            connection_string_values = dict(arg.split(VALUE_SEPARATOR, 1) for arg in cs_args)
+        except (ValueError, AttributeError):
+            raise ValueError("Connection string is required and should not be empty or blank and must be supplied as a string")
+
+        if len(cs_args) != len(connection_string_values):
+            raise ValueError("Invalid Connection String - Unable to parse")
+
+        _validate_keys(connection_string_values)
+
+        self._hostname = connection_string_values[HOST_NAME]
+        self._device_id = connection_string_values[DEVICE_ID]
+        self._shared_access_key = connection_string_values[SHARED_ACCESS_KEY]
+
+        self._logger.debug("Hostname: " + self._hostname)
+        self._logger.debug("Device Id: " + self._device_id)
+        self._logger.debug("Shared Access Key: " + self._shared_access_key)
+
+        self.on_connection_status_changed = None
+        self.on_direct_method_called = None
+        self.on_cloud_to_device_message_received = None
+        self.on_device_twin_desired_updated = None
+        self.on_device_twin_reported_updated = None
+
+        self._mqtt = None
+
+    def connect(self):
+        """Connects to Azure IoT Central
+        """
+        self._mqtt = IoTMQTT(self, self._hostname, self._device_id, self._shared_access_key, self._token_expires, self._logger)
+        self._mqtt.connect()
+
+    def disconnect(self):
+        """Disconnects from the MQTT broker
+        """
+        if self._mqtt is None:
+            raise IoTError("You are not connected to IoT Central")
+
+        self._mqtt.disconnect()
+
+    def is_connected(self) -> bool:
+        """Gets if there is an open connection to the MQTT broker
+        """
+        if self._mqtt is not None:
+            return self._mqtt.is_connected()
+
+        return False
+
+    def loop(self):
+        """Listens for MQTT messages
+        """
+        if self._mqtt is None:
+            raise IoTError("You are not connected to IoT Central")
+
+        self._mqtt.loop()
+
+    def send_device_to_cloud_message(self, message, system_properties=None):
+        """Sends a device to cloud message to the IoT Hub
+        """
+        if self._mqtt is None:
+            raise IoTError("You are not connected to IoT Central")
+
+        self._mqtt.send_device_to_cloud_message(message, system_properties)
+
+    def update_twin(self, patch):
+        """Updates the reported properties in the devices device twin
+        """
+        if self._mqtt is None:
+            raise IoTError("You are not connected to IoT Central")
+
+        if isinstance(patch, dict):
+            patch = json.dumps(patch)
+
+        self._mqtt.send_twin_patch(patch)

adafruit_azureiot/iotcentral_device.py

@@ -21,7 +21,7 @@
 # Uncomment the below if you use native CircuitPython modules such as
 # digitalio, micropython and busio. List the modules you use. Without it, the
 # autodoc module docs will fail to generate with a warning.
-# autodoc_mock_imports = ["digitalio", "busio"]
+autodoc_mock_imports = ["adafruit_loging"]
 
 
 intersphinx_mapping = {

adafruit_azureiot/iothub_device.py

@@ -1,2 +1,6 @@
 Adafruit-Blinka
-Adafruit_CircuitPython_ESP32SPI
+Adafruit_CircuitPython_ESP32SPI
+Adafruit-CircuitPython-miniMQTT
+CircuitPython-HMAC
+CircuitPython-Base64
+CircuitPython-Parse

docs/conf.py

@@ -29,7 +29,7 @@
     # Author details
     author="Adafruit Industries",
     author_email="circuitpython@adafruit.com",
-    install_requires=["Adafruit-Blinka", "Adafruit_CircuitPython_ESP32SPI"],
+    install_requires=["Adafruit-Blinka", "Adafruit_CircuitPython_ESP32SPI", "Adafruit-CircuitPython-miniMQTT", "CircuitPython-HMAC", "CircuitPython-Base64", "CircuitPython-Parse"],
     # Choose your license
     license="MIT",
     # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
@@ -44,7 +44,7 @@
         "Programming Language :: Python :: 3.5",
     ],
     # What does your project relate to?
-    keywords="adafruit blinka circuitpython micropython azureiot azure, iot, device, services",
+    keywords="adafruit blinka circuitpython micropython azureiot azure iot device services, iothub, iotcentral",
     # You can just specify the packages manually here if your project is
     # simple. Or you can use find_packages().
     # TODO: IF LIBRARY FILES ARE A PACKAGE FOLDER,