# 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).
