franklinwh-system-view 0.1.0__tar.gz

franklinwh_system_view-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 david2069
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

franklinwh_system_view-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: franklinwh-system-view
+Version: 0.1.0
+Summary: A friendly picture of a FranklinWH site (grid, aGate, batteries, solar, home, circuits) shared by the FranklinWH bridges: payload schema, layout and the overlay page
+Author: david2069
+License: MIT
+Project-URL: Source, https://github.com/david2069/franklinwh-system-view
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# franklinwh-system-view
+
+A friendly picture of a FranklinWH site, shared by the FranklinWH bridges: grid, aGate,
+batteries, solar, home, smart circuits and generator, with live flows. It opens as a
+full-page overlay over a bridge's own dashboard, and can be the page a browser starts on.
+
+- **Simple by default.** Pictures and plain words: battery charge, mode, what the inverter
+  is doing, grid up or down, solar, home use, circuits. Hover for a sentence, click for details.
+- **Fits any screen.** Desktop and tablet get a landscape layout, phones a portrait one.
+  Zoom with − / Fit / +, pinch, or Ctrl+wheel; drag to pan when zoomed.
+- **Colours mean state.** Green normal, grey offline or disabled, amber warning, red critical.
+- **Only what's there is drawn.** A site with no solar shows no solar.
+
+## How a bridge uses it
+
+```python
+from fastapi.staticfiles import StaticFiles
+import franklinwh_system_view as sv
+
+app.mount("/system-view", StaticFiles(directory=sv.static_dir()), name="system-view")
+
+@app.get("/api/system")
+def api_system():
+    return sv.build(my_payload())      # validates, then adds both layouts per gateway
+```
+
+```html
+<link rel="stylesheet" href="system-view/system-view.css">
+<script src="system-view/system-view.js"></script>
+<script>FWHSystemView.mount({endpoint: "api/system"});</script>
+<button onclick="FWHSystemView.open()">System view</button>
+```
+
+The payload is described in `schema.py`; `fixtures/` holds examples. Signs: grid
+`power_w` > 0 imports, battery `power_w` > 0 discharges. Leave out what you can't read.
+
+## Try it
+
+```bash
+python -m franklinwh_system_view.demo us_tou_two_apowers_solar
+```
+
+Design: franklinwh-direct-connect-bridge #428.

franklinwh_system_view-0.1.0/README.md

@@ -0,0 +1,43 @@
+# franklinwh-system-view
+
+A friendly picture of a FranklinWH site, shared by the FranklinWH bridges: grid, aGate,
+batteries, solar, home, smart circuits and generator, with live flows. It opens as a
+full-page overlay over a bridge's own dashboard, and can be the page a browser starts on.
+
+- **Simple by default.** Pictures and plain words: battery charge, mode, what the inverter
+  is doing, grid up or down, solar, home use, circuits. Hover for a sentence, click for details.
+- **Fits any screen.** Desktop and tablet get a landscape layout, phones a portrait one.
+  Zoom with − / Fit / +, pinch, or Ctrl+wheel; drag to pan when zoomed.
+- **Colours mean state.** Green normal, grey offline or disabled, amber warning, red critical.
+- **Only what's there is drawn.** A site with no solar shows no solar.
+
+## How a bridge uses it
+
+```python
+from fastapi.staticfiles import StaticFiles
+import franklinwh_system_view as sv
+
+app.mount("/system-view", StaticFiles(directory=sv.static_dir()), name="system-view")
+
+@app.get("/api/system")
+def api_system():
+    return sv.build(my_payload())      # validates, then adds both layouts per gateway
+```
+
+```html
+<link rel="stylesheet" href="system-view/system-view.css">
+<script src="system-view/system-view.js"></script>
+<script>FWHSystemView.mount({endpoint: "api/system"});</script>
+<button onclick="FWHSystemView.open()">System view</button>
+```
+
+The payload is described in `schema.py`; `fixtures/` holds examples. Signs: grid
+`power_w` > 0 imports, battery `power_w` > 0 discharges. Leave out what you can't read.
+
+## Try it
+
+```bash
+python -m franklinwh_system_view.demo us_tou_two_apowers_solar
+```
+
+Design: franklinwh-direct-connect-bridge #428.

