This repository contains an easy to use software development kit enabling you to leverage the power of our APIs in your applications.

• See this repository's wiki for detailed documentation and example use cases

The Litmus SDK uses python version >=3.12

The SDK supports the LTS version of Litmus Edge: 3.16.x.

• Functionality in other versions is not guarenteed to work

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
• Users are strongly encouraged to use python's environment virtualization when installing the package

The SDK relies on Python >=3.12. You can install python using any of following methods:

• Head to the python downloads page
• 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

• 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:

For each official release of the SDK there will be a tagged build accessible from the releases page.

• Each release is distributed in the form of a wheel file

1. 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)

2. In your command line navigate to the directory with the wheel file.

   • e.g. litmussdk-{vesion}.whl

3. Install the module:

   • python -m pip install {file_name}.whl

4. Verify the module is correctly installed by importing the module. If the command succeeds then the module is correctly installed.

   • python -c "import litmussdk"

The SDK requires some configuration before you are able to properly connect to your Litmus Edge instance.

The SDK relies on a series of system variables in order to control configuration.

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.

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.

1. Generate an OAuth2 token
   • In your Litmus Edge instance create a an OAuth2 token
   • Keep track of the Client Secret and Client ID
2. 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}

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.

1. Generate an API token
   • Find process in our documentation
2. 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}/
3. Set the following variables
   • EDGE_MANAGER_URL={manager_url} ex. EDGE_MANAGER_URL=127.0.0.1
   • EDGE_API_TOKEN={generated_token}
   • EDGE_PROJECT_ID={project_id}
   • EDGE_DEVICE_ID={device_id}
   • USE_LEM_BRIDGE=true

There are 2 methods of setting configuration variables. Use any of the following.

1. In your root directory create a file called .env.
2. Set your configuraiton variables using the following syntax NAME=value ex. EDGE_URL=127.0.0.1
3. Run the command load_env in the root of your project

1. Set your environment variables for your shell session
   • Linux/MACOS: export NAME=value
   • Windows: not supported
2. Run the command load_env in the root of your project

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()

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.