https://github.com/spanpanel/span-panel-api
Python API client for SPAN Panel - provides async interface to control circuits, monitor power usage, and manage panel settings
https://github.com/spanpanel/span-panel-api
api-client async home-assistant openapi pypi python span-panel
Last synced: about 1 month ago
JSON representation
Python API client for SPAN Panel - provides async interface to control circuits, monitor power usage, and manage panel settings
- Host: GitHub
- URL: https://github.com/spanpanel/span-panel-api
- Owner: SpanPanel
- License: mit
- Created: 2025-06-01T21:14:27.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-06-26T20:00:18.000Z (9 months ago)
- Last Synced: 2025-06-26T20:20:34.262Z (9 months ago)
- Topics: api-client, async, home-assistant, openapi, pypi, python, span-panel
- Language: Python
- Size: 480 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# SPAN Panel API Client
[](https://github.com/SpanPanel/span-panel-api/releases)
[](https://pypi.org/project/span-panel-api/)
[](https://pypi.org/project/span-panel-api/)
[](https://github.com/SpanPanel/span-panel-api/blob/main/LICENSE)
[](https://github.com/SpanPanel/span-panel-api/actions/workflows/ci.yml)
[](https://www.codefactor.io/repository/github/spanpanel/span-panel-api)
[](https://snyk.io/test/github/SpanPanel/span-panel-api)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/psf/black)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
[](https://www.buymeacoffee.com/cayossarian)
A Python client library for SPAN Panel smart electrical panels. Supports both **Gen2** panels (REST/OpenAPI) and **Gen3** panels (gRPC — MAIN40/MLO48).
## Installation
```bash
# 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.
```python
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:
```python
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:
```python
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](docs/gen2-client.md) |
| Gen3 gRPC client — usage, streaming, data models | [docs/gen3-client.md](docs/gen3-client.md) |
| Error handling and retry strategies | [docs/error-handling.md](docs/error-handling.md) |
| Simulation mode | [docs/simulation.md](docs/simulation.md) |
| Development setup and contributing | [docs/development.md](docs/development.md) |
## License
MIT License - see [LICENSE](LICENSE) for details.