elecnova-client 0.1.0

Python client for Elecnova ECO EMS Cloud API

Elecnova Client

Python client library for the Elecnova ECO EMS Cloud API.

Features

• 🔐 HMAC-SHA256 authentication with automatic token management
• 📦 Type-safe Pydantic models for API responses
• ⚡ Async HTTP client using httpx
• 🔄 Synchronous wrapper for non-async environments
• ✅ Comprehensive test coverage
• 🚀 Zero dependencies on specific frameworks (works with any Python application)

Installation

# From PyPI (recommended)
pip install elecnova-client

# From GitHub
pip install git+https://github.com/elektriciteit-steen/elecnova-client.git

# From source (for development)
git clone https://github.com/elektriciteit-steen/elecnova-client.git
cd elecnova-client
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Usage

Async Client

from elecnova_client import ElecnovaClient

async def main():
    client = ElecnovaClient(
        client_id="your_client_id",
        client_secret="your_client_secret"
    )

    # Fetch cabinets
    cabinets = await client.get_cabinets(page=1, page_size=100)
    for cabinet in cabinets:
        print(f"Cabinet: {cabinet.sn} - {cabinet.name}")

    # Fetch components for a cabinet
    components = await client.get_components(cabinet_sn="ESS123456")
    for component in components:
        print(f"Component: {component.sn} ({component.type})")

    # Subscribe to MQTT topics
    result = await client.subscribe_mqtt_topics(device_id="123", sn="ESS123456")

Sync Client

from elecnova_client import ElecnovaClientSync

client = ElecnovaClientSync(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

# Fetch cabinets (synchronous)
cabinets = client.get_cabinets(page=1, page_size=100)
for cabinet in cabinets:
    print(f"Cabinet: {cabinet.sn} - {cabinet.name}")

API Reference

Models

• Cabinet: ESS Cabinet data model
• Component: Component (BMS, PCS, Meter, etc.) data model
• TokenResponse: OAuth token response
• ApiResponse[T]: Generic API response wrapper

Client Methods

• get_token(): Obtain/refresh access token
• get_cabinets(page, page_size): List cabinets with pagination
• get_components(cabinet_sn): List components for a cabinet
• subscribe_mqtt_topics(device_id, sn): Subscribe to MQTT topics

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Format code
ruff format .

API Documentation

Based on Elecnova ECO EMS Cloud API Interface Document V1.2.1

• Authentication: HMAC-SHA256 with client credentials
• Token validity: 24 hours
• Rate limit: 100 requests/second
• MQTT: MQTTS protocol (port 8883)

License

LGPL-3.0-or-later