Expose zone runtime context on the override sensor

The per-zone override sensor now carries compact runtime context so a
dashboard or automation can explain a zone without opening the panel:
runtime_state and control_mode, the Manual adjustment source, policy, start
and expiry, the effective Profile and schedule source, and the last target
Velair delivered with its source, time, action, temperature or range and
HVAC mode. The last-applied values are runtime only. A new
`get_zone_context` scheduler method backs the attributes; existing
attributes are unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJhD4sYeWQvoikjYP2CxUr

Author: Cloudore

custom_components/velair/scheduler.py

@@ -336,6 +336,8 @@ def __init__(
             _AppliedPreconditioningTarget,
         ] = {}
         self._preconditioning_sessions: dict[str, _PreconditioningSession] = {}
+        # Last target Velair delivered per zone (runtime only, for entity attributes).
+        self._last_applied: dict[str, dict[str, object]] = {}
         self._preconditioning_replan_entities: tuple[str, ...] = ()
         self._preconditioning_replan_temperatures: dict[str, float] = {}
         self._preconditioning_plan_snapshots: dict[str, tuple] = {}
@@ -887,6 +889,62 @@ def get_active_overrides(self) -> dict[str, dict]:
             and _is_boost_override(override)
         }
 
+    def get_zone_context(self, entity_id: str) -> dict[str, object]:
+        """Return compact runtime context for one zone's entity attributes.
+
+        This complements the override state with what dashboards and
+        automations most often need to explain a zone: the runtime state,
+        Automatic or Manual control with the Manual adjustment source and
+        policy, which Profile (if any) supplies the schedule, and the last
+        target Velair delivered together with its source.
+        """
+        zone = self._data["zones"].get(entity_id)
+        if zone is None:
+            return {}
+        now = dt_util.now()
+        context: dict[str, object] = {}
+        try:
+            runtime = self._zone_runtime_status(entity_id)
+        except Exception:  # pragma: no cover - defensive; attributes must not break
+            runtime = {}
+        if runtime.get("state") is not None:
+            context["runtime_state"] = runtime.get("state")
+        if runtime.get("control_mode") is not None:
+            context["control_mode"] = runtime.get("control_mode")
+        manual = self._manual_control_status(entity_id, now)
+        if manual is not None:
+            context["manual_source"] = manual.get("source")
+            context["manual_policy"] = manual.get("policy")
+            context["manual_since"] = manual.get("started_at")
+            if manual.get("until") is not None:
+                context["manual_until"] = manual.get("until")
+            changed = manual.get("changed_fields")
+            if changed:
+                context["manual_changed_fields"] = list(changed)
+        profile = self._active_profile_for_zone(entity_id)
+        behavior = self._profile_zone_behavior(entity_id)
+        if profile is not None:
+            context["effective_profile_id"] = profile.get("key")
+            context["effective_profile_name"] = profile.get("name")
+            context["schedule_source"] = (
+                "profile_pause" if behavior.get("behavior") == "pause" else "profile"
+            )
+        else:
+            context["schedule_source"] = "default"
+        applied = self._last_applied.get(entity_id)
+        if applied is not None:
+            context["last_applied_source"] = applied.get("source")
+            context["last_applied_at"] = applied.get("at")
+            context["last_applied_action"] = applied.get("action")
+            if applied.get("temperature") is not None:
+                context["last_applied_temperature"] = applied.get("temperature")
+            if applied.get("target_temp_low") is not None:
+                context["last_applied_target_temp_low"] = applied.get("target_temp_low")
+                context["last_applied_target_temp_high"] = applied.get("target_temp_high")
+            if applied.get("hvac_mode") is not None:
+                context["last_applied_hvac_mode"] = applied.get("hvac_mode")
+        return context
+
     def get_zone_override_status(self, entity_id: str) -> dict[str, object]:
         """Return the current override state for one managed zone."""
         zone = self._data["zones"].get(entity_id)
