iotconnect-lib 1.0.0__tar.gz

iotconnect_lib-1.0.0/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2020-2024 Avnet
+
+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.

iotconnect_lib-1.0.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: iotconnect-lib
+Version: 1.0.0
+Summary: Avnet IoTConnect SDK Library
+Author-email: Nik Markovic <nikola.markovic@avnet.com>
+Project-URL: Homepage, https://github.com/avnet-iotconnect/iotc-python-lib
+Keywords: IoTconnect,AWS,IoTCore,Azure,IoTHub,Greengrass
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Classifier: Topic :: Internet
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+
+> This document is reformatted to better viewing as a standalone document.
+> We recommend visiting this [GitHub v1.0.0 link](https://github.com/avnet-iotconnect/iotc-python-lib/blob/v1.0.0/) for best experience.
+
+# Introduction
+This project is the library that abstracts the /IOTCONNECT protocols for the SDKs like the
+[/IOTCONNECT Python Lite SDK](https://github.com/avnet-iotconnect/iotc-python-lite-sdk)
+and the [/IOTCONNECT Greengrass SDK](https://github.com/avnet-iotconnect/iotc-python-greengrass-sdk).
+
+This library should generally not be used in other projects as the SDKs should be able 
+to provide all the functionality that you would need in your python applications.
+
+# Features
+
+The library provides common code for interacting with /IOTCONNECT MQTT and HTTP device connectivity services:
+* Format Telemetry (Reporting) messages
+* Provide events for OTA and Command processing
+* Streamline OTA and Command acknowledgements
+* Obtain Discovery and Identity information
+
+# Using The Library
+
+To use this library in your project, ensure that your pyton project depends on iotconnect-lib.
+Use a fixed major version dependency (E.g. "iotconnect-lib<2.0.0".) to 
+avoid potential major version breaking your application calls.
+
+The best way to learn how to use this library is to examine the unit test usage examples
+in the [tests](https://github.com/avnet-iotconnect/iotc-python-lib/blob/v1.0.0/tests) directory or use the SDK implementations listed above in this document
+for reference. 
+
+# Testing
+
+Regression tests should be run with every release using pytest.   
+
+See [tests/TESTS_CONFIGURATION.md](https://github.com/avnet-iotconnect/iotc-python-lib/blob/v1.0.0/tests/TESTS_CONFIGURATION.md) for more details.
+
+# Licensing
+
+This python package is distributed under the [MIT License](https://github.com/avnet-iotconnect/iotc-python-lib/blob/v1.0.0/LICENSE.md).
+
+

iotconnect_lib-1.0.0/README.md

@@ -0,0 +1,41 @@
+
+> This document is reformatted to better viewing as a standalone document.
+> We recommend visiting this [GitHub v1.0.0 link](https://github.com/avnet-iotconnect/iotc-python-lib/blob/v1.0.0/) for best experience.
+
+# Introduction
+This project is the library that abstracts the /IOTCONNECT protocols for the SDKs like the
+[/IOTCONNECT Python Lite SDK](https://github.com/avnet-iotconnect/iotc-python-lite-sdk)
+and the [/IOTCONNECT Greengrass SDK](https://github.com/avnet-iotconnect/iotc-python-greengrass-sdk).
+
+This library should generally not be used in other projects as the SDKs should be able 
+to provide all the functionality that you would need in your python applications.
+
+# Features
+
+The library provides common code for interacting with /IOTCONNECT MQTT and HTTP device connectivity services:
+* Format Telemetry (Reporting) messages
+* Provide events for OTA and Command processing
+* Streamline OTA and Command acknowledgements
+* Obtain Discovery and Identity information
+
+# Using The Library
+
+To use this library in your project, ensure that your pyton project depends on iotconnect-lib.
+Use a fixed major version dependency (E.g. "iotconnect-lib<2.0.0".) to 
+avoid potential major version breaking your application calls.
+
+The best way to learn how to use this library is to examine the unit test usage examples
+in the [tests](https://github.com/avnet-iotconnect/iotc-python-lib/blob/v1.0.0/tests) directory or use the SDK implementations listed above in this document
+for reference. 
+
+# Testing
+
+Regression tests should be run with every release using pytest.   
+
+See [tests/TESTS_CONFIGURATION.md](https://github.com/avnet-iotconnect/iotc-python-lib/blob/v1.0.0/tests/TESTS_CONFIGURATION.md) for more details.
+
+# Licensing
+
+This python package is distributed under the [MIT License](https://github.com/avnet-iotconnect/iotc-python-lib/blob/v1.0.0/LICENSE.md).
+
+

iotconnect_lib-1.0.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "iotconnect-lib"
+dynamic = ["version"]
+description = "Avnet IoTConnect SDK Library"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Nik Markovic", email = "nikola.markovic@avnet.com" },
+]
+
+keywords = [
+    "IoTconnect",
+    "AWS",
+    "IoTCore",
+    "Azure",
+    "IoTHub",
+    "Greengrass"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications",
+    "Topic :: Internet",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+
+
+[project.urls]
+Homepage = "https://github.com/avnet-iotconnect/iotc-python-lib"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "avnet.iotconnect.sdk.sdklib.__version__"}
+
+[tool.coverage.run]
+source = ["src"]  # Basic source directory
+omit = [
+    "*/tests/*",
+    "*/__pycache__/*"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

iotconnect_lib-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

iotconnect_lib-1.0.0/src/avnet/iotconnect/sdk/sdklib/__init__.py

@@ -0,0 +1 @@
+__version__ = '1.0.0'

iotconnect_lib-1.0.0/src/avnet/iotconnect/sdk/sdklib/config.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Avnet
+# Authors: Nikola Markovic <nikola.markovic@avnet.com> et al.
+
+from .error import DeviceConfigError
+
+
+
+class DeviceProperties:
+    """
+    This class represents the /IOTCONNECT device properties
+    like device Unique ID (DUID) and account properties lke CPID, Environment etc.
+    """
+
+    def __init__(self, duid: str, cpid: str, env: str, platform: str):
+        """
+        :param platform: The IoTconnect IoT platform - Either "aws" for AWS IoTCore or "az" for Azure IoTHub
+        :param env: Your account environment. You can locate this in you IoTConnect web UI at Settings -> Key Value
+        :param cpid: Your account CPID (Company ID). You can locate this in you IoTConnect web UI at Settings -> Key Value
+        :param duid: Your Device Unique ID
+        """
+
+        self.duid = duid
+        self.cpid = cpid
+        self.env = env
+        self.platform = platform
+
+    def validate(self):
+        """ Format validation in cases where custom topic configuration may be needed """
+        if self.duid is None or len(self.duid) < 2:
+            raise DeviceConfigError('DeviceProperties: Device Unique ID (DUID) is missing')
+        if self.cpid is None or len(self.cpid) < 2:
+            raise DeviceConfigError('DeviceProperties: CPID value is missing')
+        if self.env is None or len(self.env) < 2:
+            raise DeviceConfigError('DeviceProperties: Environment value is missing')
+        if self.platform not in ("aws", "az"):
+            raise DeviceConfigError('DeviceProperties: Platform must be "aws" or "az"')

iotconnect_lib-1.0.0/src/avnet/iotconnect/sdk/sdklib/dra.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Avnet
+# Authors: Nikola Markovic <nikola.markovic@avnet.com> et al.
+
+import json
+import urllib.parse
+import urllib.request
+from typing import Final, Union, Optional
+from urllib.error import HTTPError, URLError
+
+from avnet.iotconnect.sdk.sdklib.config import DeviceProperties
+from avnet.iotconnect.sdk.sdklib.error import DeviceConfigError
+from avnet.iotconnect.sdk.sdklib.protocol.discovery import IotcDiscoveryResponseJson
+from avnet.iotconnect.sdk.sdklib.protocol.identity import ProtocolIdentityPJson, ProtocolMetaJson, ProtocolIdentityResponseJson
+from avnet.iotconnect.sdk.sdklib.util import deserialize_dataclass
+
+
+class DeviceIdentityData:
+    def __init__(self, mqtt: ProtocolIdentityPJson, metadata: ProtocolMetaJson):
+        self.host = mqtt.h
+        self.client_id = mqtt.id
+        self.username = mqtt.un
+        self.topics = mqtt.topics
+
+        self.pf = metadata.pf
+        self.is_edge_device = metadata.edge
+        self.is_gateway_device = metadata.gtw
+        self.protocol_version = str(metadata.v)
+
+class DraDiscoveryUrl:
+    method: str = "GET"  # To clarify that get should be used to parse the response
+    API_URL_FORMAT: Final[str] = "https://discovery.iotconnect.io/api/v2.1/dsdk/cpId/%s/env/%s?pf=%s"
+
+    def __init__(self, config: DeviceProperties):
+        self.config = config
+
+    def get_api_url(self) -> str:
+        return DraDiscoveryUrl.API_URL_FORMAT % (
+            urllib.parse.quote(self.config.cpid, safe=''),
+            urllib.parse.quote(self.config.env, safe=''),
+            urllib.parse.quote(self.config.platform, safe='')
+        )
+
+
+class DraIdentityUrl:
+    UID_API_URL_FORMAT: Final[str] = "%s/uid/%s"
+
+    def __init__(self, base_url):
+        self.base_url = base_url
+
+    method: str = "GET"  # To clarify that get should be used to parse the response
+
+    def get_uid_api_url(self, config: DeviceProperties) -> str:
+        return DraIdentityUrl.UID_API_URL_FORMAT % (
+            self.base_url,
+            urllib.parse.quote(config.duid, safe='')
+        )
+
+    def _validate_identity_response(self, ird: ProtocolIdentityResponseJson):
+        # TODO: validate and throw DeviceConfigError
+        pass
+
+
+class DraDeviceInfoParser:
+    EC_RESPONSE_MAPPING = [
+        "OK – No Error",
+        "Device not found. Device is not whitelisted to platform.",
+        "Device is not active.",
+        "Un-Associated. Device has not any template associated with it.",
+        "Device is not acquired. Device is created but it is in release state.",
+        "Device is disabled. It’s disabled from broker by Platform Admin",
+        "Company not found as SID is not valid",
+        "Subscription is expired.",
+        "Connection Not Allowed.",
+        "Invalid Bootstrap Certificate.",
+        "Invalid Operational Certificate."
+    ]
+
+    @classmethod
+    def _parsing_common(cls, what: str, rd: Union[IotcDiscoveryResponseJson, ProtocolIdentityResponseJson]):
+        """ Helper to parse either discovery or identity response common error fields """
+
+        ec_message = 'not available'
+        has_error = False
+        if rd.d is not None:
+            if rd.d.ec != 0:
+                has_error = True
+                if rd.d.ec <= len(cls.EC_RESPONSE_MAPPING):
+                    ec_message = 'ec=%d (%s)' % (rd.d.ec, cls.EC_RESPONSE_MAPPING[rd.d.ec])
+                else:
+                    ec_message = 'ec==%d' % rd.d.ec
+        else:
+            has_error = True
+
+        if rd.status != 200:
+            has_error = True
+
+        if has_error:
+            raise DeviceConfigError(
+                '%s failed. Error: "%s" status=%d message=%s' % (
+                    what,
+                    ec_message,
+                    rd.status,
+                    rd.message or "(message not available)"
+                )
+            )
+
+    @classmethod
+    def parse_discovery_response(cls, discovery_response: str) -> str:
+        """ Parses discovery response JSON and Returns base URL or raises DeviceConfigError """
+
+        drd: IotcDiscoveryResponseJson
+        try:
+            drd = deserialize_dataclass(IotcDiscoveryResponseJson, json.loads(discovery_response))
+        except json.JSONDecodeError as json_error:
+            raise DeviceConfigError("Discovery JSON Parsing Error: %s" % str(json_error))
+        cls._parsing_common("Discovery", drd)
+
+        if drd.d.bu is None:
+            raise DeviceConfigError("Discovery response is missing base URL")
+
+        return drd.d.bu
+
+    @classmethod
+    def parse_identity_response(cls, identity_response: str) -> DeviceIdentityData:
+        ird: ProtocolIdentityResponseJson
+        try:
+            ird = deserialize_dataclass(ProtocolIdentityResponseJson, json.loads(identity_response))
+        except json.JSONDecodeError as json_error:
+            raise DeviceConfigError("Identity JSON Parsing Error: %s" % str(json_error))
+        cls._parsing_common("Identity", ird)
+
+        return DeviceIdentityData(ird.d.p, ird.d.meta)
+
+class DeviceRestApi:
+    def __init__(self, config: DeviceProperties, verbose: Optional[bool] = False):
+        self.config = config
+        self.verbose = verbose
+
+    def get_identity_data(self) -> DeviceIdentityData:
+        try:
+            if self.verbose:
+                print("Requesting Discovery Data %s..." % DraDiscoveryUrl(self.config).get_api_url())
+            resp = urllib.request.urlopen(urllib.request.Request(DraDiscoveryUrl(self.config).get_api_url()))
+            discovery_base_url = DraDeviceInfoParser.parse_discovery_response(resp.read())
+
+            if self.verbose:
+                print("Requesting Identity Data %s..." % DraIdentityUrl(discovery_base_url).get_uid_api_url(self.config))
+            resp = urllib.request.urlopen(DraIdentityUrl(discovery_base_url).get_uid_api_url(self.config))
+            identity_response = DraDeviceInfoParser.parse_identity_response(resp.read())
+            return identity_response
+
+        except HTTPError as http_error:
+            raise DeviceConfigError(http_error)
+
+        except URLError as url_error:
+            raise DeviceConfigError(str(url_error))

iotconnect_lib-1.0.0/src/avnet/iotconnect/sdk/sdklib/error.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Avnet
+# Authors: Nikola Markovic <nikola.markovic@avnet.com> et al.
+
+class DeviceConfigError(RuntimeError):
+    def __init__(self, message: str):
+        self.msg = message
+        super().__init__(message)
+
+class ClientError(RuntimeError):
+    def __init__(self, message: str):
+        self.msg = message
+        super().__init__(message)
+
+class C2DDecodeError(RuntimeError):
+    def __init__(self, message: str):
+        self.msg = message
+        super().__init__(message)