Managing Connections
All SDK API calls require a connection to a Litmus Edge instance or a Litmus Edge Manager (LEM) instance. By default the SDK builds this connection automatically from environment variables. You can also create explicit connection objects for multi-device workflows.
There are three connection modes:
- Direct LE - OAuth 2.0 to a single Litmus Edge device
- Direct LEM - API token to a Litmus Edge Manager instance (for litmussdk.lem.* calls)
- LEM Bridge - route LE calls to a managed Edge device through the Edge Manager
Direct LE Connection
Generating an OAuth 2.0 Token
- In your Litmus Edge UI navigate to System -> Access Control -> Tokens
- Press + next to API Credentials and select OAuth 2.0 Client
- Grant the token Admin permissions (lesser permissions are supported but may limit SDK functionality)
- Copy the Client ID and Client Secret
For more detail see the How to Create and Use OAuth 2.0 Tokens in Litmus Edge.
Configuration
Set the following environment variables, either in your shell or in a .env file in your working directory:
export EDGE_URL=https://<your-edge-ip>
export EDGE_API_CLIENT_ID=<client-id>
export EDGE_API_CLIENT_SECRET=<client-secret>If your device uses a self-signed TLS certificate (common in edge deployments), also set:
export VALIDATE_CERTIFICATE=false.env file example:
EDGE_URL=https://192.168.1.100
EDGE_API_CLIENT_ID=my-client-id
EDGE_API_CLIENT_SECRET=my-client-secret
VALIDATE_CERTIFICATE=falseDirect LEM Connection
For litmussdk.lem.* calls (companies, lifecycle, digital twin, etc.) that target the LEM API directly. No LE device involved.
Generating a LEM API Token
- In the Litmus Edge Manager Admin Console navigate to Settings -> Tokens -> New
- Select the appropriate scope for your use case
- Under Token Scope select the projects the token will access
- Create the token and copy it
Configuration
export EDGE_MANAGER_URL=https://<your-lem-ip>
export EDGE_API_TOKEN=<lem-api-token>LEM Bridge Connection
The LEM bridge lets the SDK communicate with individual Edge devices via the Edge Manager. Useful when the LE devices aren't directly reachable but the LEM is.
Generating a LEM API Token
- In the Litmus Edge Manager Admin Console navigate to Settings -> Tokens -> New
- Enable the Edge API Bridge scope
- Under Token Scope select the projects the token will access
- Create the token and copy it
Configuration
export USE_LEM_BRIDGE=true
export EDGE_MANAGER_URL=https://<your-lem-ip>
export EDGE_MANAGER_PROJECT_ID=<project-id>
export EDGE_MANAGER_DEVICE_ID=<device-id>
export EDGE_API_TOKEN=<lem-api-token>LE traffic is tunneled through LEM's /api/v1/edge/{project}/{device} endpoint. Authentication uses the LEM API token (the EDGE_API_TOKEN env var) sent as the X-AuthToken header.
Environment Variables Reference
Variable | Used by | Description |
|---|---|---|
EDGE_URL | Direct LE | Litmus Edge device URL |
EDGE_API_CLIENT_ID | Direct LE | OAuth 2.0 Client ID |
EDGE_API_CLIENT_SECRET | Direct LE | OAuth 2.0 Client Secret |
EDGE_MANAGER_URL | Direct LEM, LEM Bridge | Litmus Edge Manager URL |
EDGE_API_TOKEN | Direct LEM, LEM Bridge | LEM API token, sent as X-AuthToken |
EDGE_MANAGER_PROJECT_ID | LEM Bridge | Target LEM project ID |
EDGE_MANAGER_DEVICE_ID | LEM Bridge | Target Edge device ID within the project |
EDGE_MANAGER_ADMIN_URL | (optional) | LEM admin URL, currently unused |
USE_LEM_BRIDGE | LEM Bridge | Set to true to enable bridge mode |
VALIDATE_CERTIFICATE | All | false to disable TLS verification (self-signed certs) |
TIMEOUT_SECONDS | All | Request timeout in seconds. Default 30 |
Using the Default Connection
Once configured, all functions use the default connection automatically:
from litmussdk.devicehub import devices
all_devices = devices.list_devices()Managing Multiple Connections
To work with more than one device simultaneously, create explicit connection objects via the factories in litmussdk.utils.conn:
from litmussdk.utils.conn import new_le_connection
from litmussdk.devicehub import devices
# Default connection (from environment variables)
devices.list_devices()
# Explicit connection to a different device
conn_b = new_le_connection(
edge_url="https://192.168.1.100",
edge_client_id="my-client-id",
edge_client_secret="my-client-secret",
)
devices.list_devices(conn_b)Available connection factories:
- new_le_connection(edge_url, client_id, client_secret, validate_certificate=True, timeout_seconds=30): direct OAuth 2.0 connection to a Litmus Edge device.
- new_lem_connection(edge_manager_url, edge_manager_admin_url, edge_api_token, validate_certificate=True, timeout_seconds=30): direct connection to a Litmus Edge Manager instance.
- new_lem_bridge_connection(edge_manager_url, edge_api_token, project_id, device_id, validate_certificate=True, timeout_seconds=30): connection to a LE device via the LEM bridge.
Disabling and Refreshing the Default Connection
The SDK caches the default connection per type (LE / LEM) for performance. To clear the cache (for example, after rotating credentials in the env), use the corresponding refresh function:
from litmussdk.utils import conn
conn.refresh_default_le_connection() # clears the LE connection cache
conn.refresh_default_lem_connection() # clears the LEM connection cacheTo disable automatic loading of the default connection entirely:
from litmussdk import config
from litmussdk.utils import conn
config.disable_default_connection()
conn.refresh_default_le_connection()
conn.refresh_default_lem_connection()After disabling, calls without an explicit connection will raise. Re-enable with:
config.enable_default_connection()License
Copyright (c) Litmus Automation Inc.