Python SDK version 1.1

This IoTConnect Python SDK package will show you how to install and run the firmware file.

Date	Name	Download
15 January 2024	Python SDK version 1.1	Download

Getting started

Prerequisites

Before you install and run the firmware file, we recommend to check with the following set up requirements:

• Python: IoTConnect’s Python SDK supports 2.7, 3.6, 3.7 and 3.8 Python versions. However, we suggest to install the most stable
  Python version 3.7.9
• pip: pip is compatible with the Python version
• setuptools: It requires to manage the Python packages

Installation

• you can clone the full sample source code from this repository given at the Download link.
• Or run the “git clone –branch std21-patch https://github.com/avnet-iotconnect/iotc-python-sdk.git” at terminal/command prompt to get the full SDK file.
• Go to “iotc-python-sdk” directory at the path you cloned the SDK.
• If your device already has a previous IoTConnect Python SDK version, uninstall before going to install the latest version.
  

  Note: Ensure your pip version matches with the Python version you are uninstalling.
  (pip3.7,python3.7)

  pipx.x list

  • Find your package name (iotconnect-sdk)

  pipx.x uninstall <<iotconnect-sdk>>

• Use the below commands to install the required libraries:
  • Go to SDK directory path using terminal/command prompt

  cd iotconnect-python-sdk-v1.1/

  For the Python versions 3.6, 3.7 and 3.8:

  pip3 install iotconnect-sdk-1.1.tar.gz

  For the Python version 2.7:

  • Extract the iotconnect-sdk-1.1.tar.gz

  cd iotconnect-sdk/

  python setup.py install

  or go to path “iotc-python-sdk\iotconnect-sdk-1.1” and run the below command

  python .\setup.py develop

• Use the terminal/command prompt to go to the sample folder.

  cd sample/

• Edit your firmware file (iotconnect-sdk-1.0-firmware-python_msg-2_1.py) and update the following details:
  • Edit the required fields as explained in the below Prerequisite configuration (UniqueId, SId, interval)
  • If your device is secured, configure the x.509 certificate path mentioned in sdkOptions given below.
    Else, do not make any changes
  • Set your discoveryUrl as per your environment as shown below in sdkOptions
  • Configure offlineStorage in sdkOptions
  • Update sensor attributes (name and data type) exactly as added in the IoTConnect platform

Run

python3 iotconnect-sdk-1.0-firmware-python_msg-2_1.py

python iotconnect-sdk-1.0-firmware-python_msg-2_1.py

Explanation

Import the below SDK package to initialize the SDK object.

from iotconnect import IoTConnectSDK

Prerequisite configuration

#This Python SDK works with two options. Option:1 UniqueID+SId or Option:2 UniqueId+cpid+env
#If you have Option1 details then leave cpid+env details as ""
#If you have Option2 details then leave SId detail as ""
#Don't Comment or remove this veriables.
UniqueId = "<deviceUniqueId>"
SId = "<sId>"
cpid = "<cpid>"
env = "<env>"
pf = "<platform>"

• UniqueId : Your device uniqueId
• SId : SId is the company code. You can get it from the IoTConnect UI portal “Settings -> Key Vault -> SDK Identities -> select language Python and Version 1.0”
• cpid : It need to get from the IoTConnect platform “Settings->Key Vault”.
• env : It need to get from the IoTConnect platform “Settings->Key Vault”.
• pf : Set your service as az/aws

Notes:
Set either SID or CPID, As one of it is optional.

sdkOptions

SdkOptions is for the SDK configuration. It needs to parse in SDK object initialize call. Manage the below configuration as per your device authentication type.

SdkOptions={
  "certificate" : { 
    "SSLKeyPath"  : "",    #aws=pk_devicename.pem   ||   #az=device.key
    "SSLCertPath" : "",    #aws=cert_devicename.crt ||   #az=device.pem
    "SSLCaPath"   : ""     #aws=root-CA.pem         ||   #az=rootCA.pem 
        
  },
    "offlineStorage":{
        "disabled": False,
      "availSpaceInMb": 0.01,
      "fileCount": 5,
        "keepalive":60
    },
    "skipValidation":False,
    # "devicePrimaryKey":"<<DevicePrimaryKey>>",
    # "discoveryUrl":"https://eudiscovery.iotconnect.io" #Azure EU environment 
    # "discoveryUrl":"https://discovery.iotconnect.io", #Azure QA, Avnet, Prod environment 
    "discoveryUrl":"http://52.204.155.38:219", #AWS pre-QA Environment
    "IsDebug": False
   
}

sdkOptions is mandatory for “certificate” X.509 device authentication type.

