Designing public per-zone runtime context for dashboards and automations

[cgonfer]

Context

PR #22 proposes exposing additional per-zone runtime context through the existing Zone override sensor.

The underlying use case is valuable: users may want to understand Velair's current intent from standard Home Assistant dashboards and automations without opening the Velair panel or consuming its WebSocket payload directly.

Examples include:

• whether a zone is currently scheduled, paused, boosted, manually controlled, or externally managed;
• which Default or Profile schedule currently owns the zone;
• why a particular temperature is active;
• the last action or target applied by Velair;
• when that action happened and where it originated.

Before defining a public entity contract, I would like to collect use cases and agree on the correct architecture.

Why this needs design discussion

There are several possible meanings for “last applied target”:

1. Last scheduled intent

   The target selected by Velair's schedule, Profile, Mode, boost, or pause logic.

2. Last climate target event

   The most recent climate_target_applied event published by Velair.

3. Last physical command

   The final command sent to the climate entity after Room Assist, restoration, range handling, or other runtime adjustments.

These values can differ. For example, a schedule may request 24 °C while Room Assist ultimately sends 27 °C to the device.

The chosen definition affects how the data should behave after:

• velair.set_temperature;
• scheduled applications;
• boosts and restoration;
• Room Assist adjustments;
• turn_off actions;
• scalar and heat_cool range targets;
• failed or superseded deliveries;
• profile changes;
• data reset;
• Celsius/Fahrenheit migration;
• Home Assistant restart;
• switching a zone to external execution.

Entity model

PR #22 adds this information as attributes of the existing Zone override sensor. However, several proposed values have independent meaning and could be useful as automation triggers.

Possible approaches include:

• extending the existing Zone override sensor with a small amount of strictly related context;
• adding a dedicated per-zone runtime-state sensor;
• exposing independently useful values as separate entities;
• reusing the existing runtime diagnostics state;
• relying on Velair events for transient delivery information;
• exposing a smaller shared backend projection for both the Velair panel and Lovelace cards.

We should also consider Home Assistant Recorder usage. Frequently changing attributes on every zone could create unnecessary history growth.

Planned dashboard card

A dedicated Lovelace card for displaying useful Velair information in regular dashboards is also planned as one of the next project tasks, although implementation has not started yet.

That work will need a clear and stable way to obtain per-zone runtime information. It may cover part or all of the use case behind PR #22, or help identify a smaller backend contract that can support:

• the official Velair card;
• third-party cards;
• template cards;
• Home Assistant automations.

The goal is to avoid creating separate or duplicated runtime models for each consumer.

Questions

Feedback would be especially useful on the following:

1. What information do you need to display or automate on?
2. Do you need the scheduled intent, the final physical command, or both?
3. Which values need to be directly usable as automation triggers?
4. Should the information survive a Home Assistant restart?
5. How should historical values behave after a reset or temperature-unit change?
6. Would a dedicated Velair Lovelace card cover the use case?
7. Which information must remain available to generic or third-party cards?
8. Would disabled-by-default diagnostic entities be acceptable for advanced use cases?

Concrete dashboard or automation examples are welcome, provided they do not expose private Home Assistant data.

Relationship to PR #22

This Discussion was opened following PR #22. The PR demonstrates a real use case and provides a useful starting point, but it also shows that we need to agree on the public contract before committing to a specific implementation.

Once the expected behavior and entity model are agreed, we can decide whether to:

• revise PR Expose zone runtime context on the override sensor #22;
• replace it with a smaller backend change;
• implement the capability as part of the planned dashboard card;
• or combine a minimal backend contract with dedicated frontend presentation.

Thank you to @Cloudore for raising the use case and contributing an initial implementation.

[Cloudore]

Thanks for the thorough review, and for opening this rather than just closing the PR — the concerns are fair, and I'd rather get the contract right than defend the current attribute set.

Some context that might help ground the discussion: I'm running this fork (home branch, PR #22 among others) on a real house with six managed zones (five Midea/CCM15, one LocalTuya), and the dashboard that motivated PR #22 has been live for a few hours now. So I can answer with what we actually built rather than a hypothetical.

1. What we display/automate on. Two concrete surfaces: a one-line per-zone explainer ("schedule · comfort 26°", "held by you · releases when empty 60 min") built from schedule_source, effective_profile_name, and the manual attributes; and a diagnostics table across all six zones — Room | Last applied (source) | Outcome | Attempts | At — with a mismatch warning when the live device setpoint disagrees with last_applied_temperature by more than one step.

2. Scheduled intent vs. physical command — we need both, for different things. The explainer wants intent: if Room Assist nudges the delivered target, a housemate reading "comfort 26°" shouldn't see a number that doesn't match what was decided. The diagnostics table specifically wants the physical command, because its whole purpose is catching a CCM15 write that got silently dropped or altered in transit — PR #22 as written actually conflates the two under one last_applied_* name, which is exactly your point 2/3 in the "why this needs design" section. I'd now lean toward keeping intent on the override sensor (cheap, matches its existing job) and putting the physical-delivery record next to PR #3's delivery_outcome/attempts, since that's already the "what actually happened on the wire" data source and a mismatch check wants both side by side anyway.

3. What we key automations off. In practice, only the external_climate_change_detected event (existing) — a state-based control_mode transition to/from manual would be a nice-to-have but we don't strictly need a new trigger surface for it.

4. Restart survival. Yes for control_mode/manual_*/schedule_source — a restart shouldn't make a genuinely still-manual zone read as automatic. No for last_applied_*/delivery info — starting empty after a restart is expected and our dashboard already renders that as "—"; we would not want a restart to synthesize a plausible-looking stale value there.

5. Reset / unit migration. Should behave like every other cached temperature in storage. We're Celsius-only so we haven't hit this, but an unconverted cached value surviving a °C→°F switch would produce a nonsensical mismatch warning on our diagnostics table the moment someone changes units — worth fixing regardless of which entity model wins.

6. Would the planned card cover this? Partly. It would likely cover the diagnostics table, but not the inline one-line explainer embedded next to a thermostat tile in our own room card, and not the ability to gate a plain HA automation on control_mode. We'd keep wanting entity-level access even with a good official card.

7. Minimum set for third-party/template cards. control_mode, manual_source, manual_since, schedule_source, and — under whatever name the physical-delivery data ends up with — its source, temperature/hvac_mode, and timestamp.

8. Disabled-by-default diagnostic entities? Yes, fine by us. We only read this data when a zone's card or the diagnostics view is actually on screen, so we'd rather enable one entity per zone than parse the WS zone_runtime payload from a Lovelace template.

One data point on the specific bugs: our own automations never call velair.set_temperature directly (only pause_zone/resume_zone/resume_automatic_control/set_daily_schedule), so we haven't hit the "set_temperature doesn't update _last_applied" bug in production — only in an ad-hoc test script. And since we don't use Profiles yet, we haven't hit the behavior: normal → schedule_source: profile bug either. Neither observation makes them not-bugs, just noting what we have and haven't exercised.

Happy to keep PR #22 parked and revise it (or drop it in favor of whatever comes out of this) once the model settles — no rush on our end.