nearxos
0af21f4dc3
- Updated global variable lists in GVL_IO.gvl and GVL_NVL_placeholders.gvl to reflect new room naming conventions and structures. - Revised PLC_App.st to map new room configurations for lighting control. - Enhanced documentation in all-lights-and-rooms.md and ha-lights-and-rooms.md to align with updated room and light entity naming. - Adjusted room-config.js and related Node-RED flows to support the new configuration structure. This update improves the organization and clarity of room and light management within the Node-RED integration, ensuring consistency across the system.
129 lines
5.6 KiB
Markdown
129 lines
5.6 KiB
Markdown
# Creating and managing light entities in Home Assistant (by room)
|
||
|
||
This guide covers how to create the light/switch entities that Node-RED and the PLC use, and how to assign them to **rooms** (HA **Areas**) so you can manage and display them by room.
|
||
|
||
Canonical naming in this project is now:
|
||
|
||
- `input_boolean.<area>_<room>_<light_type>_<index>`
|
||
- Example: `input_boolean.open_plan_living_room_main_1`
|
||
|
||
Pre-generated helper YAML for the current electrical plan:
|
||
|
||
- [`lights_by_area_room_type_index.yaml`](lights_by_area_room_type_index.yaml)
|
||
|
||
---
|
||
|
||
## 1. Concepts
|
||
|
||
| In Home Assistant | In Node-RED / room-config.js |
|
||
|-------------------|------------------------------|
|
||
| **Area** (room) | Room name for UI/dashboards |
|
||
| **Entity** | One light switch (e.g. `input_boolean.living_room_1`) |
|
||
| Entity **name** | Friendly label (e.g. “Living Room 1”) |
|
||
|
||
- You create **entities** (e.g. `input_boolean`) and optionally **areas** (rooms).
|
||
- You **assign each entity to an area** so HA can group them by room (overview, dashboards, “turn off room”).
|
||
- Entity IDs must match what you put in **room-config.js** (`entityToRoom`, `lightEntityMap`).
|
||
|
||
---
|
||
|
||
## 2. Create rooms (Areas) first (recommended)
|
||
|
||
So you can assign entities to a room when creating or editing them.
|
||
|
||
1. **Settings** → **Areas & Zones** (or **Settings** → **Devices & services** → **Areas**).
|
||
2. Click **Add area**.
|
||
3. Name it like your rooms (e.g. *Living Room*, *Kitchen*, *Hallway*). You can add an icon per area.
|
||
4. Create one area per room you use in Node-RED (names can differ from NVL room keys; area is for HA UI only).
|
||
|
||
---
|
||
|
||
## 3. Create light entities
|
||
|
||
Two ways: **YAML (bulk, by room)** or **UI (one by one)**.
|
||
|
||
### Option A: YAML package (bulk, easy to manage by room)
|
||
|
||
Create one file per room (or one file with sections) so entities are grouped by room. Then assign the area in the UI once (see step 4).
|
||
|
||
**Single file for all lights, grouped by room** – save as `packages/lights_by_room.yaml` in your HA config:
|
||
|
||
```yaml
|
||
# PLC/Node-RED lights – entity_id must match room-config.js (entityToRoom, lightEntityMap)
|
||
# Naming: <area>_<room>_<light_type>_<index> e.g. open_plan_living_room_main_1
|
||
|
||
input_boolean:
|
||
open_plan_living_room_main_1: { name: Open Plan Living Room Main 1 }
|
||
open_plan_living_room_spots_1: { name: Open Plan Living Room Spots 1 }
|
||
kitchen_kitchen_main_1: { name: Kitchen Main 1 }
|
||
bedrooms_hallway_main_1: { name: Bedrooms Hallway Main 1 }
|
||
```
|
||
|
||
Ensure `configuration.yaml` has:
|
||
|
||
```yaml
|
||
homeassistant:
|
||
packages: !include_dir_named packages
|
||
```
|
||
|
||
Restart Home Assistant. All entities are created. Entity IDs will be `input_boolean.open_plan_living_room_main_1`, etc.
|
||
|
||
### Option B: UI (one by one)
|
||
|
||
1. **Settings** → **Devices & services** → **Helpers** → **Create Helper** → **Toggle**.
|
||
2. Name (e.g. *Living Room 1*). HA will generate an entity_id (e.g. `input_boolean.living_room_1`).
|
||
3. Create a helper for each light. Use a consistent naming pattern so the generated entity_id matches what you use in Node-RED (e.g. *Room Name N* → `room_name_n`).
|
||
|
||
---
|
||
|
||
## 4. Assign entities to a room (Area)
|
||
|
||
After entities exist, assign each to an Area so they show up by room.
|
||
|
||
1. **Settings** → **Devices & services** → **Entities** (or **Settings** → **Entities**).
|
||
2. Filter by **input_boolean** (or your light domain).
|
||
3. Click an entity → open the **Area** dropdown and choose the room (e.g. *Living Room*, *Kitchen*).
|
||
4. Repeat for each entity.
|
||
|
||
**Faster for many entities:** **Settings** → **Areas & Zones** → click an area (e.g. *Living Room*) → **Add entities** and select all lights that belong in that room.
|
||
|
||
Result: each light entity is tied to one room (area) for overview, dashboards, and “turn off all in this room”.
|
||
|
||
---
|
||
|
||
## 5. Keep Node-RED and HA in sync
|
||
|
||
Use the **same entity_id and room logic** in both places.
|
||
|
||
| Where | What to match |
|
||
|-------|----------------|
|
||
| **room-config.js** `entityToRoom` | Map from entity_id “base” (e.g. `living_room_new`, `living_room`) to NVL room key (e.g. `cmd_livingroom`, `livingRoom`). |
|
||
| **room-config.js** `lightEntityMap` | One entry per light: `entityId: 'input_boolean.living_room_1'`, `room` = NVL receive key, `light` = 1..6. |
|
||
| **HA** | Entity IDs and (optionally) names; areas are for UI only. |
|
||
|
||
**Naming convention that works well:**
|
||
|
||
- Entity ID: `input_boolean.<area>_<room>_<light_type>_<index>`
|
||
Examples: `open_plan_living_room_main_1`, `kitchen_kitchen_island_1`, `exterior_yard_driveway_1`.
|
||
- In **entityToRoom** use the part without trailing `_<index>`, e.g. `open_plan_living_room_main` or `exterior_yard_driveway`.
|
||
|
||
When you add a new light in HA (new entity_id), add or update:
|
||
|
||
1. **room-config.js** – `lightEntityMap` (and `entityToRoom` if it’s a new room base name).
|
||
2. **room-config.js** – `roomNames` if it’s a new NVL room.
|
||
3. Reload config in Node-RED (or let the Watch flow do it when you save the file).
|
||
|
||
---
|
||
|
||
## 6. Summary
|
||
|
||
| Goal | Action |
|
||
|------|--------|
|
||
| Create rooms in HA | **Settings** → **Areas & Zones** → Add area per room. |
|
||
| Create many lights at once | YAML package (e.g. `packages/lights_by_room.yaml`) with `input_boolean` entries, then restart HA. |
|
||
| Create one light | **Settings** → **Helpers** → Create Helper → Toggle, name it (e.g. *Kitchen 2*). |
|
||
| Assign lights to a room | **Settings** → **Entities** → select entity → set **Area**; or **Areas & Zones** → area → Add entities. |
|
||
| Match Node-RED | Use same entity_ids in **room-config.js** (`entityToRoom`, `lightEntityMap`). |
|
||
|
||
For scaling to many rooms and lights, see also [all-lights-and-rooms.md](all-lights-and-rooms.md).
|