SPAN Panel API Client

A Python client library for SPAN Panel smart electrical panels. Supports both Gen2 panels (REST/OpenAPI) and Gen3 panels (gRPC — MAIN40/MLO48).

Installation

# Core library — Gen2 panels (REST/OpenAPI)
pip install span-panel-api

# With Gen3 gRPC support
pip install span-panel-api[grpc]

Quick Start

Use create_span_client to connect to a panel without knowing its generation in advance. The factory auto-detects Gen2 vs Gen3 and returns the appropriate client.

import asyncio
from span_panel_api import create_span_client

async def main():
    client = await create_span_client("192.168.1.100")
    await client.connect()

    snapshot = await client.get_snapshot()
    print(f"Panel: {snapshot.serial_number}  ({snapshot.panel_generation})")
    print(f"Grid power: {snapshot.main_power_w:.0f} W")

    for circuit_id, circuit in snapshot.circuits.items():
        print(f"  [{circuit_id}] {circuit.name}: {circuit.power_w:.0f} W")

    await client.close()

asyncio.run(main())

To target a specific generation, pass panel_generation explicitly:

from span_panel_api import create_span_client, PanelGeneration

# Force Gen2 (REST/OpenAPI)
client = await create_span_client("192.168.1.100", panel_generation=PanelGeneration.GEN2)

# Force Gen3 (gRPC) — requires span-panel-api[grpc]
client = await create_span_client("192.168.1.100", panel_generation=PanelGeneration.GEN3)

Gen2 vs Gen3 Capabilities

Feature	Gen2 (REST/OpenAPI)	Gen3 (gRPC)
Authentication	Required (JWT)	None
Circuit relay control	Yes	No
Circuit priority control	Yes	No
Energy history (Wh)	Yes	No
Battery / storage SOE	Yes	No
Solar / DSM state	Yes	No
Real-time power metrics	Polled	Push-streamed
Simulation mode	Yes	No

Use client.capabilities (a PanelCapability flag set) at runtime to guard optional features:

from span_panel_api import PanelCapability

if PanelCapability.RELAY_CONTROL in client.capabilities:
    await client.set_circuit_relay("1", "OPEN")

if PanelCapability.PUSH_STREAMING in client.capabilities:
    await client.start_streaming()

Documentation

Topic	Link
Gen2 REST/OpenAPI client — usage, auth, API reference, caching	docs/gen2-client.md
Gen3 gRPC client — usage, streaming, data models	docs/gen3-client.md
Error handling and retry strategies	docs/error-handling.md
Simulation mode	docs/simulation.md
Development setup and contributing	docs/development.md

License

MIT License - see LICENSE for details.