Certificate

It requires the path of the certificate file. Mandatory for X.509/SSL device CA-signed or self-signed
authentication type.

• SSLKeyPath: Your device key
• SSLCertPath: your device certificate
• SSLCaPath: Root CA certificate
• Windows + Linux OS: Use “/” forward slash (Example: Windows: “E:/folder1/folder2/certificate”,
  Linux: “/home/folder1/folder2/certificate)

offlineStorage

Define the configuration related to the offline data storage.

• disabled: False = offline data storing, True = not storing offline data
• availSpaceInMb: Define the file size of offline data in MB
• fileCount: Number of files need to create for offline data

devicePrimaryKey

It is mandatory for the Symmetric Key Authentication support. You can get it from the IoTConnect UI portal
“Device -> Select device -> info(Tab) -> Connection Info -> Device Connection”

• devicePrimaryKey : “<<DevicePrimaryKey>>”

Notes:
SSL/X.509 device CA-signed or self-signed authentication type requires sdkOptions.Define the proper
certification path. If you do not provide offline storage, the firmware file will set the default settings as defined above.
The extensive data storage may harm your device. Also, once memory gets full, the SDK execution may stop.

To initialize the SDK object and connect to the cloud

with IoTConnectSDK(UniqueId,SId,SdkOptions,DeviceConectionCallback) as Sdk:

To receive the command from cloud-to-device

def DeviceCallback(msg):
  print(json.dumps(msg))
  if cmdType == 0:
  #Device comand Received 
    if "id" in data:
      if "ack" in data and data["ack"]:
      Sdk.sendAckCmd(data["ack"],7,"sucessfull",data["id"])  #fail=4,executed= 5,sucess=7,6=executedack 
      #To send ACK for gateway type device
      else:
        if "ack" in data and data["ack"]:
          Sdk.sendAckCmd(data["ack"],7,"sucessfull") #fail=4,executed= 5,sucess=7,6=executedack	
          #To send ACK for non-gateway type device

To receive the OTA command from cloud-to-device

def DeviceFirmwareCallback(msg):
  print(json.dumps(msg))
  if cmdType == 1:
    if ("urls" in data) and data["urls"]:
      for url_list in data["urls"]:
        if "tg" in url_list:
          for i in device_list:
            if "tg" in i and (i["tg"] == url_list["tg"]):
              Sdk.sendOTAAckCmd(data["ack"],0,"sucessfull",i["id"]) #Success=0, Failed = 1, Executed/DownloadingInProgress=2, Executed/DownloadDone=3, Failed/DownloadFailed=4
              #To send ACK for gateway type device
            else:
              Sdk.sendOTAAckCmd(data["ack"],0,"sucessfull") #Success=0, Failed = 1, Executed/DownloadingInProgress=2, Executed/DownloadDone=3, Failed/DownloadFailed=4
              #To send ACK for non-gateway type device

Device connect disconnect command

def DeviceConectionCallback(msg):  
  if cmdType == 116:
  #Device connection status e.g., data["command"] = true(connected) or false(disconnected)
  print(json.dumps(msg))

To receive the twin from cloud-to-device

def TwinUpdateCallback(msg):
  print(json.dumps(msg))
  sdk.UpdateTwin(key, value)

“key”: Desired property key received from Twin callback message

“value”: Value of the respective desired property

To publish the data on cloud device to cloud

def sendBackToSDK(sdk, dataArray):
sdk.SendData(dataArray)
time.sleep(interval)

To get device attributes in firmware

def attributeDetails(data):
  print ("attribute received in firmware")
  print (data)

To request the list of attributes with the respective device type

devices=sdk.GetAttributes()

Standard data input format for gateway and non-gateway device to send the data on IoTConnect

1. For non - gateway device

data = [{ "temperature": random.randint(30, 50) }
dObj = [{
"uniqueId": UniqueId,
"time": datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.000Z"),
"data": data
}]

2. For gateway and multiple child devices

dObj = [{
"uniqueId": " << Gateway Device UniqueId>>",
"time": " << date>>",
"data": { "temperature": random.randint(30, 50) }
},
{
"uniqueId": " << Child DeviceId>>",
"time": " << date>>",
"data": { "temperature": random.randint(30, 50) }
}]
sendBackToSDK(Sdk, dObj)

• time: Date format should be #”2023-01-02T10:06:17.857Z”
• data: JSON data type format # {“temperature”: 15.55, “gyroscope” : { ‘x’ : -1.2 }}

To disconnect the device from the cloud

sdk.Dispose()

To get all the twin properties: desired and reported

sdk.GetAllTwins()