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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

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

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

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

// 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

// 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

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