kkelomatic_home/docs/reference/architecture.md

System Architecture

Overview

The home automation system uses a distributed architecture with multiple components communicating over network protocols.

Component Diagram

┌─────────────────────────────────────────────────────────────┐
│                    Physical Layer                            │
├─────────────────────────────────────────────────────────────┤
│  Zigbee Switches  │  Relays  │  Water Boiler  │  Lights     │
└─────────────────────────────────────────────────────────────┘
                            │
                            │
┌─────────────────────────────────────────────────────────────┐
│                    Control Layer                             │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐      ┌──────────────┐                     │
│  │  CODESYS     │◄────►│  Node-RED    │                     │
│  │  (Raspberry  │      │              │                     │
│  │   Pi)        │      │              │                     │
│  └──────┬───────┘      └──────┬───────┘                     │
│         │                     │                              │
│         │                     │                              │
│  ┌──────▼───────┐      ┌──────▼───────┐                     │
│  │  EtherCAT    │      │   MQTT       │                     │
│  │  IO Card     │      │   Broker     │                     │
│  └──────────────┘      │   (LXC)      │                     │
│                        └──────┬───────┘                     │
│                               │                              │
│                        ┌──────▼───────┐                     │
│                        │ Zigbee2MQTT  │                     │
│                        └──────┬───────┘                     │
│                               │                              │
│                        ┌──────▼───────┐                     │
│                        │ Home         │                     │
│                        │ Assistant    │                     │
│                        └──────────────┘                     │
└─────────────────────────────────────────────────────────────┘

Communication Flow

Light Switch Control Flow

1. User Action: Physical Zigbee switch is pressed
2. Zigbee2MQTT: Receives Zigbee message, converts to MQTT
3. MQTT Broker: Routes message to subscribers
4. Node-RED: Receives MQTT message, processes automation logic
5. CODESYS: Node-RED sends network variable to CODESYS
6. EtherCAT IO: CODESYS activates relay via EtherCAT
7. Physical Device: Relay controls light

Water Boiler Control Flow

1. Trigger: Time-based, sensor-based, or manual trigger
2. Node-RED/Home Assistant: Processes automation logic
3. CODESYS: Receives control command via network variable
4. EtherCAT IO: CODESYS activates relay for boiler
5. Water Boiler: Receives control signal

Protocols Used

• EtherCAT: Industrial communication between CODESYS and IO card
• MQTT: Message queuing for device communication
• Zigbee: Wireless mesh network for switches
• Network Variables: CODESYS to Node-RED communication
• HTTP/REST: Home Assistant API and Node-RED HTTP nodes

Data Flow

Inputs

• Zigbee switch states
• Sensor data (if applicable)
• Time-based triggers
• Manual commands from Home Assistant

Processing

• Node-RED flows for automation logic
• CODESYS control logic
• Home Assistant automations

Outputs

• Relay control signals
• Light states
• Water boiler control
• Dashboard updates

Security Considerations

• MQTT authentication (to be documented)
• Network isolation (to be documented)
• CODESYS access control (to be documented)
• Zigbee network security (to be documented)

Redundancy and Reliability

• Backup procedures
• Failover mechanisms
• Error recovery
• Monitoring and alerting

---

Status: Initial structure - needs detailed information to complete