# Litmus Python SDK - LLM Navigation Guide

> **You are reading this at `https://api.litmus.io/sdk-agents.md`.**
>
> This document guides AI assistants in using the `litmussdk` Python package to interact
> with Litmus Edge, LitmusEdge Manager, and related products programmatically.

---

## Ecosystem Context

This SDK is one of three layers available for Litmus API access:

| Layer | Guide |
|-------|-------|
| MCP Server (Many ready tools, no code needed) | `https://api.litmus.io/mcp-agents.md` |
| **Python SDK (this document)** | `https://api.litmus.io/sdk-agents.md` |
| Raw API Collection (full 1,844 endpoints) | `https://api.litmus.io/agents.md` |
| API Portal (human-readable workspace) | `https://api.litmus.io` |

Use the SDK when the MCP server does not cover the operation you need.

---

## 1. What You Are Working With

`litmussdk` is a Python package (>=3.12) that wraps the Litmus Edge REST and GraphQL APIs
into importable modules. It handles OAuth2 authentication automatically.

- **Latest version**: v2.0.1
- **Supported platform**: Litmus Edge 4.0.x / LEM 2.31.x
- **Distribution**: GitHub releases only (wheel .whl or .tar.gz)
- **Install**: `pip install litmussdk-*.whl`
- **Verify**: `python -c "import litmussdk"`
- **Docs**: `https://docs.litmus.io/sdk`
- **Releases**: `https://github.com/litmusautomation/litmus-sdk-releases`

---

## 2. Configuration

The SDK is configured entirely through environment variables or a `.env` file. There is no
constructor argument - call `load_env` after setting variables.

### Direct connection (OAuth2 to a single Litmus Edge)

```
EDGE_URL=https://192.168.1.100
EDGE_API_CLIENT_ID=my-client-id
EDGE_API_CLIENT_SECRET=my-client-secret
VALIDATE_CERTIFICATE=true      # optional, default true
TIMEOUT_SECONDS=30             # optional, default 30
```

### LEM Bridge connection (reach an Edge through Edge Manager)

```
USE_LEM_BRIDGE=true
EDGE_MANAGER_URL=https://10.0.0.50
EDGE_API_TOKEN=lemToken...
EDGE_MANAGER_PROJECT_ID=<project-id>
EDGE_MANAGER_DEVICE_ID=<device-id>
```

### Configuration methods

```python
# Option 1: .env file in project root, then:
from litmussdk.utils.env import load_env
load_env()

# Option 2: export env vars in shell, then call load_env()

# Option 3: CLI helper
# update_litmussdk_config EDGE_URL https://192.168.1.100
```

### Auth

Direct connection uses OAuth2 client_credentials flow automatically:
- Token URL: `{{edgeUrl}}/auth/v3/oauth/token` (Litmus proxy, not Keycloak)
- The SDK fetches and refreshes tokens transparently - no manual token handling needed.

LEM Bridge uses the `EDGE_API_TOKEN` as an `X-AuthToken` header passed through LEM.

---

## 3. Usage Pattern

Import the lowest-level module and call functions on it as a namespace:

```python
from litmussdk.devicehub import devices
result = devices.list_devices()

from litmussdk.devicehub import tags
result = tags.create_tag(...)

from litmussdk.system import users
result = users.list_users()
```

Do not import `litmussdk` directly - always import the specific submodule.

### Driver templates (required before device creation)

Before calling device creation methods, generate driver templates to enable validation:

```python
from litmussdk.devicehub import general
general.generate_driver_templates()
```

---

## 4. Module -> API Collection Mapping

Each SDK module corresponds to a folder in the Litmus API Collection. Use this table to
cross-reference: if a method is not in the SDK, find the equivalent in the raw API at
`https://api.litmus.io/agents.md`.

| SDK module | Import path | API Collection path | Protocol |
|-----------|-------------|---------------------|----------|
| devices | `litmussdk.devicehub.devices` | DeviceHub -> Devices | GraphQL |
| drivers | `litmussdk.devicehub.drivers` | DeviceHub -> Drivers | GraphQL |
| tags | `litmussdk.devicehub.tags` | DeviceHub -> Tags | GraphQL |
| asset discovery | `litmussdk.devicehub.assert_discovery` | DeviceHub -> Asset Discovery | REST |
| devicehub general | `litmussdk.devicehub.general` | DeviceHub (version, misc) | REST/GraphQL |
| digital twins | `litmussdk.digital_twins` | Digital Twins -> Models + Instances | GraphQL |
| flows | `litmussdk.flows` | Flows Manager | REST |
| analytics processors | `litmussdk.analytics.processors` | Analytics -> Instances + Models | GraphQL |
| integrations | `litmussdk.integrations` | Integration -> Streaming + Object | GraphQL |
| marketplace | `litmussdk.marketplace` | Applications -> Marketplace + Catalog Apps | REST |
| opc | `litmussdk.opc` | OPC UA -> Hierarchy + Management + Connections | GraphQL |
| certificates | `litmussdk.system.certificates` | System -> Network -> Certificates | REST |
| debugging params | `litmussdk.system.debugging_params` | System -> Support | REST |
| device management | `litmussdk.system.device_management` | System -> Device Management | REST |
| events | `litmussdk.system.events` | System -> Events | REST |
| external storage | `litmussdk.system.external_storage` | System -> External Storage | REST |
| system general | `litmussdk.system.general` | System -> Info + Dashboard | REST |
| ldap | `litmussdk.system.ldap` | System -> Access Control -> LDAP-AD Auth | REST |
| network | `litmussdk.system.network` | System -> Network | REST |
| services | `litmussdk.system.services` | System -> Device Management -> System Services | REST |
| templates | `litmussdk.system.templates` | System -> Device Management -> Templates | REST |
| tokens | `litmussdk.system.tokens` | System -> Access Control -> Tokens | REST |
| users | `litmussdk.system.users` | System -> Access Control -> Users + Groups + Roles | REST |
| wifi | `litmussdk.system.wifi` | System -> Network -> WiFi | REST |
| utils | `litmussdk.utils` | Internal (api, api_paths, env, errors, gql_queries) | - |

