Overview

welcome to the litmus sdk! this repository contains an easy to use software development kit enabling you to leverage the power of our apis in your applications requirements the litmus sdk uses python version >=3 12 version support the sdk supports the lts version of litmus edge 3 16 x functionality in other versions is not guarenteed to work installing the sdk the sdk is released as a python package and can be installed using multiple methods all installations assume that the user has installed python version >=3 12 and has basic familiarity with pip or other python package management tools for more information see python's official documentation https //packaging python org/en/latest/tutorials/installing packages/ users are strongly encouraged to use python's environment virtualization https //docs python org/3/library/venv html when installing the package on windows users are required to use virtual environments installing python the sdk relies on python >=3 12 you can install python using any of following methods python releases head to the python downloads page https //www python org/downloads/ select a python version >=3 12 select the download for your os once python is installed, try running python version in your command line to verify it is correctly installed microsoft store (windows specific) open the microsoft store on your machine and search for 'python' select a python version >=3 12 from the strore (e g "python 3 12") verify the author of the application is "python software foundation" press 'get' and install the application verify the installion by running python version in your command line (if this fails, try running the exact version e g python3 12 version ) to install the sdk on your device use one of the following approaches installing from release the release is available from central under a closed beta model here if you are on windows ensure you have a virtual environment installed and configured before installing the sdk each release is distributed in the form of a tar gz file download the wheel from the releases page (make sure to verify that the build is compatible with the litmus edge version you plan on running it with) in your command line navigate to the directory with the wheel file e g litmussdk 1 0 0 tar gz install the module python m pip install {file name} tar gz verify the module is correctly installed by importing the module if the command succeeds then the module is correctly installed python c "import litmussdk" configuring your installation the sdk requires some configuration before you are able to properly connect to your litmus edge instance configuring system variables the sdk relies on a series of system variables in order to control configuration variable name type description edge url string url of the edge device used if use lem bridge=false edge api token string api token to be used by the lem bridge if use lem bridge=true edge api client id string oauth2 client id to be used when directly connecting to the le instance used if use lem bridge=false edge api client secret string oauth2 client secret used when directly connecting to the le instance used if use lem bridge=false edge manager url string url of edge manager device used if use lem bridge=true edge manager project id string project id of edge device being connected to via the lem bridge used if use lem bridge=false edge manager device id string device id of edge device being connected to via the lem bridge used if use lem bridge=false use lem bridge boolean whether to directly connect to a device or connect via the litmus edge manager api bridge validate certificate boolean whether to validate target ssl certificates when making web requests to edge device is true by default timeout seconds int how many seconds for an api request times out defaults to 30 seconds in order to connect to your litmus edge device you can either connect directly to the device url or using the litmus edge manager bridge which can act as a proxy into your devices private networks configuring for direct connection if connecting directly to the edge device, ensure the network where your python script is being run has access to the edge device's network generate an oauth2 token in your litmus edge instance create a an https //docs litmus io/litmusedge v1/product features/system/tokens/create api token keep track of the client secret and client id configure the following variables edge url={device url} ex edge url=127 0 0 1 edge api client id={oauth client id} edge api client secret={oauth client secret} configuring for lem bridge if connecting to the edge device via the lem bridge, ensure that the api bridge is enabled in the target manager device note before using the lem bridge, ensure your edge device is correctly activated with edge manager generate an api token find process in our documentation https //docs litmus io/edgemanager/lem admin console/product features/admin console settings/tokens identify the project and device ids of your target edge device in litmus edge manager navigate to your device via the lem dashboard you can find the project and device ids in the url https //{lem url}/#/{project name}/{project id}/device/{device id}/ set the following variables edge manager url={manager url} ex edge manager url=127 0 0 1 edge api token={generated token} edge manager project id={project id} edge manager device id={device id} use lem bridge=true there are 3 methods of setting configuration variables use any of the following using dotenv file in your root directory create a file called env set your configuraiton variables using the following syntax name=value ex edge url=127 0 0 1 run the command load env in the root of your project using environment variables set your environment variables for your shell session linux/macos export name=value windows not supported run the command load env in the root of your project using update litmussdk config in the root of your project run the following command for each environment variable update litmussdk config name value ex update litmussdk config edge url 127 0 0 1 generating driver templates in order to use most functionality of the devicehub module run the command generate driver templates after configuring the environment variables above the devicehub module uses a custom validation layer to ensure that devices objects are locally validated against the underlying drivers before any requests are made this is an experimental feature which attempts to provide a better user experience and faster development package structure each edge service is seperated into a different sub module in the sdk package they are as follows analytics processors devicehub assert discovery devices drivers general tags digital twins flows integrations marketplace opc system certificates debugging params device management events external storage general ldap network services templates tokens users wifi utils (internal utilities not directly related to any service) api api paths env errors gql queries the encouraged convention is to import the lowest level module possible and using the module as a namespace ex from litmussdk devicehub import devices devices list devices() contribution currently the project is developed internally, public forks and contributions to the project are not supported use of the github issues page to report bugs and requested features is highly encouraged