Skip to content

Commit 1d1e392

Browse files
webosawebosa
committed
Docs: Update Room Manager (Summary, Mermaid, Dashboards)
1 parent c65fbf8 commit 1d1e392

1 file changed

Lines changed: 163 additions & 39 deletions

File tree

‎docs/smart-home/packages/room_manager.md‎

Lines changed: 163 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -16,71 +16,197 @@ version: 1.2.0
1616

1717
## Executive Summary
1818
<!-- START_SUMMARY -->
19-
> ⚠️ **Update Required:** Analysis for v1.0.0. Code is v1.2.0.
20-
21-
The **Room Automation** package provides a standardized, scalable framework for managing room states (e.g., Occupied, Idle, Sleep) and automation parameters (e.g., lighting delays, lux thresholds) dynamically. It utilizes **MQTT discovery** to generate entities for each room on-the-fly, allowing for decentralized configuration without restarting Home Assistant. Admin users can "initialize" a room from a dashboard, which triggers scripts to publish MQTT configuration payloads, creating a suite of helpers (timers, selects, sensors) specific to that room. It effectively acts as a "factory" for room controllers.
19+
The **Room Automation Manager** is a dynamic configuration engine that enables the decentralized creation of smart room controllers. Unlike static YAML configuration, this package allows administrators to "initialize" a room directly from the dashboard. This triggers a script that publishes **MQTT Discovery** payloads to Home Assistant, effectively factory-generating a standardized suite of entities for that room (Automation Mode, Idle Timers, Occupancy Sensors, etc.) without requiring a system restart. It acts as a "Room Controller Factory," ensuring every smart room has a consistent interface and logic structure.
2220
<!-- END_SUMMARY -->
2321

2422
## Process Description (Non-Technical)
2523
<!-- START_DETAILED -->
26-
> ⚠️ **Update Required:** Analysis for v1.0.0. Code is v1.2.0.
27-
28-
This system allows you to turn any "Area" in your home into a Smart Room without writing code.
29-
1. **Creation:** You select a room (like "Kitchen") from a list in the Settings Dashboard.
30-
2. **Generation:** The system instantly creates a set of controls for that room, including:
31-
* **Mode Selector:** Choose how the room behaves (e.g., "Presence Control" vs. "Manual").
32-
* **Timers:** Set how long lights stay on after you leave.
33-
* **Sensors:** Link motion sensors and light sensors to the room.
34-
3. **Operation:** Once created, these controls appear in your dashboards, letting you tweak settings like "turn off lights after 5 minutes" individually for every room.
24+
This system allows you to turn any standard "Area" in your home into a fully functional Smart Room with a single click.
25+
1. **Select & Initialize:** Go to the **Room Management** dashboard, pick a room (e.g., "Kitchen") from the list, and click "Initialize".
26+
2. **Automatic Creation:** The system instantly builds a "Control Panel" for that room behind the scenes. It creates:
27+
* **Mode Switch:** To set the room to "Automatic", "Manual", or "Guest Mode".
28+
* **Timers:** Dials to set how long lights stay on (e.g., 5 minutes).
29+
* **Sensor Links:** Dropdown menus to choose which Motion Sensor and Bed Sensor belongs to this room.
30+
3. **Instant Control:** New controls appear immediately. You can now tweak the "Kitchen" settings without ever touching a code file. If you delete the room, all these controls vanish cleanly.
3531
<!-- END_DETAILED -->
3632

3733
## Dashboard Connections
3834
<!-- START_DASHBOARD -->
39-
This package powers the following dashboard views:
35+
* **[Room Management](../dashboards/room-management/room_management.md)**: The primary admin interface. Used to Create (Initialize) and Delete rooms. It also lists all active rooms and their configuration state.
36+
* **[Settings (System)](../dashboards/main/settings.md)**: Displays the global list of active rooms and their current modes (Occupied/Idle).
37+
38+
### Embedded Card: Configured Rooms List
39+
The following `auto-entities` configuration is used to dynamically list all rooms:
4040

