kkelomatic_home/docs/integration/ha-lights-and-rooms.md

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:

# PLC/Node-RED lights – entity_id must match room-config.js (entityToRoom, lightEntityMap)
# Naming: <room>_<light_num>  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:

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.<room>_<number>
  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.