Python Client for ClearBlade IoT Core API

Quick start

To use this library, you first need to go through the following steps:

1. Install pip package - `pip install clearblade-cloud-iot`
2. Set an environment variable CLEARBLADE_CONFIGURATION, pointing to your ClearBlade service account JSON file. Look here for how to create a service account and download a credentials JSON file.
3. Optionally set an environment variable BINARYDATA_AND_TIME_GOOGLE_FORMAT to True. Look at Note about types of times and binaryData below for details.

Installation

Install this library in a virtualenv using pip. virtualenv is a tool to create isolated Python environments. It addresses dependencies and versions and, indirectly, permissions.

With virtualenv, it's possible to install this library without system install permissions and clashing with the installed system dependencies.

Code samples and snippets

Code samples and snippets live in the samples/clearblade folder.

Supported Python versions

Our client libraries are compatible with all current active and maintenance versions of Python.

Python >= 3.7

Unsupported Python versions

Python <= 3.6

If you are using an end-of-life version of Python, we recommend you update it to an actively supported version as soon as possible.

Mac/Linux

pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate

Windows

pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate

Next steps

• Clone the GitHub repository.
• Execute the setup.py file like Python setup.py install.
• Everything else should work if you change your imports from google.cloud to clearblade.cloud.

Note about types of times and binaryData

• By default, the following parameters are returned as the shown types:

1. All time parameters (e.g. cloudUpdateTime, deviceAckTime, updateTime): RFC3339 strings (e.g. "2023-01-12T23:38:07.732Z")
2. CONFIG binaryData: base64-encoded string
3. STATE binaryData: NON-base64-encoded string

• To return these parameters using the same types used by the Google IoTCore Python SDK, set environment variable BINARYDATA_AND_TIME_GOOGLE_FORMAT to True (case-insensitive string). This will ensure the following parameters are returned as the shown types:

1. All times: DatetimeWithNanoseconds (defined in the proto.datetime_helpers module)
2. All binaryData (CONFIG, STATE etc.): BYTE ARRAYS

• If this environment variable is not set, or is set to any unexpected values, then the default types listed previously are used.

Note about performance:

• By default, calls to some SDK functions cause a REST request to be sent to acquire the registry API keys found on the IoTCore UI Registry Details page. Those keys are cached for subsequent operations to improve performance. However, these caches do not persist if the application is stopped and restarted, as would be the case with typical serverless functions (e.g., Google Cloud Functions, AWS Lambda, etc.). To improve those functions' performance, the REST call can be prevented by passing the API keys as environment variables:

1. REGISTRY_URL: string
2. REGISTRY_SYSKEY: string
3. REGISTRY_TOKEN: string

Note about running from the source instead of the PyPi (pip) module:

• To temporarily use the source code in this repo instead of the installed PyPi (pip) module, do the following:

1. Clone this repo.
2. Check out the desired branch using git checkout <branch>.
3. In your code find where clearblade or clearblade.cloud is being imported.
4. Precede that line with import sys and sys.path.insert(0, <path_to_python-iot>). The path must end with python-iot. For example:

import sys
sys.path.insert(0, "path/to/python-iot")

from clearblade.cloud import iot_v1