|
| 1 | +# Design rationale |
| 2 | + |
| 3 | +This custom integration was created to deliver a room-level entity that works hand‑in‑hand with the [Custom Features for Home Assistant Cards (CFHAC)](https://github.com/Nerwyn/custom-card-features) extension, allowing dashboards to mirror the Area card’s high‑level UX while remaining portable and source‑of‑truth agnostic. |
| 4 | + |
| 5 | +Why not just use Areas? Two reasons: |
| 6 | + |
| 7 | +- Area entities aren’t first‑class, queryable sensors. They’re a grouping concept. Many dashboards still need a single, reactive entity per room that can provide a summary state and attributes for power, climate, occupancy, etc. |
| 8 | +- The Area card’s behavior is great for overview dashboards, but it’s not easily reproducible across themes or custom dashboards without writing glue logic. This integration exposes a predictable sensor that pairs nicely with CFHAC’s rules and feature toggles. |
| 9 | + |
| 10 | +The integration makes it straightforward to reproduce Area card behavior on a Tile card using CFHAC. |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +## Goals |
| 15 | + |
| 16 | +- Provide a single sensor per room that reflects “Active/Idle/Unknown” status. |
| 17 | +- Surface useful, typed attributes (numeric + display‑friendly) to power flexible dashboards and automations. |
| 18 | +- Keep configuration simple: point to existing entities (power, energy, temp, humidity, motion, window, climate) without forcing a data model. |
| 19 | +- Be resilient across HA versions by gracefully handling missing constants and entities. |
| 20 | + |
| 21 | +## How it works |
| 22 | + |
| 23 | +- A `sensor` entity is created per configured room. Its friendly name is the room name; suggested object_id is `room_<name>` so your entity_id becomes easy to reference in UI config and automations. |
| 24 | +- The state logic prioritizes “occupied” signals: |
| 25 | + 1) If motion is ON → `active`. |
| 26 | + 2) Else, if power exceeds `active_threshold` (default 50W) → `active`. |
| 27 | + 3) Else, if any core entity is configured → `idle`. |
| 28 | + 4) Else → `unknown`. |
| 29 | +- The icon reflects window or motion when relevant, otherwise falls back to a configurable or default icon. |
| 30 | +- Attributes are exposed in two forms: |
| 31 | + - Raw numeric attributes for automations (e.g., `power_w`, `energy_wh`, `temperature_c`, `humidity_pct`, `climate_target_c`). |
| 32 | + - Human‑readable attributes with units for dashboards (e.g., `power`, `energy`, `temperature`, `humidity`, `climate_target`). |
| 33 | +- A lightweight coordinator listens to state changes of the referenced entities and schedules updates for the summary sensor—no polling. |
| 34 | + |
| 35 | +## Why this pairs well with CFHAC |
| 36 | + |
| 37 | +Custom Features for Home Assistant Cards lets you declaratively toggle and compose per‑card features based on entity attributes, thresholds, and state. By centralizing room summary data in a single entity: |
| 38 | + |
| 39 | +- You can implement area‑like tiles with conditions like “show occupied badge when `occupied` is true”, “show window alert when `window_open` is true”, or “color accent when `state == active` or `power_w > N`”. |
| 40 | +- You avoid repetitive template sensors: dashboards read a consistent schema, regardless of which underlying devices a room has. |
| 41 | +- Cards remain simple: fewer jinja templates, more declarative feature rules. |
| 42 | + |
| 43 | +## Configuration surface |
| 44 | + |
| 45 | +The integration accepts the following entity references per room: |
| 46 | + |
| 47 | +- Power sensor (W) |
| 48 | +- Energy sensor (Wh) |
| 49 | +- Temperature sensor (°C) |
| 50 | +- Humidity sensor (%) |
| 51 | +- Motion binary_sensor |
| 52 | +- Window/Contact binary_sensor |
| 53 | +- Climate entity (for HVAC mode and target temperature) |
| 54 | + |
| 55 | +Optional settings: |
| 56 | + |
| 57 | +- `active_threshold`: Power threshold (W) to consider the room active when motion is off. Default: 50.0 |
| 58 | +- `icon`: Fallback icon when neither motion nor window is active. |
| 59 | + |
| 60 | +## Design choices |
| 61 | + |
| 62 | +- Non‑polling updates: Uses `async_track_state_change_event` to react immediately to changes. |
| 63 | +- Friendly + machine attributes: Keep dashboards readable without sacrificing automation precision. |
| 64 | +- Graceful fallbacks: If unit constants differ between HA versions, we fall back to safe string units (C, W, Wh). |
| 65 | +- Minimal constraints: No enforced device model—just wire up what you already have. |
| 66 | + |
| 67 | +## Limitations and future ideas |
| 68 | + |
| 69 | +- Activity inference is intentionally simple (motion or power > threshold). Future options could include: |
| 70 | + - Time‑decay for motion (linger in `active` for N minutes after last motion) |
| 71 | + - Optional aggregation of multiple motion or power entities |
| 72 | + - Presence from BLE/Wi‑Fi trackers |
| 73 | +- Add services to override state manually (e.g., force idle/active for a scene). |
| 74 | +- More attributes for CFHAC features (e.g., comfort score, air quality if present). |
| 75 | + |
| 76 | +## Example CFHAC usage |
| 77 | + |
| 78 | +- Show a glowing border when `state == "active"`. |
| 79 | +- Display a badge when `window_open` is true. |
| 80 | +- Change icon color based on `humidity_pct` or `temperature_c` ranges. |
| 81 | +- Conditionally reveal a secondary line like `power` or `climate_target` when present. |
| 82 | + |
| 83 | +With a stable, documented schema, you can compose these behaviors per room without duplicating logic across cards. |
0 commit comments