franklinwh_system_view-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "franklinwh-system-view"
+version = "0.1.0"
+description = "A friendly picture of a FranklinWH site (grid, aGate, batteries, solar, home, circuits) shared by the FranklinWH bridges: payload schema, layout and the overlay page"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "david2069"}]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[project.urls]
+Source = "https://github.com/david2069/franklinwh-system-view"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+franklinwh_system_view = ["static/*", "fixtures/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

franklinwh_system_view-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

franklinwh_system_view-0.1.0/src/franklinwh_system_view/__init__.py

@@ -0,0 +1,40 @@
+"""The FranklinWH System view: one picture of a site's hardware, shared by both bridges.
+
+A bridge builds a payload (``schema``), the layout turns each gateway into a scene, and the
+page in ``static/`` draws it as an overlay over the bridge's own UI.
+"""
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+from .layout import scene
+from .schema import SCHEMA_VERSION, validate
+
+__version__ = "0.1.0"
+__all__ = ["SCHEMA_VERSION", "build", "fixture", "scene", "static_dir", "validate"]
+
+
+def static_dir() -> Path:
+    """The folder a bridge serves at ``/system-view/`` (system-view.js and .css)."""
+    return Path(str(resources.files(__package__) / "static"))
+
+
+def build(payload: dict) -> dict:
+    """``payload`` plus both scenes for every gateway, ready to send to the page.
+
+    Raises ``ValueError`` listing every problem when the payload is invalid.
+    """
+    errs = validate(payload)
+    if errs:
+        raise ValueError("; ".join(errs))
+    out = dict(payload)
+    out["gateways"] = [dict(g, scenes={o: scene(g, o) for o in ("landscape", "portrait")})
+                       for g in payload["gateways"]]
+    return out
+
+
+def fixture(name: str) -> dict:
+    """An example payload shipped with the package (see ``fixtures/``), for tests and demos."""
+    import json
+    return json.loads((resources.files(__package__) / "fixtures" / f"{name}.json").read_text())

franklinwh_system_view-0.1.0/src/franklinwh_system_view/demo.py

@@ -0,0 +1,69 @@
+"""See the System view without a bridge: ``python -m franklinwh_system_view.demo [fixture] [port]``.
+
+Serves a stand-in "standard dashboard" with a System view button, the overlay's files,
+and ``/api/system`` built from one of the shipped example payloads.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from . import build, fixture, static_dir
+
+PAGE = """<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>System view demo</title><link rel="stylesheet" href="/system-view/system-view.css">
+<style>body{font-family:system-ui,sans-serif;margin:0;padding:16px;background:#121924;color:#e4e9f0}</style></head>
+<body><header style="display:flex;gap:12px;align-items:center"><h1 style="margin:0;font-size:1.2rem">Standard dashboard</h1>
+<button id="open" type="button">System view</button></header>
+<p>This stands in for a bridge's own dashboard.</p>
+<script src="/system-view/system-view.js"></script>
+<script>FWHSystemView.mount({endpoint: "/api/system" + location.search});
+document.getElementById("open").onclick = () => FWHSystemView.open();</script></body></html>"""
+
+
+def make_handler(default: str):
+    class H(BaseHTTPRequestHandler):
+        def log_message(self, *a):  # quiet
+            pass
+
+        def _send(self, code, body, ctype):
+            data = body if isinstance(body, bytes) else body.encode()
+            self.send_response(code)
+            self.send_header("Content-Type", ctype)
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
+        def do_GET(self):
+            u = urlparse(self.path)
+            if u.path == "/":
+                return self._send(200, PAGE, "text/html; charset=utf-8")
+            if u.path == "/favicon.ico":
+                return self._send(204, b"", "image/x-icon")
+            if u.path == "/api/system":
+                name = parse_qs(u.query).get("fixture", [default])[0]
+                try:
+                    return self._send(200, json.dumps(build(fixture(name))), "application/json")
+                except FileNotFoundError:
+                    return self._send(404, json.dumps({"detail": f"no fixture {name!r}"}), "application/json")
+            if u.path.startswith("/system-view/"):
+                f = static_dir() / u.path.rsplit("/", 1)[-1]
+                if f.is_file():
+                    ctype = "text/css" if f.suffix == ".css" else "text/javascript"
+                    return self._send(200, f.read_bytes(), ctype)
+            return self._send(404, "not found", "text/plain")
+    return H
+
+
+def serve(default: str = "us_backup_no_solar", port: int = 8765) -> ThreadingHTTPServer:
+    return ThreadingHTTPServer(("127.0.0.1", port), make_handler(default))
+
+
+if __name__ == "__main__":
+    name = sys.argv[1] if len(sys.argv) > 1 else "us_backup_no_solar"
+    port = int(sys.argv[2]) if len(sys.argv) > 2 else 8765
+    print(f"http://127.0.0.1:{port}/  (fixture {name}; add ?fixture=<name> to switch)")
+    serve(name, port).serve_forever()

franklinwh_system_view-0.1.0/src/franklinwh_system_view/fixtures/au_single_phase.json

@@ -0,0 +1,7 @@
+{"version": 1, "site": {"name": "Example home", "timezone": "Australia/Sydney"},
+ "gateways": [{"id": "gw1", "name": "aGate", "kind": "agate", "online": true,
+   "mode": "Self-Consumption", "inverter": "Discharging", "reserve_pct": 20,
+   "grid": {"state": "connected", "power_w": -300, "voltage_v": 242.9, "freq_hz": 50.01, "legs_v": [242.9]},
+   "home": {"power_w": 900}, "battery": {"soc_pct": 74, "power_w": 400, "count": 1},
+   "solar": [{"id": "solar", "where": "agate", "power_w": 800}],
+   "circuits": [{"id": 1, "name": "Circuit 1", "on": true}, {"id": 2, "name": "Circuit 2", "on": false}]}]}

franklinwh_system_view-0.1.0/src/franklinwh_system_view/fixtures/offline.json

@@ -0,0 +1,4 @@
+{"version": 1, "site": {"name": "Example home"},
+ "gateways": [{"id": "gw1", "name": "aGate", "kind": "agate", "online": false,
+   "mode": null, "inverter": null, "grid": {"state": "unknown", "power_w": null},
+   "home": {"power_w": null}, "battery": {"soc_pct": null, "power_w": null}, "solar": [], "circuits": []}]}

franklinwh_system_view-0.1.0/src/franklinwh_system_view/fixtures/six_apowers.json

@@ -0,0 +1,10 @@
+{"version": 1, "site": {"name": "Example home"},
+ "gateways": [{"id": "gw1", "name": "aGate", "kind": "agate", "online": true,
+   "mode": "Self-Consumption", "inverter": "Discharging",
+   "grid": {"state": "connected", "power_w": 120}, "home": {"power_w": 6100},
+   "battery": {"soc_pct": 71, "power_w": 6000, "count": 6, "units": [
+     {"id": "u1", "soc_pct": 72, "power_w": 1000}, {"id": "u2", "soc_pct": 70, "power_w": 1000},
+     {"id": "u3", "soc_pct": 71, "power_w": 1000, "state": "warn"}, {"id": "u4", "soc_pct": 71, "power_w": 1000},
+     {"id": "u5", "soc_pct": 70, "power_w": 1000}, {"id": "u6", "soc_pct": 72, "power_w": 1000}]},
+   "solar": [{"id": "pv1", "where": "agate", "power_w": 2000}, {"id": "pv2", "where": "apbox", "power_w": 1500}],
+   "circuits": []}]}

franklinwh_system_view-0.1.0/src/franklinwh_system_view/fixtures/us_backup_no_solar.json

@@ -0,0 +1,8 @@
+{"version": 1, "site": {"name": "Example home", "timezone": "America/Los_Angeles"},
+ "gateways": [{"id": "gw1", "name": "aGate", "kind": "agate", "online": true,
+   "mode": "Emergency Backup", "inverter": "Standby", "reserve_pct": 100,
+   "grid": {"state": "connected", "power_w": 820, "voltage_v": 241.6, "freq_hz": 60.0, "legs_v": [120.8, 120.8]},
+   "home": {"power_w": 820},
+   "battery": {"soc_pct": 100, "power_w": 0, "count": 1},
+   "solar": [],
+   "circuits": [{"id": 1, "name": "Circuit 1", "on": true}, {"id": 2, "name": "Circuit 2", "on": true}, {"id": 3, "name": "Circuit 3", "on": false}]}]}

franklinwh_system_view-0.1.0/src/franklinwh_system_view/fixtures/us_outage.json

@@ -0,0 +1,7 @@
+{"version": 1, "site": {"name": "Example home", "timezone": "America/Denver"},
+ "gateways": [{"id": "gw1", "name": "aGate", "kind": "agate", "online": true,
+   "mode": "Emergency Backup", "inverter": "Off-grid", "reserve_pct": 100,
+   "grid": {"state": "outage", "power_w": 0, "voltage_v": null, "freq_hz": null},
+   "home": {"power_w": 1900},
+   "battery": {"soc_pct": 86, "power_w": 1900, "count": 1},
+   "solar": [], "circuits": [], "generator": {"power_w": 0}}]}

franklinwh_system_view-0.1.0/src/franklinwh_system_view/fixtures/us_tou_two_apowers_solar.json

@@ -0,0 +1,8 @@
+{"version": 1, "site": {"name": "Example home", "timezone": "America/Los_Angeles"},
+ "gateways": [{"id": "gw1", "name": "aGate", "kind": "agate", "online": true,
+   "mode": "Time-of-Use", "inverter": "Charging", "reserve_pct": 20,
+   "grid": {"state": "connected", "power_w": 0, "voltage_v": 240.2, "freq_hz": 60.0, "legs_v": [120.1, 120.1]},
+   "home": {"power_w": 1300},
+   "battery": {"soc_pct": 62, "power_w": -2900, "count": 2},
+   "solar": [{"id": "solar", "where": "agate", "power_w": 4200}],
+   "circuits": [{"id": 1, "name": "Circuit 1", "on": true}, {"id": 2, "name": "Circuit 2", "on": true}, {"id": 3, "name": "Circuit 3", "on": true}]}]}

franklinwh_system_view-0.1.0/src/franklinwh_system_view/layout.py

@@ -0,0 +1,279 @@
+"""Turn one gateway's payload into a scene: positioned pictures and the wires between them.
+
+The layout is computed here, in Python, so both bridges draw the same picture and the
+arrangement is tested without a browser. The page only renders the scene.
+
+Two arrangements: ``landscape`` (desktop and tablet) and ``portrait`` (phones). Only what
+the payload reports is drawn; a gateway with no solar has no solar picture.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+#: Below this a flow is drawn idle, so meter noise doesn't animate a wire.
+FLOW_W = 50
+#: Batteries drawn one by one; more than this collapse into one "+N more" card.
+MAX_UNITS = 4
+MAX_SOLAR = 3
+
+
+def kw(w: Any) -> str:
+    return "–" if w is None else f"{abs(w) / 1000:.2f} kW"
+
+
+def _flow(w: Any, *, reverse: bool = False) -> str:
+    if w is None or abs(w) < FLOW_W:
+        return "idle"
+    forward = (w > 0) != reverse
+    return "fwd" if forward else "rev"
+
+
+def _node(id_, icon, x, y, w, h, label, *, value="", status="", state="ok", frame=True,
+          hover="", rows=None, soc=None, card=False, sub="") -> dict:
+    """``foot`` is the height including the text under the picture; wires leave below it."""
+    foot = h if card else h + 22 + (24 if value else 0) + 18 + (16 if sub else 0) + 8
+    n = {"id": id_, "icon": icon, "x": x, "y": y, "w": w, "h": h, "foot": foot, "label": label,
+         "value": value, "status": status, "state": state, "frame": frame,
+         "hover": hover, "rows": rows or [], "soc": soc, "card": card}
+    if sub:
+        n["sub"] = sub
+    return n
+
+
+def _wire(a: dict, b: dict, flow: str, *, dc: bool = False, side_a="c", side_b="c") -> dict:
+    """An orthogonal wire from ``a`` to ``b``; ``flow`` "fwd" runs a→b, "rev" b→a."""
+    def anchor(n, side):
+        cx, cy = n["x"] + n["w"] / 2, n["y"] + n["h"] / 2
+        return {"l": (n["x"], cy), "r": (n["x"] + n["w"], cy), "t": (cx, n["y"]),
+                "b": (cx, n["y"] + n["foot"]), "c": (cx, cy)}[side]
+    (x1, y1), (x2, y2) = anchor(a, side_a), anchor(b, side_b)
+    if side_a in "lr" and side_b in "lr":
+        mx = (x1 + x2) / 2
+        d = f"M{x1:g} {y1:g} H{mx:g} V{y2:g} H{x2:g}"
+    elif side_a in "tb" and side_b in "tb":
+        my = (y1 + y2) / 2
+        d = f"M{x1:g} {y1:g} V{my:g} H{x2:g} V{y2:g}"
+    elif side_a in "lr":
+        d = f"M{x1:g} {y1:g} H{x2:g} V{y2:g}"
+    else:
+        d = f"M{x1:g} {y1:g} V{y2:g} H{x2:g}"
+    return {"from": a["id"], "to": b["id"], "d": d, "flow": flow, "dc": dc}
+
+
+# ── the objects, independent of arrangement ──────────────────────────────────────
+
+def _grid(g: dict) -> dict | None:
+    grid = g.get("grid")
+    if grid is None or "grid" in (g.get("unavailable") or []):
+        return None
+    st = grid.get("state", "unknown")
+    p = grid.get("power_w")
+    if st == "outage":
+        return {"icon": "gridout", "label": "Grid", "value": kw(0), "status": "Outage",
+                "state": "crit", "hover": "The grid is down. Your batteries are powering the backed-up circuits.",
+                "rows": [["State", "Outage"]], "flow": "off"}
+    word = ("Importing" if p and p >= FLOW_W else "Exporting" if p and p <= -FLOW_W else "Idle")
+    rows = [["State", "Connected" if st != "unknown" else "Unknown"], ["Right now", f"{word} {kw(p)}" if word != "Idle" else "Idle"]]
+    if grid.get("voltage_v") is not None:
+        rows.append(["Voltage", f"{grid['voltage_v']:.1f} V"])
+    if grid.get("freq_hz") is not None:
+        rows.append(["Frequency", f"{grid['freq_hz']:.2f} Hz"])
+    if st == "spike":
+        return {"icon": "gridspike", "label": "Grid", "value": kw(p), "status": "Voltage spike",
+                "state": "warn", "hover": "Your aGate reported a grid voltage spike. The grid is still connected.",
+                "rows": rows, "flow": _flow(p)}
+    hover = {"Importing": f"The grid is up. You are importing {kw(p)}.",
+             "Exporting": f"The grid is up. You are exporting {kw(p)}.",
+             "Idle": "The grid is up. Almost nothing is flowing to or from it right now."}[word]
+    return {"icon": "pylon", "label": "Grid", "value": kw(p), "status": "Connected" if st != "unknown" else "Unknown",
+            "state": "ok" if st != "unknown" else "off", "hover": hover, "rows": rows, "flow": _flow(p)}
+
+
+def _agate(g: dict) -> dict:
+    mode, inv = g.get("mode"), g.get("inverter")
+    online = g.get("online")
+    rows = [["Mode", mode or "–"], ["Inverter", inv or "–"]]
+    if g.get("reserve_pct") is not None:
+        rows.append(["Backup reserve", f"{g['reserve_pct']:g} %"])
+    if not online:
+        return {"icon": "battery", "label": g.get("name") or "aGate", "status": "Offline", "state": "off",
+                "hover": "The bridge can't reach this aGate right now.", "rows": rows}
+    hover = f"Your aGate is in {mode}." if mode else "Your aGate is online."
+    if mode == "Emergency Backup":
+        hover += " The batteries are kept ready for an outage."
+    if inv:
+        hover += f" Inverter: {inv.lower()}."
+    return {"icon": "battery", "label": g.get("name") or "aGate", "status": mode or "Online",
+            "sub": inv or "", "state": "ok", "hover": hover, "rows": rows}
+
+
+def _home(g: dict) -> dict | None:
+    home = g.get("home")
+    if home is None:
+        return None
+    p = home.get("power_w")
+    return {"icon": "house", "label": "Home", "value": kw(p), "status": "Using", "state": "ok",
+            "hover": f"Your home is using {kw(p)}.", "rows": [["Using now", kw(p)]], "flow": _flow(p)}
+
+
+def _solars(g: dict) -> list[dict]:
+    out = []
+    arrays = g.get("solar") or []
+    for i, s in enumerate(arrays[:MAX_SOLAR]):
+        p = s.get("power_w")
+        name = s.get("name") or ("Solar" if len(arrays) == 1 else f"Solar {i + 1}")
+        producing = p is not None and p >= FLOW_W
+        out.append({"id": s.get("id") or f"solar{i}", "icon": "solar", "label": name, "value": kw(p),
+                    "status": "Producing" if producing else "Not producing",
+                    "state": "ok" if producing else "off",
+                    "hover": f"{name} is producing {kw(p)}." if producing else f"{name} isn't producing right now.",
+                    "rows": [["Now", kw(p)]], "flow": _flow(p), "dc": s.get("where") == "apower"})
+    return out
+
+
+def _batteries(g: dict) -> list[dict]:
+    bat = g.get("battery")
+    if bat is None:
+        return []
+    units = bat.get("units") or []
+
+    def card(id_, name, soc, p, state="ok"):
+        soc = None if soc is None else round(soc)      # the ring, the sentence and the table agree
+        word = "Discharging" if p and p >= FLOW_W else "Charging" if p and p <= -FLOW_W else "Idle"
+        status = {"warn": "Warning", "crit": "Fault", "off": "Offline"}.get(state, word)
+        hover = f"{name} is {soc:g} % full" if soc is not None else name
+        hover += {"Discharging": f" and discharging {kw(p)}.", "Charging": f" and charging {kw(p)}.",
+                  "Idle": " and idle."}.get(word, ".") if state == "ok" else f". {status}."
+        return {"id": id_, "icon": "apower", "label": name, "value": kw(p) if word != "Idle" else "",
+                "status": status, "state": state, "soc": soc, "hover": hover,
+                "rows": [["Charge", "–" if soc is None else f"{soc:g} %"], ["Now", status if word == "Idle" or state != "ok" else f"{word} {kw(p)}"]],
+                "flow": "off" if state == "off" else _flow(p, reverse=True)}
+
+    if not units:
+        n = bat.get("count")
+        name = "Batteries" if (n or 0) > 1 else "Battery"
+        if n and n > 1:
+            name = f"Batteries ×{n}"
+        return [card("battery", name, bat.get("soc_pct"), bat.get("power_w"))]
+    cards = [card(u.get("id") or f"bat{i}", u.get("name") or f"Battery {i + 1}", u.get("soc_pct"),
+                  u.get("power_w"), u.get("state", "ok")) for i, u in enumerate(units)]
+    if len(cards) > MAX_UNITS:
+        rest = cards[MAX_UNITS - 1:]
+        more = card("battery_more", f"+{len(rest)} more", None, sum(c_p for c_p in
+                    (u.get("power_w") or 0 for u in units[MAX_UNITS - 1:])))
+        more["hover"] = f"{len(rest)} more batteries. Open the Battery tab for each one."
+        cards = cards[:MAX_UNITS - 1] + [more]
+    return cards
+
+
+def _circuits(g: dict) -> list[dict]:
+    out = []
+    for i, c in enumerate(g.get("circuits") or []):
+        on = c.get("on")
+        name = c.get("name") or f"Circuit {i + 1}"
+        out.append({"id": f"sc{c.get('id', i + 1)}", "icon": "toggle" if on else "toggleoff",
+                    "label": name, "value": kw(c["power_w"]) if c.get("power_w") is not None else "",
+                    "status": "On" if on else "Off" if on is False else "Unknown",
+                    "state": "ok" if on else "off",
+                    "hover": f"{name} is {'on' if on else 'off'}." if on is not None else f"{name}: state unknown.",
+                    "rows": [["State", "On" if on else "Off"]], "flow": "fwd" if on else "idle"})
+    return out
+
+
+def _generator(g: dict) -> dict | None:
+    gen = g.get("generator")
+    if gen is None:
+        return None
+    p = gen.get("power_w")
+    running = p is not None and p >= FLOW_W
+    return {"icon": "gen", "label": "Generator", "value": kw(p) if running else "",
+            "status": "Running" if running else gen.get("status") or "Standby",
+            "state": "ok" if running else "off",
+            "hover": f"The generator is supplying {kw(p)}." if running else "The generator is on standby.",
+            "rows": [["State", "Running" if running else "Standby"]], "flow": _flow(p)}
+
+
+# ── arrangements ──────────────────────────────────────────────────────────────
+
+def _place(spec: dict | None, id_, x, y, w, h, *, frame=True, card=False) -> dict | None:
+    if spec is None:
+        return None
+    return _node(spec.get("id", id_), spec["icon"], x, y, w, h, spec["label"],
+                 value=spec.get("value", ""), status=spec.get("status", ""), state=spec["state"],
+                 frame=frame, hover=spec["hover"], rows=spec["rows"], soc=spec.get("soc"),
+                 card=card, sub=spec.get("sub", ""))
+
+
+def scene(g: dict, orientation: str = "landscape") -> dict:
+    """Nodes and wires for one gateway, laid out for ``orientation``."""
+    if orientation not in ("landscape", "portrait"):
+        raise ValueError(f"orientation: 'landscape' or 'portrait', not {orientation!r}")
+    grid, agate, home = _grid(g), _agate(g), _home(g)
+    solars, bats, circs, gen = _solars(g), _batteries(g), _circuits(g), _generator(g)
+    nodes: list[dict] = []
+    wires: list[dict] = []
+    land = orientation == "landscape"
+
+    row = ([gen] if gen else []) + circs
+    if land:
+        A = _place(agate, "agate", 400, 250, 150, 150)
+        G = _place(grid, "grid", 70, 275, 100, 100, frame=False)
+        H = _place(home, "home", 425, 30, 100, 100, frame=False)
+        S = [_place(s, s["id"], 640 + i * 120, 30, 100, 90, frame=False) for i, s in enumerate(solars)]
+        B = [_place(b, b["id"], 660, 250 + i * 104, 280, 88, card=True) for i, b in enumerate(bats)]
+        below = max([A["y"] + A["foot"]] + [b["y"] + b["h"] for b in B])
+        C = [_place(c, c.get("id", "generator"), 240 + i * 120, below + 50, 90, 80) for i, c in enumerate(row)]
+        width = 1000
+    else:
+        A = _place(agate, "agate", 145, 220, 130, 130)
+        G = _place(grid, "grid", 20, 240, 90, 90, frame=False)
+        H = _place(home, "home", 310, 240, 90, 90, frame=False)
+        S = [_place(s, s["id"], 165 + (i - (len(solars) - 1) / 2) * 120, 20, 90, 80, frame=False)
+             for i, s in enumerate(solars)]
+        bus = A["y"] + A["foot"] + 12
+        B = [_place(b, b["id"], 110, bus + 28 + i * 98, 280, 84, card=True) for i, b in enumerate(bats)]
+        cy = (B[-1]["y"] + B[-1]["h"] + 46) if B else bus + 40
+        C = [_place(c, c.get("id", "generator"), 30 + (i % 3) * 125, cy + (i // 3) * 150, 90, 80)
+             for i, c in enumerate(row)]
+        width = 420
+
+    ax, ay, aw = A["x"], A["y"], A["w"]
+    amid, abot = ay + A["h"] / 2, ay + A["foot"]
+    nodes.append(A)
+    if G:
+        nodes.append(G)
+        wires.append(_wire(G, A, grid["flow"], side_a="r", side_b="l"))
+    if H:
+        nodes.append(H)
+        wires.append(_wire(A, H, home["flow"], side_a="t", side_b="b") if land
+                     else _wire(A, H, home["flow"], side_a="r", side_b="l"))
+    for k, (spec, n) in enumerate(zip(solars, S)):
+        nodes.append(n)
+        nx, nb = n["x"] + n["w"] / 2, n["y"] + n["foot"]
+        if land:    # down, then left into the aGate's right side, above the battery cards
+            ty = ay + 20 + k * 14
+            d = f"M{nx:g} {nb:g} V{nb + 16 + k * 6:g} H{ax + aw + 40 + k * 8:g} V{ty:g} H{ax + aw:g}"
+        else:       # straight down into the aGate's top
+            d = f"M{nx:g} {nb:g} V{nb + 14:g} H{ax + aw / 2 + (k - (len(S) - 1) / 2) * 16:g} V{ay:g}"
+        wires.append({"from": n["id"], "to": A["id"], "flow": spec["flow"], "dc": spec["dc"], "d": d})
+    for spec, n in zip(bats, B):
+        nodes.append(n)
+        my = n["y"] + n["h"] / 2
+        if land:
+            d = f"M{ax + aw:g} {amid + 30:g} H{n['x'] - 30:g} V{my:g} H{n['x']:g}"
+        else:       # a bus down the left edge, so no wire crosses a card
+            d = f"M{ax + aw / 2:g} {abot:g} V{bus:g} H70 V{my:g} H{n['x']:g}"
+        wires.append({"from": A["id"], "to": n["id"], "flow": spec["flow"], "dc": False, "d": d})
+    for spec, n in zip(row, C):
+        nodes.append(n)
+        flow = spec["flow"] if spec is not gen else ("rev" if spec["flow"] == "fwd" else spec["flow"])
+        nx, ny = n["x"] + n["w"] / 2, n["y"]
+        if land:
+            d = f"M{ax + aw / 2:g} {abot:g} V{ny - 22:g} H{nx:g} V{ny:g}"
+        else:       # a bus down the right edge, clear of the battery cards
+            d = f"M{ax + aw / 2:g} {abot:g} V{bus:g} H405 V{ny - 18:g} H{nx:g} V{ny:g}"
+        wires.append({"from": A["id"], "to": n["id"], "flow": flow, "dc": False, "d": d})
+
+    height = max(n["y"] + n["foot"] for n in nodes) + 24
+    return {"orientation": orientation, "width": width, "height": height,
+            "nodes": nodes, "wires": wires}