The first Home Assistant integration for the Span MAIN 40 (Gen3) smart electrical panel.
Communicates directly with the panel over your local network using gRPC — no cloud, no API keys, no dependencies on Span's servers. The Gen3 panel replaced the older REST API with a completely new gRPC-based trait system, and existing Span integrations don't support it. This one does.
The Span MAIN 40 (Gen3) uses a fundamentally different protocol than older Span panels:
| Older Span Panels | MAIN 40 Gen3 | |
|---|---|---|
| Protocol | REST API (HTTP) | gRPC (protobuf) |
| Port | 80/443 | 50065 |
| Authentication | Bearer token | None required |
| Data delivery | Polling | Real-time streaming |
| Existing HA support | Yes (SpanPanel/span) | This integration only |
If you have a Gen3 panel and tried the existing Span integration, it didn't work — because the REST API returns 502 on Gen3 hardware. This integration speaks the panel's native gRPC protocol.
- Real-time power monitoring for all circuits and main feed via gRPC streaming
- Per-circuit sensors: power (W), voltage (V), current (A)
- Main feed sensors: total power, voltage, current, frequency (Hz)
- Breaker state detection: binary sensors for each circuit (ON/OFF)
- Dual-phase support: correctly handles both 120V single-phase and 240V dual-phase circuits
- Local-only: direct gRPC connection to the panel, no cloud required
- Zero configuration: auto-discovers all circuits and their names from the panel
- Config flow: set up through the HA UI — just enter the panel IP
- Span MAIN 40 (Gen3) panel on your local network
- Home Assistant 2024.1 or later
- The panel must be reachable on port 50065 (gRPC)
- Open HACS in Home Assistant
- Click the three dots (top right) > Custom repositories
- Add
https://github.com/Griswoldlabs/span-panel-haas an Integration - Search for "Span MAIN 40" and install
- Restart Home Assistant
- Go to Settings > Integrations > Add Integration > "Span MAIN 40"
- Enter your panel's IP address
- Copy the
custom_components/span_panel/folder to your Home Assistantconfig/custom_components/directory - Restart Home Assistant
- Go to Settings > Integrations > Add Integration > "Span MAIN 40"
- Enter your panel's IP address
For a panel with N circuits, the integration creates:
| Entity Type | Count | Description |
|---|---|---|
| Main Feed Power | 1 | Total household power (W) |
| Main Feed Voltage | 1 | Split-phase voltage (V) |
| Main Feed Current | 1 | Total current draw (A) |
| Main Feed Frequency | 1 | Line frequency (Hz) |
| Circuit Power | N | Per-circuit power (W) |
| Circuit Voltage | N | Per-circuit voltage (V) |
| Circuit Current | N | Per-circuit current (A) |
| Circuit Breaker | N | Binary sensor — ON/OFF |
Example: A 25-circuit panel creates 104 entities (4 main feed + 75 circuit sensors + 25 breaker binary sensors).
The integration uses the panel's native gRPC service to:
- Discover circuits via
GetInstancesRPC (trait 26 = power metrics) - Fetch circuit names via
GetRevisionRPC (trait 16 = circuit labels) - Stream real-time metrics via
SubscribeRPC for continuous updates - Detect phase type from actual metric data (field 11 = 120V, field 12 = 240V)
- Detect breaker state via voltage threshold (>5V = ON, <5V = OFF)
All communication is local, on-network, with no cloud dependency.
The panel's gRPC service runs on port 50065 with no authentication. Ensure your Home Assistant instance can reach the panel on this port.
If your panel is on a separate VLAN/subnet (recommended for IoT devices), add a firewall rule allowing TCP traffic from your HA host to the panel on port 50065.
| Panel Model | Supported | Notes |
|---|---|---|
| Span MAIN 40 (Gen3) | Yes | Full support via gRPC |
| Span MLO 48 (Gen3) | Yes | Confirmed working by community testers |
| Span 48 | Yes | Confirmed working by community testers |
| Span MAIN 32 (Gen2 and earlier) | No | Use SpanPanel/span instead |
If this integration is useful to you, consider supporting development:
Your support helps fund hardware for testing across different panel models and keeps development active.
| Problem | Solution |
|---|---|
| Can't connect | Verify the panel IP and that port 50065 is reachable: nc -zv <panel-ip> 50065 |
| No circuit data | The panel needs a few seconds after connection to stream initial metrics |
| Wrong power readings | Power values should match the Span app; if doubled, update to latest version |
| Integration not found | Restart HA after installing; check custom_components/span_panel/ exists |
- Real-time circuit monitoring (power, voltage, current)
- Breaker state detection
- Dual-phase (240V) circuit support
- Config flow UI setup
- MLO 48 compatibility (confirmed by community)
- Energy dashboard integration (Riemann sum sensors)
- Circuit control (on/off) — pending gRPC command discovery
- Upstream merge into SpanPanel/span (in progress)
Contributions are welcome! If you have a Gen3 panel and can help test, please open an issue with your panel details.
MIT License — see LICENSE for details.
Built by GriswoldLabs by reverse-engineering the Span MAIN 40 gRPC protocol. This project is not affiliated with or endorsed by Span.
