A standalone simulator that mimics real SPAN panel behavior.

• Provides mDNS discovery to panels not yet using the Home Assistant integration and direct connections to the SpanPanel SPAN integration for Home Assistant.
• When used with the SpanPanel Home Assistant integration, the App can mimic additional panels and for modeling upgrades to the electrical system.

Includes a web dashboard for real-time configuration, grid simulation, Home Assistant history replay, and energy "what-if" modeling.

Click a simulator configuration to view it. Templates are read-only. A running simulator appears as a discovered panel in the SpanPanel integration (default configs excluded).

1. Examine templates — Load and run the included configs (default_config.yaml, simple_test_config.yaml, etc.) to see how circuits, PV, battery, and EVSE are modeled. Pick one as a starting point for your own configuration.

2. Clone — The Clone button creates an editable copy from a template or from your real panel; cloning your panel preserves recorder history per circuit.

3. Model — The Model button on a running panel opens the what-if view; add battery, PV, or circuits and compare before/after. Edits mark equipment as SYN; click the badge to revert to REC.

4. Purge — The Purge button removes recorder history written by the simulated panel's sensors if you added the simulated panel to Home Assistant's integration.

The simulator is packaged as a Home Assistant app repository for the App Store. It is installed as a third-party app repository in Home Assistant, not via HACS.

Users with the span-panel integration can spin up simulated panels directly in their HA environment.

Repository URL: https://github.com/SpanPanel/simulator

1. Go to Settings > Apps > App Store > three-dot menu > Repositories
2. Add https://github.com/SpanPanel/simulator
3. Install SPAN Panel Simulator from the store
4. Start the App — a default panel config is included
5. The span-panel integration discovers running panels automatically via the Supervisor Discovery API (default configs excluded)
6. Open the web dashboard via Open Web UI to configure panels

The App runs the simulator in a container with its own Mosquitto broker. No real SPAN hardware is needed. Each panel runs on its own HTTP port (starting from base_http_port, default 8081) and the dashboard shows the port next to each running panel's serial number.

# Prerequisites
brew install mosquitto uv

# Run
./scripts/run-local.sh

# Run with debug logging
./scripts/run-local.sh --debug

# Stop / Restart / Status
./scripts/run-local.sh --stop
./scripts/run-local.sh --restart
./scripts/run-local.sh --status

The script automatically creates a Python virtual environment, generates TLS certificates, starts Mosquitto (MQTTS on port 18883), and launches the simulator with mDNS advertising on your LAN IP. No sudo required.

Open the dashboard at http://localhost:18080.

Home Assistant's zeroconf auto-discovers one panel per IP address (default configs excluded). The first cloned panel appears as a discovery notification in HA and can be configured normally. Additional panels on the same host need to be added manually — use the port shown in the dashboard panel list:

1. In HA, go to Settings > Devices & Services > Add Integration
2. Search for Span Panel and enter the host IP and port (e.g. 192.168.1.50 port 8082)

Each panel has a unique serial number, so there is no conflict between the auto-discovered panel and manually added ones.

docker compose up --build

Container-based approaches on macOS do not work for mDNS advertisement. All macOS container runtimes use VM networking that prevents containers from obtaining real LAN IPs. Use run-local.sh on macOS instead.

The dashboard runs on port 18080 and provides full control over the simulated panel.

• Multi-panel — load multiple YAML configs; click a row to select, start/stop/restart individual panels. Running panels appear as discovered devices in the SpanPanel integration (default configs excluded).
• Clone — create an editable copy from a template or from a real panel (IP + passphrase).
• Model — open the energy what-if view for a running panel.
• Purge — remove recorder history written by the simulated panel's sensors when the simulated panel was added to HA's integration.
• File operations — import/export YAML, save & reload
• Config persistence — the simulator remembers the last running config across restarts

• Time-of-day slider — scrub through the day to see solar curves, time-of-day profiles, and battery schedules respond
• Speed acceleration — 1x to 360x time acceleration
• Grid online/offline — toggle to test backup behavior and load shedding
• Islandable toggle — controls whether PV operates during grid outage
• Live power chart — real-time grid, solar, and battery power flows