@@ -8734,6 +8792,15 @@ def _async_fire_climate_target_applied(
         if event.target_when is not None:
             data["target_when"] = event.target_when.isoformat()
 
+        self._last_applied[event.entity_id] = {
+            "source": source,
+            "at": dt_util.now().isoformat(),
+            "action": event.action,
+            "temperature": data.get("temperature"),
+            "target_temp_low": data.get(ATTR_TARGET_TEMP_LOW),
+            "target_temp_high": data.get(ATTR_TARGET_TEMP_HIGH),
+            "hvac_mode": hvac_mode,
+        }
         self._async_fire_climate_target_applied_data(data)
 
     def _async_fire_climate_target_applied_data(self, data: dict) -> None:

custom_components/velair/sensor.py

@@ -402,15 +402,32 @@ def native_value(self) -> str:
 
     @property
     def extra_state_attributes(self) -> dict[str, object] | None:
-        """Return compact active override context."""
+        """Return compact active override context plus zone runtime context."""
         status = self.scheduler.get_zone_override_status(self._climate_entity_id)
+        context_getter = getattr(self.scheduler, "get_zone_context", None)
+        context = context_getter(self._climate_entity_id) if callable(context_getter) else {}
         return _compact_attributes(
             {
-                key: status.get(key)
-                for key in (
-                    "started_at", "until", "action", "pause_id",
-                    "pause_count", "pause_ids", "manual",
-                )
+                **{
+                    key: status.get(key)
+                    for key in (
+                        "started_at", "until", "action", "pause_id",
+                        "pause_count", "pause_ids", "manual",
+                    )
+                },
+                **{
+                    key: context.get(key)
+                    for key in (
+                        "runtime_state", "control_mode", "manual_source",
+                        "manual_policy", "manual_since", "manual_until",
+                        "manual_changed_fields", "effective_profile_id",
+                        "effective_profile_name", "schedule_source",
+                        "last_applied_source", "last_applied_at",
+                        "last_applied_action", "last_applied_temperature",
+                        "last_applied_target_temp_low",
+                        "last_applied_target_temp_high", "last_applied_hvac_mode",
+                    )
+                },
             }
         )
 

docs/user/usage.md

@@ -93,7 +93,15 @@ automation events:
 - **Air quality** is created once per managed climate and keeps the independent
   CO2 assessment: good, elevated, poor, unavailable, or not monitored.
 - **Zone override** shows whether that climate currently has no override, an
-  active boost, or an active zone pause.
+  active boost, or an active zone pause. Its attributes also carry compact
+  runtime context so a dashboard can explain the zone without the panel:
+  `runtime_state`, `control_mode`, the Manual adjustment `manual_source`,
+  `manual_policy`, `manual_since` and `manual_until`, the
+  `effective_profile_id` / `effective_profile_name` and `schedule_source`
+  (`default`, `profile` or `profile_pause`), and the last target Velair
+  delivered (`last_applied_source`, `last_applied_at`, `last_applied_action`,
+  `last_applied_temperature` or range, `last_applied_hvac_mode`). The last
+  applied values are runtime only and start empty after a restart.
 - **Preconditioning start** is a timestamp sensor containing the calculated
   start for the next or currently active early-start block. Its attributes
   include the scheduled target time, lead, direction, model source, target

tests/backend/test_runtime_attributes.py

@@ -0,0 +1,157 @@
+"""Zone runtime context exposed through the override sensor attributes."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+import unittest
+
+from .helpers import (
+    NOW,
+    FakeClimateManager,
+    FakeHass,
+    VelairScheduler,
+    empty_week_schedule,
+    normalize_schedule_data,
+)
+from .test_sensor_entities import sensor_module
+
+
+class ZoneContextTest(unittest.IsolatedAsyncioTestCase):
+    def setUp(self) -> None:
+        self.entity_id = "climate.salon"
+        self.hass = FakeHass()
+        self.hass.states[self.entity_id] = SimpleNamespace(
+            state="cool",
+            attributes={"temperature": 24, "current_temperature": 26},
+        )
+        self.data = normalize_schedule_data(
+            {
+                "zones": {
+                    self.entity_id: {
+                        "enabled": True,
+                        "schedule": empty_week_schedule(),
+                    }
+                }
+            },
+            [self.entity_id],
+        )
+        self.data["zones"][self.entity_id]["schedule"]["tuesday"] = [
+            {
+                "start": "00:00",
+                "action": "set_temperature",
+                "temperature": 24.0,
+                "hvac_mode": "cool",
+            }
+        ]
+        self.scheduler = VelairScheduler(
+            self.hass, self.data, FakeClimateManager(), self._save
+        )
+        self.scheduler._climate_manager.current_hvac_modes[self.entity_id] = "cool"
+
+    async def _save(self) -> None:
+        return None
+
+    def test_context_before_any_delivery_is_compact(self) -> None:
+        context = self.scheduler.get_zone_context(self.entity_id)
+        self.assertEqual("default", context["schedule_source"])
+        self.assertEqual("automatic", context["control_mode"])
+        self.assertIn(context["runtime_state"], ("scheduled", "idle"))
+        self.assertNotIn("last_applied_source", context)
+        self.assertNotIn("manual_source", context)
+        self.assertEqual({}, self.scheduler.get_zone_context("climate.unknown"))
+
+    async def test_last_applied_target_is_recorded_with_its_source(self) -> None:
+        await self.scheduler.async_apply_current_schedule(self.entity_id)
+        context = self.scheduler.get_zone_context(self.entity_id)
+        self.assertEqual("current_schedule", context["last_applied_source"])
+        self.assertEqual(24.0, context["last_applied_temperature"])
+        self.assertEqual("set_temperature", context["last_applied_action"])
+        self.assertEqual("cool", context["last_applied_hvac_mode"])
+        self.assertTrue(str(context["last_applied_at"]).startswith(str(NOW.year)))
+
+    async def test_manual_adjustment_context_is_exposed(self) -> None:
+        await self.scheduler.async_update_external_change_policy(
+            self.entity_id, {"action": "until_resumed"}
+        )
+        await self.scheduler.async_handle_external_climate_change(
+            self.entity_id,
+            changed_fields=["temperature"],
+            previous={"temperature": 24.0},
+            current={"temperature": 20.0},
+        )
+        context = self.scheduler.get_zone_context(self.entity_id)
+        self.assertEqual("manual", context["control_mode"])
+        self.assertEqual("external_change", context["manual_source"])
+        self.assertEqual("until_resumed", context["manual_policy"])
+        self.assertEqual(["temperature"], context["manual_changed_fields"])
+        self.assertIn("manual_since", context)
+        self.assertNotIn("manual_until", context)
+
+        await self.scheduler.async_resume_automatic_control(self.entity_id)
+        context = self.scheduler.get_zone_context(self.entity_id)
+        self.assertEqual("automatic", context["control_mode"])
+        self.assertNotIn("manual_source", context)
+
+    def test_profile_context_is_exposed(self) -> None:
+        data = normalize_schedule_data(
+            {
+                "zones": {
+                    self.entity_id: {
+                        "enabled": True,
+                        "schedule": empty_week_schedule(),
+                    }
+                },
+                "profiles": [
+                    {
+                        "key": "away",
+                        "name": "Away",
+                        "zones": {
+                            self.entity_id: {
+                                "behavior": "schedule",
+                                "schedule": empty_week_schedule(),
+                            }
+                        },
+                    }
+                ],
+                "global_": {"mode": "auto", "active_profile_ids": ["away"]},
+            },
+            [self.entity_id],
+        )
+        scheduler = VelairScheduler(self.hass, data, FakeClimateManager(), self._save)
+        context = scheduler.get_zone_context(self.entity_id)
+        self.assertEqual("away", context["effective_profile_id"])
+        self.assertEqual("Away", context["effective_profile_name"])
+        self.assertEqual("profile", context["schedule_source"])
+
+    def test_override_sensor_merges_context_attributes(self) -> None:
+        scheduler = SimpleNamespace(
+            get_zone_override_status=lambda entity_id: {"state": "none"},
+            get_zone_context=lambda entity_id: {
+                "runtime_state": "scheduled",
+                "control_mode": "automatic",
+                "schedule_source": "default",
+                "last_applied_source": "scheduled_event",
+                "last_applied_temperature": 24.0,
+                "ignored_key": "dropped",
+            },
+        )
+        entry = SimpleNamespace(
+            runtime_data=SimpleNamespace(
+                scheduler=scheduler,
+                temperature_unit="°C",
+                configured_entities=["climate.living_room"],
+            ),
+            entry_id="entry",
+            options={},
+            data={},
+        )
+        sensor = sensor_module.ZoneOverrideStateSensor(entry, "climate.living_room")
+        attributes = sensor.extra_state_attributes
+        self.assertEqual("scheduled", attributes["runtime_state"])
+        self.assertEqual("automatic", attributes["control_mode"])
+        self.assertEqual(24.0, attributes["last_applied_temperature"])
+        self.assertNotIn("ignored_key", attributes)
+
+
+if __name__ == "__main__":
+    unittest.main()