41-
* **[Living Room](../dashboards/main/living_room.md)**: *The Living Room dashboard is a media and comfort hub. It features in-depth environmental monitoring (Radon, VOCs, CO2) via Airthings Wave, displaying historical trends. Entertainment controls are central, with remotes for the TV and Soundbar, plus power management for the media wall. The view also includes specific controls for the fireplace, air purifier modes, and various lighting scenes, alongside standard occupancy settings.* (Uses 1 entities)
42-
* **[Notifications Management](../dashboards/notification-center/notifications_management.md)**: *The Notification Center dashboard provides a comprehensive interface for managing the smart home's notification system. Administrators can add or remove users for mobile app notifications and define notification categories (e.g., 'Garage', 'Electricity'). The view allows for granular control over subscriptions, enabling individual users to opt-in or out of specific notification types, and includes tools to map and monitor notification-related automations.* (Uses 1 entities)
43-
* **[Room Management](../dashboards/room-management/room_management.md)**: *The Room Management dashboard serves as the administrative backend for the home's room logic. It allows users to initialize new rooms (creating necessary helper entities) or delete existing ones. It features a dynamic "Configured Rooms" section powered by `auto-entities`, which automatically lists all configured rooms and provides collapsible controls for their automation modes, occupancy sensors, and timeouts.* (Uses 4 entities)
41+
```yaml
42+
type: custom:auto-entities
43+
show_empty: true
44+
card:
45+
type: entities
46+
show_header_toggle: false
47+
filter:
48+
template: |
49+
{% set ns = namespace(rows=[]) %}
50+
{% set mode_selectors = states.select | selectattr('entity_id','search','automation_mode') | sort(attribute='entity_id') | list %}
51+
52+
{% for sel in mode_selectors %}
53+
{# Extract base id and normalize to room_key #}
54+
{% set raw_id = sel.entity_id.split('.')[1] %}
55+
{% set base = raw_id.replace('_automation_mode','') %}
56+
{% if base.startswith('room_') %}
57+
{% set room_key = base[5:] %}
58+
{% else %}
59+
{% set room_key = base %}
60+
{% endif %}
61+
{% set name = room_key.replace('_',' ') | title %}
62+
63+
{# Entity IDs #}
64+
{% set state_select = 'select.room_' ~ room_key ~ '_state' %}
65+
{% set auto_switch = 'switch.room_' ~ room_key ~ '_automation' %}
66+
{% set occ_sensor = 'binary_sensor.room_' ~ room_key ~ '_occupancy' %}
67+
{% set idle_entity = 'number.room_' ~ room_key ~ '_presence_idle_time' %}
68+
{% set delay_entity = 'number.room_' ~ room_key ~ '_lights_presence_delay' %}
69+
{% set bed_s = 'select.room_' ~ room_key ~ '_bed_sensor' %}
70+
{% set sleep_entry = 'number.room_' ~ room_key ~ '_sleep_entry_delay' %}
71+
{% set sleep_exit = 'number.room_' ~ room_key ~ '_sleep_exit_delay' %}
72+
{% set occ_source = 'select.room_' ~ room_key ~ '_occupancy_source' %}
73+
{% set timer_entity = 'sensor.room_' ~ room_key ~ '_timer' %}
74+
75+
{% set entities = [] %}
76+
77+
{# 1. Mode #}
78+
{% set entities = entities + [{'entity': sel.entity_id, 'name': 'Mode'}] %}
79+
80+
{# 2. Switch #}
81+
{% if states[auto_switch] is defined %}
82+
{% set entities = entities + [{'entity': auto_switch, 'name': 'Automation Enabled'}] %}
83+
{% endif %}
84+
85+
{# 3. State #}
86+
{% if states[state_select] is defined %}
87+
{% set entities = entities + [{'entity': state_select, 'name': 'Current State'}] %}
88+
{% endif %}
89+
90+
{# 4. Occupancy #}
91+
{% if states[occ_sensor] is defined %}
92+
{% set entities = entities + [{'entity': occ_sensor, 'name': 'Occupancy'}] %}
93+
{% endif %}
94+
95+
{# 5. Occupancy Source #}
96+
{% if states[occ_source] is defined %}
97+
{% set entities = entities + [{'entity': occ_source, 'name': 'Occupancy Sensor'}] %}
98+
{% endif %}
99+
100+
{# 6. Timer Bar (Conditional Row) #}
101+
{% if states[timer_entity] is defined %}
102+
{% set entities = entities + [{
103+
'type': 'conditional',
104+
'conditions': [
105+
{'entity': timer_entity, 'state_not': 'unavailable'},
106+
{'entity': timer_entity, 'state_not': 'unknown'},
107+
{'entity': timer_entity, 'state_not': 'none'},
108+
{'entity': timer_entity, 'state_not': ''}
109+
],
110+
'row': {
111+
'entity': timer_entity,
112+
'name': 'Timer'
113+
}
114+
}] %}
115+
{% endif %}
116+
117+
{# 7. Config Numbers #}
118+
{% if states[idle_entity] is defined %}
119+
{% set entities = entities + [{'entity': idle_entity, 'name': 'Idle Time (sec)'}] %}
120+
{% endif %}
121+
{% if states[delay_entity] is defined %}
122+
{% set entities = entities + [{'entity': delay_entity, 'name': 'Off Delay (sec)'}] %}
123+
{% endif %}
124+
125+
{# 8. Bed Sensor & Sleep Timers (Conditional) #}
126+
{% if states[bed_s] is defined %}
127+
{% set entities = entities + [{'entity': bed_s, 'name': 'Bed Occupancy Sensor'}] %}
128+
129+
{# Sleep Entry Delay #}
130+
{% if states[sleep_entry] is defined %}
131+
{% set entities = entities + [{
132+
'type': 'conditional',
133+
'conditions': [
134+
{'entity': bed_s, 'state_not': '-Select-'},
135+
{'entity': bed_s, 'state_not': 'unknown'},
136+
{'entity': bed_s, 'state_not': 'unavailable'}
137+
],
138+
'row': {
139+
'entity': sleep_entry,
140+
'name': 'Sleep Entry Delay (sec)'
141+
}
142+
}] %}
143+
{% endif %}
144+
145+
{# Sleep Exit Delay #}
146+
{% if states[sleep_exit] is defined %}
147+
{% set entities = entities + [{
148+
'type': 'conditional',
149+
'conditions': [
150+
{'entity': bed_s, 'state_not': '-Select-'},
151+
{'entity': bed_s, 'state_not': 'unknown'},
152+
{'entity': bed_s, 'state_not': 'unavailable'}
153+
],
154+
'row': {
155+
'entity': sleep_exit,
156+
'name': 'Sleep Exit Delay (sec)'
157+
}
158+
}] %}
159+
{% endif %}
160+
{% endif %}
161+
162+
{# Create the Group #}
163+
{% set group = {
164+
'type': 'custom:fold-entity-row',
165+
'head': {'type':'section', 'label': name},
166+
'entities': entities
167+
} %}
168+
{% set ns.rows = ns.rows + [group] %}
169+
{% endfor %}
170+
171+
{{ ns.rows | to_json }}
172+
```
44173
<!-- END_DASHBOARD -->
45174
46175
## Architecture Diagram
47176
<!-- START_MERMAID_DESC -->
48-
> ⚠️ **Update Required:** Analysis for v1.0.0. Code is v1.2.0.
49-
50-
The sequence diagram below illustrates the "Room Initialization" process. When a user selects a room (e.g., "Kitchen") and clicks "Initialize", the `create_room_settings` script is triggered. This script iterates through a predefined list of required entities (Mode Select, Idle Timer, Occupancy Sensor, etc.) and publishes **MQTT Configuration Payloads** to the `homeassistant/` discovery topic. Home Assistant's MQTT integration detects these payloads and dynamically duplicates the "Room Controller" entity structure for the new room. Finally, the script sets default values (e.g., 120s delay) via retained MQTT messages, ensuring the room is ready for immediate use.
177+
The sequence diagram below illustrates the **Room Initialization Flow**. When a user clicks "Initialize" for a specific room (e.g., "Kitchen"), the `create_room_settings` script triggers. It loops through a definition of required entities (Automation Mode, Idle Timer, Occupancy Sensor Link) and publishes **MQTT Configuration Payloads** to the `homeassistant/` discovery topic. Home Assistant detects these payloads and dynamically creates the entities in its registry. Finally, the script publishes default state values (retained) to ensure the new controls are immediately usable.
51178
<!-- END_MERMAID_DESC -->
52179

