kkelomatic_home/docs/redesign/light-naming-configuration.md

# Light Naming Configuration - Hybrid Structure

## Overview

This document defines the naming convention and structure for all lights in the home automation system using the Hybrid Structure (Option 4). This will serve as the basis for the redesign.

**Structure**: Room-organized in CODESYS, flattened for Home Assistant  
**Naming Convention**: `{room}_{function}` (e.g., `kitchen_main`, `master_bedroom_bedside_left`)

---

## Room-by-Room Light Configuration

### 1. Master Bedroom

**Room ID**: `master_bedroom`  
**Display Name**: "Master Bedroom"

**Lights**:
- `main` - Main ceiling light
- `bedside_left` - Left bedside lamp
- `bedside_right` - Right bedside lamp
- `closet` - Closet light
- `reading` - Reading light (optional)
- `ambient` - Ambient/atmospheric lighting (optional)

**CODESYS Structure**:
```iec
rooms.master_bedroom:
    main: struct_light_control;
    bedside_left: struct_light_control;
    bedside_right: struct_light_control;
    closet: struct_light_control;
    reading: struct_light_control;      // Optional
    ambient: struct_light_control;      // Optional
```

**Home Assistant Entities**:
- `light.master_bedroom_main`
- `light.master_bedroom_bedside_left`
- `light.master_bedroom_bedside_right`
- `light.master_bedroom_closet`
- `light.master_bedroom_reading` (if used)
- `light.master_bedroom_ambient` (if used)

---

### 2. Master Bathroom

**Room ID**: `master_bathroom`  
**Display Name**: "Master Bathroom"

**Lights**:
- `main` - Main ceiling light
- `mirror` - Mirror/vanity light
- `shower` - Shower light
- `night_light` - Night light (low brightness)

**CODESYS Structure**:
```iec
rooms.master_bathroom:
    main: struct_light_control;
    mirror: struct_light_control;
    shower: struct_light_control;
    night_light: struct_light_control;
```

**Home Assistant Entities**:
- `light.master_bathroom_main`
- `light.master_bathroom_mirror`
- `light.master_bathroom_shower`
- `light.master_bathroom_night_light`

---

### 3. Bedroom 1

**Room ID**: `bedroom_1`  
**Display Name**: "Bedroom 1"

**Lights**:
- `main` - Main ceiling light
- `bedside` - Bedside lamp
- `desk` - Desk lamp (if applicable)
- `closet` - Closet light (if applicable)

**CODESYS Structure**:
```iec
rooms.bedroom_1:
    main: struct_light_control;
    bedside: struct_light_control;
    desk: struct_light_control;      // Optional
    closet: struct_light_control;    // Optional
```

**Home Assistant Entities**:
- `light.bedroom_1_main`
- `light.bedroom_1_bedside`
- `light.bedroom_1_desk` (if used)
- `light.bedroom_1_closet` (if used)

---

### 4. Bedroom 2

**Room ID**: `bedroom_2`  
**Display Name**: "Bedroom 2"

**Lights**:
- `main` - Main ceiling light
- `bedside` - Bedside lamp
- `desk` - Desk lamp (if applicable)
- `closet` - Closet light (if applicable)

**CODESYS Structure**:
```iec
rooms.bedroom_2:
    main: struct_light_control;
    bedside: struct_light_control;
    desk: struct_light_control;      // Optional
    closet: struct_light_control;    // Optional
```

**Home Assistant Entities**:
- `light.bedroom_2_main`
- `light.bedroom_2_bedside`
- `light.bedroom_2_desk` (if used)
- `light.bedroom_2_closet` (if used)

---

### 5. Bathroom

**Room ID**: `bathroom`  
**Display Name**: "Bathroom"

**Lights**:
- `main` - Main ceiling light
- `mirror` - Mirror/vanity light
- `night_light` - Night light

**CODESYS Structure**:
```iec
rooms.bathroom:
    main: struct_light_control;
    mirror: struct_light_control;
    night_light: struct_light_control;
```