When connected to Home Assistant, the simulator replays recorded power data from the HA recorder for circuits with mapped entities. This grounds the simulation in actual household usage patterns rather than synthetic profiles.

./scripts/run-local.sh --ha-url http://192.168.1.10:8123 --ha-token YOUR_TOKEN

Circuits with recorder data show a REC badge in the entity list. Clicking the badge toggles to SYN (synthetic) mode, where the simulator uses the configured power profile instead of recorded data. Click again to switch back to recorder replay. This lets you compare how well a synthetic profile matches your real usage, or override a specific circuit while keeping the rest on recorded data.

The modeling view lets you answer "what if" questions about adding solar or battery storage to your panel. Clone your real panel, then add or modify PV and Battery entities to see the projected impact on your grid consumption over historical data.

Typical workflow:

1. Clone your real SPAN panel from the dashboard
2. Connect to HA so circuits replay actual recorded power data
3. Click Model on the running panel to enter the modeling view
4. The Before chart shows your site power as-is (loads minus any existing solar)
5. Add a Battery entity (or modify an existing one) — adjust capacity, charge/discharge schedule, and backup reserve
6. The After chart immediately updates to show grid power with the BESS applied, along with kWh savings
7. Add or resize a PV entity to see how additional solar offsets your consumption in the Before chart
8. Experiment with different battery sizes, charge modes, and PV nameplate ratings — charts auto-refresh on every save

Modeling controls:

• Horizon selector — last month, 3 months, 6 months, or 1 year
• Range zoom — drag the slider to zoom into any time window
• Circuit overlays — check individual circuits in the entity list to overlay their power traces on both charts
• Toggleable legend — show/hide Solar and Battery traces
• Energy summary — net kWh with import/export breakdown and savings percentage

Add, edit, and delete circuits with specialized editors per type:

• PV — nameplate capacity, geographic sine-curve solar model, monthly weather degradation from Open-Meteo historical data
• Battery — nameplate capacity (kWh), backup reserve %, charge mode (Custom / Solar Generation / Solar Excess), discharge presets, 24-hour charge/discharge/idle schedule
• EVSE — charging schedule with presets (Peak Solar, Evening, Night) or custom start/duration, 24-hour visual timeline
• Circuits — typical power, 24-hour usage profile with presets, HVAC type selector with seasonal power modulation

PV and Battery are singleton types — only one of each can exist per panel. Recorder-sourced entities preserve their original panel settings (priority, relay behavior) as read-only.

• Click status dots to toggle circuit relays
• Changes from the dashboard or HA integration (via MQTT) are reflected in both directions
• Grid offline triggers load shedding by priority: OFF_GRID circuits shed immediately, SOC_THRESHOLD circuits shed when battery SOC drops below threshold, NEVER circuits stay on

System, light, or dark theme via the header selector, with localStorage persistence.

Each YAML file in the config directory defines one simulated panel.

panel_config:
  serial_number: "SPAN-TEST-001"
  total_tabs: 8
  main_size: 100

circuit_templates:
  kitchen:
    energy_profile:
      mode: "consumer"
      power_range: [0.0, 1800.0]
      typical_power: 150.0
      power_variation: 0.3
    relay_behavior: "controllable"
    priority: "NEVER"

circuits:
  - id: "kitchen_outlets"
    name: "Kitchen Outlets"
    template: "kitchen"
    tabs: [1, 3]

unmapped_tabs: [2, 4, 5, 6, 7, 8]

simulation_params:
  update_interval: 5

By default, the simulator loads default_config.yaml. To use a different config:

CONFIG_NAME=simple_test_config.yaml ./scripts/run-local.sh

The simulator remembers the last running config and resumes it on restart. When no config is specified and no default exists, all YAML files in the config directory are loaded.

All variables can also be passed as CLI arguments (--help for full list).

See DEVELOPER.md for setup, testing, pre-commit hooks, full config schema, HTTP/MQTT API reference, and simulation engine internals.