New panel design

tools/ha_discover.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+List the Home Assistant entities this project cares about.
+
+Used to pin down entity IDs before wiring them into the firmware, and to
+re-check them after changing something in HA -- entity IDs are not stable
+across integration renames, and a wrong one fails silently as "unavailable".
+
+    export HA_TOKEN='...'        # Profile -> Security -> Long-lived access token
+    python3 tools/ha_discover.py
+
+The token is read from the environment and never printed or written anywhere.
+
+    --host HOST     default 192.168.1.134
+    --all           every entity, not just the interesting domains
+    --json          raw JSON for the matched entities, including attributes
+"""
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+# The domains this display draws from. "sensor" is where a weather station's
+# individual measurements land; "weather" is the forecast entity; "sun" gives
+# sunrise/sunset; "light" is what we control.
+DEFAULT_DOMAINS = ("weather", "sun", "light", "sensor", "binary_sensor", "switch")
+
+
+def fetch(host: str, token: str, path: str):
+    req = urllib.request.Request(
+        f"http://{host}:8123{path}",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        return json.load(resp)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--host", default="192.168.1.134")
+    ap.add_argument("--all", action="store_true", help="include every domain")
+    ap.add_argument("--json", action="store_true", help="dump raw JSON with attributes")
+    args = ap.parse_args()
+
+    token = os.environ.get("HA_TOKEN")
+    if not token:
+        print("HA_TOKEN is not set.\n"
+              "In Home Assistant: click your user (bottom left) -> Security tab ->\n"
+              "Long-lived access tokens -> Create token. Then:\n"
+              "    export HA_TOKEN='paste-it-here'",
+              file=sys.stderr)
+        return 2
+
+    try:
+        states = fetch(args.host, token, "/api/states")
+    except urllib.error.HTTPError as e:
+        detail = "token rejected -- create a new long-lived token" if e.code == 401 else e.reason
+        print(f"HTTP {e.code} from {args.host}: {detail}", file=sys.stderr)
+        return 1
+    except urllib.error.URLError as e:
+        print(f"Cannot reach Home Assistant at {args.host}:8123 -- {e.reason}", file=sys.stderr)
+        return 1
+
+    matched = [
+        s for s in states
+        if args.all or s["entity_id"].split(".", 1)[0] in DEFAULT_DOMAINS
+    ]
+    matched.sort(key=lambda s: s["entity_id"])
+
+    if args.json:
+        print(json.dumps(matched, indent=2))
+        return 0
+
+    print(f"{len(matched)} entities on {args.host} "
+          f"(of {len(states)} total)\n")
+
+    by_domain: dict[str, list] = {}
+    for s in matched:
+        by_domain.setdefault(s["entity_id"].split(".", 1)[0], []).append(s)
+
+    for domain in sorted(by_domain):
+        entities = by_domain[domain]
+        print(f"=== {domain} ({len(entities)}) " + "=" * (46 - len(domain)))
+        for s in entities:
+            attrs = s.get("attributes", {})
+            name = attrs.get("friendly_name", "")
+            unit = attrs.get("unit_of_measurement", "")
+            state = s["state"]
+            if len(state) > 28:
+                state = state[:25] + "..."
+            print(f"  {s['entity_id']:<48} {state:>30} {unit:<6} {name}")
+        print()
+
+    # The forecast is not in /api/states -- it moved to a service call that
+    # returns a response. Flag which entities support it so we know what to ask.
+    weather = by_domain.get("weather", [])
+    if weather:
+        print("Forecast note: weather.* forecasts come from the")
+        print("  weather.get_forecasts service (POST /api/services/weather/get_forecasts")
+        print("  with ?return_response), not from /api/states. Candidates:")
+        for s in weather:
+            print(f"    {s['entity_id']}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())