**Home Assistant Entities**:
- `light.bathroom_main`
- `light.bathroom_mirror`
- `light.bathroom_night_light`

---

### 6. Kitchen

**Room ID**: `kitchen`  
**Display Name**: "Kitchen"

**Lights**:
- `main` - Main ceiling light
- `under_cabinet` - Under cabinet task lighting
- `island` - Island pendant light
- `pantry` - Pantry light (if separate from pantry room)
- `sink` - Sink area light

**CODESYS Structure**:
```iec
rooms.kitchen:
    main: struct_light_control;
    under_cabinet: struct_light_control;
    island: struct_light_control;
    pantry: struct_light_control;      // If in kitchen
    sink: struct_light_control;
```

**Home Assistant Entities**:
- `light.kitchen_main`
- `light.kitchen_under_cabinet`
- `light.kitchen_island`
- `light.kitchen_pantry` (if used)
- `light.kitchen_sink`

---

### 7. Living Room

**Room ID**: `living_room`  
**Display Name**: "Living Room"

**Lights**:
- `main` - Main ceiling light
- `reading` - Reading lamp
- `tv` - TV area lighting
- `accent` - Accent lighting
- `fireplace` - Fireplace area lighting (if applicable)

**CODESYS Structure**:
```iec
rooms.living_room:
    main: struct_light_control;
    reading: struct_light_control;
    tv: struct_light_control;
    accent: struct_light_control;
    fireplace: struct_light_control;  // Optional
```

**Home Assistant Entities**:
- `light.living_room_main`
- `light.living_room_reading`
- `light.living_room_tv`
- `light.living_room_accent`
- `light.living_room_fireplace` (if used)

---

### 8. Dining Room

**Room ID**: `dining_room`  
**Display Name**: "Dining Room"

**Lights**:
- `main` - Main chandelier/ceiling light
- `ambient` - Ambient lighting
- `buffet` - Buffet/sideboard lighting (if applicable)

**CODESYS Structure**:
```iec
rooms.dining_room:
    main: struct_light_control;
    ambient: struct_light_control;
    buffet: struct_light_control;     // Optional
```

**Home Assistant Entities**:
- `light.dining_room_main`
- `light.dining_room_ambient`
- `light.dining_room_buffet` (if used)

---

### 9. Hallway

**Room ID**: `hallway`  
**Display Name**: "Hallway"

**Lights**:
- `main` - Main hallway light
- `secondary` - Secondary hallway light (if long hallway)
- `night_light` - Night light

**CODESYS Structure**:
```iec
rooms.hallway:
    main: struct_light_control;
    secondary: struct_light_control;  // Optional
    night_light: struct_light_control;
```

**Home Assistant Entities**:
- `light.hallway_main`
- `light.hallway_secondary` (if used)
- `light.hallway_night_light`

---

### 10. Pantry

**Room ID**: `pantry`  
**Display Name**: "Pantry"

**Lights**:
- `main` - Main pantry light

**CODESYS Structure**:
```iec
rooms.pantry:
    main: struct_light_control;
```

**Home Assistant Entities**:
- `light.pantry_main`

---

### 11. Entrance

**Room ID**: `entrance`  
**Display Name**: "Entrance"

**Lights**:
- `main` - Main entrance light
- `security` - Security/porch light

**CODESYS Structure**:
```iec
rooms.entrance:
    main: struct_light_control;
    security: struct_light_control;
```

**Home Assistant Entities**:
- `light.entrance_main`
- `light.entrance_security`

---

### 12. Guest WC

**Room ID**: `guest_wc`  
**Display Name**: "Guest WC"

**Lights**:
- `main` - Main light
- `night_light` - Night light

**CODESYS Structure**:
```iec
rooms.guest_wc:
    main: struct_light_control;
    night_light: struct_light_control;
```

**Home Assistant Entities**:
- `light.guest_wc_main`
- `light.guest_wc_night_light`

---

### 13. Outdoor Veranda

**Room ID**: `outdoor_veranda`  
**Display Name**: "Outdoor Veranda"