53180
<!-- START_MERMAID -->
54-
> ⚠️ **Update Required:** Analysis for v1.0.0. Code is v1.2.0.
55-
56181
```mermaid
57182
sequenceDiagram
58-
participant Admin as 👤 Admin
59-
participant Dash as 📱 Dashboard (Settings)
60-
participant Script as 📜 Script: create_room_settings
183+
participant User as 👤 Admin (Dashboard)
184+
participant Script as 📜 Script: create_room
61185
participant MQTT as 📡 MQTT Broker
62186
participant HA as 🏠 Home Assistant (Discovery)
63187
64-
Admin->>Dash: Selects "Kitchen" & Clicks Initialize
65-
Dash->>Script: Run(room_slug="kitchen")
188+
User->>Script: Run(room_slug="kitchen")
189+
activate Script
66190
67191
rect rgb(20, 20, 20)
68-
note right of Script: Entity Generation Loop
69-
Script->>MQTT: Publish config: select.room_kitchen_mode
70-
MQTT-->>HA: Discovery: New Entity (select.room_kitchen_mode)
71-
Script->>MQTT: Publish config: number.room_kitchen_idle
72-
MQTT-->>HA: Discovery: New Entity (number.room_kitchen_idle)
73-
Script->>MQTT: Publish config: binary_sensor.room_kitchen_occupancy
74-
MQTT-->>HA: Discovery: New Entity (binary_sensor...occupancy)
192+
note right of Script: 1. Entity Construction Loop
193+
Script->>MQTT: Publish config: select.room_kitchen_mode
194+
MQTT-->>HA: Discovery: New Entity (select...mode)
195+
Script->>MQTT: Publish config: number.room_kitchen_idle
196+
MQTT-->>HA: Discovery: New Entity (number...idle)
197+
Script->>MQTT: Publish config: binary_sensor.room_kitchen_occupancy
198+
MQTT-->>HA: Discovery: New Entity (binary_sensor...occupancy)
75199
end
76200
77201
rect rgb(30, 30, 50)
78-
note right of Script: Default Values
79-
Script->>MQTT: Publish state: mode = "presence-control"
80-
Script->>MQTT: Publish state: delay = 120s
202+
note right of Script: 2. Default State Injection (Retained)
203+
Script->>MQTT: Publish state: mode = "presence-control"
204+
Script->>MQTT: Publish state: idle_time = 120s
205+
Script->>MQTT: Publish state: occupancy = OFF
81206
end
82207
83-
HA-->>Dash: UI Updates with new Kitchen Controls
208+
deactivate Script
209+
HA-->>User: UI Updates (New Controls Appear)
84210
```
85211
<!-- END_MERMAID -->
86212

@@ -813,5 +939,3 @@ automation:
813939
payload: ""
814940
815941
- service: script.refresh_room_options
816-
817-
```

0 commit comments

Comments
 (0)