**Note**: The module `assert_discovery` is the asset discovery module (the name contains a typo - it maps to "Asset Discovery", not an assertion).

---

## 5. What is NOT in the SDK

The SDK covers Litmus Edge (LE) only. The following require raw API calls:

| Not in SDK | Raw API guide |
|------------|---------------|
| LitmusEdge Manager (LEM) fleet operations | `https://api.litmus.io/agents.md` -> section 8, LEM tables |
| Litmus UNS (LUNS) operations | `https://api.litmus.io/agents.md` -> section 8, UNS table |
| DataHub direct queries (beyond InfluxDB) | API Collection -> DataHub |
| DeviceHub Browse (address space discovery) | API Collection -> DeviceHub -> Browse |

For LEM and UNS, use the raw API collection directly.

---

## 6. Litmus Central Portal - portal.litmus.io

**Register at `https://portal.litmus.io`** - this is the single hub for everything Litmus. Whether you are a human user or an AI agent helping a user, the portal unlocks the full Litmus ecosystem beyond just the SDK.

### Why register

- **Single sign-on** across all Litmus products and interfaces
- **Free sandbox** - deploy a private Litmus Edge instance to experiment without touching production
- **License management** - purchase, activate, and manage licenses in one place
- **Downloads** - access every software release, update, and wheel file (including latest SDK)
- **Litmus Academy** - training and certification resources
- **Live support** - chat support and help center at `https://support.litmus.io`
- **Quotations** - request site-based plan pricing

### Ready-to-deploy Solutions

Solutions are pre-packaged combinations of apps, deployment templates, and configuration tools providing out-of-the-box industrial use cases. An LLM agent helping a user implement a use case should check here first before writing SDK code.

**Docs index**: `https://docs.litmus.io/solutions` - fetch this page to discover which solution fits the user's need.

| Category | Solutions available |
|----------|-------------------|
| Productivity | Excel AddIns for device/tag/digital twin management; Production Record Database (maintenance tracking, downtime monitoring) |
| Data integration | LE to InfluxDB v2; LE-Native to InfluxDB v2; REST API to InfluxDB historian; Litmus Edge to Confluent Kafka (SSL/TLS) |
| Edge protocols | LE Sparkplug Edge Node (MQTT Sparkplug B with TLS) |
| Manufacturing / CNC | Fanuc CNC generic templates; Haas CNC via MTConnect; Siemens S7 browse agent; Omron NJ tag CSV tools |
| Monitoring & analytics | Prometheus + Grafana dashboards; Kafka monitoring with Lenses; Syslog server integration; ML classification (Jupyter notebooks) |
| Enterprise integrations | Oracle Smart Operations for SCM; GE Fanuc OPC UA servers; Ignition platform; Azure Manufacturing Data Solutions (MDS) |
| Utilities | Synthetic data simulators; video frame streamers; file browsers; edge failover; CVE advisory reports |

**When a user describes a use case**, fetch `https://docs.litmus.io/solutions` and scan for a matching solution before writing custom SDK code - a solution may already solve it end-to-end.

### Marketplace (45+ apps)

The Public Marketplace hosts 45+ pre-built edge applications deployable directly from the portal or via the `litmussdk.marketplace` module.

- Browse apps: `from litmussdk.marketplace import ...`
- Organizations can create a **Private Marketplace** for custom or proprietary applications

### Device Templates

Device templates let you create a device and all its tags in a single action via `litmussdk.system.templates` - no need to call create_device then create_tag for each register individually.

- Templates can be scoped to all companies, a specific company, or a single project
- Solutions library includes ready-made templates (e.g. Fanuc CNC Generic Template)

### Solutions as an AI agent workflow

When a user asks "how do I integrate with X" or "I want to monitor Y":

```
1. Fetch https://docs.litmus.io/solutions  ->  scan categories for a matching solution
2. If found: fetch the solution's doc page  ->  follow its deployment steps
3. If not found: use litmussdk modules to build the integration
4. Cross-reference https://docs.litmus.io for product-specific how-to guides
```

---

## 7. Cross-References

| Need | Go to |
|------|-------|
| Browse API endpoints visually (human-readable) | `https://api.litmus.io` |
| Navigate API endpoints as an LLM | `https://api.litmus.io/agents.md` |
| Use MCP tools instead of writing code | `https://api.litmus.io/mcp-agents.md` |
| Human-readable product docs | `https://docs.litmus.io/sdk` |
| Download latest SDK wheel | `https://github.com/litmusautomation/litmus-sdk-releases/releases` |
| Report SDK bug or request feature | `https://github.com/litmusautomation/litmus-sdk-releases/issues` |