**Lights**:
- `main` - Main veranda light
- `ambient` - Ambient/atmospheric lighting
- `security` - Security lighting

**CODESYS Structure**:
```iec
rooms.outdoor_veranda:
    main: struct_light_control;
    ambient: struct_light_control;
    security: struct_light_control;
```

**Home Assistant Entities**:
- `light.outdoor_veranda_main`
- `light.outdoor_veranda_ambient`
- `light.outdoor_veranda_security`

---

### 14. Outdoor Front

**Room ID**: `outdoor_front`  
**Display Name**: "Outdoor Front"

**Lights**:
- `porch` - Front porch light
- `security` - Security light
- `pathway` - Pathway lighting

**CODESYS Structure**:
```iec
rooms.outdoor_front:
    porch: struct_light_control;
    security: struct_light_control;
    pathway: struct_light_control;
```

**Home Assistant Entities**:
- `light.outdoor_front_porch`
- `light.outdoor_front_security`
- `light.outdoor_front_pathway`

---

### 15. Outdoor Side

**Room ID**: `outdoor_side`  
**Display Name**: "Outdoor Side"

**Lights**:
- `security` - Side security light
- `pathway` - Side pathway lighting

**CODESYS Structure**:
```iec
rooms.outdoor_side:
    security: struct_light_control;
    pathway: struct_light_control;
```

**Home Assistant Entities**:
- `light.outdoor_side_security`
- `light.outdoor_side_pathway`

---

### 16. Outdoor Back

**Room ID**: `outdoor_back`  
**Display Name**: "Outdoor Back"

**Lights**:
- `patio` - Patio/backyard light
- `security` - Back security light
- `garden` - Garden lighting (if applicable)

**CODESYS Structure**:
```iec
rooms.outdoor_back:
    patio: struct_light_control;
    security: struct_light_control;
    garden: struct_light_control;     // Optional
```

**Home Assistant Entities**:
- `light.outdoor_back_patio`
- `light.outdoor_back_security`
- `light.outdoor_back_garden` (if used)

---

## Complete CODESYS Structure Definition

```iec
TYPE struct_light_control :
STRUCT
    // Control Commands
    ha_on: BOOL;          // Home Assistant: Turn ON
    ha_off: BOOL;         // Home Assistant: Turn OFF
    zigbee_toggle: BOOL;  // Zigbee Switch: Toggle (edge detected)
    
    // Status
    state: BOOL;          // Current light state
    relay_status: BOOL;   // Actual relay status (read from EtherCAT)
END_STRUCT
END_TYPE

TYPE struct_room_lights :
STRUCT
    main: struct_light_control;
    secondary: struct_light_control;
    task: struct_light_control;
    ambient: struct_light_control;
    accent: struct_light_control;
    security: struct_light_control;
    // Room-specific lights defined per room
END_STRUCT
END_TYPE

VAR_GLOBAL
    rooms: STRUCT
        master_bedroom: STRUCT
            main: struct_light_control;
            bedside_left: struct_light_control;
            bedside_right: struct_light_control;
            closet: struct_light_control;
            reading: struct_light_control;
            ambient: struct_light_control;
        END_STRUCT;
        
        master_bathroom: STRUCT
            main: struct_light_control;
            mirror: struct_light_control;
            shower: struct_light_control;
            night_light: struct_light_control;
        END_STRUCT;
        
        bedroom_1: STRUCT
            main: struct_light_control;
            bedside: struct_light_control;
            desk: struct_light_control;
            closet: struct_light_control;
        END_STRUCT;
        
        bedroom_2: STRUCT
            main: struct_light_control;
            bedside: struct_light_control;
            desk: struct_light_control;
            closet: struct_light_control;
        END_STRUCT;
        
        bathroom: STRUCT
            main: struct_light_control;
            mirror: struct_light_control;
            night_light: struct_light_control;
        END_STRUCT;
        
        kitchen: STRUCT
            main: struct_light_control;
            under_cabinet: struct_light_control;
            island: struct_light_control;
            pantry: struct_light_control;
            sink: struct_light_control;
        END_STRUCT;
        
        living_room: STRUCT
            main: struct_light_control;
            reading: struct_light_control;
            tv: struct_light_control;
            accent: struct_light_control;
            fireplace: struct_light_control;
        END_STRUCT;
        
        dining_room: STRUCT
            main: struct_light_control;
            ambient: struct_light_control;
            buffet: struct_light_control;
        END_STRUCT;
        
        hallway: STRUCT
            main: struct_light_control;
            secondary: struct_light_control;
            night_light: struct_light_control;
        END_STRUCT;
        
        pantry: STRUCT
            main: struct_light_control;
        END_STRUCT;
        
        entrance: STRUCT
            main: struct_light_control;
            security: struct_light_control;
        END_STRUCT;
        
        guest_wc: STRUCT
            main: struct_light_control;
            night_light: struct_light_control;
        END_STRUCT;
        
        outdoor_veranda: STRUCT
            main: struct_light_control;
            ambient: struct_light_control;
            security: struct_light_control;
        END_STRUCT;
        
        outdoor_front: STRUCT
            porch: struct_light_control;
            security: struct_light_control;
            pathway: struct_light_control;
        END_STRUCT;
        
        outdoor_side: STRUCT
            security: struct_light_control;
            pathway: struct_light_control;
        END_STRUCT;
        
        outdoor_back: STRUCT
            patio: struct_light_control;
            security: struct_light_control;
            garden: struct_light_control;
        END_STRUCT;
    END_STRUCT;
END_VAR
```

