nearxos/kkelomatic_home
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Home automation docs and CODESYS project

Browse Source 
- Reorganized project: codesys/, docs/codesys|redesign|integration|reference/, scripts/
- CODESYS project and exports in codesys/
- Documentation index in docs/README.md
- Redesign and light naming configuration
- Water boiler control and safety design

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
nearxos
2026-02-07 21:52:46 +02:00
commit bf7bd56fe7
32 changed files with 73698 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
docs/reference/architecture.md Normal file
View File

@@ -0,0 +1,108 @@
# 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

124
docs/reference/hardware.md Normal file
View File

@@ -0,0 +1,124 @@
# Hardware Inventory
## Overview
Complete inventory of physical hardware components in the home automation system.
## Control Hardware
### Raspberry Pi
- **Model**: [To be filled, e.g., Raspberry Pi 4 Model B]
- **RAM**: [To be filled]
- **Storage**: [To be filled]
- **OS**: [To be filled]
- **Purpose**: CODESYS Runtime
- **Location**: [Physical location]
- **Power Supply**: [To be filled]
### Beckhoff EtherCAT IO Card
- **Model**: [To be filled]
- **Part Number**: [To be filled]
- **I/O Channels**: [To be filled]
- **Specifications**: [To be filled]
- **Connection**: [EtherCAT connection details]
### Relay Module
- **Model**: [To be filled]
- **Number of Channels**: [To be filled]
- **Voltage/Current Ratings**: [To be filled]
- **Connection**: [How it connects to EtherCAT card]
## Zigbee Hardware
### Coordinator
- **Model**: [To be filled, e.g., CC2531, CC2652, etc.]
- **Firmware**: [To be filled]
- **Connection**: [USB, Ethernet, etc.]
- **Location**: [Physical location for optimal coverage]
### Zigbee Switches
| Switch # | Model | Location | Functions | Notes |
|----------|-------|----------|------------|-------|
| 1 | [Model] | [Location] | [Functions] | |
| 2 | [Model] | [Location] | [Functions] | |
| ... | | | | |
## Controlled Devices
### Lighting
| Light # | Type | Location | Controlled By | Relay # |
|---------|------|----------|---------------|---------|
| 1 | [Type] | [Location] | [Switch/Relay] | [Relay #] |
| 2 | [Type] | [Location] | [Switch/Relay] | [Relay #] |
| ... | | | | |
### Water Boiler
- **Model**: [To be filled]
- **Type**: [To be filled]
- **Control Interface**: [To be filled]
- **Relay Assignment**: [To be filled]
- **Safety Features**: [To be filled]
## Network Hardware
### Switches
- **Model**: [To be filled]
- **Ports**: [To be filled]
- **Features**: [VLAN support, PoE, etc.]
### Routers/Gateways
- **Model**: [To be filled]
- **Configuration**: [To be filled]
## Host Systems
### LXC Host
- **Hardware**: [To be filled]
- **OS**: [To be filled]
- **Containers**: [List containers]
### Other Hosts
[Document other physical or virtual hosts]
## Wiring
### Power Distribution
[Document power distribution if relevant]
### Low Voltage Wiring
[Document low voltage wiring for relays, sensors, etc.]
### Network Cabling
[Document network cable runs if relevant]
## Physical Layout
[Describe or diagram the physical layout of hardware]
## Spare Parts
- **Spare Components**: [List]
- **Replacement Parts**: [List]
## Maintenance Schedule
- **Regular Maintenance**: [Schedule]
- **Component Lifespan**: [Expected lifespan of components]
---
**Status**: Template - needs hardware details

89
docs/reference/network.md Normal file
View File

@@ -0,0 +1,89 @@
# Network Topology
## Overview
This document describes the network configuration and topology of the home automation system.
## Network Diagram
```
[To be created with actual IP addresses]
```
## IP Address Assignments
| Device/Service | IP Address | MAC Address | Hostname | Notes |
|----------------|------------|-------------|----------|-------|
| Raspberry Pi (CODESYS) | [To be filled] | [To be filled] | [To be filled] | |
| Node-RED Host | [To be filled] | [To be filled] | [To be filled] | |
| MQTT Broker (LXC) | [To be filled] | [To be filled] | [To be filled] | |
| Zigbee2MQTT Host | [To be filled] | [To be filled] | [To be filled] | |
| Home Assistant | [To be filled] | [To be filled] | [To be filled] | |
## Network Segments
### Subnets
- **Main Network**: [Subnet/CIDR]
- **IoT Network**: [If separate VLAN/subnet]
- **Management Network**: [If separate]
### VLANs
[If VLANs are used]
## Port Assignments
| Service | Protocol | Port | Access | Notes |
|---------|----------|------|--------|-------|
| MQTT | TCP | 1883 | Internal | |
| MQTT TLS | TCP | 8883 | Internal | If enabled |
| Node-RED | HTTP | [Port] | [Access] | |
| Home Assistant | HTTP | [Port] | [Access] | |
| CODESYS | [Protocol] | [Port] | [Access] | |
| Zigbee2MQTT | HTTP | [Port] | [Access] | |
## Firewall Rules
[Document firewall rules if applicable]
## DNS
- **Internal DNS**: [If used]
- **Hostname Resolution**: [How devices find each other]
## Routing
[If complex routing is involved]
## Network Services
### DHCP
- **DHCP Server**: [To be filled]
- **Reserved IPs**: [List if static IPs are reserved]
### DNS
- **DNS Servers**: [To be filled]
## Security
- **Network Isolation**: [To be filled]
- **VPN Access**: [If applicable]
- **Remote Access**: [How remote access is configured]
## Troubleshooting
### Network Connectivity
- **Ping Tests**: [How to test connectivity]
- **Port Checks**: [How to verify ports are open]
### Common Issues
- [Issue]: [Solution]
---
**Status**: Template - needs IP addresses and network details

125
docs/reference/quick-reference.md Normal file
View File

@@ -0,0 +1,125 @@
# Quick Reference Guide
## System Overview
- **Control System**: CODESYS on Raspberry Pi
- **Automation**: Node-RED
- **Message Bus**: MQTT (LXC container)
- **Zigbee Bridge**: Zigbee2MQTT
- **Dashboard**: Home Assistant
## Quick Access
### Service URLs
- **Home Assistant**: [To be filled]
- **Node-RED**: [To be filled]
- **Zigbee2MQTT**: [To be filled]
- **MQTT Broker**: [To be filled]
### Important IPs
- **Raspberry Pi (CODESYS)**: [To be filled]
- **MQTT Broker**: [To be filled]
### Important Ports
- **MQTT**: 1883 (or 8883 for TLS)
- **Node-RED**: [To be filled]
- **Home Assistant**: [To be filled]
## Common Tasks
### Restart Services
```bash
# MQTT Broker (LXC)
lxc restart [container-name]
# Node-RED
systemctl restart nodered
# Home Assistant
[Command to restart]
# Zigbee2MQTT
[Command to restart]
```
### Check Service Status
```bash
# MQTT
mosquitto_sub -h [broker-ip] -t '#' -v
# Node-RED
[Command]
# Home Assistant
[Command]
```
### View Logs
- **Node-RED**: [Location]
- **Home Assistant**: [Location]
- **Zigbee2MQTT**: [Location]
- **MQTT**: [Location]
## MQTT Topics
### Key Topics
- `zigbee2mqtt/[device]/set` - Control Zigbee device
- `zigbee2mqtt/[device]` - Device state
- `codesys/[variable]` - CODESYS variables
- `homeassistant/[entity]` - Home Assistant entities
## Device Control
### Control Light via MQTT
```bash
mosquitto_pub -h [broker-ip] -t "zigbee2mqtt/[switch-name]/set" -m '{"state": "ON"}'
```
### Control Relay via CODESYS
[Instructions]
## Troubleshooting Quick Fixes
### Light Not Responding
1. Check Zigbee device status in Zigbee2MQTT
2. Verify MQTT message flow
3. Check Node-RED flow
4. Verify CODESYS network variable
5. Check relay state
### MQTT Connection Issues
1. Verify broker is running
2. Check network connectivity
3. Verify credentials
4. Check firewall rules
### CODESYS Not Communicating
1. Check network variables configuration
2. Verify Node-RED connection
3. Check CODESYS runtime status
## Emergency Procedures
### Manual Override
[How to manually control devices if automation fails]
### System Reset
[Procedure for resetting the system]
---
**Status**: Template - needs actual values and commands

76
docs/reference/setup.md Normal file
View File

@@ -0,0 +1,76 @@
# Setup Guide
## Overview
This guide provides step-by-step instructions for setting up the home automation system from scratch.
## Prerequisites
- [ ] Hardware components assembled
- [ ] Network infrastructure in place
- [ ] Access to all devices
- [ ] Required software licenses (CODESYS)
## Installation Order
1. Network Configuration
2. MQTT Broker Setup
3. CODESYS Installation
4. Node-RED Installation
5. Zigbee2MQTT Setup
6. Home Assistant Installation
7. Integration Configuration
## Step-by-Step Setup
### 1. Network Configuration
[Detailed network setup instructions]
### 2. MQTT Broker (LXC)
[Instructions for setting up MQTT broker in LXC container]
### 3. CODESYS on Raspberry Pi
[Instructions for installing and configuring CODESYS]
### 4. Node-RED
[Instructions for installing and configuring Node-RED]
### 5. Zigbee2MQTT
[Instructions for setting up Zigbee2MQTT]
### 6. Home Assistant
[Instructions for installing and configuring Home Assistant]
### 7. Integration
[Instructions for connecting all components]
## Configuration Files
[Links to or locations of configuration files]
## Verification
### Testing Checklist
- [ ] MQTT broker is accessible
- [ ] CODESYS can communicate with Node-RED
- [ ] Zigbee devices are paired
- [ ] Node-RED flows are working
- [ ] Home Assistant can see all entities
- [ ] Switches control lights correctly
- [ ] Water boiler control works
## Troubleshooting Setup Issues
[Common setup problems and solutions]
---
**Status**: Template - needs detailed setup instructions