diff --git a/docs/README.md b/docs/README.md index ef9026d..78d8d9c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,6 +21,7 @@ Basics: **how home automation works**, **services**, and **CODESYS connectivity* - [Living Room flow](integration/nodered-livingroom-flow.md) — Test flow, NVL send, Action node, sync - [All lights and rooms](integration/all-lights-and-rooms.md) — Scale to all lights: config, HA entities (YAML bulk), checklist +- [HA: create and manage lights by room](integration/ha-lights-and-rooms.md) — Create entities, assign to rooms (Areas), sync with room-config.js - [Living Room analysis](integration/nodered-livingroom-analysis.md) — Current nodes and wiring (from live Node-RED) ## CODESYS diff --git a/docs/integration/all-lights-and-rooms.md b/docs/integration/all-lights-and-rooms.md index 5e98a74..67f90c6 100644 --- a/docs/integration/all-lights-and-rooms.md +++ b/docs/integration/all-lights-and-rooms.md @@ -160,6 +160,8 @@ Generate this list from your room list + lights per room (e.g. 16 rooms × up to ## 4. Home Assistant: creating entities for all lights +For a focused guide on **creating entities and assigning them to rooms (Areas)** in HA, see **[ha-lights-and-rooms.md](ha-lights-and-rooms.md)**. + You need one HA entity per light (or per zone) that Node-RED and the PLC treat as one target. Two common choices: - **`input_boolean`** – simple on/off, good for “virtual” switches that only drive the PLC. diff --git a/docs/integration/ha-lights-and-rooms.md b/docs/integration/ha-lights-and-rooms.md new file mode 100644 index 0000000..3c3494b --- /dev/null +++ b/docs/integration/ha-lights-and-rooms.md @@ -0,0 +1,124 @@ +# 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. + +--- + +## 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: _ e.g. living_room_1, kitchen_2 + +input_boolean: + # Living room + living_room_1: { name: Living Room 1 } + living_room_2: { name: Living Room 2 } + # Kitchen + kitchen_1: { name: Kitchen 1 } + kitchen_2: { name: Kitchen 2 } + # Hallway + hallway_1: { name: Hallway 1 } + # Add more: master_bedroom_1, bathroom_1, entrance_1, etc. +``` + +Ensure `configuration.yaml` has: + +```yaml +homeassistant: + packages: !include_dir_named packages +``` + +Restart Home Assistant. All entities are created. Entity IDs will be `input_boolean.living_room_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._` + Examples: `living_room_1`, `kitchen_2`, `hallway_1`. +- In **entityToRoom** use the part without the number: `living_room`, `kitchen`, `hallway` (and any alias like `living_room_new` → `cmd_livingroom`). + +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). diff --git a/node-red/room-config.js b/node-red/room-config.js index 7921912..366ebeb 100644 --- a/node-red/room-config.js +++ b/node-red/room-config.js @@ -56,10 +56,10 @@ const ROOM_CONFIG = { // out_side: 'outSide', }, - // Zigbee: friendly_name → single room (fallback when switchBindings missing). - deviceToRoom: { - 'Office Switch': 'cmd_livingroom', - }, + // // Zigbee: friendly_name → single room (fallback when switchBindings missing). + // deviceToRoom: { + // 'Office Switch': 'cmd_livingroom', + // }, // When using a multi-device Zigbee node, payload is keyed by IEEE (e.g. 0xa4c138a5b9771b05). Map IEEE → friendly name so switchBindings by name still works. deviceIdToName: { @@ -79,7 +79,7 @@ const ROOM_CONFIG = { switchBindings: { 'Office Switch': { 1: { room: 'cmd_livingroom', light: 1 }, // button 1 → light 1 - 2: { room: 'cmd_livingroom', light: 1 }, // button 2 → light 1 (same light; other switches could do button 2 → light 2) + 2: { room: 'cmd_livingroom', light: 2 }, // button 2 → light 1 (same light; other switches could do button 2 → light 2) }, }, };