---

## Light Function Types Reference

Use these standard function names for consistency:

| Function | Description | Typical Use |
|----------|-------------|-------------|
| `main` | Primary/ceiling light | Main illumination in room |
| `secondary` | Secondary light | Additional main light |
| `bedside_left` | Left bedside lamp | Bedroom bedside |
| `bedside_right` | Right bedside lamp | Bedroom bedside |
| `bedside` | Single bedside lamp | Single bed rooms |
| `closet` | Closet light | Storage areas |
| `desk` | Desk lamp | Study/work areas |
| `reading` | Reading light | Reading areas |
| `mirror` | Mirror/vanity light | Bathrooms |
| `shower` | Shower light | Bathroom shower |
| `night_light` | Night light | Low brightness |
| `under_cabinet` | Under cabinet | Kitchen task lighting |
| `island` | Island pendant | Kitchen island |
| `sink` | Sink area light | Kitchen/bathroom |
| `tv` | TV area lighting | Living room |
| `accent` | Accent lighting | Decorative |
| `ambient` | Ambient lighting | Atmospheric |
| `fireplace` | Fireplace area | Living room |
| `buffet` | Buffet/sideboard | Dining room |
| `porch` | Porch light | Entrance |
| `patio` | Patio light | Backyard |
| `security` | Security light | Outdoor security |
| `pathway` | Pathway lighting | Outdoor paths |
| `garden` | Garden lighting | Outdoor garden |

---

## Water Boiler Control

### Water Boiler Structure

```iec
TYPE struct_water_boiler :
STRUCT
    // Control Commands
    ha_on: BOOL;              // Home Assistant: Turn ON
    ha_off: BOOL;             // Home Assistant: Turn OFF
    schedule_on: BOOL;        // Scheduled ON (from automation)
    schedule_off: BOOL;       // Scheduled OFF (from automation)
    
    // Status
    state: BOOL;              // Current boiler state (ON/OFF)
    relay_status: BOOL;       // Actual relay status
    temperature: REAL;        // Water temperature (if sensor available)
    
    // Safety
    safety_override: BOOL;    // Safety system override (read-only)
    error_state: BOOL;        // Error state flag
    last_error: STRING;       // Last error message
END_STRUCT
END_TYPE

VAR_GLOBAL
    water_boiler: struct_water_boiler;
END_VAR
```

### Water Boiler Function Block

