kkelomatic_home/docs/redesign/structure-comparison-visual.md

Structure Comparison - Visual Guide

Current Structure (Room-Centric)

CODESYS:
┌─────────────────────────────────────┐
│ masterBedroom: fb_switch            │
│   ├─ l_1 (Light 1)                 │
│   ├─ l_2 (Light 2)                 │
│   ├─ l_3 (Light 3)                 │
│   ├─ l_4 (Light 4)                 │
│   ├─ l_5 (Light 5)                 │
│   └─ l_6 (Light 6)                 │
└─────────────────────────────────────┘

Network Variable:
l_masterBedroom.l_1
l_masterBedroom.l_2
...

Home Assistant:
light.master_bedroom_l1
light.master_bedroom_l2
light.master_bedroom_l3
...

Problems:

• ❌ Generic names (l_1, l_2)
• ❌ Fixed 6 lights per room
• ❌ Wasted space (most rooms don't use all 6)
• ❌ Hard to identify which light is which

---

Option 1: Flat Light-Centric

CODESYS:
┌─────────────────────────────────────┐
│ lights: struct_all_lights           │
│   ├─ kitchen_main                   │
│   ├─ kitchen_under_cabinet          │
│   ├─ master_bedroom_main            │
│   ├─ master_bedroom_bedside_left    │
│   ├─ master_bedroom_bedside_right   │
│   └─ ... (all lights flat)          │
└─────────────────────────────────────┘

Network Variable:
lights.kitchen_main.on
lights.kitchen_main.state
lights.master_bedroom_main.on
...

Home Assistant:
light.kitchen_main
light.kitchen_under_cabinet
light.master_bedroom_main
light.master_bedroom_bedside_left

Benefits:

• ✅ Clear, descriptive names
• ✅ Easy to find lights
• ✅ No wasted space
• ✅ Perfect for HA organization

---

Option 4: Hybrid (Recommended)

CODESYS (Room-organized):
┌─────────────────────────────────────┐
│ rooms: struct_rooms                 │
│   ├─ kitchen                        │
│   │   ├─ main                       │
│   │   ├─ under_cabinet              │
│   │   └─ island                     │
│   ├─ master_bedroom                 │
│   │   ├─ main                       │
│   │   ├─ bedside_left               │
│   │   └─ bedside_right              │
│   └─ ...                            │
└─────────────────────────────────────┘

Network Variable:
rooms.kitchen.main.on
rooms.kitchen.main.state
rooms.master_bedroom.main.on
...

Node-RED (Flattened):
kitchen_main → HA
kitchen_under_cabinet → HA
master_bedroom_main → HA
master_bedroom_bedside_left → HA

Home Assistant:
light.kitchen_main
light.kitchen_under_cabinet
light.master_bedroom_main
light.master_bedroom_bedside_left

Benefits:

• ✅ Organized in CODESYS (by room)
• ✅ Flat in Home Assistant (by light)
• ✅ Descriptive names
• ✅ Easy to add lights
• ✅ Best of both worlds

---

Real-World Example Comparison

Scenario: Kitchen with 3 lights

Current Structure:

kitchen: fb_switch
  l_1 = ??? (which light?)
  l_2 = ??? (which light?)
  l_3 = ??? (which light?)
  l_4 = unused
  l_5 = unused
  l_6 = unused

Hybrid Structure:

rooms.kitchen:
  main = Main ceiling light
  under_cabinet = Under cabinet lights
  island = Island pendant
  (no unused slots)

Home Assistant:

Current:
  light.kitchen_l1  ← What is this?
  light.kitchen_l2  ← What is this?
  light.kitchen_l3  ← What is this?

Hybrid:
  light.kitchen_main           ← Clear!
  light.kitchen_under_cabinet  ← Clear!
  light.kitchen_island         ← Clear!

---

MQTT Topic Comparison

Current

homeassistant/light/master_bedroom_l1/state
homeassistant/light/master_bedroom_l2/state
homeassistant/light/kitchen_l1/state

Problems: Generic, hard to identify

Hybrid

homeassistant/light/kitchen_main/state
homeassistant/light/kitchen_under_cabinet/state
homeassistant/light/master_bedroom_main/state
homeassistant/light/master_bedroom_bedside_left/state

Benefits: Self-documenting, clear purpose

---

Home Assistant Dashboard Comparison

Current

Kitchen
├─ Light 1  ← What is this?
├─ Light 2  ← What is this?
└─ Light 3  ← What is this?

Master Bedroom
├─ Light 1  ← What is this?
├─ Light 2  ← What is this?
└─ Light 3  ← What is this?

Hybrid

Kitchen
├─ Main Light
├─ Under Cabinet
└─ Island

Master Bedroom
├─ Main Light
├─ Bedside Left
└─ Bedside Right

Much clearer!

---

Network Variable Efficiency

Current

• 15 rooms × 6 lights = 90 potential lights
• Most rooms use 2-3 lights
• Waste: ~60 unused light slots
• Network traffic: Sends all 90 values every 50ms

Hybrid

• Only define lights that exist
• Kitchen: 3 lights (not 6)
• Master Bedroom: 3 lights (not 6)
• Efficiency: ~50% less network traffic
• Clarity: Only relevant data

---

Scalability Comparison

Adding a New Light

Current:

1. Find unused l_X slot in room
2. Hope it's available
3. Update documentation
4. Update HA manually

Hybrid:

1. Add new_light: struct_light_control to room
2. Done! Auto-discovered in HA

Adding a New Room

Current:

1. Add new room structure
2. Add all 6 light slots (even if unused)
3. Update network variables
4. Update HA manually

Hybrid:

1. Add room with only needed lights
2. Done! Auto-discovered in HA

---

Implementation Example

Hybrid Structure in CODESYS

TYPE struct_light_control :
STRUCT
    on: BOOL;
    off: BOOL;
    toggle: BOOL;
    state: BOOL;
    relay_status: BOOL;
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;
END_STRUCT
END_TYPE

VAR_GLOBAL
    rooms: STRUCT
        kitchen: STRUCT
            main: struct_light_control;
            under_cabinet: struct_light_control;
            island: struct_light_control;
        END_STRUCT;
        
        master_bedroom: STRUCT
            main: struct_light_control;
            bedside_left: struct_light_control;
            bedside_right: struct_light_control;
        END_STRUCT;
        
        // ... other rooms
    END_STRUCT;
END_VAR

Node-RED Transformation

// Transform room-based to flat structure for HA
function transformToHA(msg) {
    const rooms = msg.payload.rooms;
    const result = {};
    
    for (const [roomName, roomLights] of Object.entries(rooms)) {
        for (const [lightName, lightControl] of Object.entries(roomLights)) {
            const lightId = `${roomName}_${lightName}`;
            result[lightId] = {
                on: lightControl.on,
                off: lightControl.off,
                state: lightControl.state,
                status: lightControl.relay_status
            };
        }
    }
    
    return { payload: result };
}

Home Assistant Auto-Discovery

# Node-RED publishes this automatically
homeassistant/light/kitchen_main/config:
  name: "Kitchen Main"
  unique_id: "kitchen_main"
  state_topic: "homeassistant/light/kitchen_main/state"
  command_topic: "homeassistant/light/kitchen_main/set"
  state_value_template: "{{ value_json.state }}"
  command_on_template: '{"on":true}'
  command_off_template: '{"off":true}'

---

Recommendation Summary

Use Hybrid Structure (Option 4) because:

1. ✅ Best Organization: Room-based in CODESYS, flat in HA
2. ✅ Clear Naming: kitchen_main vs l_1
3. ✅ Efficiency: Only define existing lights
4. ✅ Scalability: Easy to add lights/rooms
5. ✅ Maintainability: Self-documenting structure
6. ✅ HA Integration: Perfect for Home Assistant
7. ✅ Future-Proof: Easy to extend

Key Changes:

• Replace l_1, l_2 with descriptive names
• Use function-based naming: main, secondary, task, etc.
• Flatten structure in Node-RED for HA
• Only define lights that exist
• Add metadata for better organization

---

See: Full Structure Redesign Analysis for complete details.