{% include "partials/running_panels.html" %}
{% include "partials/clone_panel.html" %}
diff --git a/tests/test_dashboard_never_saves_an_unloadable_config.py b/tests/test_dashboard_never_saves_an_unloadable_config.py
new file mode 100644
index 0000000..ac6ccad
--- /dev/null
+++ b/tests/test_dashboard_never_saves_an_unloadable_config.py
@@ -0,0 +1,143 @@
+"""The dashboard never saves a config nothing will load, and starts when one is active.
+
+A dashboard action used to be able to persist a config the loader refuses: deleting
+the circuit `pv.feed` names left the feed dangling, the save went through, and the
+panel restart then refused the file. With that config active, an add-on restart
+crashed while creating the dashboard, so the user had no screen to fix it from.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import TYPE_CHECKING
+
+import pytest
+import yaml
+from aiohttp import web
+from aiohttp.test_utils import TestClient, TestServer
+
+from panelbench.dashboard import DashboardContext, create_dashboard_app
+from panelbench.dashboard.keys import APP_KEY_DASHBOARD_CONTEXT
+from panelbench.validation import validate_yaml_config
+from tests._helpers import CURRENT_FIRMWARE, EARLIER_FIRMWARE, default_config, write_config
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from panelbench.config_types import SimulationConfig
+
+_FILE = "panel.yaml"
+
+
+def _with_inverters(firmware: str, *extra: str, feed: str | None) -> SimulationConfig:
+ """The default panel at *firmware*, with a PV circuit for each of *extra* beside
+ its own, and `pv.feed` set to *feed*."""
+ config = default_config()
+ config["firmware_version"] = firmware
+ templates = config["circuit_templates"]
+ free = list(config["unmapped_tabs"])
+ for circuit_id in extra:
+ templates[circuit_id] = copy.deepcopy(templates["solar"])
+ config["circuits"].append(
+ {"id": circuit_id, "name": circuit_id, "template": circuit_id, "tabs": [free.pop(0)]}
+ )
+ config["unmapped_tabs"] = free
+ pv = config.get("pv")
+ assert pv is not None
+ if feed is None:
+ pv.pop("feed", None)
+ else:
+ pv["feed"] = feed
+ return config
+
+
+def _app(tmp_path: Path, config: SimulationConfig | dict[str, object]) -> web.Application:
+ write_config(tmp_path / _FILE, config)
+ return create_dashboard_app(
+ DashboardContext(
+ config_dir=tmp_path,
+ config_filter=_FILE,
+ get_panel_configs=lambda: {},
+ get_panel_ports=lambda: {},
+ request_reload=lambda: None,
+ )
+ )
+
+
+def _saved(tmp_path: Path) -> dict[str, object]:
+ saved = yaml.safe_load((tmp_path / _FILE).read_text(encoding="utf-8"))
+ assert isinstance(saved, dict)
+ return saved
+
+
+@pytest.mark.asyncio
+async def test_deleting_the_circuit_pv_feed_names_drops_the_feed(tmp_path: Path) -> None:
+ app = _app(tmp_path, _with_inverters(CURRENT_FIRMWARE, "solar_garage", feed="solar_inverter"))
+
+ async with TestClient(TestServer(app)) as client:
+ deleted = await client.delete("/entities/solar_inverter")
+ saved = await client.post("/save-reload")
+
+ assert deleted.status == 200
+ assert saved.status == 200
+ config = _saved(tmp_path)
+ pv = config["pv"]
+ assert isinstance(pv, dict)
+ assert "feed" not in pv
+ validate_yaml_config(config)
+
+
+@pytest.mark.asyncio
+async def test_a_delete_that_leaves_an_unloadable_config_is_refused(tmp_path: Path) -> None:
+ """Before 202639, two PV circuits and no `pv.feed` is refused, so deleting the
+ circuit the feed names, out of three, is refused with the reason."""
+ config = _with_inverters(EARLIER_FIRMWARE, "solar_garage", "solar_barn", feed="solar_inverter")
+ app = _app(tmp_path, config)
+
+ async with TestClient(TestServer(app)) as client:
+ deleted = await client.delete("/entities/solar_inverter")
+ reason = await deleted.text()
+ listed = await (await client.get("/entities")).text()
+
+ assert deleted.status == 409
+ assert "set pv.feed" in reason
+ assert "solar_inverter" in listed, "the circuit is still there"
+
+
+@pytest.mark.asyncio
+async def test_a_save_the_loader_would_refuse_is_refused_and_writes_nothing(
+ tmp_path: Path,
+) -> None:
+ """A panel needs at least one circuit, so deleting the last one cannot be saved."""
+ config = default_config()
+ config["circuits"] = [c for c in config["circuits"] if c["id"] == "solar_inverter"]
+ app = _app(tmp_path, config)
+ before = (tmp_path / _FILE).read_text(encoding="utf-8")
+
+ async with TestClient(TestServer(app)) as client:
+ await client.delete("/entities/solar_inverter")
+ saved = await client.post("/save-reload")
+ reason = await saved.text()
+
+ assert saved.status == 422
+ assert "At least one circuit must be defined" in reason
+ assert (tmp_path / _FILE).read_text(encoding="utf-8") == before
+
+
+@pytest.mark.asyncio
+async def test_the_dashboard_starts_on_an_unloadable_active_config(tmp_path: Path) -> None:
+ config = default_config()
+ pv = config.get("pv")
+ assert pv is not None
+ pv["feed"] = "no_such_circuit"
+ app = _app(tmp_path, config)
+
+ async with TestClient(TestServer(app)) as client:
+ page = await client.get("/")
+ html = await page.text()
+
+ assert page.status == 200
+ assert "pv.feed 'no_such_circuit' names no circuit" in html
+ assert app[APP_KEY_DASHBOARD_CONTEXT].config_filter is None, (
+ "nothing is open, so nothing can be saved over the file"
+ )
From fbfe52ae0a019b025e94393322e085a1e2f7412c Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:24:23 -0700
Subject: [PATCH 46/95] fix(dashboard): name a locked relay non-controllable in
the tooltip, the refusal and a clone
bda2445 left three places spelling a locked relay the way the config happened
to: the entity list's "Relay locked (...)" tooltip, the 409 a relay command on a
locked circuit answers, and a panel clone, which wrote non_controllable. Each now
uses the shipped configs' spelling, non-controllable (or always-on). The
spelling tests' fixture and parameters are typed.
---
src/panelbench/clone.py | 4 +--
src/panelbench/dashboard/routes.py | 2 +-
.../templates/partials/entity_row.html | 2 +-
tests/test_clone.py | 5 ++--
tests/test_commissioned_system.py | 4 +--
tests/test_relay_behavior_spelling.py | 28 ++++++++++++++++---
tests/test_relay_endpoint_honours_the_lock.py | 4 ++-
7 files changed, 36 insertions(+), 13 deletions(-)
diff --git a/src/panelbench/clone.py b/src/panelbench/clone.py
index 5805dcc..8cdf05e 100644
--- a/src/panelbench/clone.py
+++ b/src/panelbench/clone.py
@@ -729,7 +729,7 @@ def _translate_circuit(
mode = _device_role_to_mode(device_role)
# Relay behavior
- relay_behavior = "controllable" if relay_controllable else "non_controllable"
+ relay_behavior = "controllable" if relay_controllable else "non-controllable"
# Power range and typical power
max_power = breaker_rating * voltage
@@ -786,7 +786,7 @@ def _translate_circuit(
template["never_backup"] = True
# A commissioned-system circuit, as capture's rule recognises it. Written with
- # the locks it implies already present above (relay non_controllable, priority
+ # the locks it implies already present above (relay non-controllable, priority
# NEVER), so the cloned template validates.
if commissioned_system is not None:
template["commissioned_system"] = commissioned_system
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index caa9ffd..7a4bca8 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -1400,7 +1400,7 @@ async def handle_set_relay(request: web.Request) -> web.Response:
raise web.HTTPConflict(
text=(
f"{entity.name} has a locked relay (relay_behavior="
- f"{entity.relay_behavior!r}), so it publishes switch/relay without "
+ f"{entity.relay_behavior_option!r}), so it publishes switch/relay without "
"$settable and relay-controllable=false. Set relay_behavior to "
"'controllable' to command it."
)
diff --git a/src/panelbench/dashboard/templates/partials/entity_row.html b/src/panelbench/dashboard/templates/partials/entity_row.html
index 3716c68..9eec295 100644
--- a/src/panelbench/dashboard/templates/partials/entity_row.html
+++ b/src/panelbench/dashboard/templates/partials/entity_row.html
@@ -11,7 +11,7 @@
would flip it optimistically against a 409. -#}
{% if entity.relay_locked %}
+ title="Relay locked ({{ entity.relay_behavior_option }}) — not commandable">
{% else %}
{% endif %}
diff --git a/tests/test_clone.py b/tests/test_clone.py
index 4cfcfba..8b5d1fc 100644
--- a/tests/test_clone.py
+++ b/tests/test_clone.py
@@ -332,7 +332,8 @@ def test_consumer_mode(self) -> None:
assert ep["mode"] == "consumer"
def test_non_controllable_relay(self) -> None:
- """A circuit whose relay is not controllable maps to non_controllable.
+ """A circuit whose relay is not controllable maps to non-controllable, the
+ spelling the shipped configs write.
v1.0 publishes `switch/relay-controllable` directly; the flat schema inferred
this from `always-on`.
@@ -343,7 +344,7 @@ def test_non_controllable_relay(self) -> None:
# Solar inverter (positions 7,9) is not relay-controllable.
t = templates["clone_7"]
assert isinstance(t, dict)
- assert t["relay_behavior"] == "non_controllable"
+ assert t["relay_behavior"] == "non-controllable"
def test_controllable_relay(self) -> None:
"""Circuit with always-on=false gets controllable relay behavior."""
diff --git a/tests/test_commissioned_system.py b/tests/test_commissioned_system.py
index 51c8484..7a3c8e6 100644
--- a/tests/test_commissioned_system.py
+++ b/tests/test_commissioned_system.py
@@ -134,7 +134,7 @@ async def test_a_clone_keeps_the_commissioned_system(tmp_path: Path) -> None:
commissioned = [t for t in templates.values() if t.get("commissioned_system") == "pv"]
assert len(commissioned) == 1
assert commissioned[0]["priority"] == "NEVER"
- assert commissioned[0]["relay_behavior"] == "non_controllable"
+ assert commissioned[0]["relay_behavior"] == "non-controllable"
assert "never_backup" not in commissioned[0]
validate_yaml_config(config)
@@ -182,5 +182,5 @@ async def test_a_never_backup_circuit_with_the_name_stays_never_backup(tmp_path:
locked = [t for t in templates.values() if t.get("never_backup")]
assert len(locked) == 1
assert locked[0]["priority"] == "OFF_GRID"
- assert locked[0]["relay_behavior"] == "non_controllable"
+ assert locked[0]["relay_behavior"] == "non-controllable"
validate_yaml_config(cloned)
diff --git a/tests/test_relay_behavior_spelling.py b/tests/test_relay_behavior_spelling.py
index d091d9a..04980d5 100644
--- a/tests/test_relay_behavior_spelling.py
+++ b/tests/test_relay_behavior_spelling.py
@@ -11,14 +11,19 @@
from __future__ import annotations
import re
+from typing import TYPE_CHECKING
import pytest
+from aiohttp import web
from aiohttp.test_utils import TestClient, TestServer
from panelbench.dashboard import DashboardContext, create_dashboard_app
from panelbench.dashboard.config_store import ConfigStore
from panelbench.validation import validate_single_template
+if TYPE_CHECKING:
+ from pathlib import Path
+
_CONFIG = """\
panel_config:
serial_number: sim-relay-spelling
@@ -58,7 +63,7 @@
@pytest.fixture
-def app(tmp_path):
+def app(tmp_path: Path) -> web.Application:
cfg_dir = tmp_path / "cfg"
cfg_dir.mkdir()
(cfg_dir / "panel.yaml").write_text(_CONFIG, encoding="utf-8")
@@ -82,7 +87,9 @@ async def _relay_options(client: TestClient, entity_id: str) -> list[tuple[str,
@pytest.mark.parametrize("entity_id", ["shipped", "underscored"])
@pytest.mark.asyncio
-async def test_the_edit_form_selects_a_locked_relay_however_it_is_spelt(app, entity_id) -> None:
+async def test_the_edit_form_selects_a_locked_relay_however_it_is_spelt(
+ app: web.Application, entity_id: str
+) -> None:
async with TestClient(TestServer(app)) as client:
options = await _relay_options(client, entity_id)
@@ -93,7 +100,7 @@ async def test_the_edit_form_selects_a_locked_relay_however_it_is_spelt(app, ent
@pytest.mark.asyncio
-async def test_the_edit_form_keeps_an_always_on_relay_selected(app) -> None:
+async def test_the_edit_form_keeps_an_always_on_relay_selected(app: web.Application) -> None:
"""Not offered as a choice, but shown as the current value rather than replaced."""
async with TestClient(TestServer(app)) as client:
options = await _relay_options(client, "always")
@@ -104,7 +111,9 @@ async def test_the_edit_form_keeps_an_always_on_relay_selected(app) -> None:
@pytest.mark.asyncio
-async def test_a_commissioned_circuit_accepts_its_relay_back_in_either_spelling(app) -> None:
+async def test_a_commissioned_circuit_accepts_its_relay_back_in_either_spelling(
+ app: web.Application,
+) -> None:
async with TestClient(TestServer(app)) as client:
resp = await client.put(
"/entities/backup_system",
@@ -133,3 +142,14 @@ def test_a_pv_circuit_added_from_the_dashboard_is_spelt_as_shipped() -> None:
added = store.add_entity("pv")
assert added.relay_behavior == "non-controllable"
+
+
+@pytest.mark.asyncio
+async def test_the_entity_list_names_a_locked_relay_as_shipped(app: web.Application) -> None:
+ async with TestClient(TestServer(app)) as client:
+ listed = await (await client.get("/entities")).text()
+
+ assert "Relay locked (non-controllable)" in listed
+ assert "Relay locked (always-on)" in listed
+ assert "non_controllable" not in listed
+ assert "always_on" not in listed
diff --git a/tests/test_relay_endpoint_honours_the_lock.py b/tests/test_relay_endpoint_honours_the_lock.py
index 5a59466..72ee7fc 100644
--- a/tests/test_relay_endpoint_honours_the_lock.py
+++ b/tests/test_relay_endpoint_honours_the_lock.py
@@ -104,7 +104,9 @@ async def test_a_controllable_circuit_is_still_commandable(client_and_calls) ->
@pytest.mark.parametrize(
("entity_id", "spelling"),
- [("chest_freezer", "non_controllable"), ("fire_pump", "always_on")],
+ # Configured `non_controllable` and `always_on`; the refusal names each the way the
+ # shipped configs spell it.
+ [("chest_freezer", "non-controllable"), ("fire_pump", "always-on")],
)
async def test_a_locked_circuit_is_refused(client_and_calls, entity_id, spelling) -> None:
"""Both spellings lock. `relay-behavior: always-on` and `non-controllable` are one
From 3e8ce826d9218c0e910efdcbf742d0d6ccb50816 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:25:34 -0700
Subject: [PATCH 47/95] docs(readme): remove all of a second inverter's load
overrides, and pin the rehearsal
The second-inverter step removed only a circuit's overrides: power_range. A
load carrying overrides: typical_power, as many shipped circuits do, kept it, so
the inverter's circuit seeded its energy total from the load's positive typical
power and defeated the step that sets the inverter's. The step now removes the
circuit's overrides, which were all the load's.
A test follows the README on a copy of default_MAIN_40.yaml: the first config
publishes the Commissioned PV System circuit unlocked, and the second publishes
it locked beside two inverters with their own identities and ratings, for a load
with each kind of override. It failed on the old step.
---
README.md | 3 +-
tests/test_readme_rehearsal.py | 149 +++++++++++++++++++++++++++++++++
2 files changed, 151 insertions(+), 1 deletion(-)
create mode 100644 tests/test_readme_rehearsal.py
diff --git a/README.md b/README.md
index 17348ca..cca96c5 100644
--- a/README.md
+++ b/README.md
@@ -153,7 +153,8 @@ upgrade of a panel with a second inverter, also make that circuit an inverter's
about 60% of the rating, negative, such as `-4560.0`, and point the circuit's `template` at the copy. Production follows the rating and the time of day, but
`typical_power` seeds the energy total the inverter's circuit starts from, so a copy that keeps the original's would start with a total sized for the
original inverter. The dashboard's nameplate field sets all three for you.
-- Remove any `overrides: power_range` on the circuit itself. It was the load's, and it would cap the inverter's production.
+- Remove the circuit's own `overrides`. They were the load's: a `power_range` there would cap the inverter's production, and a `typical_power` would replace
+ the template's.
- Give the circuit, under `circuits`, its own inverter's `vendor`, `model` and `serial_number`. It takes `pv.firmware_version` unless it sets its own
`firmware_version`, which a config with no `pv` section needs.
- Where the config has a top-level `pv` section, as a clone of a template does, set `pv.feed` to the `id` of the original inverter's circuit. The section
diff --git a/tests/test_readme_rehearsal.py b/tests/test_readme_rehearsal.py
new file mode 100644
index 0000000..ad70e8d
--- /dev/null
+++ b/tests/test_readme_rehearsal.py
@@ -0,0 +1,149 @@
+"""The README's "Rehearsing a SPAN firmware upgrade" procedure, followed on a template.
+
+Each step below is the README's own, applied to a copy of `default_MAIN_40.yaml` as
+a template clone copies it. The first config is the panel before the upgrade, with
+its "Commissioned PV System" circuit unlocked; the second is the same panel on
+release 202639, with that circuit locked and, as "A second inverter" describes, a
+load circuit turned into a second inverter. If a step stops producing the panel the
+README promises, this fails, rather than a user's rehearsal.
+"""
+
+from __future__ import annotations
+
+import copy
+from datetime import datetime
+from typing import TYPE_CHECKING
+from zoneinfo import ZoneInfo
+
+import pytest
+
+from panelbench.clone import TYPE_PV
+from panelbench.emitter_adapter import runtime as emitter_runtime
+from panelbench.emitter_adapter.instance_ids import stable_circuit_uuid
+from panelbench.emitter_adapter.wire_capture import discovered_devices, recorded_panel
+from tests._helpers import default_config, published, write_config
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from ebus_sdk import DiscoveredDevice
+
+ from panelbench.config_types import SimulationConfig
+ from panelbench.emitter_adapter.runtime import CloneRuntime
+ from panelbench.emitter_adapter.wire_capture import RecordingTransport
+
+_ORIGINAL = "solar_inverter"
+_NOON = datetime(2026, 6, 15, 12, 0, tzinfo=ZoneInfo("America/Los_Angeles")).timestamp()
+
+
+def _before() -> SimulationConfig:
+ """Step 1, on a clone of a template: its PV circuit plays the "Commissioned PV
+ System", renamed with its `id` kept, and its template unlocked."""
+ config = default_config()
+ [circuit] = [c for c in config["circuits"] if c["id"] == _ORIGINAL]
+ circuit["name"] = "Commissioned PV System"
+ solar = config["circuit_templates"][circuit["template"]]
+ solar["relay_behavior"] = "controllable"
+ solar["priority"] = "OFF_GRID"
+ return config
+
+
+def _after(before: SimulationConfig, second: str) -> SimulationConfig:
+ """Step 2, then "A second inverter" for the load circuit *second*."""
+ config = copy.deepcopy(before)
+ config["firmware_version"] = "spanos3/r202639/03"
+ templates = config["circuit_templates"]
+ [original] = [c for c in config["circuits"] if c["id"] == _ORIGINAL]
+ solar = templates[original["template"]]
+ solar["commissioned_system"] = "pv"
+ solar["priority"] = "NEVER"
+ solar["relay_behavior"] = "non-controllable"
+
+ # "Give it a PV template": the commissioned template as the first config has it.
+ copied = copy.deepcopy(before["circuit_templates"][original["template"]])
+ copied["energy_profile"]["nameplate_capacity_w"] = 3800.0
+ copied["energy_profile"]["power_range"] = [-3800.0, 0.0]
+ copied["energy_profile"]["typical_power"] = -2280.0
+ templates["solar_2"] = copied
+ [circuit] = [c for c in config["circuits"] if c["id"] == second]
+ circuit["template"] = "solar_2"
+ # "Remove the circuit's own `overrides`."
+ circuit.pop("overrides", None)
+ # "Give the circuit ... its own inverter's vendor, model and serial_number."
+ circuit["vendor"] = "SolarEdge"
+ circuit["model"] = "SE3800H-US"
+ circuit["serial_number"] = "sim-inv-0002"
+ # "Where the config has a top-level `pv` section ... set `pv.feed`."
+ pv = config.get("pv")
+ assert pv is not None
+ pv["feed"] = _ORIGINAL
+ return config
+
+
+async def _started(path: Path) -> tuple[CloneRuntime, RecordingTransport]:
+ runtime, recorder = await recorded_panel(path)
+ await emitter_runtime.publish_tick(runtime)
+ return runtime, recorder
+
+
+def _inverters(recorder: RecordingTransport) -> dict[str, DiscoveredDevice]:
+ """Each PV device, keyed by the circuit id feeding it."""
+ devices = discovered_devices(recorder.retained)
+ return {
+ str(device.get_property("info", "feed") or device_id): device
+ for device_id, device in devices.items()
+ if (device.description or {}).get("type") == TYPE_PV
+ }
+
+
+def _circuit_state(recorder: RecordingTransport, serial: str, circuit_id: str) -> tuple[str, str]:
+ device_id = stable_circuit_uuid(serial, circuit_id)
+ return (
+ published(recorder, device_id, "load-shed/priority"),
+ published(recorder, device_id, "switch/relay-controllable"),
+ )
+
+
+@pytest.mark.asyncio
+async def test_the_first_config_is_the_panel_before_the_upgrade(tmp_path: Path) -> None:
+ runtime, recorder = await _started(write_config(tmp_path / "before.yaml", _before()))
+
+ serial = runtime.engine.serial_number
+ assert _circuit_state(recorder, serial, _ORIGINAL) == ("OFF_GRID", "true")
+ assert len(_inverters(recorder)) == 1
+
+
+@pytest.mark.parametrize(
+ "second",
+ # A load whose override caps its power, and one whose override sets its typical
+ # power: whatever the load carried has to go.
+ ["new_circuit", "living_room_lights"],
+)
+@pytest.mark.asyncio
+async def test_the_second_config_is_the_same_panel_on_release_202639(
+ tmp_path: Path, second: str
+) -> None:
+ runtime, recorder = await _started(
+ write_config(tmp_path / "after.yaml", _after(_before(), second))
+ )
+
+ serial = runtime.engine.serial_number
+ assert _circuit_state(recorder, serial, _ORIGINAL) == ("NEVER", "false")
+ inverters = {
+ device.get_property("info", "model"): device for device in _inverters(recorder).values()
+ }
+ assert set(inverters) == {"IQ8PLUS-72-2-US", "SE3800H-US"}
+ assert inverters["IQ8PLUS-72-2-US"].get_property("info", "nominal-power") == "10000.0"
+ added = inverters["SE3800H-US"]
+ assert added.get_property("info", "nominal-power") == "3800.0"
+ assert added.get_property("info", "serial-number") == "sim-inv-0002"
+
+ engine = runtime.engine
+ behavior = engine._behavior_engine
+ assert behavior is not None
+ typical = engine._circuits[second].template["energy_profile"]["typical_power"]
+ assert typical == -2280.0, "the inverter's typical power, not the load's, seeds its energy"
+ produced = engine._collect_circuit_powers_at_ts(
+ _NOON, behavior, {second}, use_recorder_baseline=False
+ )[second]
+ assert 0 < produced <= 3800.0
From 3d631e28dbe5310f0188f117bbd2e2709bd13429 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:34:32 -0700
Subject: [PATCH 48/95] feat(engine): read one circuit's template and modelled
power through a public accessor
DynamicSimulationEngine.circuit_template(circuit_id) returns a copy of the
template the engine runs a circuit from, its overrides applied.
modelled_circuit_power(circuit_id, ts) returns what the circuit draws or
produces at a moment by the deterministic path the what-if model's After pass
takes, and restores the behaviour engine's tick-local state afterwards, so
reading a cycling circuit does not start its cycle early. Both raise KeyError
for an unknown circuit.
The rating and README-rehearsal tests now read production through them rather
than through three of the engine's private names. The modelling pass keeps its
own path: it runs a cloned behaviour engine over whole circuit sets, with a
recorder baseline for its Before pass, which a one-circuit live reading is not.
---
src/panelbench/engine.py | 40 +++++++++++++++
tests/test_engine_circuit_accessors.py | 67 ++++++++++++++++++++++++++
tests/test_nameplate_has_one_source.py | 7 +--
tests/test_readme_rehearsal.py | 8 +--
4 files changed, 110 insertions(+), 12 deletions(-)
create mode 100644 tests/test_engine_circuit_accessors.py
diff --git a/src/panelbench/engine.py b/src/panelbench/engine.py
index a1e8ef7..f9d360a 100644
--- a/src/panelbench/engine.py
+++ b/src/panelbench/engine.py
@@ -752,6 +752,46 @@ def override_simulation_start_time(self, start_time_str: str) -> None:
"""Override the simulation start time after initialization."""
self._clock.set_time(start_time_str)
+ # ------------------------------------------------------------------
+ # One circuit, read-only
+ # ------------------------------------------------------------------
+
+ def circuit_template(self, circuit_id: str) -> CircuitTemplateExtended:
+ """A copy of the template the engine runs *circuit_id* from, overrides applied.
+
+ A copy, so a caller reading it cannot change what the circuit does.
+
+ Raises:
+ KeyError: the panel has no circuit *circuit_id*.
+ """
+ return copy.deepcopy(self._circuits[circuit_id].template)
+
+ def modelled_circuit_power(self, circuit_id: str, ts: float) -> float:
+ """What *circuit_id* draws or produces at *ts*, in watts, as modelling sees it.
+
+ The deterministic path the what-if model takes for its After pass: the
+ circuit's template at *ts*, with no noise and no recorder baseline, so a
+ producer scales with its rating. Read-only: the behaviour engine's
+ tick-local state, such as a cycling circuit's phase, is restored after.
+
+ Raises:
+ KeyError: the panel has no circuit *circuit_id*.
+ RuntimeError: the engine has not been initialised.
+ """
+ behavior = self._behavior_engine
+ if behavior is None:
+ raise RuntimeError("The engine is not initialised")
+ if circuit_id not in self._circuits:
+ raise KeyError(circuit_id)
+ checkpoint = behavior.capture_mutable_state()
+ try:
+ powers = self._collect_circuit_powers_at_ts(
+ ts, behavior, {circuit_id}, use_recorder_baseline=False
+ )
+ finally:
+ behavior.restore_mutable_state(checkpoint)
+ return powers[circuit_id]
+
# ------------------------------------------------------------------
# Grid control
# ------------------------------------------------------------------
diff --git a/tests/test_engine_circuit_accessors.py b/tests/test_engine_circuit_accessors.py
new file mode 100644
index 0000000..9f31813
--- /dev/null
+++ b/tests/test_engine_circuit_accessors.py
@@ -0,0 +1,67 @@
+"""The engine's read-only view of one circuit: the template it runs and what it models.
+
+A circuit's production scaling with its rating is a public contract, so the tests
+that hold it read it through these rather than through the engine's internals.
+Both are read-only: reading changes nothing the running panel does next.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+from zoneinfo import ZoneInfo
+
+import pytest
+
+from panelbench.emitter_adapter.wire_capture import recorded_panel
+from tests._helpers import default_config, write_config
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+_NOON = datetime(2026, 6, 15, 12, 0, tzinfo=ZoneInfo("America/Los_Angeles")).timestamp()
+
+
+@pytest.mark.asyncio
+async def test_a_circuit_template_is_the_one_the_engine_runs_and_a_copy(tmp_path: Path) -> None:
+ """With the circuit's overrides applied, and a copy, so a caller cannot re-rate it."""
+ runtime, _ = await recorded_panel(write_config(tmp_path / "panel.yaml", default_config()))
+ engine = runtime.engine
+
+ template = engine.circuit_template("living_room_lights")
+ template["energy_profile"]["typical_power"] = 9999.0
+
+ assert template is not engine.circuit_template("living_room_lights")
+ assert engine.circuit_template("living_room_lights")["energy_profile"]["typical_power"] == 50.0
+
+
+@pytest.mark.asyncio
+async def test_modelled_power_is_deterministic_and_reads_nothing_into_the_panel(
+ tmp_path: Path,
+) -> None:
+ """Read for the solar inverter and for the cycling pool pump, whose cycle the
+ behaviour engine starts tracking the first time its power is computed."""
+ runtime, _ = await recorded_panel(write_config(tmp_path / "panel.yaml", default_config()))
+ engine = runtime.engine
+ # The live behaviour state is the engine's own; it is read here only to show the
+ # accessor leaves it as it was.
+ behavior = engine._behavior_engine
+ assert behavior is not None
+ state = behavior.capture_mutable_state()
+
+ first = engine.modelled_circuit_power("solar_inverter", _NOON)
+ second = engine.modelled_circuit_power("solar_inverter", _NOON)
+ engine.modelled_circuit_power("pool_pump", _NOON)
+
+ assert first == second > 0
+ assert behavior.capture_mutable_state() == state
+
+
+@pytest.mark.asyncio
+async def test_an_unknown_circuit_is_a_key_error(tmp_path: Path) -> None:
+ runtime, _ = await recorded_panel(write_config(tmp_path / "panel.yaml", default_config()))
+
+ with pytest.raises(KeyError):
+ runtime.engine.circuit_template("no_such_circuit")
+ with pytest.raises(KeyError):
+ runtime.engine.modelled_circuit_power("no_such_circuit", _NOON)
diff --git a/tests/test_nameplate_has_one_source.py b/tests/test_nameplate_has_one_source.py
index 45ed1b2..eae465e 100644
--- a/tests/test_nameplate_has_one_source.py
+++ b/tests/test_nameplate_has_one_source.py
@@ -90,12 +90,7 @@ async def _rating(path: Path) -> tuple[str | None, float]:
await emitter_runtime.publish_tick(runtime)
devices = discovered_devices(recorder.retained)
[pv] = [d for d in devices.values() if (d.description or {}).get("type") == TYPE_PV]
- engine = runtime.engine
- behavior = engine._behavior_engine
- assert behavior is not None
- produced = engine._collect_circuit_powers_at_ts(
- _NOON, behavior, {_SOLAR}, use_recorder_baseline=False
- )[_SOLAR]
+ produced = runtime.engine.modelled_circuit_power(_SOLAR, _NOON)
assert produced > 0, "noon in June, so the inverter is producing"
return pv.get_property("info", "nominal-power"), produced
diff --git a/tests/test_readme_rehearsal.py b/tests/test_readme_rehearsal.py
index ad70e8d..657939f 100644
--- a/tests/test_readme_rehearsal.py
+++ b/tests/test_readme_rehearsal.py
@@ -139,11 +139,7 @@ async def test_the_second_config_is_the_same_panel_on_release_202639(
assert added.get_property("info", "serial-number") == "sim-inv-0002"
engine = runtime.engine
- behavior = engine._behavior_engine
- assert behavior is not None
- typical = engine._circuits[second].template["energy_profile"]["typical_power"]
+ typical = engine.circuit_template(second)["energy_profile"]["typical_power"]
assert typical == -2280.0, "the inverter's typical power, not the load's, seeds its energy"
- produced = engine._collect_circuit_powers_at_ts(
- _NOON, behavior, {second}, use_recorder_baseline=False
- )[second]
+ produced = engine.modelled_circuit_power(second, _NOON)
assert 0 < produced <= 3800.0
From e89652afe495f33c3547e7bb384c053e0b5d2cea Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:38:12 -0700
Subject: [PATCH 49/95] fix(config): let a released dashboard edit win over its
template's stale rating
The shipped MAIN 40 template carried a top-level nameplate_capacity_w and the
MAIN 32 template a solar circuit overrides.nameplate_capacity_w, and a template
clone copied them. Every released dashboard wrote a nameplate edit to
energy_profile alone and left the copy behind, so 65aa209 refused exactly the
configs whose users had edited the rating, and their panels would not start.
No released writer ever wrote either copy, so where one disagrees with a stated
energy_profile.nameplate_capacity_w the profile wins: the copy is dropped and a
WARNING names both values and the file. The loaders pass the file through for
it. A disagreeing pv.nameplate_capacity_w, and disagreeing legacy ratings where
no profile is stated, are still refused, because only a hand edit puts them
there. Where the pv section rates one circuit of several on a shared template,
the refusal now says to give the rated circuit its own template.
Tests load the 2.5.3 MAIN 40 and MAIN 32 files with a released dashboard's edit:
both load, publish and produce at the edited rating, warn, and survive a save
and reload with the stale copy gone. The CHANGELOG says so.
---
CHANGELOG.md | 10 +-
DEVELOPER.md | 4 +-
src/panelbench/config_defaults.py | 7 +-
src/panelbench/dashboard/config_store.py | 20 +-
src/panelbench/engine.py | 5 +-
src/panelbench/history_generator.py | 2 +-
src/panelbench/pv_rating.py | 98 +-
.../released_2_5_3/default_MAIN_32.yaml | 709 ++++++++++++++
.../released_2_5_3/default_MAIN_40.yaml | 902 ++++++++++++++++++
tests/test_nameplate_has_one_source.py | 73 +-
.../test_released_dashboard_edits_survive.py | 151 +++
11 files changed, 1929 insertions(+), 52 deletions(-)
create mode 100644 tests/fixtures/released_2_5_3/default_MAIN_32.yaml
create mode 100644 tests/fixtures/released_2_5_3/default_MAIN_40.yaml
create mode 100644 tests/test_released_dashboard_edits_survive.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ab8de0e..4f685c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,8 +35,10 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
- **The top-level `pv` section now describes the inverter whose circuit `pv.feed` names by its `id`, or the only solar circuit's, where it followed whichever
solar circuit was listed first**; a `pv.feed` that names no solar circuit's `id` is now refused, as is a config with several solar circuits and no `pv.feed`
whose `firmware_version` names a release before 202639.
-- **A config that rates a solar circuit in two places with different values is now refused, naming both**, where the template's top level, a circuit's
- `overrides` or the `pv` section could each win somewhere different; equal or lone legacy ratings move into the template's `energy_profile`.
+- **A solar rating set in the dashboard now replaces the stale copy a clone of the shipped MAIN 40 or MAIN 32 template kept**, at the template's top level or
+ in the solar circuit's `overrides`, and the log warns with both values and the file.
+- **A `pv.nameplate_capacity_w` that disagrees with its circuit template's `energy_profile` rating is now refused, naming both**, where the two could each win
+ somewhere different; an equal or lone legacy rating moves into the template's `energy_profile`.
- **Every solar device is now named after its own device id**, as SPAN firmware names an inverter, where it was named "Solar", "Solar 2" and so on in circuit
order.
- **The shipped MAIN 32 config reports hardware version `1.2`**, as a SPAN Panel MAIN 32 publishes it; the other shipped configs keep `rev2` and so report
@@ -62,8 +64,8 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
deleting the circuit `pv.feed` named saved such a config and the next add-on start then failed.
- **The dashboard's relay control shows a locked relay however its config spells it**, where a circuit written `non-controllable`, as the shipped configs
write it, showed `controllable` and saving its form unlocked it.
-- **A solar inverter's nameplate edited in the dashboard now survives a restart and is the rating the panel both publishes and produces at**, where a second
- copy of the rating, at the template's top level, in the circuit's overrides or in the `pv` section, could replace it.
+- **A solar inverter's nameplate edited in the dashboard now survives a restart and is the rating the panel both publishes and produces at**, including in a
+ clone of the shipped MAIN 40 or MAIN 32 template, where the template's stale copy of the rating replaced the edit when the panel started.
## 2.5.3 — two simulated panels no longer publish over each other
diff --git a/DEVELOPER.md b/DEVELOPER.md
index 6a5b074..5caa9c7 100644
--- a/DEVELOPER.md
+++ b/DEVELOPER.md
@@ -363,7 +363,9 @@ circuit_templates: # Reusable template definitions
efficiency: float # 0.0-1.0 (optional, PV/battery)
nameplate_capacity_w:
float # The circuit's rating in watts, and its one source. A rating at the template's top level, in a
- # circuit's overrides or in the pv section is moved here, and a config where one disagrees is refused.
+ # circuit's overrides or in the pv section is moved here. Where this one is stated and another disagrees,
+ # a top-level or override copy is dropped with a warning (released templates left them stale beside a
+ # dashboard edit), and a pv section rating is refused.
initial_consumed_energy_wh: float # Seed consumed energy (from clone)
initial_produced_energy_wh: float # Seed produced energy (from clone)
relay_behavior: str # "controllable" | "non-controllable" | "always-on" (underscore spellings are read the same)
diff --git a/src/panelbench/config_defaults.py b/src/panelbench/config_defaults.py
index 7c0b4b3..3dfd3bb 100644
--- a/src/panelbench/config_defaults.py
+++ b/src/panelbench/config_defaults.py
@@ -124,7 +124,7 @@ def default_energy_profile(device_type: str) -> dict[str, Any]:
return deepcopy(profile)
-def normalize_config(config: Mapping[str, object]) -> None:
+def normalize_config(config: Mapping[str, object], *, source: str) -> None:
"""Make *config* say what its templates mean, in place, before validation.
The one normaliser every loader runs -- the engine, the dashboard on load and on
@@ -138,7 +138,8 @@ def normalize_config(config: Mapping[str, object]) -> None:
2. Every legacy rating folds into its template's
``energy_profile.nameplate_capacity_w``, the one source of a circuit's
rating (``pv_rating``). A default from step 1 is not a rating the config
- stated, so a legacy one replaces it.
+ stated, so a legacy one replaces it. A stale copy dropped beside a stated
+ profile is logged against *source*, the file or config being read.
"""
templates = config.get("circuit_templates")
if not isinstance(templates, dict):
@@ -152,4 +153,4 @@ def normalize_config(config: Mapping[str, object]) -> None:
device_type = str(template.get("device_type", _DEFAULT_DEVICE_TYPE))
template["energy_profile"] = default_energy_profile(device_type)
defaulted.add(str(name))
- fold_legacy_ratings(config, unstated=frozenset(defaulted))
+ fold_legacy_ratings(config, unstated=frozenset(defaulted), source=source)
diff --git a/src/panelbench/dashboard/config_store.py b/src/panelbench/dashboard/config_store.py
index 90f2f21..96b9750 100644
--- a/src/panelbench/dashboard/config_store.py
+++ b/src/panelbench/dashboard/config_store.py
@@ -98,6 +98,9 @@ def _detect_entity_type(template: dict[str, Any]) -> str:
return "circuit"
+_IMPORTED = "the imported config"
+
+
class ConfigStore:
"""In-memory config state: load, mutate, validate, export."""
@@ -126,34 +129,37 @@ def dirty(self) -> bool:
"""Whether in-memory state has unsaved changes."""
return self._dirty
- def load_from_yaml(self, content: str, *, saved: bool = True) -> None:
+ def load_from_yaml(self, content: str, *, saved: bool = True, source: str = _IMPORTED) -> None:
"""Parse, validate, and replace state from YAML string.
*saved* says whether *content* is what the loaded file holds; an import
is not, so it loads unsaved and leaving it prompts like any other edit.
+ *source* names it in what the loader logs: the file, or an import.
"""
data = yaml.safe_load(content)
if not isinstance(data, dict):
raise ValueError("YAML content must be a mapping")
- self.load_from_mapping(data, saved=saved)
+ self.load_from_mapping(data, saved=saved, source=source)
- def load_from_mapping(self, data: Mapping[str, object], *, saved: bool = True) -> None:
+ def load_from_mapping(
+ self, data: Mapping[str, object], *, saved: bool = True, source: str = _IMPORTED
+ ) -> None:
"""Normalise, validate and replace state from an already-parsed config; *saved*
- as for ``load_from_yaml``.
+ and *source* as for ``load_from_yaml``.
Normalised as the engine normalises, so the editor holds a circuit's rating in
the one place its form reads and writes, and saving the form cannot re-rate it
from a key the form never showed.
"""
state = deepcopy(dict(data))
- normalize_config(state)
+ normalize_config(state, source=source)
validate_yaml_config(state)
self._state = state
self._dirty = not saved
def load_from_file(self, path: Path) -> None:
"""Read a file and load its content."""
- self.load_from_yaml(path.read_text(encoding="utf-8"))
+ self.load_from_yaml(path.read_text(encoding="utf-8"), source=str(path))
def export_yaml(self) -> str:
"""Serialize current state to YAML."""
@@ -173,7 +179,7 @@ def save_to_file(self, path: Path) -> None:
Raises:
ValueError: the panel would refuse the config; nothing is written.
"""
- normalize_config(self._state)
+ normalize_config(self._state, source=str(path))
validate_yaml_config(self._state)
path.write_text(self.export_yaml(), encoding="utf-8")
self._dirty = False
diff --git a/src/panelbench/engine.py b/src/panelbench/engine.py
index f9d360a..e1cbd42 100644
--- a/src/panelbench/engine.py
+++ b/src/panelbench/engine.py
@@ -724,7 +724,10 @@ def _validate_yaml_config(self, config_data: dict[str, Any] | SimulationConfig)
# Before validation, not after: normalisation is what makes an omitted
# energy_profile legal, so validating first would reject configs this is
# meant to accept.
- normalize_config(config_data)
+ normalize_config(
+ config_data,
+ source=str(self._config_path) if self._config_path else "the engine's config",
+ )
validate_yaml_config(config_data)
def _build_circuits(self) -> None:
diff --git a/src/panelbench/history_generator.py b/src/panelbench/history_generator.py
index aaa61f3..2192ea1 100644
--- a/src/panelbench/history_generator.py
+++ b/src/panelbench/history_generator.py
@@ -99,7 +99,7 @@ async def generate(
raise ValueError(msg)
# As the engine reads it, so the history is sized by the rating the panel
# produces at.
- normalize_config(raw)
+ normalize_config(raw, source=str(config_path))
anchor = anchor_time if anchor_time is not None else time.time()
days_total = (years * 365) if years is not None else _DAYS_TOTAL
diff --git a/src/panelbench/pv_rating.py b/src/panelbench/pv_rating.py
index 39e04fd..8529b68 100644
--- a/src/panelbench/pv_rating.py
+++ b/src/panelbench/pv_rating.py
@@ -16,14 +16,24 @@
``fold_legacy_ratings`` moves each into the profile and ``rating_conflicts`` names
what cannot be moved, both from one plan, so the loader and validation cannot
disagree about which is which. A legacy value equal to the profile's, or one where
-the profile states none, folds silently. One that disagrees is refused, naming both
-keys and both values, because picking either would be a guess. The ``pv`` section's
-rating stays where it is only for an inverter with no PV circuit, one upstream of the
-panel, where it is the sole source.
+the profile states none, folds silently.
+
+Where a stated profile and a legacy value disagree, which one is the user's depends
+on who could have written it. Every released dashboard wrote a nameplate edit to the
+profile alone, and no released writer ever wrote the template's top level or a
+circuit's override; the shipped MAIN 40 and MAIN 32 templates carried one of those
+two, and a template clone copied it. So against either of those the profile wins,
+the stale copy is dropped, and a WARNING names both values and the file. Only a
+hand edit puts a rating in the ``pv`` section, or two legacy ratings where the
+profile states none, so a disagreement there is refused, naming both keys and both
+values, because picking either would be a guess. The ``pv`` section's rating stays
+where it is only for an inverter with no PV circuit, one upstream of the panel,
+where it is the sole source.
"""
from __future__ import annotations
+import logging
from dataclasses import dataclass
from typing import TYPE_CHECKING
@@ -34,6 +44,8 @@
NAMEPLATE = "nameplate_capacity_w"
+_LOGGER = logging.getLogger(__name__)
+
@dataclass(frozen=True)
class _Claim:
@@ -48,6 +60,10 @@ class _Claim:
# A mapping left empty once the claim is removed, and where it hangs, so a folded
# override does not leave `overrides: {}` behind.
empties: tuple[dict[str, object], str] | None = None
+ # Whether a released writer could have left this behind beside a dashboard edit:
+ # true of the template's top level and a circuit's override, never of the `pv`
+ # section, which only a hand edit fills.
+ stale_beside_an_edit: bool = True
@dataclass(frozen=True)
@@ -57,6 +73,8 @@ class _Fold:
profile: dict[str, object]
rating: float | None
claims: tuple[_Claim, ...]
+ # Why a stale copy was dropped rather than folded, for the WARNING each gets.
+ dropped: tuple[str, ...] = ()
@dataclass(frozen=True)
@@ -65,15 +83,20 @@ class _Plan:
conflicts: tuple[str, ...]
-def fold_legacy_ratings(config: Mapping[str, object], *, unstated: frozenset[str]) -> None:
+def fold_legacy_ratings(
+ config: Mapping[str, object], *, unstated: frozenset[str], source: str
+) -> None:
"""Move every legacy rating in *config* into its template's profile, in place.
*unstated* names the templates whose profile the loader filled in from a default:
the default's rating is not one the config stated, so a legacy rating replaces it.
- What disagrees with a stated profile is left where it is, for ``rating_conflicts``
- to refuse.
+ A stale copy beside a stated profile is dropped, with a WARNING naming *source*,
+ the file or config it came from. What else disagrees is left where it is, for
+ ``rating_conflicts`` to refuse.
"""
for fold in _plan(config, unstated=unstated).folds:
+ for reason in fold.dropped:
+ _LOGGER.warning("%s: %s", source, reason)
if fold.rating is not None:
fold.profile[NAMEPLATE] = fold.rating
for claim in fold.claims:
@@ -174,7 +197,15 @@ def _claims(
)
rates_one_of_these = any(str(circuit.get("id")) == bound for circuit in circuits)
if section is not None and bound is not None and rates_one_of_these:
- claims.append(_Claim(f"pv.{NAMEPLATE}", section[NAMEPLATE], section, bound))
+ claims.append(
+ _Claim(
+ f"pv.{NAMEPLATE}",
+ section[NAMEPLATE],
+ section,
+ bound,
+ stale_beside_an_edit=False,
+ )
+ )
return claims
@@ -202,14 +233,25 @@ def _template_plan(
if stated is not None:
canonical = _watts(stated)
- agreed = tuple(claim for claim in claims if _watts(claim.value) == canonical)
- refused = tuple(
- f"{claim.where} is {_shown(claim.value)} but {canonical_key} is {_shown(stated)}: "
- f"a rating has one source, so remove {claim.where} or make the two agree"
+ disagreeing = [claim for claim in claims if _watts(claim.value) != canonical]
+ stale = [claim for claim in disagreeing if claim.stale_beside_an_edit]
+ dropped = tuple(
+ f"{claim.where} is {_shown(claim.value)} but {canonical_key}, which the "
+ f"dashboard edits, is {_shown(stated)}: rating the circuit {_shown(stated)} "
+ f"and dropping the stale {claim.where}"
+ for claim in stale
+ )
+ removed = tuple(
+ claim
for claim in claims
- if _watts(claim.value) != canonical
+ if _watts(claim.value) == canonical or claim.stale_beside_an_edit
+ )
+ refused = tuple(
+ _disagreement(name, claim, canonical_key, stated, circuits)
+ for claim in disagreeing
+ if not claim.stale_beside_an_edit
)
- return _Fold(profile, None, agreed), refused
+ return _Fold(profile, None, removed, dropped), refused
ratings = {_watts(claim.value) for claim in claims}
if len(ratings) > 1:
@@ -235,6 +277,34 @@ def _template_plan(
return _Fold(profile, rating, tuple(claims)), ()
+def _disagreement(
+ name: str,
+ claim: _Claim,
+ canonical_key: str,
+ stated: object,
+ circuits: list[dict[str, object]],
+) -> str:
+ """Why *claim* is refused beside a profile that states *stated*.
+
+ Making the two agree re-rates every circuit on the template, so where it rates one
+ circuit of several the advice is the template of its own instead.
+ """
+ disagree = f"{claim.where} is {_shown(claim.value)} but {canonical_key} is {_shown(stated)}"
+ others = [
+ str(circuit.get("id"))
+ for circuit in circuits
+ if str(circuit.get("id")) != claim.circuit_id
+ ]
+ if claim.circuit_id is not None and others:
+ shared = ", ".join(repr(circuit_id) for circuit_id in others)
+ return (
+ f"{disagree}, and circuit template {name!r} is shared with {shared}: give the "
+ f"rated circuit its own template, set its energy_profile.{NAMEPLATE} and remove "
+ f"{claim.where}"
+ )
+ return f"{disagree}: a rating has one source, so remove {claim.where} or make the two agree"
+
+
def _watts(value: object) -> float | None:
if isinstance(value, bool) or not isinstance(value, int | float | str):
return None
diff --git a/tests/fixtures/released_2_5_3/default_MAIN_32.yaml b/tests/fixtures/released_2_5_3/default_MAIN_32.yaml
new file mode 100644
index 0000000..e3d7d25
--- /dev/null
+++ b/tests/fixtures/released_2_5_3/default_MAIN_32.yaml
@@ -0,0 +1,709 @@
+# Example YAML simulation configuration for a 32-circuit residential panel
+# This demonstrates the new flexible simulation system
+
+panel_config:
+ serial_number: "sim-32t-001"
+ total_tabs: 32
+ main_size: 200
+ # `status/wifi-ssid` is declared by the enclosure and read by consumers today,
+ # as default_MAIN_40.yaml states at length; without a value it is an entity
+ # that never resolves. Synthetic, so it attests the mapping and not what a real
+ # network is called.
+ wifi_ssid: sim-wifi
+ latitude: 37.7
+ longitude: -122.4
+
+pv:
+ # Identity only. There is no `enabled` key: the PV device is instantiated from the
+ # producer circuit templates below, and this section fills in what r202633 documents
+ # on its info node rather than changing whether it exists.
+ #
+ # `serial_number` is deliberately absent, as in default_MAIN_40.yaml:
+ # `_der_identifier` prefers a serial over `instance_id`, so setting one moves the
+ # device id from `
-pv-1` to `-`.
+ vendor: Enphase
+ product_name: IQ8PLUS-72-2-US
+ firmware_version: sim-pv/v0.1.0
+
+bess:
+ enabled: true
+ # Identity, for the reason default_MAIN_40.yaml states at length: r202633 documents
+ # these on the device's info node and the emitter passes them through, so leaving
+ # them unset publishes a declaration with no value — an entity that never resolves
+ # rather than one a user notices is missing. Synthetic, so they attest the mapping
+ # and not what real firmware sends.
+ #
+ # The MID's own identity, not the battery's. This panel used to stand up no MID at
+ # all -- the comment here said it "is not islandable", which was never a property of
+ # the panel so much as of what the old gate happened to read. A commissioned battery
+ # forms a premises island, so this panel publishes a MID like any other, and these
+ # three are the device-registry row a consumer builds for it. Unvalued, that row
+ # shows a blank model and no firmware. `serial-number` is absent on purpose: the
+ # generator derives it as `-mid`, the resolvable link between the two
+ # halves of one unit.
+ #
+ # `grid_forming` is deliberately NOT set here. It defaults to true for a
+ # commissioned battery, and leaving it unstated is what keeps
+ # test_every_shipped_config_with_a_battery_publishes_a_mid exercising that default
+ # rather than a value typed beside it.
+ mid_product_name: SPAN MID
+ mid_firmware_version: sim-mid/v0.1.0
+ mid_hardware_version: rev1
+ vendor: Span
+ product_name: SPAN Battery
+ part_number: SPN-BESS-001
+ serial_number: SIM-BESS-32T-001
+ firmware_version: sim-bess/v0.1.0
+ nameplate_capacity_kwh: 13.5
+ max_charge_w: 3500.0
+ max_discharge_w: 3500.0
+ charge_efficiency: 0.95
+ discharge_efficiency: 0.95
+ backup_reserve_pct: 20.0
+ charge_mode: self-consumption
+ charge_hours: [8, 9, 10, 11, 12, 13, 14, 15]
+ discharge_hours: [16, 17, 18, 19, 20, 21, 22]
+
+# Circuit templates define reusable behavior patterns
+circuit_templates:
+ # Always-on base load
+ always_on:
+ energy_profile:
+ mode: "consumer" # Consumes power only
+ power_range: [40.0, 100.0]
+ typical_power: 60.0
+ power_variation: 0.1
+ relay_behavior: "controllable"
+ priority: "NEVER"
+ breaker_rating: 15
+
+ # Interior lighting with time-based patterns
+ lighting:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 500.0]
+ typical_power: 80.0
+ power_variation: 0.1
+ relay_behavior: "controllable"
+ priority: "NEVER"
+ breaker_rating: 15
+ time_of_day_profile:
+ enabled: true
+ hourly_multipliers:
+ 0: 0.1
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.1
+ 7: 0.3
+ 8: 0.2
+ 9: 0.1
+ 10: 0.1
+ 11: 0.1
+ 12: 0.1
+ 13: 0.1
+ 14: 0.1
+ 15: 0.1
+ 16: 0.2
+ 17: 0.4
+ 18: 0.8
+ 19: 1.0
+ 20: 1.0
+ 21: 1.0
+ 22: 0.7
+ 23: 0.3
+
+ exterior_lighting:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 300.0]
+ typical_power: 60.0
+ power_variation: 0.1
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ breaker_rating: 15
+ time_of_day_profile:
+ enabled: true
+ hourly_multipliers:
+ 0: 0.3
+ 1: 0.3
+ 2: 0.3
+ 3: 0.3
+ 4: 0.3
+ 5: 0.3
+ 6: 0.1
+ 7: 0.0
+ 8: 0.0
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.0
+ 13: 0.0
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.0
+ 18: 0.3
+ 19: 0.7
+ 20: 1.0
+ 21: 1.0
+ 22: 1.0
+ 23: 0.5
+
+ # HVAC with cycling behavior
+ hvac:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 3500.0]
+ typical_power: 2800.0
+ power_variation: 0.1
+ relay_behavior: "controllable"
+ priority: "NEVER"
+ cycling_pattern:
+ on_duration: 1200 # 20 minutes
+ off_duration: 2400 # 40 minutes
+ hvac_type: "central_ac"
+ breaker_rating: 30
+ time_of_day_profile:
+ enabled: true
+ hourly_multipliers:
+ 0: 0.3
+ 1: 0.3
+ 2: 0.3
+ 3: 0.3
+ 4: 0.3
+ 5: 0.3
+ 6: 0.4
+ 7: 0.5
+ 8: 0.5
+ 9: 0.5
+ 10: 0.6
+ 11: 0.6
+ 12: 0.7
+ 13: 0.7
+ 14: 0.8
+ 15: 0.9
+ 16: 1.0
+ 17: 1.0
+ 18: 1.0
+ 19: 1.0
+ 20: 1.0
+ 21: 1.0
+ 22: 0.7
+ 23: 0.4
+
+ # Dishwasher — runs after dinner, motor cycles during wash
+ dishwasher:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 1800.0]
+ typical_power: 1200.0
+ power_variation: 0.15
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 1200
+ off_duration: 600
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.0
+ 8: 0.0
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.0
+ 13: 0.0
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.0
+ 18: 0.0
+ 19: 0.8
+ 20: 1.0
+ 21: 0.5
+ 22: 0.0
+ 23: 0.0
+
+ # Washing machine — morning/afternoon loads, agitation cycling
+ washing_machine:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 1500.0]
+ typical_power: 500.0
+ power_variation: 0.3
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 600
+ off_duration: 300
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.0
+ 8: 0.3
+ 9: 0.7
+ 10: 1.0
+ 11: 0.8
+ 12: 0.0
+ 13: 0.0
+ 14: 0.0
+ 15: 0.5
+ 16: 0.7
+ 17: 0.3
+ 18: 0.0
+ 19: 0.0
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+
+ # Microwave — brief bursts at mealtimes
+ microwave:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 1500.0]
+ typical_power: 1000.0
+ power_variation: 0.1
+ relay_behavior: "controllable"
+ priority: "NEVER"
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 180
+ off_duration: 3420
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.4
+ 8: 0.3
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.6
+ 13: 0.4
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.3
+ 18: 0.5
+ 19: 0.3
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+
+ # Dryer — afternoon drying cycle, mostly continuous when running
+ dryer:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 5000.0]
+ typical_power: 3000.0
+ power_variation: 0.1
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ breaker_rating: 30
+ cycling_pattern:
+ on_duration: 2400
+ off_duration: 300
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.0
+ 8: 0.0
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.0
+ 13: 0.0
+ 14: 0.5
+ 15: 1.0
+ 16: 1.0
+ 17: 0.5
+ 18: 0.0
+ 19: 0.0
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+
+ # Oven/range — thermostat cycling, dinner-centric usage
+ oven_range:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 5000.0]
+ typical_power: 2000.0
+ power_variation: 0.2
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ breaker_rating: 40
+ cycling_pattern:
+ on_duration: 600
+ off_duration: 600
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.2
+ 8: 0.2
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.3
+ 13: 0.0
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.5
+ 18: 1.0
+ 19: 0.8
+ 20: 0.3
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+
+ # Refrigerator with compressor cycling
+ refrigerator:
+ energy_profile:
+ mode: "consumer"
+ power_range: [50.0, 200.0]
+ typical_power: 120.0
+ power_variation: 0.2
+ relay_behavior: "non-controllable"
+ priority: "NEVER"
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 600 # 10 minutes
+ off_duration: 1800 # 30 minutes
+
+ # SPAN Drive EV charger with smart grid response
+ span_drive:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 11500.0]
+ typical_power: 7200.0 # Level 2 charging (240V @ 30A)
+ power_variation: 0.05
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ breaker_rating: 50
+ device_type: "evse"
+ smart_behavior:
+ responds_to_grid: true
+ max_power_reduction: 0.6 # Can reduce to 40% during grid stress
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 1.0
+ 1: 1.0
+ 2: 1.0
+ 3: 1.0
+ 4: 1.0
+ 5: 1.0
+ 6: 0.0
+ 7: 0.0
+ 8: 0.0
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.0
+ 13: 0.0
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.0
+ 18: 0.0
+ 19: 0.0
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+
+ # Pool equipment
+ pool_equipment:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 1200.0]
+ typical_power: 800.0
+ power_variation: 0.1
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 7200 # 2 hours on
+ off_duration: 14400 # 4 hours off
+
+ # Solar production system
+ solar_production:
+ energy_profile:
+ mode: "producer"
+ power_range: [-8000.0, 0.0]
+ typical_power: -5000.0
+ power_variation: 0.25
+ efficiency: 0.85
+ nameplate_capacity_w: 8000.0
+ relay_behavior: "non-controllable"
+ priority: "NEVER"
+ device_type: "pv"
+ breaker_rating: 30
+
+ # Backup generator - another producer type
+ backup_generator:
+ energy_profile:
+ mode: "producer"
+ power_range: [-8000.0, 0.0] # 8kW backup generator
+ typical_power: -6000.0
+ power_variation: 0.05 # Generators are very stable
+ efficiency: 0.92 # 92% fuel efficiency
+ relay_behavior: "controllable"
+ priority: "NEVER"
+ breaker_rating: 40
+
+ # Wind turbine - variable producer
+ wind_production:
+ energy_profile:
+ mode: "producer"
+ power_range: [-2000.0, 0.0] # 2kW small wind turbine
+ typical_power: -800.0
+ power_variation: 0.5 # Very variable based on wind
+ efficiency: 0.75 # 75% efficiency
+ relay_behavior: "non-controllable"
+ priority: "NEVER"
+ breaker_rating: 15
+
+ # General outlet circuits
+ outlets:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 1800.0]
+ typical_power: 150.0
+ power_variation: 0.4 # Very variable loads
+ relay_behavior: "controllable"
+ priority: "NEVER"
+ breaker_rating: 15
+
+ # Kitchen specific outlets (higher capacity)
+ kitchen_outlets:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 2400.0]
+ typical_power: 300.0
+ power_variation: 0.5 # Very variable - appliances
+ relay_behavior: "controllable"
+ priority: "NEVER"
+ breaker_rating: 20
+
+ # Heat pump with seasonal efficiency
+ heat_pump:
+ energy_profile:
+ mode: "consumer"
+ power_range: [500.0, 4000.0]
+ typical_power: 2800.0
+ power_variation: 0.25 # Efficiency varies with temperature
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ cycling_pattern:
+ on_duration: 900 # 15 minutes on
+ off_duration: 1800 # 30 minutes off
+ hvac_type: "heat_pump"
+ breaker_rating: 30
+
+ # Major appliances (dishwasher, laundry, etc.)
+ major_appliance:
+ energy_profile:
+ mode: "consumer"
+ power_range: [0.0, 2500.0]
+ typical_power: 800.0
+ power_variation: 0.3
+ relay_behavior: "controllable"
+ priority: "OFF_GRID"
+ breaker_rating: 20
+
+circuits:
+ # Lighting circuits (tabs 1-6)
+ - id: "master_bedroom_lights"
+ name: "Master Bedroom Lights"
+ template: "lighting"
+ tabs: [1]
+ overrides:
+ typical_power: 35.0 # Slightly higher for master
+
+ - id: "living_room_lights"
+ name: "Living Room Lights"
+ template: "lighting"
+ tabs: [2]
+ overrides:
+ typical_power: 45.0 # Higher for main living area
+
+ - id: "kitchen_lights"
+ name: "Kitchen Lights"
+ template: "lighting"
+ tabs: [3]
+ overrides:
+ typical_power: 40.0
+
+ - id: "bedroom_lights"
+ name: "Bedroom Lights"
+ template: "lighting"
+ tabs: [4]
+
+ - id: "bathroom_lights"
+ name: "Bathroom Lights"
+ template: "lighting"
+ tabs: [5]
+ overrides:
+ typical_power: 30.0
+
+ - id: "exterior_lights"
+ name: "Exterior Lights"
+ template: "exterior_lighting"
+ tabs: [6]
+
+ # Outlet circuits (tabs 7-14)
+ - id: "master_bedroom_outlets"
+ name: "Master Bedroom Outlets"
+ template: "outlets"
+ tabs: [7]
+
+ - id: "living_room_outlets"
+ name: "Living Room Outlets"
+ template: "outlets"
+ tabs: [8]
+ overrides:
+ typical_power: 200.0 # TV, entertainment system
+
+ - id: "kitchen_outlets_1"
+ name: "Kitchen Outlets 1"
+ template: "kitchen_outlets"
+ tabs: [9] # 120V circuit
+
+ - id: "kitchen_outlets_2"
+ name: "Kitchen Outlets 2"
+ template: "kitchen_outlets"
+ tabs: [12] # 120V circuit
+
+ - id: "office_outlets"
+ name: "Office Outlets"
+ template: "outlets"
+ tabs: [11]
+ overrides:
+ typical_power: 300.0 # Computers, monitors
+
+ - id: "garage_outlets"
+ name: "Garage Outlets"
+ template: "outlets"
+ tabs: [10]
+
+ - id: "laundry_outlets"
+ name: "Laundry Room Outlets"
+ template: "outlets"
+ tabs: [13]
+
+ - id: "guest_room_outlets"
+ name: "Guest Room Outlets"
+ template: "outlets"
+ tabs: [14]
+
+ # Major appliances (tabs 15-22)
+ - id: "refrigerator"
+ name: "Refrigerator"
+ template: "refrigerator"
+ tabs: [15]
+ overrides:
+ typical_power: 150.0
+
+ - id: "dishwasher"
+ name: "Dishwasher"
+ template: "dishwasher"
+ tabs: [16]
+
+ - id: "washing_machine"
+ name: "Washing Machine"
+ template: "washing_machine"
+ tabs: [17]
+
+ - id: "dryer"
+ name: "Electric Dryer"
+ template: "dryer"
+ tabs: [18, 20]
+
+ - id: "oven"
+ name: "Electric Oven"
+ template: "oven_range"
+ tabs: [19, 21]
+
+ - id: "microwave"
+ name: "Microwave"
+ template: "microwave"
+ tabs: [22]
+
+ # HVAC systems (tabs 23-26)
+ - id: "main_hvac"
+ name: "Main HVAC Unit"
+ template: "hvac"
+ tabs: [23, 25] # 240V system
+
+ - id: "heat_pump_backup"
+ name: "Heat Pump Backup"
+ template: "heat_pump"
+ tabs: [24, 26] # 240V system
+
+ # EV charging (tabs 27-29)
+ - id: "span_drive_garage"
+ name: "SPAN Drive - Garage"
+ template: "span_drive"
+ tabs: [27, 29] # 240V Level 2 charger
+
+ # Solar (tabs 28-30)
+ - id: "solar_inverter"
+ name: "Solar Inverter"
+ template: "solar_production"
+ tabs: [28, 30]
+ device_type: "pv"
+ overrides:
+ nameplate_capacity_w: 8000.0
+
+unmapped_tabs: [31, 32]
+
+# Global simulation parameters
+simulation_params:
+ update_interval: 5 # Update every 5 seconds
+ time_acceleration: 1.0 # Real-time simulation
+ noise_factor: 0.02 # ±2% random noise on all values
+ enable_realistic_behaviors: true
diff --git a/tests/fixtures/released_2_5_3/default_MAIN_40.yaml b/tests/fixtures/released_2_5_3/default_MAIN_40.yaml
new file mode 100644
index 0000000..0894147
--- /dev/null
+++ b/tests/fixtures/released_2_5_3/default_MAIN_40.yaml
@@ -0,0 +1,902 @@
+panel_config:
+ serial_number: sim-40t-001
+ display_name: Span Panel
+ total_tabs: 40
+ main_size: 200
+ postal_code: '94103'
+ time_zone: America/Los_Angeles
+ islandable: true
+ latitude: 37.7
+ longitude: -122.4
+ # Valued because a real panel publishes it, not because the emitter can. The
+ # v1.0 enclosure declares `status/wifi-ssid` ("SSID to which the Wi-Fi network
+ # interface is connected", MAY) and r202633 documents it as the MQTT successor
+ # to `GET /api/v1/wifi/status`; the flat schema reads the same field today and
+ # the HA integration surfaces it as a panel attribute. A live-capture
+ # differential against real flat firmware found the `core` device class carried
+ # an identical property set to the simulator, so this is not a simulator
+ # artifact.
+ #
+ # Unlike the identity keys below, this one is not merely absent-by-default: the
+ # enclosure declares the property unconditionally and `status/wifi` beside it
+ # already reports the interface up, so a panel that never names the network
+ # leaves a consumer holding an entity that waits forever. `const.py` carries the
+ # same value as the fallback, so a config predating this key does not reopen the
+ # gap; it is spelled out here for the same reason `postal_code` and `time_zone`
+ # are. Synthetic, so it attests the mapping rather than what a real network is
+ # called.
+ wifi_ssid: sim-wifi
+firmware_version: sim/v0.1.0
+hardware_version: rev2
+pv:
+ enabled: true
+ vendor: Enphase
+ product_name: IQ8PLUS-72-2-US
+ # Placeholder, for the reason the BESS block below states: r202633 documents
+ # info/firmware-version on the PV, the emitter passes it through, and without a
+ # value here it is declared and never published — which leaves a consumer holding
+ # an entity that waits forever. Synthetic, so it attests the mapping rather than
+ # what real firmware sends.
+ firmware_version: sim-pv/v0.1.0
+ # `serial_number` is deliberately NOT set, even though r202633 documents
+ # info/serial-number here and it is one of the two PV properties still declared
+ # and unvalued. `_der_identifier` prefers a serial over `instance_id` when
+ # building the device id, so setting one moves this device from
+ # `-pv-1` to `-`. Device ids are what a consumer keys its
+ # registry on, and `evse_serial_number` records why they are load-bearing here:
+ # they have to match what the frozen flat simulator publishes, or `simupgrade`
+ # stops rehearsing an upgrade and starts rehearsing a device replacement.
+ # Closing this gap means first confirming the flat side's PV id, which is a
+ # question about the upgrade path rather than about this config.
+bess:
+ enabled: true
+ # This battery forms a premises-wiring island, which is what makes the panel
+ # publish a MID child -- `devices/bess.md` requires one for a grid-forming BESS and
+ # treats its absence as "no premises-wiring backup". Stated here rather than left to
+ # be inferred from the PV inverter, which is what the gate used to read: that
+ # inference is silently wrong for a grid-forming battery paired with AC-coupled PV,
+ # or with no PV at all.
+ grid_forming: true
+ instance_id: bess
+ vendor: Span
+ product_name: SPAN Battery
+ part_number: SPN-BESS-001
+ serial_number: SIM-BESS-40T-001
+ # Placeholder. The BESS declares info/firmware-version and the emitter passes it
+ # through; without a value here the property is declared and never published,
+ # which creates a consumer entity that waits forever. Synthetic, so it attests
+ # the mapping and not what real firmware sends.
+ firmware_version: sim-bess/v0.1.0
+ # The MID's own identity, not the battery's. v1.0 makes them separate devices, so
+ # a consumer builds a second device-registry row from these three; unvalued, that
+ # row shows a blank model and no firmware. `serial-number` is not here because the
+ # generator derives it as `-mid`, which is the resolvable link
+ # between the two halves of one unit.
+ mid_product_name: SPAN MID
+ mid_firmware_version: sim-mid/v0.1.0
+ mid_hardware_version: rev1
+ relative_position: UPSTREAM
+ nameplate_capacity_kwh: 13.5
+ initial_soe_kwh: 6.75
+ max_charge_w: 3500.0
+ max_discharge_w: 3500.0
+ charge_efficiency: 0.95
+ discharge_efficiency: 0.95
+ backup_reserve_pct: 20.0
+ charge_mode: self-consumption
+ charge_hours: [8, 9, 10, 11, 12, 13, 14, 15]
+ discharge_hours: [16, 17, 18, 19, 20, 21, 22]
+circuit_templates:
+ lighting:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 500.0
+ typical_power: 80.0
+ power_variation: 0.1
+ relay_behavior: controllable
+ priority: NEVER
+ breaker_rating: 15
+ time_of_day_profile:
+ enabled: true
+ hourly_multipliers:
+ 0: 0.1
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.1
+ 7: 0.3
+ 8: 0.2
+ 9: 0.1
+ 10: 0.1
+ 11: 0.1
+ 12: 0.1
+ 13: 0.1
+ 14: 0.1
+ 15: 0.1
+ 16: 0.2
+ 17: 0.4
+ 18: 0.8
+ 19: 1.0
+ 20: 1.0
+ 21: 1.0
+ 22: 0.7
+ 23: 0.3
+ exterior_lighting:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 300.0
+ typical_power: 60.0
+ power_variation: 0.1
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 15
+ time_of_day_profile:
+ enabled: true
+ hourly_multipliers:
+ 0: 0.3
+ 1: 0.3
+ 2: 0.3
+ 3: 0.3
+ 4: 0.3
+ 5: 0.3
+ 6: 0.1
+ 7: 0.0
+ 8: 0.0
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.0
+ 13: 0.0
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.0
+ 18: 0.3
+ 19: 0.7
+ 20: 1.0
+ 21: 1.0
+ 22: 1.0
+ 23: 0.5
+ outlets:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 1800.0
+ typical_power: 150.0
+ power_variation: 0.4
+ relay_behavior: controllable
+ priority: NEVER
+ breaker_rating: 15
+ kitchen_outlets:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 2400.0
+ typical_power: 300.0
+ power_variation: 0.5
+ relay_behavior: controllable
+ priority: NEVER
+ breaker_rating: 20
+ refrigerator:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 50.0
+ - 200.0
+ typical_power: 120.0
+ power_variation: 0.2
+ relay_behavior: non-controllable
+ priority: NEVER
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 600
+ off_duration: 1800
+ large_appliance:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 2500.0
+ typical_power: 1200.0
+ power_variation: 0.2
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 20
+ hvac:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 3500.0
+ typical_power: 2800.0
+ power_variation: 0.1
+ relay_behavior: controllable
+ priority: NEVER
+ breaker_rating: 30
+ cycling_pattern:
+ on_duration: 1200
+ off_duration: 2400
+ hvac_type: central_ac
+ time_of_day_profile:
+ enabled: true
+ hourly_multipliers:
+ 0: 0.3
+ 1: 0.3
+ 2: 0.3
+ 3: 0.3
+ 4: 0.3
+ 5: 0.3
+ 6: 0.4
+ 7: 0.5
+ 8: 0.5
+ 9: 0.5
+ 10: 0.6
+ 11: 0.6
+ 12: 0.7
+ 13: 0.7
+ 14: 0.8
+ 15: 0.9
+ 16: 1.0
+ 17: 1.0
+ 18: 1.0
+ 19: 1.0
+ 20: 1.0
+ 21: 1.0
+ 22: 0.7
+ 23: 0.4
+ peak_hours:
+ - 14
+ - 15
+ - 16
+ - 17
+ - 18
+ - 19
+ - 20
+ - 21
+ heat_pump:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 500.0
+ - 4000.0
+ typical_power: 2800.0
+ power_variation: 0.25
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 30
+ cycling_pattern:
+ on_duration: 900
+ off_duration: 1800
+ hvac_type: heat_pump
+ dishwasher:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 1800.0
+ typical_power: 1200.0
+ power_variation: 0.15
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 1200
+ off_duration: 600
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.0
+ 8: 0.0
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.0
+ 13: 0.0
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.0
+ 18: 0.0
+ 19: 0.8
+ 20: 1.0
+ 21: 0.5
+ 22: 0.0
+ 23: 0.0
+ washing_machine:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 1500.0
+ typical_power: 500.0
+ power_variation: 0.3
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 600
+ off_duration: 300
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.0
+ 8: 0.3
+ 9: 0.7
+ 10: 1.0
+ 11: 0.8
+ 12: 0.0
+ 13: 0.0
+ 14: 0.0
+ 15: 0.5
+ 16: 0.7
+ 17: 0.3
+ 18: 0.0
+ 19: 0.0
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+ microwave:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 1500.0
+ typical_power: 1000.0
+ power_variation: 0.1
+ relay_behavior: controllable
+ priority: NEVER
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 180
+ off_duration: 3420
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.4
+ 8: 0.3
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.6
+ 13: 0.4
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.3
+ 18: 0.5
+ 19: 0.3
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+ dryer:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 5000.0
+ typical_power: 3000.0
+ power_variation: 0.1
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 30
+ cycling_pattern:
+ on_duration: 2400
+ off_duration: 300
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.0
+ 8: 0.0
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.0
+ 13: 0.0
+ 14: 0.5
+ 15: 1.0
+ 16: 1.0
+ 17: 0.5
+ 18: 0.0
+ 19: 0.0
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+ oven_range:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 5000.0
+ typical_power: 2000.0
+ power_variation: 0.2
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 40
+ cycling_pattern:
+ on_duration: 600
+ off_duration: 600
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.2
+ 8: 0.2
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.3
+ 13: 0.0
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.5
+ 18: 1.0
+ 19: 0.8
+ 20: 0.3
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+ water_heater:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 4500.0
+ typical_power: 4500.0
+ power_variation: 0.05
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 30
+ cycling_pattern:
+ on_duration: 600
+ off_duration: 2400
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 0.1
+ 1: 0.1
+ 2: 0.1
+ 3: 0.1
+ 4: 0.1
+ 5: 0.2
+ 6: 0.6
+ 7: 1.0
+ 8: 0.8
+ 9: 0.4
+ 10: 0.2
+ 11: 0.2
+ 12: 0.2
+ 13: 0.2
+ 14: 0.2
+ 15: 0.2
+ 16: 0.3
+ 17: 0.5
+ 18: 0.8
+ 19: 1.0
+ 20: 0.7
+ 21: 0.4
+ 22: 0.2
+ 23: 0.1
+ span_drive:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 11500.0
+ typical_power: 7200.0
+ power_variation: 0.05
+ relay_behavior: controllable
+ priority: OFF_GRID
+ device_type: evse
+ breaker_rating: 50
+ smart_behavior:
+ responds_to_grid: true
+ max_power_reduction: 0.6
+ time_of_day_profile:
+ enabled: true
+ hour_factors:
+ 0: 1.0
+ 1: 1.0
+ 2: 1.0
+ 3: 1.0
+ 4: 1.0
+ 5: 1.0
+ 6: 0.0
+ 7: 0.0
+ 8: 0.0
+ 9: 0.0
+ 10: 0.0
+ 11: 0.0
+ 12: 0.0
+ 13: 0.0
+ 14: 0.0
+ 15: 0.0
+ 16: 0.0
+ 17: 0.0
+ 18: 0.0
+ 19: 0.0
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+ active_days:
+ - 0
+ - 2
+ - 4
+ - 6
+ solar:
+ energy_profile:
+ mode: producer
+ power_range:
+ - -10000.0
+ - 0.0
+ typical_power: -6000.0
+ power_variation: 0.25
+ efficiency: 0.85
+ nameplate_capacity_w: 10000.0
+ relay_behavior: non-controllable
+ priority: NEVER
+ # A grid-forming inverter. This is what makes the site islandable, which is what
+ # gives the BESS a MID -- the device carrying islanding-state and
+ # grid-forming-entity in v1.0. Shipped hybrid so a fresh clone exercises the MID
+ # path rather than the panel_config override above, which masks it.
+ #
+ # Its own key: `priority` means load shedding only. The two used to be the same
+ # field, so choosing an inverter also rewrote the circuit's published
+ # `default-priority`.
+ inverter_type: hybrid
+ device_type: pv
+ breaker_rating: 30
+ nameplate_capacity_w: 10000.0
+ pool:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 1200.0
+ typical_power: 800.0
+ power_variation: 0.1
+ relay_behavior: controllable
+ priority: OFF_GRID
+ breaker_rating: 20
+ cycling_pattern:
+ on_duration: 7200
+ off_duration: 14400
+ time_of_day_profile:
+ enabled: true
+ hourly_multipliers:
+ 0: 0.0
+ 1: 0.0
+ 2: 0.0
+ 3: 0.0
+ 4: 0.0
+ 5: 0.0
+ 6: 0.0
+ 7: 0.1
+ 8: 0.3
+ 9: 0.7
+ 10: 1.0
+ 11: 1.0
+ 12: 1.0
+ 13: 1.0
+ 14: 1.0
+ 15: 0.8
+ 16: 0.5
+ 17: 0.3
+ 18: 0.1
+ 19: 0.0
+ 20: 0.0
+ 21: 0.0
+ 22: 0.0
+ 23: 0.0
+ peak_hours:
+ - 10
+ - 11
+ - 12
+ - 13
+ - 14
+ - 15
+ always_on:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 40.0
+ - 100.0
+ typical_power: 60.0
+ power_variation: 0.1
+ relay_behavior: controllable
+ priority: NEVER
+ breaker_rating: 15
+ new_circuit_tpl:
+ energy_profile:
+ mode: consumer
+ power_range:
+ - 0.0
+ - 1800.0
+ typical_power: 150.0
+ power_variation: 0.3
+ relay_behavior: controllable
+ priority: NEVER
+ breaker_rating: 15
+circuits:
+- id: master_bedroom_lights
+ name: Master Bedroom Lights
+ template: lighting
+ tabs:
+ - 1
+ overrides:
+ typical_power: 40.0
+- id: living_room_lights
+ name: Living Room Lights
+ template: lighting
+ tabs:
+ - 2
+ overrides:
+ typical_power: 50.0
+- id: bedroom_lights
+ name: Bedroom Lights
+ template: lighting
+ tabs:
+ - 4
+- id: bathroom_lights
+ name: Bathroom Lights
+ template: lighting
+ tabs:
+ - 5
+ overrides:
+ typical_power: 30.0
+- id: exterior_lights
+ name: Exterior Lights
+ template: exterior_lighting
+ tabs:
+ - 6
+- id: master_bedroom_outlets
+ name: Master Bedroom Outlets
+ template: outlets
+ tabs:
+ - 7
+- id: living_room_outlets
+ name: Living Room Outlets
+ template: outlets
+ tabs:
+ - 8
+ overrides:
+ typical_power: 250.0
+- id: kitchen_outlets_1
+ name: Kitchen Outlets (Counter)
+ template: kitchen_outlets
+ tabs:
+ - 9
+- id: kitchen_outlets_2
+ name: Kitchen Outlets (Island)
+ template: kitchen_outlets
+ tabs:
+ - 10
+- id: office_outlets
+ name: Office Outlets
+ template: outlets
+ tabs:
+ - 11
+ overrides:
+ typical_power: 300.0
+- id: garage_outlets
+ name: Garage Outlets
+ template: outlets
+ tabs:
+ - 12
+- id: laundry_outlets
+ name: Laundry Room Outlets
+ template: outlets
+ tabs:
+ - 13
+- id: guest_room_outlets
+ name: Guest Room Outlets
+ template: outlets
+ tabs:
+ - 14
+- id: refrigerator
+ name: Refrigerator
+ template: refrigerator
+ tabs:
+ - 15
+- id: dishwasher
+ name: Dishwasher
+ template: dishwasher
+ tabs:
+ - 16
+- id: washing_machine
+ name: Washing Machine
+ template: washing_machine
+ tabs:
+ - 17
+- id: microwave
+ name: Microwave
+ template: microwave
+ tabs:
+ - 18
+- id: freezer
+ name: Chest Freezer
+ template: refrigerator
+ tabs:
+ - 19
+ overrides:
+ typical_power: 80.0
+- id: garbage_disposal
+ name: Garbage Disposal
+ template: always_on
+ tabs:
+ - 21
+ overrides:
+ typical_power: 0.0
+ power_range:
+ - 0.0
+ - 500.0
+- id: pool_pump
+ name: Pool Pump
+ template: pool
+ tabs:
+ - 39
+ breaker_rating: 20
+- id: smoke_detectors
+ name: Smoke Detectors
+ template: always_on
+ tabs:
+ - 40
+ overrides:
+ typical_power: 5.0
+ power_range:
+ - 3.0
+ - 10.0
+- id: dryer
+ name: Electric Dryer
+ template: dryer
+ tabs:
+ - 20
+ - 22
+- id: main_hvac
+ name: Main HVAC
+ template: hvac
+ tabs:
+ - 23
+ - 25
+ breaker_rating: 30
+ overrides:
+ typical_power: 1400.0
+- id: heat_pump
+ name: Heat Pump
+ template: heat_pump
+ tabs:
+ - 27
+ - 29
+- id: oven
+ name: Electric Oven/Range
+ template: oven_range
+ tabs:
+ - 28
+ - 30
+- id: water_heater
+ name: Water Heater
+ template: water_heater
+ tabs:
+ - 31
+ - 33
+- id: span_drive_garage
+ name: SPAN Drive - Garage
+ template: span_drive
+ tabs:
+ - 32
+ - 34
+ breaker_rating: 50
+- id: span_drive_driveway
+ name: SPAN Drive - Driveway
+ template: span_drive
+ tabs:
+ - 35
+ - 37
+- id: solar_inverter
+ name: Solar Inverter
+ template: solar
+ tabs:
+ - 36
+ - 38
+ breaker_rating: 30
+- id: new_circuit
+ name: kitchen Lights
+ template: new_circuit_tpl
+ tabs:
+ - 3
+ overrides:
+ power_range:
+ - 0.0
+ - 250.0
+unmapped_tabs: [24, 26]
+simulation_params:
+ update_interval: 5.0
+ time_acceleration: 1.0
+ noise_factor: 0.01
+ enable_realistic_behaviors: true
+ticks:
+- name: loads and both EVSEs with some PV
+ current_time: 0.0
+ grid_online: true
+ circuits:
+ master_bedroom_lights: 40.0
+ living_room_lights: 50.0
+ kitchen_outlets_1: 300.0
+ refrigerator: 120.0
+ main_hvac: 1400.0
+ water_heater: 4500.0
+ span_drive_garage: 2410.0
+ span_drive_driveway: 2420.0
+ solar_inverter: -2430.0
+- name: PV surplus charges BESS and exports
+ current_time: 60.0
+ grid_online: true
+ circuits:
+ master_bedroom_lights: 40.0
+ living_room_lights: 50.0
+ kitchen_outlets_1: 300.0
+ refrigerator: 120.0
+ main_hvac: 0.0
+ water_heater: 0.0
+ span_drive_garage: 2410.0
+ span_drive_driveway: 0.0
+ solar_inverter: -8500.0
+- name: grid outage, the BESS forms the island
+ current_time: 120.0
+ grid_online: false
+ circuits:
+ master_bedroom_lights: 40.0
+ living_room_lights: 50.0
+ kitchen_outlets_1: 300.0
+ refrigerator: 120.0
+ main_hvac: 0.0
+ water_heater: 0.0
+ span_drive_garage: 0.0
+ span_drive_driveway: 0.0
+ solar_inverter: -1200.0
diff --git a/tests/test_nameplate_has_one_source.py b/tests/test_nameplate_has_one_source.py
index eae465e..5dd9395 100644
--- a/tests/test_nameplate_has_one_source.py
+++ b/tests/test_nameplate_has_one_source.py
@@ -5,9 +5,10 @@
``pv`` section, which rates the inverter of the circuit it binds. The one
normaliser the engine, the dashboard and the history generator all run folds each
of them into the profile. A legacy value equal to the profile's, or one where the
-profile states none, folds silently; one that disagrees with the profile is
-refused by validation, naming both keys and both values, because picking either
-would be a guess.
+profile states none, folds silently. Against a stated profile, a stale top-level or
+override copy gives way with a WARNING, because only a released template put it
+there; a disagreeing ``pv`` section rating is refused, naming both keys and both
+values, because only a hand edit puts it there and picking either would be a guess.
Each published rating here is checked against what the engine produces, because
the bug these tests pin was a panel that published one rating and produced at
@@ -17,6 +18,7 @@
from __future__ import annotations
import copy
+import logging
from datetime import datetime
from typing import TYPE_CHECKING
from zoneinfo import ZoneInfo
@@ -129,28 +131,38 @@ async def test_a_legacy_rating_equal_to_the_profile_folds_silently(
@pytest.mark.parametrize(
- ("legacy", "key"),
- [
- ({"top_level": 9000.0}, "circuit_templates.solar.nameplate_capacity_w"),
- ({"override": 9000.0}, "circuits[solar_inverter].overrides.nameplate_capacity_w"),
- ({"section": 9000.0}, "pv.nameplate_capacity_w"),
- ],
- ids=["top level", "circuit override", "pv section"],
+ "legacy",
+ [{"top_level": 9000.0}, {"override": 9000.0}],
+ ids=["top level", "circuit override"],
)
-def test_a_legacy_rating_that_disagrees_with_the_profile_is_refused(
- legacy: dict[str, float], key: str
+@pytest.mark.asyncio
+async def test_a_stale_copy_beside_a_profile_rating_gives_way_to_it(
+ tmp_path: Path, caplog: pytest.LogCaptureFixture, legacy: dict[str, float]
) -> None:
- config = _panel(profile=3800.0, **legacy)
- normalize_config(config)
+ """No released writer wrote these two, and every released dashboard edit wrote the
+ profile, so the profile is the user's and the copy is dropped, with a WARNING."""
+ with caplog.at_level(logging.WARNING):
+ await _assert_rated(tmp_path, _panel(profile=3800.0, **legacy), 3800.0)
+
+ assert any(
+ "9000.0" in record.getMessage() and "3800.0" in record.getMessage()
+ for record in caplog.records
+ if record.levelno == logging.WARNING
+ )
+
+
+def test_a_pv_section_rating_that_disagrees_with_the_profile_is_refused() -> None:
+ """Only a hand edit fills the ``pv`` section's rating, so which value is meant is a
+ guess."""
+ config = _panel(profile=3800.0, section=9000.0)
+ normalize_config(config, source="test")
with pytest.raises(ValueError, match="nameplate") as refused:
validate_yaml_config(config)
message = str(refused.value)
- assert key in message
- assert "circuit_templates.solar.energy_profile.nameplate_capacity_w" in message
- assert "9000.0" in message
- assert "3800.0" in message
+ assert "pv.nameplate_capacity_w is 9000.0" in message
+ assert "circuit_templates.solar.energy_profile.nameplate_capacity_w is 3800.0" in message
def test_a_pv_section_rating_that_rates_no_inverter_is_refused() -> None:
@@ -172,7 +184,7 @@ def test_a_pv_section_rating_that_rates_no_inverter_is_refused() -> None:
{"id": "solar_garage", "name": "Garage", "template": "solar_garage", "tabs": [24]}
)
config["firmware_version"] = "spanos3/r202639/03"
- normalize_config(config)
+ normalize_config(config, source="test")
with pytest.raises(ValueError, match=r"pv\.nameplate_capacity_w is 7600\.0"):
validate_yaml_config(config)
@@ -187,7 +199,7 @@ def test_a_circuit_override_of_a_shared_template_is_refused() -> None:
pv = config["pv"]
assert isinstance(pv, dict)
pv["feed"] = _SOLAR
- normalize_config(config)
+ normalize_config(config, source="test")
with pytest.raises(ValueError, match=r"shared with 'solar_twin'"):
validate_yaml_config(config)
@@ -200,7 +212,7 @@ def test_the_top_level_key_still_wins_over_a_default_profile() -> None:
"circuit_templates": {"solar": {"device_type": "pv", "nameplate_capacity_w": 7600.0}},
}
- normalize_config(config)
+ normalize_config(config, source="test")
solar = _template(config, "solar")
energy_profile = solar["energy_profile"]
@@ -249,3 +261,22 @@ async def test_a_dashboard_nameplate_edit_survives_a_reload(tmp_path: Path) -> N
_, expected = await _rating(write_config(tmp_path / "control.yaml", _panel(profile=3800.0)))
assert published == "3800.0"
assert produced == expected
+
+
+def test_a_pv_section_rating_on_a_shared_template_is_told_to_split_it() -> None:
+ """Making the two agree would re-rate the other circuit on the template too, so the
+ advice is a template of the rated circuit's own."""
+ config = _panel(profile=3800.0, section=9000.0)
+ circuits = config["circuits"]
+ assert isinstance(circuits, list)
+ circuits.append({"id": "solar_twin", "name": "Twin", "template": "solar", "tabs": [24]})
+ pv = config["pv"]
+ assert isinstance(pv, dict)
+ pv["feed"] = _SOLAR
+ normalize_config(config, source="test")
+
+ with pytest.raises(ValueError, match="shared with 'solar_twin'") as refused:
+ validate_yaml_config(config)
+
+ assert "give the rated circuit its own template" in str(refused.value)
+ assert "make the two agree" not in str(refused.value)
diff --git a/tests/test_released_dashboard_edits_survive.py b/tests/test_released_dashboard_edits_survive.py
new file mode 100644
index 0000000..fea8204
--- /dev/null
+++ b/tests/test_released_dashboard_edits_survive.py
@@ -0,0 +1,151 @@
+"""A nameplate edited in a released dashboard survives the upgrade to one source.
+
+The MAIN 40 and MAIN 32 templates PanelBench 2.5.3 shipped each carried a second
+copy of the solar rating: MAIN 40 at the solar template's top level, MAIN 32 in the
+solar circuit's ``overrides``. A template clone copied it, and every released
+dashboard wrote a nameplate edit to ``energy_profile`` alone, leaving the copy
+behind. No released writer ever wrote either copy, so where the two disagree the
+profile is the user's edit and the copy is stale: the profile wins, the copy is
+dropped, and a WARNING names both values and the file.
+
+The fixtures are those two files exactly as 2.5.3 shipped them.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+from zoneinfo import ZoneInfo
+
+import pytest
+import yaml
+
+from panelbench.clone import TYPE_PV
+from panelbench.dashboard.config_store import ConfigStore
+from panelbench.emitter_adapter import runtime as emitter_runtime
+from panelbench.emitter_adapter.wire_capture import discovered_devices, recorded_panel
+from tests._helpers import write_config
+
+if TYPE_CHECKING:
+ from panelbench.config_types import SimulationConfig
+
+_RELEASED = Path(__file__).parent / "fixtures" / "released_2_5_3"
+_NOON = datetime(2026, 6, 15, 12, 0, tzinfo=ZoneInfo("America/Los_Angeles")).timestamp()
+
+_PANELS = [
+ # file, solar template, its stale copy's value, the dashboard edit
+ ("default_MAIN_40.yaml", "solar", 10000.0, 7600.0),
+ ("default_MAIN_32.yaml", "solar_production", 8000.0, 6000.0),
+]
+
+
+def _edited(name: str, template: str, watts: float) -> SimulationConfig:
+ """The released file *name*, with a released dashboard's nameplate edit to *watts*.
+
+ What 2.5.3's ``ConfigStore.update_entity`` wrote: the profile's rating, a power
+ range and typical power to match, and the circuit's power overrides cleared.
+ Nothing else, so the file's other copy of the rating stays as shipped.
+ """
+ config: SimulationConfig = yaml.safe_load((_RELEASED / name).read_text(encoding="utf-8"))
+ energy_profile = config["circuit_templates"][template]["energy_profile"]
+ energy_profile["nameplate_capacity_w"] = watts
+ energy_profile["power_range"] = [-watts, 0.0]
+ energy_profile["typical_power"] = -watts * 0.6
+ for circuit in config["circuits"]:
+ if circuit["template"] == template:
+ overrides = circuit.get("overrides") or {}
+ overrides.pop("typical_power", None)
+ overrides.pop("power_range", None)
+ return config
+
+
+def _stale_copies(config: object, template: str) -> list[object]:
+ """Every copy of *template*'s rating outside its profile, in *config* as YAML holds it."""
+ assert isinstance(config, dict)
+ templates = config["circuit_templates"]
+ assert isinstance(templates, dict)
+ copies: list[object] = []
+ if "nameplate_capacity_w" in templates[template]:
+ copies.append(templates[template]["nameplate_capacity_w"])
+ for circuit in config["circuits"]:
+ overrides = circuit.get("overrides") or {}
+ if circuit["template"] == template and "nameplate_capacity_w" in overrides:
+ copies.append(overrides["nameplate_capacity_w"])
+ return copies
+
+
+def _without_the_stale_copy(config: SimulationConfig, template: str) -> dict[str, object]:
+ """*config* as if its rating had only ever been in the profile: the control."""
+ control = yaml.safe_load(yaml.safe_dump(dict(config)))
+ assert isinstance(control, dict)
+ control["circuit_templates"][template].pop("nameplate_capacity_w", None)
+ for circuit in control["circuits"]:
+ if circuit["template"] == template:
+ (circuit.get("overrides") or {}).pop("nameplate_capacity_w", None)
+ return control
+
+
+async def _rating(path: Path) -> tuple[str | None, float]:
+ """The panel at *path*'s published ``info/nominal-power``, and what its solar
+ circuit produces at noon."""
+ runtime, recorder = await recorded_panel(path)
+ await emitter_runtime.publish_tick(runtime)
+ devices = discovered_devices(recorder.retained)
+ [pv] = [d for d in devices.values() if (d.description or {}).get("type") == TYPE_PV]
+ produced = runtime.engine.modelled_circuit_power("solar_inverter", _NOON)
+ assert produced > 0, "noon in June, so the inverter is producing"
+ return pv.get_property("info", "nominal-power"), produced
+
+
+@pytest.mark.parametrize(("name", "template", "stale", "watts"), _PANELS)
+@pytest.mark.asyncio
+async def test_a_released_edit_loads_and_is_the_rating(
+ tmp_path: Path,
+ caplog: pytest.LogCaptureFixture,
+ name: str,
+ template: str,
+ stale: float,
+ watts: float,
+) -> None:
+ config = _edited(name, template, watts)
+ path = write_config(tmp_path / "panel.yaml", config)
+ control = write_config(tmp_path / "control.yaml", _without_the_stale_copy(config, template))
+
+ with caplog.at_level(logging.WARNING):
+ published, produced = await _rating(path)
+
+ assert published == str(watts)
+ assert produced == (await _rating(control))[1]
+ warned = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
+ assert any(
+ str(path) in message and str(stale) in message and str(watts) in message
+ for message in warned
+ ), warned
+
+
+@pytest.mark.parametrize(("name", "template", "stale", "watts"), _PANELS)
+@pytest.mark.asyncio
+async def test_a_released_edit_survives_a_save_and_reload(
+ tmp_path: Path, name: str, template: str, stale: float, watts: float
+) -> None:
+ path = write_config(tmp_path / "panel.yaml", _edited(name, template, watts))
+ store = ConfigStore()
+ store.load_from_file(path)
+
+ store.save_to_file(path)
+
+ assert _stale_copies(_edited(name, template, watts), template) == [stale]
+ saved = yaml.safe_load(path.read_text(encoding="utf-8"))
+ assert _stale_copies(saved, template) == [], "the stale copy is gone from the file"
+ reloaded = ConfigStore()
+ reloaded.load_from_file(path)
+ assert reloaded.get_entity("solar_inverter").energy_profile["nameplate_capacity_w"] == watts
+ published, produced = await _rating(path)
+ assert published == str(watts)
+ control = write_config(
+ tmp_path / "control.yaml",
+ _without_the_stale_copy(_edited(name, template, watts), template),
+ )
+ assert produced == (await _rating(control))[1]
From 3679b04993156c7c26d0f71e9cbacbd73b040f8e Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:41:29 -0700
Subject: [PATCH 50/95] fix(dashboard): move the editor through one place, undo
a refused save, and refuse an unloadable clone
- The editor changes file only through DashboardContext.edit, which clears a
load error. Load, Clone, Start, Stop, Restart, deleting the open file and
clone-from-panel all open the file through one helper, which answers 400
with the reason where the panel would refuse it, so a stale "was not opened"
message no longer outlives the file it was about.
- A dashboard started on an unloadable active config shows the first shipped
template, read-only, instead of an empty panel.
- A refused save returns the editor to the last state the panel would load, so
one bad edit no longer refuses every save after it.
- Cloning a config the panel would refuse answers 400 with the reason and writes
nothing, where it answered 500 after writing the copy.
- The CHANGELOG names the failures released users hit: a saved edit the panel
then refused on restart, and no dashboard to fix it from.
---
CHANGELOG.md | 4 +-
src/panelbench/dashboard/__init__.py | 25 ++++--
src/panelbench/dashboard/config_store.py | 24 +++++-
src/panelbench/dashboard/context.py | 11 ++-
src/panelbench/dashboard/routes.py | 54 +++++++-----
...hboard_never_saves_an_unloadable_config.py | 86 +++++++++++++++++--
6 files changed, 159 insertions(+), 45 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f685c4..1fb4988 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -60,8 +60,8 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
- **A cloned panel keeps the source panel's name** instead of the generic "Span Panel".
- **An imported config counts as unsaved until it is saved**, so switching panels asks before discarding it.
- **The dashboard now fetches a read-only template's weather**, where a script error on its missing location search stopped it.
-- **The dashboard no longer saves a config the panel would refuse, says why when it refuses, and starts and explains when the active config is one**, where
- deleting the circuit `pv.feed` named saved such a config and the next add-on start then failed.
+- **The dashboard no longer saves a config the panel would refuse, and starts when the active config is one**, where such a save was written and the panel
+ then failed to restart, and an add-on restart with it active left no dashboard to fix it from; it now says why, and a refused save undoes the edit.
- **The dashboard's relay control shows a locked relay however its config spells it**, where a circuit written `non-controllable`, as the shipped configs
write it, showed `controllable` and saving its form unlocked it.
- **A solar inverter's nameplate edited in the dashboard now survives a restart and is the rating the panel both publishes and produces at**, including in a
diff --git a/src/panelbench/dashboard/__init__.py b/src/panelbench/dashboard/__init__.py
index 5aa0261..6917e7c 100644
--- a/src/panelbench/dashboard/__init__.py
+++ b/src/panelbench/dashboard/__init__.py
@@ -30,6 +30,16 @@
__all__ = ["DashboardContext", "create_dashboard_app"]
+def _view_first_default(context: DashboardContext, store: ConfigStore) -> None:
+ """Show the first shipped template, read-only, or nothing when there is none."""
+ defaults = sorted(context.config_dir.glob("default_*.yaml"))
+ if defaults:
+ store.load_from_file(defaults[0])
+ context.edit(defaults[0].name)
+ else:
+ context.edit(None)
+
+
def create_dashboard_app(context: DashboardContext) -> web.Application:
"""Create and return the dashboard aiohttp application."""
app = web.Application()
@@ -37,22 +47,21 @@ def create_dashboard_app(context: DashboardContext) -> web.Application:
store = ConfigStore()
# Load the active config into the editor/viewer. One the panel would refuse is
- # not opened, so nothing can be saved over it; the dashboard still starts, says
- # why, and lets the user pick or fix a config.
+ # not opened, so nothing can be saved over it: the dashboard still starts on the
+ # first default template, read-only, says why, and lets the user pick or fix a
+ # config.
if context.config_filter:
config_path = context.config_dir / context.config_filter
if config_path.exists():
try:
store.load_from_file(config_path)
except (ValueError, TypeError, yaml.YAMLError) as exc:
- context.load_error = f"{context.config_filter} was not opened: {exc}"
- context.config_filter = None
+ load_error = f"{context.config_filter} was not opened: {exc}"
+ _view_first_default(context, store)
+ context.load_error = load_error
else:
# No active config — show first default template (read-only).
- defaults = sorted(context.config_dir.glob("default_*.yaml"))
- if defaults:
- context.config_filter = defaults[0].name
- store.load_from_file(defaults[0])
+ _view_first_default(context, store)
app[APP_KEY_STORE] = store
app[APP_KEY_DASHBOARD_CONTEXT] = context
diff --git a/src/panelbench/dashboard/config_store.py b/src/panelbench/dashboard/config_store.py
index 96b9750..eea40d7 100644
--- a/src/panelbench/dashboard/config_store.py
+++ b/src/panelbench/dashboard/config_store.py
@@ -123,6 +123,11 @@ def __init__(self) -> None:
"enable_realistic_behaviors": True,
},
}
+ # The last state the panel would load, and whether it was unsaved: where a
+ # refused save returns the editor, so one bad edit does not refuse every save
+ # after it.
+ self._last_valid: dict[str, Any] = deepcopy(self._state)
+ self._last_valid_dirty = False
@property
def dirty(self) -> bool:
@@ -156,6 +161,7 @@ def load_from_mapping(
validate_yaml_config(state)
self._state = state
self._dirty = not saved
+ self._remember_valid()
def load_from_file(self, path: Path) -> None:
"""Read a file and load its content."""
@@ -177,12 +183,24 @@ def save_to_file(self, path: Path) -> None:
never write a config nothing will load.
Raises:
- ValueError: the panel would refuse the config; nothing is written.
+ ValueError: the panel would refuse the config. Nothing is written, and the
+ editor returns to the last state the panel would load, so the edit
+ that broke it is undone rather than refusing every later save too.
"""
- normalize_config(self._state, source=str(path))
- validate_yaml_config(self._state)
+ try:
+ normalize_config(self._state, source=str(path))
+ validate_yaml_config(self._state)
+ except ValueError:
+ self._state = deepcopy(self._last_valid)
+ self._dirty = self._last_valid_dirty
+ raise
path.write_text(self.export_yaml(), encoding="utf-8")
self._dirty = False
+ self._remember_valid()
+
+ def _remember_valid(self) -> None:
+ self._last_valid = deepcopy(self._state)
+ self._last_valid_dirty = self._dirty
# -- Panel config --
diff --git a/src/panelbench/dashboard/context.py b/src/panelbench/dashboard/context.py
index ce16ee5..eea503a 100644
--- a/src/panelbench/dashboard/context.py
+++ b/src/panelbench/dashboard/context.py
@@ -51,5 +51,14 @@ class DashboardContext:
history_provider: HistoryProvider | None = None
panel_browser: Any = None # PanelBrowser | None — mDNS discovery for standalone mode
# Why the active config could not be opened when the dashboard started, shown
- # until another config is loaded.
+ # until the editor moves to another config.
load_error: str | None = None
+
+ def edit(self, filename: str | None) -> None:
+ """Move the editor to *filename*, or to none.
+
+ The one way the editor changes file, so a load error, which is always about
+ the file the editor last failed to open, goes when it does.
+ """
+ self.config_filter = filename
+ self.load_error = None
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index 7a4bca8..4402cdd 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -27,6 +27,7 @@
from panelbench.bess_link import BESS_LINKS, is_bess_link
from panelbench.const import https_port_for
+from panelbench.dashboard.config_store import ConfigStore
from panelbench.dashboard.keys import (
APP_KEY_DASHBOARD_CONTEXT,
APP_KEY_PENDING_CLONES,
@@ -58,7 +59,7 @@
from panelbench.weather import fetch_historical_weather, get_cached_weather
if TYPE_CHECKING:
- from panelbench.dashboard.config_store import ConfigStore, EntityView
+ from panelbench.dashboard.config_store import EntityView
from panelbench.rates.cache import RateCache
_LOGGER = logging.getLogger(__name__)
@@ -140,6 +141,20 @@ def _available_configs(request: web.Request) -> list[str]:
return sorted(set(files))
+def _open_in_editor(request: web.Request, filename: str) -> None:
+ """Load *filename* into the editor and make it the file being edited.
+
+ Answers 400 with the panel's reason when it would refuse the file, and the editor
+ keeps what it had.
+ """
+ ctx = _ctx(request)
+ try:
+ _store(request).load_from_file(ctx.config_dir / filename)
+ except (ValueError, TypeError, yaml.YAMLError) as exc:
+ raise web.HTTPBadRequest(text=f"{filename} was not opened: {exc}") from exc
+ ctx.edit(filename)
+
+
def _first_default_config(config_dir: Path) -> str | None:
"""Return the filename of the first default_* template, or None."""
defaults = sorted(p.name for p in config_dir.glob("default_*.yaml"))
@@ -1714,15 +1729,9 @@ async def handle_load_config(request: web.Request) -> web.Response:
# Prevent path traversal
if config_path.resolve().parent != ctx.config_dir.resolve():
raise web.HTTPBadRequest(text="Invalid config file path")
- try:
- _store(request).load_from_file(config_path)
- except (ValueError, TypeError) as exc:
- raise web.HTTPBadRequest(text=str(exc)) from exc
-
# Track which file the editor is working on. Does NOT affect
# running engines — use Start/Stop/Restart in the panels list.
- ctx.config_filter = filename
- ctx.load_error = None
+ _open_in_editor(request, filename)
# Full page redirect so HTMX replaces the entire document
return web.Response(status=200, headers={"HX-Redirect": "./"})
@@ -1790,6 +1799,12 @@ async def handle_clone(request: web.Request) -> web.Response:
else:
yaml_content = _store(request).export_yaml()
+ # Refused before anything is written: a copy of a config the panel would not
+ # load is not a clone of anything.
+ try:
+ ConfigStore().load_from_yaml(yaml_content, source=str(output_path))
+ except (ValueError, TypeError, yaml.YAMLError) as exc:
+ raise web.HTTPBadRequest(text=f"Not cloned: {exc}") from exc
output_path.write_text(yaml_content, encoding="utf-8")
_LOGGER.info("Config cloned to %s", output_path)
@@ -1809,8 +1824,7 @@ async def handle_clone(request: web.Request) -> web.Response:
# Auto-switch the editor to the newly cloned config so the entity
# list, runtime controls, and modeling view all reflect the clone.
- _store(request).load_from_file(output_path)
- ctx.config_filter = filename
+ _open_in_editor(request, filename)
return web.Response(status=200, headers={"HX-Redirect": "./"})
@@ -1944,8 +1958,7 @@ async def handle_start_panel(request: web.Request) -> web.Response:
ctx = _ctx(request)
ctx.start_panel(filename)
# Auto-switch the editor to this panel so entity list stays in sync.
- _store(request).load_from_file(ctx.config_dir / filename)
- ctx.config_filter = filename
+ _open_in_editor(request, filename)
return web.Response(status=200, headers={"HX-Redirect": "./"})
@@ -1956,8 +1969,7 @@ async def handle_stop_panel(request: web.Request) -> web.Response:
return err
ctx = _ctx(request)
ctx.stop_panel(filename)
- _store(request).load_from_file(ctx.config_dir / filename)
- ctx.config_filter = filename
+ _open_in_editor(request, filename)
return web.Response(status=200, headers={"HX-Redirect": "./"})
@@ -1968,8 +1980,7 @@ async def handle_restart_panel(request: web.Request) -> web.Response:
return err
ctx = _ctx(request)
ctx.restart_panel(filename)
- _store(request).load_from_file(ctx.config_dir / filename)
- ctx.config_filter = filename
+ _open_in_editor(request, filename)
return web.Response(status=200, headers={"HX-Redirect": "./"})
@@ -2112,9 +2123,10 @@ async def handle_delete_config(request: web.Request) -> web.Response:
# the first default template (read-only).
if filename == ctx.config_filter:
first_default = _first_default_config(ctx.config_dir)
- ctx.config_filter = first_default
if first_default:
- _store(request).load_from_file(ctx.config_dir / first_default)
+ _open_in_editor(request, first_default)
+ else:
+ ctx.edit(None)
return web.Response(
status=200,
headers={"HX-Redirect": "./"},
@@ -2223,9 +2235,7 @@ async def _finalize_clone(
clone_path = write_clone_config(config, ctx.config_dir, origin_serial, filename=filename)
# Load the clone config into the dashboard editor
- store = _store(request)
- store.load_from_file(clone_path)
- ctx.config_filter = clone_path.name
+ _open_in_editor(request, clone_path.name)
_LOGGER.info("Panel cloned from %s -> %s", host, clone_path.name)
@@ -2284,7 +2294,7 @@ async def _finalize_clone(
if profiles_imported:
# Re-read config after profile application
- store.load_from_file(clone_path)
+ _open_in_editor(request, clone_path.name)
# Redirect to refresh the full dashboard with the new config
return web.Response(status=200, headers={"HX-Redirect": "./"})
diff --git a/tests/test_dashboard_never_saves_an_unloadable_config.py b/tests/test_dashboard_never_saves_an_unloadable_config.py
index ac6ccad..d6ed9c5 100644
--- a/tests/test_dashboard_never_saves_an_unloadable_config.py
+++ b/tests/test_dashboard_never_saves_an_unloadable_config.py
@@ -9,6 +9,7 @@
from __future__ import annotations
import copy
+from pathlib import Path
from typing import TYPE_CHECKING
import pytest
@@ -22,11 +23,10 @@
from tests._helpers import CURRENT_FIRMWARE, EARLIER_FIRMWARE, default_config, write_config
if TYPE_CHECKING:
- from pathlib import Path
-
from panelbench.config_types import SimulationConfig
_FILE = "panel.yaml"
+_SHIPPED = Path(__file__).resolve().parents[1] / "configs"
def _with_inverters(firmware: str, *extra: str, feed: str | None) -> SimulationConfig:
@@ -52,6 +52,9 @@ def _with_inverters(firmware: str, *extra: str, feed: str | None) -> SimulationC
def _app(tmp_path: Path, config: SimulationConfig | dict[str, object]) -> web.Application:
+ """The dashboard, with *config* the active file beside the shipped templates."""
+ for shipped in sorted(_SHIPPED.glob("default_*.yaml")):
+ (tmp_path / shipped.name).write_text(shipped.read_text(encoding="utf-8"), encoding="utf-8")
write_config(tmp_path / _FILE, config)
return create_dashboard_app(
DashboardContext(
@@ -125,19 +128,84 @@ async def test_a_save_the_loader_would_refuse_is_refused_and_writes_nothing(
@pytest.mark.asyncio
-async def test_the_dashboard_starts_on_an_unloadable_active_config(tmp_path: Path) -> None:
+async def test_a_refused_save_returns_the_editor_to_the_config_it_last_saved(
+ tmp_path: Path,
+) -> None:
+ """Otherwise every later save, of any circuit, is refused for the first edit."""
config = default_config()
- pv = config.get("pv")
- assert pv is not None
- pv["feed"] = "no_such_circuit"
+ config["circuits"] = [c for c in config["circuits"] if c["id"] == "solar_inverter"]
app = _app(tmp_path, config)
+ async with TestClient(TestServer(app)) as client:
+ await client.delete("/entities/solar_inverter")
+ refused = await client.post("/save-reload")
+ listed = await (await client.get("/entities")).text()
+ saved = await client.post("/save-reload")
+
+ assert refused.status == 422
+ assert "solar_inverter" in listed, "the refused delete is undone in the editor"
+ assert saved.status == 200
+
+
+@pytest.mark.asyncio
+async def test_the_dashboard_starts_on_an_unloadable_active_config(tmp_path: Path) -> None:
+ app = _app(tmp_path, _unloadable())
+
async with TestClient(TestServer(app)) as client:
page = await client.get("/")
html = await page.text()
assert page.status == 200
assert "pv.feed 'no_such_circuit' names no circuit" in html
- assert app[APP_KEY_DASHBOARD_CONTEXT].config_filter is None, (
- "nothing is open, so nothing can be saved over the file"
- )
+ # The first shipped template, read-only, rather than an empty panel, and never the
+ # refused file, so nothing can be saved over it.
+ assert app[APP_KEY_DASHBOARD_CONTEXT].config_filter == "default_MAIN_16.yaml"
+ assert "sim-16t-001" in html
+
+
+@pytest.mark.parametrize(
+ ("path", "form"),
+ [
+ ("/load-config", {"config_file": "default_MAIN_16.yaml"}),
+ ("/clone", {"filename": "copy.yaml", "source_file": "default_MAIN_16.yaml"}),
+ ("/restart-panel", {"filename": "default_MAIN_16.yaml"}),
+ ],
+ ids=["load", "clone", "restart"],
+)
+@pytest.mark.asyncio
+async def test_moving_the_editor_to_another_config_clears_the_load_error(
+ tmp_path: Path, path: str, form: dict[str, str]
+) -> None:
+ app = _app(tmp_path, _unloadable())
+
+ async with TestClient(TestServer(app)) as client:
+ moved = await client.post(path, data=form)
+ html = await (await client.get("/")).text()
+
+ assert moved.status == 200
+ assert app[APP_KEY_DASHBOARD_CONTEXT].load_error is None
+ assert "was not opened" not in html
+
+
+@pytest.mark.asyncio
+async def test_cloning_an_unloadable_config_is_refused_with_the_reason(tmp_path: Path) -> None:
+ write_config(tmp_path / "broken.yaml", _unloadable())
+ app = _app(tmp_path, default_config())
+
+ async with TestClient(TestServer(app)) as client:
+ cloned = await client.post(
+ "/clone", data={"filename": "copy.yaml", "source_file": "broken.yaml"}
+ )
+ reason = await cloned.text()
+
+ assert cloned.status == 400
+ assert "names no circuit" in reason
+ assert not (tmp_path / "copy.yaml").exists()
+
+
+def _unloadable() -> SimulationConfig:
+ config = default_config()
+ pv = config.get("pv")
+ assert pv is not None
+ pv["feed"] = "no_such_circuit"
+ return config
From 4697d514f31e4d49fb8a7f20e41f0f0d636bce2f Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:52:43 -0700
Subject: [PATCH 51/95] fix(config): keep a shared template's override, and say
how to clear a stale rating
- An override counts as stale beside a dashboard edit only on its template's
sole circuit, the shape the released MAIN 32 had. On a template other
circuits share it is a deliberate per-circuit rating that only a hand edit
makes, so a disagreeing one is refused with the advice to give the rated
circuit its own template, rather than dropped.
- The stale-rating WARNING repeats on every load until the file is saved, so it
now ends "save the config in the dashboard to remove it from the file".
- A template clone is a write the user asked for, so where the loader would
change its content it is written as the loader reads it. It warns once, not
once per reader after.
The CHANGELOG matches.
---
CHANGELOG.md | 7 +--
src/panelbench/dashboard/routes.py | 10 +++-
src/panelbench/pv_rating.py | 23 ++++++---
tests/test_nameplate_has_one_source.py | 22 ++++++++
.../test_released_dashboard_edits_survive.py | 50 ++++++++++++++++++-
5 files changed, 97 insertions(+), 15 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1fb4988..1eb134c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,9 +36,10 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
solar circuit was listed first**; a `pv.feed` that names no solar circuit's `id` is now refused, as is a config with several solar circuits and no `pv.feed`
whose `firmware_version` names a release before 202639.
- **A solar rating set in the dashboard now replaces the stale copy a clone of the shipped MAIN 40 or MAIN 32 template kept**, at the template's top level or
- in the solar circuit's `overrides`, and the log warns with both values and the file.
-- **A `pv.nameplate_capacity_w` that disagrees with its circuit template's `energy_profile` rating is now refused, naming both**, where the two could each win
- somewhere different; an equal or lone legacy rating moves into the template's `energy_profile`.
+ in the solar circuit's `overrides`, and the log warns with both values and the file until the config is saved in the dashboard.
+- **A `pv.nameplate_capacity_w`, or a circuit's `overrides` rating on a template other circuits share, that disagrees with the template's `energy_profile`
+ rating is now refused, naming both**, where the two could each win somewhere different; an equal or lone legacy rating moves into the template's
+ `energy_profile`.
- **Every solar device is now named after its own device id**, as SPAN firmware names an inverter, where it was named "Solar", "Solar 2" and so on in circuit
order.
- **The shipped MAIN 32 config reports hardware version `1.2`**, as a SPAN Panel MAIN 32 publishes it; the other shipped configs keep `rev2` and so report
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index 4402cdd..e5922be 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -1800,11 +1800,17 @@ async def handle_clone(request: web.Request) -> web.Response:
yaml_content = _store(request).export_yaml()
# Refused before anything is written: a copy of a config the panel would not
- # load is not a clone of anything.
+ # load is not a clone of anything. A clone is a write the user asked for, so it
+ # is written as the loader reads it, a stale rating copy already gone, rather
+ # than warning every reader after; content the loader changes nothing in keeps
+ # its text, comments and all.
+ clone = ConfigStore()
try:
- ConfigStore().load_from_yaml(yaml_content, source=str(output_path))
+ clone.load_from_yaml(yaml_content, source=str(output_path))
except (ValueError, TypeError, yaml.YAMLError) as exc:
raise web.HTTPBadRequest(text=f"Not cloned: {exc}") from exc
+ if yaml.safe_load(clone.export_yaml()) != yaml.safe_load(yaml_content):
+ yaml_content = clone.export_yaml()
output_path.write_text(yaml_content, encoding="utf-8")
_LOGGER.info("Config cloned to %s", output_path)
diff --git a/src/panelbench/pv_rating.py b/src/panelbench/pv_rating.py
index 8529b68..1bec14b 100644
--- a/src/panelbench/pv_rating.py
+++ b/src/panelbench/pv_rating.py
@@ -22,11 +22,13 @@
on who could have written it. Every released dashboard wrote a nameplate edit to the
profile alone, and no released writer ever wrote the template's top level or a
circuit's override; the shipped MAIN 40 and MAIN 32 templates carried one of those
-two, and a template clone copied it. So against either of those the profile wins,
-the stale copy is dropped, and a WARNING names both values and the file. Only a
-hand edit puts a rating in the ``pv`` section, or two legacy ratings where the
-profile states none, so a disagreement there is refused, naming both keys and both
-values, because picking either would be a guess. The ``pv`` section's rating stays
+two, and a template clone copied it. So against the template's top level, or an
+override on the template's only circuit (the MAIN 32 shape), the profile wins, the
+stale copy is dropped, and a WARNING names both values and the file. Only a hand
+edit puts a rating in the ``pv`` section, an override on a template other circuits
+share, or two legacy ratings where the profile states none, so a disagreement there
+is refused, naming both keys and both values, because picking either would be a
+guess. The ``pv`` section's rating stays
where it is only for an inverter with no PV circuit, one upstream of the panel,
where it is the sole source.
"""
@@ -61,8 +63,8 @@ class _Claim:
# override does not leave `overrides: {}` behind.
empties: tuple[dict[str, object], str] | None = None
# Whether a released writer could have left this behind beside a dashboard edit:
- # true of the template's top level and a circuit's override, never of the `pv`
- # section, which only a hand edit fills.
+ # true of the template's top level and of an override on the template's only
+ # circuit, never of the `pv` section, which only a hand edit fills.
stale_beside_an_edit: bool = True
@@ -193,6 +195,10 @@ def _claims(
overrides,
circuit_id,
empties=(circuit, "overrides"),
+ # Stale beside an edit only on the template's sole circuit, the
+ # shape the released MAIN 32 had. Beside other circuits it is a
+ # deliberate per-circuit rating, which only a hand edit makes.
+ stale_beside_an_edit=len(circuits) == 1,
)
)
rates_one_of_these = any(str(circuit.get("id")) == bound for circuit in circuits)
@@ -238,7 +244,8 @@ def _template_plan(
dropped = tuple(
f"{claim.where} is {_shown(claim.value)} but {canonical_key}, which the "
f"dashboard edits, is {_shown(stated)}: rating the circuit {_shown(stated)} "
- f"and dropping the stale {claim.where}"
+ f"and dropping the stale {claim.where}; save the config in the dashboard to "
+ "remove it from the file"
for claim in stale
)
removed = tuple(
diff --git a/tests/test_nameplate_has_one_source.py b/tests/test_nameplate_has_one_source.py
index 5dd9395..8541f44 100644
--- a/tests/test_nameplate_has_one_source.py
+++ b/tests/test_nameplate_has_one_source.py
@@ -280,3 +280,25 @@ def test_a_pv_section_rating_on_a_shared_template_is_told_to_split_it() -> None:
assert "give the rated circuit its own template" in str(refused.value)
assert "make the two agree" not in str(refused.value)
+
+
+def test_a_disagreeing_override_on_a_shared_template_is_refused() -> None:
+ """An override stale beside a dashboard edit is the released MAIN 32 shape: the
+ template's only circuit. Beside other circuits on the template it is a deliberate
+ per-circuit rating that only a hand edit makes, so which is meant is a guess."""
+ config = _panel(profile=10000.0, override=3800.0)
+ circuits = config["circuits"]
+ assert isinstance(circuits, list)
+ circuits.append({"id": "solar_twin", "name": "Twin", "template": "solar", "tabs": [24]})
+ pv = config["pv"]
+ assert isinstance(pv, dict)
+ pv["feed"] = _SOLAR
+ normalize_config(config, source="test")
+
+ with pytest.raises(ValueError, match="shared with 'solar_twin'") as refused:
+ validate_yaml_config(config)
+
+ assert "circuits[solar_inverter].overrides.nameplate_capacity_w is 3800.0" in str(
+ refused.value
+ )
+ assert "give the rated circuit its own template" in str(refused.value)
diff --git a/tests/test_released_dashboard_edits_survive.py b/tests/test_released_dashboard_edits_survive.py
index fea8204..8a189e6 100644
--- a/tests/test_released_dashboard_edits_survive.py
+++ b/tests/test_released_dashboard_edits_survive.py
@@ -21,12 +21,14 @@
import pytest
import yaml
+from aiohttp.test_utils import TestClient, TestServer
from panelbench.clone import TYPE_PV
+from panelbench.dashboard import DashboardContext, create_dashboard_app
from panelbench.dashboard.config_store import ConfigStore
from panelbench.emitter_adapter import runtime as emitter_runtime
from panelbench.emitter_adapter.wire_capture import discovered_devices, recorded_panel
-from tests._helpers import write_config
+from tests._helpers import default_config, write_config
if TYPE_CHECKING:
from panelbench.config_types import SimulationConfig
@@ -120,7 +122,10 @@ async def test_a_released_edit_loads_and_is_the_rating(
assert produced == (await _rating(control))[1]
warned = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
assert any(
- str(path) in message and str(stale) in message and str(watts) in message
+ str(path) in message
+ and str(stale) in message
+ and str(watts) in message
+ and "save the config in the dashboard to remove it from the file" in message
for message in warned
), warned
@@ -149,3 +154,44 @@ async def test_a_released_edit_survives_a_save_and_reload(
_without_the_stale_copy(_edited(name, template, watts), template),
)
assert produced == (await _rating(control))[1]
+
+
+@pytest.mark.parametrize(("name", "template", "stale", "watts"), _PANELS)
+@pytest.mark.asyncio
+async def test_a_template_clone_writes_the_stale_copy_out_once(
+ tmp_path: Path,
+ caplog: pytest.LogCaptureFixture,
+ name: str,
+ template: str,
+ stale: float,
+ watts: float,
+) -> None:
+ """Cloning is a write the user asked for, so the clone holds the rating once and
+ the stale copy is warned about once, not by every reader after."""
+ write_config(tmp_path / "edited.yaml", _edited(name, template, watts))
+ write_config(tmp_path / "active.yaml", default_config())
+ app = create_dashboard_app(
+ DashboardContext(
+ config_dir=tmp_path,
+ config_filter="active.yaml",
+ get_panel_configs=lambda: {},
+ get_panel_ports=lambda: {},
+ request_reload=lambda: None,
+ )
+ )
+
+ caplog.clear()
+ with caplog.at_level(logging.WARNING):
+ async with TestClient(TestServer(app)) as client:
+ cloned = await client.post(
+ "/clone", data={"filename": "copy.yaml", "source_file": "edited.yaml"}
+ )
+
+ assert cloned.status == 200
+ assert _stale_copies(yaml.safe_load((tmp_path / "copy.yaml").read_text()), template) == []
+ warned = [
+ r.getMessage()
+ for r in caplog.records
+ if r.levelno == logging.WARNING and "stale" in r.getMessage()
+ ]
+ assert len(warned) == 1, warned
From 35546a9208147713b48e3965c1466cf622ff9e49 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:56:52 -0700
Subject: [PATCH 52/95] fix(dashboard): refuse an edit the panel would not
load, not the save after it
A refused save rolled the editor back to the last loaded or saved config, so it
threw away every unsaved edit made before the one the panel refused, and cleared
the flag that warns before switching panels.
Every change to the editor's config now goes through ConfigStore.edit. It makes
the change on a copy, normalises and validates the copy as the panel will, and
keeps it only if the panel would load it. Every public mutator is one edit, and
a handler that changes two things at once (a profile with its active days, an
EV schedule with its days) wraps both in one. A refused edit raises
EditRefused, and one middleware answers it for every handler: 422 with the
reason, and a page reload, so the page shows what the store holds and the
reason rather than an edit the store does not. The store and its unsaved flag
are as they were.
A save is no longer refused for an edit, so its rollback is gone; it still
validates, as a guard. Deleting the last circuit, or the pv.feed circuit where
that leaves an unloadable binding, is now refused when it is asked for. A new
plain circuit takes the first free space, since the panel refuses one with
none. The CHANGELOG says so.
---
CHANGELOG.md | 4 +-
src/panelbench/dashboard/__init__.py | 4 +-
src/panelbench/dashboard/config_store.py | 144 ++++++++++++-----
src/panelbench/dashboard/context.py | 8 +
src/panelbench/dashboard/routes.py | 49 ++++--
.../dashboard/templates/dashboard.html | 1 +
tests/test_config_store.py | 11 +-
...hboard_never_saves_an_unloadable_config.py | 46 +++---
...st_dashboard_refuses_an_unloadable_edit.py | 147 ++++++++++++++++++
9 files changed, 330 insertions(+), 84 deletions(-)
create mode 100644 tests/test_dashboard_refuses_an_unloadable_edit.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1eb134c..89f2bfc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -61,8 +61,8 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
- **A cloned panel keeps the source panel's name** instead of the generic "Span Panel".
- **An imported config counts as unsaved until it is saved**, so switching panels asks before discarding it.
- **The dashboard now fetches a read-only template's weather**, where a script error on its missing location search stopped it.
-- **The dashboard no longer saves a config the panel would refuse, and starts when the active config is one**, where such a save was written and the panel
- then failed to restart, and an add-on restart with it active left no dashboard to fix it from; it now says why, and a refused save undoes the edit.
+- **The dashboard refuses an edit the panel would not load, says why and keeps the config as it was, and starts when the active config is one the panel
+ refuses**, where such an edit was saved and the panel then failed to restart, and an add-on restart with it active left no dashboard to fix it from.
- **The dashboard's relay control shows a locked relay however its config spells it**, where a circuit written `non-controllable`, as the shipped configs
write it, showed `controllable` and saving its form unlocked it.
- **A solar inverter's nameplate edited in the dashboard now survives a restart and is the rating the panel both publishes and produces at**, including in a
diff --git a/src/panelbench/dashboard/__init__.py b/src/panelbench/dashboard/__init__.py
index 6917e7c..60a4f1c 100644
--- a/src/panelbench/dashboard/__init__.py
+++ b/src/panelbench/dashboard/__init__.py
@@ -24,7 +24,7 @@
APP_KEY_STORE,
)
from panelbench.dashboard.presets import init_presets
-from panelbench.dashboard.routes import setup_routes
+from panelbench.dashboard.routes import refuse_unloadable_edits, setup_routes
from panelbench.rates.cache import RateCache
__all__ = ["DashboardContext", "create_dashboard_app"]
@@ -42,7 +42,7 @@ def _view_first_default(context: DashboardContext, store: ConfigStore) -> None:
def create_dashboard_app(context: DashboardContext) -> web.Application:
"""Create and return the dashboard aiohttp application."""
- app = web.Application()
+ app = web.Application(middlewares=[refuse_unloadable_edits])
store = ConfigStore()
diff --git a/src/panelbench/dashboard/config_store.py b/src/panelbench/dashboard/config_store.py
index eea40d7..0945ab1 100644
--- a/src/panelbench/dashboard/config_store.py
+++ b/src/panelbench/dashboard/config_store.py
@@ -2,20 +2,27 @@
Holds the full simulator config as a mutable dict tree (matching the
YAML schema). Changes only persist when the user explicitly saves.
+
+Every change goes through ``ConfigStore.edit``: it is made on a copy, normalised and
+validated as the panel will validate it, and kept only if the panel would load it.
+So the store never holds a config the panel would refuse, and a save cannot be
+refused for an edit.
"""
from __future__ import annotations
+import functools
+from contextlib import contextmanager
from copy import deepcopy
from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, Concatenate, cast
import yaml
from panelbench.inverter import AC_COUPLED, normalise_inverter_type, template_inverter_type
if TYPE_CHECKING:
- from collections.abc import Mapping
+ from collections.abc import Callable, Iterator, Mapping
from pathlib import Path
from panelbench.config_defaults import normalize_config
@@ -29,7 +36,6 @@
get_preset,
)
from panelbench.emitter_adapter.spec_generator import normalise_relay_behavior, relay_locked
-from panelbench.pv_section import bound_pv_circuit_id
from panelbench.solar import compute_solar_curve
from panelbench.validation import validate_yaml_config
from panelbench.weather import get_cached_weather
@@ -99,6 +105,24 @@ def _detect_entity_type(template: dict[str, Any]) -> str:
_IMPORTED = "the imported config"
+_EDITED = "the dashboard's edit"
+
+
+class EditRefused(ValueError):
+ """An edit the panel would not load. The store is as it was before it."""
+
+
+def _one_edit[**P, R](
+ method: Callable[Concatenate[ConfigStore, P], R],
+) -> Callable[Concatenate[ConfigStore, P], R]:
+ """Make *method* one ``ConfigStore.edit``: all of its change or none of it."""
+
+ @functools.wraps(method)
+ def edit(store: ConfigStore, /, *args: P.args, **kwargs: P.kwargs) -> R:
+ with store.edit():
+ return method(store, *args, **kwargs)
+
+ return edit
class ConfigStore:
@@ -123,11 +147,7 @@ def __init__(self) -> None:
"enable_realistic_behaviors": True,
},
}
- # The last state the panel would load, and whether it was unsaved: where a
- # refused save returns the editor, so one bad edit does not refuse every save
- # after it.
- self._last_valid: dict[str, Any] = deepcopy(self._state)
- self._last_valid_dirty = False
+ self._editing = False
@property
def dirty(self) -> bool:
@@ -161,7 +181,6 @@ def load_from_mapping(
validate_yaml_config(state)
self._state = state
self._dirty = not saved
- self._remember_valid()
def load_from_file(self, path: Path) -> None:
"""Read a file and load its content."""
@@ -179,34 +198,55 @@ def export_yaml(self) -> str:
def save_to_file(self, path: Path) -> None:
"""Serialize current state to YAML and write to disk, normalised as on load.
- Validated first, as the panel will validate it, so a dashboard action can
- never write a config nothing will load.
+ Validated first, as the panel will validate it. Every edit already was, so
+ this only guards a store changed some other way: nothing is written then.
Raises:
- ValueError: the panel would refuse the config. Nothing is written, and the
- editor returns to the last state the panel would load, so the edit
- that broke it is undone rather than refusing every later save too.
+ ValueError: the panel would refuse the config; nothing is written.
"""
- try:
- normalize_config(self._state, source=str(path))
- validate_yaml_config(self._state)
- except ValueError:
- self._state = deepcopy(self._last_valid)
- self._dirty = self._last_valid_dirty
- raise
+ normalize_config(self._state, source=str(path))
+ validate_yaml_config(self._state)
path.write_text(self.export_yaml(), encoding="utf-8")
self._dirty = False
- self._remember_valid()
- def _remember_valid(self) -> None:
- self._last_valid = deepcopy(self._state)
- self._last_valid_dirty = self._dirty
+ @contextmanager
+ def edit(self) -> Iterator[None]:
+ """Make the changes inside one edit the panel would load, or none of them.
+
+ The changes are made on a copy of the state, which is normalised and
+ validated as the panel will validate it and kept only if the panel would load
+ it. Every public mutator is one edit; a handler that makes several changes as
+ one wraps them in another, and an edit inside an edit is part of it.
+
+ Raises:
+ EditRefused: the panel would not load the result; the state and the
+ unsaved-changes flag are as they were.
+ """
+ if self._editing:
+ yield
+ return
+ original, was_dirty = self._state, self._dirty
+ self._state = deepcopy(original)
+ self._editing = True
+ try:
+ yield
+ normalize_config(self._state, source=_EDITED)
+ try:
+ validate_yaml_config(self._state)
+ except ValueError as exc:
+ raise EditRefused(str(exc)) from exc
+ except BaseException:
+ self._state, self._dirty = original, was_dirty
+ raise
+ finally:
+ self._editing = False
# -- Panel config --
def get_panel_config(self) -> dict[str, Any]:
return dict(self._state.get("panel_config", {}))
+ @_one_edit
def update_panel_config(self, data: dict[str, Any]) -> None:
cfg = self._state.setdefault("panel_config", {})
for key in ("serial_number", "total_tabs", "main_size"):
@@ -252,6 +292,7 @@ def has_bess(self) -> bool:
bess = self._state.get("bess")
return isinstance(bess, dict) and bool(bess.get("enabled"))
+ @_one_edit
def update_bess_config(self, data: dict[str, Any]) -> None:
"""Update top-level BESS settings from form data.
@@ -271,6 +312,7 @@ def update_bess_config(self, data: dict[str, Any]) -> None:
bess[yaml_key] = float(data[form_key])
self._dirty = True
+ @_one_edit
def add_bess(self) -> None:
"""Add a default BESS configuration."""
self._state["bess"] = {
@@ -287,6 +329,7 @@ def add_bess(self) -> None:
}
self._dirty = True
+ @_one_edit
def remove_bess(self) -> None:
"""Remove the BESS configuration."""
self._state.pop("bess", None)
@@ -297,6 +340,7 @@ def remove_bess(self) -> None:
def get_simulation_params(self) -> dict[str, Any]:
return dict(self._state.get("simulation_params", {}))
+ @_one_edit
def update_simulation_params(self, data: dict[str, Any]) -> None:
params = self._state.setdefault("simulation_params", {})
for key in ("update_interval", "time_acceleration", "noise_factor"):
@@ -338,6 +382,7 @@ def get_recorder_map(self) -> dict[str, str]:
return dict(rm)
return {}
+ @_one_edit
def restore_recorder(self, entity_id: str) -> bool:
"""Restore a template to its original recorder state.
@@ -379,6 +424,7 @@ def restore_recorder(self, entity_id: str) -> bool:
self._dirty = True
return True
+ @_one_edit
def toggle_user_modified(self, entity_id: str) -> bool:
"""Toggle the user_modified flag on a template. Returns the new value.
@@ -449,6 +495,7 @@ def get_entity(self, entity_id: str) -> EntityView:
raise KeyError(f"Entity not found: {entity_id}")
return self._merge_entity(circuit)
+ @_one_edit
def update_entity(self, entity_id: str, data: dict[str, Any]) -> None:
"""Update circuit and template fields from form data.
@@ -542,9 +589,22 @@ def update_entity(self, entity_id: str, data: dict[str, Any]) -> None:
self._mark_user_modified(template_name)
self._dirty = True
+ @_one_edit
def add_entity(self, entity_type: str) -> EntityView:
- """Create a new entity with type-appropriate defaults."""
+ """Create a new entity with type-appropriate defaults.
+
+ A circuit is placed on the first unmapped space, since the panel refuses a
+ circuit with none.
+
+ Raises:
+ EditRefused: a circuit was asked for and no space is free.
+ """
entity_id, template_name, template_dict, circuit_dict = make_defaults(entity_type)
+ if entity_type == "circuit" and not circuit_dict.get("tabs"):
+ free = self.get_unmapped_tabs()
+ if not free:
+ raise EditRefused("No unmapped space is left for a circuit")
+ circuit_dict["tabs"] = [free[0]]
existing_ids = {c["id"] for c in self._circuits()}
base_id = entity_id
@@ -567,6 +627,7 @@ def get_unmapped_tabs(self) -> list[int]:
used.update(circ.get("tabs", []))
return sorted(t for t in range(1, total_tabs + 1) if t not in used)
+ @_one_edit
def add_entity_from_tabs(self, tabs: list[int]) -> EntityView:
"""Create a new circuit entity assigned to the given tabs.
@@ -608,35 +669,27 @@ def add_entity_from_tabs(self, tabs: list[int]) -> EntityView:
self._dirty = True
return self._merge_entity(circuit_dict)
+ @_one_edit
def delete_entity(self, entity_id: str) -> None:
"""Remove an entity and its template if no other circuit uses it.
A ``pv.feed`` naming the circuit goes with it, and then the ``pv`` section
binds by the sole-circuit rule as usual (``pv_section.bound_pv_circuit_id``).
- Where that rule refuses what is left -- before SPAN release 202639, several
- PV circuits and no ``pv.feed`` -- the delete is refused with its reason and
- nothing changes, rather than leaving a config the panel will not load.
+ Where the panel would refuse what is left -- before SPAN release 202639,
+ several PV circuits and no ``pv.feed``, or no circuit at all -- the edit is
+ refused and nothing changes.
Raises:
KeyError: no circuit has *entity_id*.
- ValueError: the config left behind binds no inverter it can publish.
+ EditRefused: the panel would not load the config left behind.
"""
circuits = self._circuits()
index = next((i for i, c in enumerate(circuits) if c.get("id") == entity_id), None)
if index is None:
raise KeyError(f"Entity not found: {entity_id}")
- pv = self._state.get("pv")
- drops_feed = isinstance(pv, dict) and "feed" in pv and str(pv["feed"]) == str(entity_id)
- after: dict[str, object] = {
- **self._state,
- "circuits": circuits[:index] + circuits[index + 1 :],
- }
- if drops_feed and isinstance(pv, dict):
- after["pv"] = {key: value for key, value in pv.items() if key != "feed"}
- bound_pv_circuit_id(after)
-
circuit = circuits.pop(index)
- if drops_feed and isinstance(pv, dict):
+ pv = self._state.get("pv")
+ if isinstance(pv, dict) and str(pv.get("feed")) == str(entity_id):
pv.pop("feed")
template_name = circuit["template"]
still_used = any(c.get("template") == template_name for c in circuits)
@@ -656,6 +709,7 @@ def get_active_days(self, entity_id: str) -> list[int]:
days: list[int] = tod.get("active_days", [])
return [d for d in days if isinstance(d, int) and 0 <= d <= 6]
+ @_one_edit
def update_active_days(self, entity_id: str, days: list[int]) -> None:
"""Write active weekdays into the entity's template."""
circuit = self._find_circuit(entity_id)
@@ -683,6 +737,7 @@ def get_bess_active_days(self) -> list[int]:
days: list[int] = bess.get("active_days", [])
return [d for d in days if isinstance(d, int) and 0 <= d <= 6]
+ @_one_edit
def update_bess_active_days(self, days: list[int]) -> None:
"""Write active weekdays into BESS config."""
bess = self._state.setdefault("bess", {"enabled": True})
@@ -734,6 +789,7 @@ def get_entity_profile(self, entity_id: str) -> dict[int, float]:
return multipliers
+ @_one_edit
def update_entity_profile(self, entity_id: str, multipliers: dict[int, float]) -> None:
"""Write 24-hour multipliers into the entity's template."""
circuit = self._find_circuit(entity_id)
@@ -757,6 +813,7 @@ def update_entity_profile(self, entity_id: str, multipliers: dict[int, float]) -
self._mark_user_modified(template_name)
self._dirty = True
+ @_one_edit
def apply_preset(
self,
entity_id: str,
@@ -806,6 +863,7 @@ def get_battery_charge_mode(self) -> str:
return raw
return "self-consumption"
+ @_one_edit
def update_battery_charge_mode(
self,
mode: str,
@@ -849,6 +907,7 @@ def get_battery_profile(self) -> dict[int, str]:
profile[h] = "idle"
return profile
+ @_one_edit
def update_battery_profile(self, hour_modes: dict[int, str]) -> None:
"""Write per-hour charge/discharge/idle schedule into BESS config."""
bess = self._state.setdefault("bess", {"enabled": True})
@@ -856,6 +915,7 @@ def update_battery_profile(self, hour_modes: dict[int, str]) -> None:
bess["discharge_hours"] = sorted(h for h, m in hour_modes.items() if m == "discharge")
self._dirty = True
+ @_one_edit
def apply_battery_preset(self, preset_name: str) -> dict[int, str]:
"""Apply a named battery preset and return the schedule."""
hour_modes = get_battery_preset(preset_name)
@@ -918,6 +978,7 @@ def get_evse_schedule(self, entity_id: str) -> dict[str, Any]:
"profile": profile,
}
+ @_one_edit
def update_evse_schedule(self, entity_id: str, start_hour: int, duration_hours: int) -> None:
"""Update EVSE charging schedule from start hour and duration."""
circuit = self._find_circuit(entity_id)
@@ -936,6 +997,7 @@ def update_evse_schedule(self, entity_id: str, start_hour: int, duration_hours:
self._mark_user_modified(template_name)
self._dirty = True
+ @_one_edit
def apply_evse_preset(self, entity_id: str, preset_name: str) -> dict[int, float]:
"""Apply an EVSE charging preset and return the schedule factors."""
factors = get_evse_preset(preset_name)
diff --git a/src/panelbench/dashboard/context.py b/src/panelbench/dashboard/context.py
index eea503a..cbb5ec5 100644
--- a/src/panelbench/dashboard/context.py
+++ b/src/panelbench/dashboard/context.py
@@ -54,6 +54,14 @@ class DashboardContext:
# until the editor moves to another config.
load_error: str | None = None
+ # Why the last edit was refused, shown once on the page that reloads after it.
+ notice: str | None = None
+
+ def take_notice(self) -> str | None:
+ """The notice to show, once."""
+ notice, self.notice = self.notice, None
+ return notice
+
def edit(self, filename: str | None) -> None:
"""Move the editor to *filename*, or to none.
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index e5922be..043075d 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -16,6 +16,7 @@
from ebus_panel_sim import EmitterError
if TYPE_CHECKING:
+ from collections.abc import Awaitable, Callable
from pathlib import Path
import multidict
@@ -27,7 +28,7 @@
from panelbench.bess_link import BESS_LINKS, is_bess_link
from panelbench.const import https_port_for
-from panelbench.dashboard.config_store import ConfigStore
+from panelbench.dashboard.config_store import ConfigStore, EditRefused
from panelbench.dashboard.keys import (
APP_KEY_DASHBOARD_CONTEXT,
APP_KEY_PENDING_CLONES,
@@ -141,6 +142,24 @@ def _available_configs(request: web.Request) -> list[str]:
return sorted(set(files))
+@web.middleware
+async def refuse_unloadable_edits(
+ request: web.Request, handler: Callable[[web.Request], Awaitable[web.StreamResponse]]
+) -> web.StreamResponse:
+ """Answer an edit the panel would not load, from any handler, in one way.
+
+ The store has already refused it and is as it was, so the answer is 422 with the
+ reason and a page reload: the page then shows what the store holds, and the
+ reason, rather than an edit the store does not.
+ """
+ try:
+ return await handler(request)
+ except EditRefused as exc:
+ ctx = _ctx(request)
+ ctx.notice = f"Not changed: {exc}"
+ return web.Response(status=422, text=ctx.notice, headers={"HX-Refresh": "true"})
+
+
def _open_in_editor(request: web.Request, filename: str) -> None:
"""Load *filename* into the editor and make it the file being edited.
@@ -228,6 +247,7 @@ def _dashboard_context(request: web.Request) -> dict[str, Any]:
"readonly": _is_readonly(ctx),
"bess_config": store.get_bess_config(),
"load_error": ctx.load_error,
+ "notice": ctx.take_notice(),
}
@@ -832,8 +852,8 @@ def _persist_config(request: web.Request) -> None:
def _save_or_refuse(store: ConfigStore, output_path: Path) -> None:
"""Save *store* to *output_path*, or answer 422 with why the panel would refuse it.
- The store validates before it writes, so a refused save leaves the file as the
- panel last loaded it.
+ Every edit is validated as it is made, so this answers only for a store changed
+ some other way; nothing is written then.
"""
try:
store.save_to_file(output_path)
@@ -940,10 +960,7 @@ async def handle_put_entity(request: web.Request) -> web.Response:
async def handle_delete_entity(request: web.Request) -> web.Response:
entity_id = request.match_info["id"]
- try:
- _store(request).delete_entity(entity_id)
- except ValueError as exc:
- raise web.HTTPConflict(text=f"Not deleted: {exc}") from exc
+ _store(request).delete_entity(entity_id)
return _render("partials/entity_list.html", request, _entity_list_context(request))
@@ -986,10 +1003,11 @@ async def handle_put_profile(request: web.Request) -> web.Response:
if key in data:
multipliers[h] = float(str(data[key]))
store = _store(request)
- store.update_entity_profile(entity_id, multipliers)
- active = _parse_active_days(data)
- if active is not None:
- store.update_active_days(entity_id, active)
+ with store.edit():
+ store.update_entity_profile(entity_id, multipliers)
+ active = _parse_active_days(data)
+ if active is not None:
+ store.update_active_days(entity_id, active)
return _render("partials/profile_editor.html", request, _profile_context(request, entity_id))
@@ -1144,10 +1162,11 @@ async def handle_put_evse_schedule(request: web.Request) -> web.Response:
start = int(str(data.get("charge_start", "0")))
duration = int(str(data.get("charge_duration", "6")))
store = _store(request)
- store.update_evse_schedule(entity_id, start, duration)
- active = _parse_active_days(data)
- if active is not None:
- store.update_active_days(entity_id, active)
+ with store.edit():
+ store.update_evse_schedule(entity_id, start, duration)
+ active = _parse_active_days(data)
+ if active is not None:
+ store.update_active_days(entity_id, active)
return _render(
"partials/evse_schedule.html",
request,
diff --git a/src/panelbench/dashboard/templates/dashboard.html b/src/panelbench/dashboard/templates/dashboard.html
index c305637..7305106 100644
--- a/src/panelbench/dashboard/templates/dashboard.html
+++ b/src/panelbench/dashboard/templates/dashboard.html
@@ -11,6 +11,7 @@ Getting started
{% include "partials/running_panels.html" %}
diff --git a/tests/test_config_store.py b/tests/test_config_store.py
index 9940569..b230dcb 100644
--- a/tests/test_config_store.py
+++ b/tests/test_config_store.py
@@ -39,6 +39,14 @@
""")
+_SECOND_CIRCUIT = """ tabs: [1]
+ - id: light_2
+ name: Light 2
+ template: lighting
+ tabs: [2]
+"""
+
+
class TestDirtyFlag:
def test_starts_clean(self) -> None:
store = ConfigStore()
@@ -75,8 +83,9 @@ def test_add_entity_sets_dirty(self) -> None:
assert store.dirty is True
def test_delete_entity_sets_dirty(self) -> None:
+ """Of two circuits, since the panel refuses a config with none."""
store = ConfigStore()
- store.load_from_yaml(MINIMAL_YAML)
+ store.load_from_yaml(MINIMAL_YAML.replace(" tabs: [1]\n", _SECOND_CIRCUIT))
store.delete_entity("light_1")
assert store.dirty is True
diff --git a/tests/test_dashboard_never_saves_an_unloadable_config.py b/tests/test_dashboard_never_saves_an_unloadable_config.py
index d6ed9c5..c3f53b2 100644
--- a/tests/test_dashboard_never_saves_an_unloadable_config.py
+++ b/tests/test_dashboard_never_saves_an_unloadable_config.py
@@ -18,6 +18,7 @@
from aiohttp.test_utils import TestClient, TestServer
from panelbench.dashboard import DashboardContext, create_dashboard_app
+from panelbench.dashboard import config_store as config_store_module
from panelbench.dashboard.keys import APP_KEY_DASHBOARD_CONTEXT
from panelbench.validation import validate_yaml_config
from tests._helpers import CURRENT_FIRMWARE, EARLIER_FIRMWARE, default_config, write_config
@@ -102,49 +103,48 @@ async def test_a_delete_that_leaves_an_unloadable_config_is_refused(tmp_path: Pa
reason = await deleted.text()
listed = await (await client.get("/entities")).text()
- assert deleted.status == 409
+ assert deleted.status == 422
assert "set pv.feed" in reason
assert "solar_inverter" in listed, "the circuit is still there"
@pytest.mark.asyncio
-async def test_a_save_the_loader_would_refuse_is_refused_and_writes_nothing(
- tmp_path: Path,
-) -> None:
- """A panel needs at least one circuit, so deleting the last one cannot be saved."""
+async def test_deleting_the_last_circuit_is_refused(tmp_path: Path) -> None:
+ """A panel needs at least one circuit, so the delete is refused, not a later save."""
config = default_config()
config["circuits"] = [c for c in config["circuits"] if c["id"] == "solar_inverter"]
app = _app(tmp_path, config)
- before = (tmp_path / _FILE).read_text(encoding="utf-8")
async with TestClient(TestServer(app)) as client:
- await client.delete("/entities/solar_inverter")
- saved = await client.post("/save-reload")
- reason = await saved.text()
+ deleted = await client.delete("/entities/solar_inverter")
+ reason = await deleted.text()
+ listed = await (await client.get("/entities")).text()
- assert saved.status == 422
+ assert deleted.status == 422
assert "At least one circuit must be defined" in reason
- assert (tmp_path / _FILE).read_text(encoding="utf-8") == before
+ assert "solar_inverter" in listed
@pytest.mark.asyncio
-async def test_a_refused_save_returns_the_editor_to_the_config_it_last_saved(
- tmp_path: Path,
+async def test_a_save_still_refuses_a_config_the_panel_would_not_load(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
- """Otherwise every later save, of any circuit, is refused for the first edit."""
- config = default_config()
- config["circuits"] = [c for c in config["circuits"] if c["id"] == "solar_inverter"]
- app = _app(tmp_path, config)
+ """Every edit is validated as it is made, so this is a guard for a store changed
+ some other way: the save answers 422 and writes nothing."""
+ app = _app(tmp_path, default_config())
+ before = (tmp_path / _FILE).read_text(encoding="utf-8")
+
+ def refuse(_config: object) -> None:
+ raise ValueError("refused for the test")
+ monkeypatch.setattr(config_store_module, "validate_yaml_config", refuse)
async with TestClient(TestServer(app)) as client:
- await client.delete("/entities/solar_inverter")
- refused = await client.post("/save-reload")
- listed = await (await client.get("/entities")).text()
saved = await client.post("/save-reload")
+ reason = await saved.text()
- assert refused.status == 422
- assert "solar_inverter" in listed, "the refused delete is undone in the editor"
- assert saved.status == 200
+ assert saved.status == 422
+ assert "refused for the test" in reason
+ assert (tmp_path / _FILE).read_text(encoding="utf-8") == before
@pytest.mark.asyncio
diff --git a/tests/test_dashboard_refuses_an_unloadable_edit.py b/tests/test_dashboard_refuses_an_unloadable_edit.py
new file mode 100644
index 0000000..cda3eb5
--- /dev/null
+++ b/tests/test_dashboard_refuses_an_unloadable_edit.py
@@ -0,0 +1,147 @@
+"""The dashboard refuses an edit the panel would not load, and nothing else.
+
+Every change to the editor's config is made on a copy, normalised and validated as
+the panel will validate it, and swapped in only if the panel would load it.
+Otherwise the request answers 422 with the reason, the editor's config is as it
+was, and the page reloads, so it never shows an edit the editor does not hold.
+
+Refusing the save instead, as the dashboard did, threw away every unsaved edit made
+before the one the panel refused, and cleared the flag that warns before switching
+panels.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from aiohttp import web
+from aiohttp.test_utils import TestClient, TestServer
+
+from panelbench.dashboard import DashboardContext, create_dashboard_app
+from panelbench.dashboard import config_store as config_store_module
+from panelbench.dashboard.keys import APP_KEY_STORE
+from tests._helpers import default_config, write_config
+
+_FILE = "panel.yaml"
+
+
+@pytest.fixture
+def app(tmp_path: Path) -> web.Application:
+ """The dashboard, editing a saved copy of the shipped MAIN 40 config."""
+ write_config(tmp_path / _FILE, default_config())
+ return create_dashboard_app(
+ DashboardContext(
+ config_dir=tmp_path,
+ config_filter=_FILE,
+ get_panel_configs=lambda: {},
+ get_panel_ports=lambda: {},
+ request_reload=lambda: None,
+ )
+ )
+
+
+def _refuse_everything(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Make the panel refuse any config the editor validates from here on."""
+
+ def refuse(_config: object) -> None:
+ raise ValueError("refused for the test")
+
+ monkeypatch.setattr(config_store_module, "validate_yaml_config", refuse)
+
+
+@pytest.mark.parametrize(
+ ("method", "path", "form"),
+ [
+ ("PUT", "/panel-config", {"serial_number": "renamed"}),
+ ("PUT", "/sim-params", {"update_interval": "7"}),
+ ("POST", "/entities", {"entity_type": "evse"}),
+ ("DELETE", "/entities/living_room_lights", {}),
+ ("PUT", "/entities/pool_pump/profile", {"hour_0": "0.5"}),
+ ("POST", "/entities/pool_pump/profile/preset", {"preset": "always_on"}),
+ ("PUT", "/entities/pool_pump/active-days", {"days_submitted": "1", "day_0": "on"}),
+ (
+ "PUT",
+ "/entities/span_drive_garage/evse-schedule",
+ {"charge_start": "1", "charge_duration": "4"},
+ ),
+ ("POST", "/entities/span_drive_garage/evse-schedule/preset", {"preset": "night"}),
+ ],
+ ids=[
+ "panel config",
+ "sim params",
+ "add circuit",
+ "delete circuit",
+ "profile",
+ "preset",
+ "active days",
+ "EV schedule",
+ "EV preset",
+ ],
+)
+@pytest.mark.asyncio
+async def test_every_kind_of_edit_is_refused_whole(
+ app: web.Application,
+ monkeypatch: pytest.MonkeyPatch,
+ method: str,
+ path: str,
+ form: dict[str, str],
+) -> None:
+ store = app[APP_KEY_STORE]
+ before = store.export_yaml()
+ _refuse_everything(monkeypatch)
+
+ async with TestClient(TestServer(app)) as client:
+ refused = await client.request(method, path, data=form)
+ reason = await refused.text()
+
+ assert refused.status == 422
+ assert "refused for the test" in reason
+ assert refused.headers.get("HX-Refresh") == "true", "the page reloads to what the editor holds"
+ assert store.export_yaml() == before
+ assert not store.dirty
+
+
+@pytest.mark.asyncio
+async def test_an_earlier_unsaved_edit_survives_a_later_refused_one(
+ app: web.Application,
+) -> None:
+ """Tabs 1 and 4 are not a double-pole pair, so the panel refuses that edit alone."""
+ async with TestClient(TestServer(app)) as client:
+ renamed = await client.put("/panel-config", data={"serial_number": "sim-renamed"})
+ refused = await client.put("/entities/bedroom_lights", data={"tabs": "1,4"})
+ reason = await refused.text()
+ dirty = await (await client.get("/check-dirty")).json()
+ page = await (await client.get("/")).text()
+
+ store = app[APP_KEY_STORE]
+ assert renamed.status == 200
+ assert refused.status == 422
+ assert "mixed parity" in reason
+ assert store.get_panel_config()["serial_number"] == "sim-renamed"
+ assert store.get_entity("bedroom_lights").tabs != [1, 4]
+ assert dirty == {"dirty": True}, "the rename is still unsaved, so switching panels still asks"
+ assert "mixed parity" in page, "the reloaded page says why"
+
+
+@pytest.mark.asyncio
+async def test_a_refused_edit_leaves_a_saved_config_saved(app: web.Application) -> None:
+ async with TestClient(TestServer(app)) as client:
+ refused = await client.put("/entities/bedroom_lights", data={"tabs": "1,4"})
+ dirty = await (await client.get("/check-dirty")).json()
+
+ assert refused.status == 422
+ assert dirty == {"dirty": False}
+
+
+@pytest.mark.asyncio
+async def test_a_new_circuit_takes_the_first_free_space(app: web.Application) -> None:
+ """A circuit with no space is one the panel refuses, so it is placed on one."""
+ store = app[APP_KEY_STORE]
+ free = store.get_unmapped_tabs()
+
+ async with TestClient(TestServer(app)) as client:
+ added = await client.post("/entities", data={"entity_type": "circuit"})
+
+ assert added.status == 200
+ assert free[0] not in store.get_unmapped_tabs()
From ffe3529eb01671ef818611128e1f01f691f8d92f Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:58:01 -0700
Subject: [PATCH 53/95] test: share the rating helpers, and guard the released
template files unedited
NOON and the published-and-produced rating read move into tests/_helpers.py, as
pv_rating, from the four modules that each defined their own. The synthetic test
that a stale top-level or override copy gives way to the profile goes: the
released-file test pins the same outcome on the files users hold, and the
synthetic module keeps only the shapes those files cannot express. The released
fixtures name the commit their bytes come from, and a new test starts each one
unedited, a guard that a 2.5.3 template clone still runs.
---
tests/_helpers.py | 23 +++++++-
tests/test_engine_circuit_accessors.py | 14 ++---
tests/test_nameplate_has_one_source.py | 59 ++++---------------
tests/test_readme_rehearsal.py | 7 +--
.../test_released_dashboard_edits_survive.py | 48 +++++++--------
5 files changed, 63 insertions(+), 88 deletions(-)
diff --git a/tests/_helpers.py b/tests/_helpers.py
index 50f6dcc..505510f 100644
--- a/tests/_helpers.py
+++ b/tests/_helpers.py
@@ -9,12 +9,14 @@
from __future__ import annotations
import copy
+from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING, Final
+from zoneinfo import ZoneInfo
import yaml
-from panelbench.clone import translate_panel_tree
+from panelbench.clone import TYPE_PV, translate_panel_tree
from panelbench.emitter_adapter import runtime as emitter_runtime
from panelbench.emitter_adapter.runtime import bess_config_from_engine
from panelbench.emitter_adapter.wire_capture import (
@@ -39,6 +41,9 @@
EARLIER_FIRMWARE: Final = "spanos2/r202633/02"
CURRENT_FIRMWARE: Final = "spanos2/r202639/01"
+# Midday in June where the shipped panels sit, so an inverter there is producing.
+NOON: Final = datetime(2026, 6, 15, 12, 0, tzinfo=ZoneInfo("America/Los_Angeles")).timestamp()
+
def default_config() -> SimulationConfig:
"""A fresh copy of the shipped default config, to modify and then write."""
@@ -102,3 +107,19 @@ def discharging_bess_meter(runtime: CloneRuntime, recorder: RecordingTransport)
# An idle battery shows no frame at all, so no caller may pass on one.
assert flow < 0, "the battery discharges at night, so power flows out of it"
return meter
+
+
+async def pv_rating(path: Path, circuit_id: str = "solar_inverter") -> tuple[str | None, float]:
+ """The panel at *path*'s one PV device's published ``info/nominal-power``, and what
+ its PV circuit *circuit_id* produces at `NOON`.
+
+ Both, because a rating is a contract on the wire and on the power: the bug the
+ callers pin was a panel that published one rating and produced at another.
+ """
+ runtime, recorder = await recorded_panel(path)
+ await emitter_runtime.publish_tick(runtime)
+ devices = discovered_devices(recorder.retained)
+ [pv] = [d for d in devices.values() if (d.description or {}).get("type") == TYPE_PV]
+ produced = runtime.engine.modelled_circuit_power(circuit_id, NOON)
+ assert produced > 0, "noon in June, so the inverter is producing"
+ return pv.get_property("info", "nominal-power"), produced
diff --git a/tests/test_engine_circuit_accessors.py b/tests/test_engine_circuit_accessors.py
index 9f31813..4435697 100644
--- a/tests/test_engine_circuit_accessors.py
+++ b/tests/test_engine_circuit_accessors.py
@@ -7,20 +7,16 @@
from __future__ import annotations
-from datetime import datetime
from typing import TYPE_CHECKING
-from zoneinfo import ZoneInfo
import pytest
from panelbench.emitter_adapter.wire_capture import recorded_panel
-from tests._helpers import default_config, write_config
+from tests._helpers import NOON, default_config, write_config
if TYPE_CHECKING:
from pathlib import Path
-_NOON = datetime(2026, 6, 15, 12, 0, tzinfo=ZoneInfo("America/Los_Angeles")).timestamp()
-
@pytest.mark.asyncio
async def test_a_circuit_template_is_the_one_the_engine_runs_and_a_copy(tmp_path: Path) -> None:
@@ -49,9 +45,9 @@ async def test_modelled_power_is_deterministic_and_reads_nothing_into_the_panel(
assert behavior is not None
state = behavior.capture_mutable_state()
- first = engine.modelled_circuit_power("solar_inverter", _NOON)
- second = engine.modelled_circuit_power("solar_inverter", _NOON)
- engine.modelled_circuit_power("pool_pump", _NOON)
+ first = engine.modelled_circuit_power("solar_inverter", NOON)
+ second = engine.modelled_circuit_power("solar_inverter", NOON)
+ engine.modelled_circuit_power("pool_pump", NOON)
assert first == second > 0
assert behavior.capture_mutable_state() == state
@@ -64,4 +60,4 @@ async def test_an_unknown_circuit_is_a_key_error(tmp_path: Path) -> None:
with pytest.raises(KeyError):
runtime.engine.circuit_template("no_such_circuit")
with pytest.raises(KeyError):
- runtime.engine.modelled_circuit_power("no_such_circuit", _NOON)
+ runtime.engine.modelled_circuit_power("no_such_circuit", NOON)
diff --git a/tests/test_nameplate_has_one_source.py b/tests/test_nameplate_has_one_source.py
index 8541f44..21aeff9 100644
--- a/tests/test_nameplate_has_one_source.py
+++ b/tests/test_nameplate_has_one_source.py
@@ -6,9 +6,11 @@
normaliser the engine, the dashboard and the history generator all run folds each
of them into the profile. A legacy value equal to the profile's, or one where the
profile states none, folds silently. Against a stated profile, a stale top-level or
-override copy gives way with a WARNING, because only a released template put it
-there; a disagreeing ``pv`` section rating is refused, naming both keys and both
-values, because only a hand edit puts it there and picking either would be a guess.
+sole-circuit override copy gives way with a WARNING, because only a released template
+put it there: ``test_released_dashboard_edits_survive.py`` pins that on the released
+files themselves. A disagreeing ``pv`` section rating, or an override on a template
+other circuits share, is refused, naming both keys and both values, because only a
+hand edit puts it there and picking either would be a guess.
Each published rating here is checked against what the engine produces, because
the bug these tests pin was a panel that published one rating and produced at
@@ -18,21 +20,15 @@
from __future__ import annotations
import copy
-import logging
-from datetime import datetime
from typing import TYPE_CHECKING
-from zoneinfo import ZoneInfo
import pytest
import yaml
-from panelbench.clone import TYPE_PV
from panelbench.config_defaults import normalize_config
from panelbench.dashboard.config_store import ConfigStore
-from panelbench.emitter_adapter import runtime as emitter_runtime
-from panelbench.emitter_adapter.wire_capture import discovered_devices, recorded_panel
from panelbench.validation import validate_yaml_config
-from tests._helpers import default_config, write_config
+from tests._helpers import default_config, pv_rating, write_config
if TYPE_CHECKING:
from pathlib import Path
@@ -40,8 +36,6 @@
from panelbench.config_types import SimulationConfig
_SOLAR = "solar_inverter"
-# Midday in June where the default panel sits, so the inverter is producing.
-_NOON = datetime(2026, 6, 15, 12, 0, tzinfo=ZoneInfo("America/Los_Angeles")).timestamp()
def _panel(
@@ -85,23 +79,11 @@ def _circuit(config: dict[str, object], circuit_id: str) -> dict[str, object]:
return circuit
-async def _rating(path: Path) -> tuple[str | None, float]:
- """The panel at *path*'s published ``info/nominal-power``, and what its solar
- circuit produces at noon."""
- runtime, recorder = await recorded_panel(path)
- await emitter_runtime.publish_tick(runtime)
- devices = discovered_devices(recorder.retained)
- [pv] = [d for d in devices.values() if (d.description or {}).get("type") == TYPE_PV]
- produced = runtime.engine.modelled_circuit_power(_SOLAR, _NOON)
- assert produced > 0, "noon in June, so the inverter is producing"
- return pv.get_property("info", "nominal-power"), produced
-
-
async def _assert_rated(tmp_path: Path, config: dict[str, object], watts: float) -> None:
"""*config* publishes *watts* and produces exactly what a panel stating only
``energy_profile.nameplate_capacity_w: watts`` produces."""
- published, produced = await _rating(write_config(tmp_path / "panel.yaml", config))
- _, expected = await _rating(write_config(tmp_path / "control.yaml", _panel(profile=watts)))
+ published, produced = await pv_rating(write_config(tmp_path / "panel.yaml", config))
+ _, expected = await pv_rating(write_config(tmp_path / "control.yaml", _panel(profile=watts)))
assert published == str(watts)
assert produced == expected
@@ -130,27 +112,6 @@ async def test_a_legacy_rating_equal_to_the_profile_folds_silently(
await _assert_rated(tmp_path, _panel(profile=3800.0, **legacy), 3800.0)
-@pytest.mark.parametrize(
- "legacy",
- [{"top_level": 9000.0}, {"override": 9000.0}],
- ids=["top level", "circuit override"],
-)
-@pytest.mark.asyncio
-async def test_a_stale_copy_beside_a_profile_rating_gives_way_to_it(
- tmp_path: Path, caplog: pytest.LogCaptureFixture, legacy: dict[str, float]
-) -> None:
- """No released writer wrote these two, and every released dashboard edit wrote the
- profile, so the profile is the user's and the copy is dropped, with a WARNING."""
- with caplog.at_level(logging.WARNING):
- await _assert_rated(tmp_path, _panel(profile=3800.0, **legacy), 3800.0)
-
- assert any(
- "9000.0" in record.getMessage() and "3800.0" in record.getMessage()
- for record in caplog.records
- if record.levelno == logging.WARNING
- )
-
-
def test_a_pv_section_rating_that_disagrees_with_the_profile_is_refused() -> None:
"""Only a hand edit fills the ``pv`` section's rating, so which value is meant is a
guess."""
@@ -257,8 +218,8 @@ async def test_a_dashboard_nameplate_edit_survives_a_reload(tmp_path: Path) -> N
store.update_entity(_SOLAR, {"nameplate_capacity_w": "3800"})
store.save_to_file(path)
- published, produced = await _rating(path)
- _, expected = await _rating(write_config(tmp_path / "control.yaml", _panel(profile=3800.0)))
+ published, produced = await pv_rating(path)
+ _, expected = await pv_rating(write_config(tmp_path / "control.yaml", _panel(profile=3800.0)))
assert published == "3800.0"
assert produced == expected
diff --git a/tests/test_readme_rehearsal.py b/tests/test_readme_rehearsal.py
index 657939f..313baaf 100644
--- a/tests/test_readme_rehearsal.py
+++ b/tests/test_readme_rehearsal.py
@@ -11,9 +11,7 @@
from __future__ import annotations
import copy
-from datetime import datetime
from typing import TYPE_CHECKING
-from zoneinfo import ZoneInfo
import pytest
@@ -21,7 +19,7 @@
from panelbench.emitter_adapter import runtime as emitter_runtime
from panelbench.emitter_adapter.instance_ids import stable_circuit_uuid
from panelbench.emitter_adapter.wire_capture import discovered_devices, recorded_panel
-from tests._helpers import default_config, published, write_config
+from tests._helpers import NOON, default_config, published, write_config
if TYPE_CHECKING:
from pathlib import Path
@@ -33,7 +31,6 @@
from panelbench.emitter_adapter.wire_capture import RecordingTransport
_ORIGINAL = "solar_inverter"
-_NOON = datetime(2026, 6, 15, 12, 0, tzinfo=ZoneInfo("America/Los_Angeles")).timestamp()
def _before() -> SimulationConfig:
@@ -141,5 +138,5 @@ async def test_the_second_config_is_the_same_panel_on_release_202639(
engine = runtime.engine
typical = engine.circuit_template(second)["energy_profile"]["typical_power"]
assert typical == -2280.0, "the inverter's typical power, not the load's, seeds its energy"
- produced = engine.modelled_circuit_power(second, _NOON)
+ produced = engine.modelled_circuit_power(second, NOON)
assert 0 < produced <= 3800.0
diff --git a/tests/test_released_dashboard_edits_survive.py b/tests/test_released_dashboard_edits_survive.py
index 8a189e6..55ee219 100644
--- a/tests/test_released_dashboard_edits_survive.py
+++ b/tests/test_released_dashboard_edits_survive.py
@@ -8,33 +8,28 @@
profile is the user's edit and the copy is stale: the profile wins, the copy is
dropped, and a WARNING names both values and the file.
-The fixtures are those two files exactly as 2.5.3 shipped them.
+The fixtures are those two files exactly as 2.5.3 shipped them, byte for byte:
+``git show 4ad9dd4:configs/
``, the commit the 2.5.3 version was built from.
"""
from __future__ import annotations
import logging
-from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING
-from zoneinfo import ZoneInfo
import pytest
import yaml
from aiohttp.test_utils import TestClient, TestServer
-from panelbench.clone import TYPE_PV
from panelbench.dashboard import DashboardContext, create_dashboard_app
from panelbench.dashboard.config_store import ConfigStore
-from panelbench.emitter_adapter import runtime as emitter_runtime
-from panelbench.emitter_adapter.wire_capture import discovered_devices, recorded_panel
-from tests._helpers import default_config, write_config
+from tests._helpers import default_config, pv_rating, write_config
if TYPE_CHECKING:
from panelbench.config_types import SimulationConfig
_RELEASED = Path(__file__).parent / "fixtures" / "released_2_5_3"
-_NOON = datetime(2026, 6, 15, 12, 0, tzinfo=ZoneInfo("America/Los_Angeles")).timestamp()
_PANELS = [
# file, solar template, its stale copy's value, the dashboard edit
@@ -89,18 +84,6 @@ def _without_the_stale_copy(config: SimulationConfig, template: str) -> dict[str
return control
-async def _rating(path: Path) -> tuple[str | None, float]:
- """The panel at *path*'s published ``info/nominal-power``, and what its solar
- circuit produces at noon."""
- runtime, recorder = await recorded_panel(path)
- await emitter_runtime.publish_tick(runtime)
- devices = discovered_devices(recorder.retained)
- [pv] = [d for d in devices.values() if (d.description or {}).get("type") == TYPE_PV]
- produced = runtime.engine.modelled_circuit_power("solar_inverter", _NOON)
- assert produced > 0, "noon in June, so the inverter is producing"
- return pv.get_property("info", "nominal-power"), produced
-
-
@pytest.mark.parametrize(("name", "template", "stale", "watts"), _PANELS)
@pytest.mark.asyncio
async def test_a_released_edit_loads_and_is_the_rating(
@@ -116,10 +99,10 @@ async def test_a_released_edit_loads_and_is_the_rating(
control = write_config(tmp_path / "control.yaml", _without_the_stale_copy(config, template))
with caplog.at_level(logging.WARNING):
- published, produced = await _rating(path)
+ published, produced = await pv_rating(path)
assert published == str(watts)
- assert produced == (await _rating(control))[1]
+ assert produced == (await pv_rating(control))[1]
warned = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
assert any(
str(path) in message
@@ -147,13 +130,13 @@ async def test_a_released_edit_survives_a_save_and_reload(
reloaded = ConfigStore()
reloaded.load_from_file(path)
assert reloaded.get_entity("solar_inverter").energy_profile["nameplate_capacity_w"] == watts
- published, produced = await _rating(path)
+ published, produced = await pv_rating(path)
assert published == str(watts)
control = write_config(
tmp_path / "control.yaml",
_without_the_stale_copy(_edited(name, template, watts), template),
)
- assert produced == (await _rating(control))[1]
+ assert produced == (await pv_rating(control))[1]
@pytest.mark.parametrize(("name", "template", "stale", "watts"), _PANELS)
@@ -195,3 +178,20 @@ async def test_a_template_clone_writes_the_stale_copy_out_once(
if r.levelno == logging.WARNING and "stale" in r.getMessage()
]
assert len(warned) == 1, warned
+
+
+@pytest.mark.parametrize(("name", "template", "stale", "watts"), _PANELS)
+@pytest.mark.asyncio
+async def test_a_released_template_clone_still_runs_unedited(
+ tmp_path: Path, name: str, template: str, stale: float, watts: float
+) -> None:
+ """Beside the R1 edit, the files pay for a broader guard: a 2.5.3 template clone,
+ with every key and shape of its era, still loads and starts a panel."""
+ path = tmp_path / "panel.yaml"
+ path.write_text((_RELEASED / name).read_text(encoding="utf-8"), encoding="utf-8")
+ ConfigStore().load_from_file(path)
+
+ published, produced = await pv_rating(path)
+
+ assert published == str(stale), "its stale copy agrees with its profile, so nothing drops"
+ assert produced > 0
From b76edd8a61a4df4e6d87db5880ccd22b87d79b6b Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:58:08 -0700
Subject: [PATCH 54/95] docs(engine): say modelled_circuit_power runs on the
engine's event loop
It restores the behaviour engine's tick-local state after reading, so from
another thread mid-tick it would undo that tick's cycle updates.
---
src/panelbench/engine.py | 3 +++
1 file changed, 3 insertions(+)
diff --git a/src/panelbench/engine.py b/src/panelbench/engine.py
index e1cbd42..29ceb9d 100644
--- a/src/panelbench/engine.py
+++ b/src/panelbench/engine.py
@@ -777,6 +777,9 @@ def modelled_circuit_power(self, circuit_id: str, ts: float) -> float:
producer scales with its rating. Read-only: the behaviour engine's
tick-local state, such as a cycling circuit's phase, is restored after.
+ Call it on the engine's event loop. It is not thread-safe: from another
+ thread mid-tick, the restore would undo that tick's cycle updates.
+
Raises:
KeyError: the panel has no circuit *circuit_id*.
RuntimeError: the engine has not been initialised.
From 40240fd916658e50f4a1f9ecb2efef231e64a852 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:59:18 -0700
Subject: [PATCH 55/95] fix(dashboard): open a config before starting or
restarting it, and still stop one that will not open
Start and Restart asked for the panel action, then opened the file in the
editor, answering 400 if it would not open. A refused start had still become the
config the next add-on boot tries, and a refused restart had already taken the
running panel down. Both now open the file first, and on refusal answer 400 with
the reason and leave the panel alone. Stop does not need the file, so it still
stops the panel, keeps the editor where it was, and shows that the file was not
opened and why.
---
src/panelbench/dashboard/routes.py | 29 +++++++---
...hboard_never_saves_an_unloadable_config.py | 57 +++++++++++++++++++
2 files changed, 78 insertions(+), 8 deletions(-)
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index 043075d..534083f 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -166,12 +166,19 @@ def _open_in_editor(request: web.Request, filename: str) -> None:
Answers 400 with the panel's reason when it would refuse the file, and the editor
keeps what it had.
"""
- ctx = _ctx(request)
+ reason = _try_open_in_editor(request, filename)
+ if reason is not None:
+ raise web.HTTPBadRequest(text=f"{filename} was not opened: {reason}")
+
+
+def _try_open_in_editor(request: web.Request, filename: str) -> str | None:
+ """``_open_in_editor``, answering why the panel would refuse the file instead."""
try:
- _store(request).load_from_file(ctx.config_dir / filename)
+ _store(request).load_from_file(_ctx(request).config_dir / filename)
except (ValueError, TypeError, yaml.YAMLError) as exc:
- raise web.HTTPBadRequest(text=f"{filename} was not opened: {exc}") from exc
- ctx.edit(filename)
+ return str(exc)
+ _ctx(request).edit(filename)
+ return None
def _first_default_config(config_dir: Path) -> str | None:
@@ -1981,9 +1988,10 @@ async def handle_start_panel(request: web.Request) -> web.Response:
if err is not None:
return err
ctx = _ctx(request)
- ctx.start_panel(filename)
- # Auto-switch the editor to this panel so entity list stays in sync.
+ # Opened first: the engine refuses what the editor refuses, and a requested start
+ # also becomes the config the next boot tries.
_open_in_editor(request, filename)
+ ctx.start_panel(filename)
return web.Response(status=200, headers={"HX-Redirect": "./"})
@@ -1993,8 +2001,12 @@ async def handle_stop_panel(request: web.Request) -> web.Response:
if err is not None:
return err
ctx = _ctx(request)
+ # Stopping does not need the file, so a panel whose file has gone bad still stops,
+ # and the page says the editor did not open it.
ctx.stop_panel(filename)
- _open_in_editor(request, filename)
+ reason = _try_open_in_editor(request, filename)
+ if reason is not None:
+ ctx.load_error = f"Stopped {filename}; it was not opened in the editor: {reason}"
return web.Response(status=200, headers={"HX-Redirect": "./"})
@@ -2004,8 +2016,9 @@ async def handle_restart_panel(request: web.Request) -> web.Response:
if err is not None:
return err
ctx = _ctx(request)
- ctx.restart_panel(filename)
+ # Opened first: a running panel is not taken down for a start the engine refuses.
_open_in_editor(request, filename)
+ ctx.restart_panel(filename)
return web.Response(status=200, headers={"HX-Redirect": "./"})
diff --git a/tests/test_dashboard_never_saves_an_unloadable_config.py b/tests/test_dashboard_never_saves_an_unloadable_config.py
index c3f53b2..1bbfcca 100644
--- a/tests/test_dashboard_never_saves_an_unloadable_config.py
+++ b/tests/test_dashboard_never_saves_an_unloadable_config.py
@@ -209,3 +209,60 @@ def _unloadable() -> SimulationConfig:
assert pv is not None
pv["feed"] = "no_such_circuit"
return config
+
+
+def _lifecycle_app(tmp_path: Path, calls: list[tuple[str, str]]) -> web.Application:
+ """The dashboard editing a good config, beside an unloadable `broken.yaml`, with
+ each panel action recorded in *calls*."""
+ write_config(tmp_path / "broken.yaml", _unloadable())
+ write_config(tmp_path / _FILE, default_config())
+ return create_dashboard_app(
+ DashboardContext(
+ config_dir=tmp_path,
+ config_filter=_FILE,
+ get_panel_configs=lambda: {},
+ get_panel_ports=lambda: {},
+ request_reload=lambda: None,
+ start_panel=lambda name: calls.append(("start", name)),
+ stop_panel=lambda name: calls.append(("stop", name)),
+ restart_panel=lambda name: calls.append(("restart", name)),
+ )
+ )
+
+
+@pytest.mark.parametrize("verb", ["start", "restart"])
+@pytest.mark.asyncio
+async def test_an_unloadable_config_is_not_started_or_restarted(tmp_path: Path, verb: str) -> None:
+ """Starting it would make it the config the next add-on boot tries; restarting it
+ would take a running panel down for a start the engine refuses."""
+ calls: list[tuple[str, str]] = []
+ app = _lifecycle_app(tmp_path, calls)
+
+ async with TestClient(TestServer(app)) as client:
+ answered = await client.post(f"/{verb}-panel", data={"filename": "broken.yaml"})
+ reason = await answered.text()
+
+ assert answered.status == 400
+ assert "names no circuit" in reason
+ assert calls == []
+ assert app[APP_KEY_DASHBOARD_CONTEXT].config_filter == _FILE
+
+
+@pytest.mark.asyncio
+async def test_an_unloadable_config_is_still_stopped(tmp_path: Path) -> None:
+ """Stopping does not need the file, so it happens, and the page says the file was
+ not opened."""
+ calls: list[tuple[str, str]] = []
+ app = _lifecycle_app(tmp_path, calls)
+
+ async with TestClient(TestServer(app)) as client:
+ answered = await client.post("/stop-panel", data={"filename": "broken.yaml"})
+ page = await (await client.get("/")).text()
+
+ context = app[APP_KEY_DASHBOARD_CONTEXT]
+ assert answered.status == 200
+ assert calls == [("stop", "broken.yaml")]
+ assert context.config_filter == _FILE, "the editor stays where it was"
+ assert context.load_error is not None
+ assert context.load_error.startswith("Stopped broken.yaml; it was not opened in the editor:")
+ assert "Stopped broken.yaml" in page
From 52879c81e532f5bea675dcd37ea758c6a4a6a7cb Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:08:57 -0700
Subject: [PATCH 56/95] fix(dashboard): gate every store write, and answer an
edit's own bad input with 422
- The edit gate now wraps a ValueError the change itself raises, such as an odd
total_tabs or a non-numeric field, as EditRefused, so it answers 422 with the
reason instead of 500, and the store is as it was.
- The battery schedule form changes the hours and the days as one edit, as the
profile and EV schedule forms already did.
- Two route paths wrote the store's private state around the gate: a re-scrape's
recorder snapshots and the panel-source energy sync. Both are now gated store
methods; the sync also marks a change unsaved, as any edit is.
- Tests: the "add circuit" case posts a circuit, the seven battery mutators are
covered, every public mutator is checked to carry the gate, and no module
outside the store may reach into a store's private state.
---
src/panelbench/dashboard/config_store.py | 38 +++++-
src/panelbench/dashboard/routes.py | 19 ++-
...st_dashboard_refuses_an_unloadable_edit.py | 110 +++++++++++++++++-
3 files changed, 150 insertions(+), 17 deletions(-)
diff --git a/src/panelbench/dashboard/config_store.py b/src/panelbench/dashboard/config_store.py
index 0945ab1..be052cb 100644
--- a/src/panelbench/dashboard/config_store.py
+++ b/src/panelbench/dashboard/config_store.py
@@ -25,6 +25,9 @@
from collections.abc import Callable, Iterator, Mapping
from pathlib import Path
+ from panelbench.scraper import ScrapedPanel
+
+from panelbench.clone import update_config_from_scrape
from panelbench.config_defaults import normalize_config
from panelbench.config_types import BESSConfigYAML
from panelbench.dashboard.defaults import make_defaults
@@ -219,8 +222,9 @@ def edit(self) -> Iterator[None]:
one wraps them in another, and an edit inside an edit is part of it.
Raises:
- EditRefused: the panel would not load the result; the state and the
- unsaved-changes flag are as they were.
+ EditRefused: the panel would not load the result, or the change itself
+ refused its input (an odd tab count, a field that is not a number);
+ the state and the unsaved-changes flag are as they were.
"""
if self._editing:
yield
@@ -229,10 +233,12 @@ def edit(self) -> Iterator[None]:
self._state = deepcopy(original)
self._editing = True
try:
- yield
- normalize_config(self._state, source=_EDITED)
try:
+ yield
+ normalize_config(self._state, source=_EDITED)
validate_yaml_config(self._state)
+ except EditRefused:
+ raise
except ValueError as exc:
raise EditRefused(str(exc)) from exc
except BaseException:
@@ -382,6 +388,30 @@ def get_recorder_map(self) -> dict[str, str]:
return dict(rm)
return {}
+ @_one_edit
+ def record_recorder_snapshots(
+ self, recorder_map: dict[str, str], snapshots: dict[str, object]
+ ) -> None:
+ """Keep a re-scrape's recorder mapping and template snapshots in ``panel_source``,
+ without touching the current templates."""
+ ps = self._state.setdefault("panel_source", {})
+ if isinstance(ps, dict):
+ if recorder_map:
+ ps["recorder_map"] = recorder_map
+ ps["recorder_snapshots"] = snapshots
+ self._dirty = True
+
+ @_one_edit
+ def update_from_scrape(self, scraped: ScrapedPanel) -> bool:
+ """Refresh the energy seeds from a scrape of the source panel.
+
+ Returns whether anything changed; a change is unsaved, as any edit is.
+ """
+ changed = update_config_from_scrape(self._state, scraped)
+ if changed:
+ self._dirty = True
+ return changed
+
@_one_edit
def restore_recorder(self, entity_id: str) -> bool:
"""Restore a template to its original recorder state.
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index 534083f..21013a8 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -1087,10 +1087,11 @@ async def handle_put_bess_schedule(request: web.Request) -> web.Response:
mode = str(data.get(key, "idle"))
hour_modes[h] = mode if mode in ("charge", "discharge", "idle") else "idle"
store = _store(request)
- store.update_battery_profile(hour_modes)
- active = _parse_active_days(data)
- if active is not None:
- store.update_bess_active_days(active)
+ with store.edit():
+ store.update_battery_profile(hour_modes)
+ active = _parse_active_days(data)
+ if active is not None:
+ store.update_bess_active_days(active)
_persist_config(request)
return _render("partials/bess_card.html", request, _bess_card_context(request, editing=True))
@@ -1549,12 +1550,7 @@ async def _rescrape_snapshots(request: web.Request) -> None:
snapshots[tpl_name] = copy.deepcopy(tpl)
# Persist map and snapshots without touching current templates
- ps = store._state.setdefault("panel_source", {})
- if isinstance(ps, dict):
- if recorder_map:
- ps["recorder_map"] = recorder_map
- ps["recorder_snapshots"] = snapshots
- store._dirty = True
+ store.record_recorder_snapshots(recorder_map, snapshots)
# -- Energy projection --
@@ -1903,7 +1899,6 @@ async def handle_get_panel_source(request: web.Request) -> web.Response:
async def handle_sync_panel_source(request: web.Request) -> web.Response:
"""Re-scrape the source panel and overwrite typical_power + energy seeds."""
- from panelbench.clone import update_config_from_scrape
from panelbench.scraper import ScrapeError, register_with_panel, scrape_ebus
store = _store(request)
@@ -1926,7 +1921,7 @@ async def handle_sync_panel_source(request: web.Request) -> web.Response:
content_type="text/html",
)
- update_config_from_scrape(store._state, scraped)
+ store.update_from_scrape(scraped)
ctx = _panel_source_context(request)
ctx["sync_message"] = "Updated energy seeds from source panel."
diff --git a/tests/test_dashboard_refuses_an_unloadable_edit.py b/tests/test_dashboard_refuses_an_unloadable_edit.py
index cda3eb5..276e166 100644
--- a/tests/test_dashboard_refuses_an_unloadable_edit.py
+++ b/tests/test_dashboard_refuses_an_unloadable_edit.py
@@ -12,6 +12,7 @@
from __future__ import annotations
+import re
from pathlib import Path
import pytest
@@ -20,10 +21,14 @@
from panelbench.dashboard import DashboardContext, create_dashboard_app
from panelbench.dashboard import config_store as config_store_module
+from panelbench.dashboard.config_store import ConfigStore
from panelbench.dashboard.keys import APP_KEY_STORE
from tests._helpers import default_config, write_config
_FILE = "panel.yaml"
+# What htmx sends with every request it makes, which is how the dashboard's forms
+# reach these routes.
+_HTMX = {"HX-Request": "true"}
@pytest.fixture
@@ -55,6 +60,7 @@ def refuse(_config: object) -> None:
[
("PUT", "/panel-config", {"serial_number": "renamed"}),
("PUT", "/sim-params", {"update_interval": "7"}),
+ ("POST", "/entities", {"entity_type": "circuit"}),
("POST", "/entities", {"entity_type": "evse"}),
("DELETE", "/entities/living_room_lights", {}),
("PUT", "/entities/pool_pump/profile", {"hour_0": "0.5"}),
@@ -66,17 +72,32 @@ def refuse(_config: object) -> None:
{"charge_start": "1", "charge_duration": "4"},
),
("POST", "/entities/span_drive_garage/evse-schedule/preset", {"preset": "night"}),
+ ("POST", "/bess", {}),
+ ("DELETE", "/bess", {}),
+ ("PUT", "/bess", {"nameplate_capacity_kwh": "20"}),
+ ("PUT", "/bess/schedule", {"hour_0": "charge"}),
+ ("POST", "/bess/schedule/preset", {"preset": "custom"}),
+ ("PUT", "/bess/charge-mode", {"charge_mode": "backup-only"}),
+ ("PUT", "/bess/active-days", {"days_submitted": "1", "day_0": "on"}),
],
ids=[
"panel config",
"sim params",
"add circuit",
+ "add EV charger",
"delete circuit",
"profile",
"preset",
"active days",
"EV schedule",
"EV preset",
+ "add battery",
+ "remove battery",
+ "battery settings",
+ "battery schedule",
+ "battery preset",
+ "battery charge mode",
+ "battery active days",
],
)
@pytest.mark.asyncio
@@ -92,7 +113,7 @@ async def test_every_kind_of_edit_is_refused_whole(
_refuse_everything(monkeypatch)
async with TestClient(TestServer(app)) as client:
- refused = await client.request(method, path, data=form)
+ refused = await client.request(method, path, data=form, headers=_HTMX)
reason = await refused.text()
assert refused.status == 422
@@ -145,3 +166,90 @@ async def test_a_new_circuit_takes_the_first_free_space(app: web.Application) ->
assert added.status == 200
assert free[0] not in store.get_unmapped_tabs()
+
+
+@pytest.mark.parametrize(
+ ("method", "path", "form", "reason"),
+ [
+ ("PUT", "/panel-config", {"total_tabs": "41"}, "even number"),
+ ("PUT", "/entities/pool_pump", {"typical_power": "lots"}, "could not convert"),
+ ],
+ ids=["odd tabs", "non-numeric field"],
+)
+@pytest.mark.asyncio
+async def test_an_edit_its_own_input_refuses_answers_422_with_the_reason(
+ app: web.Application, method: str, path: str, form: dict[str, str], reason: str
+) -> None:
+ store = app[APP_KEY_STORE]
+ before = store.export_yaml()
+
+ async with TestClient(TestServer(app)) as client:
+ refused = await client.request(method, path, data=form, headers=_HTMX)
+ text = await refused.text()
+
+ assert refused.status == 422
+ assert reason in text
+ assert store.export_yaml() == before
+
+
+def test_every_public_mutator_is_one_gated_edit() -> None:
+ """Structural, so a mutator added later cannot skip the gate: every public method
+ that is not a reader carries the gate's wrapper."""
+ readers = ("get_", "list_", "has_", "load_from_", "compute_")
+ exempt = {"edit", "export_yaml", "save_to_file", "dirty"}
+ public = {
+ name: member
+ for name, member in vars(ConfigStore).items()
+ if not name.startswith("_") and callable(member) and name not in exempt
+ }
+ ungated = sorted(
+ name
+ for name, member in public.items()
+ if not name.startswith(readers) and not hasattr(member, "__wrapped__")
+ )
+
+ assert ungated == []
+ assert len(public) > 20, "the scan found the store's methods"
+
+
+@pytest.mark.asyncio
+async def test_a_battery_schedule_and_its_days_are_one_edit(
+ app: web.Application, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The schedule form saves the hours and the days together, so a refusal of the
+ days leaves the hours as they were too."""
+ store = app[APP_KEY_STORE]
+ before = store.export_yaml()
+ real = config_store_module.validate_yaml_config
+
+ def refuse_the_days(config: dict[str, object]) -> None:
+ bess = config.get("bess")
+ if isinstance(bess, dict) and bess.get("active_days") == [0]:
+ raise ValueError("refused for the test")
+ real(config)
+
+ monkeypatch.setattr(config_store_module, "validate_yaml_config", refuse_the_days)
+ async with TestClient(TestServer(app)) as client:
+ refused = await client.put(
+ "/bess/schedule",
+ data={"hour_0": "charge", "days_submitted": "1", "day_0": "on"},
+ headers=_HTMX,
+ )
+
+ assert refused.status == 422
+ assert store.export_yaml() == before
+
+
+def test_nothing_outside_the_store_writes_its_state() -> None:
+ """The gate holds only if every write goes through the store's own methods, so no
+ other module reaches into a store's private state."""
+ package = Path(config_store_module.__file__).resolve().parents[1]
+ reaches = [
+ f"{path.relative_to(package)}:{number}"
+ for path in sorted(package.rglob("*.py"))
+ if path.name != "config_store.py"
+ for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1)
+ if re.search(r"\bstore\._\w", line)
+ ]
+
+ assert reaches == []
From 180684e1b51954376d71f8e79e2af0c39fe70a5b Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:10:48 -0700
Subject: [PATCH 57/95] fix(dashboard): show a refused rate choice in its
dialog, and keep the current rate
PUT rates/current set the simulator-wide current rate before the battery's
edit, and the rate dialog closed whatever the answer. A refused edit therefore
left the dialog looking successful, the current rate changed, and a notice for
some later page.
The battery's edit now comes first, and the current rate changes only after it.
The refusal middleware reloads the page and leaves a notice only for an htmx
request; a script's request gets the reason in its 422, and the rate dialog
checks the status and shows it, staying open.
---
src/panelbench/dashboard/routes.py | 17 +++--
.../templates/partials/modeling_view.html | 10 ++-
...st_dashboard_refuses_an_unloadable_edit.py | 63 ++++++++++++++++++-
3 files changed, 81 insertions(+), 9 deletions(-)
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index 21013a8..b86a8c1 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -149,15 +149,18 @@ async def refuse_unloadable_edits(
"""Answer an edit the panel would not load, from any handler, in one way.
The store has already refused it and is as it was, so the answer is 422 with the
- reason and a page reload: the page then shows what the store holds, and the
- reason, rather than an edit the store does not.
+ reason. An htmx request also reloads the page, which then shows what the store
+ holds and the reason, rather than an edit the store does not. A script's request
+ gets the reason in the response, for it to show where it asked.
"""
try:
return await handler(request)
except EditRefused as exc:
- ctx = _ctx(request)
- ctx.notice = f"Not changed: {exc}"
- return web.Response(status=422, text=ctx.notice, headers={"HX-Refresh": "true"})
+ reason = f"Not changed: {exc}"
+ if request.headers.get("HX-Request") != "true":
+ return web.Response(status=422, text=reason)
+ _ctx(request).notice = reason
+ return web.Response(status=422, text=reason, headers={"HX-Refresh": "true"})
def _open_in_editor(request: web.Request, filename: str) -> None:
@@ -549,12 +552,14 @@ async def handle_put_current_rate(request: web.Request) -> web.Response:
label = body.get("label", "").strip()
if not label:
return web.json_response({"error": "label is required"}, status=400)
- _rate_cache(request).set_current_rate_label(label)
+ # The battery's edit first: if the panel would refuse it, the current rate stays
+ # as it was too.
store = _store(request)
if store.get_battery_charge_mode() == "custom":
store.update_battery_charge_mode("custom", rate_label=label)
_persist_config(request)
+ _rate_cache(request).set_current_rate_label(label)
return web.json_response({"ok": True})
diff --git a/src/panelbench/dashboard/templates/partials/modeling_view.html b/src/panelbench/dashboard/templates/partials/modeling_view.html
index 5ee3935..d6afbb6 100644
--- a/src/panelbench/dashboard/templates/partials/modeling_view.html
+++ b/src/panelbench/dashboard/templates/partials/modeling_view.html
@@ -913,7 +913,15 @@ Rate Data Source
method: 'PUT',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({label: label}),
- }).then(function() {
+ }).then(function(r) {
+ if (!r.ok) {
+ // Refused: the dialog stays open and says why; nothing changed.
+ return r.text().then(function(reason) {
+ dialogError.textContent = reason || ('Request failed (' + r.status + ')');
+ dialogError.style.display = '';
+ useRateBtn.disabled = false;
+ });
+ }
loadCurrentRate();
closeRateDialog();
fetchModelingData(horizonSelect.value);
diff --git a/tests/test_dashboard_refuses_an_unloadable_edit.py b/tests/test_dashboard_refuses_an_unloadable_edit.py
index 276e166..fb16cd8 100644
--- a/tests/test_dashboard_refuses_an_unloadable_edit.py
+++ b/tests/test_dashboard_refuses_an_unloadable_edit.py
@@ -22,7 +22,11 @@
from panelbench.dashboard import DashboardContext, create_dashboard_app
from panelbench.dashboard import config_store as config_store_module
from panelbench.dashboard.config_store import ConfigStore
-from panelbench.dashboard.keys import APP_KEY_STORE
+from panelbench.dashboard.keys import (
+ APP_KEY_DASHBOARD_CONTEXT,
+ APP_KEY_RATE_CACHE,
+ APP_KEY_STORE,
+)
from tests._helpers import default_config, write_config
_FILE = "panel.yaml"
@@ -130,7 +134,7 @@ async def test_an_earlier_unsaved_edit_survives_a_later_refused_one(
"""Tabs 1 and 4 are not a double-pole pair, so the panel refuses that edit alone."""
async with TestClient(TestServer(app)) as client:
renamed = await client.put("/panel-config", data={"serial_number": "sim-renamed"})
- refused = await client.put("/entities/bedroom_lights", data={"tabs": "1,4"})
+ refused = await client.put("/entities/bedroom_lights", data={"tabs": "1,4"}, headers=_HTMX)
reason = await refused.text()
dirty = await (await client.get("/check-dirty")).json()
page = await (await client.get("/")).text()
@@ -253,3 +257,58 @@ def test_nothing_outside_the_store_writes_its_state() -> None:
]
assert reaches == []
+
+
+def _custom_battery_app(tmp_path: Path) -> web.Application:
+ """The dashboard, editing a panel whose battery follows a utility rate."""
+ config = default_config()
+ bess = config.get("bess")
+ assert bess is not None
+ bess["charge_mode"] = "custom"
+ write_config(tmp_path / _FILE, config)
+ return create_dashboard_app(
+ DashboardContext(
+ config_dir=tmp_path,
+ config_filter=_FILE,
+ get_panel_configs=lambda: {},
+ get_panel_ports=lambda: {},
+ request_reload=lambda: None,
+ )
+ )
+
+
+@pytest.mark.asyncio
+async def test_a_refused_rate_choice_keeps_the_current_rate(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The rate dialog calls this with fetch, not htmx, so the refusal comes back in
+ the response for the dialog to show, and nothing else changes: not the battery's
+ rate, not the simulator-wide current rate, and no notice left for a later page."""
+ app = _custom_battery_app(tmp_path)
+ store = app[APP_KEY_STORE]
+ rates = app[APP_KEY_RATE_CACHE]
+ before = store.export_yaml()
+ _refuse_everything(monkeypatch)
+
+ async with TestClient(TestServer(app)) as client:
+ refused = await client.put("rates/current", json={"label": "rate-b"})
+ reason = await refused.text()
+
+ assert refused.status == 422
+ assert "refused for the test" in reason
+ assert "HX-Refresh" not in refused.headers
+ assert store.export_yaml() == before
+ assert rates.get_current_rate_label() is None
+ assert app[APP_KEY_DASHBOARD_CONTEXT].notice is None
+
+
+@pytest.mark.asyncio
+async def test_a_rate_choice_reaches_the_battery_and_the_current_rate(tmp_path: Path) -> None:
+ app = _custom_battery_app(tmp_path)
+
+ async with TestClient(TestServer(app)) as client:
+ chosen = await client.put("rates/current", json={"label": "rate-b"})
+
+ assert chosen.status == 200
+ assert app[APP_KEY_RATE_CACHE].get_current_rate_label() == "rate-b"
+ assert app[APP_KEY_STORE].get_bess_config().get("rate_label") == "rate-b"
From bd57f93a8d04e1d2c72f595f646d857b819433e4 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:10:59 -0700
Subject: [PATCH 58/95] test(dashboard): pin that Start and Restart request a
good config and open it
The refusal cases pinned that an unloadable config is never started or
restarted. These pin the other half: a config that opens is requested and the
editor moves to it.
---
...ashboard_never_saves_an_unloadable_config.py | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/tests/test_dashboard_never_saves_an_unloadable_config.py b/tests/test_dashboard_never_saves_an_unloadable_config.py
index 1bbfcca..369e9b7 100644
--- a/tests/test_dashboard_never_saves_an_unloadable_config.py
+++ b/tests/test_dashboard_never_saves_an_unloadable_config.py
@@ -266,3 +266,20 @@ async def test_an_unloadable_config_is_still_stopped(tmp_path: Path) -> None:
assert context.load_error is not None
assert context.load_error.startswith("Stopped broken.yaml; it was not opened in the editor:")
assert "Stopped broken.yaml" in page
+
+
+@pytest.mark.parametrize("verb", ["start", "restart"])
+@pytest.mark.asyncio
+async def test_a_loadable_config_is_started_or_restarted_and_opened(
+ tmp_path: Path, verb: str
+) -> None:
+ calls: list[tuple[str, str]] = []
+ app = _lifecycle_app(tmp_path, calls)
+ write_config(tmp_path / "good.yaml", default_config())
+
+ async with TestClient(TestServer(app)) as client:
+ answered = await client.post(f"/{verb}-panel", data={"filename": "good.yaml"})
+
+ assert answered.status == 200
+ assert calls == [(verb, "good.yaml")]
+ assert app[APP_KEY_DASHBOARD_CONTEXT].config_filter == "good.yaml", "the editor moves"
From 4180d2f5bbcb0ece979bdc43499d8c2907a144da Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:11:13 -0700
Subject: [PATCH 59/95] docs(changelog): note the new circuit's placement, and
say the sim/v0.1.0 change once
The Changed bullet on configs that name no SPAN release repeated the section's
opening paragraph; its advice for a panel clone moves into the paragraph. Add
Entity placing a new circuit on the first free space gets its Fixed sentence.
---
CHANGELOG.md | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89f2bfc..1651fd7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,7 @@
**The shipped templates stay on SPAN release 202633's conventions, and a config or clone that names no SPAN release now publishes release 202639's.** The add-on
refreshes its shipped templates on every start, so an upgraded install publishes what this release ships. A config or clone whose `firmware_version` names no
SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 40 template, which named `sim/v0.1.0`. To keep the earlier conventions, set its
-`firmware_version` to a 202633 release such as `spanos3/r202633/02`.
+`firmware_version` to a 202633 release such as `spanos3/r202633/02`, or, for a clone of a panel, to the source panel's firmware.
### Added
@@ -28,8 +28,6 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
- **The shipped configs now report firmware `spanos3/r202633/02`**, which Home Assistant's device info shows, so they keep SPAN release 202633's conventions and
integrations released before r202639 support read them correctly; set a clone's `firmware_version` to a 202639 release to emulate the new firmware.
- **A panel without a battery no longer publishes load-shed state**, as the eBus specification requires.
-- **An existing config or clone whose `firmware_version` names no SPAN release, such as `sim/v0.1.0`, publishes the conventions of SPAN release 202639**; set
- `firmware_version` to the source panel's firmware, or clone the panel again, to keep its earlier release's conventions.
- **A config with two or more solar circuits now publishes each inverter as its own solar device, under new device ids**, unless its `firmware_version` names a
SPAN release before 202639, as SPAN firmware does from that release, and a clone keeps every inverter.
- **The top-level `pv` section now describes the inverter whose circuit `pv.feed` names by its `id`, or the only solar circuit's, where it followed whichever
@@ -63,6 +61,7 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
- **The dashboard now fetches a read-only template's weather**, where a script error on its missing location search stopped it.
- **The dashboard refuses an edit the panel would not load, says why and keeps the config as it was, and starts when the active config is one the panel
refuses**, where such an edit was saved and the panel then failed to restart, and an add-on restart with it active left no dashboard to fix it from.
+- **The dashboard's Add Entity places a new circuit on the first free space**, where it made a circuit with no space, which the panel refused.
- **The dashboard's relay control shows a locked relay however its config spells it**, where a circuit written `non-controllable`, as the shipped configs
write it, showed `controllable` and saving its form unlocked it.
- **A solar inverter's nameplate edited in the dashboard now survives a restart and is the rating the panel both publishes and produces at**, including in a
From 47288687ac33bfc22cc484c61ebf4b5603d45f76 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:12:17 -0700
Subject: [PATCH 60/95] docs(addon): bring the add-on store changelog up to
date through 2.6.0
The add-on store shows panelbench/CHANGELOG.md to users when a version is
published, and it stopped at 2.2.0. It now covers 2.3.0 to 2.6.0, one
user-facing sentence per entry, consistent with the repository CHANGELOG and
without its developer-facing detail. The 2.6.0 date assumes it is published
today.
---
panelbench/CHANGELOG.md | 103 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 103 insertions(+)
diff --git a/panelbench/CHANGELOG.md b/panelbench/CHANGELOG.md
index 710aa89..bb555cc 100644
--- a/panelbench/CHANGELOG.md
+++ b/panelbench/CHANGELOG.md
@@ -1,5 +1,108 @@
# Changelog
+## 2.6.0 — 2026-10-06
+
+SPAN firmware release 202639 arrives for any config that names it, while the shipped templates stay on release 202633's conventions. A config or clone that
+names no SPAN release, including a clone of the earlier MAIN 40 template, now publishes release 202639's; to keep the earlier conventions, set its
+`firmware_version` to a 202633 release such as `spanos3/r202633/02`, or, for a clone of a panel, to the source panel's firmware.
+
+### Added
+
+- **The dashboard can set the health of the panel's link to its battery**, which a SPAN panel requires before it honours Home Assistant's dominant power source
+ control.
+- **Commissioned PV and battery system circuits are modelled and kept by a clone**, locked as release 202639 locks them, and a config naming an earlier release
+ is refused if it asks for one.
+- **From release 202639, a panel's status endpoint reports its hardware version**: `1.2` or `2.0` from the config's `hardware_version`, and `UNKNOWN` otherwise.
+- **The dashboard's Import accepts a panel definition file**, such as one `panel-sim-capture` wrote from a live panel, and turns it into a PanelBench config.
+- **The dashboard can export a saved config as a panel definition file**, the makeup other eBus tools read.
+
+### Changed
+
+- **Home Assistant's dominant power source control is ignored while the panel's link to its battery is healthy**, as a SPAN panel ignores it.
+- **From release 202639, the battery's own power reading is positive while discharging**, as SPAN firmware publishes it.
+- **From release 202639, a SPAN Drive's user charge limit is not published until a user sets one**, as on SPAN firmware.
+- **The shipped configs report firmware `spanos3/r202633/02`**, which Home Assistant's device info shows, and the shipped MAIN 32 reports hardware version
+ `1.2`.
+- **A panel without a battery no longer publishes load-shed state**, as the eBus specification requires.
+- **From release 202639, a config with two or more solar circuits publishes each inverter as its own solar device**, under new device ids, and a clone keeps
+ every inverter.
+- **Every solar device is named after its own device id**, as SPAN firmware names an inverter, where it was named "Solar", "Solar 2" and so on in circuit order.
+- **The `pv` section describes the inverter whose circuit `pv.feed` names by its `id`, or the only solar circuit's**, where it followed whichever was listed
+ first, and a config whose `pv.feed` names no solar circuit, or with several solar circuits and no `pv.feed` before release 202639, is refused.
+- **A solar rating set in the dashboard replaces the stale copy a clone of the shipped MAIN 40 or MAIN 32 template kept**, and the log warns about it until the
+ config is saved in the dashboard.
+- **A `pv.nameplate_capacity_w`, or a circuit override on a shared template, that disagrees with the template's rating is refused**, naming both values.
+- **A new clone of a panel whose battery publishes a serial number identifies that battery by its serial**, which gives the battery and its MID new device ids
+ when such a panel is cloned again.
+
+### Fixed
+
+- **An upgraded add-on refreshes its shipped `default_*` templates on every start**, where it kept the copies an earlier release laid down.
+- **The panel's HTTP status, Homie schema endpoint and mDNS advertisement report the same firmware version it publishes over MQTT.**
+- **A cloned panel keeps the source panel's name, firmware version and hardware version.**
+- **A cloned panel keeps each solar inverter's identity, its battery's model, and each SPAN Drive's serial number and firmware version.**
+- **The dashboard refuses an edit the panel would not load, says why and keeps the config as it was**, where such an edit was saved and the panel then failed to
+ restart.
+- **The dashboard starts when the active config is one the panel refuses**, showing why, where the add-on had no dashboard to fix it from.
+- **A solar nameplate edited in the dashboard survives a restart and is the rating the panel both publishes and produces at.**
+- **The dashboard's relay control shows a locked relay however its config spells it**, where saving the form could unlock it.
+- **The dashboard's Add Entity places a new circuit on the first free space**, where it made a circuit with no space, which the panel refused.
+- **The dashboard shows a panel as islandable when any of its solar inverters is hybrid**, where only the first solar circuit listed decided it.
+- **An imported config counts as unsaved until it is saved**, so switching panels asks before discarding it.
+- **The dashboard fetches a read-only template's weather**, where a script error stopped it.
+
+## 2.5.3 — 2026-08-28
+
+**A simulated panel already added to Home Assistant has to be removed and re-added**, because its circuits get new device ids.
+
+### Fixed
+
+- **Two simulated panels running in one add-on no longer overwrite each other's circuit readings.**
+
+## 2.5.2 — 2026-08-28
+
+### Fixed
+
+- **Discovery gives Home Assistant the panel's address rather than an internal add-on hostname**, so a panel added by IP keeps verifying its certificate.
+
+## 2.5.1 — 2026-08-28
+
+### Fixed
+
+- **The certificate and the mDNS advertisement carry this host's own address**, so Home Assistant can reach the panel and verify it, and an existing install
+ corrects itself on the next start.
+- **Discovery entries are removed when the add-on stops**, where stale ones accumulated across restarts.
+- **The add-on image builds again.**
+
+## 2.5.0 — 2026-08-28
+
+**The certificate authority now ships with the app and matches the SPAN Panel Simulator's**, so swapping the simulator for PanelBench on one panel rehearses a
+firmware upgrade rather than a panel replacement; upgrade the simulator to 1.1.0 first, and the swap raises no certificate repair in Home Assistant.
+
+### Fixed
+
+- **A changed address or hostname re-signs only the server certificate**, where it rotated the certificate authority too.
+- **An expired, corrupt or superseded server certificate is replaced at startup**, where it failed handshakes or put the add-on into a restart loop.
+- **Certificate files are written atomically, and the authority's private key is no longer written to the certificate directory.**
+
+## 2.4.0 — 2026-08-26
+
+### Changed
+
+- **Locked circuits no longer offer a relay command**, as a real panel publishes them, and the dashboard refuses a relay toggle on one.
+- **The dashboard refuses a shed-priority change on a never-backup circuit**, which would have saved a config the panel could not start from.
+
+### Added
+
+- **Cloning a panel reproduces its never-backup circuits.**
+
+## 2.3.0 — 2026-08-26
+
+### Added
+
+- **Every panel serves its API over TLS as well as plaintext**, on a port 1000 above its bootstrap port, which Home Assistant's setup needs.
+- **Discovery publishes both ports, and the dashboard shows the pair beside each running panel** for adding one to Home Assistant by hand.
+
## 2.2.0 — 2026-08-23
### Fixed
From 7896c45c5a3be1e4480e71a1bae18668724d245a Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:16:47 -0700
Subject: [PATCH 61/95] fix(dashboard): say a panel-source sync needs saving,
and finish the release notes
- The panel-source sync's message now says to save, since the refreshed energy
seeds are an unsaved edit, and says so when nothing changed.
- The test that no module writes a store's private state now matches ._state
and ._dirty anywhere outside config_store.py, whatever the store is called.
- The add-on store changelog's 2.6.0 entry says the other shipped templates
keep hardware rev2 and so report UNKNOWN from release 202639.
---
panelbench/CHANGELOG.md | 1 +
src/panelbench/dashboard/routes.py | 8 +++-
...st_dashboard_refuses_an_unloadable_edit.py | 40 ++++++++++++++++++-
3 files changed, 45 insertions(+), 4 deletions(-)
diff --git a/panelbench/CHANGELOG.md b/panelbench/CHANGELOG.md
index bb555cc..412bb0e 100644
--- a/panelbench/CHANGELOG.md
+++ b/panelbench/CHANGELOG.md
@@ -23,6 +23,7 @@ names no SPAN release, including a clone of the earlier MAIN 40 template, now pu
- **From release 202639, a SPAN Drive's user charge limit is not published until a user sets one**, as on SPAN firmware.
- **The shipped configs report firmware `spanos3/r202633/02`**, which Home Assistant's device info shows, and the shipped MAIN 32 reports hardware version
`1.2`.
+- **The other shipped templates keep hardware version `rev2`**, so from release 202639 their status endpoint reports `UNKNOWN`.
- **A panel without a battery no longer publishes load-shed state**, as the eBus specification requires.
- **From release 202639, a config with two or more solar circuits publishes each inverter as its own solar device**, under new device ids, and a clone keeps
every inverter.
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index b86a8c1..6aae4db 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -1926,10 +1926,14 @@ async def handle_sync_panel_source(request: web.Request) -> web.Response:
content_type="text/html",
)
- store.update_from_scrape(scraped)
+ changed = store.update_from_scrape(scraped)
ctx = _panel_source_context(request)
- ctx["sync_message"] = "Updated energy seeds from source panel."
+ ctx["sync_message"] = (
+ "Updated energy seeds from source panel. Save to keep it."
+ if changed
+ else "The energy seeds already match the source panel."
+ )
return _render("partials/panel_source.html", request, ctx)
diff --git a/tests/test_dashboard_refuses_an_unloadable_edit.py b/tests/test_dashboard_refuses_an_unloadable_edit.py
index fb16cd8..3830de1 100644
--- a/tests/test_dashboard_refuses_an_unloadable_edit.py
+++ b/tests/test_dashboard_refuses_an_unloadable_edit.py
@@ -19,6 +19,7 @@
from aiohttp import web
from aiohttp.test_utils import TestClient, TestServer
+from panelbench import scraper
from panelbench.dashboard import DashboardContext, create_dashboard_app
from panelbench.dashboard import config_store as config_store_module
from panelbench.dashboard.config_store import ConfigStore
@@ -246,14 +247,14 @@ def refuse_the_days(config: dict[str, object]) -> None:
def test_nothing_outside_the_store_writes_its_state() -> None:
"""The gate holds only if every write goes through the store's own methods, so no
- other module reaches into a store's private state."""
+ other module reaches into a store's private state, whatever it calls the store."""
package = Path(config_store_module.__file__).resolve().parents[1]
reaches = [
f"{path.relative_to(package)}:{number}"
for path in sorted(package.rglob("*.py"))
if path.name != "config_store.py"
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1)
- if re.search(r"\bstore\._\w", line)
+ if re.search(r"\._(state|dirty)\b", line)
]
assert reaches == []
@@ -312,3 +313,38 @@ async def test_a_rate_choice_reaches_the_battery_and_the_current_rate(tmp_path:
assert chosen.status == 200
assert app[APP_KEY_RATE_CACHE].get_current_rate_label() == "rate-b"
assert app[APP_KEY_STORE].get_bess_config().get("rate_label") == "rate-b"
+
+
+@pytest.mark.asyncio
+async def test_a_panel_source_sync_says_the_change_is_unsaved(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The sync refreshes the energy seeds as an unsaved edit, so it says to save."""
+ config = default_config()
+ config["panel_source"] = {"origin_serial": "nt-0000-tg1", "host": "192.168.1.100"}
+ write_config(tmp_path / _FILE, config)
+ app = create_dashboard_app(
+ DashboardContext(
+ config_dir=tmp_path,
+ config_filter=_FILE,
+ get_panel_configs=lambda: {},
+ get_panel_ports=lambda: {},
+ request_reload=lambda: None,
+ )
+ )
+
+ async def registered(_host: str, _passphrase: str | None) -> tuple[object, str]:
+ return object(), ""
+
+ async def scraped(_creds: object, _ca_pem: str) -> object:
+ return object()
+
+ monkeypatch.setattr(scraper, "register_with_panel", registered)
+ monkeypatch.setattr(scraper, "scrape_ebus", scraped)
+ monkeypatch.setattr(app[APP_KEY_STORE], "update_from_scrape", lambda _scraped: True)
+ async with TestClient(TestServer(app)) as client:
+ synced = await client.post("/sync-panel-source", headers=_HTMX)
+ html = await synced.text()
+
+ assert synced.status == 200
+ assert "Save to keep it" in html
From e772a0d71db3d02291299aa488d88df389e8eb51 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 20:24:08 -0700
Subject: [PATCH 62/95] feat(validation): warn about a solar circuit on one tab
A grid-tied inverter in a US panel is 240 V on a two-pole breaker, two tabs on
opposite legs, as every shipped template's PV circuit is. A PV or commissioned
PV circuit on a single tab is almost always a load circuit turned into an
inverter without its second pole, so validation now logs a WARNING naming the
circuit and its tab. It does not refuse it: a 120 V PV circuit is unusual rather
than impossible, and existing configs keep loading. A PV circuit with no tabs, a
what-if one, is not warned about.
---
src/panelbench/validation.py | 14 +++++++
tests/test_single_pole_pv_warns.py | 60 ++++++++++++++++++++++++++++++
2 files changed, 74 insertions(+)
create mode 100644 tests/test_single_pole_pv_warns.py
diff --git a/src/panelbench/validation.py b/src/panelbench/validation.py
index eacbf98..dfb61dd 100644
--- a/src/panelbench/validation.py
+++ b/src/panelbench/validation.py
@@ -6,6 +6,7 @@
from __future__ import annotations
+import logging
from typing import TYPE_CHECKING, Any
from panelbench.emitter_adapter.spec_generator import relay_locked
@@ -16,6 +17,8 @@
if TYPE_CHECKING:
from collections.abc import Mapping
+_LOGGER = logging.getLogger(__name__)
+
def validate_yaml_config(config_data: Any) -> None:
"""Validate YAML configuration structure and required fields."""
@@ -174,6 +177,17 @@ def validate_single_circuit(index: int, circuit: Any, circuit_templates: dict[st
if len(tabs) == 2:
validate_double_pole_tabs(index, circuit.get("name", f"circuit {index}"), tabs)
+ if len(tabs) == 1 and (
+ template.get("device_type") == "pv" or template.get("commissioned_system") == "pv"
+ ):
+ # Warned, not refused: a 120 V PV circuit is unusual rather than impossible,
+ # and a config that loaded before must keep loading.
+ _LOGGER.warning(
+ "Circuit %r feeds a solar inverter from one tab (%s); a grid-tied inverter in "
+ "a US panel is 240 V on a two-pole breaker, two tabs on opposite legs",
+ circuit["id"],
+ tabs[0],
+ )
def validate_pv_section(config_data: Mapping[str, object]) -> None:
diff --git a/tests/test_single_pole_pv_warns.py b/tests/test_single_pole_pv_warns.py
new file mode 100644
index 0000000..d34b03b
--- /dev/null
+++ b/tests/test_single_pole_pv_warns.py
@@ -0,0 +1,60 @@
+"""A PV circuit on one tab is warned about, never refused.
+
+A grid-tied inverter in a US panel is 240 V on a two-pole breaker: two tabs on
+opposite legs, as every shipped template's PV circuit is. One on a single tab is
+almost always a modelling slip, such as a load circuit turned into an inverter
+without its second pole, but a 120 V PV circuit is unusual rather than impossible,
+and existing configs must keep loading. So validation names the circuit in a
+WARNING and carries on.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+
+from panelbench.config_types import SimulationConfig
+from panelbench.validation import validate_yaml_config
+from tests._helpers import default_config
+
+
+def _with_solar_tabs(tabs: list[int], *, commissioned: bool = False) -> SimulationConfig:
+ """The default panel, its solar circuit on *tabs*."""
+ config = default_config()
+ [solar] = [c for c in config["circuits"] if c["id"] == "solar_inverter"]
+ solar["tabs"] = tabs
+ if commissioned:
+ config["firmware_version"] = "spanos3/r202639/03"
+ template = config["circuit_templates"][solar["template"]]
+ template["commissioned_system"] = "pv"
+ template["relay_behavior"] = "non-controllable"
+ template["priority"] = "NEVER"
+ return config
+
+
+def _warnings(caplog: pytest.LogCaptureFixture) -> list[str]:
+ return [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
+
+
+@pytest.mark.parametrize("commissioned", [False, True], ids=["pv", "commissioned pv"])
+def test_a_pv_circuit_on_one_tab_loads_with_a_warning(
+ caplog: pytest.LogCaptureFixture, *, commissioned: bool
+) -> None:
+ with caplog.at_level(logging.WARNING):
+ validate_yaml_config(_with_solar_tabs([36], commissioned=commissioned))
+
+ assert any(
+ "'solar_inverter'" in message and "two-pole" in message for message in _warnings(caplog)
+ ), _warnings(caplog)
+
+
+@pytest.mark.parametrize("tabs", [[36, 38], []], ids=["two-pole", "virtual"])
+def test_a_two_pole_or_virtual_pv_circuit_is_not_warned_about(
+ caplog: pytest.LogCaptureFixture, tabs: list[int]
+) -> None:
+ """A PV circuit with no tabs is a what-if one, which occupies no breaker."""
+ with caplog.at_level(logging.WARNING):
+ validate_yaml_config(_with_solar_tabs(tabs))
+
+ assert not any("solar_inverter" in message for message in _warnings(caplog))
From 6aa16823115dca495b72d5cc2013856811dd482d Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 20:25:36 -0700
Subject: [PATCH 63/95] docs(readme): put the rehearsal's second inverter on a
two-pole circuit
A grid-tied inverter in a US panel, a string inverter or a set of
microinverters, is 240 V on a two-pole breaker, two tabs on opposite legs, as
the Commissioned PV System circuit is. The second-inverter step turned a
single-pole load into one. It now says the second inverter's circuit is two-pole:
a clone of the panel already holds it as a two-pole load to pick, and a clone of
a template adds one to both configs on two free spaces on opposite legs, with
the same id and tabs and a two-pole breaker rating. The circuit is named as the
inverter's, such as Solar Inverter 2.
The README procedure test follows the new step for an added circuit and for a
two-pole load with an override. It checks the second inverter's circuit is on
the same two spaces in both configs, named as an inverter's, and draws no
single-pole warning. The old single-pole shape fails it.
---
README.md | 9 ++++-
tests/test_readme_rehearsal.py | 64 +++++++++++++++++++++++++++-------
2 files changed, 60 insertions(+), 13 deletions(-)
diff --git a/README.md b/README.md
index cca96c5..af74e5d 100644
--- a/README.md
+++ b/README.md
@@ -146,8 +146,15 @@ panel with one keeps its device id.
### A second inverter
Before release 202639 a panel publishes one solar device, so a clone holds one PV circuit and models any other inverter's circuit as a load. To rehearse the
-upgrade of a panel with a second inverter, also make that circuit an inverter's in the second config:
+upgrade of a panel with a second inverter, also make that circuit an inverter's in the second config.
+The second inverter's circuit is a 240 V two-pole circuit, two tabs on opposite legs, as the "Commissioned PV System" circuit is: a grid-tied inverter in a US
+panel, whether a string inverter or a set of microinverters, sits on a two-pole breaker. A clone of your panel already holds it, as a two-pole circuit modelled
+as a load, so pick that circuit. A clone of a template has no second inverter, so add its circuit to both configs on two free spaces on opposite legs, such as
+`24` and `26`, with the same `id` and `tabs` in both, a two-pole `breaker_rating` such as `20`, and a load's template in the first config; take the two spaces
+out of `unmapped_tabs`. PanelBench warns when a solar circuit sits on one tab. Then, in the second config:
+
+- Name the circuit as its inverter's, for example `Solar Inverter 2`, rather than leaving a load's name.
- Give it a PV template: copy the "Commissioned PV System" circuit's template as the first config has it, unlocked, under a new name. Set the copy's
`energy_profile.nameplate_capacity_w` to the inverter's rating, its producer `power_range` to match, such as `[-7600.0, 0.0]`, and its `typical_power` to
about 60% of the rating, negative, such as `-4560.0`, and point the circuit's `template` at the copy. Production follows the rating and the time of day, but
diff --git a/tests/test_readme_rehearsal.py b/tests/test_readme_rehearsal.py
index 313baaf..034a155 100644
--- a/tests/test_readme_rehearsal.py
+++ b/tests/test_readme_rehearsal.py
@@ -4,13 +4,15 @@
a template clone copies it. The first config is the panel before the upgrade, with
its "Commissioned PV System" circuit unlocked; the second is the same panel on
release 202639, with that circuit locked and, as "A second inverter" describes, a
-load circuit turned into a second inverter. If a step stops producing the panel the
-README promises, this fails, rather than a user's rehearsal.
+two-pole circuit turned into a second inverter: one the first config already models
+as a load, or one added to both configs on two free spaces. If a step stops
+producing the panel the README promises, this fails, rather than a user's rehearsal.
"""
from __future__ import annotations
import copy
+import logging
from typing import TYPE_CHECKING
import pytest
@@ -31,22 +33,43 @@
from panelbench.emitter_adapter.wire_capture import RecordingTransport
_ORIGINAL = "solar_inverter"
+# The second inverter's circuit as "A second inverter" adds it to a clone of a
+# template: a two-pole circuit on two free spaces on opposite legs.
+_ADDED = "solar_inverter_2"
+_ADDED_TABS = [24, 26]
-def _before() -> SimulationConfig:
+def _before(second: str | None = None) -> SimulationConfig:
"""Step 1, on a clone of a template: its PV circuit plays the "Commissioned PV
- System", renamed with its `id` kept, and its template unlocked."""
+ System", renamed with its `id` kept, and its template unlocked.
+
+ With *second* `_ADDED`, the second inverter's two-pole circuit is added too, as a
+ load, on two free spaces taken out of `unmapped_tabs`.
+ """
config = default_config()
[circuit] = [c for c in config["circuits"] if c["id"] == _ORIGINAL]
circuit["name"] = "Commissioned PV System"
solar = config["circuit_templates"][circuit["template"]]
solar["relay_behavior"] = "controllable"
solar["priority"] = "OFF_GRID"
+ if second == _ADDED:
+ templates = config["circuit_templates"]
+ templates[_ADDED] = copy.deepcopy(templates["new_circuit_tpl"])
+ config["circuits"].append(
+ {
+ "id": _ADDED,
+ "name": "Solar Inverter 2",
+ "template": _ADDED,
+ "tabs": list(_ADDED_TABS),
+ "breaker_rating": 20,
+ }
+ )
+ config["unmapped_tabs"] = [t for t in config["unmapped_tabs"] if t not in _ADDED_TABS]
return config
def _after(before: SimulationConfig, second: str) -> SimulationConfig:
- """Step 2, then "A second inverter" for the load circuit *second*."""
+ """Step 2, then "A second inverter" for the two-pole circuit *second*."""
config = copy.deepcopy(before)
config["firmware_version"] = "spanos3/r202639/03"
templates = config["circuit_templates"]
@@ -63,6 +86,8 @@ def _after(before: SimulationConfig, second: str) -> SimulationConfig:
copied["energy_profile"]["typical_power"] = -2280.0
templates["solar_2"] = copied
[circuit] = [c for c in config["circuits"] if c["id"] == second]
+ # "Name the circuit as its inverter's."
+ circuit["name"] = "Solar Inverter 2"
circuit["template"] = "solar_2"
# "Remove the circuit's own `overrides`."
circuit.pop("overrides", None)
@@ -112,17 +137,21 @@ async def test_the_first_config_is_the_panel_before_the_upgrade(tmp_path: Path)
@pytest.mark.parametrize(
"second",
- # A load whose override caps its power, and one whose override sets its typical
- # power: whatever the load carried has to go.
- ["new_circuit", "living_room_lights"],
+ # The circuit a template clone adds on two free spaces, and a two-pole load the
+ # clone already holds, whose override sets its typical power: whatever the load
+ # carried has to go.
+ [_ADDED, "main_hvac"],
)
@pytest.mark.asyncio
async def test_the_second_config_is_the_same_panel_on_release_202639(
- tmp_path: Path, second: str
+ tmp_path: Path, caplog: pytest.LogCaptureFixture, second: str
) -> None:
- runtime, recorder = await _started(
- write_config(tmp_path / "after.yaml", _after(_before(), second))
- )
+ before = _before(second)
+ [first_time] = [c for c in before["circuits"] if c["id"] == second]
+ with caplog.at_level(logging.WARNING):
+ runtime, recorder = await _started(
+ write_config(tmp_path / "after.yaml", _after(before, second))
+ )
serial = runtime.engine.serial_number
assert _circuit_state(recorder, serial, _ORIGINAL) == ("NEVER", "false")
@@ -140,3 +169,14 @@ async def test_the_second_config_is_the_same_panel_on_release_202639(
assert typical == -2280.0, "the inverter's typical power, not the load's, seeds its energy"
produced = engine.modelled_circuit_power(second, NOON)
assert 0 < produced <= 3800.0
+
+ # A grid-tied inverter is 240 V on a two-pole breaker, on the same spaces and with
+ # the same id in both configs, and is named as an inverter's circuit.
+ circuit_device = discovered_devices(recorder.retained)[stable_circuit_uuid(serial, second)]
+ spaces = str(circuit_device.get_property("info", "spaces"))
+ assert [int(t) for t in spaces.split(",")] == first_time["tabs"]
+ assert len(first_time["tabs"]) == 2
+ assert (circuit_device.description or {}).get("name") == "Solar Inverter 2"
+ assert not any(
+ "one tab" in r.getMessage() for r in caplog.records if r.levelno == logging.WARNING
+ )
From b875244efbcf0dc0f5b0fb880e60e4ebc30f81d6 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Wed, 7 Oct 2026 13:13:47 -0700
Subject: [PATCH 64/95] fix(rehearsal): lock the second inverter's circuit on
release 202639
From release 202639 SPAN publishes every commissioned inverter as its own PV
device, named by the circuit feeding it, and locks the circuits the panel adds for
a commissioned PV system: relay not switchable, priority permanently NEVER. A
circuit names a device it feeds only when that device is commissioned, so on that
release the second inverter's circuit is a locked one. The README's second-inverter
step copied the first config's unlocked template, so the r202639 config published
it switchable at OFF_GRID, which that release never does.
The step now copies the second config's template, locked, with
commissioned_system: pv, priority: NEVER and relay_behavior: non-controllable. It
keeps the inverter's name: SPAN's public notes do not say what a second
commissioned PV circuit is called, and the template, not the name, is the lock.
The first config's procedure is unchanged, since earlier releases lock nothing.
Validation now logs a WARNING for a solar circuit with tabs and no
commissioned_system: pv on a config naming release 202639 or later, or no release.
It does not refuse it: a template shipped before the key existed must keep loading,
and a panel clone recognises a commissioned circuit only by the name SPAN gives it,
so it can produce one. A what-if PV circuit with no tabs is not warned about.
The README procedure test now checks the second inverter's circuit publishes
NEVER with a locked relay and draws no warning; the old unlocked copy fails it.
---
README.md | 19 ++--
src/panelbench/validation.py | 49 ++++++++++
tests/test_readme_rehearsal.py | 20 +++--
tests/test_uncommissioned_pv_circuit_warns.py | 90 +++++++++++++++++++
4 files changed, 162 insertions(+), 16 deletions(-)
create mode 100644 tests/test_uncommissioned_pv_circuit_warns.py
diff --git a/README.md b/README.md
index af74e5d..cb2bd35 100644
--- a/README.md
+++ b/README.md
@@ -146,7 +146,7 @@ panel with one keeps its device id.
### A second inverter
Before release 202639 a panel publishes one solar device, so a clone holds one PV circuit and models any other inverter's circuit as a load. To rehearse the
-upgrade of a panel with a second inverter, also make that circuit an inverter's in the second config.
+upgrade of a panel with a second inverter, also make that circuit a commissioned inverter's, locked, in the second config.
The second inverter's circuit is a 240 V two-pole circuit, two tabs on opposite legs, as the "Commissioned PV System" circuit is: a grid-tied inverter in a US
panel, whether a string inverter or a set of microinverters, sits on a two-pole breaker. A clone of your panel already holds it, as a two-pole circuit modelled
@@ -155,13 +155,16 @@ as a load, so pick that circuit. A clone of a template has no second inverter, s
out of `unmapped_tabs`. PanelBench warns when a solar circuit sits on one tab. Then, in the second config:
- Name the circuit as its inverter's, for example `Solar Inverter 2`, rather than leaving a load's name.
-- Give it a PV template: copy the "Commissioned PV System" circuit's template as the first config has it, unlocked, under a new name. Set the copy's
- `energy_profile.nameplate_capacity_w` to the inverter's rating, its producer `power_range` to match, such as `[-7600.0, 0.0]`, and its `typical_power` to
- about 60% of the rating, negative, such as `-4560.0`, and point the circuit's `template` at the copy. Production follows the rating and the time of day, but
- `typical_power` seeds the energy total the inverter's circuit starts from, so a copy that keeps the original's would start with a total sized for the
- original inverter. The dashboard's nameplate field sets all three for you.
-- Remove the circuit's own `overrides`. They were the load's: a `power_range` there would cap the inverter's production, and a `typical_power` would replace
- the template's.
+- Give it a commissioned PV template: copy the "Commissioned PV System" circuit's template as this config has it, locked, under a new name. Release 202639
+ publishes each commissioned inverter fed by its own circuit and locks that circuit as it locks the "Commissioned PV System" one, so the copy keeps
+ `commissioned_system: pv`, `priority: NEVER` and `relay_behavior: non-controllable`; the template, not the name, is what locks it. PanelBench warns when a
+ solar circuit on a config naming release 202639 or later has no `commissioned_system: pv`. Set the copy's `energy_profile.nameplate_capacity_w` to the
+ inverter's rating, its producer `power_range` to match, such as `[-7600.0, 0.0]`, and its `typical_power` to about 60% of the rating, negative, such as
+ `-4560.0`, and point the circuit's `template` at the copy. Production follows the rating and the time of day, but `typical_power` seeds the energy total the
+ inverter's circuit starts from, so a copy that keeps the original's would start with a total sized for the original inverter. The dashboard's nameplate field
+ sets all three for you.
+- Remove the circuit's own `overrides`. They were the load's: a `power_range` there would cap the inverter's production, and a `typical_power` would replace the
+ template's.
- Give the circuit, under `circuits`, its own inverter's `vendor`, `model` and `serial_number`. It takes `pv.firmware_version` unless it sets its own
`firmware_version`, which a config with no `pv` section needs.
- Where the config has a top-level `pv` section, as a clone of a template does, set `pv.feed` to the `id` of the original inverter's circuit. The section
diff --git a/src/panelbench/validation.py b/src/panelbench/validation.py
index dfb61dd..56811dd 100644
--- a/src/panelbench/validation.py
+++ b/src/panelbench/validation.py
@@ -36,6 +36,11 @@ def validate_yaml_config(config_data: Any) -> None:
panel_firmware_version(config_data), config_data["circuit_templates"]
)
validate_circuits(config_data["circuits"], config_data["circuit_templates"])
+ _warn_uncommissioned_pv_circuits(
+ panel_firmware_version(config_data),
+ config_data["circuits"],
+ config_data["circuit_templates"],
+ )
validate_pv_section(config_data)
validate_ratings(config_data)
@@ -137,6 +142,50 @@ def _validate_commissioned_firmware(
)
+def _warn_uncommissioned_pv_circuits(
+ firmware: str,
+ circuits: list[Mapping[str, object]],
+ circuit_templates: Mapping[str, Mapping[str, object]],
+) -> None:
+ """From SPAN release 202639 a circuit feeding an inverter is a locked one.
+
+ That release publishes every commissioned inverter as its own PV device, named by
+ the circuit feeding it, and locks the circuits the panel adds for a commissioned
+ PV system (SPAN-API-Client-Docs, Release 202639). A circuit names a device it
+ feeds only when that device is commissioned, so on that release a PV circuit
+ without ``commissioned_system: pv`` publishes a switchable, re-prioritisable
+ circuit the release never does.
+
+ Warned, not refused: a config that loaded before must keep loading, such as a
+ template shipped before the key existed, and a panel clone recognises a
+ commissioned circuit only by the name SPAN gives it, so it can produce one. A PV
+ circuit with no tabs, a what-if one, is fed by no breaker.
+
+ *circuits* and *circuit_templates* have already passed validation, so every
+ circuit names a template that exists.
+ """
+ if predates(firmware, SPAN_RELEASE_202639):
+ return
+ for circuit in circuits:
+ template_name = str(circuit["template"])
+ template = circuit_templates[template_name]
+ if (
+ template.get("device_type") == "pv"
+ and template.get("commissioned_system") != "pv"
+ and circuit.get("tabs")
+ ):
+ _LOGGER.warning(
+ "Circuit %r feeds a solar inverter, which SPAN release 202639 and later "
+ "lock as a commissioned PV system, but firmware_version is %r and its "
+ "template %r has no commissioned_system: pv, so its relay and priority "
+ "stay settable; give the template commissioned_system: pv, priority: NEVER "
+ "and relay_behavior: non-controllable",
+ circuit["id"],
+ firmware,
+ template_name,
+ )
+
+
def validate_circuits(circuits: Any, circuit_templates: dict[str, Any]) -> None:
"""Validate circuits section."""
if not isinstance(circuits, list):
diff --git a/tests/test_readme_rehearsal.py b/tests/test_readme_rehearsal.py
index 034a155..bdab347 100644
--- a/tests/test_readme_rehearsal.py
+++ b/tests/test_readme_rehearsal.py
@@ -4,9 +4,10 @@
a template clone copies it. The first config is the panel before the upgrade, with
its "Commissioned PV System" circuit unlocked; the second is the same panel on
release 202639, with that circuit locked and, as "A second inverter" describes, a
-two-pole circuit turned into a second inverter: one the first config already models
-as a load, or one added to both configs on two free spaces. If a step stops
-producing the panel the README promises, this fails, rather than a user's rehearsal.
+two-pole circuit turned into a second inverter, its circuit locked the same way: one
+the first config already models as a load, or one added to both configs on two free
+spaces. If a step stops producing the panel the README promises, this fails, rather
+than a user's rehearsal.
"""
from __future__ import annotations
@@ -79,8 +80,9 @@ def _after(before: SimulationConfig, second: str) -> SimulationConfig:
solar["priority"] = "NEVER"
solar["relay_behavior"] = "non-controllable"
- # "Give it a PV template": the commissioned template as the first config has it.
- copied = copy.deepcopy(before["circuit_templates"][original["template"]])
+ # "Give it a commissioned PV template": the commissioned template as this config
+ # has it, locked.
+ copied = copy.deepcopy(solar)
copied["energy_profile"]["nameplate_capacity_w"] = 3800.0
copied["energy_profile"]["power_range"] = [-3800.0, 0.0]
copied["energy_profile"]["typical_power"] = -2280.0
@@ -155,6 +157,8 @@ async def test_the_second_config_is_the_same_panel_on_release_202639(
serial = runtime.engine.serial_number
assert _circuit_state(recorder, serial, _ORIGINAL) == ("NEVER", "false")
+ # Release 202639 locks the circuit feeding each commissioned inverter.
+ assert _circuit_state(recorder, serial, second) == ("NEVER", "false")
inverters = {
device.get_property("info", "model"): device for device in _inverters(recorder).values()
}
@@ -177,6 +181,6 @@ async def test_the_second_config_is_the_same_panel_on_release_202639(
assert [int(t) for t in spaces.split(",")] == first_time["tabs"]
assert len(first_time["tabs"]) == 2
assert (circuit_device.description or {}).get("name") == "Solar Inverter 2"
- assert not any(
- "one tab" in r.getMessage() for r in caplog.records if r.levelno == logging.WARNING
- )
+ warnings = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
+ assert not any("one tab" in message for message in warnings)
+ assert not any("commissioned_system: pv" in message for message in warnings)
diff --git a/tests/test_uncommissioned_pv_circuit_warns.py b/tests/test_uncommissioned_pv_circuit_warns.py
new file mode 100644
index 0000000..dd9f3dd
--- /dev/null
+++ b/tests/test_uncommissioned_pv_circuit_warns.py
@@ -0,0 +1,90 @@
+"""A solar circuit left unlocked on release 202639 is warned about, never refused.
+
+From SPAN release 202639 every commissioned inverter is its own PV device, named
+by the circuit feeding it, and the circuits the panel adds for a commissioned PV
+system are locked: relay not switchable, priority permanently NEVER
+(SPAN-API-Client-Docs CHANGELOG, Release 202639). A circuit names a device it feeds
+only when that device is commissioned, so on that release a circuit feeding an
+inverter is a locked one. A config naming it whose PV circuit has no
+`commissioned_system: pv` publishes a circuit the release never does.
+
+Warned, not refused: a config that loaded before must keep loading, such as a
+template shipped before the key existed, and a clone of a panel recognises a
+commissioned circuit by the name SPAN gives it, so it can produce one.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+
+from panelbench.config_types import SimulationConfig
+from panelbench.validation import validate_yaml_config
+from tests._helpers import CURRENT_FIRMWARE, EARLIER_FIRMWARE, default_config
+
+
+def _solar_on(
+ firmware: str, *, commissioned: bool, tabs: list[int] | None = None
+) -> SimulationConfig:
+ """The default panel naming *firmware*, its solar circuit locked or not."""
+ config = default_config()
+ config["firmware_version"] = firmware
+ [solar] = [c for c in config["circuits"] if c["id"] == "solar_inverter"]
+ if tabs is not None:
+ solar["tabs"] = tabs
+ template = config["circuit_templates"][solar["template"]]
+ template["relay_behavior"] = "non-controllable"
+ template["priority"] = "NEVER"
+ if commissioned:
+ template["commissioned_system"] = "pv"
+ return config
+
+
+def _unlocked_warnings(caplog: pytest.LogCaptureFixture) -> list[str]:
+ return [
+ r.getMessage()
+ for r in caplog.records
+ if r.levelno == logging.WARNING and "commissioned_system: pv" in r.getMessage()
+ ]
+
+
+@pytest.mark.parametrize(
+ "firmware",
+ # A string naming no release is taken to be current, as the emitter takes it.
+ [CURRENT_FIRMWARE, "sim/v0.1.0"],
+)
+def test_an_uncommissioned_pv_circuit_loads_with_a_warning(
+ caplog: pytest.LogCaptureFixture, firmware: str
+) -> None:
+ with caplog.at_level(logging.WARNING):
+ validate_yaml_config(_solar_on(firmware, commissioned=False))
+
+ [message] = _unlocked_warnings(caplog)
+ assert "'solar_inverter'" in message
+ assert "'solar'" in message
+
+
+def test_a_commissioned_pv_circuit_is_not_warned_about(caplog: pytest.LogCaptureFixture) -> None:
+ with caplog.at_level(logging.WARNING):
+ validate_yaml_config(_solar_on(CURRENT_FIRMWARE, commissioned=True))
+
+ assert not _unlocked_warnings(caplog)
+
+
+def test_a_pv_circuit_before_release_202639_is_not_warned_about(
+ caplog: pytest.LogCaptureFixture,
+) -> None:
+ """Before release 202639 the circuit is unlocked, and the key is refused there."""
+ with caplog.at_level(logging.WARNING):
+ validate_yaml_config(_solar_on(EARLIER_FIRMWARE, commissioned=False))
+
+ assert not _unlocked_warnings(caplog)
+
+
+def test_a_virtual_pv_circuit_is_not_warned_about(caplog: pytest.LogCaptureFixture) -> None:
+ """A PV circuit with no tabs is a what-if one, which no breaker feeds."""
+ with caplog.at_level(logging.WARNING):
+ validate_yaml_config(_solar_on(CURRENT_FIRMWARE, commissioned=False, tabs=[]))
+
+ assert not _unlocked_warnings(caplog)
From 61b16bc9fc27bab3530648c3071a21be11aea00c Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Wed, 7 Oct 2026 18:30:31 -0700
Subject: [PATCH 65/95] docs(changelog): note the solar circuit warnings, and
date 2.6.0
Validation now warns about a solar circuit on one tab, and, on release 202639
or a config naming no release, about a solar circuit on a breaker whose template
lacks commissioned_system: pv. Both are new in 2.6.0, so both changelogs say so.
The add-on store changelog's 2.6.0 date was held for the release; it is now the
date the release PR is opened. The root changelog is rewrapped at the repository's
160-column prose width, which three entries had drifted from.
---
CHANGELOG.md | 12 ++++++++----
panelbench/CHANGELOG.md | 4 +++-
2 files changed, 11 insertions(+), 5 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1651fd7..9ab264e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,10 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
source control.
- **Commissioned PV and battery system circuits**, locked as SPAN firmware release 202639 locks them, are modelled and kept by a clone, and a config naming an
earlier release is refused if it asks for one.
+- **The log warns about a solar circuit on a breaker whose template lacks `commissioned_system: pv` when the config's `firmware_version` names SPAN release
+ 202639 or later, or no SPAN release**, since that release locks such a circuit, though the config still loads.
+- **The log warns about a solar circuit on a single tab**, since a grid-tied inverter is 240 V on a two-pole breaker with two tabs on opposite legs, though the
+ config still loads.
- **From SPAN firmware release 202639, a panel's status endpoint reports its hardware version**, as SPAN's does: `1.2` or `2.0` from the config's
`hardware_version`, and `UNKNOWN` for any other value.
- **The dashboard's Import accepts a panel definition file**, such as one `panel-sim-capture` wrote from a live panel, and turns it into a PanelBench config.
@@ -33,8 +37,8 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
- **The top-level `pv` section now describes the inverter whose circuit `pv.feed` names by its `id`, or the only solar circuit's, where it followed whichever
solar circuit was listed first**; a `pv.feed` that names no solar circuit's `id` is now refused, as is a config with several solar circuits and no `pv.feed`
whose `firmware_version` names a release before 202639.
-- **A solar rating set in the dashboard now replaces the stale copy a clone of the shipped MAIN 40 or MAIN 32 template kept**, at the template's top level or
- in the solar circuit's `overrides`, and the log warns with both values and the file until the config is saved in the dashboard.
+- **A solar rating set in the dashboard now replaces the stale copy a clone of the shipped MAIN 40 or MAIN 32 template kept**, at the template's top level or in
+ the solar circuit's `overrides`, and the log warns with both values and the file until the config is saved in the dashboard.
- **A `pv.nameplate_capacity_w`, or a circuit's `overrides` rating on a template other circuits share, that disagrees with the template's `energy_profile`
rating is now refused, naming both**, where the two could each win somewhere different; an equal or lone legacy rating moves into the template's
`energy_profile`.
@@ -62,8 +66,8 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
- **The dashboard refuses an edit the panel would not load, says why and keeps the config as it was, and starts when the active config is one the panel
refuses**, where such an edit was saved and the panel then failed to restart, and an add-on restart with it active left no dashboard to fix it from.
- **The dashboard's Add Entity places a new circuit on the first free space**, where it made a circuit with no space, which the panel refused.
-- **The dashboard's relay control shows a locked relay however its config spells it**, where a circuit written `non-controllable`, as the shipped configs
- write it, showed `controllable` and saving its form unlocked it.
+- **The dashboard's relay control shows a locked relay however its config spells it**, where a circuit written `non-controllable`, as the shipped configs write
+ it, showed `controllable` and saving its form unlocked it.
- **A solar inverter's nameplate edited in the dashboard now survives a restart and is the rating the panel both publishes and produces at**, including in a
clone of the shipped MAIN 40 or MAIN 32 template, where the template's stale copy of the rating replaced the edit when the panel started.
diff --git a/panelbench/CHANGELOG.md b/panelbench/CHANGELOG.md
index 412bb0e..deecf40 100644
--- a/panelbench/CHANGELOG.md
+++ b/panelbench/CHANGELOG.md
@@ -1,6 +1,6 @@
# Changelog
-## 2.6.0 — 2026-10-06
+## 2.6.0 — 2026-10-07
SPAN firmware release 202639 arrives for any config that names it, while the shipped templates stay on release 202633's conventions. A config or clone that
names no SPAN release, including a clone of the earlier MAIN 40 template, now publishes release 202639's; to keep the earlier conventions, set its
@@ -12,6 +12,8 @@ names no SPAN release, including a clone of the earlier MAIN 40 template, now pu
control.
- **Commissioned PV and battery system circuits are modelled and kept by a clone**, locked as release 202639 locks them, and a config naming an earlier release
is refused if it asks for one.
+- **From release 202639, the log warns about a solar circuit on a breaker whose template lacks `commissioned_system: pv`**, since that release locks it.
+- **The log warns about a solar circuit on a single tab**, since a grid-tied inverter is 240 V on a two-pole breaker.
- **From release 202639, a panel's status endpoint reports its hardware version**: `1.2` or `2.0` from the config's `hardware_version`, and `UNKNOWN` otherwise.
- **The dashboard's Import accepts a panel definition file**, such as one `panel-sim-capture` wrote from a live panel, and turns it into a PanelBench config.
- **The dashboard can export a saved config as a panel definition file**, the makeup other eBus tools read.
From 1fa43cfe93c79eb7d3eb2694a26fc8e73980dd69 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:35:04 -0700
Subject: [PATCH 66/95] fix(engine): seed a panel's weather from a digest of
its serial
The live solar curve and the producer energy estimate were seeded with
hash(serial_number), which Python salts per interpreter. Each start gave
the same panel different weather, so solar output stepped at every
restart and never matched the history generated for the same days.
Both now seed from solar.weather_seed, the SHA-256 derivation the
history generator already used, which it now shares.
---
src/panelbench/engine.py | 6 +--
src/panelbench/history_generator.py | 6 +--
src/panelbench/solar.py | 12 +++++
tests/test_weather_seed.py | 72 +++++++++++++++++++++++++++++
4 files changed, 89 insertions(+), 7 deletions(-)
create mode 100644 tests/test_weather_seed.py
diff --git a/src/panelbench/engine.py b/src/panelbench/engine.py
index 29ceb9d..20cea29 100644
--- a/src/panelbench/engine.py
+++ b/src/panelbench/engine.py
@@ -44,7 +44,7 @@
from panelbench.recorder import RecorderDataSource
from panelbench.hvac import hvac_seasonal_factor
-from panelbench.solar import daily_weather_factor, solar_production_factor
+from panelbench.solar import daily_weather_factor, solar_production_factor, weather_seed
from panelbench.validation import validate_yaml_config
from panelbench.weather import get_cached_weather
@@ -333,7 +333,7 @@ def _apply_solar_day_night_cycle(self, base_power: float, current_time: float) -
weather = daily_weather_factor(
current_time,
- seed=hash(self._config["panel_config"]["serial_number"]),
+ seed=weather_seed(self._config["panel_config"]["serial_number"]),
monthly_factors=monthly_factors,
)
return abs(base_power) * factor * weather
@@ -462,7 +462,7 @@ def _estimate_solar_annual_factor(self) -> float:
"""
lat = self._config["panel_config"].get("latitude", 37.7)
lon = self._config["panel_config"].get("longitude", -122.4)
- seed = hash(self._config["panel_config"]["serial_number"])
+ seed = weather_seed(self._config["panel_config"]["serial_number"])
monthly_factors: dict[int, float] | None = None
cached = get_cached_weather(lat, lon)
diff --git a/src/panelbench/history_generator.py b/src/panelbench/history_generator.py
index 2192ea1..91d79cb 100644
--- a/src/panelbench/history_generator.py
+++ b/src/panelbench/history_generator.py
@@ -27,7 +27,7 @@
from panelbench.config_defaults import normalize_config
from panelbench.hvac import hvac_seasonal_factor
-from panelbench.solar import daily_weather_factor, solar_production_factor
+from panelbench.solar import daily_weather_factor, solar_production_factor, weather_seed
from panelbench.sqlite_history import SCHEMA_SQL
from panelbench.weather import fetch_historical_weather, get_cached_weather
@@ -350,9 +350,7 @@ def _generate_rows(
# Mean of monthly factors for normalisation
mean_mf = sum(monthly_factors.values()) / len(monthly_factors) if monthly_factors else 1.0
- # Precompute deterministic seed from serial for weather factor
- serial_bytes = str(serial).encode("utf-8")
- serial_seed = int.from_bytes(hashlib.sha256(serial_bytes).digest()[:8], "big")
+ serial_seed = weather_seed(str(serial))
batch: list[tuple[object, ...]] = []
ts = start_ts
diff --git a/src/panelbench/solar.py b/src/panelbench/solar.py
index 6bd1380..113fec1 100644
--- a/src/panelbench/solar.py
+++ b/src/panelbench/solar.py
@@ -11,6 +11,7 @@
from __future__ import annotations
+import hashlib
import math
DEFAULT_LATITUDE = 37.7 # San Francisco
@@ -118,6 +119,17 @@ def solar_production_factor(
return float(min(1.0, max(0.0, raw)))
+def weather_seed(serial_number: str) -> int:
+ """The weather seed for a panel, the same in every process that asks.
+
+ A digest rather than ``hash()``, which Python salts per interpreter: a serial
+ seeded from ``hash`` gets different weather each time PanelBench starts. The
+ live engine and the history generator both seed from here, so the history a
+ panel is given and the weather it then runs into are one sky.
+ """
+ return int.from_bytes(hashlib.sha256(serial_number.encode("utf-8")).digest()[:8], "big")
+
+
def daily_weather_factor(
timestamp: float,
*,
diff --git a/tests/test_weather_seed.py b/tests/test_weather_seed.py
new file mode 100644
index 0000000..cd689fe
--- /dev/null
+++ b/tests/test_weather_seed.py
@@ -0,0 +1,72 @@
+"""A panel's weather is the same in every process that simulates it.
+
+The live engine seeded its weather with ``hash(serial_number)``, and Python salts
+``hash`` of a string per interpreter (``PYTHONHASHSEED``). So each start of
+PanelBench gave the same serial different weather: solar output stepped up or
+down at every restart, the producer energy estimate moved with it, and neither
+matched the history generated for the same days, which was already seeded from a
+digest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from panelbench.solar import weather_seed
+
+_CONFIG = Path(__file__).resolve().parents[1] / "configs" / "default_MAIN_40.yaml"
+
+# Noon in the default config's timezone (America/Los_Angeles) on 2024-07-01, so the
+# sun is up and the weather factor is what decides the output.
+_SUMMER_NOON = 1719860400.0
+
+# Both places the engine seeds from the serial: the live solar curve, and the
+# annual estimate that gives an unseeded producer its starting energy.
+_PROBE = f"""
+import sys
+
+import yaml
+
+from panelbench.engine import RealisticBehaviorEngine
+
+config = yaml.safe_load(open(sys.argv[1]))
+engine = RealisticBehaviorEngine(0.0, config)
+producer = next(
+ t for t in config["circuit_templates"].values()
+ if t["energy_profile"]["mode"] == "producer"
+)
+print(repr(engine.estimate_annual_energy_wh(producer)))
+print(repr(engine._apply_solar_day_night_cycle(1000.0, {_SUMMER_NOON})))
+"""
+
+
+def _simulate_in_a_fresh_process(hash_seed: str) -> str:
+ result = subprocess.run(
+ [sys.executable, "-c", _PROBE, str(_CONFIG)],
+ env={**os.environ, "PYTHONHASHSEED": hash_seed},
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+ return result.stdout
+
+
+def test_a_serial_gets_the_same_weather_in_every_process() -> None:
+ first, second = (_simulate_in_a_fresh_process(seed) for seed in ("1", "2"))
+
+ assert float(first.splitlines()[1]) > 0, "the probe ran at night and proves nothing"
+ assert first == second
+
+
+def test_the_seed_is_the_one_history_has_always_used() -> None:
+ """History already generated for a panel was seeded this way, so the live
+ weather now continues it rather than starting a different sky at the join."""
+ serial = "example-serial-001"
+
+ assert weather_seed(serial) == int.from_bytes(
+ hashlib.sha256(serial.encode("utf-8")).digest()[:8], "big"
+ )
From 1601a1353121770574d97f2824758f3f947b25bd Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:35:12 -0700
Subject: [PATCH 67/95] fix(mqtt): act on Home Assistant's commands and survive
a broker restart
Inbound /set commands were dropped. The SDK subscribes each settable
property with the callback that applies a command to it; the transport
discarded that callback, and nothing read aiomqtt's message queue, so a
relay or priority command from Home Assistant reached the broker and
stopped there.
The connection also died with its broker. aiomqtt 2.x does not
reconnect, is_connected only said a client object existed, and every
publish after an outage failed with a traceback of its own.
BrokerLink replaces the single aiomqtt client with a supervised one. It
records each subscription's filter, callback and QoS, reads every
message and hands it to the callback of each filter it matches, and on
the link dropping reconnects with bounded exponential backoff, replays
every subscription and then calls Emitter.republish_tree, the hook the
SDK leaves to whoever injects a client. is_connected now follows the
live link. An outage logs one warning; operations attempted during it
raise BrokerUnavailable, which the transport drops at debug, and any
operation in flight when the link drops is abandoned rather than left
waiting out aiomqtt's ten-second PUBACK timeout. The delay resets only
after a connection outlasts the ceiling, so a broker that drops the
panel on every connect is retried at the ceiling.
The real-broker test restarts a mosquitto process under a running
panel and is skipped where mosquitto is not installed.
---
src/panelbench/emitter_adapter/broker_link.py | 316 +++++++++++++++
src/panelbench/emitter_adapter/runtime.py | 128 ++-----
src/panelbench/emitter_adapter/transport.py | 71 +++-
tests/_helpers.py | 20 +
tests/emitter_adapter/_fake_aiomqtt.py | 144 +++++++
tests/emitter_adapter/conftest.py | 15 +
tests/emitter_adapter/test_broker_link.py | 359 ++++++++++++++++++
.../test_runtime_transport_path.py | 119 +++---
tests/emitter_adapter/test_transport.py | 66 +++-
tests/integration/test_broker_restart.py | 169 +++++++++
10 files changed, 1240 insertions(+), 167 deletions(-)
create mode 100644 src/panelbench/emitter_adapter/broker_link.py
create mode 100644 tests/emitter_adapter/_fake_aiomqtt.py
create mode 100644 tests/emitter_adapter/conftest.py
create mode 100644 tests/emitter_adapter/test_broker_link.py
create mode 100644 tests/integration/test_broker_restart.py
diff --git a/src/panelbench/emitter_adapter/broker_link.py b/src/panelbench/emitter_adapter/broker_link.py
new file mode 100644
index 0000000..f286112
--- /dev/null
+++ b/src/panelbench/emitter_adapter/broker_link.py
@@ -0,0 +1,316 @@
+"""The panel's connection to its broker, kept up for as long as the panel runs.
+
+An ``aiomqtt.Client`` is one connection. It does not reconnect, and it does not
+route: what arrives on it waits in ``client.messages`` until something reads it.
+The SDK's own ``MqttClient`` does both for a client it builds — it re-subscribes
+every filter on reconnect, calls its on-connect hook, and hands each message to
+the callback its filter was subscribed with. For a client injected into the SDK,
+as this package's is, all of that is the caller's. This module is the caller's
+half.
+
+**One client per connection.** The supervisor enters a fresh client for each
+attempt, so nothing survives from a connection the broker no longer knows about:
+the session is clean, and the filters the broker forgot are replayed from
+``_routes``, which outlives every client.
+
+**A link that keeps dropping backs off.** The delay before a reconnect doubles
+up to a ceiling, and resets only once a connection has outlasted that ceiling. A
+broker that accepts and then drops the panel at once, as one does when a second
+client takes over the same client id, is retried at the ceiling rather than
+every second.
+
+**An outage is reported once.** The first sign of it, whether the reader seeing
+the link drop or an operation failing on it, logs a single warning. Everything
+attempted until the link is back raises ``BrokerUnavailable``, which the transport
+drops quietly, and failed reconnect attempts log only at debug.
+
+**Nothing waits on a dead socket.** aiomqtt resolves a QoS 1 publish on its
+PUBACK, and a client whose socket has died never gets one, so the publish waits
+out aiomqtt's timeout. The transport drains one operation at a time, so for that
+long nothing else moves, the republished tree included. Each operation therefore
+runs under a deadline the supervisor brings forward to now when the link drops.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import aiomqtt
+
+from panelbench.emitter_adapter.transport import BrokerUnavailable, MessageCallback
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator, Callable
+
+_LOG = logging.getLogger(__name__)
+
+DEFAULT_MIN_RECONNECT_DELAY = 1.0
+# A broker restart is usually back within seconds. The ceiling bounds how long a
+# panel stays dark after a longer outage ends, at a cost of one refused connection
+# per interval while it lasts.
+DEFAULT_MAX_RECONNECT_DELAY = 30.0
+
+
+class _Backoff:
+ """Reconnect delays that double from *first* up to *ceiling*."""
+
+ def __init__(self, *, first: float, ceiling: float) -> None:
+ self._first = first
+ self.ceiling = ceiling
+ self._next = first
+
+ def next_delay(self) -> float:
+ delay = self._next
+ self._next = min(delay * 2, self.ceiling)
+ return delay
+
+ def reset(self) -> None:
+ self._next = self._first
+
+
+@dataclass(frozen=True, slots=True)
+class _Route:
+ callback: MessageCallback
+ qos: int
+
+
+class _Session:
+ """One connected client, and the operations in flight on it."""
+
+ def __init__(self, client: aiomqtt.Client) -> None:
+ self.client = client
+ self.outage_reported = False
+ self._in_flight: set[asyncio.Timeout] = set()
+
+ @contextlib.asynccontextmanager
+ async def operation(self) -> AsyncIterator[aiomqtt.Client]:
+ """The client, for one operation that ``abandon`` can cut short.
+
+ Cut short, the operation raises ``TimeoutError`` out of this block.
+ """
+ async with asyncio.timeout(None) as deadline:
+ self._in_flight.add(deadline)
+ try:
+ yield self.client
+ finally:
+ self._in_flight.discard(deadline)
+
+ def abandon(self) -> None:
+ """End every operation in flight: the link they were waiting on is gone."""
+ now = asyncio.get_running_loop().time()
+ for deadline in self._in_flight:
+ deadline.reschedule(now)
+
+
+class BrokerLink:
+ """A supervised aiomqtt connection that reconnects, re-subscribes and routes.
+
+ ``connect`` returns once the first connection is up, and raises if it cannot
+ be made, as start-up did before the link supervised itself. From then on the
+ supervisor keeps it up until ``disconnect``: after each reconnect it restores
+ every subscription and then runs the ``on_reconnect`` hook.
+ """
+
+ def __init__(
+ self,
+ *,
+ host: str,
+ port: int,
+ client_id: str,
+ username: str | None = None,
+ password: str | None = None,
+ will: aiomqtt.Will | None = None,
+ ca_cert_path: str | None = None,
+ min_reconnect_delay: float = DEFAULT_MIN_RECONNECT_DELAY,
+ max_reconnect_delay: float = DEFAULT_MAX_RECONNECT_DELAY,
+ ) -> None:
+ self._host = host
+ self._port = port
+ self._client_id = client_id
+ self._username = username
+ self._password = password
+ self._will = will
+ self._ca_cert_path = ca_cert_path
+ self._backoff = _Backoff(first=min_reconnect_delay, ceiling=max_reconnect_delay)
+ self._routes: dict[str, _Route] = {}
+ self._session: _Session | None = None
+ self._supervisor: asyncio.Task[None] | None = None
+ self._on_reconnect: Callable[[], None] | None = None
+
+ # -- lifecycle --------------------------------------------------------------
+
+ async def connect(self) -> None:
+ """Open the link, raising ``aiomqtt.MqttError`` if the broker refuses it."""
+ if self._supervisor is not None:
+ raise RuntimeError("the broker link is already open")
+ connected: asyncio.Future[None] = asyncio.get_running_loop().create_future()
+ self._supervisor = asyncio.create_task(
+ self._supervise(connected), name=f"mqtt-link-{self._client_id}"
+ )
+ try:
+ await connected
+ except BaseException:
+ await self.disconnect()
+ raise
+
+ def on_reconnect(self, hook: Callable[[], None]) -> None:
+ """Run *hook* after each reconnect, once every subscription is restored.
+
+ Not after the first connection: whatever is built on the link announces
+ itself then. Set after ``connect`` because the hook is typically a method
+ of something that needs the link up to be built.
+ """
+ self._on_reconnect = hook
+
+ async def disconnect(self) -> None:
+ """Stop the supervisor and close the client cleanly, which suppresses the will."""
+ supervisor, self._supervisor = self._supervisor, None
+ if supervisor is None:
+ return
+ supervisor.cancel()
+ await asyncio.wait({supervisor})
+
+ # -- the operations the transport drains into -------------------------------
+
+ def is_connected(self) -> bool:
+ return self._session is not None
+
+ async def publish(
+ self, topic: str, payload: bytes, qos: int = 0, retain: bool = False
+ ) -> None:
+ session = self._live_session()
+ try:
+ async with session.operation() as client:
+ await client.publish(topic, payload=payload, qos=qos, retain=retain)
+ except (aiomqtt.MqttError, TimeoutError) as exc:
+ self._report_outage(session, exc)
+ raise BrokerUnavailable(f"publish to {topic} was not sent") from exc
+
+ async def subscribe(self, topic_filter: str, callback: MessageCallback, qos: int = 0) -> None:
+ """Route messages on *topic_filter* to *callback*, now and after every reconnect.
+
+ Recorded before anything is sent, so a filter the link is down for is
+ still restored when it comes back: the SDK subscribes once and never again.
+ """
+ self._routes[topic_filter] = _Route(callback, qos)
+ session = self._live_session()
+ try:
+ async with session.operation() as client:
+ await client.subscribe(topic_filter, qos=qos)
+ except (aiomqtt.MqttError, TimeoutError) as exc:
+ self._report_outage(session, exc)
+ raise BrokerUnavailable(f"subscription to {topic_filter} was not sent") from exc
+
+ # -- internals --------------------------------------------------------------
+
+ def _live_session(self) -> _Session:
+ session = self._session
+ if session is None:
+ raise BrokerUnavailable(f"no connection to the MQTT broker at {self._address}")
+ return session
+
+ @property
+ def _address(self) -> str:
+ return f"{self._host}:{self._port}"
+
+ def _new_client(self) -> aiomqtt.Client:
+ tls_params = (
+ aiomqtt.TLSParameters(ca_certs=self._ca_cert_path) if self._ca_cert_path else None
+ )
+ return aiomqtt.Client(
+ hostname=self._host,
+ port=self._port,
+ identifier=self._client_id,
+ username=self._username,
+ password=self._password,
+ will=self._will,
+ tls_params=tls_params,
+ )
+
+ async def _supervise(self, connected: asyncio.Future[None]) -> None:
+ loop = asyncio.get_running_loop()
+ reconnecting = False
+ while True:
+ session: _Session | None = None
+ opened_at: float | None = None
+ try:
+ async with self._new_client() as client:
+ opened_at = loop.time()
+ session = _Session(client)
+ self._session = session
+ try:
+ if reconnecting:
+ _LOG.info("reconnected to the MQTT broker at %s", self._address)
+ await self._restore(client)
+ else:
+ reconnecting = True
+ if not connected.done():
+ connected.set_result(None)
+ async for message in client.messages:
+ self._dispatch(message.topic.value, message.payload)
+ finally:
+ self._session = None
+ session.abandon()
+ except aiomqtt.MqttError as exc:
+ if not reconnecting:
+ self._fail_start(connected, exc)
+ return
+ # A refused reconnect has no session: its outage is already reported.
+ if session is not None:
+ self._report_outage(session, exc)
+ except Exception as exc:
+ if not reconnecting:
+ self._fail_start(connected, exc)
+ return
+ _LOG.exception("the link to the MQTT broker at %s failed", self._address)
+ if opened_at is not None and loop.time() - opened_at >= self._backoff.ceiling:
+ self._backoff.reset()
+ delay = self._backoff.next_delay()
+ _LOG.debug("reconnecting to the MQTT broker at %s in %.2fs", self._address, delay)
+ await asyncio.sleep(delay)
+
+ @staticmethod
+ def _fail_start(connected: asyncio.Future[None], exc: Exception) -> None:
+ """The first connection failed: ``connect`` raises it, the supervisor ends."""
+ if not connected.done():
+ connected.set_exception(exc)
+
+ async def _restore(self, client: aiomqtt.Client) -> None:
+ """Replay every subscription, then run the hook: the order the SDK's client keeps."""
+ for topic_filter, route in list(self._routes.items()):
+ await client.subscribe(topic_filter, qos=route.qos)
+ if self._on_reconnect is None:
+ return
+ try:
+ self._on_reconnect()
+ except Exception:
+ # The link is up and serving commands; a hook that failed must not end it.
+ _LOG.exception("the reconnect hook failed")
+
+ def _dispatch(self, topic: str, payload: bytes) -> None:
+ """Hand a message to the callback of each filter it matches, as a broker would."""
+ delivered = aiomqtt.Topic(topic)
+ for topic_filter, route in list(self._routes.items()):
+ if not delivered.matches(topic_filter):
+ continue
+ try:
+ route.callback(topic, payload)
+ except Exception:
+ _LOG.warning("the handler for %s raised", topic, exc_info=True)
+
+ def _report_outage(self, session: _Session, exc: BaseException) -> None:
+ if session.outage_reported:
+ return
+ session.outage_reported = True
+ # aiomqtt raises a generic "Disconnected during message iteration" from the
+ # error that says what actually happened.
+ reason = exc.__cause__ or exc
+ _LOG.warning(
+ "lost the MQTT broker at %s (%s); reconnecting",
+ self._address,
+ str(reason) or type(reason).__name__,
+ )
diff --git a/src/panelbench/emitter_adapter/runtime.py b/src/panelbench/emitter_adapter/runtime.py
index 0095873..2ecbabe 100644
--- a/src/panelbench/emitter_adapter/runtime.py
+++ b/src/panelbench/emitter_adapter/runtime.py
@@ -10,12 +10,13 @@
``TickInputs`` and hands it to ``Emitter.publish_tick``. The emitter does the
rest: BESS dispatch, load shedding, energy integration, panel meter aggregation,
diff publication. /set commands are handled by the emitter's internal default
-handlers (no producer-side setter wiring needed)."""
+handlers (no producer-side setter wiring needed); the broker link routes each
+command to the handler the SDK subscribed with."""
from __future__ import annotations
from dataclasses import dataclass
-from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from typing import TYPE_CHECKING
import aiomqtt
@@ -33,6 +34,7 @@
)
from panelbench.const import DEFAULT_WIFI_SSID
+from panelbench.emitter_adapter.broker_link import BrokerLink
from panelbench.emitter_adapter.definition import bess_config, build_definition
from panelbench.emitter_adapter.instance_ids import (
evse_device_id,
@@ -64,25 +66,6 @@ class BrokerConnection:
ca_cert_path: str | None = None
-@runtime_checkable
-class MqttPublisher(Protocol):
- """Structural subset of the MQTT client interface the emitter consumes.
-
- Mirrors the emitter's internal ``_MqttClientLike`` protocol; we redeclare
- it here rather than import an underscore-private symbol across packages."""
-
- def is_connected(self) -> bool: ...
- async def publish(
- self,
- topic: str,
- payload: bytes,
- qos: int = 0,
- retain: bool = False,
- ) -> None: ...
- async def subscribe(self, topic: str) -> None: ...
- async def disconnect(self) -> None: ...
-
-
@dataclass(slots=True)
class CloneRuntime:
engine: DynamicSimulationEngine
@@ -91,80 +74,13 @@ class CloneRuntime:
transport: MqttDeviceTransport
emitter: Emitter
uuid_to_circuit_id: dict[str, str]
- mqtt: MqttPublisher | None = None
- """The async client, when this runtime opened one.
+ mqtt: BrokerLink | None = None
+ """The broker link, when this runtime opened one.
``None`` when a transport was injected: whoever supplied it owns its
lifecycle, which is the same rule the SDK follows for an injected client."""
-class _AiomqttPublisher:
- """Adapter wrapping ``aiomqtt.Client`` to satisfy the emitter's duck-typed
- MQTT interface (``is_connected``, ``publish``, ``subscribe``)."""
-
- def __init__(
- self,
- host: str,
- port: int,
- client_id: str,
- username: str | None = None,
- password: str | None = None,
- will: aiomqtt.Will | None = None,
- ca_cert_path: str | None = None,
- ) -> None:
- self._host = host
- self._port = port
- self._client_id = client_id
- self._username = username
- self._password = password
- self._will = will
- self._ca_cert_path = ca_cert_path
- self._client: aiomqtt.Client | None = None
-
- async def connect(self) -> None:
- tls_params = (
- aiomqtt.TLSParameters(ca_certs=self._ca_cert_path) if self._ca_cert_path else None
- )
- self._client = aiomqtt.Client(
- hostname=self._host,
- port=self._port,
- identifier=self._client_id,
- username=self._username,
- password=self._password,
- will=self._will,
- tls_params=tls_params,
- )
- await self._client.__aenter__()
-
- async def disconnect(self) -> None:
- if self._client is not None:
- await self._client.__aexit__(None, None, None)
- self._client = None
-
- def is_connected(self) -> bool:
- """Return True once :meth:`connect` has constructed the underlying client.
-
- Note: this is a coarse "ready to attempt publishing" gate, not a live
- link check — aiomqtt does not surface broker reachability synchronously.
- A True return indicates the emitter may issue publishes; transport
- failures will surface as exceptions from :meth:`publish` / :meth:`subscribe`."""
- return self._client is not None
-
- async def publish(
- self,
- topic: str,
- payload: bytes,
- qos: int = 0,
- retain: bool = False,
- ) -> None:
- assert self._client is not None
- await self._client.publish(topic, payload=payload, qos=qos, retain=retain)
-
- async def subscribe(self, topic: str) -> None:
- assert self._client is not None
- await self._client.subscribe(topic)
-
-
def bess_config_from_engine(engine: DynamicSimulationEngine) -> BESSConfig | None:
"""Build the emitter-side BESSConfig from the engine's loaded clone profile.
Returns None when the profile has no BESS enabled."""
@@ -257,11 +173,11 @@ async def start_clone(
# defaults match what the SDK's own client applies to the same descriptor.
lwt = Emitter.lwt_settings(manifest)
- mqtt: MqttPublisher | None = None
+ link: BrokerLink | None = None
if transport is None:
broker_cfg: BrokerConfigYAML = engine.config.get("broker") or {}
resolved = _resolve_broker(broker_cfg, broker)
- aiomqtt_publisher = _AiomqttPublisher(
+ link = BrokerLink(
host=resolved.host,
port=resolved.port,
client_id=f"span-sim-{engine.serial_number}",
@@ -275,17 +191,31 @@ async def start_clone(
),
ca_cert_path=resolved.ca_cert_path,
)
- await aiomqtt_publisher.connect()
- mqtt = aiomqtt_publisher
+ await link.connect()
loop_bound = LoopBoundTransport(
- publish=aiomqtt_publisher.publish,
- subscribe=aiomqtt_publisher.subscribe,
- connected=aiomqtt_publisher.is_connected,
+ publish=link.publish,
+ subscribe=link.subscribe,
+ connected=link.is_connected,
)
loop_bound.start()
transport = loop_bound
- emitter = Emitter.from_definition(definition, setters, mqttc=transport)
+ try:
+ emitter = Emitter.from_definition(definition, setters, mqttc=transport)
+ except BaseException:
+ # The link supervises itself, so one left open here would keep reconnecting
+ # for a panel that never started.
+ if link is not None:
+ if isinstance(transport, LoopBoundTransport):
+ await transport.aclose()
+ await link.disconnect()
+ raise
+ if link is not None:
+ # Built after the link because constructing it publishes the tree. The SDK
+ # wires this itself only for a client it builds, and leaves it to whoever
+ # injects one (`Emitter.republish_tree`): without it, a broker that comes
+ # back empty gets a few topics a tick and never a `$description`.
+ link.on_reconnect(emitter.republish_tree)
runtime = CloneRuntime(
engine=engine,
@@ -294,7 +224,7 @@ async def start_clone(
transport=transport,
emitter=emitter,
uuid_to_circuit_id=uuid_to_circuit_id,
- mqtt=mqtt,
+ mqtt=link,
)
# Synchronous, and returns immediately for an injected client rather than
diff --git a/src/panelbench/emitter_adapter/transport.py b/src/panelbench/emitter_adapter/transport.py
index f54a438..8bcec99 100644
--- a/src/panelbench/emitter_adapter/transport.py
+++ b/src/panelbench/emitter_adapter/transport.py
@@ -24,19 +24,34 @@
preserves that, so the choice surfaces here as a bounded queue: a producer that
outruns its broker fails loudly at a stated depth instead of growing the heap
until the add-on is killed.
+
+**A subscription is a filter and a callback.** The SDK subscribes each settable
+property's ``/set`` topic with the callback that applies a command to it, and
+expects whatever carries the filter to call that callback with the topic and
+payload of each message on it, as ``ebus_mqtt_client.MqttClient`` does. Both go
+through the queue together, so the client behind it can route what arrives.
"""
from __future__ import annotations
import asyncio
import logging
-from typing import TYPE_CHECKING, Any
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
if TYPE_CHECKING:
- from collections.abc import Awaitable, Callable
+ from collections.abc import Awaitable
_LOG = logging.getLogger(__name__)
+MessageCallback = Callable[[str, bytes], object]
+"""What the SDK subscribes with: called with a message's topic and payload.
+
+The contract ``ebus_mqtt_client.MqttClient`` keeps and ``Property._settable_callback``
+is written against. The return is discarded, which is why it is ``object``.
+"""
+
# One tick of a 40-space panel publishes on the order of 500 topics, and the
# cold-start tree is larger still. This holds several ticks' worth so a transient
# broker stall is absorbed, while staying small enough that a producer looping
@@ -48,6 +63,31 @@ class TransportBacklogFull(RuntimeError):
"""The publish queue hit its bound: the producer is outrunning the broker."""
+class BrokerUnavailable(ConnectionError):
+ """The broker link is down, so the operation was not sent.
+
+ Raised by the client behind this transport rather than by the transport, and
+ dropped quietly when it reaches the drainer: the client reports an outage once,
+ and what an outage drops is restored when the link comes back, since the
+ subscriptions are replayed and the tree republished.
+ """
+
+
+@dataclass(frozen=True, slots=True)
+class _Publish:
+ topic: str
+ payload: bytes
+ qos: int
+ retain: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _Subscribe:
+ topic_filter: str
+ callback: MessageCallback
+ qos: int
+
+
class LoopBoundTransport:
"""Satisfies ``ebus_sdk.MqttDeviceTransport`` on top of an async MQTT client.
@@ -65,16 +105,14 @@ def __init__(
self,
*,
publish: Callable[[str, bytes, int, bool], Awaitable[None]],
- subscribe: Callable[[str], Awaitable[None]],
+ subscribe: Callable[[str, MessageCallback, int], Awaitable[None]],
connected: Callable[[], bool],
max_pending: int = DEFAULT_MAX_PENDING,
) -> None:
self._publish = publish
self._subscribe = subscribe
self._connected = connected
- self._queue: asyncio.Queue[tuple[str, bytes, int, bool] | str] = asyncio.Queue(
- maxsize=max_pending
- )
+ self._queue: asyncio.Queue[_Publish | _Subscribe] = asyncio.Queue(maxsize=max_pending)
self._drainer: asyncio.Task[None] | None = None
self.is_running = False
@@ -112,17 +150,17 @@ def is_connected(self) -> bool:
return self._connected()
def publish(self, topic: str, data: str, qos: int = 1, retain: bool = False) -> object:
- self._submit((topic, str(data).encode(), qos, retain))
+ self._submit(_Publish(topic, str(data).encode(), qos, retain))
return None
- def subscribe(self, sub: str, param: Any = None, qos: int = 1) -> object:
- del param, qos # routing is the SDK's; this transport only carries the filter
- self._submit(sub)
+ def subscribe(self, sub: str, param: MessageCallback, qos: int = 1) -> object:
+ """``param`` is the SDK's name for the callback, kept so it can pass it by name."""
+ self._submit(_Subscribe(sub, param, qos))
return None
# -- internals --------------------------------------------------------------
- def _submit(self, item: tuple[str, bytes, int, bool] | str) -> None:
+ def _submit(self, item: _Publish | _Subscribe) -> None:
try:
self._queue.put_nowait(item)
except asyncio.QueueFull as exc:
@@ -135,11 +173,14 @@ async def _drain(self) -> None:
while True:
item = await self._queue.get()
try:
- if isinstance(item, str):
- await self._subscribe(item)
+ if isinstance(item, _Subscribe):
+ await self._subscribe(item.topic_filter, item.callback, item.qos)
else:
- topic, payload, qos, retain = item
- await self._publish(topic, payload, qos, retain)
+ await self._publish(item.topic, item.payload, item.qos, item.retain)
+ except BrokerUnavailable:
+ # Already reported, once, by the link. Logging every casualty would
+ # bury that line under one per topic per tick.
+ _LOG.debug("dropping an MQTT operation: the broker link is down")
except Exception:
# One failed publish must not kill the drainer: the SDK has already
# been told the value went out and will not resend it, so a dead
diff --git a/tests/_helpers.py b/tests/_helpers.py
index 505510f..7669e3f 100644
--- a/tests/_helpers.py
+++ b/tests/_helpers.py
@@ -8,6 +8,7 @@
from __future__ import annotations
+import asyncio
import copy
from datetime import datetime
from pathlib import Path
@@ -15,6 +16,7 @@
from zoneinfo import ZoneInfo
import yaml
+from ebus_panel_sim.relay_resolver import RelayRequester, RelayState
from panelbench.clone import TYPE_PV, translate_panel_tree
from panelbench.emitter_adapter import runtime as emitter_runtime
@@ -123,3 +125,21 @@ async def pv_rating(path: Path, circuit_id: str = "solar_inverter") -> tuple[str
produced = runtime.engine.modelled_circuit_power(circuit_id, NOON)
assert produced > 0, "noon in June, so the inverter is producing"
return pv.get_property("info", "nominal-power"), produced
+
+
+def settable_relays(runtime: CloneRuntime) -> list[str]:
+ """Circuits a relay command may move: every one not locked by commissioning."""
+ return [
+ uuid
+ for uuid in runtime.uuid_to_circuit_id
+ if runtime.emitter.relays.state(uuid)[1] != RelayRequester.CONFIGURATION
+ ]
+
+
+async def relay_opened_by_command(
+ runtime: CloneRuntime, uuid: str, *, within: float = 2.0
+) -> None:
+ """Wait until circuit *uuid*'s relay is open on a user's command."""
+ async with asyncio.timeout(within):
+ while runtime.emitter.relays.state(uuid) != (RelayState.OPEN, RelayRequester.USER):
+ await asyncio.sleep(0.005)
diff --git a/tests/emitter_adapter/_fake_aiomqtt.py b/tests/emitter_adapter/_fake_aiomqtt.py
new file mode 100644
index 0000000..a430202
--- /dev/null
+++ b/tests/emitter_adapter/_fake_aiomqtt.py
@@ -0,0 +1,144 @@
+"""A stand-in for ``aiomqtt.Client``, with a broker behind it that a test can take away.
+
+Installed in place of ``aiomqtt.Client`` (``FakeBroker.install``), so the code under
+test builds its clients exactly as it would against a real broker. Each client
+records what it was asked to do in one ordered log, because the order is most of
+what these tests assert: subscriptions restored before the tree is republished,
+nothing published on a client that has been closed.
+
+A severed client behaves the way aiomqtt does when its socket drops: message
+iteration raises ``MqttError``, and so does any later publish or subscribe.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, ClassVar
+
+import aiomqtt
+import pytest
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator
+
+
+class FakeClient:
+ """One connection attempt, successful or not, and everything done on it."""
+
+ broker: ClassVar[FakeBroker]
+
+ def __init__(self, **kwargs: object) -> None:
+ self.kwargs = kwargs
+ self.log: list[tuple[str, str]] = []
+ self.published: list[tuple[str, bytes, int, bool]] = []
+ self.subscribed: list[tuple[str, int]] = []
+ self.entered = False
+ self.exited = False
+ self.severed = False
+ self._lost = asyncio.Event()
+ self._inbox: asyncio.Queue[aiomqtt.Message] = asyncio.Queue()
+ self.broker.clients.append(self)
+
+ @property
+ def connected(self) -> bool:
+ return self.entered and not self.exited and not self.severed
+
+ async def __aenter__(self) -> FakeClient:
+ if not self.broker.up:
+ raise aiomqtt.MqttError("[Errno 61] Connection refused")
+ self.entered = True
+ if self.broker.drop_on_connect:
+ self.sever()
+ return self
+
+ async def __aexit__(self, *exc: object) -> None:
+ self.exited = True
+
+ async def publish(
+ self, topic: str, payload: bytes | None = None, qos: int = 0, retain: bool = False
+ ) -> None:
+ if self.exited:
+ raise AssertionError(f"published {topic!r} after the client was closed")
+ if self.severed:
+ raise aiomqtt.MqttError("Could not publish message")
+ if self.broker.hang_publishes:
+ # A QoS 1 publish whose PUBACK never comes, because the socket died
+ # under it. aiomqtt waits out its own timeout; this waits forever.
+ await asyncio.Event().wait()
+ self.published.append((topic, payload or b"", qos, retain))
+ self.log.append(("publish", topic))
+
+ async def subscribe(self, topic: str, qos: int = 0) -> None:
+ if self.severed:
+ raise aiomqtt.MqttError("Could not subscribe to topic")
+ self.subscribed.append((topic, qos))
+ self.log.append(("subscribe", topic))
+
+ @property
+ def messages(self) -> AsyncIterator[aiomqtt.Message]:
+ return self._iterate()
+
+ async def _iterate(self) -> AsyncIterator[aiomqtt.Message]:
+ while True:
+ arrival = asyncio.ensure_future(self._inbox.get())
+ loss = asyncio.ensure_future(self._lost.wait())
+ try:
+ done, _ = await asyncio.wait({arrival, loss}, return_when=asyncio.FIRST_COMPLETED)
+ finally:
+ arrival.cancel()
+ loss.cancel()
+ if arrival in done:
+ yield arrival.result()
+ else:
+ raise aiomqtt.MqttError("Disconnected during message iteration")
+
+ def sever(self) -> None:
+ self.severed = True
+ self._lost.set()
+
+ def receive(self, topic: str, payload: bytes) -> None:
+ self._inbox.put_nowait(aiomqtt.Message(topic, payload, 1, False, 0, None))
+
+
+class FakeBroker:
+ """Whether the broker is reachable, and every client that tried to reach it."""
+
+ def __init__(self) -> None:
+ self.up = True
+ self.hang_publishes = False
+ # Accept each connection, then drop it at once: what a broker does to a
+ # client whose id another client has just taken over.
+ self.drop_on_connect = False
+ self.clients: list[FakeClient] = []
+
+ def install(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ FakeClient.broker = self
+ monkeypatch.setattr(aiomqtt, "Client", FakeClient)
+
+ @property
+ def live(self) -> FakeClient | None:
+ connected = [c for c in self.clients if c.connected]
+ return connected[-1] if connected else None
+
+ def go_down(self) -> None:
+ self.up = False
+ for client in self.clients:
+ if client.connected:
+ client.sever()
+
+ def come_up(self) -> None:
+ self.up = True
+
+ def send(self, topic: str, payload: bytes) -> None:
+ """Route a message to each connected client subscribed to a matching filter."""
+ delivered = aiomqtt.Topic(topic)
+ for client in self.clients:
+ if client.connected and any(delivered.matches(f) for f, _ in client.subscribed):
+ client.receive(topic, payload)
+
+ async def wait_for_live(self, *, after: FakeClient | None = None) -> FakeClient:
+ """The next connected client, other than *after*."""
+ async with asyncio.timeout(5):
+ while (client := self.live) is None or client is after:
+ await asyncio.sleep(0.005)
+ return client
diff --git a/tests/emitter_adapter/conftest.py b/tests/emitter_adapter/conftest.py
new file mode 100644
index 0000000..a3d0ac8
--- /dev/null
+++ b/tests/emitter_adapter/conftest.py
@@ -0,0 +1,15 @@
+"""Fixtures shared by the emitter adapter's tests."""
+
+from __future__ import annotations
+
+import pytest
+
+from tests.emitter_adapter._fake_aiomqtt import FakeBroker
+
+
+@pytest.fixture
+def fake_broker(monkeypatch: pytest.MonkeyPatch) -> FakeBroker:
+ """A broker the test can take away, behind every ``aiomqtt.Client`` built."""
+ broker = FakeBroker()
+ broker.install(monkeypatch)
+ return broker
diff --git a/tests/emitter_adapter/test_broker_link.py b/tests/emitter_adapter/test_broker_link.py
new file mode 100644
index 0000000..d64eee0
--- /dev/null
+++ b/tests/emitter_adapter/test_broker_link.py
@@ -0,0 +1,359 @@
+"""The broker connection: inbound messages, and a link that outlives its broker.
+
+aiomqtt 2.x neither reconnects nor routes messages: a client is one connection,
+and what arrives on it waits in ``client.messages`` until something reads it.
+``BrokerLink`` supplies both, and these tests hold it to the contract the SDK's own
+``MqttClient`` keeps for a client it builds: every subscription restored on
+reconnect, then the on-connect hook, and each message handed to the callback its
+filter was subscribed with.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+import aiomqtt
+import pytest
+
+from panelbench.emitter_adapter.broker_link import BrokerLink, _Backoff
+from panelbench.emitter_adapter.transport import BrokerUnavailable, LoopBoundTransport
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+ from tests.emitter_adapter._fake_aiomqtt import FakeBroker
+
+RELAY_SETS = "ebus/5/+/switch/relay/set"
+PRIORITY_SET = "ebus/5/dev-1/load-shed/priority/set"
+
+
+class Inbox:
+ """A message callback that keeps what it was handed."""
+
+ def __init__(self) -> None:
+ self.received: list[tuple[str, bytes]] = []
+
+ def __call__(self, topic: str, payload: bytes) -> None:
+ self.received.append((topic, payload))
+
+
+async def eventually(condition: Callable[[], object], *, within: float = 2.0) -> None:
+ async with asyncio.timeout(within):
+ while not condition():
+ await asyncio.sleep(0.005)
+
+
+async def connected_link(*, max_reconnect_delay: float = 0.05) -> BrokerLink:
+ link = BrokerLink(
+ host="broker.invalid",
+ port=1883,
+ client_id="span-sim-test",
+ min_reconnect_delay=0.01,
+ max_reconnect_delay=max_reconnect_delay,
+ )
+ await link.connect()
+ return link
+
+
+async def outage(broker: FakeBroker, link: BrokerLink) -> None:
+ """Take the broker away and wait until the link has noticed."""
+ broker.go_down()
+ await eventually(lambda: not link.is_connected())
+
+
+def supervisors() -> list[asyncio.Task[object]]:
+ return [t for t in asyncio.all_tasks() if t.get_name().startswith("mqtt-link")]
+
+
+# -- inbound messages ---------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_a_message_reaches_the_callback_its_filter_was_subscribed_with(
+ fake_broker: FakeBroker,
+) -> None:
+ """The defect: HA published `switch/relay/set OPEN` and nothing acted on it."""
+ link = await connected_link()
+ relays, priority = Inbox(), Inbox()
+ await link.subscribe(RELAY_SETS, relays, 1)
+ await link.subscribe(PRIORITY_SET, priority, 1)
+
+ fake_broker.send("ebus/5/dev-1/switch/relay/set", b"OPEN")
+ fake_broker.send("ebus/5/dev-1/load-shed/priority/set", b"OFF_GRID")
+ await eventually(lambda: relays.received and priority.received)
+
+ assert relays.received == [("ebus/5/dev-1/switch/relay/set", b"OPEN")]
+ assert priority.received == [("ebus/5/dev-1/load-shed/priority/set", b"OFF_GRID")]
+ assert fake_broker.live is not None
+ assert fake_broker.live.subscribed == [(RELAY_SETS, 1), (PRIORITY_SET, 1)]
+ await link.disconnect()
+
+
+@pytest.mark.asyncio
+async def test_a_raising_callback_does_not_stop_the_next_message(
+ fake_broker: FakeBroker,
+) -> None:
+ """Callbacks run on the link's reader; one that raises must not end it."""
+ link = await connected_link()
+ inbox = Inbox()
+
+ def explode(topic: str, payload: bytes) -> None:
+ raise ValueError("a handler bug")
+
+ await link.subscribe("ebus/5/dev-1/switch/relay/set", explode, 1)
+ await link.subscribe("ebus/5/dev-2/switch/relay/set", inbox, 1)
+
+ fake_broker.send("ebus/5/dev-1/switch/relay/set", b"OPEN")
+ fake_broker.send("ebus/5/dev-2/switch/relay/set", b"OPEN")
+ await eventually(lambda: inbox.received)
+
+ assert inbox.received == [("ebus/5/dev-2/switch/relay/set", b"OPEN")]
+ await link.disconnect()
+
+
+# -- surviving the broker -----------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_is_connected_follows_the_live_link(fake_broker: FakeBroker) -> None:
+ link = await connected_link()
+ assert link.is_connected()
+
+ await outage(fake_broker, link)
+ fake_broker.come_up()
+ await eventually(link.is_connected)
+
+ await link.disconnect()
+ assert not link.is_connected()
+
+
+@pytest.mark.asyncio
+async def test_a_reconnect_restores_every_subscription_before_running_the_hook(
+ fake_broker: FakeBroker,
+) -> None:
+ """The hook is `Emitter.republish_tree`. A tree announced before its `/set`
+ filters are back invites a command that nothing is listening for."""
+ link = await connected_link()
+ restored_at_hook: list[list[tuple[str, int]]] = []
+ link.on_reconnect(lambda: restored_at_hook.append(list(fake_broker.clients[-1].subscribed)))
+ await link.subscribe(RELAY_SETS, Inbox(), 1)
+ await link.subscribe(PRIORITY_SET, Inbox(), 0)
+ first = fake_broker.live
+
+ await outage(fake_broker, link)
+ assert restored_at_hook == [], "the hook ran without a reconnect"
+ fake_broker.come_up()
+ await fake_broker.wait_for_live(after=first)
+ await eventually(lambda: restored_at_hook)
+
+ assert restored_at_hook == [[(RELAY_SETS, 1), (PRIORITY_SET, 0)]]
+ await link.disconnect()
+
+
+@pytest.mark.asyncio
+async def test_a_command_after_a_reconnect_reaches_its_callback(
+ fake_broker: FakeBroker,
+) -> None:
+ link = await connected_link()
+ inbox = Inbox()
+ await link.subscribe(RELAY_SETS, inbox, 1)
+
+ first = fake_broker.live
+ await outage(fake_broker, link)
+ fake_broker.come_up()
+ await fake_broker.wait_for_live(after=first)
+ await eventually(lambda: fake_broker.live is not None and fake_broker.live.subscribed)
+ fake_broker.send("ebus/5/dev-1/switch/relay/set", b"OPEN")
+ await eventually(lambda: inbox.received)
+
+ assert inbox.received == [("ebus/5/dev-1/switch/relay/set", b"OPEN")]
+ await link.disconnect()
+
+
+@pytest.mark.asyncio
+async def test_a_subscription_made_during_an_outage_is_restored(
+ fake_broker: FakeBroker,
+) -> None:
+ """The SDK subscribes once and never again, so a filter the outage swallowed
+ has to come back with the link or it is gone for good."""
+ link = await connected_link()
+ inbox = Inbox()
+ first = fake_broker.live
+
+ await outage(fake_broker, link)
+ with pytest.raises(BrokerUnavailable):
+ await link.subscribe(RELAY_SETS, inbox, 1)
+ fake_broker.come_up()
+ await fake_broker.wait_for_live(after=first)
+ await eventually(lambda: fake_broker.live is not None and fake_broker.live.subscribed)
+ fake_broker.send("ebus/5/dev-1/switch/relay/set", b"OPEN")
+ await eventually(lambda: inbox.received)
+
+ assert inbox.received == [("ebus/5/dev-1/switch/relay/set", b"OPEN")]
+ await link.disconnect()
+
+
+@pytest.mark.asyncio
+async def test_publishing_without_a_broker_says_so(fake_broker: FakeBroker) -> None:
+ link = await connected_link()
+ await outage(fake_broker, link)
+
+ with pytest.raises(BrokerUnavailable):
+ await link.publish("ebus/5/dev-1/$state", b"ready", 1, True)
+
+ await link.disconnect()
+
+
+@pytest.mark.asyncio
+async def test_a_publish_in_flight_when_the_link_drops_is_abandoned(
+ fake_broker: FakeBroker,
+) -> None:
+ """A QoS 1 publish whose socket dies waits for a PUBACK that never comes —
+ aiomqtt's timeout, ten seconds by default. The drainer is single-file, so for
+ those seconds nothing else moves, the republished tree included."""
+ link = await connected_link()
+ fake_broker.hang_publishes = True
+ in_flight = asyncio.create_task(link.publish("ebus/5/dev-1/$state", b"ready", 1, True))
+ await asyncio.sleep(0.01)
+
+ fake_broker.go_down()
+
+ with pytest.raises(BrokerUnavailable):
+ await asyncio.wait_for(in_flight, timeout=1.0)
+ await link.disconnect()
+
+
+@pytest.mark.asyncio
+async def test_an_outage_is_reported_once_and_without_a_traceback(
+ fake_broker: FakeBroker, caplog: pytest.LogCaptureFixture
+) -> None:
+ """Every tick publishes hundreds of topics. Logging each casualty, with a
+ traceback, is what buried the one line that said the broker had gone."""
+ caplog.set_level(logging.DEBUG)
+ link = await connected_link()
+ transport = LoopBoundTransport(
+ publish=link.publish, subscribe=link.subscribe, connected=link.is_connected
+ )
+ transport.start()
+
+ def warnings() -> list[logging.LogRecord]:
+ return [r for r in caplog.records if r.levelno >= logging.WARNING]
+
+ for outage_number in (1, 2):
+ live = fake_broker.live
+ fake_broker.go_down()
+ # Submitted the instant the socket dies, so the drainer can meet the dead
+ # client before the reader does: either may notice first, and only one
+ # of them may say so.
+ for i in range(50):
+ transport.publish(f"ebus/5/dev-1/node/p{i}", str(i))
+ await transport.drain()
+ await eventually(lambda: not link.is_connected())
+ await asyncio.sleep(0.1) # several refused reconnects
+
+ assert len(warnings()) == outage_number, [r.getMessage() for r in warnings()]
+ assert all(r.exc_info is None for r in warnings())
+
+ fake_broker.come_up()
+ await fake_broker.wait_for_live(after=live)
+
+ await transport.aclose()
+ await link.disconnect()
+
+
+# -- lifecycle ----------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_disconnect_closes_the_client_and_stops_the_supervisor(
+ fake_broker: FakeBroker,
+) -> None:
+ link = await connected_link()
+ client = fake_broker.live
+ assert client is not None and supervisors()
+
+ await link.disconnect()
+
+ assert client.exited
+ assert not supervisors()
+
+
+@pytest.mark.asyncio
+async def test_disconnect_during_an_outage_stops_the_retries(fake_broker: FakeBroker) -> None:
+ link = await connected_link()
+ await outage(fake_broker, link)
+
+ await link.disconnect()
+ attempts = len(fake_broker.clients)
+ fake_broker.come_up()
+ await asyncio.sleep(0.1)
+
+ assert not supervisors()
+ assert len(fake_broker.clients) == attempts, "the link kept reconnecting after disconnect"
+
+
+@pytest.mark.asyncio
+async def test_a_broker_down_at_start_fails_the_connect(fake_broker: FakeBroker) -> None:
+ """Start-up still fails loudly, as it did before the link supervised itself:
+ a panel that cannot reach its broker at all is a configuration error."""
+ fake_broker.up = False
+ link = BrokerLink(host="broker.invalid", port=1883, client_id="span-sim-test")
+
+ with pytest.raises(aiomqtt.MqttError):
+ async with asyncio.timeout(2): # retrying the first connection would hang here
+ await link.connect()
+
+ assert not supervisors()
+ assert not link.is_connected()
+
+
+@pytest.mark.asyncio
+async def test_a_link_that_drops_as_soon_as_it_connects_backs_off(
+ fake_broker: FakeBroker,
+) -> None:
+ """Resetting the delay on every connection would retry a broker that takes
+ the panel's client id away each time at the floor, forever, with a warning
+ for each. The delay resets only once a connection has outlasted the ceiling."""
+ link = await connected_link() # delays double from 0.01s to 0.05s
+ fake_broker.drop_on_connect = True
+ fake_broker.go_down()
+ fake_broker.come_up()
+ attempts = len(fake_broker.clients)
+
+ await asyncio.sleep(0.5)
+
+ # At the ceiling, 0.5s holds about ten attempts; at the floor, about fifty.
+ assert len(fake_broker.clients) - attempts < 20
+ await link.disconnect()
+
+
+@pytest.mark.asyncio
+async def test_a_link_that_held_reconnects_promptly_after_its_next_drop(
+ fake_broker: FakeBroker,
+) -> None:
+ """The other half: a connection that outlasted the ceiling was a real one, so
+ the next outage starts again from the floor, not from where the last left off."""
+ link = await connected_link(max_reconnect_delay=1.0)
+ await outage(fake_broker, link)
+ await asyncio.sleep(0.7) # refused at 0.01s, 0.02s, ... 0.32s: next wait 0.64s
+ fake_broker.come_up()
+ await eventually(link.is_connected, within=2.0)
+ await asyncio.sleep(1.1) # outlasts the ceiling
+
+ await outage(fake_broker, link)
+ fake_broker.come_up()
+
+ await eventually(link.is_connected, within=0.5) # the ceiling would be 1.0s
+ await link.disconnect()
+
+
+def test_the_reconnect_delay_doubles_to_its_ceiling_and_resets() -> None:
+ backoff = _Backoff(first=1.0, ceiling=30.0)
+
+ delays = [backoff.next_delay() for _ in range(7)]
+ backoff.reset()
+
+ assert delays == [1.0, 2.0, 4.0, 8.0, 16.0, 30.0, 30.0]
+ assert backoff.next_delay() == 1.0
diff --git a/tests/emitter_adapter/test_runtime_transport_path.py b/tests/emitter_adapter/test_runtime_transport_path.py
index 715dabf..ed63e92 100644
--- a/tests/emitter_adapter/test_runtime_transport_path.py
+++ b/tests/emitter_adapter/test_runtime_transport_path.py
@@ -9,53 +9,22 @@
from __future__ import annotations
+import asyncio
import pathlib
-from typing import Any, ClassVar
+from typing import TYPE_CHECKING
import pytest
from panelbench.emitter_adapter import runtime as emitter_runtime
from panelbench.emitter_adapter.transport import LoopBoundTransport
from panelbench.engine import DynamicSimulationEngine
+from tests._helpers import relay_opened_by_command, settable_relays
-_CONFIG = pathlib.Path(__file__).resolve().parents[2] / "configs" / "default_MAIN_40.yaml"
-
-
-class FakeBrokerClient:
- """Enough of ``aiomqtt.Client`` for the path under test, recording order."""
-
- instances: ClassVar[list[FakeBrokerClient]] = []
-
- def __init__(self, **kwargs: Any) -> None:
- self.kwargs = kwargs
- self.published: list[tuple[str, bytes, int, bool]] = []
- self.entered = False
- self.exited = False
- FakeBrokerClient.instances.append(self)
-
- async def __aenter__(self) -> FakeBrokerClient:
- self.entered = True
- return self
-
- async def __aexit__(self, *exc: object) -> None:
- self.exited = True
-
- async def publish(
- self, topic: str, payload: bytes, qos: int = 0, retain: bool = False
- ) -> None:
- if self.exited:
- raise AssertionError(f"published {topic!r} after the client was closed")
- self.published.append((topic, payload, qos, retain))
-
- async def subscribe(self, topic: str) -> None:
- return None
+if TYPE_CHECKING:
+ from tests.emitter_adapter._fake_aiomqtt import FakeBroker, FakeClient
-
-@pytest.fixture
-def fake_broker(monkeypatch: pytest.MonkeyPatch) -> type[FakeBrokerClient]:
- FakeBrokerClient.instances = []
- monkeypatch.setattr(emitter_runtime.aiomqtt, "Client", FakeBrokerClient)
- return FakeBrokerClient
+_CONFIG = pathlib.Path(__file__).resolve().parents[2] / "configs" / "default_MAIN_40.yaml"
+_ROOT = "ebus/5/sim-40t-001"
async def _started(config: pathlib.Path) -> emitter_runtime.CloneRuntime:
@@ -66,7 +35,7 @@ async def _started(config: pathlib.Path) -> emitter_runtime.CloneRuntime:
@pytest.mark.asyncio
async def test_the_tree_reaches_the_broker_through_the_queue(
- fake_broker: type[FakeBrokerClient],
+ fake_broker: FakeBroker,
) -> None:
"""The whole point: a synchronous SDK publish path feeding an async client."""
runtime = await _started(_CONFIG)
@@ -74,7 +43,7 @@ async def test_the_tree_reaches_the_broker_through_the_queue(
await emitter_runtime.publish_tick(runtime)
await runtime.transport.drain()
- client = fake_broker.instances[0]
+ client = fake_broker.clients[0]
topics = [t for t, _, _, _ in client.published]
assert client.entered
@@ -87,7 +56,7 @@ async def test_the_tree_reaches_the_broker_through_the_queue(
@pytest.mark.asyncio
async def test_each_device_describes_itself_before_it_announces_ready(
- fake_broker: type[FakeBrokerClient],
+ fake_broker: FakeBroker,
) -> None:
"""The ordering guarantee, asserted where it actually matters.
@@ -96,9 +65,10 @@ async def test_each_device_describes_itself_before_it_announces_ready(
order; this proves the order submitted is the one Homie requires.
"""
runtime = await _started(_CONFIG)
- await runtime.transport.drain() # type: ignore[union-attr]
+ assert isinstance(runtime.transport, LoopBoundTransport)
+ await runtime.transport.drain()
- client = fake_broker.instances[0]
+ client = fake_broker.clients[0]
seen_ready: set[str] = set()
described: set[str] = set()
for topic, payload, _qos, _retain in client.published:
@@ -116,7 +86,7 @@ async def test_each_device_describes_itself_before_it_announces_ready(
@pytest.mark.asyncio
async def test_teardown_drains_before_closing_the_client(
- fake_broker: type[FakeBrokerClient],
+ fake_broker: FakeBroker,
) -> None:
"""`stop` queues the root's final state and cannot flush it — the SDK's
publish path is synchronous and the client behind it is not. Closing first
@@ -128,14 +98,67 @@ async def test_teardown_drains_before_closing_the_client(
await emitter_runtime.stop_clone(runtime, graceful=True)
- client = fake_broker.instances[0]
+ client = fake_broker.clients[0]
assert client.exited, "the client was never closed"
root_states = [
- payload
- for topic, payload, _q, _r in client.published
- if topic == "ebus/5/sim-40t-001/$state"
+ payload for topic, payload, _q, _r in client.published if topic == f"{_ROOT}/$state"
]
assert root_states, "the root never published a state"
assert root_states[-1] != b"ready", (
f"the retained root state after teardown is {root_states[-1]!r}"
)
+
+
+@pytest.mark.asyncio
+async def test_a_relay_command_from_home_assistant_reaches_the_emitter(
+ fake_broker: FakeBroker,
+) -> None:
+ """The defect, end to end: HA published `/switch/relay/set OPEN` and
+ PanelBench subscribed to it, then never read the message."""
+ runtime = await _started(_CONFIG)
+ assert isinstance(runtime.transport, LoopBoundTransport)
+ await runtime.transport.drain()
+ circuit = settable_relays(runtime)[0]
+
+ fake_broker.send(f"ebus/5/{circuit}/switch/relay/set", b"OPEN")
+
+ await relay_opened_by_command(runtime, circuit)
+ await emitter_runtime.stop_clone(runtime)
+
+
+@pytest.mark.asyncio
+async def test_a_reconnect_restores_the_subscriptions_then_republishes_the_tree(
+ fake_broker: FakeBroker,
+) -> None:
+ """What the SDK does for a client it builds, and leaves to the caller for an
+ injected one: re-subscribe, then `republish_tree`. A broker that restarted
+ without persistence holds nothing until the tree is announced again."""
+ runtime = await _started(_CONFIG)
+ assert isinstance(runtime.transport, LoopBoundTransport)
+ await runtime.transport.drain()
+ first = fake_broker.clients[0]
+ filters = [f for f, _ in first.subscribed]
+
+ fake_broker.go_down()
+ fake_broker.come_up()
+ second = await fake_broker.wait_for_live(after=first)
+ await _republished(second)
+
+ assert [f for f, _ in second.subscribed] == filters
+ last_subscribe = max(i for i, (kind, _) in enumerate(second.log) if kind == "subscribe")
+ first_publish = min(i for i, (kind, _) in enumerate(second.log) if kind == "publish")
+ assert last_subscribe < first_publish, "the tree went out before its subscriptions"
+ published = {topic for topic, _, _, _ in second.published}
+ assert f"{_ROOT}/$description" in published
+ assert f"{_ROOT}/$state" in published
+
+ circuit = settable_relays(runtime)[0]
+ fake_broker.send(f"ebus/5/{circuit}/switch/relay/set", b"OPEN")
+ await relay_opened_by_command(runtime, circuit)
+ await emitter_runtime.stop_clone(runtime)
+
+
+async def _republished(client: FakeClient) -> None:
+ async with asyncio.timeout(2):
+ while not any(t.endswith("/$state") and p == b"ready" for t, p, _, _ in client.published):
+ await asyncio.sleep(0.005)
diff --git a/tests/emitter_adapter/test_transport.py b/tests/emitter_adapter/test_transport.py
index eaed219..048ed4c 100644
--- a/tests/emitter_adapter/test_transport.py
+++ b/tests/emitter_adapter/test_transport.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import asyncio
+import logging
import pathlib
import pytest
@@ -11,7 +12,9 @@
from panelbench.emitter_adapter.spec_generator import build_manifest
from panelbench.emitter_adapter.transport import (
+ BrokerUnavailable,
LoopBoundTransport,
+ MessageCallback,
TransportBacklogFull,
)
@@ -23,7 +26,7 @@ class Recorder:
def __init__(self, delay_first: float = 0.0) -> None:
self.published: list[tuple[str, bytes, int, bool]] = []
- self.subscribed: list[str] = []
+ self.subscribed: list[tuple[str, MessageCallback, int]] = []
self.failures = 0
self._delay_first = delay_first
@@ -34,8 +37,8 @@ async def publish(self, topic: str, payload: bytes, qos: int, retain: bool) -> N
await asyncio.sleep(self._delay_first)
self.published.append((topic, payload, qos, retain))
- async def subscribe(self, topic: str) -> None:
- self.subscribed.append(topic)
+ async def subscribe(self, topic: str, callback: MessageCallback, qos: int) -> None:
+ self.subscribed.append((topic, callback, qos))
def is_connected(self) -> bool:
return True
@@ -50,6 +53,10 @@ def _transport(recorder: Recorder, **kwargs: object) -> LoopBoundTransport:
)
+def _ignore(topic: str, payload: bytes) -> None:
+ del topic, payload
+
+
@pytest.mark.asyncio
async def test_it_satisfies_the_protocol_the_sdk_type_checks_against() -> None:
"""The claim the whole adapter rests on, asserted against the real protocol.
@@ -193,7 +200,56 @@ async def test_subscriptions_go_through_the_same_queue_as_publishes() -> None:
transport.start()
transport.publish("ebus/5/dev/node/p", "1")
- transport.subscribe("ebus/5/dev/node/p/set")
+ transport.subscribe("ebus/5/dev/node/p/set", _ignore)
+ await transport.drain()
+
+ assert recorder.published
+ assert [topic for topic, _, _ in recorder.subscribed] == ["ebus/5/dev/node/p/set"]
+
+
+@pytest.mark.asyncio
+async def test_a_subscription_carries_the_sdks_callback_to_the_client() -> None:
+ """The defect behind every ignored relay command: the callback the SDK hands
+ `subscribe` was discarded here, so the client had a filter and no idea what
+ to do with a message on it."""
+ recorder = Recorder()
+ transport = _transport(recorder)
+ transport.start()
+ received: list[tuple[str, bytes]] = []
+
+ def on_set(topic: str, payload: bytes) -> None:
+ received.append((topic, payload))
+
+ transport.subscribe("ebus/5/dev/switch/relay/set", on_set, qos=1)
+ await transport.drain()
+
+ [(topic, callback, qos)] = recorder.subscribed
+ callback("ebus/5/dev/switch/relay/set", b"OPEN")
+ assert (topic, qos) == ("ebus/5/dev/switch/relay/set", 1)
+ assert received == [("ebus/5/dev/switch/relay/set", b"OPEN")]
+
+
+@pytest.mark.asyncio
+async def test_an_operation_lost_to_an_outage_is_dropped_quietly(
+ caplog: pytest.LogCaptureFixture,
+) -> None:
+ """The link reports an outage once; the drainer must not report each
+ casualty again, with a traceback, for every topic of every tick."""
+ caplog.set_level(logging.DEBUG)
+ recorder = Recorder()
+
+ async def unavailable(topic: str, payload: bytes, qos: int, retain: bool) -> None:
+ raise BrokerUnavailable("the broker link is down")
+
+ transport = LoopBoundTransport(
+ publish=unavailable,
+ subscribe=recorder.subscribe,
+ connected=recorder.is_connected,
+ )
+ transport.start()
+
+ for i in range(5):
+ transport.publish(f"ebus/5/dev/node/p{i}", str(i))
await transport.drain()
- assert recorder.published and recorder.subscribed == ["ebus/5/dev/node/p/set"]
+ assert not [r for r in caplog.records if r.levelno >= logging.WARNING]
diff --git a/tests/integration/test_broker_restart.py b/tests/integration/test_broker_restart.py
new file mode 100644
index 0000000..8ba8623
--- /dev/null
+++ b/tests/integration/test_broker_restart.py
@@ -0,0 +1,169 @@
+"""A running panel outlives a restart of its broker: a real mosquitto, restarted under it.
+
+The fake client in ``tests/emitter_adapter`` pins the link's contract. This pins
+the parts a fake cannot speak for: that aiomqtt notices a broker that went away,
+that a broker restarted without persistence comes back holding nothing, and that
+a command Home Assistant publishes after the restart reaches the panel.
+
+Skipped where mosquitto is not installed. The in-process amqtt broker the other
+tests use cannot stand in here: a restart has to take the process away, sockets
+and retained store with it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import shutil
+import socket
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import aiomqtt
+import pytest
+
+from panelbench.emitter_adapter import runtime as emitter_runtime
+from panelbench.emitter_adapter.runtime import BrokerConnection
+from panelbench.emitter_adapter.transport import LoopBoundTransport
+from panelbench.engine import DynamicSimulationEngine
+from tests._helpers import DEFAULT_CONFIG, relay_opened_by_command, settable_relays
+
+if TYPE_CHECKING:
+ from collections.abc import AsyncIterator, Callable
+
+# Package managers put mosquitto in an sbin directory, which is often not on PATH.
+_MOSQUITTO = shutil.which(
+ "mosquitto",
+ path=os.pathsep.join(
+ [os.environ.get("PATH", ""), "/opt/homebrew/sbin", "/usr/local/sbin", "/usr/sbin"]
+ ),
+)
+
+pytestmark = pytest.mark.skipif(_MOSQUITTO is None, reason="mosquitto is not installed")
+
+
+class Mosquitto:
+ """A mosquitto process on a fixed port that can be stopped and started again.
+
+ No persistence, so a restart empties the retained store the way a broker
+ that lost it would: only a republished tree can refill it.
+ """
+
+ def __init__(self, executable: str, workdir: Path) -> None:
+ with socket.socket() as probe:
+ probe.bind(("127.0.0.1", 0))
+ self.port: int = probe.getsockname()[1]
+ self._executable = executable
+ self._config = workdir / "mosquitto.conf"
+ self._config.write_text(
+ f"listener {self.port} 127.0.0.1\nallow_anonymous true\npersistence false\n",
+ encoding="utf-8",
+ )
+ self._log = workdir / "mosquitto.log"
+ self._process: asyncio.subprocess.Process | None = None
+
+ async def start(self) -> None:
+ with self._log.open("ab") as log:
+ self._process = await asyncio.create_subprocess_exec(
+ self._executable, "-c", str(self._config), stdout=log, stderr=subprocess.STDOUT
+ )
+ async with asyncio.timeout(5):
+ while True:
+ with contextlib.suppress(OSError):
+ _, writer = await asyncio.open_connection("127.0.0.1", self.port)
+ writer.close()
+ await writer.wait_closed()
+ return
+ await asyncio.sleep(0.02)
+
+ async def stop(self) -> None:
+ process, self._process = self._process, None
+ if process is None or process.returncode is not None:
+ return
+ process.terminate()
+ await process.wait()
+
+
+@pytest.fixture
+async def mosquitto(tmp_path: Path) -> AsyncIterator[Mosquitto]:
+ assert _MOSQUITTO is not None
+ broker = Mosquitto(_MOSQUITTO, tmp_path)
+ await broker.start()
+ try:
+ yield broker
+ finally:
+ await broker.stop()
+
+
+async def eventually(condition: Callable[[], bool], *, within: float) -> None:
+ async with asyncio.timeout(within):
+ while not condition():
+ await asyncio.sleep(0.02)
+
+
+async def command(port: int, circuit: str, value: str) -> None:
+ """Publish a relay command the way Home Assistant does."""
+ async with aiomqtt.Client("127.0.0.1", port, identifier="home-assistant") as ha:
+ await ha.publish(f"ebus/5/{circuit}/switch/relay/set", value.encode(), qos=1)
+
+
+async def retained(port: int, topic: str) -> bytes:
+ """What a consumer connecting now is handed for *topic*."""
+ async with aiomqtt.Client("127.0.0.1", port, identifier="observer") as observer:
+ await observer.subscribe(topic)
+ async with asyncio.timeout(5):
+ async for message in observer.messages:
+ return message.payload
+ raise AssertionError(f"nothing retained on {topic}")
+
+
+@pytest.mark.asyncio
+async def test_a_panel_outlives_a_restart_of_its_broker(
+ mosquitto: Mosquitto, caplog: pytest.LogCaptureFixture
+) -> None:
+ caplog.set_level(logging.DEBUG)
+ engine = DynamicSimulationEngine(config_path=DEFAULT_CONFIG)
+ await engine.initialize_async()
+ runtime = await emitter_runtime.start_clone(
+ engine, broker=BrokerConnection(host="127.0.0.1", port=mosquitto.port)
+ )
+ root = f"ebus/5/{engine.serial_number}"
+ transport = runtime.transport
+ assert isinstance(transport, LoopBoundTransport)
+ try:
+ await emitter_runtime.publish_tick(runtime)
+ # A command is not retained: one sent before the subscription is up is lost.
+ await transport.drain()
+ before_restart, after_restart = settable_relays(runtime)[:2]
+
+ await command(mosquitto.port, before_restart, "OPEN")
+ await relay_opened_by_command(runtime, before_restart)
+
+ await mosquitto.stop()
+ await eventually(lambda: not transport.is_connected(), within=5)
+ for _ in range(3):
+ # The tick loop does not stop for an outage; what it publishes meanwhile
+ # must be dropped without a word, since the link has already said it.
+ await emitter_runtime.publish_tick(runtime)
+ await asyncio.sleep(0.05)
+ await mosquitto.start()
+ await eventually(transport.is_connected, within=10)
+
+ # The broker came back empty. A `$description` there now was republished.
+ assert await retained(mosquitto.port, f"{root}/$description")
+ assert await retained(mosquitto.port, f"{root}/$state") == b"ready"
+
+ await command(mosquitto.port, after_restart, "OPEN")
+ await relay_opened_by_command(runtime, after_restart)
+ finally:
+ await emitter_runtime.stop_clone(runtime)
+
+ ours = [r for r in caplog.records if r.name.startswith("panelbench")]
+ warnings = [r for r in ours if r.levelno >= logging.WARNING]
+ assert len(warnings) == 1, [r.getMessage() for r in warnings]
+ assert "lost the MQTT broker" in warnings[0].getMessage()
+ assert not [r for r in caplog.records if r.exc_info], "a traceback was logged"
+ assert any("reconnected to the MQTT broker" in r.getMessage() for r in ours)
From d4c6e50133c77c7216819c56d5c8ecdc3474ad20 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:35:15 -0700
Subject: [PATCH 68/95] docs(changelog): note the command, reconnect and
weather fixes for 2.6.0
---
CHANGELOG.md | 4 ++++
panelbench/CHANGELOG.md | 3 +++
2 files changed, 7 insertions(+)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9ab264e..1677ffa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -51,6 +51,10 @@ SPAN release changes on upgrade, and that includes a clone of the earlier MAIN 4
### Fixed
+- **Commands from Home Assistant now take effect**, such as a circuit's relay or shed priority, where PanelBench subscribed to them and then never read them.
+- **PanelBench reconnects after its MQTT broker restarts and publishes its panels again**, where it stayed disconnected until it was restarted itself and
+ logged an error for every topic it could not publish.
+- **A panel's solar output no longer changes when PanelBench restarts**, where each start gave the same panel different weather.
- **An upgraded add-on now refreshes its shipped `default_*` templates on every start**, where it kept the copies an earlier release laid down and published
whatever firmware they named.
- **The dashboard shows a panel as islandable when any of its solar inverters is hybrid**, where only the first solar circuit listed decided it.
diff --git a/panelbench/CHANGELOG.md b/panelbench/CHANGELOG.md
index deecf40..f652921 100644
--- a/panelbench/CHANGELOG.md
+++ b/panelbench/CHANGELOG.md
@@ -40,6 +40,9 @@ names no SPAN release, including a clone of the earlier MAIN 40 template, now pu
### Fixed
+- **Commands from Home Assistant take effect**, such as a circuit's relay or shed priority, where PanelBench never read them.
+- **PanelBench reconnects after its MQTT broker restarts and publishes its panels again**, where it stayed disconnected until the add-on was restarted.
+- **A panel's solar output no longer changes when the add-on restarts**, where each start gave the same panel different weather.
- **An upgraded add-on refreshes its shipped `default_*` templates on every start**, where it kept the copies an earlier release laid down.
- **The panel's HTTP status, Homie schema endpoint and mDNS advertisement report the same firmware version it publishes over MQTT.**
- **A cloned panel keeps the source panel's name, firmware version and hardware version.**
From 9273054f738a822d453be6b19668e5cee539bf2a Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:44:28 -0700
Subject: [PATCH 69/95] fix(clone): read commissioning, size and site values
from what the panel publishes
A commissioned circuit is now recognised by its two locks and what it
feeds: a doubly locked circuit at NEVER feeding an inverter is the PV
system, feeding a battery the backup system. SPAN's names for these
circuits decide only for a circuit that publishes no connection, since
a user may rename them.
The panel size comes from a published info/panel-size, else the numeric
suffix of info/model, as upstream's capture reads it. Only without
either, or when the circuits would not fit, does the highest occupied
space decide, which undercounted any panel whose top spaces are empty.
The clone copies the panel's status/time-zone and its line voltages,
the legs' mean as the per-leg voltage and twice it as the service
voltage. The postal code is not copied.
The lookup for the circuit feeding an inverter or SPAN Drive reads only
this panel's circuits, so another panel's tree on the same broker cannot
take its nameplate or identity. A breaker rating the panel does not
publish is logged when the default replaces it.
---
src/panelbench/clone.py | 167 ++++++++++++++++++-----
tests/_helpers.py | 35 ++++-
tests/test_clone.py | 290 +++++++++++++++++++++++++++++++++++++++-
3 files changed, 457 insertions(+), 35 deletions(-)
diff --git a/src/panelbench/clone.py b/src/panelbench/clone.py
index 8cdf05e..f3b461e 100644
--- a/src/panelbench/clone.py
+++ b/src/panelbench/clone.py
@@ -16,6 +16,7 @@
from __future__ import annotations
import logging
+import re
from collections.abc import Mapping
from datetime import UTC, datetime
from types import MappingProxyType
@@ -35,15 +36,27 @@
TYPE_PV = "energy.ebus.device.pv"
TYPE_EVSE = "energy.ebus.device.evse"
+COMMISSIONED_SYSTEM_FEEDS: Final[Mapping[str, str]] = MappingProxyType(
+ {TYPE_PV: "pv", TYPE_BESS: "backup"}
+)
+"""The system a commissioned circuit belongs to, by the type of device it feeds."""
+
COMMISSIONED_SYSTEM_NAMES: Final[Mapping[str, str]] = MappingProxyType(
{"Commissioned PV System": "pv", "Commissioned Backup System": "backup"}
)
-"""The circuits a SPAN panel adds for a commissioned system, by the name it gives them.
+"""The names a SPAN panel gives the circuits it adds for a commissioned system.
-The same rule upstream's ``panel-sim-capture`` applies: the name, a locked relay,
-and a NEVER priority without ``$settable``. The name alone is not enough.
+Read only when a circuit publishes no ``connection`` to say what it feeds: the name
+is the user's to change, and a renamed circuit is commissioned all the same.
"""
+# Breaker ratings for a panel or circuit that publishes none, each reported when used.
+_DEFAULT_MAIN_BREAKER_A: Final = 200
+_DEFAULT_CIRCUIT_BREAKER_A: Final = 20
+
+# What a panel publishing no size is rounded up to from its highest occupied space.
+_STANDARD_PANEL_SIZES: Final = (16, 24, 32, 40, 48)
+
if TYPE_CHECKING:
from pathlib import Path
@@ -167,10 +180,16 @@ def translate_panel_tree(
feed_map = _build_feed_map(devices, circuit_nodes)
# Extract panel-level values
- main_breaker = _int_prop(devices, panel_device_id, "breaker", "rating") or 200
+ main_breaker = _int_prop(devices, panel_device_id, "breaker", "rating")
+ if not main_breaker:
+ _LOGGER.warning(
+ "Panel %s publishes no breaker/rating; cloning it with a %d A main breaker",
+ panel_device_id,
+ _DEFAULT_MAIN_BREAKER_A,
+ )
+ main_breaker = _DEFAULT_MAIN_BREAKER_A
- # Derive panel size from maximum space value across all circuits
- total_tabs = _derive_total_tabs(devices, circuit_nodes)
+ total_tabs = _derive_total_tabs(devices, panel_device_id, circuit_nodes)
clone_serial = make_clone_serial(panel_device_id)
@@ -185,6 +204,7 @@ def translate_panel_tree(
panel_description = panel_device.description if panel_device is not None else None
if isinstance(panel_description, dict) and isinstance(panel_description.get("name"), str):
panel_config["display_name"] = panel_description["name"]
+ _copy_site_values(devices, panel_device_id, panel_config)
# Build per-circuit templates and definitions
templates: dict[str, dict[str, object]] = {}
@@ -207,11 +227,11 @@ def translate_panel_tree(
# Enrich PV circuit template
for pv_id in pv_nodes:
- _enrich_pv_template(devices, pv_id, feed_map, templates, circuits)
+ _enrich_pv_template(devices, circuit_nodes, pv_id, feed_map, templates, circuits)
# Enrich EVSE circuit templates
for evse_id in evse_nodes:
- _enrich_evse_template(devices, evse_id, feed_map, templates, circuits)
+ _enrich_evse_template(devices, circuit_nodes, evse_id, feed_map, templates, circuits)
# Unmapped tabs
all_tabs = set(range(1, total_tabs + 1))
@@ -585,16 +605,19 @@ def _devices_of_type(
def _circuit_feeding(
devices: Mapping[str, DiscoveredDevice],
+ circuit_nodes: list[str],
target_device_id: str,
) -> str | None:
- """The circuit that feeds ``target_device_id``, or None.
+ """The circuit of this panel that feeds ``target_device_id``, or None.
The reverse of the flat schema's lookup. A DER used to name its circuit through
``feed``; now the circuit names the DER through ``connection/feeds-device-id``,
so finding a DER's circuit means searching the circuits rather than reading one
- property off the DER.
+ property off the DER. Only *circuit_nodes*, this panel's circuits: a broker
+ serving two panels hands back both trees, and another device publishing
+ ``connection`` is not a circuit of this one.
"""
- for device_id in devices:
+ for device_id in circuit_nodes:
if _get_prop(devices, device_id, "connection", "feeds-device-id") == target_device_id:
return device_id
return None
@@ -632,29 +655,85 @@ def _build_feed_map(
def _derive_total_tabs(
devices: Mapping[str, DiscoveredDevice],
+ panel_device_id: str,
circuit_nodes: list[str],
) -> int:
- """Derive panel size from the highest breaker position any circuit occupies.
+ """The panel's size: what it publishes, else its highest occupied space.
- v1.0 publishes the positions directly in ``info/spaces``, so a 240 V circuit
- already reports both. The flat schema published one position plus a ``dipole``
- flag and left the consumer to infer the companion as position + 2 — that
- inference is gone, along with the class of bug where a panel wired against the
- convention was silently mis-sized.
+ An ``info/panel-size``, where one is published, then the numeric suffix of
+ ``info/model`` (``MAIN_32``), as upstream's capture reads it. Only without either
+ does the highest breaker position decide, rounded up to a standard size, and
+ that undercounts any panel whose top spaces are empty.
+
+ A published size the circuits do not fit in is reported and set aside, since the
+ clone would place a circuit on a space the panel does not have.
"""
max_space = 0
for node_id in circuit_nodes:
for space in _spaces_prop(devices, node_id):
max_space = max(max_space, space)
- # Round up to standard panel sizes
- for standard_size in (16, 24, 32, 40, 48):
+ published = _published_panel_size(devices, panel_device_id)
+ if published is not None:
+ if published >= max_space:
+ return published
+ _LOGGER.warning(
+ "Panel %s publishes a size of %d (model %s) but has a circuit on space %d; "
+ "sizing the clone from its circuits",
+ panel_device_id,
+ published,
+ _get_prop(devices, panel_device_id, "info", "model"),
+ max_space,
+ )
+
+ for standard_size in _STANDARD_PANEL_SIZES:
if max_space <= standard_size:
return standard_size
return max_space
+def _published_panel_size(
+ devices: Mapping[str, DiscoveredDevice],
+ panel_device_id: str,
+) -> int | None:
+ """The size the panel states, from ``info/panel-size`` or its model's suffix."""
+ size = _int_prop(devices, panel_device_id, "info", "panel-size")
+ if size:
+ return size
+ model = _get_prop(devices, panel_device_id, "info", "model") or ""
+ suffix = re.search(r"(\d+)$", model)
+ return int(suffix.group(1)) if suffix else None
+
+
+def _copy_site_values(
+ devices: Mapping[str, DiscoveredDevice],
+ panel_device_id: str,
+ panel_config: dict[str, object],
+) -> None:
+ """The panel's time zone and line voltages, where it publishes them.
+
+ A simulated panel publishes one per-leg voltage on both legs, so the clone takes
+ the mean of the legs the source publishes, and their sum (or twice the one) as
+ the service voltage. A value the panel does not publish is left unwritten, so
+ the config's default applies. The postal code is deliberately not copied.
+ """
+ time_zone = _get_prop(devices, panel_device_id, "status", "time-zone")
+ if time_zone:
+ panel_config["time_zone"] = time_zone
+
+ legs = [
+ voltage
+ for leg in ("voltage-a", "voltage-b")
+ if (voltage := _float_prop(devices, panel_device_id, "meter", leg)) is not None
+ and voltage > 0
+ ]
+ if legs:
+ line = sum(legs) / len(legs)
+ panel_config["line_voltage_v"] = round(line, 2)
+ panel_config["service_voltage_v"] = round(2 * line, 2)
+
+
def _translate_circuit(
devices: Mapping[str, DiscoveredDevice],
node_uuid: str,
@@ -672,7 +751,15 @@ def _translate_circuit(
space = tabs[0]
name = _get_prop(devices, node_uuid, "info", "name") or f"Circuit {space}"
- breaker_rating = _int_prop(devices, node_uuid, "breaker", "rating") or 20
+ breaker_rating = _int_prop(devices, node_uuid, "breaker", "rating")
+ if not breaker_rating:
+ _LOGGER.warning(
+ "Circuit %s (%s) publishes no breaker/rating; cloning it with a %d A breaker",
+ node_uuid,
+ name,
+ _DEFAULT_CIRCUIT_BREAKER_A,
+ )
+ breaker_rating = _DEFAULT_CIRCUIT_BREAKER_A
active_power = _float_prop(devices, node_uuid, "meter", "active-power")
priority = _get_prop(devices, node_uuid, "load-shed", "priority") or "NEVER"
# v1.0 publishes controllability directly as `switch/relay-controllable`, where
@@ -696,16 +783,12 @@ def _translate_circuit(
# `$settable = true`, which no value-derived flag can produce.
priority_locked = not _is_settable(devices, node_uuid, "load-shed", "priority")
# A circuit SPAN adds for a commissioned PV or battery system is the third lock:
- # priority locked at NEVER on a locked relay. Recognised by the rule upstream's
- # `panel-sim-capture` applies, so the name alone commissions nothing.
- commissioned_system = COMMISSIONED_SYSTEM_NAMES.get(name)
- if not (
- commissioned_system is not None
- and priority_locked
- and not relay_controllable
- and priority == "NEVER"
- ):
- commissioned_system = None
+ # priority locked at NEVER on a locked relay.
+ commissioned_system = (
+ _commissioned_system(devices, node_uuid, name)
+ if priority_locked and not relay_controllable and priority == "NEVER"
+ else None
+ )
never_backup = priority_locked and commissioned_system is None
if never_backup and priority != "OFF_GRID":
# The panel contradicted itself: a circuit commissioned never-backup *is*
@@ -810,6 +893,24 @@ def _translate_circuit(
return template_name, template, circuit_def, tabs
+def _commissioned_system(
+ devices: Mapping[str, DiscoveredDevice],
+ node_uuid: str,
+ name: str,
+) -> str | None:
+ """The commissioned system a doubly locked circuit belongs to, if any.
+
+ What the circuit feeds decides it: an inverter makes it the PV system, a battery
+ the backup system, anything else neither. Only a circuit that publishes no
+ ``connection`` falls back to the name SPAN gives such a circuit, which the user
+ may since have changed.
+ """
+ feeds = _get_prop(devices, node_uuid, "connection", "feeds-device-type")
+ if feeds:
+ return COMMISSIONED_SYSTEM_FEEDS.get(feeds)
+ return COMMISSIONED_SYSTEM_NAMES.get(name)
+
+
def _device_role_to_mode(device_role: str | None) -> str:
"""Map a device role from the feed map to an energy profile mode."""
if device_role == "pv":
@@ -852,6 +953,7 @@ def _build_bess_config(
def _enrich_pv_template(
devices: Mapping[str, DiscoveredDevice],
+ circuit_nodes: list[str],
pv_node_id: str,
feed_map: dict[str, str],
templates: dict[str, dict[str, object]],
@@ -859,7 +961,7 @@ def _enrich_pv_template(
) -> None:
"""Enrich the PV circuit template with nameplate capacity and solar profile, and
write the inverter's identity onto the circuit that feeds it."""
- circuit_uuid = _circuit_feeding(devices, pv_node_id)
+ circuit_uuid = _circuit_feeding(devices, circuit_nodes, pv_node_id)
template = _find_template_for_feed(circuit_uuid, feed_map, templates, devices)
if template is None:
return
@@ -882,6 +984,7 @@ def _enrich_pv_template(
def _enrich_evse_template(
devices: Mapping[str, DiscoveredDevice],
+ circuit_nodes: list[str],
evse_node_id: str,
feed_map: dict[str, str],
templates: dict[str, dict[str, object]],
@@ -889,7 +992,7 @@ def _enrich_evse_template(
) -> None:
"""Enrich the EVSE circuit template with time-of-day charging profile, and write
the drive's serial and firmware onto the circuit that feeds it."""
- circuit_uuid = _circuit_feeding(devices, evse_node_id)
+ circuit_uuid = _circuit_feeding(devices, circuit_nodes, evse_node_id)
template = _find_template_for_feed(circuit_uuid, feed_map, templates, devices)
if template is None:
return
diff --git a/tests/_helpers.py b/tests/_helpers.py
index 7669e3f..4cc8799 100644
--- a/tests/_helpers.py
+++ b/tests/_helpers.py
@@ -10,6 +10,7 @@
import asyncio
import copy
+import json
from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING, Final
@@ -17,6 +18,7 @@
import yaml
from ebus_panel_sim.relay_resolver import RelayRequester, RelayState
+from ebus_sdk import DiscoveredDevice
from panelbench.clone import TYPE_PV, translate_panel_tree
from panelbench.emitter_adapter import runtime as emitter_runtime
@@ -30,14 +32,22 @@
if TYPE_CHECKING:
from collections.abc import Mapping
- from ebus_sdk import DiscoveredDevice
-
from panelbench.config_types import SimulationConfig
from panelbench.emitter_adapter.runtime import CloneRuntime
from panelbench.emitter_adapter.wire_capture import RecordingTransport
DEFAULT_CONFIG: Final = Path(__file__).resolve().parents[1] / "configs" / "default_MAIN_40.yaml"
+# The pinned emitter release's masked capture of a real MAIN 32 on SPAN release 202639.
+CAPTURED_MAIN_32: Final = (
+ Path(__file__).resolve().parent
+ / "fidelity"
+ / "fixtures"
+ / "upstream"
+ / "main32_r202639-tree-v1.json"
+)
+CAPTURED_MAIN_32_SERIAL: Final = "nt-9874-s7rxt"
+
# SPAN firmware strings either side of release 202639, where the BESS meter's sign
# and the EVSE user limit's publication changed.
EARLIER_FIRMWARE: Final = "spanos2/r202633/02"
@@ -143,3 +153,24 @@ async def relay_opened_by_command(
async with asyncio.timeout(within):
while runtime.emitter.relays.state(uuid) != (RelayState.OPEN, RelayRequester.USER):
await asyncio.sleep(0.005)
+
+
+def discovered_from_tree_snapshot(path: Path) -> dict[str, DiscoveredDevice]:
+ """A ``tree-v1`` snapshot as the devices a scrape of that panel would discover.
+
+ The snapshot keeps strings and numbers apart; the wire does not, and neither does
+ a discovered device, so both are read back as the strings a panel published.
+ """
+ snapshot = json.loads(path.read_text(encoding="utf-8"))
+ devices: dict[str, DiscoveredDevice] = {}
+ for device_id, entry in snapshot["devices"].items():
+ device = DiscoveredDevice(device_id)
+ device.update_description(json.dumps(entry["description"]))
+ values = {**entry.get("properties", {}), **entry.get("numeric_properties", {})}
+ for key, value in values.items():
+ if value is None:
+ continue
+ capability, prop = key.split("/", 1)
+ device.update_property(capability, prop, str(value))
+ devices[device_id] = device
+ return devices
diff --git a/tests/test_clone.py b/tests/test_clone.py
index 8b5d1fc..f654397 100644
--- a/tests/test_clone.py
+++ b/tests/test_clone.py
@@ -3,8 +3,10 @@
from __future__ import annotations
import json
+import logging
from typing import TYPE_CHECKING
+import pytest
import yaml
from ebus_sdk import DiscoveredDevice
@@ -13,13 +15,20 @@
TYPE_CIRCUIT,
TYPE_EVSE,
TYPE_PV,
+ translate_panel_tree,
translate_scraped_panel,
update_config_from_scrape,
write_clone_config,
)
from panelbench.scraper import ScrapedPanel
from panelbench.validation import validate_yaml_config
-from tests._helpers import CURRENT_FIRMWARE, EARLIER_FIRMWARE
+from tests._helpers import (
+ CAPTURED_MAIN_32,
+ CAPTURED_MAIN_32_SERIAL,
+ CURRENT_FIRMWARE,
+ EARLIER_FIRMWARE,
+ discovered_from_tree_snapshot,
+)
if TYPE_CHECKING:
from pathlib import Path
@@ -608,3 +617,282 @@ def test_a_refresh_leaves_the_clone_firmware_alone(self) -> None:
update_config_from_scrape(config, _make_scraped(after))
assert config["firmware_version"] == EARLIER_FIRMWARE
+
+
+def _templates(config: dict[str, object]) -> dict[str, dict[str, object]]:
+ templates = config["circuit_templates"]
+ assert isinstance(templates, dict)
+ return templates
+
+
+def _panel_config(config: dict[str, object]) -> dict[str, object]:
+ panel = config["panel_config"]
+ assert isinstance(panel, dict)
+ return panel
+
+
+def _locked_circuit(
+ device_id: str,
+ name: str,
+ spaces: str,
+ *,
+ feeds: tuple[str, str] | None,
+) -> DiscoveredDevice:
+ """A circuit SPAN adds for a commissioned system: relay locked, priority locked
+ at NEVER. Whatever it is named, and whatever it feeds, is the test's to choose."""
+ return _circuit(
+ device_id,
+ name,
+ spaces,
+ rating="40",
+ priority="NEVER",
+ active_power="0.0",
+ controllable="false",
+ never_backup=True,
+ feeds=feeds,
+ )
+
+
+class TestCommissionedSystemByWhatItFeeds:
+ """A commissioned circuit is recognised by its locks and what it feeds.
+
+ SPAN names these circuits "Commissioned PV System" and "Commissioned Backup
+ System", but the name is the user's to change. Reading it as the commissioning
+ lost the lock from any clone of a renamed one.
+ """
+
+ def test_a_locked_circuit_feeding_an_inverter_is_the_pv_system_whatever_its_name(
+ self,
+ ) -> None:
+ devices = _base_devices()
+ devices["ccc333"] = _locked_circuit(
+ "ccc333", "Roof Array", "7,9", feeds=("pv-0", "energy.ebus.device.pv")
+ )
+
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ assert _templates(config)["clone_7"].get("commissioned_system") == "pv"
+ validate_yaml_config(config)
+
+ def test_a_locked_circuit_feeding_a_battery_is_the_backup_system(self) -> None:
+ devices = _base_devices()
+ devices["ddd444"] = _locked_circuit(
+ "ddd444", "Powerwall", "11,13", feeds=("bess-0", "energy.ebus.device.bess")
+ )
+
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ assert _templates(config)["clone_11"].get("commissioned_system") == "backup"
+ validate_yaml_config(config)
+
+ def test_what_it_feeds_outranks_its_name(self) -> None:
+ """A locked circuit feeding a SPAN Drive is no PV system, whatever it is called."""
+ devices = _base_devices()
+ devices["eee555"] = _locked_circuit(
+ "eee555",
+ "Commissioned PV System",
+ "15,17",
+ feeds=("evse-0", "energy.ebus.device.evse"),
+ )
+
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ assert "commissioned_system" not in _templates(config)["clone_15"]
+
+ def test_without_connection_data_the_name_decides(self) -> None:
+ """The fallback, for a panel that publishes no `connection` on the circuit."""
+ devices = _base_devices()
+ devices["ccc333"] = _locked_circuit("ccc333", "Commissioned PV System", "7,9", feeds=None)
+ devices["ddd444"] = _locked_circuit("ddd444", "Battery Storage", "11,13", feeds=None)
+
+ templates = _templates(translate_scraped_panel(_make_scraped(devices)))
+
+ assert templates["clone_7"].get("commissioned_system") == "pv"
+ assert "commissioned_system" not in templates["clone_11"]
+
+ def test_feeding_an_inverter_without_both_locks_is_not_commissioned(self) -> None:
+ """The base fixture's solar circuit: relay locked, priority still settable."""
+ templates = _templates(translate_scraped_panel(_make_scraped()))
+
+ assert "commissioned_system" not in templates["clone_7"]
+
+
+class TestPanelSize:
+ """The panel's size is the model it publishes, not its highest occupied space."""
+
+ def test_the_model_names_the_size(self) -> None:
+ """A MAIN 40 whose circuits stop at space 17 is still a 40-space panel."""
+ devices = _base_devices()
+ devices[_SERIAL].update_property("info", "model", "MAIN_40")
+
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ assert _panel_config(config)["total_tabs"] == 40
+ assert config["unmapped_tabs"] == [
+ t for t in range(1, 41) if t not in {1, 3, 5, 7, 9, 11, 13, 15, 17}
+ ]
+ validate_yaml_config(config)
+
+ def test_a_published_panel_size_outranks_the_model(self) -> None:
+ devices = _base_devices()
+ devices[_SERIAL].update_property("info", "model", "MAIN_40")
+ devices[_SERIAL].update_property("info", "panel-size", "32")
+
+ assert _panel_config(translate_scraped_panel(_make_scraped(devices)))["total_tabs"] == 32
+
+ def test_a_model_without_a_size_falls_back_to_the_highest_space(self) -> None:
+ devices = _base_devices()
+ devices[_SERIAL].update_property("info", "model", "UNKNOWN")
+
+ assert _panel_config(translate_scraped_panel(_make_scraped(devices)))["total_tabs"] == 24
+
+ def test_a_model_smaller_than_the_circuits_falls_back(
+ self, caplog: pytest.LogCaptureFixture
+ ) -> None:
+ """A size the circuits do not fit in would make a clone the panel refuses."""
+ devices = _base_devices()
+ devices[_SERIAL].update_property("info", "model", "MAIN_16")
+
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ assert _panel_config(config)["total_tabs"] == 24
+ assert "MAIN_16" in caplog.text
+ validate_yaml_config(config)
+
+
+class TestPanelSiteValues:
+ """The panel's time zone and line voltages travel with the clone."""
+
+ def test_the_time_zone_is_copied(self) -> None:
+ devices = _base_devices()
+ devices[_SERIAL].update_property("status", "time-zone", "America/Denver")
+
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ assert _panel_config(config)["time_zone"] == "America/Denver"
+ validate_yaml_config(config)
+
+ def test_the_line_voltages_are_copied(self) -> None:
+ """One per-leg voltage is all a simulated panel publishes, so the clone takes
+ the legs' mean, and their sum as the service voltage."""
+ devices = _base_devices()
+ devices[_SERIAL].update_property("meter", "voltage-a", "121.8")
+ devices[_SERIAL].update_property("meter", "voltage-b", "122.1")
+
+ panel = _panel_config(translate_scraped_panel(_make_scraped(devices)))
+
+ assert panel["line_voltage_v"] == 121.95
+ assert panel["service_voltage_v"] == 243.9
+
+ def test_one_leg_stands_for_both(self) -> None:
+ devices = _base_devices()
+ devices[_SERIAL].update_property("meter", "voltage-a", "121.8")
+
+ panel = _panel_config(translate_scraped_panel(_make_scraped(devices)))
+
+ assert panel["line_voltage_v"] == 121.8
+ assert panel["service_voltage_v"] == 243.6
+
+ def test_nothing_published_writes_nothing(self) -> None:
+ """Absent, the config's defaults apply rather than a guess written into it."""
+ devices = _base_devices()
+ devices[_SERIAL].update_property("meter", "voltage-a", "0.0")
+
+ panel = _panel_config(translate_scraped_panel(_make_scraped(devices)))
+
+ assert "time_zone" not in panel
+ assert "line_voltage_v" not in panel
+ assert "service_voltage_v" not in panel
+ assert "postal_code" not in panel
+
+
+class TestDefaultedBreakerRatings:
+ """A rating the panel did not publish is a guess, and the log says so."""
+
+ def test_a_missing_main_breaker_rating_is_reported(
+ self, caplog: pytest.LogCaptureFixture
+ ) -> None:
+ devices = _base_devices()
+ devices[_SERIAL] = _device(
+ _SERIAL,
+ TYPE_PANEL,
+ {"info": {"serial-number": _SERIAL, "data-model-version": "1.0"}},
+ children=list(devices[_SERIAL].description.get("children", [])),
+ )
+
+ with caplog.at_level(logging.WARNING, logger="panelbench.clone"):
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ assert _panel_config(config)["main_size"] == 200
+ assert any(
+ _SERIAL in r.getMessage() and "200" in r.getMessage()
+ for r in caplog.records
+ if r.levelno == logging.WARNING
+ )
+
+ def test_each_missing_circuit_rating_is_reported(
+ self, caplog: pytest.LogCaptureFixture
+ ) -> None:
+ devices = _base_devices()
+ for device_id in ("aaa111", "bbb222"):
+ devices[device_id].properties["breaker"].pop("rating")
+
+ with caplog.at_level(logging.WARNING, logger="panelbench.clone"):
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ warned = [r.getMessage() for r in caplog.records if r.levelno == logging.WARNING]
+ assert _templates(config)["clone_1"]["breaker_rating"] == 20
+ assert any("aaa111" in m and "20" in m for m in warned)
+ assert any("bbb222" in m and "20" in m for m in warned)
+ assert not any("ccc333" in m for m in warned)
+
+
+class TestFeedLookupStaysInThePanel:
+ """Finding the circuit that feeds a device reads only this panel's circuits."""
+
+ def test_another_panels_circuit_naming_the_same_inverter_is_ignored(self) -> None:
+ """A broker serving two panels hands back both trees. A circuit of the other
+ panel, listed first, that names this panel's inverter must not take its
+ nameplate, which then lands on no template at all."""
+ foreign = _device(
+ "000foreign",
+ TYPE_CIRCUIT,
+ {
+ "info": {"name": "Other Panel Solar", "spaces": "1"},
+ "connection": {
+ "feeds-device-id": "pv-0",
+ "feeds-device-type": "energy.ebus.device.pv",
+ },
+ },
+ parent="other-panel",
+ )
+ foreign_description = dict(foreign.description)
+ foreign_description["root"] = "other-panel"
+ foreign.update_description(json.dumps(foreign_description))
+ devices = {"000foreign": foreign, **_base_devices()}
+
+ config = translate_scraped_panel(_make_scraped(devices))
+
+ ep = _templates(config)["clone_7"]["energy_profile"]
+ assert isinstance(ep, dict)
+ assert ep["nameplate_capacity_w"] == 5000.0
+
+
+class TestTheCapturedPanel:
+ """The release's masked capture of a real MAIN 32 on SPAN release 202639."""
+
+ def test_a_clone_of_it_reads_what_the_panel_publishes(self) -> None:
+ devices = discovered_from_tree_snapshot(CAPTURED_MAIN_32)
+
+ config = translate_panel_tree(CAPTURED_MAIN_32_SERIAL, devices)
+
+ panel = _panel_config(config)
+ assert panel["total_tabs"] == 32
+ assert panel["time_zone"] == "America/Los_Angeles"
+ assert panel["line_voltage_v"] == 121.95
+ assert panel["service_voltage_v"] == 243.9
+ commissioned = [
+ t for t in _templates(config).values() if t.get("commissioned_system") == "pv"
+ ]
+ assert len(commissioned) == 1
+ validate_yaml_config(config)
From f3f85384bb661eac0efc3b4f0743f858978c6312 Mon Sep 17 00:00:00 2001
From: cayossarian <23534755+cayossarian@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:54:23 -0700
Subject: [PATCH 70/95] fix(clone): register with a panel once and keep its
secrets out of configs
Every clone, sync and restore registered a new sim-clone- client
on the real panel, which its owner had to remove by hand. scrape_panel
now reads the panel's serial from its status endpoint, registers once
as panelbench-clone-, keeps the broker credentials that returns
and reuses them, registering again under the same name only when the
broker refuses them. The clone form also takes broker credentials the
user already holds (serial, username, password, port, and a CA that is
fetched from the panel when left blank), and then registers nothing.
The passphrase was written into the clone's panel_source, so it went
into every export and showed in a text field. It and the broker
credentials now live in a PanelSecretsStore keyed by origin serial: a
0600 JSON file in /.secrets (gitignored), or SECRETS_DIR,
which the add-on sets to /data/secrets. The form asks for it in a
password field and never sends it back. A config that carries one gives
it up on the next scan of the config directory or when the dashboard
loads it, and the dashboard never holds it, so no export or save writes
it again.
A restore or replay toggle that has to re-scrape the source panel used
to swallow any failure and leave the circuit unchanged without a word;
it now shows why, as a sync does. A clone keeps the time zone the panel
publishes rather than one derived from Home Assistant's home location.
---
.gitignore | 3 +
DEVELOPER.md | 14 +-
README.md | 3 +-
panelbench/DOCS.md | 4 +-
panelbench/run.sh | 3 +
src/panelbench/__main__.py | 8 +
src/panelbench/app.py | 12 +
src/panelbench/clone.py | 13 +-
src/panelbench/config_types.py | 7 +-
src/panelbench/dashboard/__init__.py | 6 +-
src/panelbench/dashboard/config_store.py | 26 +-
src/panelbench/dashboard/context.py | 3 +
src/panelbench/dashboard/keys.py | 2 +
src/panelbench/dashboard/routes.py | 170 +++++++++----
.../templates/partials/clone_panel.html | 28 ++-
.../templates/partials/entity_list.html | 1 +
src/panelbench/panel_secrets.py | 209 ++++++++++++++++
src/panelbench/scraper.py | 168 ++++++++++++-
tests/_fake_span_panel.py | 111 +++++++++
tests/test_clone.py | 38 ++-
tests/test_clone_from_panel_routes.py | 224 ++++++++++++++++++
...st_dashboard_refuses_an_unloadable_edit.py | 8 +-
tests/test_panel_registration.py | 131 ++++++++++
tests/test_panel_secrets.py | 171 +++++++++++++
24 files changed, 1256 insertions(+), 107 deletions(-)
create mode 100644 src/panelbench/panel_secrets.py
create mode 100644 tests/_fake_span_panel.py
create mode 100644 tests/test_clone_from_panel_routes.py
create mode 100644 tests/test_panel_registration.py
create mode 100644 tests/test_panel_secrets.py
diff --git a/.gitignore b/.gitignore
index c80428a..28470f6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,6 +34,9 @@ configs/*_history.db
configs/*.yaml
!configs/default_*.yaml
+# Source panels' passphrases and broker credentials (panel_secrets.py)
+configs/.secrets/
+
# Local-developer source overrides + env. See .env.example and uv.toml.example.
.env
uv.toml
diff --git a/DEVELOPER.md b/DEVELOPER.md
index 5caa9c7..079e03c 100644
--- a/DEVELOPER.md
+++ b/DEVELOPER.md
@@ -480,7 +480,6 @@ hardware_version:
panel_source:
origin_serial: str # Real panel's serial (immutable)
host: str # IP or hostname of source panel
- passphrase: str | null # Proximity code (null for door-bypass)
last_synced: str # ISO 8601 timestamp
```
@@ -593,17 +592,24 @@ with the target panel, scrapes its MQTT topics, translates the eBus description
### What gets cloned
-- Panel identity (`sim-{serial}-clone`), main breaker rating, panel size
+- Panel identity (`sim-{serial}-clone`), main breaker rating, and the panel size its model names
+- The panel's time zone and line voltages
- The panel's firmware version, so the clone publishes as that SPAN release does
- The panel's hardware version
- All circuits: name, tab position, breaker rating, relay behavior, priority
-- Commissioned PV and battery system circuits, recognised by name and both locks, as `commissioned_system`
+- Commissioned PV and battery system circuits, recognised by both locks and the inverter or battery they feed, as `commissioned_system`
- Energy profile mode inferred from device feeds (PV -> producer, BESS -> bidirectional, EVSE -> bidirectional)
- Energy accumulators seeded from the panel's imported/exported energy values
- Battery behavior with sensible schedule defaults, and the battery's vendor, model, part number, serial and firmware version
- PV nameplate capacity and production profile, and each inverter's vendor, model, serial and firmware version on the circuit that feeds it
- EVSE night-charging time-of-day profile, and each SPAN Drive's serial and firmware version on the circuit that feeds it
-- Source panel credentials stored in `panel_source` for on-demand refresh
+- The source panel's host in `panel_source`, for on-demand refresh
+
+PanelBench registers with a source panel once, as `panelbench-clone-`, and reuses the broker credentials that returns for every later clone, sync and
+restore, registering again only if the panel's broker refuses them. Broker credentials you already hold can be given in the clone form instead, and nothing is
+registered. The passphrase and broker credentials are kept outside every config, keyed by the panel's serial, in `/.secrets/panel_sources.json` (or
+`SECRETS_DIR`; the add-on uses `/data/secrets`), readable only by its owner. A config written before this that carries a `panel_source.passphrase` gives it up
+to that store on the next scan of the config directory, and is never written with it again.
### Usage profile import
diff --git a/README.md b/README.md
index cb2bd35..a1c9972 100644
--- a/README.md
+++ b/README.md
@@ -188,7 +188,8 @@ The dashboard runs on port 18080 and provides full control over the simulated pa
- **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 panel running `r202633+` firmware (IP + passphrase).
+- **Clone** — create an editable copy from a template, or from a panel running `r202633+` firmware (IP and passphrase, or broker credentials you already hold).
+ PanelBench registers with a panel once, keeps the passphrase and credentials outside the config, and reuses them for every sync.
- **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
diff --git a/panelbench/DOCS.md b/panelbench/DOCS.md
index 57630bd..7841cf2 100644
--- a/panelbench/DOCS.md
+++ b/panelbench/DOCS.md
@@ -30,7 +30,9 @@ real SPAN panel's configuration directly from the dashboard.
individual panels
- **File operations** — import/export YAML, clone configs, save & reload
- **Panel cloning** — clone a real SPAN panel's configuration from
- the dashboard (enter the panel IP and passphrase)
+ the dashboard (enter the panel IP and passphrase, or broker
+ credentials you already hold); the passphrase and credentials are
+ kept in the add-on's private storage, never in the config
- **Config persistence** — the simulator remembers the last running
config across restarts
diff --git a/panelbench/run.sh b/panelbench/run.sh
index 06d3a51..a1d5403 100755
--- a/panelbench/run.sh
+++ b/panelbench/run.sh
@@ -54,6 +54,9 @@ detect_advertise_address() {
ADVERTISE_ADDRESS="${ADVERTISE_ADDRESS:-$(detect_advertise_address)}"
export ADVERTISE_ADDRESS
export CERT_DIR="/data/certs"
+# Source panels' passphrases and broker credentials. In /data, which only the add-on
+# reads, rather than beside the configs in the folder Home Assistant shares.
+export SECRETS_DIR="/data/secrets"
export BROKER_USERNAME="span"
export BROKER_PASSWORD="sim-password"
diff --git a/src/panelbench/__main__.py b/src/panelbench/__main__.py
index 8af72c2..8520c5b 100644
--- a/src/panelbench/__main__.py
+++ b/src/panelbench/__main__.py
@@ -170,6 +170,13 @@ def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
default=Path(os.environ.get("CERT_DIR", "/tmp/span-sim-certs")),
help="Directory for generated TLS certificates",
)
+ parser.add_argument(
+ "--secrets-dir",
+ type=Path,
+ default=Path(secrets_dir) if (secrets_dir := os.environ.get("SECRETS_DIR")) else None,
+ help="Directory for source panels' passphrases and broker credentials "
+ "(default: .secrets in the config directory)",
+ )
parser.add_argument(
"--dashboard-port",
type=int,
@@ -272,6 +279,7 @@ def main(argv: list[str] | None = None) -> None:
dashboard_port=args.dashboard_port,
advertise_address=args.advertise_address,
ha_config=ha_config,
+ secrets_dir=args.secrets_dir,
)
try:
diff --git a/src/panelbench/app.py b/src/panelbench/app.py
index 2297157..375cfdc 100644
--- a/src/panelbench/app.py
+++ b/src/panelbench/app.py
@@ -36,6 +36,7 @@
from panelbench.emitter_adapter.runtime import BrokerConnection
from panelbench.panel import PanelInstance
from panelbench.panel_models import PANEL_SIZE_TO_MODEL
+from panelbench.panel_secrets import SECRETS_FILENAME, PanelSecretsStore
from panelbench.recorder import RecorderDataSource
from panelbench.schema import HomieSchemaRegistry, load_schema, render_for_panel
@@ -118,8 +119,14 @@ def __init__(
dashboard_port: int = DASHBOARD_PORT,
advertise_address: str | None = None,
ha_config: HAConnectionConfig | None = None,
+ secrets_dir: Path | None = None,
) -> None:
self._config_dir = config_dir
+ self._panel_secrets = (
+ PanelSecretsStore(secrets_dir / SECRETS_FILENAME)
+ if secrets_dir is not None
+ else PanelSecretsStore.in_config_dir(config_dir)
+ )
self._config_filter = config_filter
self._tick_interval = tick_interval
self._broker_username = broker_username
@@ -586,6 +593,10 @@ async def reload(self) -> dict[str, list[str]]:
stopped, or reloaded. Errors for affected filenames are stored
on ``self._panel_start_errors`` so the dashboard can surface them.
"""
+ # A clone written before the secrets store existed carries its source panel's
+ # passphrase. It moves out on the first scan that finds it, every file in the
+ # directory alike, and before anything hashes or reads them.
+ self._panel_secrets.migrate_config_files(self._config_dir)
current = _discover_configs(self._config_dir, self._config_filter)
# Exclude configs the user explicitly stopped via the dashboard
@@ -850,6 +861,7 @@ async def run(self) -> None:
ha_client=ha_client,
history_provider=ha_client,
panel_browser=browser,
+ panel_secrets=self._panel_secrets,
)
dashboard_app = create_dashboard_app(dashboard_ctx)
self._dashboard_runner = web.AppRunner(dashboard_app)
diff --git a/src/panelbench/clone.py b/src/panelbench/clone.py
index f3b461e..03200f1 100644
--- a/src/panelbench/clone.py
+++ b/src/panelbench/clone.py
@@ -135,21 +135,17 @@ def translate_scraped_panel(
scraped: ScrapedPanel,
*,
host: str | None = None,
- passphrase: str | None = None,
) -> dict[str, object]:
"""Translate a scraped panel into a simulator config dict.
Args:
scraped: The scraped panel data.
host: Source panel IP/hostname (stored in panel_source for refresh).
- passphrase: Source panel passphrase (stored in panel_source for refresh).
Returns a dict matching the ``SimulationConfig`` TypedDict shape,
ready for YAML serialisation and ``validate_yaml_config()``.
"""
- return translate_panel_tree(
- scraped.serial_number, scraped.devices, host=host, passphrase=passphrase
- )
+ return translate_panel_tree(scraped.serial_number, scraped.devices, host=host)
def translate_panel_tree(
@@ -157,7 +153,6 @@ def translate_panel_tree(
devices: Mapping[str, DiscoveredDevice],
*,
host: str | None = None,
- passphrase: str | None = None,
) -> dict[str, object]:
"""Translate a panel's device tree into a simulator config dict.
@@ -165,8 +160,9 @@ def translate_panel_tree(
panel_device_id: The panel's Homie device id, which roots the tree. On a
live SPAN panel it is the serial number.
devices: Every discovered device; only *panel_device_id*'s tree is read.
- host: Source panel IP/hostname (stored in panel_source for refresh).
- passphrase: Source panel passphrase (stored in panel_source for refresh).
+ host: Source panel IP/hostname (stored in panel_source for refresh). What it
+ takes to reach the panel there is kept in the ``PanelSecretsStore``,
+ never in the config.
Returns a dict matching the ``SimulationConfig`` TypedDict shape,
ready for YAML serialisation and ``validate_yaml_config()``.
@@ -273,7 +269,6 @@ def translate_panel_tree(
panel_source: dict[str, object] = {
"origin_serial": panel_device_id,
"host": host,
- "passphrase": passphrase,
"last_synced": datetime.now(UTC).isoformat(),
}
# Snapshot the original BESS config so the modeling Before pass
diff --git a/src/panelbench/config_types.py b/src/panelbench/config_types.py
index a5d1165..0a2987a 100644
--- a/src/panelbench/config_types.py
+++ b/src/panelbench/config_types.py
@@ -11,11 +11,14 @@
class PanelSource(TypedDict, total=False):
- """Source panel connection details for clone configs."""
+ """Source panel provenance for clone configs.
+
+ What it takes to reach the panel, its passphrase and broker credentials, is kept
+ in the ``PanelSecretsStore`` under ``origin_serial``, never here.
+ """
origin_serial: str # real panel's serial (immutable provenance)
host: str # IP or hostname of the source panel
- passphrase: str | None # proximity code (null for door-bypass)
last_synced: str # ISO 8601 timestamp of last sync
diff --git a/src/panelbench/dashboard/__init__.py b/src/panelbench/dashboard/__init__.py
index 60a4f1c..1ab1b42 100644
--- a/src/panelbench/dashboard/__init__.py
+++ b/src/panelbench/dashboard/__init__.py
@@ -18,6 +18,7 @@
from panelbench.dashboard.context import DashboardContext
from panelbench.dashboard.keys import (
APP_KEY_DASHBOARD_CONTEXT,
+ APP_KEY_PANEL_SECRETS,
APP_KEY_PENDING_CLONES,
APP_KEY_PRESET_REGISTRY,
APP_KEY_RATE_CACHE,
@@ -25,6 +26,7 @@
)
from panelbench.dashboard.presets import init_presets
from panelbench.dashboard.routes import refuse_unloadable_edits, setup_routes
+from panelbench.panel_secrets import PanelSecretsStore
from panelbench.rates.cache import RateCache
__all__ = ["DashboardContext", "create_dashboard_app"]
@@ -44,7 +46,8 @@ def create_dashboard_app(context: DashboardContext) -> web.Application:
"""Create and return the dashboard aiohttp application."""
app = web.Application(middlewares=[refuse_unloadable_edits])
- store = ConfigStore()
+ secrets = context.panel_secrets or PanelSecretsStore.in_config_dir(context.config_dir)
+ store = ConfigStore(secrets=secrets)
# Load the active config into the editor/viewer. One the panel would refuse is
# not opened, so nothing can be saved over it: the dashboard still starts on the
@@ -64,6 +67,7 @@ def create_dashboard_app(context: DashboardContext) -> web.Application:
_view_first_default(context, store)
app[APP_KEY_STORE] = store
+ app[APP_KEY_PANEL_SECRETS] = secrets
app[APP_KEY_DASHBOARD_CONTEXT] = context
app[APP_KEY_PRESET_REGISTRY] = init_presets(context.config_dir)
app[APP_KEY_PENDING_CLONES] = {}
diff --git a/src/panelbench/dashboard/config_store.py b/src/panelbench/dashboard/config_store.py
index be052cb..b11ba6b 100644
--- a/src/panelbench/dashboard/config_store.py
+++ b/src/panelbench/dashboard/config_store.py
@@ -12,6 +12,7 @@
from __future__ import annotations
import functools
+import logging
from contextlib import contextmanager
from copy import deepcopy
from dataclasses import dataclass, field
@@ -25,6 +26,7 @@
from collections.abc import Callable, Iterator, Mapping
from pathlib import Path
+ from panelbench.panel_secrets import PanelSecretsStore
from panelbench.scraper import ScrapedPanel
from panelbench.clone import update_config_from_scrape
@@ -43,6 +45,8 @@
from panelbench.validation import validate_yaml_config
from panelbench.weather import get_cached_weather
+_LOGGER = logging.getLogger(__name__)
+
@dataclass
class EntityView:
@@ -129,9 +133,15 @@ def edit(store: ConfigStore, /, *args: P.args, **kwargs: P.kwargs) -> R:
class ConfigStore:
- """In-memory config state: load, mutate, validate, export."""
+ """In-memory config state: load, mutate, validate, export.
+
+ A source panel's passphrase never enters the state: a config loaded with one,
+ written before the secrets store existed, gives it to *secrets*, so nothing
+ exported or saved from here can carry it.
+ """
- def __init__(self) -> None:
+ def __init__(self, *, secrets: PanelSecretsStore | None = None) -> None:
+ self._secrets = secrets
self._dirty: bool = False
self._state: dict[str, Any] = {
"panel_config": {
@@ -180,11 +190,23 @@ def load_from_mapping(
from a key the form never showed.
"""
state = deepcopy(dict(data))
+ self._take_secrets(state, source=source)
normalize_config(state, source=source)
validate_yaml_config(state)
self._state = state
self._dirty = not saved
+ def _take_secrets(self, state: dict[str, Any], *, source: str) -> None:
+ """Move a passphrase out of *state*, into the secrets store where there is one."""
+ if self._secrets is not None:
+ self._secrets.take_from_config(state)
+ return
+ panel_source = state.get("panel_source")
+ if isinstance(panel_source, dict) and panel_source.pop("passphrase", None) is not None:
+ _LOGGER.warning(
+ "Dropped the source panel's passphrase from %s: no store to keep it in", source
+ )
+
def load_from_file(self, path: Path) -> None:
"""Read a file and load its content."""
self.load_from_yaml(path.read_text(encoding="utf-8"), source=str(path))
diff --git a/src/panelbench/dashboard/context.py b/src/panelbench/dashboard/context.py
index cbb5ec5..6a327ed 100644
--- a/src/panelbench/dashboard/context.py
+++ b/src/panelbench/dashboard/context.py
@@ -13,6 +13,7 @@
from panelbench.config_types import BESSConfigYAML
from panelbench.history import HistoryProvider
+ from panelbench.panel_secrets import PanelSecretsStore
async def _noop_modeling_data(
@@ -50,6 +51,8 @@ class DashboardContext:
ha_client: Any = None # HAClient | None — optional, set when HA API is available
history_provider: HistoryProvider | None = None
panel_browser: Any = None # PanelBrowser | None — mDNS discovery for standalone mode
+ # Source panels' passphrases and broker credentials; beside config_dir when None.
+ panel_secrets: PanelSecretsStore | None = None
# Why the active config could not be opened when the dashboard started, shown
# until the editor moves to another config.
load_error: str | None = None
diff --git a/src/panelbench/dashboard/keys.py b/src/panelbench/dashboard/keys.py
index 67348ef..fb96519 100644
--- a/src/panelbench/dashboard/keys.py
+++ b/src/panelbench/dashboard/keys.py
@@ -11,6 +11,7 @@
from panelbench.dashboard.config_store import ConfigStore
from panelbench.dashboard.context import DashboardContext
from panelbench.dashboard.presets import PresetRegistry
+from panelbench.panel_secrets import PanelSecretsStore
from panelbench.rates.cache import RateCache
APP_KEY_STORE = web.AppKey("store", ConfigStore)
@@ -20,3 +21,4 @@
"pending_clones", dict
)
APP_KEY_RATE_CACHE = web.AppKey("rate_cache", RateCache)
+APP_KEY_PANEL_SECRETS = web.AppKey("panel_secrets", PanelSecretsStore)
diff --git a/src/panelbench/dashboard/routes.py b/src/panelbench/dashboard/routes.py
index 6aae4db..d59c818 100644
--- a/src/panelbench/dashboard/routes.py
+++ b/src/panelbench/dashboard/routes.py
@@ -16,12 +16,14 @@
from ebus_panel_sim import EmitterError
if TYPE_CHECKING:
- from collections.abc import Awaitable, Callable
+ from collections.abc import Awaitable, Callable, Mapping
from pathlib import Path
import multidict
from panelbench.dashboard.context import DashboardContext
+ from panelbench.panel_secrets import PanelSecretsStore
+ from panelbench.scraper import SuppliedBroker
from datetime import UTC, datetime
from zoneinfo import ZoneInfo
@@ -31,6 +33,7 @@
from panelbench.dashboard.config_store import ConfigStore, EditRefused
from panelbench.dashboard.keys import (
APP_KEY_DASHBOARD_CONTEXT,
+ APP_KEY_PANEL_SECRETS,
APP_KEY_PENDING_CLONES,
APP_KEY_PRESET_REGISTRY,
APP_KEY_RATE_CACHE,
@@ -101,6 +104,10 @@ def _store(request: web.Request) -> ConfigStore:
return request.app[APP_KEY_STORE]
+def _panel_secrets(request: web.Request) -> PanelSecretsStore:
+ return request.app[APP_KEY_PANEL_SECRETS]
+
+
def _rate_cache(request: web.Request) -> RateCache:
return request.app[APP_KEY_RATE_CACHE]
@@ -266,11 +273,17 @@ def _presets_for_type(request: web.Request, entity_type: str) -> dict[str, str]:
return _presets(request).presets_for_type(entity_type)
-def _entity_list_context(request: web.Request, editing_id: str | None = None) -> dict[str, Any]:
+def _entity_list_context(
+ request: web.Request,
+ editing_id: str | None = None,
+ *,
+ restore_error: str | None = None,
+) -> dict[str, Any]:
"""Build the entity-list template context.
When *editing_id* is set, the template renders that entity in edit
- mode and all others as collapsed rows.
+ mode and all others as collapsed rows. *restore_error* says why a restore
+ from the source panel failed.
"""
store = _store(request)
dash_ctx = _ctx(request)
@@ -282,6 +295,7 @@ def _entity_list_context(request: web.Request, editing_id: str | None = None) ->
"unmapped_tabs": store.get_unmapped_tabs(),
"readonly": _is_readonly(dash_ctx),
"restorable_templates": set(recorder_map.keys()),
+ "restore_error": restore_error,
}
if editing_id is not None:
entity = store.get_entity(editing_id)
@@ -1472,9 +1486,13 @@ async def handle_toggle_replay(request: web.Request) -> web.Response:
if entity.user_modified:
# SYN → REC: full restore
- if not store.restore_recorder(entity_id):
- await _rescrape_snapshots(request)
- store.restore_recorder(entity_id)
+ failure = await _restore_recorder(request, entity_id)
+ if failure is not None:
+ return _render(
+ "partials/entity_list.html",
+ request,
+ _entity_list_context(request, restore_error=failure),
+ )
_persist_config(request)
else:
# REC → SYN: flip the flag and persist so the engine matches the UI
@@ -1491,40 +1509,59 @@ async def handle_restore_recorder(request: web.Request) -> web.Response:
needed — no other templates are touched.
"""
entity_id = request.match_info["id"]
- store = _store(request)
- if not store.restore_recorder(entity_id):
- # No snapshot — try a targeted re-scrape
- await _rescrape_snapshots(request)
- store.restore_recorder(entity_id)
+ failure = await _restore_recorder(request, entity_id)
+ if failure is not None:
+ return _render(
+ "partials/entity_list.html",
+ request,
+ _entity_list_context(request, restore_error=failure),
+ )
_persist_config(request)
return _render("partials/entity_list.html", request, _entity_list_context(request))
+async def _restore_recorder(request: web.Request, entity_id: str) -> str | None:
+ """Restore *entity_id* from its snapshot, re-scraping the source panel for one.
+
+ Answers why the restore failed, or None. A re-scrape that fails is reported, as
+ a sync's is, rather than leaving the circuit as it was without a word.
+ """
+ from panelbench.scraper import ScrapeError
+
+ store = _store(request)
+ if store.restore_recorder(entity_id):
+ return None
+ try:
+ await _rescrape_snapshots(request)
+ except ScrapeError as exc:
+ return f"Restore failed: [{exc.phase}] {exc}"
+ store.restore_recorder(entity_id)
+ return None
+
+
async def _rescrape_snapshots(request: web.Request) -> None:
- """Re-scrape source panel and store snapshots without modifying templates."""
+ """Re-scrape source panel and store snapshots without modifying templates.
+
+ Raises:
+ ScrapeError: The config has no source panel, or it could not be scraped.
+ """
import copy
from panelbench.clone import translate_scraped_panel
- from panelbench.scraper import register_with_panel, scrape_ebus
+ from panelbench.scraper import ScrapeError, scrape_panel
store = _store(request)
panel_source = store.get_panel_source()
if not panel_source:
- return
+ raise ScrapeError("source", "This config was not cloned from a panel")
host = panel_source.get("host", "")
- passphrase = panel_source.get("passphrase")
-
- try:
- creds, ca_pem = await register_with_panel(host, passphrase)
- scraped = await scrape_ebus(creds, ca_pem)
- except Exception:
- return
+ scraped = await scrape_panel(host, _panel_secrets(request))
# Build a fresh config to get original template values
- fresh = translate_scraped_panel(scraped, host=host, passphrase=passphrase)
+ fresh = translate_scraped_panel(scraped, host=host)
fresh_templates = fresh.get("circuit_templates")
if not isinstance(fresh_templates, dict):
return
@@ -1831,7 +1868,7 @@ async def handle_clone(request: web.Request) -> web.Response:
# is written as the loader reads it, a stale rating copy already gone, rather
# than warning every reader after; content the loader changes nothing in keeps
# its text, comments and all.
- clone = ConfigStore()
+ clone = ConfigStore(secrets=_panel_secrets(request))
try:
clone.load_from_yaml(yaml_content, source=str(output_path))
except (ValueError, TypeError, yaml.YAMLError) as exc:
@@ -1904,7 +1941,7 @@ async def handle_get_panel_source(request: web.Request) -> web.Response:
async def handle_sync_panel_source(request: web.Request) -> web.Response:
"""Re-scrape the source panel and overwrite typical_power + energy seeds."""
- from panelbench.scraper import ScrapeError, register_with_panel, scrape_ebus
+ from panelbench.scraper import ScrapeError, scrape_panel
store = _store(request)
panel_source = store.get_panel_source()
@@ -1915,11 +1952,9 @@ async def handle_sync_panel_source(request: web.Request) -> web.Response:
)
host = panel_source.get("host", "")
- passphrase = panel_source.get("passphrase")
try:
- creds, ca_pem = await register_with_panel(host, passphrase)
- scraped = await scrape_ebus(creds, ca_pem)
+ scraped = await scrape_panel(host, _panel_secrets(request))
except ScrapeError as exc:
return web.Response(
text=f'Sync failed: [{exc.phase}] {exc}
',
@@ -2181,6 +2216,47 @@ async def handle_delete_config(request: web.Request) -> web.Response:
)
+_SPAN_MQTTS_PORT = 8883
+
+
+def _supplied_broker(form: Mapping[str, object]) -> SuppliedBroker | None:
+ """Broker credentials the clone form was given in place of registering, if any.
+
+ All of serial, username and password, or none of them; the port defaults to
+ the one SPAN's broker listens on, and a blank CA is fetched from the panel.
+
+ Raises:
+ ValueError: Some of the three were given, but not all.
+ """
+ from panelbench.scraper import SuppliedBroker
+
+ fields = {
+ key: str(form.get(key, "")).strip()
+ for key in ("broker_serial", "broker_username", "broker_password")
+ }
+ if not any(fields.values()):
+ return None
+ missing = [key.removeprefix("broker_") for key, value in fields.items() if not value]
+ if missing:
+ raise ValueError(
+ "Existing broker credentials need the panel's serial, a username and a "
+ f"password; missing: {', '.join(missing)}."
+ )
+ port_text = str(form.get("broker_port", "")).strip()
+ try:
+ port = int(port_text) if port_text else _SPAN_MQTTS_PORT
+ except ValueError:
+ raise ValueError(f"The broker port must be a number, not {port_text!r}.") from None
+ ca_pem = str(form.get("broker_ca", "")).strip()
+ return SuppliedBroker(
+ serial=fields["broker_serial"],
+ username=fields["broker_username"],
+ password=fields["broker_password"],
+ port=port,
+ ca_pem=f"{ca_pem}\n" if ca_pem else None,
+ )
+
+
def _clone_panel_context(request: web.Request, **extra: object) -> dict[str, Any]:
"""Build the clone panel section template context."""
ctx = _ctx(request)
@@ -2386,7 +2462,7 @@ async def handle_clone_from_panel(request: web.Request) -> web.Response:
clone_config_path,
translate_scraped_panel,
)
- from panelbench.scraper import ScrapeError, register_with_panel, scrape_ebus
+ from panelbench.scraper import ScrapeError, scrape_panel
data = await request.post()
host = str(data.get("host", "")).strip()
@@ -2399,20 +2475,19 @@ async def handle_clone_from_panel(request: web.Request) -> web.Response:
_clone_panel_context(request, clone_error="Panel IP or hostname is required."),
)
- if not passphrase:
+ try:
+ supplied = _supplied_broker(data)
+ except ValueError as exc:
return _render(
"partials/clone_panel.html",
request,
- _clone_panel_context(
- request,
- clone_error="Passphrase is required.",
- clone_host=host,
- ),
+ _clone_panel_context(request, clone_error=str(exc), clone_host=host),
)
try:
- creds, ca_pem = await register_with_panel(host, passphrase)
- scraped = await scrape_ebus(creds, ca_pem)
+ scraped = await scrape_panel(
+ host, _panel_secrets(request), passphrase=passphrase, supplied=supplied
+ )
except ScrapeError as exc:
return _render(
"partials/clone_panel.html",
@@ -2424,7 +2499,7 @@ async def handle_clone_from_panel(request: web.Request) -> web.Response:
),
)
- config = translate_scraped_panel(scraped, host=host, passphrase=passphrase)
+ config = translate_scraped_panel(scraped, host=host)
ctx = _ctx(request)
@@ -2440,13 +2515,20 @@ async def handle_clone_from_panel(request: web.Request) -> web.Response:
panel_cfg["longitude"] = lon
# Derive IANA timezone from coordinates so profile
- # builder can bucket hour_factors in local time.
- from timezonefinder import TimezoneFinder
-
- tz_result = TimezoneFinder().timezone_at(lat=lat, lng=lon)
- tz_name = str(tz_result) if tz_result else "America/Los_Angeles"
- panel_cfg["time_zone"] = tz_name
- _LOGGER.info("Applied HA home location: %.4f, %.4f → %s", lat, lon, tz_name)
+ # builder can bucket hour_factors in local time, unless the
+ # panel published its own, which the clone already holds.
+ if "time_zone" not in panel_cfg:
+ from timezonefinder import TimezoneFinder
+
+ tz_result = TimezoneFinder().timezone_at(lat=lat, lng=lon)
+ tz_name = str(tz_result) if tz_result else "America/Los_Angeles"
+ panel_cfg["time_zone"] = tz_name
+ _LOGGER.info(
+ "Applied HA home location: %.4f, %.4f → %s",
+ lat,
+ lon,
+ panel_cfg["time_zone"],
+ )
except Exception:
_LOGGER.debug("Could not fetch HA location", exc_info=True)
diff --git a/src/panelbench/dashboard/templates/partials/clone_panel.html b/src/panelbench/dashboard/templates/partials/clone_panel.html
index f6bda1d..2434f1b 100644
--- a/src/panelbench/dashboard/templates/partials/clone_panel.html
+++ b/src/panelbench/dashboard/templates/partials/clone_panel.html
@@ -36,12 +36,36 @@ Clone from Panel
{% endif %}
⏳