```iec
FUNCTION_BLOCK fb_waterBoiler
VAR_INPUT
    // Control
    ha_on: BOOL;
    ha_off: BOOL;
    schedule_on: BOOL;
    schedule_off: BOOL;
    
    // Sensors
    temperature: REAL;        // Water temperature sensor
    pressure: REAL;           // Water pressure (if available)
    
    // Safety Inputs
    emergency_stop: BOOL;    // Emergency stop button
    flow_sensor: BOOL;       // Water flow sensor
    overtemp_sensor: BOOL;   // Over-temperature sensor
    pressure_sensor: BOOL;   // Pressure sensor (if available)
    
    // Relay Output
    relay_output: BOOL;      // Read actual relay state
END_VAR
VAR_OUTPUT
    relay_control: BOOL;     // Control output to relay
    state: BOOL;              // Current state
    relay_status: BOOL;       // Actual relay status
    safety_override: BOOL;   // Safety override active
    error_state: BOOL;        // Error detected
    error_code: INT;          // Error code
    error_message: STRING;    // Error description
END_VAR
VAR
    // Internal State
    internal_state: BOOL;
    last_state: BOOL;
    
    // Safety Timers
    max_on_time: TIME := T#8H;      // Maximum ON time (8 hours)
    min_off_time: TIME := T#30M;   // Minimum OFF time (30 minutes)
    on_timer: TON;
    off_timer: TON;
    
    // Temperature Limits
    max_temp: REAL := 80.0;         // Maximum temperature (°C)
    min_temp: REAL := 10.0;         // Minimum temperature (°C)
    
    // Safety Flags
    temp_ok: BOOL;
    pressure_ok: BOOL;
    flow_ok: BOOL;
    time_ok: BOOL;
    
    // Edge Detection
    r_trig_ha_on: R_TRIG;
    r_trig_ha_off: R_TRIG;
    r_trig_schedule_on: R_TRIG;
    r_trig_schedule_off: R_TRIG;
    r_trig_emergency: R_TRIG;
END_VAR
```

### Safety Logic Implementation

```iec
// Edge detection
r_trig_ha_on(CLK := ha_on);
r_trig_ha_off(CLK := ha_off);
r_trig_schedule_on(CLK := schedule_on);
r_trig_schedule_off(CLK := schedule_off);
r_trig_emergency(CLK := emergency_stop);

// Safety Checks
temp_ok := (temperature >= min_temp) AND (temperature <= max_temp);
pressure_ok := pressure_sensor;  // Assuming normally closed safety switch
flow_ok := flow_sensor;           // Water flow detected
time_ok := NOT on_timer.Q;        // Not exceeded max ON time

// Safety Override (highest priority)
IF r_trig_emergency.Q OR NOT temp_ok OR NOT pressure_ok THEN
    safety_override := TRUE;
    internal_state := FALSE;
    error_state := TRUE;
    error_code := 1;  // Safety override
    error_message := 'Safety override active';
ELSIF NOT flow_ok AND internal_state THEN
    // No water flow but boiler is on - turn off after delay
    off_timer(IN := TRUE, PT := T#5M);  // 5 minute delay
    IF off_timer.Q THEN
        internal_state := FALSE;
        error_state := TRUE;
        error_code := 2;  // No flow
        error_message := 'No water flow detected';
    END_IF;
ELSIF NOT time_ok THEN
    // Maximum ON time exceeded
    internal_state := FALSE;
    error_state := TRUE;
    error_code := 3;  // Time exceeded
    error_message := 'Maximum ON time exceeded';
ELSE
    safety_override := FALSE;
    error_state := FALSE;
    error_code := 0;
    error_message := '';
END_IF;

// Control Logic (only if safety OK)
IF NOT safety_override THEN
    // Priority: Emergency OFF > Manual OFF > Scheduled OFF > Manual ON > Scheduled ON
    IF r_trig_ha_off.Q OR r_trig_schedule_off.Q THEN
        internal_state := FALSE;
    ELSIF r_trig_ha_on.Q OR r_trig_schedule_on.Q THEN
        IF temp_ok AND flow_ok AND time_ok THEN
            internal_state := TRUE;
            on_timer(IN := internal_state, PT := max_on_time);
        END_IF;
    END_IF;
END_IF;

// Update timers
on_timer(IN := internal_state AND NOT safety_override, PT := max_on_time);
off_timer(IN := NOT internal_state, PT := min_off_time);

// Output Assignment
relay_control := internal_state AND NOT safety_override;
state := internal_state;
relay_status := relay_output;  // Read from actual relay
```

### Safety Measures

#### 1. Temperature Protection
- **Max Temperature**: 80°C (configurable)
- **Min Temperature**: 10°C (freeze protection)
- **Action**: Auto-shutoff if temperature exceeds limits

#### 2. Time-Based Protection
- **Max ON Time**: 8 hours (prevents continuous operation)
- **Min OFF Time**: 30 minutes (prevents rapid cycling)
- **Action**: Force OFF after max time, prevent ON during min OFF time

#### 3. Flow Detection
- **Flow Sensor**: Monitors water flow
- **Action**: Shut off if no flow detected for 5 minutes (dry-run protection)

#### 4. Emergency Stop
- **Emergency Button**: Physical emergency stop
- **Action**: Immediate shutdown, requires manual reset

#### 5. Pressure Protection
- **Pressure Sensor**: Monitors system pressure
- **Action**: Shut off if pressure abnormal

#### 6. State Monitoring
- **Relay Status**: Read actual relay state
- **Action**: Detect relay failures, report status

#### 7. Error Reporting
- **Error Codes**: 
  - 0: No error
  - 1: Safety override
  - 2: No flow
  - 3: Time exceeded
  - 4: Temperature fault
  - 5: Pressure fault
- **Error Messages**: Human-readable descriptions

### Water Boiler Network Variable

```iec
// Sent to Node-RED (Status)
VAR_GLOBAL
    boiler_status: struct_water_boiler;
END_VAR

// Received from Node-RED (Commands)
VAR_GLOBAL
    boiler_commands: STRUCT
        ha_on: BOOL;
        ha_off: BOOL;
        schedule_on: BOOL;
        schedule_off: BOOL;
    END_STRUCT;
END_VAR
```

### Home Assistant Integration

**Entity Type**: `switch` or `water_heater`

```yaml
switch:
  - platform: mqtt
    name: "Water Boiler"
    unique_id: "water_boiler"
    state_topic: "homeassistant/water_boiler/state"
    command_topic: "homeassistant/water_boiler/set"
    state_value_template: "{{ value_json.state }}"
    command_on_template: '{"ha_on":true}'
    command_off_template: '{"ha_off":true}'
    qos: 1
    retain: true

sensor:
  - platform: mqtt
    name: "Water Boiler Temperature"
    state_topic: "homeassistant/water_boiler/state"
    value_template: "{{ value_json.temperature }}"
    unit_of_measurement: "°C"
    
  - platform: mqtt
    name: "Water Boiler Error"
    state_topic: "homeassistant/water_boiler/state"
    value_template: "{{ value_json.error_message }}"
```

---

## Summary

### Light Configuration
- **Total Rooms**: 16 (15 indoor + outdoor areas)
- **Total Lights**: ~60-70 lights (varies by room)
- **Structure**: Hybrid (room-organized in CODESYS, flat in HA)
- **Naming**: `{room}_{function}` format

### Water Boiler
- **Control**: ON/OFF with scheduling
- **Safety**: 7 safety measures implemented
- **Monitoring**: Temperature, flow, pressure, time
- **Error Reporting**: Comprehensive error codes and messages

### Next Steps
1. Review and modify light names per room based on actual installation
2. Map lights to relay outputs
3. Implement new structure in CODESYS
4. Update Node-RED flows
5. Configure Home Assistant entities
6. Test all safety measures for water boiler

---

**Document Status**: Template - Modify with actual light configuration  
**Last Updated**: January 27, 2026